- Generated by
1.9.8
|
tinyCLUNX33
System on Module with CrosslinkU-NX
|
This app note presents the layers involved in the tinyCLUNX33 USB Video, and how debugging can happen at every level.
Going through each step is not mandatory but only informative, and reaching tinyVision.ai on the chat server or by email is more than welcome.
Furthermore, help can also be found on the Zephyr Project chat server about how Zephyr works in general, as well as on the Zephyr documentation.
The Zephyr debug resources would cover this topic more in depth, however here is some extension to it:
Here is how the build system is layered:
Chaining multiple layers of configuration is very frequent while building. For instance, the C preprocessor reads C, turned into preprocessed C, turned into intermediate representation, turned into assembly, turned into objects, turned into a binary. The same happens above the C level to avoid solving all the problems in one place.
This means that the C errors related to the configuratoin system are the most challenging to debug.
To help with that, it is possible to verify that the files generated at each layer are still looking as expected:
The devicetree used is at build/zephyr/zephyr.dts.
status = "okay" for each peripheral of interest? If not, this can be enabled in the app.overlay of the application.--board with tinyclunx33, /soc and @rev as expected). A complete "clean" build is sometimes necessary when updating the app.overlay or devicetree.The Kconfig used is at build/zephyr/.config.
CONFIG_DT_HAS_... for the problematic driver? If not, this means there is a missing devicetree entry, and checking the zephyr.dts again could help.CONFIG_... option disabled while it was expected to be enabled? Checking if it can is set in prj.conf can help, or otherwise look at the warning during the build time, often explaining what went wrong and why.The CMake system uses the various CMakeLists.txt directly. The way a driver is used
Errors involving macros like DT_... are related to the devicetree. The C macros genreated by the devicetree and used by all the drivers are at build/zephyr/include/generated/zephyr/devicetree_generated.h.
The lowest level available to debug the most tedious C macro errors is to search for the names that the C preprocessor cannot find or build, and see if there is the expected name generated on this file. If not, this suggests that either the C macros are not doing what is expected (i.e. working on a new driver), or that there is a Kconfig or Devicetree issue.
This file also contains the reference between the device numbers and the device name, whch help for errors such as undefined reference to __device_dts_ord_123.
First of all, a bad USB cable is a frequent source of failure, and testing different cables, or testing the same cable with different devices is recommended.
The USB ports of the host can also have differences in how it is handled. For instance, USB 3 ports that are 20 Gbit/s capable and those only 5 Gbit/s capable can behave slightly differently. Also, damage or misconfiguration of a particular port can also happen on the host side, and testing a different port can sometimes reveal useful.
If several modules and devkits are provided, Testing a different one can also reveal a problem specific to one particular device rather than a firmware or gateware issue.
Testing with or without the presence of an intermediate USB HUB, as well as different types of USB HUBs can also give slightly different results in presence of some bug.
The order in which the DATA and DEBUG USB connectors of the devkit are connected can also affect the power sequence, and in presence of some other bug, permit to show a different behavior. The actual port to which each interface is also connected can also play a role: In case of problem, connecting both ports to the same hub/device can be more useful.
When additional hardware gets connected to the devkit, this can lead to additional current being pulled by the USB device, up to being too much for what an USB port can supply. In which case, disconnecting every external device from the devkit (i.e. the adapter boards) can reveal useful.
An USB Video device is fundamentally an USB device: once it is connected to the host, the host queries its USB descriptors, arrays of bytes encoding the functions of the device. According to these, the host selects an appropriate driver for this device. This is the USB enumeration.
To tell if the enumeration did succeed, the lsusb command (Linux), ioreg -p IOUSB command (Mac OSX), or USB Device Tree Viewer (Windows) should show an entry for the tinyCLUNX33, named "tinyVision.ai tinyCLUNX33" by default.
In all case, upon error preventing the device to be detected, the host-side system logs and Zephyr-side logs will contain precious information about what happened.
If the enumeration does not work on Linux, this suggests that a low-level issue happened. The dmesg -w logs from the host as well as the UART logs from the tinyCLUNX33 would be what to aim for to understand what is going wrong. It is possible to increase the log verbosity of the USB driver by setting CONFIG_UDC_DRIVER_LOG_LEVEL_INF=y in prj.conf and rebuilding.
If the enumeration works on Linux, but not on Windows, this could be a low-level issue as above, or possibly a problem in the USB descriptors that are not specific to video, but globally describing the device. In which case, the USB3CV can be used to test if the device is detected using this method.
If the USB device works but the video device does not appear in the list of video devices (i.e. /dev/video2 on Linux, or the list of webcams in online video conferences systems), this means that the enumeration did succeed, but some descriptor was not considered valid. Debugging the descriptors content itself could be needed.
If the following error message appears through the logs, then this means that the number of USB endpoints configured at build time to provide enough for every USB class.
This can be configured on the devicetree for the USB driver (USB Device Controller, UDC):
A few examples:
If the USB descriptors are valid and correctly transmitted during enumeration, then a system video interface should appear. Even if there is any problem with the video transfer. If nothing appears, then something went wrong with the enumeration or descriptors content.
One method to verify that the descriptors are correct is to use the official USB3CV validator tool from the USB-IF, which will build a report of all USB descriptors that are incorrect. Except some rare exceptions, if the USB3CV tool suite does not report any bug, the descriptors are should be accepted by the host.
This means that all the USB descriptor foes can be caught by this (Windows-only) tool. However, insightful error messages can also be presented by lsusb -v or USB Device Tree Viewer that would not be described in the USB3CV tool.
The tinyCLUNX33 SDK uses the 1209:0001 vendorID/productID combo from pid.codes (for a production device, a vendorID/productID registered at USB-IF must be obtained, or pid.codes for open hardware projects), so the command to list the detailed descriptors would be for both Linux and Mac OSX: lsusb -v -d 1209:0001.
On the tinyCLUNX33, the USB descriptors are defined by the USB Video Class implementation part of Zephyr (subsys/usb/device_next/class/usbd_uvc.c). Some part is constant, and some part is dynamically generated based on informations contained withing the video driver, such as the IMX219 image sensor driver, or custom driver you are developing. This means that if the USB descriptors content are wrong, it can be due to data coming from the video driver (i.e. empty list of formats) or be a bug in the USB Video Class (i.e. wrong order for a list).
For any kind of error, enabling the verbose logs for the Linux uvcvideo driver gives better insights of what is going on under the hood. To enable them:
This is expected to show a few lines for video frame received, such as this:
The working of the uvcvideo Linux driver is that any frame shorter than the expected wMaxVideoFrameSize is dropped. In order to troubleshoot, it might be useful to force the frames out and inspect them to understand what goes wrong. To do so, reload the uvcvideo driver with the nodrop=1 flag:
Once the video interface is present, it becomes possible to start the video feed from the host, i.e. using a simple video player like ffplay /dev/video2. If the player does not open, this could mean that the stream negotiation that happens before starting the transfer failed. Error messages will be present on dmesg and the device UART logs.
The negotiation will involve communication with the video driver. This requires the driver to work consistently: tuning up the video log level could help: CONFIG_VIDEO_LOG_LEVEL_DBG=y.
If a window opens-up with a video feed, but it is dark, it is possible that the exposure level of your image sensor is left to the default minimum setup. Pointing a torchlight at the image sensor permits to verify this.
The Zephyr shell available on the debug UART interface or as an extra USB-serial console (depending on configuration) will allow to run extra. Tab completion is available, which helps with avoiding typos while entering the device names.
One command that always help screening whereabout an error might be is device list, giving the return status for the init() function of every driver:
If anything other than READY is shown, then the return code of init() was not 0, which can be investigated directly on the driver C source file of the relevant driver.
If the stream appears to be stuck and there is no I/O, then it is possible that the UVC Manager input feed is stuck. To verify this, get the address of the FIFO, and manually read bytes from it with for instance the devmem Zephyr command:
The UVC Manager shows early debug information about the input video stream as well as other low-level information. By looking at the STREAM ADDRESS field, the location of the data pipe can be obtained, and read from the shell to test if data comes out of it:
The serial console speed can be improved by reducing the USB driver log verbosity. If data does not come out of it, this suggests that no data was provided into the feed.
In order to review the current state of the transfer, the dwc3 command can be used for debugging Lattice USB23, as it uses a compatible API. To review the list of buffers scheduled for transfer:
Looking at the output of lsusb -vd 1209:0001 | grep -C10 bEndpointAddress would give a summary of every endpoint address, useful to know which endpoint is used for the video transfers.
Then, inspecting the state of the video transfers can be done as such:
0xb1000140 is the address where this list of buffers is encoded.ep=0x83 confirms us that it is the endpoint 0x83.addr=0x00000000b1200040 is the address of the stram to transfer, on which the devmem command from earlier can be used.ctl=1 indicates that this is a BULK transfer. There are 3 BULK transfers in this case.ctl=8 indicates that the list of buffers wraps over to the address specified by addr=, in a ring buffer looping over continuously.hwo=1 (HardWare Owned) means that the transfers are submitted to the buffer,chn=1 (CHaiN) means that the buffers are all connected together into a single transfer (does not apply to ctl=8).bufsiz=2048 indicate that the buffers did not start to be transferred at all as they are still complete with their original size 2048 (does not apply to ctl=8). 1.9.8