diff options
| author | Gregory Nutt <gnutt@nuttx.org> | 2015-02-20 11:36:56 -0600 |
|---|---|---|
| committer | Gregory Nutt <gnutt@nuttx.org> | 2015-02-20 11:36:56 -0600 |
| commit | bc27c0d83fabb5cad5f3223678f0f3859690653c (patch) | |
| tree | 2843cbe7a4cbf69beaef008058b343f73e398cc5 | |
| parent | ed9901e15e1e0afe7482c199d67f84c75dab8007 (diff) | |
| download | nuttx-bc27c0d83fabb5cad5f3223678f0f3859690653c.tar.gz nuttx-bc27c0d83fabb5cad5f3223678f0f3859690653c.tar.bz2 nuttx-bc27c0d83fabb5cad5f3223678f0f3859690653c.zip | |
Porting Guide: Reorder some paragraphs for a clearer distinction of driver types
| -rw-r--r-- | nuttx/Documentation/NuttxPortingGuide.html | 1220 |
1 files changed, 626 insertions, 594 deletions
diff --git a/nuttx/Documentation/NuttxPortingGuide.html b/nuttx/Documentation/NuttxPortingGuide.html index ed6109f22..554bf098c 100644 --- a/nuttx/Documentation/NuttxPortingGuide.html +++ b/nuttx/Documentation/NuttxPortingGuide.html @@ -173,28 +173,30 @@ <a href="#DeviceDrivers">6.0 NuttX Device Drivers</a> <ul> <a href="#chardrivers">6.1 Character Device Drivers</a><br> + <ul> + <a href="#serialdrivers">6.1.1 Serial Device Drivers</a><br> + <a href="#tscdrivers">6.1.2 Touchscreen Device Drivers</a><br> + <a href="#analogdrivers">6.1.3 Analog (ADC/DAC) Drivers</a><br> + <a href="#pwmdrivers">6.1.4 PWM Drivers</a><br> + <a href="#candrivers">6.1.5 CAN Drivers</a><br> + <a href="#quadencoder">6.1.6 Quadrature Encoder Drivers</a><br> + <a href="#timerdriver">6.1.7 Timer Drivers</a><br> + <a href="#rtcriver">6.1.8 RTC Drivers</a><br> + <a href="#wdogdriver">6.1.9 Watchdog Timer Drivers</a><br> + <a href="#kbddriver">6.1.10 Keyboard/Keypad Drivers</a><br> + </ul> <a href="#blockdrivers">6.2 Block Device Drivers</a><br> <a href="#specdrivers">6.3 Specialized Device Drivers</a> <ul> <a href="#ethdrivers">6.3.1 Ethernet Device Drivers</a><br> <a href="#spidrivers">6.3.2 SPI Device Drivers</a><br> <a href="#i2cdrivers">6.3.3 I2C Device Drivers</a><br> - <a href="#serialdrivers">6.3.4 Serial Device Drivers</a><br> - <a href="#fbdrivers">6.3.5 Frame Buffer Drivers</a><br> - <a href="#lcddrivers">6.3.6 LCD Drivers</a><br> - <a href="#tscdrivers">6.3.7 Touchscreen Device Drivers</a><br> - <a href="#mtddrivers">6.3.8 Memory Technology Device Drivers</a><br> - <a href="#sdiodrivers">6.3.9 SDIO Device Drivers</a><br> - <a href="#usbhostdrivers">6.3.10 USB Host-Side Drivers</a><br> - <a href="#usbdevdrivers">6.3.11 USB Device-Side Drivers</a><br> - <a href="#analogdrivers">6.3.12 Analog (ADC/DAC) Drivers</a><br> - <a href="#pwmdrivers">6.3.13 PWM Drivers</a><br> - <a href="#candrivers">6.3.14 CAN Drivers</a><br> - <a href="#quadencoder">6.3.15 Quadrature Encoder Drivers</a><br> - <a href="#timerdriver">6.3.16 Timer Drivers</a><br> - <a href="#rtcriver">6.3.17 RTC Drivers</a><br> - <a href="#wdogdriver">6.3.18 Watchdog Timer Drivers</a><br> - <a href="#kbddriver">6.3.19 Keyboard/Keypad Drivers</a><br> + <a href="#fbdrivers">6.3.4 Frame Buffer Drivers</a><br> + <a href="#lcddrivers">6.3.5 LCD Drivers</a><br> + <a href="#mtddrivers">6.3.6 Memory Technology Device Drivers</a><br> + <a href="#sdiodrivers">6.3.7 SDIO Device Drivers</a><br> + <a href="#usbhostdrivers">6.3.8 USB Host-Side Drivers</a><br> + <a href="#usbdevdrivers">6.3.9 USB Device-Side Drivers</a><br> </ul> <a href="#pwrmgmt">6.4 Power Management</a> <ul> @@ -4227,12 +4229,607 @@ void board_led_off(int led); </li> <li> <p> + <b>Specialized Character Drivers</b>. + Within the common character driver framework, there are different specific varieties of <i>specialized</i> 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: + </p> + <ul> + <li> + Device-specific <code>ioctl()</code> commands used to performed specialized operations on the device. + These <code>ioctl()</code> will be documented in header files under <code>include/nuttx</code> that detail the specific device interface. + </li> + <li> + Specialized I/O formats. + Some devices will require that <code>read()</code> and/or <code>write()</code> 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 <code>include/nuttx</code> that detail the specific device interface. + The typical representation of the I/O format will be a C structure definition. + </li> + </ul> + <p> + The specialized character drivers support by NuttX are documented in the following paragraphs. + </p> + </li> + <li> + <p> <b>Examples</b>: <code>drivers/dev_null.c</code>, <code>drivers/fifo.c</code>, <code>drivers/serial.c</code>, etc. </p> </li> </ul> +<h3><a name="serialdrivers">6.1.1 Serial Device Drivers</a></h3> + +<ul> + <li> + <p> + <b><code>include/nuttx/serial/serial.h</code></b>. + All structures and APIs needed to work with serial drivers are provided in this header file. + </p> + </li> + <li> + <p> + <b><code>struct uart_ops_s</code></b>. + Each serial device driver must implement an instance of <code>struct uart_ops_s</code>. + That structure defines a call table with the following methods: + <ul> + <p><code>int setup(FAR struct uart_dev_s *dev);</code><br> + <code>void shutdown(FAR struct uart_dev_s *dev);</code><br> + <code>int attach(FAR struct uart_dev_s *dev);</code><br> + <code>void detach(FAR struct uart_dev_s *dev);</code><br> + <code>int ioctl(FAR struct file *filep, int cmd, unsigned long arg);</code><br> + <code>int receive(FAR struct uart_dev_s *dev, unsigned int *status);</code><br> + <code>void rxint(FAR struct uart_dev_s *dev, bool enable);</code><br> + <code>bool rxavailable(FAR struct uart_dev_s *dev);</code><br> + <code>#ifdef CONFIG_SERIAL_IFLOWCONTROL</code><br> + <code>bool rxflowcontrol(FAR struct uart_dev_s *dev, unsigned int nbuffered, bool upper);</code><br> + <code>#endif</code><br> + <code>void send(FAR struct uart_dev_s *dev, int ch);</code><br> + <code>void txint(FAR struct uart_dev_s *dev, bool enable);</code><br> + <code>bool txready(FAR struct uart_dev_s *dev);</code><br> + <code>bool txempty(FAR struct uart_dev_s *dev);</code></p> + </ul> + </p> + </li> + <li> + <p> + <b><code>int uart_register(FAR const char *path, FAR uart_dev_t *dev);</code></b>. + A serial driver may register itself by calling <code>uart_register()</code>, passing it the + <code>path</code> where it will appear in the <a href="#NxFileSystem">pseudo-file-system</a> and it's + initialized instance of <code>struct uart_ops_s</code>. + By convention, serial device drivers are registered at paths like <code>/dev/ttyS0</code>, <code>/dev/ttyS1</code>, etc. + See the <code>uart_register()</code> implementation in <code>drivers/serial.c</code>. + </p> + </li> + <li> + <p> + <b>User Access</b>. + Serial drivers are, ultimately, normal <a href="#chardrivers">character drivers</a> and are accessed as other character drivers. + </p> + </li> + <li> + <p> + <b>Examples</b>: + <code>arch/arm/src/chip/lm_serial.c</code>, <code>arch/arm/src/lpc214x/lpc214x_serial.c</code>, <code>arch/z16/src/z16f/z16f_serial.c</code>, etc. + </p> + </li> +</ul> + +<h3><a name="tscdrivers">6.1.1 Touchscreen Device Drivers</a></h3> + +<p> + NuttX supports a two-part touchscreen driver architecture. +</p> +<ol> + <li> + An "upper half", generic driver that provides the common touchscreen interface to application level code, and + </li> + <li> + A "lower half", platform-specific driver that implements the low-level touchscreen controls to implement the touchscreen functionality. + </li> +</ol> +<p> + Files supporting the touchscreen controller (TSC) driver can be found in the following locations: +</p> +<ul> + <li><b>Interface Definition</b>. + The header files for NuttX touchscreen drivers reside in the <code>include/nuttx/include/input</code> directory. + The interface between the touchscreen controller "upper half" and "lower half" drivers are <i>not</i> 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, <i>is</i> the same for each touchscreen driver and is described <code>include/nuttx/include/input/touchscreen.h</code>. + The touchscreen driver uses a standard character driver framework but read operations return specially formatted data. + </li> + <li><b>"Upper Half" Driver</b>. + The controller-specific, "upper half" touchscreen drivers reside in the directory <code>drivers/input</code>. + </li> + <li><b>"Lower Half" Drivers</b>. + Platform-specific touchscreen drivers reside in either: (1) The <code>arch/</code><i><architecture></i><code>/src/</code><i><chip></i> directory for the processor architectures that have build in touchscreen controllers or (2) the <code>configs/</code><i><board></i><code>/src/</code> directory for boards that use an external touchscreen controller chip. + </li> +</ul> + +<h3><a name="analogdrivers">6.1.2 Analog (ADC/DAC) Drivers</a></h3> +<p> + The NuttX analog drivers are split into two parts: +</p> +<ol> + <li> + An "upper half", generic driver that provides the common analog interface to application level code, and + </li> + <li> + A "lower half", platform-specific driver that implements the low-level controls to implement the analog functionality. + </li> +</ol> +<ul> + <li> + General header files for the NuttX analog drivers reside in <code>include/nuttx/analog/</code>. + 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. + </li> + <li> + Common analog logic and share-able analog drivers reside in the <code>drivers/analog/</code>. + </li> + <li> + Platform-specific drivers reside in <code>arch/</code><i><architecture></i><code>/src/</code><i><chip></i> directory for the specific processor <i><architecture></i> and for the specific <i><chip></i> analog peripheral devices. + </li> +</ul> + +<h4><a name="adcdrivers">6.1.3.1 ADC Drivers</a></h4> +<ul> + <li> + <code>include/nuttx/analog/adc.h</code>. + All structures and APIs needed to work with ADC drivers are provided in this header file. + This header file includes: + <ol> + <li> + Structures and interface descriptions needed to develop a low-level, + architecture-specific, ADC driver. + </li> + <li> + To register the ADC driver with a common ADC character driver. + </li> + <li> + Interfaces needed for interfacing user programs with the common ADC character driver. + </li> + </ol> + </li> + <li> + <code>drivers/analog/adc.c</code>. + The implementation of the common ADC character driver. + </li> +</ul> + +<h4><a name="dacdrivers">6.1.3.2 DAC Drivers</a></h4> +<ul> + <li> + <code>include/nuttx/analog/dac.h</code>. + All structures and APIs needed to work with DAC drivers are provided in this header file. + This header file includes: + <ol> + <li> + Structures and interface descriptions needed to develop a low-level, + architecture-specific, DAC driver. + </li> + <li> + To register the DAC driver with a common DAC character driver. + </li> + <li> + Interfaces needed for interfacing user programs with the common DAC character driver. + </li> + </ol> + </li> + <li> + <code>drivers/analog/dac.c</code>. + The implementation of the common DAC character driver. + </li> +</ul> + +<h3><a name="pwmdrivers">6.1.4 PWM Drivers</a></h3> +<p> + 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). +</p> +<p> + The NuttX PWM driver is split into two parts: +</p> +<ol> + <li> + An "upper half", generic driver that provides the common PWM interface to application level code, and + </li> + <li> + A "lower half", platform-specific driver that implements the low-level timer controls to implement the PWM functionality. + </li> +</ol> +<p> + Files supporting PWM can be found in the following locations: +</p> +<ul> + <li><b>Interface Definition</b>. + The header file for the NuttX PWM driver reside at <code>include/nuttx/pwm.h</code>. + 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. + </li> + <li><b>"Upper Half" Driver</b>. + The generic, "upper half" PWM driver resides at <code>drivers/pwm.c</code>. + </li> + <li><b>"Lower Half" Drivers</b>. + Platform-specific PWM drivers reside in <code>arch/</code><i><architecture></i><code>/src/</code><i><chip></i> directory for the specific processor <i><architecture></i> and for the specific <i><chip></i> PWM peripheral devices. + </li> +</ul> + +<h3><a name="candrivers">6.1.5 CAN Drivers</a></h3> +<p> + 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: +</p> +<ol> + <li> + An "upper half", generic driver that provides the common CAN interface to application level code, and + </li> + <li> + A "lower half", platform-specific driver that implements the low-level timer controls to implement the CAN functionality. + </li> +</ol> +<p> + Files supporting CAN can be found in the following locations: +</p> +<ul> + <li><b>Interface Definition</b>. + The header file for the NuttX CAN driver reside at <code>include/nuttx/can.h</code>. + 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. + </li> + <li><b>"Upper Half" Driver</b>. + The generic, "upper half" CAN driver resides at <code>drivers/can.c</code>. + </li> + <li><b>"Lower Half" Drivers</b>. + Platform-specific CAN drivers reside in <code>arch/</code><i><architecture></i><code>/src/</code><i><chip></i> directory for the specific processor <i><architecture></i> and for the specific <i><chip></i> CAN peripheral devices. + </li> +</ul> + +<h3><a name="quadencoder">6.1.6 Quadrature Encoder Drivers</a></h3> +<p> + NuttX supports a low-level, two-part Quadrature Encoder driver. +</p> +<ol> + <li> + An "upper half", generic driver that provides the common Quadrature Encoder interface to application level code, and + </li> + <li> + A "lower half", platform-specific driver that implements the low-level timer controls to implement the Quadrature Encoder functionality. + </li> +</ol> +<p> + Files supporting the Quadrature Encoder can be found in the following locations: +</p> +<ul> + <li><b>Interface Definition</b>. + The header file for the NuttX Quadrature Encoder driver reside at <code>include/nuttx/sensors/qencoder.h</code>. + 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. + </li> + <li><b>"Upper Half" Driver</b>. + The generic, "upper half" Quadrature Encoder driver resides at <code>drivers/sensors/qencoder.c</code>. + </li> + <li><b>"Lower Half" Drivers</b>. + Platform-specific Quadrature Encoder drivers reside in <code>arch/</code><i><architecture></i><code>/src/</code><i><chip></i> directory for the specific processor <i><architecture></i> and for the specific <i><chip></i> Quadrature Encoder peripheral devices. + </li> +</ul> + +<h3><a name="timerdriver">6.1.7 Timer Drivers</a></h3> +<p> + NuttX supports a low-level, two-part timer driver. +</p> +<ol> + <li> + An "upper half", generic driver that provides the common timer interface to application level code, and + </li> + <li> + A "lower half", platform-specific driver that implements the low-level timer controls to implement the timer functionality. + </li> +</ol> +<p> + Files supporting the timer driver can be found in the following locations: +</p> +<ul> + <li><b>Interface Definition</b>. + The header file for the NuttX timer driver reside at <code>include/nuttx/timer.h</code>. + 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. + </li> + <li><b>"Upper Half" Driver</b>. + The generic, "upper half" timer driver resides at <code>drivers/timers/timer.c</code>. + </li> + <li><b>"Lower Half" Drivers</b>. + Platform-specific timer drivers reside in <code>arch/</code><i><architecture></i><code>/src/</code><i><chip></i> directory for the specific processor <i><architecture></i> and for the specific <i><chip></i> timer peripheral devices. + </li> +</ul> + +<h3><a name="rtcriver">6.1.8 RTC Drivers</a></h3> +<p> + NuttX supports a low-level, two-part RealTime Clock (RTC) driver. +</p> +<ol> + <li> + An "upper half", generic driver that provides the common RTC interface to application level code, and + </li> + <li> + A "lower half", platform-specific driver that implements the low-level timer controls to implement the RTC functionality. + </li> +</ol> +<p> + Files supporting the RTC driver can be found in the following locations: +</p> +<ul> + <li><b>Interface Definition</b>. + The header file for the NuttX RTC driver reside at <code>include/nuttx/rtc.h</code>. + 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. + </li> + <li><b>"Upper Half" Driver</b>. + The generic, "upper half" RTC driver resides at <code>drivers/timers/rtc.c</code>. + </li> + <li><b>"Lower Half" Drivers</b>. + Platform-specific RTC drivers reside in <code>arch/</code><i><architecture></i><code>/src/</code><i><chip></i> directory for the specific processor <i><architecture></i> and for the specific <i><chip></i> RTC peripheral devices. + </li> +</ul> + +<h3><a name="wdogdriver">6.1.9 Watchdog Timer Drivers</a></h3> +<p> + NuttX supports a low-level, two-part watchdog timer driver. +</p> +<ol> + <li> + An "upper half", generic driver that provides the common watchdog timer interface to application level code, and + </li> + <li> + A "lower half", platform-specific driver that implements the low-level timer controls to implement the watchdog timer functionality. + </li> +</ol> +<p> + Files supporting the watchdog timer driver can be found in the following locations: +</p> +<ul> + <li><b>Interface Definition</b>. + The header file for the NuttX watchdog timer driver reside at <code>include/nuttx/watchdog.h</code>. + 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. + </li> + <li><b>"Upper Half" Driver</b>. + The generic, "upper half" watchdog timer driver resides at <code>drivers/timers/watchdog.c</code>. + </li> + <li><b>"Lower Half" Drivers</b>. + Platform-specific watchdog timer drivers reside in <code>arch/</code><i><architecture></i><code>/src/</code><i><chip></i> directory for the specific processor <i><architecture></i> and for the specific <i><chip></i> watchdog timer peripheral devices. + </li> +</ul> + +<h3><a name="kbddriver">6.1.10 Keyboard/Keypad Drivers</a></h3> +<p> + <b>Keypads vs. Keyboards</b> + Keyboards and keypads are really the same devices for NuttX. + A keypad is thought of as simply a keyboard with fewer keys. +</p> +<p> + <b>Special Commands</b>. + 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. +</p> +<p> + <b>Key Press and Release Events</b> + 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. +</p> +<p> + <b>Encoding/Decoding</b> Layer</b>. + 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 <code>include/nuttx/input/kbd_code.h</code>. + These functions provide an matched set of (a) driver encoding interfaces, and (b) application decoding interfaces. +</p> +<ol> + <li> + <p> + <b>Driver Encoding Interfaces</b>. + These are interfaces used by the keyboard/keypad driver to encode keyboard events and data. + </p> + <ul> + <li> + <p> + <b><code>kbd_press()</code></b> + </p> + <p><b>Function Prototype:</b></p> + <ul><pre> +#include <nuttx/streams.h> +#include <nuttx/input/kbd_codec.h> +void kbd_press(int ch, FAR struct lib_outstream_s *stream); +</pre></ul> + <p><b>Description:</b></p> + <ul> + Indicates a normal key press event. + Put one byte of normal keyboard data into the output stream. + </ul> + <p><b>Input Parameters:</b></p> + <ul> + <li> + <code>ch</code>: The character to be added to the output stream. + </li> + <li> + <code>stream</code>: An instance of <code>lib_outstream_s</code> to perform the actual low-level put operation. + </li> + </ul> + <p><b>Returned Value:</b></p> + <ul> + None. + </ul> + </li> + <li> + <p> + <b><code>kbd_release()</code></b> + </p> + <p><b>Function Prototype:</b></p> + <ul><pre> +#include <nuttx/streams.h> +#include <nuttx/input/kbd_codec.h> +void kbd_release(uint8_t ch, FAR struct lib_outstream_s *stream); +</pre></ul> + <p><b>Description:</b></p> + <ul> + Encode the release of a normal key. + </ul> + <p><b>Input Parameters:</b></p> + <ul> + <li> + <code>ch</code>: The character associated with the key that was released. + </li> + <li> + <code>stream</code>: An instance of <code>lib_outstream_s</code> to perform the actual low-level put operation. + </li> + </ul> + <p><b>Returned Value:</b></p> + <ul> + None. + </ul> + </li> + <li> + <p> + <b><code>kbd_specpress()</code></b> + </p> + <p><b>Function Prototype:</b></p> + <ul><pre> +#include <nuttx/streams.h> +#include <nuttx/input/kbd_codec.h> +void kbd_specpress(enum kbd_keycode_e keycode, FAR struct lib_outstream_s *stream); +</pre></ul> + <p><b>Description:</b></p> + <ul> + Denotes a special key press event. + Put one special keyboard command into the output stream. + </ul> + <p><b>Input Parameters:</b></p> + <ul> + <li> + <code>keycode</code>: The command to be added to the output stream. + The enumeration <code>enum kbd_keycode_e keycode</code> identifies all commands known to the system. + </li> + <li> + <code>stream</code>: An instance of <code>lib_outstream_s</code> to perform the actual low-level put operation. + </li> + </ul> + <p><b>Returned Value:</b></p> + <ul> + None. + </ul> + </li> + <li> + <p> + <b><code>kbd_specrel()</code></b> + </p> + <p><b>Function Prototype:</b></p> + <ul><pre> +#include <nuttx/streams.h> +#include <nuttx/input/kbd_codec.h> +void kbd_specrel(enum kbd_keycode_e keycode, FAR struct lib_outstream_s *stream); +</pre></ul> + <p><b>Description:</b></p> + <ul> + Denotes a special key release event. + Put one special keyboard command into the output stream. + </ul> + <p><b>Input Parameters:</b></p> + <ul> + <li> + <code>keycode</code>: The command to be added to the output stream. + The enumeration <code>enum kbd_keycode_e keycode</code> identifies all commands known to the system. + </li> + <li> + <code>stream</code>: An instance of <code>lib_outstream_s</code> to perform the actual low-level put operation. + </li> + </ul> + <p><b>Returned Value:</b></p> + <ul> + None. + </ul> + </li> + </ul> + </li> + <li> + <p> + <b>Application Decoding Interfaces</b>. + These are user interfaces to decode the values returned by the keyboard/keypad driver. + </p> + <ul> + <li> + <p> + <b><code>kbd_decode()</code></b> + </p> + <p><b>Function Prototype:</b></p> + <ul><pre> +#include <nuttx/streams.h> +#include <nuttx/input/kbd_codec.h> +int kbd_decode(FAR struct lib_instream_s *stream, FAR struct kbd_getstate_s *state, FAR uint8_t *pch); +</pre></ul> + <p><b>Description:</b></p> + <ul> + Get one byte of data or special command from the driver provided input buffer. + </ul> + <p><b>Input Parameters:</b></p> + <ul> + <li> + <code>stream</code>: An instance of <code>lib_instream_s</code> to perform the actual low-level get operation. + </li> + <li> + <code>pch</code>: The location to save the returned value. + This may be either a normal, character code or a special command (i.e., a value from <code>enum kbd_getstate_s</code>. + </li> + <li> + <code>state</code>: A user provided buffer to support parsing. + This structure should be cleared the first time that <code>kbd_decode()</code> is called. + </li> + </ul> + <p><b>Returned Value:</b></p> + <ul> + <li> + <b><code>KBD_PRESS</code> (0)</b>: + Indicates the successful receipt of normal, keyboard data. + This corresponds to a keypress event. + The returned value in <code>pch</code> is a simple byte of text or control data. + </li> + <li> + <b><code>KBD_RELEASE</code> (1)</b>: + Indicates a key release event. + The returned value in <code>pch</code> is the byte of text or control data corresponding to the released key. + </li> + <li> + <b><code>KBD_SPECPRESS</code> (2)</b>: + Indicates the successful receipt of a special keyboard command. + The returned value in <code>pch</code> is a value from <code>enum kbd_getstate_s</code>. + </li> + <li> + <b><code>KBD_SPECREL</code> (3)</b>: + Indicates a special command key release event. + The returned value in <code>pch</code> is a value from <code>enum kbd_getstate_s</code>. + </li> + <li> + <b><code>KBD_ERROR</code> (<code>EOF</code>)</b>: + An error has getting the next character (reported by the <code>stream</code>). + Normally indicates the end of file. + </li> + </ul> + </li> + </ul> + </li> +</ol> +<p> + <b>I/O Streams</b>. + Notice the use of the abstract I/O streams in these interfaces. + These stream interfaces are defined in <code>include/nuttx/streams.h</code>. +</p> + <h2><a name="blockdrivers">6.2 Block Device Drivers</a></h2> <p> @@ -4302,6 +4899,13 @@ void board_led_off(int led); <h2><a name="specdrivers">6.3 Specialized Device Drivers</a></h2> +<p> + All device drivers that are accessible to application logic are either: (1) Character device drivers that can be accessed via the standard driver operations (<code>open()</code>, <code>close()</code>, <code>read()</code>, <code>write()</code>, 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. +</p> +<p> + 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. +</p> + <h3><a name="ethdrivers">6.3.1 Ethernet Device Drivers</a></h3> <ul> @@ -4419,64 +5023,7 @@ void board_led_off(int led); </li> </ul> -<h3><a name="serialdrivers">6.3.4 Serial Device Drivers</a></h3> - -<ul> - <li> - <p> - <b><code>include/nuttx/serial/serial.h</code></b>. - All structures and APIs needed to work with serial drivers are provided in this header file. - </p> - </li> - <li> - <p> - <b><code>struct uart_ops_s</code></b>. - Each serial device driver must implement an instance of <code>struct uart_ops_s</code>. - That structure defines a call table with the following methods: - <ul> - <p><code>int setup(FAR struct uart_dev_s *dev);</code><br> - <code>void shutdown(FAR struct uart_dev_s *dev);</code><br> - <code>int attach(FAR struct uart_dev_s *dev);</code><br> - <code>void detach(FAR struct uart_dev_s *dev);</code><br> - <code>int ioctl(FAR struct file *filep, int cmd, unsigned long arg);</code><br> - <code>int receive(FAR struct uart_dev_s *dev, unsigned int *status);</code><br> - <code>void rxint(FAR struct uart_dev_s *dev, bool enable);</code><br> - <code>bool rxavailable(FAR struct uart_dev_s *dev);</code><br> - <code>#ifdef CONFIG_SERIAL_IFLOWCONTROL</code><br> - <code>bool rxflowcontrol(FAR struct uart_dev_s *dev, unsigned int nbuffered, bool upper);</code><br> - <code>#endif</code><br> - <code>void send(FAR struct uart_dev_s *dev, int ch);</code><br> - <code>void txint(FAR struct uart_dev_s *dev, bool enable);</code><br> - <code>bool txready(FAR struct uart_dev_s *dev);</code><br> - <code>bool txempty(FAR struct uart_dev_s *dev);</code></p> - </ul> - </p> - </li> - <li> - <p> - <b><code>int uart_register(FAR const char *path, FAR uart_dev_t *dev);</code></b>. - A serial driver may register itself by calling <code>uart_register()</code>, passing it the - <code>path</code> where it will appear in the <a href="#NxFileSystem">pseudo-file-system</a> and it's - initialized instance of <code>struct uart_ops_s</code>. - By convention, serial device drivers are registered at paths like <code>/dev/ttyS0</code>, <code>/dev/ttyS1</code>, etc. - See the <code>uart_register()</code> implementation in <code>drivers/serial.c</code>. - </p> - </li> - <li> - <p> - <b>User Access</b>. - Serial drivers are, ultimately, normal <a href="#chardrivers">character drivers</a> and are accessed as other character drivers. - </p> - </li> - <li> - <p> - <b>Examples</b>: - <code>arch/arm/src/chip/lm_serial.c</code>, <code>arch/arm/src/lpc214x/lpc214x_serial.c</code>, <code>arch/z16/src/z16f/z16f_serial.c</code>, etc. - </p> - </li> -</ul> - -<h3><a name="fbdrivers">6.3.5 Frame Buffer Drivers</a></h3> +<h3><a name="fbdrivers">6.3.4 Frame Buffer Drivers</a></h3> <ul> <li> @@ -4536,7 +5083,7 @@ void board_led_off(int led); </li> </ul> -<h3><a name="lcddrivers">6.3.6 LCD Drivers</a></h3> +<h3><a name="lcddrivers">6.3.5 LCD Drivers</a></h3> <ul> <li> @@ -4637,39 +5184,7 @@ void board_led_off(int led); </li> </ul> -<h3><a name="tscdrivers">6.3.7 Touchscreen Device Drivers</a></h3> - -<p> - NuttX supports a two-part touchscreen driver architecture. -</p> -<ol> - <li> - An "upper half", generic driver that provides the common touchscreen interface to application level code, and - </li> - <li> - A "lower half", platform-specific driver that implements the low-level touchscreen controls to implement the touchscreen functionality. - </li> -</ol> -<p> - Files supporting the touchscreen controller (TSC) driver can be found in the following locations: -</p> -<ul> - <li><b>Interface Definition</b>. - The header files for NuttX touchscreen drivers reside in the <code>include/nuttx/include/input</code> directory. - The interface between the touchscreen controller "upper half" and "lower half" drivers are <i>not</i> 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, <i>is</i> the same for each touchscreen driver and is described <code>include/nuttx/include/input/touchscreen.h</code>. - The touchscreen driver uses a standard character driver framework but read operations return specially formatted data. - </li> - <li><b>"Upper Half" Driver</b>. - The controller-specific, "upper half" touchscreen drivers reside in the directory <code>drivers/input</code>. - </li> - <li><b>"Lower Half" Drivers</b>. - Platform-specific touchscreen drivers reside in either: (1) The <code>arch/</code><i><architecture></i><code>/src/</code><i><chip></i> directory for the processor architectures that have build in touchscreen controllers or (2) the <code>configs/</code><i><board></i><code>/src/</code> directory for boards that use an external touchscreen controller chip. - </li> -</ul> - -<h3><a name="mtddrivers">6.3.8 Memory Technology Device Drivers</a></h3> +<h3><a name="mtddrivers">6.3.6 Memory Technology Device Drivers</a></h3> <ul> <li> @@ -4751,7 +5266,7 @@ void board_led_off(int led); </li> </ul> -<h3><a name="sdiodrivers">6.3.9 SDIO Device Drivers</a></h3> +<h3><a name="sdiodrivers">6.3.7 SDIO Device Drivers</a></h3> <ul> <li> @@ -4843,7 +5358,7 @@ void board_led_off(int led); </li> </ul> -<h3><a name="usbhostdrivers">6.3.10 USB Host-Side Drivers</a></h3> +<h3><a name="usbhostdrivers">6.3.8 USB Host-Side Drivers</a></h3> <ul> <li> @@ -4975,7 +5490,7 @@ void board_led_off(int led); </li> </ul> -<h3><a name="usbdevdrivers">6.3.11 USB Device-Side Drivers</a></h3> +<h3><a name="usbdevdrivers">6.3.9 USB Device-Side Drivers</a></h3> <ul> <li> @@ -5048,489 +5563,6 @@ void board_led_off(int led); </li> </ul> -<h3><a name="analogdrivers">6.3.12 Analog (ADC/DAC) Drivers</a></h3> -<p> - The NuttX analog drivers are split into two parts: -</p> -<ol> - <li> - An "upper half", generic driver that provides the common analog interface to application level code, and - </li> - <li> - A "lower half", platform-specific driver that implements the low-level controls to implement the analog functionality. - </li> -</ol> -<ul> - <li> - General header files for the NuttX analog drivers reside in <code>include/nuttx/analog/</code>. - 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. - </li> - <li> - Common analog logic and share-able analog drivers reside in the <code>drivers/analog/</code>. - </li> - <li> - Platform-specific drivers reside in <code>arch/</code><i><architecture></i><code>/src/</code><i><chip></i> directory for the specific processor <i><architecture></i> and for the specific <i><chip></i> analog peripheral devices. - </li> -</ul> - -<h4><a name="adcdrivers">6.3.12.1 ADC Drivers</a></h4> -<ul> - <li> - <code>include/nuttx/analog/adc.h</code>. - All structures and APIs needed to work with ADC drivers are provided in this header file. - This header file includes: - <ol> - <li> - Structures and interface descriptions needed to develop a low-level, - architecture-specific, ADC driver. - </li> - <li> - To register the ADC driver with a common ADC character driver. - </li> - <li> - Interfaces needed for interfacing user programs with the common ADC character driver. - </li> - </ol> - </li> - <li> - <code>drivers/analog/adc.c</code>. - The implementation of the common ADC character driver. - </li> -</ul> - -<h4><a name="dacdrivers">6.3.12.2 DAC Drivers</a></h4> -<ul> - <li> - <code>include/nuttx/analog/dac.h</code>. - All structures and APIs needed to work with DAC drivers are provided in this header file. - This header file includes: - <ol> - <li> - Structures and interface descriptions needed to develop a low-level, - architecture-specific, DAC driver. - </li> - <li> - To register the DAC driver with a common DAC character driver. - </li> - <li> - Interfaces needed for interfacing user programs with the common DAC character driver. - </li> - </ol> - </li> - <li> - <code>drivers/analog/dac.c</code>. - The implementation of the common DAC character driver. - </li> -</ul> - -<h3><a name="pwmdrivers">6.3.13 PWM Drivers</a></h3> -<p> - 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). -</p> -<p> - The NuttX PWM driver is split into two parts: -</p> -<ol> - <li> - An "upper half", generic driver that provides the common PWM interface to application level code, and - </li> - <li> - A "lower half", platform-specific driver that implements the low-level timer controls to implement the PWM functionality. - </li> -</ol> -<p> - Files supporting PWM can be found in the following locations: -</p> -<ul> - <li><b>Interface Definition</b>. - The header file for the NuttX PWM driver reside at <code>include/nuttx/pwm.h</code>. - 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. - </li> - <li><b>"Upper Half" Driver</b>. - The generic, "upper half" PWM driver resides at <code>drivers/pwm.c</code>. - </li> - <li><b>"Lower Half" Drivers</b>. - Platform-specific PWM drivers reside in <code>arch/</code><i><architecture></i><code>/src/</code><i><chip></i> directory for the specific processor <i><architecture></i> and for the specific <i><chip></i> PWM peripheral devices. - </li> -</ul> - -<h3><a name="candrivers">6.3.14 CAN Drivers</a></h3> -<p> - 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: -</p> -<ol> - <li> - An "upper half", generic driver that provides the common CAN interface to application level code, and - </li> - <li> - A "lower half", platform-specific driver that implements the low-level timer controls to implement the CAN functionality. - </li> -</ol> -<p> - Files supporting CAN can be found in the following locations: -</p> -<ul> - <li><b>Interface Definition</b>. - The header file for the NuttX CAN driver reside at <code>include/nuttx/can.h</code>. - 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. - </li> - <li><b>"Upper Half" Driver</b>. - The generic, "upper half" CAN driver resides at <code>drivers/can.c</code>. - </li> - <li><b>"Lower Half" Drivers</b>. - Platform-specific CAN drivers reside in <code>arch/</code><i><architecture></i><code>/src/</code><i><chip></i> directory for the specific processor <i><architecture></i> and for the specific <i><chip></i> CAN peripheral devices. - </li> -</ul> - -<h3><a name="quadencoder">6.3.15 Quadrature Encoder Drivers</a></h3> -<p> - NuttX supports a low-level, two-part Quadrature Encoder driver. -</p> -<ol> - <li> - An "upper half", generic driver that provides the common Quadrature Encoder interface to application level code, and - </li> - <li> - A "lower half", platform-specific driver that implements the low-level timer controls to implement the Quadrature Encoder functionality. - </li> -</ol> -<p> - Files supporting the Quadrature Encoder can be found in the following locations: -</p> -<ul> - <li><b>Interface Definition</b>. - The header file for the NuttX Quadrature Encoder driver reside at <code>include/nuttx/sensors/qencoder.h</code>. - 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. - </li> - <li><b>"Upper Half" Driver</b>. - The generic, "upper half" Quadrature Encoder driver resides at <code>drivers/sensors/qencoder.c</code>. - </li> - <li><b>"Lower Half" Drivers</b>. - Platform-specific Quadrature Encoder drivers reside in <code>arch/</code><i><architecture></i><code>/src/</code><i><chip></i> directory for the specific processor <i><architecture></i> and for the specific <i><chip></i> Quadrature Encoder peripheral devices. - </li> -</ul> - -<h3><a name="timerdriver">6.3.16 Timer Drivers</a></h3> -<p> - NuttX supports a low-level, two-part timer driver. -</p> -<ol> - <li> - An "upper half", generic driver that provides the common timer interface to application level code, and - </li> - <li> - A "lower half", platform-specific driver that implements the low-level timer controls to implement the timer functionality. - </li> -</ol> -<p> - Files supporting the timer driver can be found in the following locations: -</p> -<ul> - <li><b>Interface Definition</b>. - The header file for the NuttX timer driver reside at <code>include/nuttx/timer.h</code>. - 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. - </li> - <li><b>"Upper Half" Driver</b>. - The generic, "upper half" timer driver resides at <code>drivers/timers/timer.c</code>. - </li> - <li><b>"Lower Half" Drivers</b>. - Platform-specific timer drivers reside in <code>arch/</code><i><architecture></i><code>/src/</code><i><chip></i> directory for the specific processor <i><architecture></i> and for the specific <i><chip></i> timer peripheral devices. - </li> -</ul> - -<h3><a name="rtcriver">6.3.17 RTC Drivers</a></h3> -<p> - NuttX supports a low-level, two-part RealTime Clock (RTC) driver. -</p> -<ol> - <li> - An "upper half", generic driver that provides the common RTC interface to application level code, and - </li> - <li> - A "lower half", platform-specific driver that implements the low-level timer controls to implement the RTC functionality. - </li> -</ol> -<p> - Files supporting the RTC driver can be found in the following locations: -</p> -<ul> - <li><b>Interface Definition</b>. - The header file for the NuttX RTC driver reside at <code>include/nuttx/rtc.h</code>. - 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. - </li> - <li><b>"Upper Half" Driver</b>. - The generic, "upper half" RTC driver resides at <code>drivers/timers/rtc.c</code>. - </li> - <li><b>"Lower Half" Drivers</b>. - Platform-specific RTC drivers reside in <code>arch/</code><i><architecture></i><code>/src/</code><i><chip></i> directory for the specific processor <i><architecture></i> and for the specific <i><chip></i> RTC peripheral devices. - </li> -</ul> - -<h3><a name="wdogdriver">6.3.18 Watchdog Timer Drivers</a></h3> -<p> - NuttX supports a low-level, two-part watchdog timer driver. -</p> -<ol> - <li> - An "upper half", generic driver that provides the common watchdog timer interface to application level code, and - </li> - <li> - A "lower half", platform-specific driver that implements the low-level timer controls to implement the watchdog timer functionality. - </li> -</ol> -<p> - Files supporting the watchdog timer driver can be found in the following locations: -</p> -<ul> - <li><b>Interface Definition</b>. - The header file for the NuttX watchdog timer driver reside at <code>include/nuttx/watchdog.h</code>. - 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. - </li> - <li><b>"Upper Half" Driver</b>. - The generic, "upper half" watchdog timer driver resides at <code>drivers/timers/watchdog.c</code>. - </li> - <li><b>"Lower Half" Drivers</b>. - Platform-specific watchdog timer drivers reside in <code>arch/</code><i><architecture></i><code>/src/</code><i><chip></i> directory for the specific processor <i><architecture></i> and for the specific <i><chip></i> watchdog timer peripheral devices. - </li> -</ul> - -<h3><a name="kbddriver">6.3.19 Keyboard/Keypad Drivers</a></h3> -<p> - <b>Keypads vs. Keyboards</b> - Keyboards and keypads are really the same devices for NuttX. - A keypad is thought of as simply a keyboard with fewer keys. -</p> -<p> - <b>Special Commands</b>. - 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. -</p> -<p> - <b>Key Press and Release Events</b> - 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. -</p> -<p> - <b>Encoding/Decoding</b> Layer</b>. - 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 <code>include/nuttx/input/kbd_code.h</code>. - These functions provide an matched set of (a) driver encoding interfaces, and (b) application decoding interfaces. -</p> -<ol> - <li> - <p> - <b>Driver Encoding Interfaces</b>. - These are interfaces used by the keyboard/keypad driver to encode keyboard events and data. - </p> - <ul> - <li> - <p> - <b><code>kbd_press()</code></b> - </p> - <p><b>Function Prototype:</b></p> - <ul><pre> -#include <nuttx/streams.h> -#include <nuttx/input/kbd_codec.h> -void kbd_press(int ch, FAR struct lib_outstream_s *stream); -</pre></ul> - <p><b>Description:</b></p> - <ul> - Indicates a normal key press event. - Put one byte of normal keyboard data into the output stream. - </ul> - <p><b>Input Parameters:</b></p> - <ul> - <li> - <code>ch</code>: The character to be added to the output stream. - </li> - <li> - <code>stream</code>: An instance of <code>lib_outstream_s</code> to perform the actual low-level put operation. - </li> - </ul> - <p><b>Returned Value:</b></p> - <ul> - None. - </ul> - </li> - <li> - <p> - <b><code>kbd_release()</code></b> - </p> - <p><b>Function Prototype:</b></p> - <ul><pre> -#include <nuttx/streams.h> -#include <nuttx/input/kbd_codec.h> -void kbd_release(uint8_t ch, FAR struct lib_outstream_s *stream); -</pre></ul> - <p><b>Description:</b></p> - <ul> - Encode the release of a normal key. - </ul> - <p><b>Input Parameters:</b></p> - <ul> - <li> - <code>ch</code>: The character associated with the key that was released. - </li> - <li> - <code>stream</code>: An instance of <code>lib_outstream_s</code> to perform the actual low-level put operation. - </li> - </ul> - <p><b>Returned Value:</b></p> - <ul> - None. - </ul> - </li> - <li> - <p> - <b><code>kbd_specpress()</code></b> - </p> - <p><b>Function Prototype:</b></p> - <ul><pre> -#include <nuttx/streams.h> -#include <nuttx/input/kbd_codec.h> -void kbd_specpress(enum kbd_keycode_e keycode, FAR struct lib_outstream_s *stream); -</pre></ul> - <p><b>Description:</b></p> - <ul> - Denotes a special key press event. - Put one special keyboard command into the output stream. - </ul> - <p><b>Input Parameters:</b></p> - <ul> - <li> - <code>keycode</code>: The command to be added to the output stream. - The enumeration <code>enum kbd_keycode_e keycode</code> identifies all commands known to the system. - </li> - <li> - <code>stream</code>: An instance of <code>lib_outstream_s</code> to perform the actual low-level put operation. - </li> - </ul> - <p><b>Returned Value:</b></p> - <ul> - None. - </ul> - </li> - <li> - <p> - <b><code>kbd_specrel()</code></b> - </p> - <p><b>Function Prototype:</b></p> - <ul><pre> -#include <nuttx/streams.h> -#include <nuttx/input/kbd_codec.h> -void kbd_specrel(enum kbd_keycode_e keycode, FAR struct lib_outstream_s *stream); -</pre></ul> - <p><b>Description:</b></p> - <ul> - Denotes a special key release event. - Put one special keyboard command into the output stream. - </ul> - <p><b>Input Parameters:</b></p> - <ul> - <li> - <code>keycode</code>: The command to be added to the output stream. - The enumeration <code>enum kbd_keycode_e keycode</code> identifies all commands known to the system. - </li> - <li> - <code>stream</code>: An instance of <code>lib_outstream_s</code> to perform the actual low-level put operation. - </li> - </ul> - <p><b>Returned Value:</b></p> - <ul> - None. - </ul> - </li> - </ul> - </li> - <li> - <p> - <b>Application Decoding Interfaces</b>. - These are user interfaces to decode the values returned by the keyboard/keypad driver. - </p> - <ul> - <li> - <p> - <b><code>kbd_decode()</code></b> - </p> - <p><b>Function Prototype:</b></p> - <ul><pre> -#include <nuttx/streams.h> -#include <nuttx/input/kbd_codec.h> -int kbd_decode(FAR struct lib_instream_s *stream, FAR struct kbd_getstate_s *state, FAR uint8_t *pch); -</pre></ul> - <p><b>Description:</b></p> - <ul> - Get one byte of data or special command from the driver provided input buffer. - </ul> - <p><b>Input Parameters:</b></p> - <ul> - <li> - <code>stream</code>: An instance of <code>lib_instream_s</code> to perform the actual low-level get operation. - </li> - <li> - <code>pch</code>: The location to save the returned value. - This may be either a normal, character code or a special command (i.e., a value from <code>enum kbd_getstate_s</code>. - </li> - <li> - <code>state</code>: A user provided buffer to support parsing. - This structure should be cleared the first time that <code>kbd_decode()</code> is called. - </li> - </ul> - <p><b>Returned Value:</b></p> - <ul> - <li> - <b><code>KBD_PRESS</code> (0)</b>: - Indicates the successful receipt of normal, keyboard data. - This corresponds to a keypress event. - The returned value in <code>pch</code> is a simple byte of text or control data. - </li> - <li> - <b><code>KBD_RELEASE</code> (1)</b>: - Indicates a key release event. - The returned value in <code>pch</code> is the byte of text or control data corresponding to the released key. - </li> - <li> - <b><code>KBD_SPECPRESS</code> (2)</b>: - Indicates the successful receipt of a special keyboard command. - The returned value in <code>pch</code> is a value from <code>enum kbd_getstate_s</code>. - </li> - <li> - <b><code>KBD_SPECREL</code> (3)</b>: - Indicates a special command key release event. - The returned value in <code>pch</code> is a value from <code>enum kbd_getstate_s</code>. - </li> - <li> - <b><code>KBD_ERROR</code> (<code>EOF</code>)</b>: - An error has getting the next character (reported by the <code>stream</code>). - Normally indicates the end of file. - </li> - </ul> - </li> - </ul> - </li> -</ol> -<p> - <b>I/O Streams</b>. - Notice the use of the abstract I/O streams in these interfaces. - These stream interfaces are defined in <code>include/nuttx/streams.h</code>. -</p> - <h2><a name="pwrmgmt">6.4 Power Management</a></h2> <h3><a name="pmoverview">6.4.1 Overview</a></h3> |