Coding Guidelines

The project TSC and the Safety Committee of the project agreed to implement a staged and incremental approach for complying with a set of coding rules (AKA Coding Guidelines) to improve quality and consistency of the code base. Below are the agreed upon stages and the approximate timelines:

Stage I

Coding guideline rules are available to be followed and referenced, but not enforced. Rules are not yet enforced in CI and pull-requests cannot be blocked by reviewers/approvers due to violations.

Stage II

Begin enforcement on a limited scope of the code base. Initially, this would be the safety certification scope. For rules easily applied across codebase, we should not limit compliance to initial scope. This step requires tooling and CI setup and will start sometime after LTS2.

Stage III

Revisit the coding guideline rules and based on experience from previous stages, refine/iterate on selected rules.

Stage IV

Expand enforcement to the wider codebase. Exceptions may be granted on some areas of the codebase with a proper justification. Exception would require TSC approval.

Note

Coding guideline rules may be removed/changed at any time by filing a GH issue/RFC.

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 severity and the equivlent rules from other standards for reference.

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.

Table 1 Main rules

MISRA C 2012

Severity

Description

CERT C

Example

Dir 1.1

Required

Any implementation-defined behaviour on which the output of the program depends shall be documented and understood

MSC09-C

Dir 1.1

Dir 2.1

Required

All source files shall compile without any compilation errors

N/A

Dir 2.1

Dir 3.1

Required

All code shall be traceable to documented requirements

N/A

Dir 3.1

Dir 4.1

Required

Run-time failures shall be minimized

N/A

Dir 4.1

Dir 4.2

Advisory

All usage of assembly language should be documented

N/A

Dir 4.2

Dir 4.4

Advisory

Sections of code should not be “commented out”

MSC04-C

Dir 4.4

Dir 4.5

Advisory

Identifiers in the same name space with overlapping visibility should be typographically unambiguous

DCL02-C

Dir 4.5

Dir 4.6

Advisory

typedefs that indicate size and signedness should be used in place of the basic numerical types

N/A

Dir 4.6

Dir 4.7

Required

If a function returns error information, then that error information shall be tested

N/A

Dir 4.7

Dir 4.8

Advisory

If a pointer to a structure or union is never dereferenced within a translation unit, then the implementation of the object should be hidden

DCL12-C

Dir 4.9

Advisory

A function should be used in preference to a function-like macro where they are interchangeable

PRE00-C

Dir 4.9

Dir 4.10

Required

Precautions shall be taken in order to prevent the contents of a header file being included more than once

PRE06-C

Dir 4.10

Dir 4.11

Required

The validity of values passed to library functions shall be checked

N/A

Dir 4.11

Dir 4.12

Required

Dynamic memory allocation shall not be used

STR01-C

Dir 4.12

Dir 4.13

Advisory

Functions which are designed to provide operations on a resource should be called in an appropriate sequence

N/A

Dir 4.13

Dir 4.14

Required

The validity of values received from external sources shall be checked

N/A

Dir 4.14

Rule 1.2

Advisory

Language extensions should not be used

MSC04-C

Rule 1.2

Rule 1.3

Required

There shall be no occurrence of undefined or critical unspecified behaviour

N/A

Rule 1.3

Rule 2.1

Required

A project shall not contain unreachable code

MSC07-C

Rule 2.2

Required

There shall be no dead code

MSC12-C

Rule 2.2

Rule 2.3

Advisory

A project should not contain unused type declarations

N/A

Rule 2.3

Rule 2.6

Advisory

A function should not contain unused label declarations

N/A

Rule 2.6

Rule 2.7

Advisory

There should be no unused parameters in functions

N/A

Rule 2.7

Rule 3.1

Required

