123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453 |
- <html>
- <head>
- <title>NuttX USB Trace Capability</title>
- <link rel="stylesheet" href="style.css">
- </head>
- <body background="backgd.gif">
- <hr><hr>
- <table width ="100%">
- <tr align="center" bgcolor="#e4e4e4">
- <td>
- <h1><big><font color="#3c34ec"><i>NuttX USB Device Trace</i></font></big></h1>
- <p>Last Updated: March 20, 2011</p>
- </td>
- </tr>
- </table>
- <hr><hr>
- <p><b>USB Device Tracing Controls</b>.
- The NuttX USB device subsystem supports a fairly sophisticated tracing facility.
- The basic trace cabability is controlled by these NuttX configuration settings:
- </p>
- <ul>
- <li><code>CONFIG_USBDEV_TRACE</code>: Enables USB tracing</li>
- <li><code>CONFIG_USBDEV_TRACE_NRECORDS</code>: Number of trace entries to remember</li>
- </ul>
- <p><b>Trace IDs</b>.
- 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 <code>include/nuttx/usb/usbdev_trace.h</code>.
- The logged events are identified by a set of event IDs:
- </p>
- <ul><table>
- <tr>
- <td><code>TRACE_INIT_ID</code></td>
- <td>Initialization events</td>
- </tr>
- <tr>
- <td><code>TRACE_EP_ID</code></td>
- <td>Endpoint API calls</td>
- </tr>
- <tr>
- <td><code>TRACE_DEV_ID</code></td>
- <td>USB device API calls</td>
- </tr>
- <tr>
- <td><code>TRACE_CLASS_ID</code></td>
- <td>USB class driver API calls</td>
- </tr>
- <tr>
- <td><code>TRACE_CLASSAPI_ID</code></td>
- <td>Other class driver system API calls</td>
- </tr>
- <tr>
- <td><code>TRACE_CLASSSTATE_ID</code></td>
- <td>Track class driver state changes</td>
- </tr>
- <tr>
- <td><code>TRACE_INTENTRY_ID</code></td>
- <td>Interrupt handler entry</td>
- </tr>
- <tr>
- <td><code>TRACE_INTDECODE_ID</code></td>
- <td>Decoded interrupt event</td>
- </tr>
- <tr>
- <td><code>TRACE_INTEXIT_ID</code></td>
- <td>Interrupt handler exit</td>
- </tr>
- <tr>
- <td><code>TRACE_OUTREQQUEUED_ID</code></td>
- <td>Request queued for OUT endpoint</td>
- </tr>
- <tr>
- <td><code>TRACE_INREQQUEUED_ID</code></td>
- <td>Request queued for IN endpoint</td>
- </tr>
- <tr>
- <td><code>TRACE_READ_ID</code></td>
- <td>Read (OUT) action</td>
- </tr>
- <tr>
- <td><code>TRACE_WRITE_ID</code></td>
- <td>Write (IN) action</td>
- </tr>
- <tr>
- <td><code>TRACE_COMPLETE_ID</code></td>
- <td>Request completed</td>
- </tr>
- <tr>
- <td><code>TRACE_DEVERROR_ID</code></td>
- <td>USB controller driver error event</td>
- </tr>
- <tr>
- <td><code>TRACE_CLSERROR_ID</code></td>
- <td>USB class driver error event</td>
- </tr>
- </table></ul>
- <p><b>Logged Events</b>.
- Each logged event is 32-bits in size and includes
- </p>
- <ol>
- <li>8-bits of the trace ID (values associated with the above)</li>
- <li>8-bits of additional trace ID data, and</li>
- <li>16-bits of additional data.</li>
- </ol>
- <p><b>8-bit Trace Data</b>
- The 8-bit trace data depends on the specific event ID. As examples,
- </p>
- <ul>
- <li>
- For the USB serial and mass storage class, the 8-bit event data is provided in <code>include/nuttx/usb/usbdev_trace.h</code>.
- </li>
- <li>
- 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 <code>arch/arm/src/lpc17xx_40xx/lpc17_40_usbdev.c</code>.
- </li>
- </ul>
- <p><b>16-bit Trace Data</b>.
- The 16-bit trace data provided additional context data relevant to the specific logged event.
- </p>
- <p><b>Trace Control Interfaces</b>.
- Logging of each of these kinds events can be enabled or disabled using the interfaces described in <code>include/nuttx/usb/usbdev_trace.h</code>.
- </p>
- <p><b>Enabling USB Device Tracing</b>.
- USB device tracing will be configured if <code>CONFIG_USBDEV</code> and either of the following are set in the NuttX configuration file:
- </p>
- <ul>
- <li><code>CONFIG_USBDEV_TRACE</code>, or</li>
- <li><code>CONFIG_DEBUG_FEATURES and CONFIG_DEBUG_USB</code></li>
- </ul>
- <p><b>Log Data Sink</b>.
- The logged data itself may go to either (1) an internal circular buffer, or (2) may be provided on the console.
- If <code>CONFIG_USBDEV_TRACE</code> is defined, then the trace data will go to the circular buffer.
- The size of the circular buffer is determined by <code>CONFIG_USBDEV_TRACE_NRECORDS</code>.
- Otherwise, the trace data goes to console.
- <p>
- <p><b>Example</b>.
- Here is an example of USB trace output using <code>apps/examples/usbserial</code> for an LPC1768 platform with the following NuttX configuration settings:
- </p>
- <ul>
- <li><code>CONFIG_DEBUG_FEATURES</code>, <code>CONFIG_DEBUG_INFO</code>, <code>CONFIG_USB</code>
- <li><code>CONFIG_EXAMPLES_USBSERIAL_TRACEINIT</code>, <code>CONFIG_EXAMPLES_USBSERIAL_TRACECLASS</code>,
- <code>CONFIG_EXAMPLES_USBSERIAL_TRACETRANSFERS</code>, <code>CONFIG_EXAMPLES_USBSERIAL_TRACECONTROLLER</code>,
- <code>CONFIG_EXAMPLES_USBSERIAL_TRACEINTERRUPTS</code>
- </ul>
- <p>Console Output:</p>
- <ul><table>
- <tr>
- <td align="center"> </td>
- <td align="left"><code>ABDE</code></td>
- </tr>
- <tr>
- <td align="center"> </td>
- <td align="left"><code>usbserial_main: Registering USB serial driver</code></td>
- </tr>
- <tr>
- <td align="center"> </td>
- <td align="left"><code>uart_register: Registering /dev/ttyUSB0</code></td>
- </tr>
- <tr>
- <td align="center"> </td>
- <td align="left"><code>usbserial_main: Successfully registered the serial driver</code></td>
- </tr>
- <tr>
- <td align="center">1</td>
- <td align="left"><code>Class API call 1: 0000</code></td>
- </tr>
- <tr>
- <td align="center">2</td>
- <td align="left"><code>Class error: 19:0000</code></td>
- </tr>
- <tr>
- <td align="center"> </td>
- <td align="left"><code>usbserial_main: ERROR: Failed to open /dev/ttyUSB0 for reading: 107</code></td>
- </tr>
- <tr>
- <td align="center"> </td>
- <td align="left"><code>usbserial_main: Not connected. Wait and try again.</code></td>
- </tr>
- <tr>
- <td align="center">3</td>
- <td align="left"><code>Interrupt 1 entry: 0039</code></td>
- </tr>
- <tr>
- <td align="center">4</td>
- <td align="left"><code>Interrupt decode 7: 0019</code></td>
- </tr>
- <tr>
- <td align="center">5</td>
- <td align="left"><code>Interrupt decode 32: 0019</code></td>
- </tr>
- <tr>
- <td align="center">6</td>
- <td align="left"><code>Interrupt decode 6: 0019</code></td>
- </tr>
- <tr>
- <td align="center">7</td>
- <td align="left"><code>Class disconnect(): 0000</code></td>
- </tr>
- <tr>
- <td align="center">8</td>
- <td align="left"><code>Device pullup(): 0001</code></td>
- </tr>
- <tr>
- <td align="center">9</td>
- <td align="left"><code>Interrupt 1 exit: 0000</code></td>
- </tr>
- </table></ul>
- <p>
- The numbered items are USB USB trace output.
- You can look in the file <code>drivers/usbdev/usbdev_trprintf.c</code> to see examctly how each output line is formatted.
- Here is how each line should be interpreted:
- </p>
- <ul><table>
- <tr>
- <th align="center"> </th>
- <td align="left">USB EVENT ID</td>
- <td align="right">8-bit<br>EVENT<br>DATA</td>
- <td align="left">MEANING</td>
- <td align="left">16-bit<br>EVENT<br>DATA</td>
- </tr>
- <tr>
- <td align="center">1</td>
- <td align="left"><code>TRACE_CLASSAPI_ID</code><sup>1</sup></td>
- <td align="right">1</td>
- <td align="left"><code>USBSER_TRACECLASSAPI_SETUP</code><sup>1</sup></td>
- <td align="left">0000</td>
- </tr>
- <tr>
- <td align="center">2</td>
- <td align="left"><code>TRACE_CLSERROR_ID</code><sup>1</sup></td>
- <td align="right">19</td>
- <td align="left"><code>USBSER_TRACEERR_SETUPNOTCONNECTED</code><sup>1</sup></td>
- <td align="left">0000</td>
- </tr>
- <tr>
- <td align="center">3</td>
- <td align="left"><code>TRACE_INTENTRY_ID</code><sup>1</sup></td>
- <td align="right">1</td>
- <td align="left"><code>LPC17_40_TRACEINTID_USB</code><sup>2</sup></td>
- <td align="left">0039</td>
- </tr>
- <tr>
- <td align="center">4</td>
- <td align="left"><code>TRACE_INTDECODE_ID</code><sup>2</sup></td>
- <td align="right">7</td>
- <td align="left"><code>LPC17_40_TRACEINTID_DEVSTAT</code><sup>2</sup></td>
- <td align="left">0019</td>
- </tr>
- <tr>
- <td align="center">5</td>
- <td align="left"><code>TRACE_INTDECODE_ID</code><sup>2</sup></td>
- <td align="right">32</td>
- <td align="left"><code>LPC17_40_TRACEINTID_SUSPENDCHG</code><sup>2</sup></td>
- <td align="left">0019</td>
- </tr>
- <tr>
- <td align="center">6</td>
- <td align="left"><code>TRACE_INTDECODE_ID</code><sup>2</sup></td>
- <td align="right">6</td>
- <td align="left"><code>LPC17_40_TRACEINTID_DEVRESET</code><sup>2</sup></td>
- <td align="left">0019</td>
- </tr>
- <tr>
- <td align="center">7</td>
- <td align="left"><code>TRACE_CLASS_ID</code><sup>1</sup></td>
- <td align="right">3</td>
- <td align="left"><code>(See TRACE_CLASSDISCONNECT</code><sup>1</sup>)</td>
- <td align="left">0000</td>
- </tr>
- <tr>
- <td align="center">8</td>
- <td align="left"><code>TRACE_DEV_ID</code><sup>1</sup></td>
- <td align="right">6</td>
- <td align="left"><code>(See TRACE_DEVPULLUP</code><sup>1</sup>)</td>
- <td align="left">0001</td>
- </tr>
- <tr>
- <td align="center">9</td>
- <td align="left"><code>TRACE_INTEXIT_ID</code><sup>1</sup></td>
- <td align="right">1</td>
- <td align="left"><code>LPC17_40_TRACEINTID_USB</code><sup>2</sup></td>
- <td align="left">0000</td>
- </tr>
- </table>
- <p><small><b>NOTES</b>:<br>
- <sup>1</sup>See <code>include/nuttx/usb/usbdev_trace.h</code><br>
- <sup>2</sup><code>See arch/arm/src/lpc17xx_40xx/lpc17_40_usbdev.c</code>
- </small></p>
- </ul>
- <p>
- In the above example you can see that:
- </p>
- <ul>
- <li><b>1</b>.
- The serial class USB setup method was called for the USB serial class.
- This is the corresponds to the following logic in <code>drivers/usbdev/pl2303.c</code>:
- <ul><pre>
- static int pl2303_setup(FAR struct uart_dev_s *dev)
- {
- ...
- usbtrace(PL2303_CLASSAPI_SETUP, 0);
- ...
- </pre></ul>
- </li>
- <li><b>2</b>.
- 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 <code>drivers/usbdev/pl2303.c</code>:
- <ul><pre>
- 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;
- }
- ...
- </pre></ul>
- <li><b>3-6</b>.
- Here is a USB interrupt that suspends and resets the device.
- </li>
- <li><b>7-8</b>.
- During the interrupt processing the serial class is disconnected
- </li>
- <li><b>9</b>.
- And the interrupt returns
- </li>
- </ul>
- <p><b>USB Monitor</b>.
- The <i>USB monitor</i> is an application in the <code>apps/system/usbmonitor</code> that provides a convenient way to get debug trace output.
- If tracing is enabled, the USB device will save encoded trace output in in-memory buffer;
- if the USB monitor is also enabled, that trace buffer will be periodically emptied and dumped to the
- system logging device (the serial console in most configurations).
- The following are some of the relevant configuration options:
- </p>
- <ul>
- <table width="100%">
- <tr>
- <td colspan="2" align="left" valign="top" bgcolor="#e4e4e4">
- <i>Device Drivers -> USB Device Driver Support</i>
- </td>
- </tr>
- <tr>
- <td width="30%" align="left" valign="top">
- <code>CONFIG_USBDEV_TRACE=y</code>
- </td>
- <td align="left" valign="top">
- Enable USB trace feature
- </td>
- </tr>
- <tr>
- <td width="30%" align="left" valign="top">
- <code>CONFIG_USBDEV_TRACE_NRECORDS=<i>nnnn</i></code>
- </td>
- <td align="left" valign="top">
- Buffer <i>nnnn</i> records in memory.
- If you lose trace data, then you will need to increase the size of this buffer
- (or increase the rate at which the trace buffer is emptied).
- </td>
- </tr>
- <td width="30%" align="left" valign="top">
- <code>CONFIG_USBDEV_TRACE_STRINGS=y</code>
- </td>
- <td align="left" valign="top">
- Optionally, convert trace ID numbers to strings.
- This feature may not be supported by all drivers.
- </td>
- <tr>
- <td colspan="2" align="left" valign="top" bgcolor="#e4e4e4">
- <i>Application Configuration -> NSH LIbrary</i>
- </td>
- </tr>
- <tr>
- <td width="30%" align="left" valign="top">
- <code>CONFIG_NSH_USBDEV_TRACE=n</code>
- </td>
- <td align="left" valign="top">
- Make sure that any built-in tracing from NSH is disabled.
- </td>
- </tr>
- <tr>
- <td width="30%" align="left" valign="top">
- <code>CONFIG_NSH_ARCHINIT=y</code>
- </td>
- <td align="left" valign="top">
- Enable this option <i>only</i> if your board-specific logic has logic to automatically start the USB monitor.
- Otherwise the USB monitor can be started or stopped with the <code>usbmon_start</code> and <code>usbmon_stop</code> commands from the NSH console.
- </td>
- </tr>
- <tr>
- <td colspan="2" align="left" valign="top" bgcolor="#e4e4e4">
- <i>Application Configuration -> System NSH Add-Ons</i>
- </td>
- </tr>
- <tr>
- <td width="30%" align="left" valign="top">
- <code>CONFIG_USBMONITOR=y</code>
- </td>
- <td align="left" valign="top">
- Enable the USB monitor daemon
- </td>
- </tr>
- <tr>
- <td width="30%" align="left" valign="top">
- <code>CONFIG_USBMONITOR_STACKSIZE=<i>nnnn</i></code>
- </td>
- <td align="left" valign="top">
- Sets the USB monitor daemon stack size to <i>nnnn</i>.
- The default is 2KiB.
- </td>
- </tr>
- <tr>
- <td width="30%" align="left" valign="top">
- <code>CONFIG_USBMONITOR_PRIORITY=50</code>
- </td>
- <td align="left" valign="top">
- Sets the USB monitor daemon priority to <i>nnnn</i>.
- This priority should be low so that it does not interfere with other operations, but not so low that you cannot dump the buffered USB data sufficiently rapidly.
- The default is 50.
- </td>
- </tr>
- <tr>
- <td width="30%" align="left" valign="top">
- <code>CONFIG_USBMONITOR_INTERVAL=<i>nnnn</i></code>
- </td>
- <td align="left" valign="top">
- Dump the buffered USB data every <i>nnnn</i> seconds.
- If you lose buffered USB trace data, then dropping this value will help by increasing the rate at which the USB trace buffer is emptied.
- </td>
- </tr>
- <tr>
- <td width="30%" align="left" valign="top">
- <code>CONFIG_USBMONITOR_TRACEINIT=y</code><br>
- <code>CONFIG_USBMONITOR_TRACECLASS=y</code><br>
- <code>CONFIG_USBMONITOR_TRACETRANSFERS=y</code><br>
- <code>CONFIG_USBMONITOR_TRACECONTROLLER=y</code><br>
- <code>CONFIG_USBMONITOR_TRACEINTERRUPTS=y</code><br>
- </td>
- <td align="left" valign="top">
- Selects which USB event(s) that you want to be traced.
- </td>
- </tr>
- </table>
- </ul>
- <p>
- NOTE: If USB debug output is also enabled, both outputs will appear on the serial console.
- However, the debug output will be asynchronous with the trace output and, hence, difficult to interpret.
- </p>
- </body>
- </html>
|