Shell & Logging Subsystem
Relevant source files
The following files were used as context for generating this wiki page:
The Shell and Logging subsystems are critical components of the Zephyr RTOS, providing essential services for system interaction, debugging, and diagnostics. The logging subsystem serves as an OS service responsible for recording system events, while the shell provides a command-line interface for real-time interaction with the kernel and applications. Together, they form the primary interface for developers to monitor and control the system state during development and production.
These subsystems are integrated into the broader OS Services layer, positioned above the kernel and below application services. They play a vital role in both quality assurance and security, as logs provide auditable events for security monitoring and the shell facilitates manual system verification.
Sources: doc/security/security-overview.rst:142-148, doc/index.rst:38-42
Subsystem Architecture
The Shell and Logging subsystems operate as part of the monolithic kernel design, where services are compiled into a single static binary. This architecture minimizes the attack surface by removing the need for dynamic loaders and context switches for system calls.
Integration with System Layers
The following diagram illustrates the position of the Shell and Logging services within the Zephyr system architecture:
The Shell and Logging subsystems act as an intermediary layer between Application Services and the Kernel.
Sources: doc/security/security-overview.rst:140-153
Logging Subsystem
The Logging subsystem is designed for execution protection and system-level diagnostics. It is essential for documenting "auditable events," which is a requirement for security-oriented system designs.
Key Features and Security Considerations
Logging is treated as a core security measure under the "Quality Assurance" pillar. It ensures that security-relevant code can be reviewed and that system behavior is trackable.
| Feature | Description |
|---|---|
| Auditable Events | Recording security-relevant status information and system events. |
| Static Analysis | Integrated checks to ensure appropriate usage of string and memory functions in logs. |
| Verification | Used to verify correct functionality during manual and automated code reviews. |
Sources: doc/security/security-overview.rst:58-62, doc/security/security-overview.rst:252-255
Data Flow for Auditable Events
The logging flow ensures that system events are captured and stored in a manner that supports threat modeling and vulnerability analysis.
Capture and storage of events for future security audits.
Sources: doc/security/security-overview.rst:248-260
Shell Subsystem
The Shell provides a command-line interface (CLI) that allows developers to execute commands, modify configurations, and interact with the system at runtime. In the context of the Zephyr project, the shell is often used in sample applications to demonstrate subsystem functionality.
Command Structure and Documentation
Shell commands are documented using Doxygen to provide a consistent API reference. Each public API symbol associated with the shell must be fully documented, including function parameters and return values.
| Element | Documentation Requirement |
|---|---|
| @param | Description of parameters in declaration order. |
| @return | General description of the computed value. |
| @retval | Specific discrete return values (e.g., error codes like -EINVAL). |
Sources: doc/contribute/style/doxygen.rst:133-145, doc/contribute/style/doxygen.rst:160-165
Implementation in Samples
Samples often use the shell to provide a "console harness" for automated testing via the Twister tool. This allows the tool to verify sample output against expected regular expressions.
The shell serves as the interface for automated harness verification.
Sources: samples/sample_definition_and_criteria.rst:43-52
Configuration and Quality Goals
Both subsystems are subject to Zephyr's strict quality and configuration management processes.
Kconfig Management
Functionalities within the Shell and Logging subsystems can be disabled using Kconfig. This is a critical safety and security feature, following the principle of "Economy of Mechanism"—keeping the design as simple and small as possible by disabling unused services.
Sources: doc/safety/safety_overview.rst:180-185, doc/security/security-overview.rst:183-189
Quality Criteria for Release
For these subsystems to be included in a release, specifically an LTS (Long Term Support) release, they must meet the following criteria:
- API Stability: Core implementations must be frozen and not modified between releases to ensure a stable foundation.
- Static Analysis: Zero high or critical static analysis issues.
- Documentation: Complete Doxygen-generated API documentation.
Sources: doc/project/release_process.rst:155-160, doc/project/release_process.rst:210-215
Conclusion
The Shell and Logging subsystems are foundational OS services in Zephyr. While the Logging subsystem provides the transparency necessary for security auditing and diagnostics, the Shell offers the interactivity required for development and automated testing. Their integration into the Zephyr safety and security workflows ensures they contribute to the overall reliability and audibility of the RTOS.