nuttx/nuttx-mirror
1
2
Fork 0
mirror of https://github.com/apache/nuttx.git synced 2025-01-13 07:28:38 +08:00
Code Issues Projects Releases Packages Wiki Activity Actions

documentation: split device drivers sections into individual documents

Browse source
This commit is contained in:
Matias N 2020-09-05 18:36:36 -03:00 committed by Alan Carvalho de Assis
parent 7549e2e9de
commit 44cee3f211
23 changed files with 985 additions and 936 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

41
Documentation/components/drivers/block/index.rst Normal file
View file

@ -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.

55
Documentation/components/drivers/character/analog.rst Normal file
View file

@ -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.

36
Documentation/components/drivers/character/can.rst Normal file
View file

@ -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:

64
Documentation/components/drivers/character/index.rst Normal file
View file

@ -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

143
Documentation/components/drivers/character/keypad.rst Normal file
View file

@ -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``.

34
Documentation/components/drivers/character/pwm.rst Normal file
View file

@ -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.

29
Documentation/components/drivers/character/quadrature.rst Normal file
View file

@ -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.

25
Documentation/components/drivers/character/rtc.rst Normal file
View file

@ -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.

29
Documentation/components/drivers/character/serial.rst Normal file
View file

@ -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.

18
Documentation/components/drivers/character/timer.rst Normal file
View file

@ -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.

38
Documentation/components/drivers/character/touchscreen.rst Normal file
View file

@ -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.

29
Documentation/components/drivers/character/watchdog.rst Normal file
View file

@ -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.

963
Documentation/components/drivers/index.rst
View file

@ -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.

17
Documentation/components/drivers/special/ethernet.rst Normal file
View file

@ -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.

34
Documentation/components/drivers/special/framebuffer.rst Normal file
View file

@ -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.

22
Documentation/components/drivers/special/i2c.rst Normal file
View file

@ -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.

34
Documentation/components/drivers/special/index.rst Normal file
View file

@ -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

47
Documentation/components/drivers/special/lcd.rst Normal file
View file

@ -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.

47
Documentation/components/drivers/special/mtd.rst Normal file
View file

@ -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``

33
Documentation/components/drivers/special/sdio.rst Normal file
View file

@ -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``

25
Documentation/components/drivers/special/spi.rst Normal file
View file

@ -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.

50
Documentation/components/drivers/special/usbdev.rst Normal file
View file

@ -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.

108
Documentation/components/drivers/special/usbhost.rst Normal file
View file

@ -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``.