The character sequences /* and // shall not be used within a comment

MSC04-C

Rule 3.1

Rule 3.2

Required

Line-splicing shall not be used in // comments

N/A

Rule 3.2

Rule 4.1

Required

Octal and hexadecimal escape sequences shall be terminated

MSC09-C

Rule 4.1

Rule 4.2

Advisory

Trigraphs should not be used

PRE07-C

Rule 4.2

Rule 5.1

Required

External identifiers shall be distinct

DCL23-C

Rule 5.2

Required

Identifiers declared in the same scope and name space shall be distinct

DCL23-C

Rule 5.2

Rule 5.3

Required

An identifier declared in an inner scope shall not hide an identifier declared in an outer scope

DCL23-C

Rule 5.3

Rule 5.4

Required

Macro identifiers shall be distinct

DCL23-C

Rule 5.4

Rule 5.5

Required

Identifiers shall be distinct from macro names

DCL23-C

Rule 5.5

Rule 5.6

Required

A typedef name shall be a unique identifier

N/A

Rule 5.6

Rule 5.7

Required

A tag name shall be a unique identifier

N/A

Rule 5.7

Rule 5.8

Required

Identifiers that define objects or functions with external linkage shall be unique

N/A

Rule 5.9

Advisory

Identifiers that define objects or functions with internal linkage should be unique

N/A

Rule 6.1

Required

Bit-fields shall only be declared with an appropriate type

INT14-C

Rule 6.1

Rule 6.2

Required

Single-bit named bit fields shall not be of a signed type

INT14-C

Rule 6.2

Rule 7.1

Required

Octal constants shall not be used

DCL18-C

Rule 7.1

Rule 7.2

Required

A u or U suffix shall be applied to all integer constants that are represented in an unsigned type

N/A

Rule 7.2

Rule 7.3

Required

The lowercase character l shall not be used in a literal suffix

DCL16-C

Rule 7.3

Rule 7.4

Required

A string literal shall not be assigned to an object unless the objects type is pointer to const-qualified char

N/A

Rule 7.4

Rule 8.1

Required

Types shall be explicitly specified

N/A

Rule 8.1

Rule 8.2

Required

Function types shall be in prototype form with named parameters

DCL20-C

Rule 8.2

Rule 8.3

Required

All declarations of an object or function shall use the same names and type qualifiers

N/A

Rule 8.3

Rule 8.4

Required

A compatible declaration shall be visible when an object or function with external linkage is defined

N/A

Rule 8.4

Rule 8.5

Required

An external object or function shall be declared once in one and only one file

N/A

Rule 8.6

Required

An identifier with external linkage shall have exactly one external definition

N/A

Rule 8.8

Required

The static storage class specifier shall be used in all declarations of objects and functions that have internal linkage

DCL15-C

Rule 8.8

Rule 8.9

Advisory

An object should be defined at block scope if its identifier only appears in a single function

DCL19-C

Rule 8.9

Rule 8.10

Required

An inline function shall be declared with the static storage class

N/A

Rule 8.10

Rule 8.12

Required

Within an enumerator list, the value of an implicitly-specified enumeration constant shall be unique

INT09-C

Rule 8.12

Rule 8.14

Required

The restrict type qualifier shall not be used

N/A

Rule 8.14

Rule 9.1

Mandatory

The value of an object with automatic storage duration shall not be read before it has been set

N/A

Rule 9.1

Rule 9.2

Required

The initializer for an aggregate or union shall be enclosed in braces

N/A

Rule 9.2

Rule 9.3

Required

Arrays shall not be partially initialized

N/A

Rule 9.3

Rule 9.4

Required

An element of an object shall not be initialized more than once

N/A

Rule 9.4

Rule 9.5

Required

Where designated initializers are used to initialize an array object the size of the array shall be specified explicitly

N/A

Rule 9.5

Rule 10.1

Required

Operands shall not be of an inappropriate essential type

STR04-C

Rule 10.1

Rule 10.2

Required

Expressions of essentially character type shall not be used inappropriately in addition and subtraction operations

STR04-C

Rule 10.2

Rule 10.3

Required

The value of an expression shall not be assigned to an object with a narrower essential type or of a dierent essential type category

STR04-C

Rule 10.3

Rule 10.4

Required

Both operands of an operator in which the usual arithmetic conversions are performed shall have the same essential type category

STR04-C

Rule 10.4

Rule 10.5

Advisory

The value of an expression should not be cast to an inappropriate essential type

N/A

Rule 10.5

Rule 10.6

Required

The value of a composite expression shall not be assigned to an object with wider essential type

INT02-C

Rule 10.6

Rule 10.7

Required

If a composite expression is used as one operand of an operator in which the usual arithmetic conversions are performed then the other operand shall not have wider essential type

INT02-C

Rule 10.7

Rule 10.8

Required

The value of a composite expression shall not be cast to a different essential type category or a wider essential type

INT02-C

Rule 10.8

Rule 11.2

Required

Conversions shall not be performed between a pointer to an incomplete type and any other type

N/A

Rule 11.2

Rule 11.6

Required

A cast shall not be performed between pointer to void and an arithmetic type

N/A

Rule 11.6

Rule 11.7

Required

A cast shall not be performed between pointer to object and a noninteger arithmetic type

N/A

Rule 11.7

Rule 11.8

Required

A cast shall not remove any const or volatile qualification from the type pointed to by a pointer

EXP05-C

Rule 11.8

Rule 11.9

Required

The macro NULL shall be the only permitted form of integer null pointer constant

N/A

Rule 11.9

Rule 12.1

Advisory

The precedence of operators within expressions should be made explicit

EXP00-C

Rule 12.1

Rule 12.2

Required

The right hand operand of a shift operator shall lie in the range zero to one less than the width in bits of the essential type of the left hand operand

N/A

Rule 12.2

Rule 12.4

Advisory

Evaluation of constant expressions should not lead to unsigned integer wrap-around

N/A

Rule 12.4

Rule 12.5

Mandatory

The sizeof operator shall not have an operand which is a function parameter declared as “array of type”

N/A

Rule 12.5

Rule 13.1

Required

Initializer lists shall not contain persistent side effects

N/A

Rule 13.2

Required

The value of an expression and its persistent side effects shall be the same under all permitted evaluation orders

N/A

Rule 13.2

Rule 13.3

Advisory

A full expression containing an increment (++) or decrement (–) operator should have no other potential side effects other than that caused by the increment or decrement operator

N/A

Rule 13.3

Rule 13.4

Advisory

The result of an assignment operator should not be used

N/A

Rule 13.4

Rule 13.5

Required

The right hand operand of a logical && or || operator shall not contain persistent side effects

EXP10-C

Rule 13.6

Mandatory

The operand of the sizeof operator shall not contain any expression which has potential side effects

N/A

Rule 13.6

Rule 14.1

Required

A loop counter shall not have essentially floating type

N/A

Rule 14.1

Rule 14.2

Required

A for loop shall be well-formed

N/A

Rule 14.2

Rule 14.3

Required

Controlling expressions shall not be invariant

N/A

Rule 14.3

Rule 14.4

Required

The controlling expression of an if statement and the controlling expression of an iteration-statement shall have essentially Boolean type

N/A

Rule 14.4

Rule 15.2

Required

The goto statement shall jump to a label declared later in the same function

N/A

Rule 15.2

Rule 15.3

Required

Any label referenced by a goto statement shall be declared in the same block, or in any block enclosing the goto statement

N/A

Rule 15.3

Rule 15.6

Required

The body of an iteration-statement or a selection-statement shall be a compound-statement

EXP19-C

Rule 15.6

Rule 15.7

Required

All if else if constructs shall be terminated with an else statement

N/A

Rule 15.7

Rule 16.1

Required

All switch statements shall be well-formed

N/A

Rule 16.1

Rule 16.2

Required

A switch label shall only be used when the most closely-enclosing compound statement is the body of a switch statement

MSC20-C

Rule 16.2

Rule 16.3

Required

An unconditional break statement shall terminate every switch-clause

N/A

Rule 16.3

Rule 16.4

Required

Every switch statement shall have a default label

N/A

Rule 16.4

Rule 16.5

Required

A default label shall appear as either the first or the last switch label of a switch statement

N/A

Rule 16.5

Rule 16.6

Required

Every switch statement shall have at least two switch-clauses

N/A

Rule 16.6

Rule 16.7

Required

A switch-expression shall not have essentially Boolean type

N/A

Rule 16.7

Rule 17.1

Required

The features of <stdarg.h> shall not be used

ERR00-C

Rule 17.1

Rule 17.2

Required

Functions shall not call themselves, either directly or indirectly

MEM05-C

Rule 17.2

Rule 17.3

Mandatory

A function shall not be declared implicitly

N/A

Rule 17.3

Rule 17.4

Mandatory

All exit paths from a function with non-void return type shall have an explicit return statement with an expression

N/A

Rule 17.4

Rule 17.5

Advisory

The function argument corresponding to a parameter declared to have an array type shall have an appropriate number of elements

N/A

Rule 17.5

Rule 17.6

Mandatory

The declaration of an array parameter shall not contain the static keyword between the [ ]

N/A

Rule 17.6

Rule 17.7

Required

The value returned by a function having non-void return type shall be used

N/A

Rule 17.7

Rule 18.1

Required

A pointer resulting from arithmetic on a pointer operand shall address an element of the same array as that pointer operand

EXP08-C

Rule 18.1

Rule 18.2

Required

Subtraction between pointers shall only be applied to pointers that address elements of the same array

EXP08-C

Rule 18.2

Rule 18.3

Required

The relational operators >, >=, < and <= shall not be applied to objects of pointer type except where they point into the same object

EXP08-C

Rule 18.3

Rule 18.5

Advisory

Declarations should contain no more than two levels of pointer nesting

N/A

Rule 18.5

Rule 18.6

Required

The address of an object with automatic storage shall not be copied to another object that persists after the first object has ceased to exist

N/A

Rule 18.8

Required

Variable-length array types shall not be used

N/A

Rule 18.8

Rule 19.1

Mandatory

An object shall not be assigned or copied to an overlapping object

N/A

Rule 19.1

Rule 20.2

Required

The ‘, or characters and the /* or // character sequences shall not occur in a header file name”

N/A

Rule 20.2

Rule 20.3

Required

The #include directive shall be followed by either a <filename> or “filename” sequence

N/A

Rule 20.3

Rule 20.4

Required

A macro shall not be defined with the same name as a keyword

N/A

Rule 20.4

Rule 20.7

Required

Expressions resulting from the expansion of macro parameters shall be enclosed in parentheses

PRE01-C

Rule 20.7

Rule 20.8

Required

The controlling expression of a #if or #elif preprocessing directive shall evaluate to 0 or 1

N/A

Rule 20.8

Rule 20.9

Required

All identifiers used in the controlling expression of #if or #elif preprocessing directives shall be #defined before evaluation

N/A

Rule 20.9

Rule 20.11

Required

A macro parameter immediately following a # operator shall not immediately be followed by a ## operator

N/A

Rule 20.11

Rule 20.12

Required

A macro parameter used as an operand to the # or ## operators, which is itself subject to further macro replacement, shall only be used as an operand to these operators

N/A

Rule 20.12

Rule 20.13

Required

A line whose first token is # shall be a valid preprocessing directive

N/A

Rule 20.13

Rule 20.14

Required

All #else, #elif and #endif preprocessor directives shall reside in the same file as the #if, #ifdef or #ifndef directive to which they are related

N/A

Rule 20.14

Rule 21.1

Required

#define and #undef shall not be used on a reserved identifier or reserved macro name

N/A

Rule 21.1

Rule 21.2

Required

A reserved identifier or macro name shall not be declared

N/A

Rule 21.2

Rule 21.3

Required

The memory allocation and deallocation functions of <stdlib.h> shall not be used

MSC24-C

Rule 21.3

Rule 21.4

Required

The standard header file <setjmp.h> shall not be used

N/A

Rule 21.4

Rule 21.6

Required

The Standard Library input/output functions shall not be used

N/A

Rule 21.6

Rule 21.7

Required

The atof, atoi, atol and atoll functions of <stdlib.h> shall not be used

N/A

Rule 21.7

Rule 21.9

Required

The library functions bsearch and qsort of <stdlib.h> shall not be used

N/A

Rule 21.9

Rule 21.11

Required

The standard header file <tgmath.h> shall not be used

N/A

Rule 21.11

Rule 21.12

Advisory

The exception handling features of <fenv.h> should not be used

N/A

Rule 21.12

Rule 21.13

Mandatory

Any value passed to a function in <ctype.h> shall be representable as an unsigned char or be the value EO

N/A

Rule 21.13

Rule 21.14

Required

The Standard Library function memcmp shall not be used to compare null terminated strings

N/A

Rule 21.14

Rule 21.15

Required

The pointer arguments to the Standard Library functions memcpy, memmove and memcmp shall be pointers to qualified or unqualified versions of compatible types

N/A

Rule 21.15

Rule 21.16

Required

The pointer arguments to the Standard Library function memcmp shall point to either a pointer type, an essentially signed type, an essentially unsigned type, an essentially Boolean type or an essentially enum type

N/A

Rule 21.16

Rule 21.17

Mandatory

Use of the string handling functions from <string.h> shall not result in accesses beyond the bounds of the objects referenced by their pointer parameters

N/A

Rule 21.17

Rule 21.18

Mandatory

The size_t argument passed to any function in <string.h> shall have an appropriate value

N/A

Rule 21.18

Rule 21.19

Mandatory

The pointers returned by the Standard Library functions localeconv, getenv, setlocale or, strerror shall only be used as if they have pointer to const-qualified type

N/A

Rule 21.19

Rule 21.20

Mandatory

The pointer returned by the Standard Library functions asctime, ctime, gmtime, localtime, localeconv, getenv, setlocale or strerror shall not be used following a subsequent call to the same function

N/A

Rule 21.20

Rule 22.1

Required

All resources obtained dynamically by means of Standard Library functions shall be explicitly released

N/A

Rule 22.1

Rule 22.2

Mandatory

A block of memory shall only be freed if it was allocated by means of a Standard Library function

N/A

Rule 22.2

Rule 22.3

Required

The same file shall not be open for read and write access at the same time on different streams

N/A

Rule 22.3

Rule 22.4

Mandatory

There shall be no attempt to write to a stream which has been opened as read-only

N/A

Rule 22.4

Rule 22.5

Mandatory

A pointer to a FILE object shall not be dereferenced

N/A

Rule 22.5

Rule 22.6

Mandatory

The value of a pointer to a FILE shall not be used after the associated stream has been closed

N/A

Rule 22.6

Rule 22.7

Required

The macro EOF shall only be compared with the unmodified return value from any Standard Library function capable of returning EOF

N/A

Rule 22.7

Rule 22.8

Required

The value of errno shall be set to zero prior to a call to an errno-setting-function

N/A

Rule 22.8

Rule 22.9

Required

The value of errno shall be tested against zero after calling an errno-setting-function

N/A

Rule 22.9

Rule 22.10

Required

The value of errno shall only be tested when the last function to be called was an errno-setting-function

N/A

Rule 22.10

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 / performer

  • central / peripheral

blacklist / whitelist

  • denylist / allowlist

  • blocklist / allowlist

  • rejectlist / acceptlist

grandfather policy

  • legacy

sanity

  • coherence

  • confidence

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

Bluetooth

See Bluetooth Appropriate Language Mapping Tables

eSPI

  • master / slave => TBD

gPTP

  • master / slave => TBD

I2C

  • master / slave => TBD

NXP publishes the I2C Specification and has selected controller / target as replacement terms, but the timing to publish an announcement or new specification is TBD. Zephyr will update I2C when replacement terminology is confirmed by a public announcement or updated specification.

See Zephyr issue 27033.

I2S

  • master / slave => TBD

SMP/AMP

  • master / slave => TBD

SPI

  • master / slave => controller / peripheral

  • MOSI / MISO / SS => SDO / SDI / CS

The Open Source Hardware Association has selected these replacement terms. See OSHWA Resolution to Redefine SPI Signal Names

Test Runner (Twister)

  • platform_whitelist => platform_allow

  • sanitycheck => twister

Parasoft Codescan Tool

Parasoft Codescan is an official static code analysis tool used by the Zephyr project. It is used to automate compliance with a range of coding and security standards. The tool is currently set to the MISRA-C:2012 Coding Standard because the Zephyr Coding Guidelines are based on that standard. It is used together with the Coverity Scan tool to achieve the best code health and precision in bug findings.

Violations fixing process

Step 1

Any Zephyr Project member, company or a developer can request access to the Parasoft reporting centre if they wish to get involved in fixing violations by submitting issues.

Step 2

A developer starts to review violations.

Step 3

A developer submits a Github PR with the fix. Commit messages should follow the same guidelines as other PRs in the Zephyr project. Please add a comment that your fix was found by a static coding scanning tool. Developers should follow and refer to the Zephyr Coding Guidelines as basic rules for coding. These rules are based on the MISRA-C standard.

Below you can find an example of a recommended commit message:

lib: os: add braces to 'if' statements

An 'if' (expression) construct shall be followed by a compound statement.
Add braces to improve readability and maintainability.

Found as a coding guideline violation (Rule 15.6) by static
coding scanning tool.

Signed-off-by: Johnny Developer <johnny.developer@company.com>
Step 4

If a violation is a false positive, the developer should mark it for the Codescan tool just like they would do for the Coverity tool. The developer should also add a comment to the code explaining that the violation raised by the static code analysis tool should be considered a false positive.

Step 5

If the developer has found a real violation that the community decided to ignore, the developer must submit a PR with a suppression tag and a comment explaining why the violation has been deviated. The template structure of the comment and tag in the code should be:

/* Explain why that part of the code doesn't follow the standard,
 * explain why it is a deliberate deviation from the standard.
 * Don't refer to the Parasoft tool here, just mention that static code
 * analysis tool raised a violation in the line below.
 */
