3.4.Coding Style

The following sections outline theTF-A coding style forC code. The styleis based on theLinux kernel coding style, with a few modifications.

The style should not be consideredset in stone. Feel free to provide feedbackand suggestions.

Note

You will almost certainly find code in theTF-A repository that does notfollow the style. The intent is for all code to do so eventually.

3.4.1.File Encoding

The source code must use theUTF-8 character encoding. Comments anddocumentation may use non-ASCII characters when required (e.g. Greek lettersused for units) but code itself is still limited to ASCII characters.

Newlines must be inUnix style, which means that only the Line Feed (LF)character is used to break a line and reset to the first column.

3.4.2.Language

The primary language for comments and naming must be International English. Incases where there is a conflict between the American English and British Englishspellings of a word, the American English spelling is used.

Exceptions are made when referring directly to something that does not useinternational style, such as the name of a company. In these cases the existingname should be used as-is.

3.4.3.C Language Standard

The C language mode used for TF-A isGNU99. This is the “GNU dialect of ISOC99”, which implies theISO C99 standard with GNU extensions.

Both GCC and Clang compiler toolchains have support forGNU99 mode, thoughClang does lack support for a small number of GNU extensions. Thesemissing extensions are rarely used, however, and should not pose a problem.

3.4.4.MISRA Compliance

TF-A attempts to comply with theMISRA C:2012 Guidelines.ECLAIR staticanalysis is used to regularly generate a report of current MISRA defects and toprevent the addition of new ones.

It is not possible for the project to follow all MISRA guidelines. Table 1below lists all rules and directives and whether we aim to comply with them ornot. A rationale is given for each deviation.

Note

Enforcing a rule does not mean that the codebase is free of defectsof that rule, only that they would ideally be removed.

Note

Third-party libraries are not considered in our MISRA analysis and we do notintend to modify them to make them MISRA compliant.

