Modules & Hardware Abstraction Layers
Relevant source files
The following files were used as context for generating this wiki page:
The Zephyr Project utilizes a modular architecture to manage external source code, libraries, and hardware-specific code. This approach allows the core kernel to remain architecture-agnostic while enabling support for a vast array of silicon vendors and third-party software components. Hardware Abstraction Layers (HALs) and external modules are integrated into the project to provide drivers, protocol stacks, and vendor-specific implementations without cluttering the main repository.
Modules and HALs are typically managed via the west tool, which handles the acquisition and synchronization of external repositories. This structure supports the project's goals of scalability and resource efficiency, particularly for resource-constrained IoT devices.
Sources: README.rst, doc/contribute/external.rst:117-120, doc/develop/beyond-GSG.rst:64-70
External Component Integration
External source code can be integrated into the project in three primary modes, depending on the scope of the code and its intended maintenance lifecycle.
Integration Modes
| Mode | Description | Requirements |
|---|---|---|
| Main Tree | Code is imported directly into the zephyr repository. | Must follow Zephyr coding style and guidelines; subject to same static analysis as kernel code. |
| Module | Code is kept in a separate repository and linked via west.yml. | Can maintain external coding styles; validated by Zephyr CI. |
| Optional Module | Standalone projects without incoming dependencies. | Filtered by default in submanifests/optional.yml; tests/samples kept in module repo. |
Sources: doc/contribute/external.rst:86-114, doc/contribute/external.rst:122-132
The Module Workflow
The following diagram illustrates the lifecycle of external source code from submission to integration as a module.
The integration process requires Technical Steering Committee (TSC) approval for any changes to the projects: section of the main manifest.
Sources: doc/contribute/external.rst:162-212, doc/contribute/external.rst:248-255
Hardware Abstraction Layers (HAL)
Hardware Abstraction Layers are a specific class of modules that provide the low-level, platform-specific drivers and register definitions required for an architecture or SoC.
HAL Architecture and Security
In the Zephyr system architecture, HALs reside within the OS part (Kernel + OS Services), specifically providing platform-specific drivers that interface with generic I/O APIs. This modularity is a key part of the "Economy of Mechanism" security principle, keeping the design simple and small by abstracting hardware complexities.
The architecture separates privileged and unprivileged environments, where HALs may be utilized by drivers to perform system calls that do not always require context switches if implemented as function calls in a monolithic design.
Sources: doc/security/security-overview.rst:160-170, doc/security/security-overview.rst:209-218, doc/security/security-overview.rst:242-250
Vendor HAL Management
HALs for specific vendors (e.g., Nordic, NXP) are typically managed as modules. This allows vendors to maintain their own HALs according to their specific release cycles while Zephyr ensures compatibility through the west update mechanism.
Sources: doc/develop/beyond-GSG.rst:72-74, doc/contribute/external.rst:117-120
Safety and Quality Standards
Modules and HALs must adhere to specific quality goals to be considered "auditable" for safety-critical applications (e.g., IEC 61508 certification).
Quality Managed Status
For a module to be usable in a safety-certified context, it must pursue several architectural design principles:
- Layered Architecture: Organizing modules with similar functionality into layers to show interfaces at a high level.
- Encapsulation: Separating safety-relevant components from non-safety-relevant ones to prevent repercussions.
- Configurability: Using Kconfig to disable functionalities within modules that are unacceptable for safety (e.g., dynamic memory management).
Sources: doc/safety/safety_overview.rst:104-114, doc/safety/safety_overview.rst:215-245
Coding Guidelines Implementation
The project follows a staged approach for coding guidelines across its code base and modules:
- Stage I: Rules available but not enforced.
- Stage II: Reviewers can block PRs for violations; enforcement begins on safety certification scope.
- Stage III: Refinement of rules based on experience.
- Stage IV: Expansion of enforcement to the wider codebase.
Sources: doc/safety/safety_overview.rst:147-168
Module Maintenance and Tooling
West Tooling
west is the primary tool for managing Zephyr modules. The west update command is critical for keeping modules in sync with the local zephyr repository.
Sources: doc/develop/beyond-GSG.rst:64-74
External Tooling
Some modules are classified as "external tooling" rather than code modules. These include software for compilation, testing, or simulation (e.g., scripts placed in the scripts/ folder). Unlike code modules, these are not automatically processed by the Zephyr build system.
Sources: doc/contribute/external.rst:216-235
Conclusion
Modules and Hardware Abstraction Layers are fundamental to Zephyr's ability to support diverse hardware and software ecosystems. By utilizing west for repository management and enforcing strict integration processes through the TSC, the project maintains a high standard of quality and security while allowing for extensive external contributions. These structures are critical for the project's roadmap toward safety certification and industrial-grade stability.
Sources: doc/safety/safety_overview.rst:215-225, doc/security/security-overview.rst:242-250, doc/contribute/external.rst:152-160