Serial Communication (I2C, SPI, UART)
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Serial communication within the Zephyr RTOS encompasses the Inter-Integrated Circuit (I2C), Serial Peripheral Interface (SPI), and Universal Asynchronous Receiver-Transmitter (UART) protocols. These interfaces are implemented via a standardized device driver model that abstracts hardware-specific complexities into common APIs, ensuring portability across multiple architectures such as ARM, Intel x86, ARC, RISC-V, and Xtensa.
The primary purpose of these serial modules is to provide a reliable, stable interface for peripheral interaction, ranging from simple sensors to high-speed communication controllers. Within the project's Long Term Support (LTS) framework, I2C and SPI APIs are considered "core" and are subject to strict API freeze requirements to maintain backward compatibility for product developers.
Sources: README.rst, doc/project/release_process.rst:410-425, doc/releases/release-notes-1.7.rst:14-16
Architecture and Maturity
Zephyr utilizes a layered architecture for serial drivers. The generic implementation of I/O APIs resides in the OS services layer, while platform-specific drivers handle the low-level hardware interaction.
Driver Model and API Lifecycle
Serial drivers follow the Zephyr API lifecycle, progressing from experimental to stable. For LTS releases, stable APIs like i2c.h and spi.h must be frozen at least two releases prior to ensure implementation maturity.
The diagram above illustrates the relationship between application code, generic serial APIs, and vendor-specific shim drivers.
Sources: doc/security/security-overview.rst:170-178, doc/project/release_process.rst:400-415
Configuration via Kconfig
Serial drivers are configured using a specific Kconfig naming convention to ensure scope clarity. Driver symbols are formatted as {Driver Type}_{Driver Name}, while prompts follow {Driver Name} {Driver Type} driver.
| Driver Type | Symbol Example | Prompt Example |
|---|---|---|
| I2C | I2C_QMSI | QMSI I2C driver |
| SPI | SPI_MCUX | MCUX SPI driver |
| UART | UART_KSDK | KSDK UART driver |
Sources: doc/contribute/style/kconfig.rst:64-70, doc/releases/release-notes-1.6.rst:54-60
Protocol Specifics
I2C (Inter-Integrated Circuit)
I2C support includes generic configuration parameters that were refactored to be SoC-specific in early releases to improve hardware alignment. Zephyr includes various shim drivers, such as the KSDK shim, to facilitate I2C communication on NXP hardware.
- Key Files:
i2c.h - Functionality: Supports sensors like the FXOS8700 (accelerometer/magnetometer) and HP206C.
Sources: doc/releases/release-notes-1.6.rst:58-65, doc/project/release_process.rst:412
SPI (Serial Peripheral Interface)
SPI implementation includes support for standard master/slave communication and specialized use cases such as SPI HCI drivers for Bluetooth Controller-to-Host communication.
- Maturity: SPI APIs are part of the frozen core for LTS releases.
- Context Management: Internal structures (like those found in
spi_context.h) manage buffer pointers and transfer states.
Sources: doc/releases/release-notes-1.7.rst:48, doc/project/release_process.rst:412
UART (Universal Asynchronous Receiver-Transmitter)
UART provides asynchronous serial communication, often used for consoles, logging, and shell interfaces. Documentation for UART configurations, such as parity modes, uses standardized enums for clarity.
/** @brief Parity modes */
enum uart_config_parity {
UART_CFG_PARITY_NONE, /**< No parity */
UART_CFG_PARITY_ODD, /**< Odd parity */
UART_CFG_PARITY_EVEN, /**< Even parity */
UART_CFG_PARITY_MARK, /**< Mark parity */
UART_CFG_PARITY_SPACE, /**< Space parity */
};
Sources: doc/contribute/style/doxygen.rst:142-149, doc/releases/release-notes-1.7.rst:38
Security and Quality Assurance
Serial communication modules are subject to mandatory code reviews and static analysis. Security-critical aspects, such as memory protection and thread separation for drivers, ensure that UART/I2C/SPI buffers do not cause stack overruns or unauthorized memory access.
- Static Analysis: Analysis must be run regularly, and all findings must be resolved or documented as false-positives before a release.
- Access Control: In secure configurations, peripheral address space can be partitioned, and access can be restricted to specific authorized threads.
Sources: doc/security/security-overview.rst:225-235, doc/security/security-overview.rst:95-105
Summary
Serial Communication in Zephyr is a mature subsystem characterized by its hardware-agnostic API, strict LTS stability guarantees, and integrated security measures. By utilizing standardized Kconfig naming and Doxygen-documented APIs, the project maintains a consistent development environment for I2C, SPI, and UART protocols across diverse hardware platforms.