Table 1: MISRA compliance in TF-A code base
Seq	Dir / Rule	Number	Source	Category	Checker Enabled	Enforced	Comments
1	D	1.1	MISRA C 2012	Required	N/A	Yes
2	D	2.1	MISRA C 2012	Required	N/A	Yes
3	D	3.1	MISRA C 2012	Required	N/A	No	It can’t be done retroactively.
4	D	4.1	MISRA C 2012	Required	N/A	Yes
5	D	4.2	MISRA C 2012	Advisory	N/A	Yes
6	D	4.3	MISRA C 2012	Required	Yes	Yes
7	D	4.4	MISRA C 2012	Advisory	Yes	Yes
8	D	4.5	MISRA C 2012	Advisory	Yes	Yes
9	D	4.6	MISRA C 2012	Advisory	No	No	We use a mix of both. It would be too disruptive for the project to change.
10	D	4.7	MISRA C 2012	Required	Yes	Yes
11	D	4.8	MISRA C 2012	Advisory	No	No	Fixing all instances would involve invasive changes to the codebase for no good reason.
12	D	4.9	MISRA C 2012	Advisory	No	No	We mustn’t introduce new macros unless strictly needed, but this affects assert(), INFO(), etc. It creates too much noise in the report for little gain.
13	D	4.10	MISRA C 2012	Required	Yes	Yes
14	D	4.11	MISRA C 2012	Required	Yes	Yes
15	D	4.12	MISRA C 2012	Required	Yes	Yes
16	D	4.13	MISRA C 2012	Advisory	Yes	Yes
17	D	4.14	MISRA C 2012 AMD-1	Required	Yes	Yes
18	R	1.1	MISRA C 2012	Required	Yes	Yes
19	R	1.2	MISRA C 2012	Advisory	Yes	Optional	It bans __attribute__(()) and similar helpers.
20	R	1.3	MISRA C 2012	Required	N/A	Yes
21	R	2.1	MISRA C 2012	Required	Yes	Yes
22	R	2.2	MISRA C 2012	Required	Yes	Yes
23	R	2.3	MISRA C 2012	Advisory	Yes	Optional	It prevents the usage of CASSERT().
24	R	2.4	MISRA C 2012	Advisory	No	No	Header files may use enumerations instead of defines to group sets of values.
25	R	2.5	MISRA C 2012	Advisory	No	No	We define many headers with macros that are unused in the project but may be used by non-upstream code or may be desirable for completeness.
26	R	2.6	MISRA C 2012	Advisory	Yes	Yes
27	R	2.7	MISRA C 2012	Advisory	No	No	Doesn’t allow for simple implementations of porting functions that don’t require all parameters.
28	R	3.1	MISRA C 2012	Required	Yes	Yes
29	R	3.2	MISRA C 2012	Required	Yes	Yes
30	R	4.1	MISRA C 2012	Required	Yes	Yes
31	R	4.2	MISRA C 2012	Advisory	Yes	Yes
32	R	5.1	MISRA C 2012	Required	No	No	We use weak symbols that prevent us from complying with this rule.
33	R	5.2	MISRA C 2012	Required	Yes	Yes
34	R	5.3	MISRA C 2012	Required	Yes	Yes
35	R	5.4	MISRA C 2012	Required	Yes	Yes
36	R	5.5	MISRA C 2012	Required	Yes	Yes
37	R	5.6	MISRA C 2012	Required	Yes	Yes
38	R	5.7	MISRA C 2012	Required	Yes	Optional	Fixing all existing defects is problematic because of compatibility issues.
39	R	5.8	MISRA C 2012	Required	No	No	We use weak symbols that prevent us from complying with this rule.
40	R	5.9	MISRA C 2012	Advisory	Yes	Yes
41	R	6.1	MISRA C 2012	Required	Yes	Yes
42	R	6.2	MISRA C 2012	Required	Yes	Yes
43	R	7.1	MISRA C 2012	Required	Yes	Yes
44	R	7.2	MISRA C 2012	Required	Yes	Yes
45	R	7.3	MISRA C 2012	Required	Yes	Yes
46	R	7.4	MISRA C 2012	Required	Yes	Yes
47	R	8.1	MISRA C 2012	Required	Yes	Yes
48	R	8.2	MISRA C 2012	Required	Yes	Yes
49	R	8.3	MISRA C 2012	Required	Yes	Yes
50	R	8.4	MISRA C 2012	Required	Yes	Yes
51	R	8.5	MISRA C 2012	Required	Yes	Yes
52	R	8.6	MISRA C 2012	Required	No	No	We use weak symbols that prevent us from complying with this rule.
53	R	8.7	MISRA C 2012	Advisory	No	No	Bans pattern of declaring funcs in private header that are used/defined in separate translation units, which seems over the top.
54	R	8.8	MISRA C 2012	Required	Yes	Yes
55	R	8.9	MISRA C 2012	Advisory	Yes	Yes
56	R	8.10	MISRA C 2012	Required	Yes	Yes
57	R	8.11	MISRA C 2012	Advisory	Yes	Optional	This may not be possible in some interfaces.
58	R	8.12	MISRA C 2012	Required	Yes	Yes
59	R	8.13	MISRA C 2012	Advisory	Yes	Optional	The benefits of fixing existing code aren’t worth the effort.
60	R	8.14	MISRA C 2012	Required	Yes	Yes
61	R	9.1	MISRA C 2012	Mandatory	Yes	Yes
62	R	9.2	MISRA C 2012	Required	Yes	Yes
63	R	9.3	MISRA C 2012	Required	Yes	Yes
64	R	9.4	MISRA C 2012	Required	Yes	Yes
65	R	9.5	MISRA C 2012	Required	Yes	Yes
66	R	10.1	MISRA C 2012	Required	Yes	Optional	Fixing existing code may be counter-productive and introduce bugs.
67	R	10.2	MISRA C 2012	Required	Yes	Yes
68	R	10.3	MISRA C 2012	Required	Yes	Optional	Fixing existing code may be counter-productive and introduce bugs.
69	R	10.4	MISRA C 2012	Required	Yes	Optional	Fixing existing code may be counter-productive and introduce bugs.
70	R	10.5	MISRA C 2012	Advisory	Yes	Yes
71	R	10.6	MISRA C 2012	Required	Yes	Yes
72	R	10.7	MISRA C 2012	Required	Yes	Yes
73	R	10.8	MISRA C 2012	Required	Yes	Yes
74	R	11.1	MISRA C 2012	Required	Yes	Yes
75	R	11.2	MISRA C 2012	Required	Yes	Yes
76	R	11.3	MISRA C 2012	Required	Yes	Yes
77	R	11.4	MISRA C 2012	Advisory	No	No	This would be invasive for TF (e.g. in exported linker script macros). Also bans conversion from uintptr_t.
78	R	11.5	MISRA C 2012	Advisory	No	No	This seems to preclude the pattern of using void * in interfaces to hide the real object, which we use extensively.
79	R	11.6	MISRA C 2012	Required	Yes	Optional	This is needed in several cases.
80	R	11.7	MISRA C 2012	Required	Yes	Yes
81	R	11.8	MISRA C 2012	Required	Yes	Yes
82	R	11.9	MISRA C 2012	Required	Yes	Yes
83	R	12.1	MISRA C 2012	Advisory	Yes	Yes
84	R	12.2	MISRA C 2012	Required	Yes	Yes	This rule is fine, but there are lots of false positives in Coverity.
85	R	12.3	MISRA C 2012	Advisory	Yes	Yes
86	R	12.4	MISRA C 2012	Advisory	Yes	Yes
87	R	12.5	MISRA C 2012 AMD-1	Mandatory	Yes	Yes
88	R	13.1	MISRA C 2012	Required	Yes	Yes
89	R	13.2	MISRA C 2012	Required	Yes	Yes
90	R	13.3	MISRA C 2012	Advisory	Yes	Yes
91	R	13.4	MISRA C 2012	Advisory	Yes	Yes
92	R	13.5	MISRA C 2012	Required	Yes	Yes
93	R	13.6	MISRA C 2012	Mandatory	Yes	Yes
94	R	14.1	MISRA C 2012	Required	Yes	Yes
95	R	14.2	MISRA C 2012	Required	Yes	Yes
96	R	14.3	MISRA C 2012	Required	Yes	Yes
97	R	14.4	MISRA C 2012	Required	Yes	Yes
98	R	15.1	MISRA C 2012	Advisory	No	No	In some cases goto may be useful for readability.
99	R	15.2	MISRA C 2012	Required	Yes	Yes
100	R	15.3	MISRA C 2012	Required	Yes	Yes
101	R	15.4	MISRA C 2012	Advisory	Yes	Yes
102	R	15.5	MISRA C 2012	Advisory	No	No	This has no real value. It may make code less understandable than before.
103	R	15.6	MISRA C 2012	Required	No	No	This directly contradicts the Linux style guidelines and would require many changes. We would have to remove that rule from checkpatch.
104	R	15.7	MISRA C 2012	Required	Yes	Yes
105	R	16.1	MISRA C 2012	Required	No	No	Cannot comply with this unless we comply with 16.3
106	R	16.2	MISRA C 2012	Required	Yes	Yes
107	R	16.3	MISRA C 2012	Required	No	No	Returns within switch statements and fall-throughs can improve readability.
108	R	16.4	MISRA C 2012	Required	Yes	Yes
109	R	16.5	MISRA C 2012	Required	Yes	Yes
110	R	16.6	MISRA C 2012	Required	Yes	Yes
111	R	16.7	MISRA C 2012	Required	Yes	Yes
112	R	17.1	MISRA C 2012	Required	No	No	This is needed for printf.
113	R	17.2	MISRA C 2012	Required	Yes	Yes	Bans recursion. We consider it acceptable if the max depth is known.
114	R	17.3	MISRA C 2012	Mandatory	Yes	Yes
115	R	17.4	MISRA C 2012	Mandatory	Yes	Yes
116	R	17.5	MISRA C 2012	Advisory	Yes	Yes
117	R	17.6	MISRA C 2012	Mandatory	Yes	Yes
118	R	17.7	MISRA C 2012	Required	Yes	Optional	In some cases it doesn’t add any value to the code (like with memset() or printf()).
119	R	17.8	MISRA C 2012	Advisory	Yes	Optional	It would make some one-line functions grow in size for no reason.
120	R	18.1	MISRA C 2012	Required	Yes	Yes
121	R	18.2	MISRA C 2012	Required	Yes	Yes
122	R	18.3	MISRA C 2012	Required	Yes	Yes
123	R	18.4	MISRA C 2012	Advisory	Yes	Yes
124	R	18.5	MISRA C 2012	Advisory	Yes	Yes
125	R	18.6	MISRA C 2012	Required	Yes	Yes
126	R	18.7	MISRA C 2012	Required	Yes	Yes
127	R	18.8	MISRA C 2012	Required	Yes	Yes
128	R	19.1	MISRA C 2012	Mandatory	Yes	Yes
129	R	19.2	MISRA C 2012	Advisory	Yes	Optional	Unions can be useful. We almost don’t use them, so it’s ok.
130	R	20.1	MISRA C 2012	Advisory	Yes	Optional	In some files we have assembly-compatible includes followed by assembly-compatible definitions followed by C includes and C declarations. This is done to not have #ifdef in the include list.
131	R	20.2	MISRA C 2012	Required	Yes	Yes
132	R	20.3	MISRA C 2012	Required	Yes	Yes
133	R	20.4	MISRA C 2012	Required	Yes	Yes
134	R	20.5	MISRA C 2012	Advisory	Yes	Yes
135	R	20.6	MISRA C 2012	Required	Yes	Yes
136	R	20.7	MISRA C 2012	Required	Yes	Yes
137	R	20.8	MISRA C 2012	Required	Yes	Optional	We need a new configuration system to fix all defects.
138	R	20.9	MISRA C 2012	Required	Yes	Optional	We use a mix of #if and #ifdef for boolean macros, which may raise some failures here. We should consistently use one or the other
139	R	20.10	MISRA C 2012	Advisory	Yes	Optional	It’s good to avoid them, but they are sometimes needed.
140	R	20.11	MISRA C 2012	Required	Yes	Yes
141	R	20.12	MISRA C 2012	Required	Yes	Yes
142	R	20.13	MISRA C 2012	Required	Yes	Yes
143	R	20.14	MISRA C 2012	Required	Yes	Yes
144	R	21.1	MISRA C 2012	Required	Yes	Yes
145	R	21.2	MISRA C 2012	Required	Yes	Yes
146	R	21.3	MISRA C 2012	Required	Yes	Yes
147	R	21.4	MISRA C 2012	Required	Yes	Yes
148	R	21.5	MISRA C 2012	Required	Yes	Yes
149	R	21.6	MISRA C 2012	Required	No	No	This bans printf.
150	R	21.7	MISRA C 2012	Required	Yes	Yes
151	R	21.8	MISRA C 2012	Required	Yes	Yes
152	R	21.9	MISRA C 2012	Required	Yes	Yes
153	R	21.10	MISRA C 2012	Required	Yes	Yes
154	R	21.11	MISRA C 2012	Required	Yes	Yes
155	R	21.12	MISRA C 2012	Advisory	Yes	Yes
156	R	21.13	MISRA C 2012 AMD-1	Mandatory	Yes	Yes
157	R	21.14	MISRA C 2012 AMD-1	Required	Yes	Yes
158	R	21.15	MISRA C 2012 AMD-1	Required	Yes	Yes
159	R	21.16	MISRA C 2012 AMD-1	Required	Yes	Yes
160	R	21.17	MISRA C 2012 AMD-1	Mandatory	Yes	Yes
161	R	21.18	MISRA C 2012 AMD-1	Mandatory	Yes	Yes
162	R	21.19	MISRA C 2012 AMD-1	Mandatory	Yes	Yes
163	R	21.20	MISRA C 2012 AMD-1	Mandatory	Yes	Yes
164	R	22.1	MISRA C 2012	Required	Yes	Yes
165	R	22.2	MISRA C 2012	Mandatory	Yes	Yes
166	R	22.3	MISRA C 2012	Required	Yes	Yes
167	R	22.4	MISRA C 2012	Mandatory	Yes	Yes
168	R	22.5	MISRA C 2012	Mandatory	Yes	Yes
169	R	22.6	MISRA C 2012	Mandatory	Yes	Yes
170	R	22.7	MISRA C 2012 AMD-1	Required	Yes	Yes
171	R	22.8	MISRA C 2012 AMD-1	Required	Yes	Yes
172	R	22.9	MISRA C 2012 AMD-1	Required	Yes	Yes
173	R	22.10	MISRA C 2012 AMD-1	Required	Yes	Yes

