Introduction¶
The Zephyr kernel supports a variety of device drivers. Whether adriver is available depends on the board and the driver.
The Zephyr device model provides a consistent device model for configuring thedrivers that are part of a system. The device model is responsiblefor initializing all the drivers configured into the system.
Each type of driver (UART, SPI, I2C) is supported by a generic type API.
In this model the driver fills in the pointer to the structure containing thefunction pointers to its API functions during driver initialization. Thesestructures are placed into the RAM section in initialization level order.
It provides a bridge between your computer (or other USB host) and the embedded target processor, which can be used for debugging, flash programming, and serial communication, all over a simple USB cable. The OpenSDA hardware features a Kinetis K2x microcontroller with an integrated USB controller. Use any device capable of scanning to make sure Zephyr's beacon is advertising correctly; Building a BLE Controller. Using Zephyr's built-in, Nordic-contributed, BLE Controller you can actually turn any of your nRF5x-based boards into a fully featured, standard BLE Controller than you can use with external protocol stacks.
Standard Drivers¶
Device drivers which are present on all supported board configurationsare listed below.
Interrupt controller: This device driver is used by the kernel'sinterrupt management subsystem.
Timer: This device driver is used by the kernel's system clock andhardware clock subsystem.
Serial communication: This device driver is used by the kernel'ssystem console subsystem.
Random number generator: This device driver provides a source of randomnumbers.
Important
Certain implementations of this device driver do not generate sequences ofvalues that are truly random.
Synchronous Calls¶
Zephyr provides a set of device drivers for multiple boards. Each drivershould support an interrupt-based implementation, rather than polling, unlessthe specific hardware does not provide any interrupt.
High-level calls accessed through device-specific APIs, such as i2c.hor spi.h, are usually intended as synchronous. Thus, these calls should beblocking.
Driver APIs¶
The following APIs for device drivers are provided by device.h. The APIsare intended for use in device drivers only and should not be used inapplications.
DEVICE_INIT()- create device object and set it up for boot time initialization.
DEVICE_AND_API_INIT()- Create device object and set it up for boot time initialization.This also takes a pointer to driver API struct for link timepointer assignment.
DEVICE_NAME_GET()- Expands to the full name of a global device object.
DEVICE_GET()- Obtain a pointer to a device object by name.
DEVICE_DECLARE()- Declare a device object.
Driver Data Structures¶
The device initialization macros populate some data structures at build timewhich aresplit into read-only and runtime-mutable parts. At a high level we have:
The config member is for read-only configuration data set at build time. Forexample, base memory mapped IO addresses, IRQ line numbers, or other fixedphysical characteristics of the device. This is the config_info structurepassed to the DEVICE_*INIT() macros.
The driver_data struct is kept in RAM, and is used by the driver forper-instance runtime housekeeping. For example, it may contain reference counts,semaphores, scratch buffers, etc.
Download Zephyr Usb Devices Driver Updater
The driver_api struct maps generic subsystem APIs to the device-specificimplementations in the driver. It is typically read-only and populated atbuild time. The next section describes this in more detail.
Subsystems and API Structures¶
Most drivers will be implementing a device-independent subsystem API.Applications can simply program to that generic API, and applicationcode is not specific to any particular driver implementation.
A subsystem API definition typically looks like this:
A driver implementing a particular subsystem will define the real implementationof these APIs, and populate an instance of subsystem_api structure:
The driver would then pass my_driver_api_funcs as the api argument toDEVICE_AND_API_INIT(), or manually assign it to device->driver_apiin the driver init function.
Note
Since pointers to the API functions are referenced in the driver_apistruct, they will always be included in the binary even if unused;gc-sections linker option will always see at least one reference tothem. Providing for link-time size optimizations with driver APIs inmost cases requires that the optional feature be controlled by aKconfig option.
Single Driver, Multiple Instances¶
Some drivers may be instantiated multiple times in a given system. For examplethere can be multiple GPIO banks, or multiple UARTS. Each instance of the driverwill have a different config_info struct and driver_data struct.
Configuring interrupts for multiple drivers instances is a special case. If eachinstance needs to configure a different interrupt line, this can be accomplishedthrough the use of per-instance configuration functions, since the parametersto IRQ_CONNECT() need to be resolvable at build time.
For example, let's say we need to configure two instances of my_driver, eachwith a different interrupt line. In drivers/subsystem/subsystem_my_driver.h:
In the implementation of the common init function:
Then when the particular instance is declared:
Note the use of DEVICE_DECLARE() to avoid a circular dependency on providingthe IRQ handler argument and the definition of the device itself.
Initialization Levels¶
Drivers may depend on other drivers being initialized first, orrequire the use of kernel services. The DEVICE_INIT() APIs allow the user tospecify at what time during the boot sequence the init function will beexecuted. Any driver will specify one of five initialization levels:
PRE_KERNEL_1- Used for devices that have no dependencies, such as those that relysolely on hardware present in the processor/SOC. These devices cannotuse any kernel services during configuration, since the kernel services arenot yet available. The interrupt subsystem will be configured howeverso it's OK to set up interrupts. Init functions at this level run on theinterrupt stack.
PRE_KERNEL_2- Used for devices that rely on the initialization of devices initializedas part of the PRIMARY level. These devices cannot use any kernelservices during configuration, since the kernel services are not yetavailable. Init functions at this level run on the interrupt stack.
POST_KERNEL- Used for devices that require kernel services during configuration.Init functions at this level run in context of the kernel main task.
APPLICATION- Used for application components (i.e. non-kernel components) that needautomatic configuration. These devices can use all services provided bythe kernel during configuration. Init functions at this level run onthe kernel main task.
Within each initialization level you may specify a priority level, relative toother devices in the same initialization level. The priority level is specifiedas an integer value in the range 0 to 99; lower values indicate earlierinitialization. The priority level must be a decimal integer literal withoutleading zeroes or sign (e.g. 32), or an equivalent symbolic name (e.g.#defineMY_INIT_PRIO32); symbolic expressions are not permitted (e.g.CONFIG_KERNEL_INIT_PRIORITY_DEFAULT+5).
System Drivers¶
In some cases you may just need to run a function at boot. Special SYS_*macros exist that map to DEVICE_*INIT() calls.For SYS_INIT() there are no config or runtime data structures and thereisn't a wayto later get a device pointer by name. The same policies for initializationlevel and priority apply.
For SYS_DEVICE_DEFINE() you can obtain pointers by name, seepower management section.
SYS_INIT()
SYS_DEVICE_DEFINE()
Error handling¶
In general, it's best to use __ASSERT() macros instead ofpropagating return values unless the failure is expected to occurduring the normal course of operation (such as a storage devicefull). Bad parameters, programming errors, consistency checks,pathological/unrecoverable failures, etc., should be handled byassertions.
Download Zephyr USB Devices Driver
When it is appropriate to return error conditions for the caller tocheck, 0 should be returned on success and a POSIX errno.h codereturned on failure. Seehttps://github.com/zephyrproject-rtos/zephyr/wiki/Naming-Conventions#return-codesfor details about this.
