Documentation/ReleaseNotes/NuttX-5.16

NuttX-5.16
----------

The 63rd release of NuttX, Version 5.16, was made on January 10,
2010 and is available for download from the SourceForge website.
This release includes initial support for USB host in NuttX. The
USB host infrastructure is new to NuttX. This initial USB host release
is probably only beta quality; it is expected the some bugs remain
in the logic and that the functionality requires extension.

Below is a summary of the NuttX USB host implementation as extracted
from the NuttX Porting Guide:

6.3.9 USB Host-Side Drivers
* include/nuttx/usb/usbhost.h. All structures and APIs needed to
work with USB host-side drivers are provided in this header
file.
* struct usbhost_driver_s. Each USB host controller driver must
implement an instance of struct usbhost_driver_s. This structure
is defined in include/nuttx/usb/usbhost.h. Examples:
arch/arm/src/lpc17xx/lpc17_usbhost.c.
* struct usbhost_class_s. Each USB host class driver must implement
an instance of struct usbhost_class_s. This structure is also
defined in include/nuttx/usb/usbhost.h. Examples:
drivers/usbhost/usbhost_storage.c
* USB Host Class Driver Registry. The NuttX USB host infrastructure
includes a registry. During its initialization, each USB host
class driver must call the interface, usbhost_registerclass()
in order add its interface to the registry. Later, when a USB
device is connected, the USB host controller will look up the
USB host class driver that is needed to support the connected
device in this registry. Examples: drivers/usbhost/usbhost_registry.c,
drivers/usbhost/usbhost_registerclass.c, and
drivers/usbhost/usbhost_findclass.c,
* Detection and Enumeration of Connected Devices. Each USB host
device controller supports two methods that are used to detect
and enumeration newly connected devices (and also detect
disconnected devices):
+ int (*wait)(FAR struct usbhost_driver_s *drvr, bool connected);
Wait for a device to be connected or disconnected.
+ int (*enumerate)(FAR struct usbhost_driver_s *drvr);
Enumerate the connected device. As part of this enumeration
process, the driver will (1) get the device's configuration
descriptor, (2) extract the class ID info from the configuration
descriptor, (3) call usbhost_findclass() to find the class
that supports this device, (4) call the create() method on
the struct usbhost_registry_s interface to get a class instance,
and finally (5) call the connect() method of the struct
usbhost_class_s interface. After that, the class is in charge
of the sequence of operations.
* Binding USB Host-Side Drivers. USB host-side controller drivers
are not normally directly accessed by user code, but are usually
bound to another, higher level USB host class driver. The class
driver exports the standard NuttX device interface so that the
connected USB device can be accessed just as with other, similar,
on-board devices. For example, the USB host mass storage class
driver (drivers/usbhost/usbhost_storage.c) will register a
standard, NuttX block driver interface (like /dev/sda) that can
be used to mount a file system just as with any other other
block driver instance. In general, the binding sequence is:

1. Each USB host class driver includes an initialization entry
point that is called from the application at initialization
time. This driver calls usbhost_registerclass() during this
initialization in order to makes itself available in the
event that the device that it supports is connected. Examples:
The function usbhost_storageinit() in the file
drivers/usbhost/usbhost_storage.c
2. Each application must include a waiter thread thread that
(1) calls the USB host controller driver's wait() to detect
the connection of a device, and then (2) call the USB host
controller driver's enumerate method to bind the registered
USB host class driver to the USB host controller driver.
Examples: The function nsh_waiter() in the file
configs/nucleus2g/src/up_nsh.c and the function nsh_waiter()
in the file configs/olimex-lpc1766stk/src/up_nsh.c.
3. As part of its operation during the binding operation, the
USB host class driver will register an instances of a standard
NuttX driver under the /dev directory. To repeat the above
example, the USB host mass storage class driver
(drivers/usbhost/usbhost_storage.c) will register a standard,
NuttX block driver interface (like /dev/sda) that can be
used to mount a file system just as with any other other
block driver instance. Examples: See the call to
register_blockdriver() in the function usbhost_initvolume()
in the file drivers/usbhost/usbhost_storage.c.