3.4.5.Indentation

Usetabs for indentation. The use of spaces for indentation is forbiddenexcept in the case where a term is being indented to a boundary that cannot beachieved using tabs alone.

Tab spacing should be set to8 characters.

Trailing whitespace is not allowed and must be trimmed.

3.4.6.Spacing

Single spacing should be used around most operators, including:

Arithmetic operators (+,-,/,*)
Assignment operators (=,+=, etc)
Boolean operators (&&,||)
Comparison operators (<,>,==, etc)

A space should also be used to separate parentheses and braces when they are notalready separated by a newline, such as for theif statement in thefollowing example:

intfunction_foo(boolbar){if(bar){function_baz();}}

Note that there is no space between the name of a function and the followingparentheses.

Control statements (if,for,switch,while, etc) must beseparated from the following open parenthesis by a single space. The previousexample illustrates this for anif statement.

3.4.7.Line Length

Line lengthshould be at most80 characters. This limit does not includenon-printing characters such as the line feed.

This rule is ashould, not a must, and it is acceptable to exceed the limitslightly where the readability of the code would otherwise be significantlyreduced. Use your judgement in these cases.

3.4.8.Blank Lines

Functions are usually separated by a single blank line. In certain cases it isacceptable to use additional blank lines for clarity, if required.

