3.4. Coding Style

The following sections outline the TF-A coding style for C code. The style is based on the Linux kernel coding style, with a few modifications.

The style should not be considered set in stone. Feel free to provide feedback and suggestions.

Note

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

3.4.1. File Encoding

The source code must use the UTF-8 character encoding. Comments and documentation may use non-ASCII characters when required (e.g. Greek letters used for units) but code itself is still limited to ASCII characters.

Newlines must be in Unix 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. In cases where there is a conflict between the American English and British English spellings of a word, the American English spelling is used.

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

3.4.3. C Language Standard

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

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

3.4.4. MISRA Compliance

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

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

Note

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

Note

Third-party libraries are not considered in our MISRA analysis and we do not intend 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

Use tabs for indentation. The use of spaces for indentation is forbidden except in the case where a term is being indented to a boundary that cannot be achieved using tabs alone.

Tab spacing should be set to 8 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 not already separated by a newline, such as for the if statement in the following example:

int function_foo(bool bar)
{
    if (bar) {
        function_baz();
    }
}

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

Control statements (if, for, switch, while, etc) must be separated from the following open parenthesis by a single space. The previous example illustrates this for an if statement.

3.4.7. Line Length

Line length should be at most 80 characters. This limit does not include non-printing characters such as the line feed.

This rule is a should, not a must, and it is acceptable to exceed the limit slightly where the readability of the code would otherwise be significantly reduced. Use your judgement in these cases.

3.4.8. Blank Lines

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

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

3.4.9. Braces

3.4.9.1. Opening Brace Placement

Braces follow the Kernighan and Ritchie (K&R) style, where the opening brace is not placed on a new line.

Example for a while loop:

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

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

Example for a function:

int my_function(void)
{
    int a;

    a = 1;
    return a;
}

3.4.9.2. Conditional Statement Bodies

Where conditional statements (such as if, for, while and do) are used, braces must be placed around the statements that form the body of the conditional. This is the case regardless of the number of statements in the body.

Note

This is a notable departure from the Linux coding style that has been adopted 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 when modifying the body of the conditional. For example, at a quick glance it is easy to think that the value of bar is only incremented if condition evaluates to true but this is not the case - bar will always be incremented regardless of the condition evaluation. If the developer forgets to add braces around the conditional body when adding the bar++; statement then the 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 underscore character (_). This is sometimes referred to as Snake Case. An example is given below:

void bl2_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 is given below:

static void set_scr_el3_from_rm(uint32_t type,
                                uint32_t interrupt_type_flags,
                                uint32_t security_state)
{
    uint32_t flag, bit_pos;

    ...

}

3.4.10.3. Preprocessor Macros

Identifiers that are defined using preprocessor macros are written in all uppercase text.

#define BUFFER_SIZE_BYTES 64

3.4.11. Function Attributes

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

void __init plat_arm_interconnect_init(void);

3.4.12. Alignment

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

3.4.12.1. Switch Statement Alignment

When using switch statements, align each case statement with the switch so that they are in the same column.

switch (condition) {
case A:
    foo();
case B:
    bar();
default:
    baz();
}

3.4.12.2. Pointer Alignment

The reference and dereference operators (ampersand and pointer star) must be aligned with the name of the object on which they are operating, as opposed to the 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 by TF-A is:

#ifndef SOME_DRIVER_H
#define SOME_DRIVER_H

<header content>

#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 quickly read through the list of headers) and maintainability.

  1. System includes: Header files from the standard C library, such as stddef.h and string.h.

  2. Project includes: Header files under the include/ directory within TF-A are project includes.

  3. Platform includes: Header files relating to a single, specific platform, and which are located under the plat/<platform_name> directory within TF-A, are platform 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 header file 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 immediately following system header files like in the example below, where the version.h header from the Mbed TLS library immediately follows the stddef.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 the TF-A codebase. Correct use of the two styles improves readability by suggesting the location of the included header and reducing ambiguity in cases where generic and platform-specific headers share a name.

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

For header files that are not in the same directory as the source file that is 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:

typedef struct {
        int arg1;
        int arg2;
} my_struct_t;

is better written as:

struct my_struct {
        int arg1;
        int arg2;
};

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

struct my_struct;
void my_func(struct my_struct *arg);

instead of:

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

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

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

Existing typedefs will be retained for compatibility.


Copyright (c) 2020-2023, Arm Limited. All rights reserved.