You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@nuttx.apache.org by ac...@apache.org on 2020/09/06 13:58:21 UTC
[incubator-nuttx] branch master updated: documentation: split
device drivers sections into individual documents
This is an automated email from the ASF dual-hosted git repository.
acassis pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
The following commit(s) were added to refs/heads/master by this push:
new 44cee3f documentation: split device drivers sections into individual documents
44cee3f is described below
commit 44cee3f2114de6e24f7299c063918965c0405343
Author: Matias N <ma...@protobits.dev>
AuthorDate: Sat Sep 5 18:36:36 2020 -0300
documentation: split device drivers sections into individual documents
---
Documentation/components/drivers/block/index.rst | 41 +
.../components/drivers/character/analog.rst | 55 ++
Documentation/components/drivers/character/can.rst | 36 +
.../components/drivers/character/index.rst | 64 ++
.../components/drivers/character/keypad.rst | 143 +++
Documentation/components/drivers/character/pwm.rst | 34 +
.../components/drivers/character/quadrature.rst | 29 +
Documentation/components/drivers/character/rtc.rst | 25 +
.../components/drivers/character/serial.rst | 29 +
.../components/drivers/character/timer.rst | 18 +
.../components/drivers/character/touchscreen.rst | 38 +
.../components/drivers/character/watchdog.rst | 29 +
Documentation/components/drivers/index.rst | 963 +--------------------
.../components/drivers/special/ethernet.rst | 17 +
.../components/drivers/special/framebuffer.rst | 34 +
Documentation/components/drivers/special/i2c.rst | 22 +
Documentation/components/drivers/special/index.rst | 34 +
Documentation/components/drivers/special/lcd.rst | 47 +
Documentation/components/drivers/special/mtd.rst | 47 +
Documentation/components/drivers/special/sdio.rst | 33 +
Documentation/components/drivers/special/spi.rst | 25 +
.../components/drivers/special/usbdev.rst | 50 ++
.../components/drivers/special/usbhost.rst | 108 +++
23 files changed, 985 insertions(+), 936 deletions(-)
diff --git a/Documentation/components/drivers/block/index.rst b/Documentation/components/drivers/block/index.rst
new file mode 100644
index 0000000..51a09ec
--- /dev/null
+++ b/Documentation/components/drivers/block/index.rst
@@ -0,0 +1,41 @@
+====================
+Block Device Drivers
+====================
+
+Block device drivers have these properties:
+
+- ``include/nuttx/fs/fs.h``. All structures and APIs needed
+ to work with block drivers are provided in this header file.
+
+- ``struct block_operations``. Each block device driver must
+ implement an instance of ``struct block_operations``. That
+ structure defines a call table with the following methods:
+
+- ``int register_blockdriver(const char *path, const struct block_operations *bops, mode_t mode, void *priv);``.
+ Each block driver registers itself by calling
+ ``register_blockdriver()``, passing it the ``path`` where it
+ will appear in the `pseudo-file-system <#NxFileSystem>`__ and
+ it's initialized instance of ``struct block_operations``.
+
+- **User Access**. Users do not normally access block drivers
+ directly, rather, they access block drivers indirectly through
+ the ``mount()`` API. The ``mount()`` API binds a block driver
+ instance with a file system and with a mountpoint. Then the
+ user may use the block driver to access the file system on the
+ underlying media. *Example*: See the ``cmd_mount()``
+ implementation in ``apps/nshlib/nsh_fscmds.c``.
+
+- **Accessing a Character Driver as a Block Device**. See the
+ loop device at ``drivers/loop.c``. *Example*: See the
+ ``cmd_losetup()`` implementation in
+ ``apps/nshlib/nsh_fscmds.c``.
+
+- **Accessing a Block Driver as Character Device**. See the
+ Block-to-Character (BCH) conversion logic in ``drivers/bch/``.
+ *Example*: See the ``cmd_dd()`` implementation in
+ ``apps/nshlib/nsh_ddcmd.c``.
+
+- **Examples**. ``drivers/loop.c``,
+ ``drivers/mmcsd/mmcsd_spi.c``, ``drivers/ramdisk.c``, etc.
+
+
diff --git a/Documentation/components/drivers/character/analog.rst b/Documentation/components/drivers/character/analog.rst
new file mode 100644
index 0000000..f4714d8
--- /dev/null
+++ b/Documentation/components/drivers/character/analog.rst
@@ -0,0 +1,55 @@
+========================
+Analog (ADC/DAC) Drivers
+========================
+
+The NuttX analog drivers are split into two parts:
+
+#. An "upper half", generic driver that provides the common analog
+ interface to application level code, and
+#. A "lower half", platform-specific driver that implements the
+ low-level controls to implement the analog functionality.
+
+- General header files for the NuttX analog drivers reside in
+ ``include/nuttx/analog/``. These header files includes both the
+ application level interface to the analog driver as well as the
+ interface between the "upper half" and "lower half" drivers.
+- Common analog logic and share-able analog drivers reside in the
+ ``drivers/analog/``.
+- Platform-specific drivers reside in
+ ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>* directory
+ for the specific processor *<architecture>* and for the
+ specific *<chip>* analog peripheral devices.
+
+ADC Drivers
+-----------
+
+- ``include/nuttx/analog/adc.h``. All structures and APIs needed
+ to work with ADC drivers are provided in this header file. This
+ header file includes:
+
+ #. Structures and interface descriptions needed to develop a
+ low-level, architecture-specific, ADC driver.
+ #. To register the ADC driver with a common ADC character
+ driver.
+ #. Interfaces needed for interfacing user programs with the
+ common ADC character driver.
+
+- ``drivers/analog/adc.c``. The implementation of the common ADC
+ character driver.
+
+DAC Drivers
+-----------
+
+- ``include/nuttx/analog/dac.h``. All structures and APIs needed
+ to work with DAC drivers are provided in this header file. This
+ header file includes:
+
+ #. Structures and interface descriptions needed to develop a
+ low-level, architecture-specific, DAC driver.
+ #. To register the DAC driver with a common DAC character
+ driver.
+ #. Interfaces needed for interfacing user programs with the
+ common DAC character driver.
+
+- ``drivers/analog/dac.c``. The implementation of the common DAC
+ character driver.
diff --git a/Documentation/components/drivers/character/can.rst b/Documentation/components/drivers/character/can.rst
new file mode 100644
index 0000000..b08ebb0
--- /dev/null
+++ b/Documentation/components/drivers/character/can.rst
@@ -0,0 +1,36 @@
+===========
+CAN Drivers
+===========
+
+NuttX supports only a very low-level CAN driver. This driver
+supports only the data exchange and does not include any
+high-level CAN protocol. The NuttX CAN driver is split into two
+parts:
+
+#. An "upper half", generic driver that provides the common CAN
+ interface to application level code, and
+#. A "lower half", platform-specific driver that implements the
+ low-level timer controls to implement the CAN functionality.
+
+Files supporting CAN can be found in the following locations:
+
+- **Interface Definition**. The header file for the NuttX CAN
+ driver resides at ``include/nuttx/can/can.h``. This header file
+ includes both the application level interface to the CAN driver
+ as well as the interface between the "upper half" and "lower
+ half" drivers. The CAN module uses a standard character driver
+ framework.
+- **"Upper Half" Driver**. The generic, "upper half" CAN driver
+ resides at ``drivers/can.c``.
+- **"Lower Half" Drivers**. Platform-specific CAN drivers reside
+ in ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>*
+ directory for the specific processor *<architecture>* and for
+ the specific *<chip>* CAN peripheral devices.
+
+**Usage Note**: When reading from the CAN driver multiple messages
+may be returned, depending on (1) the size the returned can
+messages, and (2) the size of the buffer provided to receive CAN
+messages. *Never assume that a single message will be returned*...
+if you do this, *you will lose CAN data* under conditions where
+your read buffer can hold more than one small message. Below is an
+example about how you should think of the CAN read operation:
diff --git a/Documentation/components/drivers/character/index.rst b/Documentation/components/drivers/character/index.rst
new file mode 100644
index 0000000..e50dc89
--- /dev/null
+++ b/Documentation/components/drivers/character/index.rst
@@ -0,0 +1,64 @@
+========================
+Character Device Drivers
+========================
+
+Character device drivers have these properties:
+
+- ``include/nuttx/fs/fs.h``. All structures and APIs needed
+ to work with character drivers are provided in this header
+ file.
+
+- ``struct file_operations``. Each character device driver
+ must implement an instance of ``struct file_operations``. That
+ structure defines a call table with the following methods:
+
+- ``int register_driver(const char *path, const struct file_operations *fops, mode_t mode, void *priv);``.
+ Each character driver registers itself by calling
+ ``register_driver()``, passing it the ``path`` where it will
+ appear in the `pseudo-file-system <#NxFileSystem>`__ and it's
+ initialized instance of ``struct file_operations``.
+
+- **User Access**. After it has been registered, the character
+ driver can be accessed by user code using the standard `driver
+ operations <NuttxUserGuide.html#driveroperations>`__ including
+ ``open()``, ``close()``, ``read()``, ``write()``, etc.
+
+- **Specialized Character Drivers**. Within the common character
+ driver framework, there are different specific varieties of
+ *specialized* character drivers. The unique requirements of the
+ underlying device hardware often mandates some customization of
+ the character driver. These customizations tend to take the
+ form of:
+
+ - Device-specific ``ioctl()`` commands used to performed
+ specialized operations on the device. These ``ioctl()`` will
+ be documented in header files under ``include/nuttx`` that
+ detail the specific device interface.
+ - Specialized I/O formats. Some devices will require that
+ ``read()`` and/or ``write()`` operations use data conforming
+ to a specific format, rather than a plain stream of bytes.
+ These specialized I/O formats will be documented in header
+ files under ``include/nuttx`` that detail the specific
+ device interface. The typical representation of the I/O
+ format will be a C structure definition.
+
+ The specialized character drivers support by NuttX are
+ documented in the following paragraphs.
+
+- **Examples**: ``drivers/dev_null.c``, ``drivers/fifo.c``,
+ ``drivers/serial.c``, etc.
+
+.. toctree::
+ :caption: Supported Drivers
+
+ serial.rst
+ touchscreen.rst
+ analog.rst
+ pwm.rst
+ can.rst
+ quadrature.rst
+ timer.rst
+ rtc.rst
+ watchdog.rst
+ keypad.rst
+
diff --git a/Documentation/components/drivers/character/keypad.rst b/Documentation/components/drivers/character/keypad.rst
new file mode 100644
index 0000000..63e0446
--- /dev/null
+++ b/Documentation/components/drivers/character/keypad.rst
@@ -0,0 +1,143 @@
+=======================
+Keyboard/Keypad Drivers
+=======================
+
+**Keypads vs. Keyboards** Keyboards and keypads are really the
+same devices for NuttX. A keypad is thought of as simply a
+keyboard with fewer keys.
+
+**Special Commands**. In NuttX, a keyboard/keypad driver is simply
+a character driver that may have an (optional) encoding/decoding
+layer on the data returned by the character driver. A keyboard may
+return simple text data (alphabetic, numeric, and punctuation) or
+control characters (enter, control-C, etc.) when a key is pressed.
+We can think about this the "normal" keyboard data stream.
+However, in addition, most keyboards support actions that cannot
+be represented as text or control data. Such actions include
+things like cursor controls (home, up arrow, page down, etc.),
+editing functions (insert, delete, etc.), volume controls, (mute,
+volume up, etc.) and other special functions. In this case, some
+special encoding may be required to multiplex the normal text data
+and special command key press data streams.
+
+**Key Press and Release Events** Sometimes the time that a key is
+released is needed by applications as well. Thus, in addition to
+normal and special key press events, it may also be necessary to
+encode normal and special key release events.
+
+**Encoding/Decoding** Layer. An optional encoding/decoding layer
+can be used with the basic character driver to encode the keyboard
+events into the text data stream. The function interfaces that
+comprise that encoding/decoding layer are defined in the header
+file ``include/nuttx/input/kbd_code.h``. These functions provide
+an matched set of (a) driver encoding interfaces, and (b)
+application decoding interfaces.
+
+#. **Driver Encoding Interfaces**. These are interfaces used by
+ the keyboard/keypad driver to encode keyboard events and data.
+
+ - ``kbd_press()``
+
+ **Function Prototype:**
+
+ **Description:**
+
+ **Input Parameters:**
+
+ - ``ch``: The character to be added to the output stream.
+ - ``stream``: An instance of ``lib_outstream_s`` to perform
+ the actual low-level put operation.
+
+ **Returned Value:**
+
+ - ``kbd_release()``
+
+ **Function Prototype:**
+
+ **Description:**
+
+ **Input Parameters:**
+
+ - ``ch``: The character associated with the key that was
+ released.
+ - ``stream``: An instance of ``lib_outstream_s`` to perform
+ the actual low-level put operation.
+
+ **Returned Value:**
+
+ - ``kbd_specpress()``
+
+ **Function Prototype:**
+
+ **Description:**
+
+ **Input Parameters:**
+
+ - ``keycode``: The command to be added to the output
+ stream. The enumeration ``enum kbd_keycode_e keycode``
+ identifies all commands known to the system.
+ - ``stream``: An instance of ``lib_outstream_s`` to perform
+ the actual low-level put operation.
+
+ **Returned Value:**
+
+ - ``kbd_specrel()``
+
+ **Function Prototype:**
+
+ **Description:**
+
+ **Input Parameters:**
+
+ - ``keycode``: The command to be added to the output
+ stream. The enumeration ``enum kbd_keycode_e keycode``
+ identifies all commands known to the system.
+ - ``stream``: An instance of ``lib_outstream_s`` to perform
+ the actual low-level put operation.
+
+ **Returned Value:**
+
+#. **Application Decoding Interfaces**. These are user interfaces
+ to decode the values returned by the keyboard/keypad driver.
+
+ - ``kbd_decode()``
+
+ **Function Prototype:**
+
+ **Description:**
+
+ **Input Parameters:**
+
+ - ``stream``: An instance of ``lib_instream_s`` to perform
+ the actual low-level get operation.
+ - ``pch``: The location to save the returned value. This
+ may be either a normal, character code or a special
+ command (i.e., a value from ``enum kbd_getstate_s``.
+ - ``state``: A user provided buffer to support parsing.
+ This structure should be cleared the first time that
+ ``kbd_decode()`` is called.
+
+ **Returned Value:**
+
+ - ``KBD_PRESS`` (0)**: Indicates the successful receipt
+ of normal, keyboard data. This corresponds to a keypress
+ event. The returned value in ``pch`` is a simple byte of
+ text or control data.
+ - ``KBD_RELEASE`` (1)**: Indicates a key release event.
+ The returned value in ``pch`` is the byte of text or
+ control data corresponding to the released key.
+ - ``KBD_SPECPRESS`` (2)**: Indicates the successful
+ receipt of a special keyboard command. The returned value
+ in ``pch`` is a value from ``enum kbd_getstate_s``.
+ - ``KBD_SPECREL`` (3)**: Indicates a special command key
+ release event. The returned value in ``pch`` is a value
+ from ``enum kbd_getstate_s``.
+ - ``KBD_ERROR`` (``EOF``)**: An error has getting the
+ next character (reported by the ``stream``). Normally
+ indicates the end of file.
+
+**I/O Streams**. Notice the use of the abstract I/O streams in
+these interfaces. These stream interfaces are defined in
+``include/nuttx/streams.h``.
+
+
diff --git a/Documentation/components/drivers/character/pwm.rst b/Documentation/components/drivers/character/pwm.rst
new file mode 100644
index 0000000..918c0c1
--- /dev/null
+++ b/Documentation/components/drivers/character/pwm.rst
@@ -0,0 +1,34 @@
+===========
+PWM Drivers
+===========
+
+For the purposes of this driver, a PWM device is any device that
+generates periodic output pulses of controlled frequency and pulse
+width. Such a device might be used, for example, to perform
+pulse-width modulated output or frequency/pulse-count modulated
+output (such as might be needed to control a stepper motor).
+
+The NuttX PWM driver is split into two parts:
+
+#. An "upper half", generic driver that provides the common PWM
+ interface to application level code, and
+#. A "lower half", platform-specific driver that implements the
+ low-level timer controls to implement the PWM functionality.
+
+Files supporting PWM can be found in the following locations:
+
+- **Interface Definition**. The header file for the NuttX PWM
+ driver reside at ``include/nuttx/timers/pwm.h``. This header
+ file includes both the application level interface to the PWM
+ driver as well as the interface between the "upper half" and
+ "lower half" drivers. The PWM module uses a standard character
+ driver framework. However, since the PWM driver is a devices
+ control interface and not a data transfer interface, the
+ majority of the functionality available to the application is
+ implemented in driver ioctl calls.
+- **"Upper Half" Driver**. The generic, "upper half" PWM driver
+ resides at ``drivers/pwm.c``.
+- **"Lower Half" Drivers**. Platform-specific PWM drivers reside
+ in ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>*
+ directory for the specific processor *<architecture>* and for
+ the specific *<chip>* PWM peripheral devices.
diff --git a/Documentation/components/drivers/character/quadrature.rst b/Documentation/components/drivers/character/quadrature.rst
new file mode 100644
index 0000000..51d5372
--- /dev/null
+++ b/Documentation/components/drivers/character/quadrature.rst
@@ -0,0 +1,29 @@
+Quadrature Encoder Drivers
+==========================
+
+NuttX supports a low-level, two-part Quadrature Encoder driver.
+
+#. An "upper half", generic driver that provides the common
+ Quadrature Encoder interface to application level code, and
+#. A "lower half", platform-specific driver that implements the
+ low-level timer controls to implement the Quadrature Encoder
+ functionality.
+
+Files supporting the Quadrature Encoder can be found in the
+following locations:
+
+- **Interface Definition**. The header file for the NuttX
+ Quadrature Encoder driver reside at
+ ``include/nuttx/sensors/qencoder.h``. This header file includes
+ both the application level interface to the Quadrature Encoder
+ driver as well as the interface between the "upper half" and
+ "lower half" drivers. The Quadrature Encoder module uses a
+ standard character driver framework.
+- **"Upper Half" Driver**. The generic, "upper half" Quadrature
+ Encoder driver resides at ``drivers/sensors/qencoder.c``.
+- **"Lower Half" Drivers**. Platform-specific Quadrature Encoder
+ drivers reside in
+ ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>* directory
+ for the specific processor *<architecture>* and for the
+ specific *<chip>* Quadrature Encoder peripheral devices.
+
diff --git a/Documentation/components/drivers/character/rtc.rst b/Documentation/components/drivers/character/rtc.rst
new file mode 100644
index 0000000..f913e45
--- /dev/null
+++ b/Documentation/components/drivers/character/rtc.rst
@@ -0,0 +1,25 @@
+RTC Drivers
+===========
+
+NuttX supports a low-level, two-part RealTime Clock (RTC) driver.
+
+#. An "upper half", generic driver that provides the common RTC
+ interface to application level code, and
+#. A "lower half", platform-specific driver that implements the
+ low-level timer controls to implement the RTC functionality.
+
+Files supporting the RTC driver can be found in the following
+locations:
+
+- **Interface Definition**. The header file for the NuttX RTC
+ driver reside at ``include/nuttx/timers/rtc.h``. This header
+ file includes both the application level interface to the RTC
+ driver as well as the interface between the "upper half" and
+ "lower half" drivers. The RTC driver uses a standard character
+ driver framework.
+- **"Upper Half" Driver**. The generic, "upper half" RTC driver
+ resides at ``drivers/timers/rtc.c``.
+- **"Lower Half" Drivers**. Platform-specific RTC drivers reside
+ in ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>*
+ directory for the specific processor *<architecture>* and for
+ the specific *<chip>* RTC peripheral devices.
diff --git a/Documentation/components/drivers/character/serial.rst b/Documentation/components/drivers/character/serial.rst
new file mode 100644
index 0000000..2d1f5eb
--- /dev/null
+++ b/Documentation/components/drivers/character/serial.rst
@@ -0,0 +1,29 @@
+=====================
+Serial Device Drivers
+=====================
+
+- ``include/nuttx/serial/serial.h``. All structures and APIs
+ needed to work with serial drivers are provided in this header
+ file.
+
+- ``struct uart_ops_s``. Each serial device driver must
+ implement an instance of ``struct uart_ops_s``. That structure
+ defines a call table with the following methods:
+
+- ``int uart_register(FAR const char *path, FAR uart_dev_t *dev);``.
+ A serial driver may register itself by calling
+ ``uart_register()``, passing it the ``path`` where it will
+ appear in the `pseudo-file-system <#NxFileSystem>`__ and it's
+ initialized instance of ``struct uart_ops_s``. By convention,
+ serial device drivers are registered at paths like
+ ``/dev/ttyS0``, ``/dev/ttyS1``, etc. See the
+ ``uart_register()`` implementation in ``drivers/serial.c``.
+
+- **User Access**. Serial drivers are, ultimately, normal
+ `character drivers <#chardrivers>`__ and are accessed as other
+ character drivers.
+
+- **Examples**: ``arch/arm/src/stm32/stm32_serial.c``,
+ ``arch/arm/src/lpc214x/lpc214x_serial.c``,
+ ``arch/z16/src/z16f/z16f_serial.c``, etc.
+
diff --git a/Documentation/components/drivers/character/timer.rst b/Documentation/components/drivers/character/timer.rst
new file mode 100644
index 0000000..6f2a90e
--- /dev/null
+++ b/Documentation/components/drivers/character/timer.rst
@@ -0,0 +1,18 @@
+Timer Drivers
+=============
+
+Files supporting the timer driver can be found in the following
+locations:
+
+- **Interface Definition**. The header file for the NuttX timer
+ driver reside at ``include/nuttx/timers/timer.h``. This header
+ file includes both the application level interface to the timer
+ driver as well as the interface between the "upper half" and
+ "lower half" drivers. The timer driver uses a standard
+ character driver framework.
+- **"Upper Half" Driver**. The generic, "upper half" timer driver
+ resides at ``drivers/timers/timer.c``.
+- **"Lower Half" Drivers**. Platform-specific timer drivers
+ reside in ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>*
+ directory for the specific processor *<architecture>* and for
+ the specific *<chip>* timer peripheral devices.
diff --git a/Documentation/components/drivers/character/touchscreen.rst b/Documentation/components/drivers/character/touchscreen.rst
new file mode 100644
index 0000000..70876d5
--- /dev/null
+++ b/Documentation/components/drivers/character/touchscreen.rst
@@ -0,0 +1,38 @@
+==========================
+Touchscreen Device Drivers
+==========================
+
+NuttX supports a two-part touchscreen driver architecture.
+
+#. An "upper half", generic driver that provides the common
+ touchscreen interface to application level code, and
+#. A "lower half", platform-specific driver that implements the
+ low-level touchscreen controls to implement the touchscreen
+ functionality.
+
+Files supporting the touchscreen controller (TSC) driver can be
+found in the following locations:
+
+- **Interface Definition**. The header files for NuttX
+ touchscreen drivers reside in the
+ ``include/nuttx/include/input`` directory. The interface
+ between the touchscreen controller "upper half" and "lower
+ half" drivers are *not* common, but vary from
+ controller-to-controller. Because of this, each touchscreen
+ driver has its own unique header file that describes the "upper
+ half"/"lower half" interface in that directory. The application
+ level interface to each touchscreen driver, on the other hand,
+ *is* the same for each touchscreen driver and is described
+ ``include/nuttx/include/input/touchscreen.h``. The touchscreen
+ driver uses a standard character driver framework but read
+ operations return specially formatted data.
+- **"Upper Half" Driver**. The controller-specific, "upper half"
+ touchscreen drivers reside in the directory ``drivers/input``.
+- **"Lower Half" Drivers**. Platform-specific touchscreen drivers
+ reside in either: (1) The
+ ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>* directory
+ for the processor architectures that have build in touchscreen
+ controllers or (2) the
+ ``boards/``\ *<arch>*\ ``/``\ *<chip>*\ ``/``\ *<board>*\ ``/src/``
+ directory for boards that use an external touchscreen
+ controller chip.
diff --git a/Documentation/components/drivers/character/watchdog.rst b/Documentation/components/drivers/character/watchdog.rst
new file mode 100644
index 0000000..94a28c9
--- /dev/null
+++ b/Documentation/components/drivers/character/watchdog.rst
@@ -0,0 +1,29 @@
+======================
+Watchdog Timer Drivers
+======================
+
+NuttX supports a low-level, two-part watchdog timer driver.
+
+#. An "upper half", generic driver that provides the common
+ watchdog timer interface to application level code, and
+#. A "lower half", platform-specific driver that implements the
+ low-level timer controls to implement the watchdog timer
+ functionality.
+
+Files supporting the watchdog timer driver can be found in the
+following locations:
+
+- **Interface Definition**. The header file for the NuttX
+ watchdog timer driver reside at
+ ``include/nuttx/timers/watchdog.h``. This header file includes
+ both the application level interface to the watchdog timer
+ driver as well as the interface between the "upper half" and
+ "lower half" drivers. The watchdog timer driver uses a standard
+ character driver framework.
+- **"Upper Half" Driver**. The generic, "upper half" watchdog
+ timer driver resides at ``drivers/timers/watchdog.c``.
+- **"Lower Half" Drivers**. Platform-specific watchdog timer
+ drivers reside in
+ ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>* directory
+ for the specific processor *<architecture>* and for the
+ specific *<chip>* watchdog timer peripheral devices.
diff --git a/Documentation/components/drivers/index.rst b/Documentation/components/drivers/index.rst
index 28af15d..5ccc1f0 100644
--- a/Documentation/components/drivers/index.rst
+++ b/Documentation/components/drivers/index.rst
@@ -2,940 +2,31 @@
Device Drivers
==============
-NuttX supports a variety of device drivers including:
-
- - *Character* Device Drivers,
- - *Block* Device Drivers, and
- - Other *Specialized* Drivers.
-
-These different device driver types are discussed in the following
-paragraphs. Note: device driver support depends on the
-*in-memory*, *pseudo* file system that is enabled by default.
-
-Character Device Drivers
-************************
-
-Character device drivers have these properties:
-
-- ``include/nuttx/fs/fs.h``. All structures and APIs needed
- to work with character drivers are provided in this header
- file.
-
-- ``struct file_operations``. Each character device driver
- must implement an instance of ``struct file_operations``. That
- structure defines a call table with the following methods:
-
-- ``int register_driver(const char *path, const struct file_operations *fops, mode_t mode, void *priv);``.
- Each character driver registers itself by calling
- ``register_driver()``, passing it the ``path`` where it will
- appear in the `pseudo-file-system <#NxFileSystem>`__ and it's
- initialized instance of ``struct file_operations``.
-
-- **User Access**. After it has been registered, the character
- driver can be accessed by user code using the standard `driver
- operations <NuttxUserGuide.html#driveroperations>`__ including
- ``open()``, ``close()``, ``read()``, ``write()``, etc.
-
-- **Specialized Character Drivers**. Within the common character
- driver framework, there are different specific varieties of
- *specialized* character drivers. The unique requirements of the
- underlying device hardware often mandates some customization of
- the character driver. These customizations tend to take the
- form of:
-
- - Device-specific ``ioctl()`` commands used to performed
- specialized operations on the device. These ``ioctl()`` will
- be documented in header files under ``include/nuttx`` that
- detail the specific device interface.
- - Specialized I/O formats. Some devices will require that
- ``read()`` and/or ``write()`` operations use data conforming
- to a specific format, rather than a plain stream of bytes.
- These specialized I/O formats will be documented in header
- files under ``include/nuttx`` that detail the specific
- device interface. The typical representation of the I/O
- format will be a C structure definition.
-
- The specialized character drivers support by NuttX are
- documented in the following paragraphs.
-
-- **Examples**: ``drivers/dev_null.c``, ``drivers/fifo.c``,
- ``drivers/serial.c``, etc.
-
-Serial Device Drivers
-=====================
-
-- ``include/nuttx/serial/serial.h``. All structures and APIs
- needed to work with serial drivers are provided in this header
- file.
-
-- ``struct uart_ops_s``. Each serial device driver must
- implement an instance of ``struct uart_ops_s``. That structure
- defines a call table with the following methods:
-
-- ``int uart_register(FAR const char *path, FAR uart_dev_t *dev);``.
- A serial driver may register itself by calling
- ``uart_register()``, passing it the ``path`` where it will
- appear in the `pseudo-file-system <#NxFileSystem>`__ and it's
- initialized instance of ``struct uart_ops_s``. By convention,
- serial device drivers are registered at paths like
- ``/dev/ttyS0``, ``/dev/ttyS1``, etc. See the
- ``uart_register()`` implementation in ``drivers/serial.c``.
-
-- **User Access**. Serial drivers are, ultimately, normal
- `character drivers <#chardrivers>`__ and are accessed as other
- character drivers.
-
-- **Examples**: ``arch/arm/src/stm32/stm32_serial.c``,
- ``arch/arm/src/lpc214x/lpc214x_serial.c``,
- ``arch/z16/src/z16f/z16f_serial.c``, etc.
-
-Touchscreen Device Drivers
-==========================
-
-NuttX supports a two-part touchscreen driver architecture.
-
-#. An "upper half", generic driver that provides the common
- touchscreen interface to application level code, and
-#. A "lower half", platform-specific driver that implements the
- low-level touchscreen controls to implement the touchscreen
- functionality.
-
-Files supporting the touchscreen controller (TSC) driver can be
-found in the following locations:
-
-- **Interface Definition**. The header files for NuttX
- touchscreen drivers reside in the
- ``include/nuttx/include/input`` directory. The interface
- between the touchscreen controller "upper half" and "lower
- half" drivers are *not* common, but vary from
- controller-to-controller. Because of this, each touchscreen
- driver has its own unique header file that describes the "upper
- half"/"lower half" interface in that directory. The application
- level interface to each touchscreen driver, on the other hand,
- *is* the same for each touchscreen driver and is described
- ``include/nuttx/include/input/touchscreen.h``. The touchscreen
- driver uses a standard character driver framework but read
- operations return specially formatted data.
-- **"Upper Half" Driver**. The controller-specific, "upper half"
- touchscreen drivers reside in the directory ``drivers/input``.
-- **"Lower Half" Drivers**. Platform-specific touchscreen drivers
- reside in either: (1) The
- ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>* directory
- for the processor architectures that have build in touchscreen
- controllers or (2) the
- ``boards/``\ *<arch>*\ ``/``\ *<chip>*\ ``/``\ *<board>*\ ``/src/``
- directory for boards that use an external touchscreen
- controller chip.
-
-Analog (ADC/DAC) Drivers
-========================
-
-The NuttX analog drivers are split into two parts:
-
-#. An "upper half", generic driver that provides the common analog
- interface to application level code, and
-#. A "lower half", platform-specific driver that implements the
- low-level controls to implement the analog functionality.
-
-- General header files for the NuttX analog drivers reside in
- ``include/nuttx/analog/``. These header files includes both the
- application level interface to the analog driver as well as the
- interface between the "upper half" and "lower half" drivers.
-- Common analog logic and share-able analog drivers reside in the
- ``drivers/analog/``.
-- Platform-specific drivers reside in
- ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>* directory
- for the specific processor *<architecture>* and for the
- specific *<chip>* analog peripheral devices.
-
-ADC Drivers
------------
-
-- ``include/nuttx/analog/adc.h``. All structures and APIs needed
- to work with ADC drivers are provided in this header file. This
- header file includes:
-
- #. Structures and interface descriptions needed to develop a
- low-level, architecture-specific, ADC driver.
- #. To register the ADC driver with a common ADC character
- driver.
- #. Interfaces needed for interfacing user programs with the
- common ADC character driver.
-
-- ``drivers/analog/adc.c``. The implementation of the common ADC
- character driver.
-
-DAC Drivers
------------
-
-- ``include/nuttx/analog/dac.h``. All structures and APIs needed
- to work with DAC drivers are provided in this header file. This
- header file includes:
-
- #. Structures and interface descriptions needed to develop a
- low-level, architecture-specific, DAC driver.
- #. To register the DAC driver with a common DAC character
- driver.
- #. Interfaces needed for interfacing user programs with the
- common DAC character driver.
-
-- ``drivers/analog/dac.c``. The implementation of the common DAC
- character driver.
-
-PWM Drivers
-===========
-
-For the purposes of this driver, a PWM device is any device that
-generates periodic output pulses of controlled frequency and pulse
-width. Such a device might be used, for example, to perform
-pulse-width modulated output or frequency/pulse-count modulated
-output (such as might be needed to control a stepper motor).
-
-The NuttX PWM driver is split into two parts:
-
-#. An "upper half", generic driver that provides the common PWM
- interface to application level code, and
-#. A "lower half", platform-specific driver that implements the
- low-level timer controls to implement the PWM functionality.
-
-Files supporting PWM can be found in the following locations:
-
-- **Interface Definition**. The header file for the NuttX PWM
- driver reside at ``include/nuttx/timers/pwm.h``. This header
- file includes both the application level interface to the PWM
- driver as well as the interface between the "upper half" and
- "lower half" drivers. The PWM module uses a standard character
- driver framework. However, since the PWM driver is a devices
- control interface and not a data transfer interface, the
- majority of the functionality available to the application is
- implemented in driver ioctl calls.
-- **"Upper Half" Driver**. The generic, "upper half" PWM driver
- resides at ``drivers/pwm.c``.
-- **"Lower Half" Drivers**. Platform-specific PWM drivers reside
- in ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>*
- directory for the specific processor *<architecture>* and for
- the specific *<chip>* PWM peripheral devices.
-
-CAN Drivers
-===========
-
-NuttX supports only a very low-level CAN driver. This driver
-supports only the data exchange and does not include any
-high-level CAN protocol. The NuttX CAN driver is split into two
-parts:
-
-#. An "upper half", generic driver that provides the common CAN
- interface to application level code, and
-#. A "lower half", platform-specific driver that implements the
- low-level timer controls to implement the CAN functionality.
-
-Files supporting CAN can be found in the following locations:
-
-- **Interface Definition**. The header file for the NuttX CAN
- driver resides at ``include/nuttx/can/can.h``. This header file
- includes both the application level interface to the CAN driver
- as well as the interface between the "upper half" and "lower
- half" drivers. The CAN module uses a standard character driver
- framework.
-- **"Upper Half" Driver**. The generic, "upper half" CAN driver
- resides at ``drivers/can.c``.
-- **"Lower Half" Drivers**. Platform-specific CAN drivers reside
- in ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>*
- directory for the specific processor *<architecture>* and for
- the specific *<chip>* CAN peripheral devices.
-
-**Usage Note**: When reading from the CAN driver multiple messages
-may be returned, depending on (1) the size the returned can
-messages, and (2) the size of the buffer provided to receive CAN
-messages. *Never assume that a single message will be returned*...
-if you do this, *you will lose CAN data* under conditions where
-your read buffer can hold more than one small message. Below is an
-example about how you should think of the CAN read operation:
-
-Quadrature Encoder Drivers
-==========================
-
-NuttX supports a low-level, two-part Quadrature Encoder driver.
-
-#. An "upper half", generic driver that provides the common
- Quadrature Encoder interface to application level code, and
-#. A "lower half", platform-specific driver that implements the
- low-level timer controls to implement the Quadrature Encoder
- functionality.
-
-Files supporting the Quadrature Encoder can be found in the
-following locations:
-
-- **Interface Definition**. The header file for the NuttX
- Quadrature Encoder driver reside at
- ``include/nuttx/sensors/qencoder.h``. This header file includes
- both the application level interface to the Quadrature Encoder
- driver as well as the interface between the "upper half" and
- "lower half" drivers. The Quadrature Encoder module uses a
- standard character driver framework.
-- **"Upper Half" Driver**. The generic, "upper half" Quadrature
- Encoder driver resides at ``drivers/sensors/qencoder.c``.
-- **"Lower Half" Drivers**. Platform-specific Quadrature Encoder
- drivers reside in
- ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>* directory
- for the specific processor *<architecture>* and for the
- specific *<chip>* Quadrature Encoder peripheral devices.
-
-Timer Drivers
-=============
-
-NuttX supports a low-level, two-part timer driver.
-
-#. An "upper half", generic driver that provides the common timer
- interface to application level code, and
-#. A "lower half", platform-specific driver that implements the
- low-level timer controls to implement the timer functionality.
-
-Files supporting the timer driver can be found in the following
-locations:
-
-- **Interface Definition**. The header file for the NuttX timer
- driver reside at ``include/nuttx/timers/timer.h``. This header
- file includes both the application level interface to the timer
- driver as well as the interface between the "upper half" and
- "lower half" drivers. The timer driver uses a standard
- character driver framework.
-- **"Upper Half" Driver**. The generic, "upper half" timer driver
- resides at ``drivers/timers/timer.c``.
-- **"Lower Half" Drivers**. Platform-specific timer drivers
- reside in ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>*
- directory for the specific processor *<architecture>* and for
- the specific *<chip>* timer peripheral devices.
-
-RTC Drivers
-===========
-
-NuttX supports a low-level, two-part RealTime Clock (RTC) driver.
-
-#. An "upper half", generic driver that provides the common RTC
- interface to application level code, and
-#. A "lower half", platform-specific driver that implements the
- low-level timer controls to implement the RTC functionality.
-
-Files supporting the RTC driver can be found in the following
-locations:
-
-- **Interface Definition**. The header file for the NuttX RTC
- driver reside at ``include/nuttx/timers/rtc.h``. This header
- file includes both the application level interface to the RTC
- driver as well as the interface between the "upper half" and
- "lower half" drivers. The RTC driver uses a standard character
- driver framework.
-- **"Upper Half" Driver**. The generic, "upper half" RTC driver
- resides at ``drivers/timers/rtc.c``.
-- **"Lower Half" Drivers**. Platform-specific RTC drivers reside
- in ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>*
- directory for the specific processor *<architecture>* and for
- the specific *<chip>* RTC peripheral devices.
-
-Watchdog Timer Drivers
-======================
-
-NuttX supports a low-level, two-part watchdog timer driver.
-
-#. An "upper half", generic driver that provides the common
- watchdog timer interface to application level code, and
-#. A "lower half", platform-specific driver that implements the
- low-level timer controls to implement the watchdog timer
- functionality.
-
-Files supporting the watchdog timer driver can be found in the
-following locations:
-
-- **Interface Definition**. The header file for the NuttX
- watchdog timer driver reside at
- ``include/nuttx/timers/watchdog.h``. This header file includes
- both the application level interface to the watchdog timer
- driver as well as the interface between the "upper half" and
- "lower half" drivers. The watchdog timer driver uses a standard
- character driver framework.
-- **"Upper Half" Driver**. The generic, "upper half" watchdog
- timer driver resides at ``drivers/timers/watchdog.c``.
-- **"Lower Half" Drivers**. Platform-specific watchdog timer
- drivers reside in
- ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>* directory
- for the specific processor *<architecture>* and for the
- specific *<chip>* watchdog timer peripheral devices.
-
-Keyboard/Keypad Drivers
-=======================
-
-**Keypads vs. Keyboards** Keyboards and keypads are really the
-same devices for NuttX. A keypad is thought of as simply a
-keyboard with fewer keys.
-
-**Special Commands**. In NuttX, a keyboard/keypad driver is simply
-a character driver that may have an (optional) encoding/decoding
-layer on the data returned by the character driver. A keyboard may
-return simple text data (alphabetic, numeric, and punctuation) or
-control characters (enter, control-C, etc.) when a key is pressed.
-We can think about this the "normal" keyboard data stream.
-However, in addition, most keyboards support actions that cannot
-be represented as text or control data. Such actions include
-things like cursor controls (home, up arrow, page down, etc.),
-editing functions (insert, delete, etc.), volume controls, (mute,
-volume up, etc.) and other special functions. In this case, some
-special encoding may be required to multiplex the normal text data
-and special command key press data streams.
-
-**Key Press and Release Events** Sometimes the time that a key is
-released is needed by applications as well. Thus, in addition to
-normal and special key press events, it may also be necessary to
-encode normal and special key release events.
-
-**Encoding/Decoding** Layer. An optional encoding/decoding layer
-can be used with the basic character driver to encode the keyboard
-events into the text data stream. The function interfaces that
-comprise that encoding/decoding layer are defined in the header
-file ``include/nuttx/input/kbd_code.h``. These functions provide
-an matched set of (a) driver encoding interfaces, and (b)
-application decoding interfaces.
-
-#. **Driver Encoding Interfaces**. These are interfaces used by
- the keyboard/keypad driver to encode keyboard events and data.
-
- - ``kbd_press()``
-
- **Function Prototype:**
-
- **Description:**
-
- **Input Parameters:**
-
- - ``ch``: The character to be added to the output stream.
- - ``stream``: An instance of ``lib_outstream_s`` to perform
- the actual low-level put operation.
-
- **Returned Value:**
-
- - ``kbd_release()``
-
- **Function Prototype:**
-
- **Description:**
-
- **Input Parameters:**
-
- - ``ch``: The character associated with the key that was
- released.
- - ``stream``: An instance of ``lib_outstream_s`` to perform
- the actual low-level put operation.
-
- **Returned Value:**
-
- - ``kbd_specpress()``
-
- **Function Prototype:**
-
- **Description:**
-
- **Input Parameters:**
-
- - ``keycode``: The command to be added to the output
- stream. The enumeration ``enum kbd_keycode_e keycode``
- identifies all commands known to the system.
- - ``stream``: An instance of ``lib_outstream_s`` to perform
- the actual low-level put operation.
-
- **Returned Value:**
-
- - ``kbd_specrel()``
-
- **Function Prototype:**
-
- **Description:**
-
- **Input Parameters:**
-
- - ``keycode``: The command to be added to the output
- stream. The enumeration ``enum kbd_keycode_e keycode``
- identifies all commands known to the system.
- - ``stream``: An instance of ``lib_outstream_s`` to perform
- the actual low-level put operation.
-
- **Returned Value:**
-
-#. **Application Decoding Interfaces**. These are user interfaces
- to decode the values returned by the keyboard/keypad driver.
-
- - ``kbd_decode()``
-
- **Function Prototype:**
-
- **Description:**
-
- **Input Parameters:**
-
- - ``stream``: An instance of ``lib_instream_s`` to perform
- the actual low-level get operation.
- - ``pch``: The location to save the returned value. This
- may be either a normal, character code or a special
- command (i.e., a value from ``enum kbd_getstate_s``.
- - ``state``: A user provided buffer to support parsing.
- This structure should be cleared the first time that
- ``kbd_decode()`` is called.
-
- **Returned Value:**
-
- - ``KBD_PRESS`` (0)**: Indicates the successful receipt
- of normal, keyboard data. This corresponds to a keypress
- event. The returned value in ``pch`` is a simple byte of
- text or control data.
- - ``KBD_RELEASE`` (1)**: Indicates a key release event.
- The returned value in ``pch`` is the byte of text or
- control data corresponding to the released key.
- - ``KBD_SPECPRESS`` (2)**: Indicates the successful
- receipt of a special keyboard command. The returned value
- in ``pch`` is a value from ``enum kbd_getstate_s``.
- - ``KBD_SPECREL`` (3)**: Indicates a special command key
- release event. The returned value in ``pch`` is a value
- from ``enum kbd_getstate_s``.
- - ``KBD_ERROR`` (``EOF``)**: An error has getting the
- next character (reported by the ``stream``). Normally
- indicates the end of file.
-
-**I/O Streams**. Notice the use of the abstract I/O streams in
-these interfaces. These stream interfaces are defined in
-``include/nuttx/streams.h``.
-
-Block Device Drivers
-********************
-
-Block device drivers have these properties:
-
-- ``include/nuttx/fs/fs.h``. All structures and APIs needed
- to work with block drivers are provided in this header file.
-
-- ``struct block_operations``. Each block device driver must
- implement an instance of ``struct block_operations``. That
- structure defines a call table with the following methods:
-
-- ``int register_blockdriver(const char *path, const struct block_operations *bops, mode_t mode, void *priv);``.
- Each block driver registers itself by calling
- ``register_blockdriver()``, passing it the ``path`` where it
- will appear in the `pseudo-file-system <#NxFileSystem>`__ and
- it's initialized instance of ``struct block_operations``.
-
-- **User Access**. Users do not normally access block drivers
- directly, rather, they access block drivers indirectly through
- the ``mount()`` API. The ``mount()`` API binds a block driver
- instance with a file system and with a mountpoint. Then the
- user may use the block driver to access the file system on the
- underlying media. *Example*: See the ``cmd_mount()``
- implementation in ``apps/nshlib/nsh_fscmds.c``.
-
-- **Accessing a Character Driver as a Block Device**. See the
- loop device at ``drivers/loop.c``. *Example*: See the
- ``cmd_losetup()`` implementation in
- ``apps/nshlib/nsh_fscmds.c``.
-
-- **Accessing a Block Driver as Character Device**. See the
- Block-to-Character (BCH) conversion logic in ``drivers/bch/``.
- *Example*: See the ``cmd_dd()`` implementation in
- ``apps/nshlib/nsh_ddcmd.c``.
-
-- **Examples**. ``drivers/loop.c``,
- ``drivers/mmcsd/mmcsd_spi.c``, ``drivers/ramdisk.c``, etc.
-
-Specialized Device Drivers
-**************************
-
-All device drivers that are accessible to application logic are
-either: (1) Character device drivers that can be accessed via the
-standard driver operations (``open()``, ``close()``, ``read()``,
-``write()``, etc.), or (2) block drivers that can be accessing
-only as part of mounting a file system or other special use cases
-as described in the preceding paragraph.
-
-In addition to this, there are also specialized "drivers" that can
-be used only within the OS logic itself and are not accessible to
-application logic. These specialized drivers are discussed in the
-following paragraphs.
-
-Ethernet Device Drivers
-=======================
-
-- ``include/nuttx/net/netdev.h``. All structures and APIs
- needed to work with Ethernet drivers are provided in this
- header file. The structure ``struct net_driver_s`` defines the
- interface and is passed to the network via
- ``netdev_register()``.
-
-- ``int netdev_register(FAR struct net_driver_s *dev, enum net_lltype_e lltype);``.
- Each Ethernet driver registers itself by calling
- ``netdev_register()``.
-
-- **Examples**: ``drivers/net/dm90x0.c``,
- ``arch/drivers/arm/src/c5471/c5471_ethernet.c``,
- ``arch/z80/src/ez80/ez80_emac.c``, etc.
-
-SPI Device Drivers
-==================
-
-- ``include/nuttx/spi/spi.h``. All structures and APIs needed
- to work with SPI drivers are provided in this header file.
-
-- ``struct spi_ops_s``. Each SPI device driver must implement
- an instance of ``struct spi_ops_s``. That structure defines a
- call table with the following methods:
-
-- **Binding SPI Drivers**. SPI drivers are not normally directly
- accessed by user code, but are usually bound to another, higher
- level device driver. See for example,
- ``int mmcsd_spislotinitialize(int minor, int slotno, FAR struct spi_dev_s *spi)``
- in ``drivers/mmcsd/mmcsd_spi.c``. In general, the binding
- sequence is:
-
- #. Get an instance of ``struct spi_dev_s`` from the
- hardware-specific SPI device driver, and
- #. Provide that instance to the initialization method of the
- higher level device driver.
-
-- **Examples**: ``drivers/loop.c``,
- ``drivers/mmcsd/mmcsd_spi.c``, ``drivers/ramdisk.c``, etc.
-
-I2C Device Drivers
-==================
-
-- ``include/nuttx/i2c/i2c.h``. All structures and APIs needed
- to work with I2C drivers are provided in this header file.
-
-- ``struct i2c_ops_s``. Each I2C device driver must implement
- an instance of ``struct i2c_ops_s``. That structure defines a
- call table with the following methods:
-
-- **Binding I2C Drivers**. I2C drivers are not normally directly
- accessed by user code, but are usually bound to another, higher
- level device driver. In general, the binding sequence is:
-
- #. Get an instance of ``struct i2c_master_s`` from the
- hardware-specific I2C device driver, and
- #. Provide that instance to the initialization method of the
- higher level device driver.
-
-- **Examples**: ``arch/z80/src/ez80/ez80_i2c.c``,
- ``arch/z80/src/z8/z8_i2c.c``, etc.
-
-Frame Buffer Drivers
-====================
-
-- ``include/nuttx/video/fb.h``. All structures and APIs
- needed to work with frame buffer drivers are provided in this
- header file.
-
-- ``struct fb_vtable_s``. Each frame buffer device driver
- must implement an instance of ``struct fb_vtable_s``. That
- structure defines a call table with the following methods:
-
- Get information about the video controller configuration and
- the configuration of each color plane.
-
- The following are provided only if the video hardware supports
- RGB color mapping:
-
- The following are provided only if the video hardware supports
- a hardware cursor:
-
-- **Binding Frame Buffer Drivers**. Frame buffer drivers are not
- normally directly accessed by user code, but are usually bound
- to another, higher level device driver. In general, the binding
- sequence is:
-
- #. Get an instance of ``struct fb_vtable_s`` from the
- hardware-specific frame buffer device driver, and
- #. Provide that instance to the initialization method of the
- higher level device driver.
-
-- **Examples**: ``arch/sim/src/up_framebuffer.c``. See also the
- usage of the frame buffer driver in the ``graphics/``
- directory.
-
-LCD Drivers
-===========
-
-- ``include/nuttx/lcd/lcd.h``. Structures and APIs needed to
- work with LCD drivers are provided in this header file. This
- header file also depends on some of the same definitions used
- for the frame buffer driver as provided in
- ``include/nuttx/video/fb.h``.
-
-- ``struct lcd_dev_s``. Each LCD device driver must implement
- an instance of ``struct lcd_dev_s``. That structure defines a
- call table with the following methods:
-
- Get information about the LCD video controller configuration
- and the configuration of each LCD color plane.
-
- The following are provided only if the video hardware supports
- RGB color mapping:
-
- The following are provided only if the video hardware supports
- a hardware cursor:
-
- Get the LCD panel power status (0: full off -
- ``CONFIG_LCD_MAXPOWER``: full on). On backlit LCDs, this
- setting may correspond to the backlight setting.
-
- Enable/disable LCD panel power (0: full off -
- ``CONFIG_LCD_MAXPOWER``: full on). On backlit LCDs, this
- setting may correspond to the backlight setting.
-
- Get the current contrast setting (0-CONFIG_LCD_MAXCONTRAST) \*/
-
- Set LCD panel contrast (0-CONFIG_LCD_MAXCONTRAST)
-
-- **Binding LCD Drivers**. LCD drivers are not normally directly
- accessed by user code, but are usually bound to another, higher
- level device driver. In general, the binding sequence is:
-
- #. Get an instance of ``struct lcd_dev_s`` from the
- hardware-specific LCD device driver, and
- #. Provide that instance to the initialization method of the
- higher level device driver.
-
-- **Examples**: ``drivers/lcd/p14201.c``,
- ``boards/arm/sam34/sam3u-ek/src/up_lcd.c.`` See also the usage
- of the LCD driver in the ``graphics/`` directory.
-
-Memory Technology Device Drivers
-================================
-
-- ``include/nuttx/mtd/mtd.h``. All structures and APIs needed
- to work with MTD drivers are provided in this header file.
-
-- ``struct mtd_dev_s``. Each MTD device driver must implement
- an instance of ``struct mtd_dev_s``. That structure defines a
- call table with the following methods:
-
- Erase the specified erase blocks (units are erase blocks):
-
- Read/write from the specified read/write blocks:
-
- Some devices may support byte oriented reads (optional). Most
- MTD devices are inherently block oriented so byte-oriented
- accesses are not supported. It is recommended that low-level
- drivers not support read() if it requires buffering.
-
- Some devices may also support byte oriented writes (optional).
- Most MTD devices are inherently block oriented so byte-oriented
- accesses are not supported. It is recommended that low-level
- drivers not support read() if it requires buffering. This
- interface is only available if ``CONFIG_MTD_BYTE_WRITE`` is
- defined.
-
- Support other, less frequently used commands:
-
- - ``MTDIOC_GEOMETRY``: Get MTD geometry
- - ``MTDIOC_XIPBASE:``: Convert block to physical address for
- eXecute-In-Place
- - ``MTDIOC_BULKERASE``: Erase the entire device
-
- is provided via a single ``ioctl`` method (see
- ``include/nuttx/fs/ioctl.h``):
-
-- **Binding MTD Drivers**. MTD drivers are not normally directly
- accessed by user code, but are usually bound to another, higher
- level device driver. In general, the binding sequence is:
-
- #. Get an instance of ``struct mtd_dev_s`` from the
- hardware-specific MTD device driver, and
- #. Provide that instance to the initialization method of the
- higher level device driver.
-
-- **Examples**: ``drivers/mtd/m25px.c`` and ``drivers/mtd/ftl.c``
-
-SDIO Device Drivers
-===================
-
-- ``include/nuttx/sdio.h``. All structures and APIs needed to
- work with SDIO drivers are provided in this header file.
-
-- ``struct sdio_dev_s``. Each SDIO device driver must
- implement an instance of ``struct sdio_dev_s``. That structure
- defines a call table with the following methods:
-
- Mutual exclusion:
-
- Initialization/setup:
-
- Command/Status/Data Transfer:
-
- Event/Callback support:
-
- DMA support:
-
-- **Binding SDIO Drivers**. SDIO drivers are not normally
- directly accessed by user code, but are usually bound to
- another, higher level device driver. In general, the binding
- sequence is:
-
- #. Get an instance of ``struct sdio_dev_s`` from the
- hardware-specific SDIO device driver, and
- #. Provide that instance to the initialization method of the
- higher level device driver.
-
-- **Examples**: ``arch/arm/src/stm32/stm32_sdio.c`` and
- ``drivers/mmcsd/mmcsd_sdio.c``
-
-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`` and
- ``struct usbhost_connection_s``. Each USB host controller
- driver must implement an instance of
- ``struct usbhost_driver_s`` and
- ``struct usbhost_connection_s``: ``struct usbhost_driver_s``
- provides the interface between the USB host driver and the USB
- class driver; ``struct usbhost_connection_s`` provides the
- interface between the USB host driver and platform-specific
- connection management and device enumeration logic. These
- structures are defined in ``include/nuttx/usb/usbhost.h``.
-
- **Examples**: ``arch/arm/src/lpc17xx_40xx/lpc17_40_usbhost.c``,
- ``arch/arm/src/stm32/stm32_otgfshost.c``,
- ``arch/arm/src/sama5/sam_ohci.c``, and
- ``arch/arm/src/sama5/sam_ehci.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_connection_s *drvr, FAR const bool *connected);``
-
- Wait for a device to be connected or disconnected.
-
- - ``int (*enumerate)(FAR struct usbhost_connection_s *drvr, int rhpndx);``
-
- Enumerate the device connected to a root hub port. 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:
-
- #. 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 the device that it supports is connected.
-
- **Examples**: The function ``usbhost_msc_initialize()`` in
- the file ``drivers/usbhost/usbhost_storage.c``
-
- #. 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
- ``boards/arm/lpc17xx_40xx/olimex-lpc1766stk/src/lpc17_40_appinit.c``.
-
- #. 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``.
-
-USB Device-Side Drivers
-=======================
-
-- ``include/nuttx/usb/usbdev.h``. 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 with the NuttX USB device driver trace capability. That
- USB trace capability is detailed in `separate
- document <UsbTrace.html>`__.
-
-- ``struct usbdev_s``. Each USB device controller driver must
- implement an instance of ``struct usbdev_s``. This structure is
- defined in ``include/nuttx/usb/usbdev.h``.
-
- **Examples**: ``arch/arm/src/dm320/dm320_usbdev.c``,
- ``arch/arm/src/lpc17xx_40xx/lpc17_40_usbdev.c``,
- ``arch/arm/src/lpc214x/lpc214x_usbdev.c``,
- ``arch/arm/src/lpc313x/lpc313x_usbdev.c``, and
- ``arch/arm/src/stm32/stm32_usbdev.c``.
-
-- ``struct usbdevclass_driver_s``. Each USB device class
- driver must implement an instance of
- ``struct usbdevclass_driver_s``. This structure is also defined
- in ``include/nuttx/usb/usbdev.h``.
-
- **Examples**: ``drivers/usbdev/pl2303.c`` and
- ``drivers/usbdev/usbmsc.c``
-
-- **Binding USB Device-Side Drivers**. USB device-side controller
- drivers are not normally directly accessed by user code, but
- are usually bound to another, higher level USB device class
- driver. The class driver is then configured to export the USB
- device functionality. In general, the binding sequence is:
-
- #. Each USB device class driver includes an initialization
- entry point that is called from the application at
- initialization time.
-
- **Examples**: The function ``usbdev_serialinitialize()`` in
- the file ``drivers/usbdev/pl2303.c`` and the function
- in the file ``drivers/usbdev/usbmsc.c``
-
- #. These initialization functions called the driver API,
- ``usbdev_register()``. This driver function will *bind* the
- USB class driver to the USB device controller driver,
- completing the initialization.
+NuttX supports a variety of device drivers, which can be broadly
+divided in three classes:
+
+.. toctree::
+ :maxdepth: 1
+
+ character/index.rst
+ block/index.rst
+ special/index.rst
+
+.. note::
+ Device driver support depends on the *in-memory*, *pseudo*
+ file system that is enabled by default.
+
+Lower-half and upper-half
+=========================
+
+Drivers in NuttX generally work in two distinct layers:
+
+ * An *upper half* which registers itself to NuttX using
+ a call such as :c:func:`register_driver` or
+ :c:func:`register_blockdriver` and implements the corresponding
+ high-level interface (`read`, `write`, `close`, etc.).
+ implements the interface. This *upper half* calls into
+ the *lower half* via callbacks.
+ * A "lower half" which is typically hardware-specific. This is
+ usually implemented at the architecture or board level.
diff --git a/Documentation/components/drivers/special/ethernet.rst b/Documentation/components/drivers/special/ethernet.rst
new file mode 100644
index 0000000..a8f371a
--- /dev/null
+++ b/Documentation/components/drivers/special/ethernet.rst
@@ -0,0 +1,17 @@
+=======================
+Ethernet Device Drivers
+=======================
+
+- ``include/nuttx/net/netdev.h``. All structures and APIs
+ needed to work with Ethernet drivers are provided in this
+ header file. The structure ``struct net_driver_s`` defines the
+ interface and is passed to the network via
+ ``netdev_register()``.
+
+- ``int netdev_register(FAR struct net_driver_s *dev, enum net_lltype_e lltype);``.
+ Each Ethernet driver registers itself by calling
+ ``netdev_register()``.
+
+- **Examples**: ``drivers/net/dm90x0.c``,
+ ``arch/drivers/arm/src/c5471/c5471_ethernet.c``,
+ ``arch/z80/src/ez80/ez80_emac.c``, etc.
diff --git a/Documentation/components/drivers/special/framebuffer.rst b/Documentation/components/drivers/special/framebuffer.rst
new file mode 100644
index 0000000..aefa7d1
--- /dev/null
+++ b/Documentation/components/drivers/special/framebuffer.rst
@@ -0,0 +1,34 @@
+====================
+Frame Buffer Drivers
+====================
+
+- ``include/nuttx/video/fb.h``. All structures and APIs
+ needed to work with frame buffer drivers are provided in this
+ header file.
+
+- ``struct fb_vtable_s``. Each frame buffer device driver
+ must implement an instance of ``struct fb_vtable_s``. That
+ structure defines a call table with the following methods:
+
+ Get information about the video controller configuration and
+ the configuration of each color plane.
+
+ The following are provided only if the video hardware supports
+ RGB color mapping:
+
+ The following are provided only if the video hardware supports
+ a hardware cursor:
+
+- **Binding Frame Buffer Drivers**. Frame buffer drivers are not
+ normally directly accessed by user code, but are usually bound
+ to another, higher level device driver. In general, the binding
+ sequence is:
+
+ #. Get an instance of ``struct fb_vtable_s`` from the
+ hardware-specific frame buffer device driver, and
+ #. Provide that instance to the initialization method of the
+ higher level device driver.
+
+- **Examples**: ``arch/sim/src/up_framebuffer.c``. See also the
+ usage of the frame buffer driver in the ``graphics/``
+ directory.
diff --git a/Documentation/components/drivers/special/i2c.rst b/Documentation/components/drivers/special/i2c.rst
new file mode 100644
index 0000000..a284468
--- /dev/null
+++ b/Documentation/components/drivers/special/i2c.rst
@@ -0,0 +1,22 @@
+==================
+I2C Device Drivers
+==================
+
+- ``include/nuttx/i2c/i2c.h``. All structures and APIs needed
+ to work with I2C drivers are provided in this header file.
+
+- ``struct i2c_ops_s``. Each I2C device driver must implement
+ an instance of ``struct i2c_ops_s``. That structure defines a
+ call table with the following methods:
+
+- **Binding I2C Drivers**. I2C drivers are not normally directly
+ accessed by user code, but are usually bound to another, higher
+ level device driver. In general, the binding sequence is:
+
+ #. Get an instance of ``struct i2c_master_s`` from the
+ hardware-specific I2C device driver, and
+ #. Provide that instance to the initialization method of the
+ higher level device driver.
+
+- **Examples**: ``arch/z80/src/ez80/ez80_i2c.c``,
+ ``arch/z80/src/z8/z8_i2c.c``, etc.
diff --git a/Documentation/components/drivers/special/index.rst b/Documentation/components/drivers/special/index.rst
new file mode 100644
index 0000000..1e8d445
--- /dev/null
+++ b/Documentation/components/drivers/special/index.rst
@@ -0,0 +1,34 @@
+==========================
+Specialized Device Drivers
+==========================
+
+All device drivers that are accessible to application logic are
+either: (1) Character device drivers that can be accessed via the
+standard driver operations (``open()``, ``close()``, ``read()``,
+``write()``, etc.), or (2) block drivers that can be accessing
+only as part of mounting a file system or other special use cases
+as described in the preceding paragraph.
+
+In addition to this, there are also specialized "drivers" that can
+be used only within the OS logic itself and are not accessible to
+application logic. These specialized drivers are discussed in the
+following section.
+
+.. note::
+ While special drivers are *internal*, in some cases there are also
+ character/block drivers that sit on top of these special drivers
+ and thus expose them to applications.
+
+.. toctree::
+ :caption: Supported Drivers
+
+ spi.rst
+ i2c.rst
+ ethernet.rst
+ framebuffer.rst
+ lcd.rst
+ mtd.rst
+ sdio.rst
+ usbhost.rst
+ usbdev.rst
+
diff --git a/Documentation/components/drivers/special/lcd.rst b/Documentation/components/drivers/special/lcd.rst
new file mode 100644
index 0000000..63da835
--- /dev/null
+++ b/Documentation/components/drivers/special/lcd.rst
@@ -0,0 +1,47 @@
+===========
+LCD Drivers
+===========
+
+- ``include/nuttx/lcd/lcd.h``. Structures and APIs needed to
+ work with LCD drivers are provided in this header file. This
+ header file also depends on some of the same definitions used
+ for the frame buffer driver as provided in
+ ``include/nuttx/video/fb.h``.
+
+- ``struct lcd_dev_s``. Each LCD device driver must implement
+ an instance of ``struct lcd_dev_s``. That structure defines a
+ call table with the following methods:
+
+ Get information about the LCD video controller configuration
+ and the configuration of each LCD color plane.
+
+ The following are provided only if the video hardware supports
+ RGB color mapping:
+
+ The following are provided only if the video hardware supports
+ a hardware cursor:
+
+ Get the LCD panel power status (0: full off -
+ ``CONFIG_LCD_MAXPOWER``: full on). On backlit LCDs, this
+ setting may correspond to the backlight setting.
+
+ Enable/disable LCD panel power (0: full off -
+ ``CONFIG_LCD_MAXPOWER``: full on). On backlit LCDs, this
+ setting may correspond to the backlight setting.
+
+ Get the current contrast setting (0-CONFIG_LCD_MAXCONTRAST) \*/
+
+ Set LCD panel contrast (0-CONFIG_LCD_MAXCONTRAST)
+
+- **Binding LCD Drivers**. LCD drivers are not normally directly
+ accessed by user code, but are usually bound to another, higher
+ level device driver. In general, the binding sequence is:
+
+ #. Get an instance of ``struct lcd_dev_s`` from the
+ hardware-specific LCD device driver, and
+ #. Provide that instance to the initialization method of the
+ higher level device driver.
+
+- **Examples**: ``drivers/lcd/p14201.c``,
+ ``boards/arm/sam34/sam3u-ek/src/up_lcd.c.`` See also the usage
+ of the LCD driver in the ``graphics/`` directory.
diff --git a/Documentation/components/drivers/special/mtd.rst b/Documentation/components/drivers/special/mtd.rst
new file mode 100644
index 0000000..5e6e556
--- /dev/null
+++ b/Documentation/components/drivers/special/mtd.rst
@@ -0,0 +1,47 @@
+================================
+Memory Technology Device Drivers
+================================
+
+- ``include/nuttx/mtd/mtd.h``. All structures and APIs needed
+ to work with MTD drivers are provided in this header file.
+
+- ``struct mtd_dev_s``. Each MTD device driver must implement
+ an instance of ``struct mtd_dev_s``. That structure defines a
+ call table with the following methods:
+
+ Erase the specified erase blocks (units are erase blocks):
+
+ Read/write from the specified read/write blocks:
+
+ Some devices may support byte oriented reads (optional). Most
+ MTD devices are inherently block oriented so byte-oriented
+ accesses are not supported. It is recommended that low-level
+ drivers not support read() if it requires buffering.
+
+ Some devices may also support byte oriented writes (optional).
+ Most MTD devices are inherently block oriented so byte-oriented
+ accesses are not supported. It is recommended that low-level
+ drivers not support read() if it requires buffering. This
+ interface is only available if ``CONFIG_MTD_BYTE_WRITE`` is
+ defined.
+
+ Support other, less frequently used commands:
+
+ - ``MTDIOC_GEOMETRY``: Get MTD geometry
+ - ``MTDIOC_XIPBASE:``: Convert block to physical address for
+ eXecute-In-Place
+ - ``MTDIOC_BULKERASE``: Erase the entire device
+
+ is provided via a single ``ioctl`` method (see
+ ``include/nuttx/fs/ioctl.h``):
+
+- **Binding MTD Drivers**. MTD drivers are not normally directly
+ accessed by user code, but are usually bound to another, higher
+ level device driver. In general, the binding sequence is:
+
+ #. Get an instance of ``struct mtd_dev_s`` from the
+ hardware-specific MTD device driver, and
+ #. Provide that instance to the initialization method of the
+ higher level device driver.
+
+- **Examples**: ``drivers/mtd/m25px.c`` and ``drivers/mtd/ftl.c``
diff --git a/Documentation/components/drivers/special/sdio.rst b/Documentation/components/drivers/special/sdio.rst
new file mode 100644
index 0000000..d03f8ec
--- /dev/null
+++ b/Documentation/components/drivers/special/sdio.rst
@@ -0,0 +1,33 @@
+===================
+SDIO Device Drivers
+===================
+
+- ``include/nuttx/sdio.h``. All structures and APIs needed to
+ work with SDIO drivers are provided in this header file.
+
+- ``struct sdio_dev_s``. Each SDIO device driver must
+ implement an instance of ``struct sdio_dev_s``. That structure
+ defines a call table with the following methods:
+
+ Mutual exclusion:
+
+ Initialization/setup:
+
+ Command/Status/Data Transfer:
+
+ Event/Callback support:
+
+ DMA support:
+
+- **Binding SDIO Drivers**. SDIO drivers are not normally
+ directly accessed by user code, but are usually bound to
+ another, higher level device driver. In general, the binding
+ sequence is:
+
+ #. Get an instance of ``struct sdio_dev_s`` from the
+ hardware-specific SDIO device driver, and
+ #. Provide that instance to the initialization method of the
+ higher level device driver.
+
+- **Examples**: ``arch/arm/src/stm32/stm32_sdio.c`` and
+ ``drivers/mmcsd/mmcsd_sdio.c``
diff --git a/Documentation/components/drivers/special/spi.rst b/Documentation/components/drivers/special/spi.rst
new file mode 100644
index 0000000..55560ea
--- /dev/null
+++ b/Documentation/components/drivers/special/spi.rst
@@ -0,0 +1,25 @@
+==================
+SPI Device Drivers
+==================
+
+- ``include/nuttx/spi/spi.h``. All structures and APIs needed
+ to work with SPI drivers are provided in this header file.
+
+- ``struct spi_ops_s``. Each SPI device driver must implement
+ an instance of ``struct spi_ops_s``. That structure defines a
+ call table with the following methods:
+
+- **Binding SPI Drivers**. SPI drivers are not normally directly
+ accessed by user code, but are usually bound to another, higher
+ level device driver. See for example,
+ ``int mmcsd_spislotinitialize(int minor, int slotno, FAR struct spi_dev_s *spi)``
+ in ``drivers/mmcsd/mmcsd_spi.c``. In general, the binding
+ sequence is:
+
+ #. Get an instance of ``struct spi_dev_s`` from the
+ hardware-specific SPI device driver, and
+ #. Provide that instance to the initialization method of the
+ higher level device driver.
+
+- **Examples**: ``drivers/loop.c``,
+ ``drivers/mmcsd/mmcsd_spi.c``, ``drivers/ramdisk.c``, etc.
diff --git a/Documentation/components/drivers/special/usbdev.rst b/Documentation/components/drivers/special/usbdev.rst
new file mode 100644
index 0000000..23c0a6a
--- /dev/null
+++ b/Documentation/components/drivers/special/usbdev.rst
@@ -0,0 +1,50 @@
+=======================
+USB Device-Side Drivers
+=======================
+
+- ``include/nuttx/usb/usbdev.h``. 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 with the NuttX USB device driver trace capability. That
+ USB trace capability is detailed in `separate
+ document <UsbTrace.html>`__.
+
+- ``struct usbdev_s``. Each USB device controller driver must
+ implement an instance of ``struct usbdev_s``. This structure is
+ defined in ``include/nuttx/usb/usbdev.h``.
+
+ **Examples**: ``arch/arm/src/dm320/dm320_usbdev.c``,
+ ``arch/arm/src/lpc17xx_40xx/lpc17_40_usbdev.c``,
+ ``arch/arm/src/lpc214x/lpc214x_usbdev.c``,
+ ``arch/arm/src/lpc313x/lpc313x_usbdev.c``, and
+ ``arch/arm/src/stm32/stm32_usbdev.c``.
+
+- ``struct usbdevclass_driver_s``. Each USB device class
+ driver must implement an instance of
+ ``struct usbdevclass_driver_s``. This structure is also defined
+ in ``include/nuttx/usb/usbdev.h``.
+
+ **Examples**: ``drivers/usbdev/pl2303.c`` and
+ ``drivers/usbdev/usbmsc.c``
+
+- **Binding USB Device-Side Drivers**. USB device-side controller
+ drivers are not normally directly accessed by user code, but
+ are usually bound to another, higher level USB device class
+ driver. The class driver is then configured to export the USB
+ device functionality. In general, the binding sequence is:
+
+ #. Each USB device class driver includes an initialization
+ entry point that is called from the application at
+ initialization time.
+
+ **Examples**: The function ``usbdev_serialinitialize()`` in
+ the file ``drivers/usbdev/pl2303.c`` and the function
+ in the file ``drivers/usbdev/usbmsc.c``
+
+ #. These initialization functions called the driver API,
+ ``usbdev_register()``. This driver function will *bind* the
+ USB class driver to the USB device controller driver,
+ completing the initialization.
+
diff --git a/Documentation/components/drivers/special/usbhost.rst b/Documentation/components/drivers/special/usbhost.rst
new file mode 100644
index 0000000..7c91c1d
--- /dev/null
+++ b/Documentation/components/drivers/special/usbhost.rst
@@ -0,0 +1,108 @@
+=====================
+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`` and
+ ``struct usbhost_connection_s``. Each USB host controller
+ driver must implement an instance of
+ ``struct usbhost_driver_s`` and
+ ``struct usbhost_connection_s``: ``struct usbhost_driver_s``
+ provides the interface between the USB host driver and the USB
+ class driver; ``struct usbhost_connection_s`` provides the
+ interface between the USB host driver and platform-specific
+ connection management and device enumeration logic. These
+ structures are defined in ``include/nuttx/usb/usbhost.h``.
+
+ **Examples**: ``arch/arm/src/lpc17xx_40xx/lpc17_40_usbhost.c``,
+ ``arch/arm/src/stm32/stm32_otgfshost.c``,
+ ``arch/arm/src/sama5/sam_ohci.c``, and
+ ``arch/arm/src/sama5/sam_ehci.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_connection_s *drvr, FAR const bool *connected);``
+
+ Wait for a device to be connected or disconnected.
+
+ - ``int (*enumerate)(FAR struct usbhost_connection_s *drvr, int rhpndx);``
+
+ Enumerate the device connected to a root hub port. 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:
+
+ #. 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 the device that it supports is connected.
+
+ **Examples**: The function ``usbhost_msc_initialize()`` in
+ the file ``drivers/usbhost/usbhost_storage.c``
+
+ #. 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
+ ``boards/arm/lpc17xx_40xx/olimex-lpc1766stk/src/lpc17_40_appinit.c``.
+
+ #. 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``.