Coding Guidelines
Main rules
The coding guideline rules are based on MISRA-C 2012 and are a subset of MISRA-C. The subset is listed in the table below with a summary of the rules, its MISRA-C severity and the equivalent rules from other standards for reference.
The severity and other references in the table below are for informational purposes only. The listed rules are all required for Zephyr and all new code should comply with the rules listed below.
Note
For existing Zephyr maintainers and collaborators, if you are unable to obtain a copy through your employer, a limited number of copies will be made available through the project. If you need a copy of MISRA-C 2012, please send email to safety@lists.zephyrproject.org and provide details on reason why you can’t obtain one through other options and expected contributions once you have one. The safety committee will review all requests.
Additional rules
Rule A.1: Conditional Compilation
- Severity
Required
- Description
Do not conditionally compile function declarations in header files. Do not conditionally compile structure declarations in header files. You may conditionally exclude fields within structure definitions to avoid wasting memory when the feature they support is not enabled.
- Rationale
Excluding declarations from the header based on compile-time options may prevent their documentation from being generated. Their absence also prevents use of
if (IS_ENABLED(CONFIG_FOO)) {}as an alternative to preprocessor conditionals when the code path should change based on the selected options.
Rule A.2: Inclusive Language
- Severity
Required
- Description
Do not introduce new usage of offensive terms listed below. This rule applies but is not limited to source code, comments, documentation, and branch names. Replacement terms may vary by area or subsystem, but should aim to follow updated industry standards when possible.
Exceptions are allowed for maintaining existing implementations or adding new implementations of industry standard specifications governed externally to the Zephyr Project.
Existing usage is recommended to change as soon as updated industry standard specifications become available or new terms are publicly announced by the governing body, or immediately if no specifications apply.
Offensive Terms
Recommended Replacements
{master,leader} / slave{primary,main} / {secondary,replica}{initiator,requester} / {target,responder}{controller,host} / {device,worker,proxy,target}director / performercentral / peripheral
blacklist / whitelistdenylist / allowlistblocklist / allowlistrejectlist / acceptlist
grandfather policylegacy
sanitycoherenceconfidence
- Rationale
Offensive terms do not create an inclusive community environment and therefore violate the Zephyr Project Code of Conduct. This coding rule was inspired by a similar rule in Linux.
- Status
Related GitHub Issues and Pull Requests are tagged with the Inclusive Language Label.
Area
Selected Replacements
Status
CAN
This CAN in Automation Inclusive Language news post has a list of general recommendations. See CAN in Automation Inclusive Language for terms to be used in specification document updates.
eSPI
master / slave=>controller / target
Refer to eSPI Specification for new terminology
gPTP
master / slave=> TBD
master / slave=>controller / target
Refer to I2C Specification for new terminology.
master / slave=> TBD
SMP/AMP
master / slave=> TBD
master / slave=>controller / peripheralMOSI / MISO / SS=>SDO / SDI / CS
The Open Source Hardware Association has selected these replacement terms. See OSHWA Resolution to Redefine SPI Signal Names
platform_whitelist=>platform_allowsanitycheck=>twister
Rule A.3: Macro name collisions
- Severity
Required
- Description
Macros with commonly used names such as
MIN,MAX,ARRAY_SIZE, must not be modified or protected to avoid name collisions with other implementations. In particular, they must not be prefixed to place them in a Zephyr-specific namespace, re-defined using#undef, or conditionally excluded from compilation using#ifndef. Instead, if a conflict arises with an existing definition originating from a module, the module’s code itself needs to be modified (ideally upstream, alternatively via a change in Zephyr’s own fork).This rule applies to Zephyr as a project in general, regardless of the time of introduction of the macro or its current name in the tree. If a macro name is commonly used in several other well-known open source projects then the implementation in Zephyr should use that name. While there is a subjective and non-measurable component to what “commonly used” means, the ultimate goal is to offer users familiar macros.
Finally, this rule applies to inter-module name collisions as well: in that case both modules, prior to their inclusion, should be modified to use module-specific versions of the macro name that collides.
- Rationale
Zephyr is an RTOS that comes with additional functionality and dependencies in the form of modules. Those modules are typically independent projects that may use macro names that can conflict with other modules or with Zephyr itself. Since, in the context of this documentation, Zephyr is considered the central or main project, it should implement the non-namespaced versions of the macros. Given that Zephyr uses a fork of the corresponding upstream for each module, it is always possible to patch the macro implementation in each module to avoid collisions.
Rule A.4: C Standard Library Usage Restrictions in Zephyr Kernel
- Severity
Required
- Description
The use of the C standard library functions and macros in the Zephyr kernel shall be limited to the following functions and macros from the ISO/IEC 9899:2011 standard, also known as C11, and their extensions:
All of the functions listed above must be implemented by the minimal libc to ensure that the Zephyr kernel can build with the minimal libc.
In addition, any functions from the above list that are not part of the ISO/IEC 9899:2011 standard must be implemented by the common libc to ensure their availability across multiple C standard libraries.
Introducing new C standard library functions to the Zephyr kernel is allowed with justification given that the above requirements are satisfied.
Note that the use of the functions listed above are subject to secure and safe coding practices and it should not be assumed that their use in the Zephyr kernel is unconditionally permitted by being listed in this rule.
The “Zephyr kernel” in this context consists of the following components:
Kernel (
kernel)OS Library (
lib/os)Architecture Port (
arch)Logging Subsystem (
subsys/logging)
- Rationale
Zephyr kernel must be able to build with the minimal libc, a limited C standard library implementation that is part of the Zephyr RTOS and maintained by the Zephyr Project, to allow self-contained testing and verification of the kernel and core OS services.
In order to ensure that the Zephyr kernel can build with the minimal libc, it is necessary to restrict the use of the C standard library functions and macros in the Zephyr kernel to the functions and macros that are available as part of the minimal libc.
Rule A.5: C Standard Library Usage Restrictions in Zephyr Codebase
- Severity
Required
- Description
The use of the C standard library functions and macros in the Zephyr codebase shall be limited to the functions, excluding the Annex K “Bounds-checking interfaces”, from the ISO/IEC 9899:2011 standard, also known as C11, unless exempted by this rule.
The “Zephyr codebase” in this context refers to all embedded source code files committed to the main Zephyr repository, except the Zephyr kernel as defined by the Rule A.3: Macro name collisions. With embedded source code we refer to code which is meant to be executed in embedded targets, and therefore excludes host tooling, and code specific for the native test targets.
The following non-ISO 9899:2011, hereinafter referred to as non-standard, functions and macros are exempt from this rule and allowed to be used in the Zephyr codebase:
List of allowed non-standard libc functions Function
Source
POSIX.1-2001
POSIX.1-2008
POSIX.1-2001
All non-standard functions and macros listed above must be implemented by the common libc in order to make sure that these functions can be made available when using a C standard library that does not implement these functions.
Adding a new non-standard function from common C standard libraries to the above list is allowed with justification, given that the above requirement is satisfied. However, when there exists a standard function that is functionally equivalent, the standard function shall be used.
- Rationale
Some C standard libraries, such as Newlib and Picolibc, include additional functions and macros that are defined by the standards and de-facto standards that extend the ISO C standard (e.g. POSIX, Linux).
The ISO/IEC 9899:2011 standard does not require C compiler toolchains to include the support for these non-standard functions, and therefore using these functions can lead to compatibility issues with the third-party toolchains that come with their own C standard libraries.