code_line_with_a_violation /* parasoft-suppress Rule ID */

Below you can find an example of a recommended commit message:

testsuite: suppress usage of setjmp in a testcode (rule 21.4)

According to the Rule 21.4 the standard header file <setjmp.h> shall not
be used. We will suppress this violation because it is in
test code. Tag suppresses reporting of the violation for the
line where the violation is located.
This is a deliberate deviation.

Found as a coding guideline violation (Rule 21.4) by static coding
scanning tool.

Signed-off-by: Johnny Developer <johnny.developer@company.com>

The example below demonstrates how deviations can be suppressed in the code:

/* Static code analysis tool can raise a violation that the standard
 * header <setjmp.h> shall not be used.
 * Since this violation is in test code, we will suppress it.
 * Deliberate deviation.
 */
#include <setjmp.h> /* parasoft-suppress MISRAC2012-RULE_21_4-a MISRAC2012-RULE_21_4-b */

This variant above suppresses item MISRAC2012-RULE_21_4-a and MISRAC2012-RULE_21_4-b on the line with “setjump” header include. You can add as many rules to suppress you want - just make sure to keep the Parasoft tag on one line and separate rules with a space. To read more about suppressing findings in the Parasoft tool, refer to the official Parasoft documentation

Step 6

After a PR is submitted, the developer should add the Coding guidelines and MISRA-C Github labels so their PR can be easily tracked by maintainers. If you have any concerns about what your PR should look like, you can search on Github using those tags and refer to similar PRs that have already been merged.