The file must end with a single newline character. Many editors have the optionto insert this automatically and to trim multiple blank lines at the end of thefile.

3.4.9.Braces

3.4.9.1.Opening Brace Placement

Braces follow theKernighan and Ritchie (K&R) style, where the opening braceisnot placed on a new line.

Example for awhile loop:

while(condition){foo();bar();}

This style applies to all blocks except for functions which, following the Linuxstyle,do place the opening brace on a new line.

Example for a function:

intmy_function(void){inta;a=1;returna;}

3.4.9.2.Conditional Statement Bodies

Where conditional statements (such asif,for,while anddo) areused, braces must be placed around the statements that form the body of theconditional. This is the case regardless of the number of statements in thebody.

Note

This is a notable departure from the Linux coding style that has beenadopted to follow MISRA guidelines more closely and to help prevent errors.

For example, use the following style:

if(condition){foo++;}

instead of omitting the optional braces around a single statement:

/* This is violating MISRA C 2012: Rule 15.6 */if(condition)foo++;

The reason for this is to prevent accidental changes to control flow whenmodifying the body of the conditional. For example, at a quick glance it is easyto think that the value ofbar is only incremented ifconditionevaluates totrue but this is not the case -bar will always beincremented regardless of the condition evaluation. If the developer forgets toadd braces around the conditional body when adding thebar++; statement thenthe program execution will not proceed as intended.

