NuttX USB Device Trace

USB Device Tracing Controls. The NuttX USB device subsystem supports a fairly sophisticated tracing facility. The basic trace cabability is controlled by these NuttX configuration settings:

• CONFIG_USBDEV_TRACE: Enables USB tracing
• CONFIG_USBDEV_TRACE_NRECORDS: Number of trace entries to remember

Trace IDs. The trace facility works like this: When enabled, USB events that occur in either the USB device driver or in the USB class driver are logged. These events are described in include/nuttx/usb/usbdev_trace.h. The logged events are identified by a set of event IDs:

TRACE_INIT_ID	Initialization events
TRACE_EP_ID	Endpoint API calls
TRACE_DEV_ID	USB device API calls
TRACE_CLASS_ID	USB class driver API calls
TRACE_CLASSAPI_ID	Other class driver system API calls
TRACE_CLASSSTATE_ID	Track class driver state changes
TRACE_INTENTRY_ID	Interrupt handler entry
TRACE_INTDECODE_ID	Decoded interrupt event
TRACE_INTEXIT_ID	Interrupt handler exit
TRACE_OUTREQQUEUED_ID	Request queued for OUT endpoint
TRACE_INREQQUEUED_ID	Request queued for IN endpoint
TRACE_READ_ID	Read (OUT) action
TRACE_WRITE_ID	Write (IN) action
TRACE_COMPLETE_ID	Request completed
TRACE_DEVERROR_ID	USB controller driver error event
TRACE_CLSERROR_ID	USB class driver error event

Logged Events. Each logged event is 32-bits in size and includes

1. 8-bits of the trace ID (values associated with the above)
2. 8-bits of additional trace ID data, and
3. 16-bits of additonal data.

8-bit Trace Data The 8-bit trace data depends on the specific event ID. As examples,

• For the USB serial and mass storage class, the 8-bit event data is provided in include/nuttx/usb/usbdev_trace.h.
• For the USB device driver, that 8-bit event data is provided within the USB device driver itself. So, for example, the 8-bit event data for the LPC1768 USB device driver is found in arch/arm/src/lpc17xx/lpc17_usbdev.c.

16-bit Trace Data. The 16-bit trace data provided additional context data relevant to the specific logged event.

Trace Control Interfaces. Logging of each of these kinds events can be enabled or disabled using the interfaces described in include/nuttx/usb/usbdev_trace.h.

Enabling USB Device Tracing. USB device tracing will be configured if CONFIG_USBDEV and either of the following are set in the NuttX configuration file:

• CONFIG_USBDEV_TRACE, or
• CONFIG_DEBUG and CONFIG_DEBUG_USB

Log Data Sink. The logged data itself may go to either (1) an internal circular buffer, or (2) may be provided on the console. If CONFIG_USBDEV_TRACE is defined, then the trace data will go to the circular buffer. The size of the circular buffer is determined by CONFIG_USBDEV_TRACE_NRECORDS. Otherwise, the trace data goes to console.

Example. Here is an example of USB trace output using apps/examples/usbserial for an LPC1768 platform with the following NuttX configuration settings:

• CONFIG_DEBUG, CONFIG_DEBUG_VERBOSE, CONFIG_USB
• CONFIG_EXAMPLES_USBSERIAL_TRACEINIT, CONFIG_EXAMPLES_USBSERIAL_TRACECLASS, CONFIG_EXAMPLES_USBSERIAL_TRACETRANSFERS, CONFIG_EXAMPLES_USBSERIAL_TRACECONTROLLER, CONFIG_EXAMPLES_USBSERIAL_TRACEINTERRUPTS

Console Output:

	ABDE
	usbserial_main: Registering USB serial driver
	uart_register: Registering /dev/ttyUSB0
	usbserial_main: Successfully registered the serial driver
1	Class API call 1: 0000
2	Class error: 19:0000
	usbserial_main: ERROR: Failed to open /dev/ttyUSB0 for reading: 107
	usbserial_main: Not connected. Wait and try again.
3	Interrupt 1 entry: 0039
4	Interrupt decode 7: 0019
5	Interrupt decode 32: 0019
6	Interrupt decode 6: 0019
7	Class disconnect(): 0000
8	Device pullup(): 0001
9	Interrupt 1 exit: 0000

The numbered items are USB USB trace output. You can look in the file drivers/usbdev/usbdev_trprintf.c to see examctly how each output line is formatted. Here is how each line should be interpreted:

	USB EVENT ID	8-bit EVENT DATA	MEANING	16-bit EVENT DATA
1	TRACE_CLASSAPI_ID1	1	USBSER_TRACECLASSAPI_SETUP1	0000
2	TRACE_CLSERROR_ID1	19	USBSER_TRACEERR_SETUPNOTCONNECTED1	0000
3	TRACE_INTENTRY_ID1	1	LPC17_TRACEINTID_USB2	0039
4	TRACE_INTDECODE_ID2	7	LPC17_TRACEINTID_DEVSTAT2	0019
5	TRACE_INTDECODE_ID2	32	LPC17_TRACEINTID_SUSPENDCHG2	0019
6	TRACE_INTDECODE_ID2	6	LPC17_TRACEINTID_DEVRESET2	0019
7	TRACE_CLASS_ID1	3	(See TRACE_CLASSDISCONNECT1)	0000
8	TRACE_DEV_ID1	6	(See TRACE_DEVPULLUP1)	0001
9	TRACE_INTEXIT_ID1	1	LPC17_TRACEINTID_USB2	0000

NOTES:
¹See include/nuttx/usb/usbdev_trace.h
²See arch/arm/src/lpc17xx/lpc17_usbdev.c

In the above example you can see that:

• 1. The serial class USB setup method was called for the USB serial class. This is the corresponds to the following logic in drivers/usbdev/pl2303.c:

  static int pl2303_setup(FAR struct uart_dev_s *dev)
  {
    ...
    usbtrace(PL2303_CLASSAPI_SETUP, 0);
    ...
  

• 2. An error occurred while processing the setup command because no configuration has yet been selected by the host. This corresponds to the following logic in drivers/usbdev/pl2303.c:

  static int pl2303_setup(FAR struct uart_dev_s *dev)
  {
    ...
    /* Check if we have been configured */
  
    if (priv->config == PL2303_CONFIGIDNONE)
      {
        usbtrace(TRACE_CLSERROR(USBSER_TRACEERR_SETUPNOTCONNECTED), 0);
        return -ENOTCONN;
      }
    ...
  

• 3-6. Here is a USB interrupt that suspends and resets the device.
• 7-8. During the interrupt processing the serial class is disconnected
• 9. And the interrupt returns