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: +
+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.
+ 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: @@ -4233,193 +4258,7 @@ void board_led_off(int led);
- 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 open(FAR struct inode *inode);
- int close(FAR struct inode *inode);
- ssize_t read(FAR struct inode *inode, FAR unsigned char *buffer, size_t start_sector, unsigned int nsectors);
- ssize_t write(FAR struct inode *inode, FAR const unsigned char *buffer, size_t start_sector, unsigned int nsectors);
- int geometry(FAR struct inode *inode, FAR struct geometry *geometry);
- int ioctl(FAR struct inode *inode, int cmd, unsigned long arg);
- 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 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.
-
- 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 uIP 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.
-
- 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:
-
void lock(FAR struct spi_dev_s *dev);
void select(FAR struct spi_dev_s *dev, enum spi_dev_e devid, bool selected);
- uint32_t setfrequency(FAR struct spi_dev_s *dev, uint32_t frequency);
- void setmode(FAR struct spi_dev_s *dev, enum spi_mode_e mode);
- void setbits(FAR struct spi_dev_s *dev, int nbits);
- uint8_t status(FAR struct spi_dev_s *dev, enum spi_dev_e devid);
- uint16_t send(FAR struct spi_dev_s *dev, uint16_t wd);
- void exchange(FAR struct spi_dev_s *dev, FAR const void *txbuffer, FAR void *rxbuffer, size_t nwords);
-
int registercallback(FAR struct spi_dev_s *dev, mediachange_t callback, void *arg);
- 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:
-
-
struct spi_dev_s from the hardware-specific SPI device driver, and
- Examples:
- drivers/loop.c, drivers/mmcsd/mmcsd_spi.c, drivers/ramdisk.c, etc.
-
- 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:
-
uint32_t setfrequency(FAR struct i2c_dev_s *dev, uint32_t frequency);
- int setaddress(FAR struct i2c_dev_s *dev, int addr, int nbits);
- int write(FAR struct i2c_dev_s *dev, const uint8_t *buffer, int buflen);
- int read(FAR struct i2c_dev_s *dev, uint8_t *buffer, int buflen);
- 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: -
--
struct i2c_dev_s from the hardware-specific I2C device driver, and
- Examples:
- arch/z80/src/ez80/ez80_i2c.c, arch/z80/src/z8/z8_i2c.c, etc.
-
- 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. -
-int (*getvideoinfo)(FAR struct fb_vtable_s *vtable, FAR struct fb_videoinfo_s *vinfo);
- int (*getplaneinfo)(FAR struct fb_vtable_s *vtable, int planeno, FAR struct fb_planeinfo_s *pinfo);
- The following are provided only if the video hardware supports RGB color mapping: -
-int (*getcmap)(FAR struct fb_vtable_s *vtable, FAR struct fb_cmap_s *cmap);
- int (*putcmap)(FAR struct fb_vtable_s *vtable, FAR const struct fb_cmap_s *cmap);
- The following are provided only if the video hardware supports a hardware cursor: -
-int (*getcursor)(FAR struct fb_vtable_s *vtable, FAR struct fb_cursorattrib_s *attrib);
- int (*setcursor)(FAR struct fb_vtable_s *vtable, FAR struct fb_setcursor_s *settings);
- 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: -
--
struct fb_vtable_s from the hardware-specific frame buffer device driver, and
- Examples:
- arch/sim/src/up_framebuffer.c.
- See also the usage of the frame buffer driver in the graphics/ directory.
-
- 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. -
-
- int (*getvideoinfo)(FAR struct lcd_dev_s *dev, FAR struct fb_videoinfo_s *vinfo);
- int (*getplaneinfo)(FAR struct lcd_dev_s *dev, unsigned int planeno, FAR struct lcd_planeinfo_s *pinfo);
-
- The following are provided only if the video hardware supports RGB color mapping: -
-
- int (*getcmap)(FAR struct lcd_dev_s *dev, FAR struct fb_cmap_s *cmap);
- int (*putcmap)(FAR struct lcd_dev_s *dev, FAR const struct fb_cmap_s *cmap);
-
- The following are provided only if the video hardware supports a hardware cursor: -
-
- int (*getcursor)(FAR struct lcd_dev_s *dev, FAR struct fb_cursorattrib_s *attrib);
- int (*setcursor)(FAR struct lcd_dev_s *dev, FAR struct fb_setcursor_s *settings)
-
- 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.
-
- int (*getpower)(struct lcd_dev_s *dev);
-
- Enable/disable LCD panel power (0: full off - CONFIG_LCD_MAXPOWER: full on).
- On backlit LCDs, this setting may correspond to the backlight setting.
-
- int (*setpower)(struct lcd_dev_s *dev, int power);
-
- Get the current contrast setting (0-CONFIG_LCD_MAXCONTRAST) */ -
-
- int (*getcontrast)(struct lcd_dev_s *dev);
-
- Set LCD panel contrast (0-CONFIG_LCD_MAXCONTRAST) -
-
- int (*setcontrast)(struct lcd_dev_s *dev, unsigned int contrast);
-
- 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: -
--
struct lcd_dev_s from the hardware-specific LCD device driver, and
- Examples:
- drivers/lcd/nokia6100.c, drivers/lcd/p14201.c, configs/sam3u-ek/src/up_lcd.c.
- See also the usage of the LCD driver in the graphics/ directory.
-
NuttX supports a two-part touchscreen driver architecture. @@ -4669,386 +4347,7 @@ void board_led_off(int led);
- 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): -
-int (*erase)(FAR struct mtd_dev_s *dev, off_t startblock, size_t nblocks);
- Read/write from the specified read/write blocks: -
-ssize_t (*bread)(FAR struct mtd_dev_s *dev, off_t startblock, size_t nblocks, FAR uint8_t *buffer);
- ssize_t (*bwrite)(FAR struct mtd_dev_s *dev, off_t startblock, size_t nblocks, FAR const uint8_t *buffer);
- 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. -
-ssize_t (*read)(FAR struct mtd_dev_s *dev, off_t offset, size_t nbytes, FAR uint8_t *buffer);
- 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.
-
ssize_t (*write)(FAR struct mtd_dev_s *dev, off_t offset, size_t nbytes, FAR const uint8_t *buffer);
- Support other, less frequently used commands: -
-MTDIOC_GEOMETRY: Get MTD geometryMTDIOC_XIPBASE:: Convert block to physical address for eXecute-In-PlaceMTDIOC_BULKERASE: Erase the entire device
- is provided via a single ioctl method (see include/nuttx/fs/ioctl.h):
-
int (*ioctl)(FAR struct mtd_dev_s *dev, int cmd, unsigned long arg);
- 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: -
--
struct mtd_dev_s from the hardware-specific MTD device driver, and
- Examples:
- drivers/mtd/m25px.c and drivers/mtd/ftl.c
-
- 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: -
-
- #ifdef CONFIG_SDIO_MUXBUS
- int (*lock)(FAR struct sdio_dev_s *dev, bool lock);
- #endif
-
- Initialization/setup: -
-void (*reset)(FAR struct sdio_dev_s *dev);
- uint8_t (*status)(FAR struct sdio_dev_s *dev);
- void (*widebus)(FAR struct sdio_dev_s *dev, bool enable);
- void (*clock)(FAR struct sdio_dev_s *dev, enum sdio_clock_e rate);
- int (*attach)(FAR struct sdio_dev_s *dev);
-
- Command/Status/Data Transfer: -
-int (*sendcmd)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t arg);
- int (*recvsetup)(FAR struct sdio_dev_s *dev, FAR uint8_t *buffer, size_t nbytes);
- int (*sendsetup)(FAR struct sdio_dev_s *dev, FAR const uint8_t *buffer, size_t nbytes);
- int (*cancel)(FAR struct sdio_dev_s *dev);
- int (*waitresponse)(FAR struct sdio_dev_s *dev, uint32_t cmd);
- int (*recvR1)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R1);
- int (*recvR2)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t R2[4]);
- int (*recvR3)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R3);
- int (*recvR4)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R4);
- int (*recvR5)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R5);
- int (*recvR6)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R6);
- int (*recvR7)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R7);
- Event/Callback support: -
-void (*waitenable)(FAR struct sdio_dev_s *dev, sdio_eventset_t eventset);
- sdio_eventset_t (*eventwait)(FAR struct sdio_dev_s *dev, uint32_t timeout);
- void (*callbackenable)(FAR struct sdio_dev_s *dev, sdio_eventset_t eventset);
- int (*registercallback)(FAR struct sdio_dev_s *dev, worker_t callback, void *arg);
- DMA support: -
-bool (*dmasupported)(FAR struct sdio_dev_s *dev);
- int (*dmarecvsetup)(FAR struct sdio_dev_s *dev, FAR uint8_t *buffer, size_t buflen);
- int (*dmasendsetup)(FAR struct sdio_dev_s *dev, FAR const uint8_t *buffer, size_t buflen);
- 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: -
--
struct sdio_dev_s from the hardware-specific SDIO device driver, and
- Examples:
- arch/arm/src/stm32/stm32_sdio.c and drivers/mmcsd/mmcsd_sdio.c
-
- 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/lpc17_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_storageinit() 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 configs/nucleus2g/src/up_nsh.c and
- the function nsh_waiter() in the file configs/olimex-lpc1766stk/src/up_nsh.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.
-
- 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.
-
- 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/lpc17_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.
-
The NuttX analog drivers are split into two parts:
@@ -5073,7 +4372,7 @@ void board_led_off(int led); -include/nuttx/analog/adc.h.
@@ -5098,7 +4397,7 @@ void board_led_off(int led);
include/nuttx/analog/dac.h.
@@ -5123,7 +4422,7 @@ void board_led_off(int led);
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 @@ -5159,7 +4458,7 @@ void board_led_off(int led); -
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. @@ -5190,7 +4489,7 @@ void board_led_off(int led); -
NuttX supports a low-level, two-part Quadrature Encoder driver.
@@ -5219,7 +4518,7 @@ void board_led_off(int led); -NuttX supports a low-level, two-part timer driver.
@@ -5248,7 +4547,7 @@ void board_led_off(int led); -NuttX supports a low-level, two-part RealTime Clock (RTC) driver.
@@ -5277,7 +4576,7 @@ void board_led_off(int led); -NuttX supports a low-level, two-part watchdog timer driver.
@@ -5306,7 +4605,7 @@ void board_led_off(int led); -
Keypads vs. Keyboards
Keyboards and keypads are really the same devices for NuttX.
@@ -5531,6 +4830,739 @@ int kbd_decode(FAR struct lib_instream_s *stream, FAR struct kbd_getstate_s *sta
These stream interfaces are defined in include/nuttx/streams.h.
+ 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 open(FAR struct inode *inode);
+ int close(FAR struct inode *inode);
+ ssize_t read(FAR struct inode *inode, FAR unsigned char *buffer, size_t start_sector, unsigned int nsectors);
+ ssize_t write(FAR struct inode *inode, FAR const unsigned char *buffer, size_t start_sector, unsigned int nsectors);
+ int geometry(FAR struct inode *inode, FAR struct geometry *geometry);
+ int ioctl(FAR struct inode *inode, int cmd, unsigned long arg);
+ 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 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.
+
+ 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. +
+ +
+ 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 uIP 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.
+
+ 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:
+
void lock(FAR struct spi_dev_s *dev);
void select(FAR struct spi_dev_s *dev, enum spi_dev_e devid, bool selected);
+ uint32_t setfrequency(FAR struct spi_dev_s *dev, uint32_t frequency);
+ void setmode(FAR struct spi_dev_s *dev, enum spi_mode_e mode);
+ void setbits(FAR struct spi_dev_s *dev, int nbits);
+ uint8_t status(FAR struct spi_dev_s *dev, enum spi_dev_e devid);
+ uint16_t send(FAR struct spi_dev_s *dev, uint16_t wd);
+ void exchange(FAR struct spi_dev_s *dev, FAR const void *txbuffer, FAR void *rxbuffer, size_t nwords);
+
int registercallback(FAR struct spi_dev_s *dev, mediachange_t callback, void *arg);
+ 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:
+
+
struct spi_dev_s from the hardware-specific SPI device driver, and
+ Examples:
+ drivers/loop.c, drivers/mmcsd/mmcsd_spi.c, drivers/ramdisk.c, etc.
+
+ 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:
+
uint32_t setfrequency(FAR struct i2c_dev_s *dev, uint32_t frequency);
+ int setaddress(FAR struct i2c_dev_s *dev, int addr, int nbits);
+ int write(FAR struct i2c_dev_s *dev, const uint8_t *buffer, int buflen);
+ int read(FAR struct i2c_dev_s *dev, uint8_t *buffer, int buflen);
+ 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: +
++
struct i2c_dev_s from the hardware-specific I2C device driver, and
+ Examples:
+ arch/z80/src/ez80/ez80_i2c.c, arch/z80/src/z8/z8_i2c.c, etc.
+
+ 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. +
+int (*getvideoinfo)(FAR struct fb_vtable_s *vtable, FAR struct fb_videoinfo_s *vinfo);
+ int (*getplaneinfo)(FAR struct fb_vtable_s *vtable, int planeno, FAR struct fb_planeinfo_s *pinfo);
+ The following are provided only if the video hardware supports RGB color mapping: +
+int (*getcmap)(FAR struct fb_vtable_s *vtable, FAR struct fb_cmap_s *cmap);
+ int (*putcmap)(FAR struct fb_vtable_s *vtable, FAR const struct fb_cmap_s *cmap);
+ The following are provided only if the video hardware supports a hardware cursor: +
+int (*getcursor)(FAR struct fb_vtable_s *vtable, FAR struct fb_cursorattrib_s *attrib);
+ int (*setcursor)(FAR struct fb_vtable_s *vtable, FAR struct fb_setcursor_s *settings);
+ 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: +
++
struct fb_vtable_s from the hardware-specific frame buffer device driver, and
+ Examples:
+ arch/sim/src/up_framebuffer.c.
+ See also the usage of the frame buffer driver in the graphics/ directory.
+
+ 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. +
+
+ int (*getvideoinfo)(FAR struct lcd_dev_s *dev, FAR struct fb_videoinfo_s *vinfo);
+ int (*getplaneinfo)(FAR struct lcd_dev_s *dev, unsigned int planeno, FAR struct lcd_planeinfo_s *pinfo);
+
+ The following are provided only if the video hardware supports RGB color mapping: +
+
+ int (*getcmap)(FAR struct lcd_dev_s *dev, FAR struct fb_cmap_s *cmap);
+ int (*putcmap)(FAR struct lcd_dev_s *dev, FAR const struct fb_cmap_s *cmap);
+
+ The following are provided only if the video hardware supports a hardware cursor: +
+
+ int (*getcursor)(FAR struct lcd_dev_s *dev, FAR struct fb_cursorattrib_s *attrib);
+ int (*setcursor)(FAR struct lcd_dev_s *dev, FAR struct fb_setcursor_s *settings)
+
+ 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.
+
+ int (*getpower)(struct lcd_dev_s *dev);
+
+ Enable/disable LCD panel power (0: full off - CONFIG_LCD_MAXPOWER: full on).
+ On backlit LCDs, this setting may correspond to the backlight setting.
+
+ int (*setpower)(struct lcd_dev_s *dev, int power);
+
+ Get the current contrast setting (0-CONFIG_LCD_MAXCONTRAST) */ +
+
+ int (*getcontrast)(struct lcd_dev_s *dev);
+
+ Set LCD panel contrast (0-CONFIG_LCD_MAXCONTRAST) +
+
+ int (*setcontrast)(struct lcd_dev_s *dev, unsigned int contrast);
+
+ 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: +
++
struct lcd_dev_s from the hardware-specific LCD device driver, and
+ Examples:
+ drivers/lcd/nokia6100.c, drivers/lcd/p14201.c, configs/sam3u-ek/src/up_lcd.c.
+ See also the usage of the LCD driver in the graphics/ directory.
+
+ 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): +
+int (*erase)(FAR struct mtd_dev_s *dev, off_t startblock, size_t nblocks);
+ Read/write from the specified read/write blocks: +
+ssize_t (*bread)(FAR struct mtd_dev_s *dev, off_t startblock, size_t nblocks, FAR uint8_t *buffer);
+ ssize_t (*bwrite)(FAR struct mtd_dev_s *dev, off_t startblock, size_t nblocks, FAR const uint8_t *buffer);
+ 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. +
+ssize_t (*read)(FAR struct mtd_dev_s *dev, off_t offset, size_t nbytes, FAR uint8_t *buffer);
+ 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.
+
ssize_t (*write)(FAR struct mtd_dev_s *dev, off_t offset, size_t nbytes, FAR const uint8_t *buffer);
+ Support other, less frequently used commands: +
+MTDIOC_GEOMETRY: Get MTD geometryMTDIOC_XIPBASE:: Convert block to physical address for eXecute-In-PlaceMTDIOC_BULKERASE: Erase the entire device
+ is provided via a single ioctl method (see include/nuttx/fs/ioctl.h):
+
int (*ioctl)(FAR struct mtd_dev_s *dev, int cmd, unsigned long arg);
+ 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: +
++
struct mtd_dev_s from the hardware-specific MTD device driver, and
+ Examples:
+ drivers/mtd/m25px.c and drivers/mtd/ftl.c
+
+ 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: +
+
+ #ifdef CONFIG_SDIO_MUXBUS
+ int (*lock)(FAR struct sdio_dev_s *dev, bool lock);
+ #endif
+
+ Initialization/setup: +
+void (*reset)(FAR struct sdio_dev_s *dev);
+ uint8_t (*status)(FAR struct sdio_dev_s *dev);
+ void (*widebus)(FAR struct sdio_dev_s *dev, bool enable);
+ void (*clock)(FAR struct sdio_dev_s *dev, enum sdio_clock_e rate);
+ int (*attach)(FAR struct sdio_dev_s *dev);
+
+ Command/Status/Data Transfer: +
+int (*sendcmd)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t arg);
+ int (*recvsetup)(FAR struct sdio_dev_s *dev, FAR uint8_t *buffer, size_t nbytes);
+ int (*sendsetup)(FAR struct sdio_dev_s *dev, FAR const uint8_t *buffer, size_t nbytes);
+ int (*cancel)(FAR struct sdio_dev_s *dev);
+ int (*waitresponse)(FAR struct sdio_dev_s *dev, uint32_t cmd);
+ int (*recvR1)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R1);
+ int (*recvR2)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t R2[4]);
+ int (*recvR3)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R3);
+ int (*recvR4)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R4);
+ int (*recvR5)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R5);
+ int (*recvR6)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R6);
+ int (*recvR7)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R7);
+ Event/Callback support: +
+void (*waitenable)(FAR struct sdio_dev_s *dev, sdio_eventset_t eventset);
+ sdio_eventset_t (*eventwait)(FAR struct sdio_dev_s *dev, uint32_t timeout);
+ void (*callbackenable)(FAR struct sdio_dev_s *dev, sdio_eventset_t eventset);
+ int (*registercallback)(FAR struct sdio_dev_s *dev, worker_t callback, void *arg);
+ DMA support: +
+bool (*dmasupported)(FAR struct sdio_dev_s *dev);
+ int (*dmarecvsetup)(FAR struct sdio_dev_s *dev, FAR uint8_t *buffer, size_t buflen);
+ int (*dmasendsetup)(FAR struct sdio_dev_s *dev, FAR const uint8_t *buffer, size_t buflen);
+ 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: +
++
struct sdio_dev_s from the hardware-specific SDIO device driver, and
+ Examples:
+ arch/arm/src/stm32/stm32_sdio.c and drivers/mmcsd/mmcsd_sdio.c
+
+ 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/lpc17_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_storageinit() 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 configs/nucleus2g/src/up_nsh.c and
+ the function nsh_waiter() in the file configs/olimex-lpc1766stk/src/up_nsh.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.
+
+ 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.
+
+ 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/lpc17_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.
+