/* This is violating MISRA C 2012: Rule 15.6 */if(condition)foo++;bar++;

3.4.10.Naming

3.4.10.1.Functions

Use lowercase for function names, separating multiple words with an underscorecharacter (_). This is sometimes referred to asSnake Case. An example isgiven below:

voidbl2_arch_setup(void){...}

3.4.10.2.Local Variables and Parameters

Local variables and function parameters use the same format as function names:lowercase with underscore separation between multiple words. An example isgiven below:

staticvoidset_scr_el3_from_rm(uint32_ttype,uint32_tinterrupt_type_flags,uint32_tsecurity_state){uint32_tflag,bit_pos;...}

3.4.10.3.Preprocessor Macros

Identifiers that are defined using preprocessor macros are written in alluppercase text.

#define BUFFER_SIZE_BYTES 64

3.4.11.Function Attributes

Place any function attributes after the function type and before the functionname.

void__initplat_arm_interconnect_init(void);

3.4.12.Alignment

Alignment should be performed primarily with tabs, adding spaces if required toachieve a granularity that is smaller than the tab size. For example, with a tabsize of eight columns it would be necessary to use one tab character and twospaces to indent text by ten columns.

3.4.12.1.Switch Statement Alignment

When usingswitch statements, align eachcase statement with theswitch so that they are in the same column.

switch(condition){caseA:foo();caseB:bar();default:baz();}

3.4.12.2.Pointer Alignment

The reference and dereference operators (ampersand andpointer star) must bealigned with the name of the object on which they are operating, as opposed tothe type of the object.

uint8_t*foo;foo=&bar;

3.4.13.Comments

