From 1eed02c74c2edbb515f122f70832df2d91027771 Mon Sep 17 00:00:00 2001 From: patacongo Date: Fri, 25 Feb 2011 18:46:06 +0000 Subject: [PATCH] Add configuration for Future Electronics Group NE64 Badge board git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@3316 42af7a65-404d-4744-a932-0658087f49c3 --- Documentation/NuttX.html | 10 +- Documentation/NuttxPortingGuide.html | 9 +- Documentation/UsbTrace.html | 332 +++++++++++++++++++++++++++ 3 files changed, 348 insertions(+), 3 deletions(-) create mode 100755 Documentation/UsbTrace.html diff --git a/Documentation/NuttX.html b/Documentation/NuttX.html index 897aa488759..b58bc952436 100644 --- a/Documentation/NuttX.html +++ b/Documentation/NuttX.html @@ -8,7 +8,7 @@

NuttX RTOS

-

Last Updated: February 24, 2011

+

Last Updated: February 25, 2011

@@ -582,7 +582,7 @@

-

  • Built-in USB trace functionality for USB debug.
    • +
  • Built-in USB trace functionality for USB debug.

    • @@ -2043,6 +2043,8 @@ nuttx-5.18 2011-xx-xx Gregory Nutt <spudmonkey@racsa.co.cr> * examples/nsh -- Correct an usage of getopt(): If you stop calling getopt() before all parameters are parsed, you can leave getopt() in a strange state. * Rename arch/pjrc-8051 to arch/8051 + * configs/ne64badge -- Add a configuration for the Future Electronics Group + NE64 Badge development board (Freescale MC9S12NE64) pascal-2.1 2011-xx-xx Gregory Nutt <spudmonkey@racsa.co.cr> @@ -2109,6 +2111,10 @@ buildroot-1.10 2011-xx-xx To-Do List + + + USB Device Driver Tracing + diff --git a/Documentation/NuttxPortingGuide.html b/Documentation/NuttxPortingGuide.html index 6c9de941fb0..5358f6797be 100644 --- a/Documentation/NuttxPortingGuide.html +++ b/Documentation/NuttxPortingGuide.html @@ -12,7 +12,7 @@

    NuttX RTOS Porting Guide

    -

    Last Updated: February 24, 2011

    +

    Last Updated: February 25, 2011

    @@ -2457,6 +2457,13 @@ extern void up_ledoff(int led); All structures and APIs needed to work with USB device-side drivers are provided in this header file.

    +
  • +

    + include/nuttx/usb/usbdev_trace.h. + Declarations needed to work the the NuttX USB device driver trace capability. + That USB trace capability is detailed in separate document. +

    +

  • struct usbdev_s. diff --git a/Documentation/UsbTrace.html b/Documentation/UsbTrace.html new file mode 100755 index 00000000000..ac1a7e75074 --- /dev/null +++ b/Documentation/UsbTrace.html @@ -0,0 +1,332 @@ + + +README Files + + + +

    + + + + +
    +

    NuttX USB Device Trace

    +

    Last Updated: February 25, 2010

    +
    +
    +

    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_IDInitialization events
      TRACE_EP_IDEndpoint API calls
      TRACE_DEV_IDUSB device API calls
      TRACE_CLASS_IDUSB class driver API calls
      TRACE_CLASSAPI_IDOther class driver system API calls
      TRACE_CLASSSTATE_IDTrack class driver state changes
      TRACE_INTENTRY_IDInterrupt handler entry
      TRACE_INTDECODE_IDDecoded interrupt event
      TRACE_INTEXIT_IDInterrupt handler exit
      TRACE_OUTREQQUEUED_IDRequest queued for OUT endpoint
      TRACE_INREQQUEUED_IDRequest queued for IN endpoint
      TRACE_READ_IDRead (OUT) action
      TRACE_WRITE_IDWrite (IN) action
      TRACE_COMPLETE_IDRequest completed
      TRACE_DEVERROR_IDUSB controller driver error event
      TRACE_CLSERROR_IDUSB 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. +
    2. 8-bits of additional trace ID data, and
      3. +
    3. 16-bits of additonal data.
      4. +
    +

    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 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
       user_start: Registering USB serial driver
       uart_register: Registering /dev/ttyUSB0
       user_start: Successfully registered the serial driver
      1Class API call 1: 0000
      2Class error: 19:0000
       user_start: ERROR: Failed to open /dev/ttyUSB0 for reading: 107
       user_start: Not connected. Wait and try again.
      3Interrupt 1 entry: 0039
      4Interrupt decode 7: 0019
      5Interrupt decode 32: 0019
      6Interrupt decode 6: 0019
      7Class disconnect(): 0000
      8Device pullup(): 0001
      9Interrupt 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 ID8-bit
      EVENT
      DATA      		MEANING16-bit
      EVENT
      DATA
      1TRACE_CLASSAPI_ID11USBSER_TRACECLASSAPI_SETUP10000
      2TRACE_CLSERROR_ID119USBSER_TRACEERR_SETUPNOTCONNECTED10000
      3TRACE_INTENTRY_ID11LPC17_TRACEINTID_USB20039
      4TRACE_INTDECODE_ID27LPC17_TRACEINTID_DEVSTAT20019
      5TRACE_INTDECODE_ID232LPC17_TRACEINTID_SUSPENDCHG20019
      6TRACE_INTDECODE_ID26LPC17_TRACEINTID_DEVRESET20019
      7TRACE_CLASS_ID13(See TRACE_CLASSDISCONNECT1)0000
      8TRACE_DEV_ID16(See TRACE_DEVPULLUP1)0001
      9TRACE_INTEXIT_ID11LPC17_TRACEINTID_USB20000
      +

      NOTES:
      + 1See include/nuttx/usb/usbdev_trace.h
      + 2See 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/usbdev_serial.c: + 
        +static int usbser_setup(FAR struct uart_dev_s *dev)
+{
+  ...
+  usbtrace(USBSER_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/usbdev_serial.c: + 
        +static int usbser_setup(FAR struct uart_dev_s *dev)
+{
+  ...
+  /* Check if we have been configured */
+
+  if (priv->config == USBSER_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 +
      • +
    + +