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:

Stage I (COMPLETED)

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, CI setup and an enforcement strategy.

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.

Important

Current stage: The prerequisites for entering Stage II are currently being looked at: The tooling is in evaluation, CI setup and enforcement strategy is being worked on.

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 equivalent 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.

Main rules

Zephyr rule	Description	MISRA-C 2012 rule	MISRA-C severity	CERT C reference
1	Any implementation-defined behaviour on which the output of the program depends shall be documented and understood	Dir 1.1	Required	MSC09-C
2	All source files shall compile without any compilation errors	Dir 2.1	Required	N/A
3	All code shall be traceable to documented requirements	Dir 3.1	Required	N/A
4	Run-time failures shall be minimized	Dir 4.1	Required	N/A
5	All usage of assembly language should be documented	Dir 4.2	Advisory	N/A
6	Sections of code should not be “commented out”	Dir 4.4	Advisory	MSC04-C
7	Identifiers in the same name space with overlapping visibility should be typographically unambiguous	Dir 4.5	Advisory	DCL02-C
8	typedefs that indicate size and signedness should be used in place of the basic numerical types	Dir 4.6	Advisory	N/A
9	If a function returns error information, then that error information shall be tested	Dir 4.7	Required	N/A
10	If a pointer to a structure or union is never dereferenced within a translation unit, then the implementation of the object should be hidden	Dir 4.8 example 1 Dir 4.8 example 2	Advisory	DCL12-C
11	A function should be used in preference to a function-like macro where they are interchangeable	Dir 4.9	Advisory	PRE00-C
12	Precautions shall be taken in order to prevent the contents of a header file being included more than once	Dir 4.10	Required	PRE06-C
13	The validity of values passed to library functions shall be checked	Dir 4.11	Required	N/A
14	Dynamic memory allocation shall not be used	Dir 4.12	Required	STR01-C
15	Functions which are designed to provide operations on a resource should be called in an appropriate sequence	Dir 4.13	Advisory	N/A
16	The validity of values received from external sources shall be checked	Dir 4.14	Required	N/A
17	Language extensions should not be used	Rule 1.2	Advisory	MSC04-C
18	There shall be no occurrence of undefined or critical unspecified behaviour	Rule 1.3	Required	N/A
19	A project shall not contain unreachable code	Rule 2.1 example 1 Rule 2.1 example 2	Required	MSC07-C
20	There shall be no dead code	Rule 2.2	Required	MSC12-C
21	A project should not contain unused type declarations	Rule 2.3	Advisory	N/A
22	A function should not contain unused label declarations	Rule 2.6	Advisory	N/A
23	There should be no unused parameters in functions	Rule 2.7	Advisory	N/A
24	The character sequences /* and // shall not be used within a comment	Rule 3.1	Required	MSC04-C
25	Line-splicing shall not be used in // comments	Rule 3.2	Required	N/A
26	Octal and hexadecimal escape sequences shall be terminated	Rule 4.1	Required	MSC09-C
27	Trigraphs should not be used	Rule 4.2	Advisory	PRE07-C
28	External identifiers shall be distinct	Rule 5.1 example 1 Rule 5.1 example 2	Required	DCL23-C
29	Identifiers declared in the same scope and name space shall be distinct	Rule 5.2	Required	DCL23-C
30	An identifier declared in an inner scope shall not hide an identifier declared in an outer scope	Rule 5.3	Required	DCL23-C
31	Macro identifiers shall be distinct	Rule 5.4	Required	DCL23-C
32	Identifiers shall be distinct from macro names	Rule 5.5	Required	DCL23-C
33	A typedef name shall be a unique identifier	Rule 5.6	Required	N/A
34	A tag name shall be a unique identifier	Rule 5.7	Required	N/A
35	Identifiers that define objects or functions with external linkage shall be unique	Rule 5.8 example 1 Rule 5.8 example 2	Required	N/A
36	Identifiers that define objects or functions with internal linkage should be unique	Rule 5.9 example 1 Rule 5.9 example 2	Advisory	N/A
37	Bit-fields shall only be declared with an appropriate type	Rule 6.1	Required	INT14-C
38	Single-bit named bit fields shall not be of a signed type	Rule 6.2	Required	INT14-C
39	Octal constants shall not be used	Rule 7.1	Required	DCL18-C
40	A u or U suffix shall be applied to all integer constants that are represented in an unsigned type	Rule 7.2	Required	N/A
41	The lowercase character l shall not be used in a literal suffix	Rule 7.3	Required	DCL16-C
42	A string literal shall not be assigned to an object unless the objects type is pointer to const-qualified char	Rule 7.4	Required	N/A
43	Types shall be explicitly specified	Rule 8.1	Required	N/A
44	Function types shall be in prototype form with named parameters	Rule 8.2	Required	DCL20-C
45	All declarations of an object or function shall use the same names and type qualifiers	Rule 8.3	Required	N/A
46	A compatible declaration shall be visible when an object or function with external linkage is defined	Rule 8.4	Required	N/A
47	An external object or function shall be declared once in one and only one file	Rule 8.5 example 1 Rule 8.5 example 2	Required	N/A
48	An identifier with external linkage shall have exactly one external definition	Rule 8.6 example 1 Rule 8.6 example 2	Required	N/A
49	The static storage class specifier shall be used in all declarations of objects and functions that have internal linkage	Rule 8.8	Required	DCL15-C
50	An object should be defined at block scope if its identifier only appears in a single function	Rule 8.9	Advisory	DCL19-C
51	An inline function shall be declared with the static storage class	Rule 8.10	Required	N/A
52	Within an enumerator list, the value of an implicitly-specified enumeration constant shall be unique	Rule 8.12	Required	INT09-C
53	The restrict type qualifier shall not be used	Rule 8.14	Required	N/A
54	The value of an object with automatic storage duration shall not be read before it has been set	Rule 9.1	Mandatory	N/A
55	The initializer for an aggregate or union shall be enclosed in braces	Rule 9.2	Required	N/A
56	Arrays shall not be partially initialized	Rule 9.3	Required	N/A
57	An element of an object shall not be initialized more than once	Rule 9.4	Required	N/A
58	Where designated initializers are used to initialize an array object the size of the array shall be specified explicitly	Rule 9.5	Required	N/A
59	Operands shall not be of an inappropriate essential type	Rule 10.1	Required	STR04-C
60	Expressions of essentially character type shall not be used inappropriately in addition and subtraction operations	Rule 10.2	Required	STR04-C
61	The value of an expression shall not be assigned to an object with a narrower essential type or of a different essential type category	Rule 10.3	Required	STR04-C
62	Both operands of an operator in which the usual arithmetic conversions are performed shall have the same essential type category	Rule 10.4	Required	STR04-C
63	The value of an expression should not be cast to an inappropriate essential type	Rule 10.5	Advisory	N/A
64	The value of a composite expression shall not be assigned to an object with wider essential type	Rule 10.6	Required	INT02-C
65	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	Rule 10.7	Required	INT02-C
66	The value of a composite expression shall not be cast to a different essential type category or a wider essential type	Rule 10.8	Required	INT02-C
67	Conversions shall not be performed between a pointer to an incomplete type and any other type	Rule 11.2	Required	N/A
68	A cast shall not be performed between pointer to void and an arithmetic type	Rule 11.6	Required	N/A
69	A cast shall not be performed between pointer to object and a noninteger arithmetic type	Rule 11.7	Required	N/A
70	A cast shall not remove any const or volatile qualification from the type pointed to by a pointer	Rule 11.8	Required	EXP05-C
71	The macro NULL shall be the only permitted form of integer null pointer constant	Rule 11.9	Required	N/A
72	The precedence of operators within expressions should be made explicit	Rule 12.1	Advisory	EXP00-C
73	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	Rule 12.2	Required	N/A
74	Evaluation of constant expressions should not lead to unsigned integer wrap-around	Rule 12.4	Advisory	N/A
75	The sizeof operator shall not have an operand which is a function parameter declared as “array of type”	Rule 12.5	Mandatory	N/A
76	Initializer lists shall not contain persistent side effects	Rule 13.1 example 1 Rule 13.1 example 2	Required	N/A
77	The value of an expression and its persistent side effects shall be the same under all permitted evaluation orders	Rule 13.2	Required	N/A
78	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	Rule 13.3	Advisory	N/A
79	The result of an assignment operator should not be used	Rule 13.4	Advisory	N/A
80	The right hand operand of a logical && or || operator shall not contain persistent side effects	Rule 13.5 example 1 Rule 13.5 example 2	Required	EXP10-C
81	The operand of the sizeof operator shall not contain any expression which has potential side effects	Rule 13.6	Mandatory	N/A
82	A loop counter shall not have essentially floating type	Rule 14.1	Required	N/A
83	A for loop shall be well-formed	Rule 14.2	Required	N/A
84	Controlling expressions shall not be invariant	Rule 14.3	Required	N/A
85	The controlling expression of an if statement and the controlling expression of an iteration-statement shall have essentially Boolean type	Rule 14.4	Required	N/A
86	The goto statement shall jump to a label declared later in the same function	Rule 15.2	Required	N/A
87	Any label referenced by a goto statement shall be declared in the same block, or in any block enclosing the goto statement	Rule 15.3	Required	N/A
88	The body of an iteration-statement or a selection-statement shall be a compound-statement	Rule 15.6	Required	EXP19-C
89	All if else if constructs shall be terminated with an else statement	Rule 15.7	Required	N/A
90	All switch statements shall be well-formed	Rule 16.1	Required	N/A
91	A switch label shall only be used when the most closely-enclosing compound statement is the body of a switch statement	Rule 16.2	Required	MSC20-C
92	An unconditional break statement shall terminate every switch-clause	Rule 16.3	Required	N/A
93	Every switch statement shall have a default label	Rule 16.4	Required	N/A
94	A default label shall appear as either the first or the last switch label of a switch statement	Rule 16.5	Required	N/A
95	Every switch statement shall have at least two switch-clauses	Rule 16.6	Required	N/A
96	A switch-expression shall not have essentially Boolean type	Rule 16.7	Required	N/A
97	The features of <stdarg.h> shall not be used	Rule 17.1	Required	ERR00-C
98	Functions shall not call themselves, either directly or indirectly	Rule 17.2	Required	MEM05-C
99	A function shall not be declared implicitly	Rule 17.3	Mandatory	N/A
100	All exit paths from a function with non-void return type shall have an explicit return statement with an expression	Rule 17.4	Mandatory	N/A
101	The function argument corresponding to a parameter declared to have an array type shall have an appropriate number of elements	Rule 17.5	Advisory	N/A
102	The declaration of an array parameter shall not contain the static keyword between the [ ]	Rule 17.6	Mandatory	N/A
103	The value returned by a function having non-void return type shall be used	Rule 17.7	Required	N/A
104	A pointer resulting from arithmetic on a pointer operand shall address an element of the same array as that pointer operand	Rule 18.1	Required	EXP08-C
105	Subtraction between pointers shall only be applied to pointers that address elements of the same array	Rule 18.2	Required	EXP08-C
106	The relational operators >, >=, < and <= shall not be applied to objects of pointer type except where they point into the same object	Rule 18.3	Required	EXP08-C
107	Declarations should contain no more than two levels of pointer nesting	Rule 18.5	Advisory	N/A
108	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	Rule 18.6 example 1 Rule 18.6 example 2	Required	N/A
109	Variable-length array types shall not be used	Rule 18.8	Required	N/A
110	An object shall not be assigned or copied to an overlapping object	Rule 19.1	Mandatory	N/A
111	The ‘, or characters and the /* or // character sequences shall not occur in a header file name”	Rule 20.2	Required	N/A
112	The #include directive shall be followed by either a <filename> or “filename” sequence	Rule 20.3	Required	N/A
113	A macro shall not be defined with the same name as a keyword	Rule 20.4	Required	N/A
114	Expressions resulting from the expansion of macro parameters shall be enclosed in parentheses	Rule 20.7	Required	PRE01-C
115	The controlling expression of a #if or #elif preprocessing directive shall evaluate to 0 or 1	Rule 20.8	Required	N/A
116	All identifiers used in the controlling expression of #if or #elif preprocessing directives shall be #defined before evaluation	Rule 20.9	Required	N/A
117	A macro parameter immediately following a # operator shall not immediately be followed by a ## operator	Rule 20.11	Required	N/A
118	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	Rule 20.12	Required	N/A
119	A line whose first token is # shall be a valid preprocessing directive	Rule 20.13	Required	N/A
120	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	Rule 20.14	Required	N/A
121	#define and #undef shall not be used on a reserved identifier or reserved macro name	Rule 21.1	Required	N/A
122	A reserved identifier or macro name shall not be declared	Rule 21.2	Required	N/A
123	The memory allocation and deallocation functions of <stdlib.h> shall not be used	Rule 21.3	Required	MSC24-C
124	The standard header file <setjmp.h> shall not be used	Rule 21.4	Required	N/A
125	The Standard Library input/output functions shall not be used	Rule 21.6	Required	N/A
126	The atof, atoi, atol and atoll functions of <stdlib.h> shall not be used	Rule 21.7	Required	N/A
127	The library functions bsearch and qsort of <stdlib.h> shall not be used	Rule 21.9	Required	N/A
128	The standard header file <tgmath.h> shall not be used	Rule 21.11	Required	N/A
129	The exception handling features of <fenv.h> should not be used	Rule 21.12	Advisory	N/A
130	Any value passed to a function in <ctype.h> shall be representable as an unsigned char or be the value EO	Rule 21.13	Mandatory	N/A
131	The Standard Library function memcmp shall not be used to compare null terminated strings	Rule 21.14	Required	N/A
132	The pointer arguments to the Standard Library functions memcpy, memmove and memcmp shall be pointers to qualified or unqualified versions of compatible types	Rule 21.15	Required	N/A
133	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	Rule 21.16	Required	N/A
134	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	Rule 21.17	Mandatory	N/A
135	The size_t argument passed to any function in <string.h> shall have an appropriate value	Rule 21.18	Mandatory	N/A
136	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	Rule 21.19	Mandatory	N/A
137	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	Rule 21.20	Mandatory	N/A
138	All resources obtained dynamically by means of Standard Library functions shall be explicitly released	Rule 22.1	Required	N/A
139	A block of memory shall only be freed if it was allocated by means of a Standard Library function	Rule 22.2	Mandatory	N/A
140	The same file shall not be open for read and write access at the same time on different streams	Rule 22.3	Required	N/A
141	There shall be no attempt to write to a stream which has been opened as read-only	Rule 22.4	Mandatory	N/A
142	A pointer to a FILE object shall not be dereferenced	Rule 22.5	Mandatory	N/A
143	The value of a pointer to a FILE shall not be used after the associated stream has been closed	Rule 22.6	Mandatory	N/A
144	The macro EOF shall only be compared with the unmodified return value from any Standard Library function capable of returning EOF	Rule 22.7	Required	N/A
145	The value of errno shall be set to zero prior to a call to an errno-setting-function	Rule 22.8	Required	N/A
146	The value of errno shall be tested against zero after calling an errno-setting-function	Rule 22.9	Required	N/A
147	The value of errno shall only be tested when the last function to be called was an errno-setting-function	Rule 22.10	Required	N/A

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
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
Inter-Integrated Circuit (I2C) Bus	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.
Inter-IC Sound (I2S) Bus	master / slave => TBD
SMP/AMP	master / slave => TBD
Serial Peripheral Interface (SPI) Bus	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

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:

List of allowed libc functions and macros in the Zephyr kernel

Function	Source
abort()	ISO/IEC 9899:2011
abs()	ISO/IEC 9899:2011
aligned_alloc()	ISO/IEC 9899:2011
assert()	ISO/IEC 9899:2011
atoi()	ISO/IEC 9899:2011
bsearch()	ISO/IEC 9899:2011
calloc()	ISO/IEC 9899:2011
exit()	ISO/IEC 9899:2011
fprintf()	ISO/IEC 9899:2011
fputc()	ISO/IEC 9899:2011
fputs()	ISO/IEC 9899:2011
free()	ISO/IEC 9899:2011
fwrite()	ISO/IEC 9899:2011
gmtime()	ISO/IEC 9899:2011
isalnum()	ISO/IEC 9899:2011
isalpha()	ISO/IEC 9899:2011
iscntrl()	ISO/IEC 9899:2011
isdigit()	ISO/IEC 9899:2011
isgraph()	ISO/IEC 9899:2011
isprint()	ISO/IEC 9899:2011
isspace()	ISO/IEC 9899:2011
isupper()	ISO/IEC 9899:2011
isxdigit()	ISO/IEC 9899:2011
labs()	ISO/IEC 9899:2011
llabs()	ISO/IEC 9899:2011
malloc()	ISO/IEC 9899:2011
memchr()	ISO/IEC 9899:2011
memcmp()	ISO/IEC 9899:2011
memcpy()	ISO/IEC 9899:2011
memmove()	ISO/IEC 9899:2011
memset()	ISO/IEC 9899:2011
perror()	ISO/IEC 9899:2011
printf()	ISO/IEC 9899:2011
putc()	ISO/IEC 9899:2011
putchar()	ISO/IEC 9899:2011
puts()	ISO/IEC 9899:2011
qsort()	ISO/IEC 9899:2011
rand()	ISO/IEC 9899:2011
realloc()	ISO/IEC 9899:2011
snprintf()	ISO/IEC 9899:2011
sprintf()	ISO/IEC 9899:2011
sqrt()	ISO/IEC 9899:2011
sqrtf()	ISO/IEC 9899:2011
srand()	ISO/IEC 9899:2011
strcat()	ISO/IEC 9899:2011
strchr()	ISO/IEC 9899:2011
strcmp()	ISO/IEC 9899:2011
strcpy()	ISO/IEC 9899:2011
strcspn()	ISO/IEC 9899:2011
strerror()	ISO/IEC 9899:2011
strlen()	ISO/IEC 9899:2011
strncat()	ISO/IEC 9899:2011
strncmp()	ISO/IEC 9899:2011
strncpy()	ISO/IEC 9899:2011
strnlen()	POSIX.1-2008
strrchr()	ISO/IEC 9899:2011
strspn()	ISO/IEC 9899:2011
strstr()	ISO/IEC 9899:2011
strtol()	ISO/IEC 9899:2011
strtoll()	ISO/IEC 9899:2011
strtoul()	ISO/IEC 9899:2011
strtoull()	ISO/IEC 9899:2011
time()	ISO/IEC 9899:2011
tolower()	ISO/IEC 9899:2011
toupper()	ISO/IEC 9899:2011
vfprintf()	ISO/IEC 9899:2011
vprintf()	ISO/IEC 9899:2011
vsnprintf()	ISO/IEC 9899:2011
vsprintf()	ISO/IEC 9899:2011

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.4: C Standard Library Usage Restrictions in Zephyr Kernel. 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
gmtime_r()	POSIX.1-2001
strnlen()	POSIX.1-2008
strtok_r()	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.