The general rule for comments is that the double-slash style of comment (//)is not allowed. Examples of the allowed comment formats are shown below:

/* * This example illustrates the first allowed style for multi-line comments. * * Blank lines within multi-lines are allowed when they add clarity or when * they separate multiple contexts. * */

/************************************************************************** * This is the second allowed style for multi-line comments. * * In this style, the first and last lines use asterisks that run the full * width of the comment at its widest point. * * This style can be used for additional emphasis. * *************************************************************************/

/* Single line comments can use this format */

/*************************************************************************** * This alternative single-line comment style can also be used for emphasis. **************************************************************************/

3.4.14.Headers and inclusion

3.4.14.1.Header guards

For a header file called “some_driver.h” the style used byTF-A is:

#ifndef SOME_DRIVER_H#define SOME_DRIVER_H<headercontent>#endif/* SOME_DRIVER_H */

3.4.14.2.Include statement ordering

All header files that are included by a source file must use the following,grouped ordering. This is to improve readability (by making it easier to quicklyread through the list of headers) and maintainability.

System includes: Header files from the standardC library, such asstddef.h andstring.h.
Project includes: Header files under theinclude/ directory withinTF-A areproject includes.
Platform includes: Header files relating to a single, specific platform,and which are located under theplat/<platform_name> directory withinTF-A, areplatform includes.

Within each group,#include statements must be in alphabetical order,taking both the file and directory names into account.

Groups must be separated by a single blank line for clarity.

The example below illustrates the ordering rules using some contrived headerfile names; this type of name reuse should be otherwise avoided.

#include<string.h>#include<a_dir/example/a_header.h>#include<a_dir/example/b_header.h>#include<a_dir/test/a_header.h>#include<b_dir/example/a_header.h>#include"a_header.h"

The preferred approach for third-party headers is to include them immediatelyfollowing system header files like in the example below, where theversion.h header from the Mbed TLS library immediately follows thestddef.h system header.

/* system header files */#include<stddef.h>/* Mbed TLS header files */#include<mbedtls/version.h>/* project header files */#include<drivers/auth/auth_mod.h>#include<drivers/auth/tbbr_cot_common.h>/* platform header files */#include<platform_def.h>

3.4.14.3.Include statement variants

Two variants of the#include directive are acceptable in theTF-Acodebase. Correct use of the two styles improves readability by suggesting thelocation of the included header and reducing ambiguity in cases where genericand platform-specific headers share a name.

For header files that are in the same directory as the source file that isincluding them, use the"..." variant.

For header files that arenot in the same directory as the source file thatis including them, use the<...> variant.

Example (bl1_fwu.c):

#include<assert.h>#include<errno.h>#include<string.h>#include"bl1_private.h"

3.4.15.Typedefs

3.4.15.1.Avoid anonymous typedefs of structs/enums in headers

For example, the following definition:

typedefstruct{intarg1;intarg2;}my_struct_t;

is better written as:

structmy_struct{intarg1;intarg2;};

This allows function declarations in other header files that depend on thestruct/enum to forward declare the struct/enum instead of including theentire header:

structmy_struct;voidmy_func(structmy_struct*arg);

instead of:

#include<my_struct.h>voidmy_func(my_struct_t*arg);

Some TF definitions use both a struct/enum nameand a typedef name. Thisis discouraged for new definitions as it makes it difficult for TF to complywith MISRA rule 8.3, which states that “All declarations of an object orfunction shall use the same names and type qualifiers”.

The Linux coding standards also discourage new typedefs and checkpatch emitsa warning for this.

Existing typedefs will be retained for compatibility.

Movatterモバイル変換

3.4.Coding Style

3.4.1.File Encoding

3.4.2.Language

3.4.3.C Language Standard

3.4.4.MISRA Compliance

3.4.5.Indentation

3.4.6.Spacing

3.4.7.Line Length

3.4.8.Blank Lines

3.4.9.Braces

3.4.9.1.Opening Brace Placement

3.4.9.2.Conditional Statement Bodies

3.4.10.Naming

3.4.10.1.Functions

3.4.10.2.Local Variables and Parameters

3.4.10.3.Preprocessor Macros

3.4.11.Function Attributes

3.4.12.Alignment

3.4.12.1.Switch Statement Alignment

3.4.12.2.Pointer Alignment

3.4.13.Comments

3.4.14.Headers and inclusion

3.4.14.1.Header guards

3.4.14.2.Include statement ordering

3.4.14.3.Include statement variants

3.4.15.Typedefs

3.4.15.1.Avoid anonymous typedefs of structs/enums in headers