1# Coding Style
2
3To maintain consistency within the SCP/MCP software source code a series of
4rules and guidelines have been created; these form the project's coding style.
5
6## Style
7
8### Unicode
9
10The source code must use the UTF-8 encoding. Comments, documentation and strings
11may use non-ASCII characters when required (e.g. Greek letters used for units).
12
13### License Headers
14
15All files must begin with a license header of the following form, where first
16year describes the year the file was first upstreamed, and the second year the
17year when the file was last updated:
18
19Arm SCP/MCP Software
20Copyright (c) 2015-2021, Arm Limited and Contributors. All rights reserved.
21
22SPDX-License-Identifier: BSD-3-Clause
23
24### Clang Format
25
26To aid in establishing a uniform style across the code-base, this project uses
27Clang Format. When contributing patches, care should be taken to ensure that
28code has been formatted according to the rules laid down in the .clang-format
29file, and that deviations occur only where the tool is unable to format code
30reasonably.
31
32You can automatically format any staged changes with:
33
34```sh
35git clang-format
36```
37
38One common deviation is found when defining a list of harware registers, for
39example:
40
41```c
42struct some_reg {
43             uint8_t   RESERVED0[0x820 - 0x818];
44     FWK_RW  uint32_t  REGISTER0;
45     FWK_RW  uint32_t  REGIRTER1;
46};
47```
48
49The above indentation, although easy to read, will fail the formatting style.
50To preserve the legacy format and allow silent operation of the tool, only such
51definitions may be preceded and followed by the following special comments:
52
53```c
54// clang-format off
55struct some_reg {
56             uint8_t   RESERVED0[0x820 - 0x818];
57     FWK_RW  uint32_t  REGISTER0;
58     FWK_RW  uint32_t  REGIRTER1;
59};
60// clang-format on
61```
62
63### Braces
64
65Conditional statements and iteration statements with a single line or
66multiple lines of code must be surrounded by braces:
67
68```c
69if (condition) {
70    function_call(
71        long_variable_name_x,
72        long_variable_name_y,
73        long_variable_name_z);
74}
75```
76
77This rule applies also to an if-else chain:
78
79```c
80if (condition) {
81    function_call(
82        long_variable_name_x,
83        long_variable_name_y,
84        long_variable_name_z);
85} else {
86    function_call_b();
87}
88```
89
90Empty loop statements must use `continue`:
91
92```c
93while (condition) {
94  continue;
95}
96```
97
98### Operators
99
100When using operators like `sizeof` and `alignof`, where possible use the
101value-based version over the type-based version:
102
103```c
104int counter;
105
106sizeof(counter); /* Preferred over sizeof(int) */
107```
108
109### Operator Precedence
110
111Do not rely on the implicit precedence and associativity of operators. Use
112parentheses to make precedence and associativity explicit:
113
114```c
115if ((a == 'a') || (x == 'x')) {
116    do_something();
117}
118```
119
120Parentheses around a unary operator and its operand may be omitted:
121
122```c
123if (!a && *b) {
124    do_something();
125}
126```
127
128## Conventions
129
130### Header Guards
131
132All headers must be wrapped with include guards to prevent accidental multiple
133definitions of header contents. The definition name should be the upper-case
134file name followed by `_H`. An example for a file named `fwk_mm.h` follows:
135
136```c
137#ifndef FWK_MM_H
138#define FWK_MM_H
139
140(...)
141
142#endif /* FWK_MM_H */
143```
144
145### Inclusion Policy
146
147The closing `endif` statement should be followed directly by a single-line
148comment which replicates the full guard name. In long files this helps to
149clarify what is being closed.
150
151*Public* headers must be included directly *except* in the following situations:
152
153- The header is already included by the counterpart to the current C file (e.g.
154  `x/src/mod_x.c` does not need to include `<stdint.h>` if `x/include/mod_x.h`
155  includes it)
156- The header is an internal header and is included as part of another public
157  header (e.g. `x/src/mod_x.c` does not need to include `x/include/internal/x.h`
158  if another header includes it)
159
160These rules do not apply to *private* headers (headers under a `src/`
161directory).
162
163### Macros and Constants
164
165All macro and constant names must be written in upper-case to differentiate
166them from functions and non-constants.
167
168Logical groupings of constants should be defined as enumerations with a common
169prefix, so that they can be used as parameter types and in constant expressions.
170Enumerations that contain a "number of elements" value must use the `_COUNT`
171suffix, and the final enumeration value should include a comma.
172
173```c
174enum command_id {
175    COMMAND_ID_VERSION,
176    COMMAND_ID_PING,
177    COMMAND_ID_EXIT,
178    COMMAND_ID_COUNT,
179};
180
181void process_cmd(enum command_id id)
182{
183    (...)
184}
185```
186
187### Symbol Naming
188
189Function, variable, file name and type names must:
190
191- Be written in lower-case
192- Have compound words separated by underline characters (`_`)
193- Have descriptive names, avoiding contractions where possible (e.g.
194    `cluster_count` instead of `clus_cnt`)
195
196Avoid using:
197
198- Camel case syntax (e.g. `cssClusterCount`)
199- Hungarian notation, encoding types within names (e.g. `int iSize`)
200
201The following prefixes are reserved for these components:
202
203- Architecture: `arch_`
204- Framework: `fwk_`
205- Module: `mod_`
206  - Module description: `module_`
207  - Module configuration: `config_`
208- Firmware: `fmw_`
209
210### Assertions
211
212Use `fwk_assert()` to mark *invariants*. Invariants are logical assertions about
213the behaviour of the system which must hold true for the program to be valid.
214Invariants are usually easy to communicate to human readers, but not very easy
215to communicate to the compiler.
216
217Use `fwk_expect()` to mark *expectations*. Expectations may fail, and they may
218or may not be handled, but they are not invariants in that they may reasonably
219occur at some point in time.
220
221### Loop Indices
222
223It is acceptable to use the following common placeholder names for loop indices:
224
225- `i`
226- `j`
227- `k`
228
229### Types
230
231Avoid defining custom types with the `typedef` keyword where possible. Names
232defined with `typedef` must use the `_t` suffix.
233
234### Comments
235
236To ensure a consistent look, the preferred style for single-line comments is to
237use the C89 style of paired forward-slashes and asterisks, ending with no
238punctuation:
239
240```c
241/* A short, single-line comment */
242```
243
244Multi-line comments should follow a similar style, and always end with
245punctuation:
246
247```c
248/*
249 * This is a very, very, very, very long multi-line comment where each line
250 * starts with an asterisk and paragraphs ends with punctation.
251 */
252```
253
254Doxygen comments follow only the second style, for consistency in the generated
255documentation:
256
257```c
258/*!
259 * \brief Hello, World.
260 */
261```
262
263Preprocessor `if 0` is preferred for commenting out blocks of code where it is
264necessary to do so, as these can be nested (unlike multi-line comment blocks).
265
266```c
267void function_a(int x, int y)
268{
269    (...)
270}
271
272#if 0
273void function_b(int x, int y)
274{
275    (...)
276}
277#endif
278```
279
280Prefer functions to function-like macros where possible. Avoid using the
281`inline` keyword, as inlining sites are better-determined by the compiler.
282
283### Initialization
284
285When literals require explicit literal initialization, avoid implicit casts by
286using the proper integer literal suffix or initializer:
287
288```c
289void *p = NULL;
290unsigned int u = 0u;
291float f = 0.0f;
292double d = 0.0;
293char c = '\0';
294```
295
296Array and structure initialization should use designated initializers. These
297allow elements to be initialized using array indices or structure field names
298without a fixed ordering:
299
300```c
301uint32_t clock_frequencies[3] = {
302    [2] = 800,
303    [0] = 675,
304};
305
306struct clock clock_cpu = {
307    .name = "CPU",
308    .frequency = clock_frequencies[2],
309};
310```
311
312### Device Register Definitions
313
314The format for structures representing memory-mapped device registers is
315standardized:
316
317- Register structure names are suffixed with `_reg`
318- All register names must be capitalized
319- Non-reserved registers must be one of `FWK_R`, `FWK_W`, or `FWK_RW`
320- Bit-field masks and shifts use the `<DEVICE>_<REGISTER>_<FIELD>` name,
321  suffixed with either `_MASK` or `_POS`
322
323```c
324#include <stdint.h>
325#include <fwk_macros.h>
326
327struct my_timer_reg {
328    FWK_RW uint32_t CONFIG;
329           uint32_t RESERVED1;
330    FWK_W  uint32_t IRQ_CLEAR;
331    FWK_R  uint32_t IRQ_STATUS;
332           uint8_t  RESERVED2[0x40];
333};
334
335#define MY_TIMER_CONFIG_ENABLE UINT32_C(0x00000001)
336#define MY_TIMER_CONFIG_SLEEP UINT32_C(0x00000002)
337
338#define MY_TIMER_IRQ_STATUS_ALERT UINT32_C(0x00000001)
339```
340
341**Note:** A template file can be found in doc/template/device.h
342
343### Doxygen Comments
344
345The project APIs are documented using Doxygen comments.
346
347It is mandatory to document every API exposed to other elements of the project.
348By default, the provided Doxygen configuration omits undocumented elements from
349the compiled documentation.
350
351At a minimum:
352
353- All functions and structures must have at least a `brief` tag
354- All functions must document their parameters (if any) with the `param` tag
355  - Input parameters must use `param[in]`
356  - Output parameters must use `param[out]`
357  - Input/output parameters must use `param[in, out]`
358- All functions returning a value should use the `return` and, optionally, the
359  `retval` tag to document their return value
360  - `return` should document what the *type* of the return value represents
361  - `retval` should document what *individual return values* represent
362
363Alignment and indentation:
364
365- Documentation must also obey the 80 column limit
366- Multiple lines of documentation on an entry (e.g. details) must be indented
367  using the equivalent of two 4-space based tabs from the first column (see
368  example below)
369
370Function documentation example:
371
372```c
373/*!
374 * \brief Enable the watchdog.
375 *
376 * \details This function enables the watchdog. If mod_wdog_set_interval() has
377 *      not been called beforehand then the watchdog defaults to a 500
378 *      millisecond timeout period.
379 */
380void mod_wdog_enable(void);
381```
382
383Structure documentation example:
384
385```c
386/*!
387 * \brief A structure example.
388 *
389 * \details This is an example of a structure for the code style documentation.
390 */
391struct mod_structure {
392    /*!
393     * \brief Example field.
394     */
395    unsigned int example;
396};
397```
398
399## Python
400
401Python based tools must follow the [PEP8][pep8] specification. This is enforced
402with the `pycodestyle` tool.
403
404Python code must be linted with `pylint`.
405
406[pep8]: https://www.python.org/dev/peps/pep-0008
407