1##############################
2Yet another coding standard :)
3##############################
4
5.. Warning::
6
7    Every rule has an exception so if you disagree or dislike then reach out!
8
9The coding style of TF-M project is based on
10`Linux coding style <https://www.kernel.org/doc/html/v4.10/process/coding-style.html>`__
11but there are updates for domain specific conventions as listed below.
12
13TF-M also reuses code from other SW projects, e.g. ``CMSIS_5``, which
14means some areas of code may have different styles. We use common sense approach
15and new code may inherit coding style from external projects but it needs to
16remain within clear scope.
17
18The guidance below is provided as a help. It isn't meant to be a definitive
19list.
20
21As implied in the :doc:`contributing guide </contributing/contributing_process>`
22maintainers have the right to decide on what's acceptable in case of any
23divergence.
24
25.. Warning::
26
27    Text files do not fall within these rules as they may require different formatting.
28
29****************
30Consistent style
31****************
32The code needs to be consistent with itself, so if existing code in the file
33violates listed coding style rules then it is better to follow existing style
34in the file and not break consistency by following the rules listed here.
35
36You may need to add a comment in the commit description to clarify this.
37
38List of rules
39=============
40
41- Use 4 spaces indentation. No tabs.
42- Use ``lower_case_with_underscore`` for filenames, variable and function names.
43- Use standard types e.g. ``uint32_t``, ``uint16_t``, ``uint8_t``, ``int32_t``
44  etc.
45- Use ``uintptr_t`` type when representing addresses as numbers.
46- Use static for all private functions and variables.
47- Use void argument if your function doesn't contain any argument.
48- Use C90 ``/* */`` for comments rather than C99 ``//``
49- No trailing spaces in code.
50- Keep up to 100 characters per line but 140 chars can be accepted exceptionally.
51- Open curly brace ``{`` at the same if/else/while/for/switch statement line.
52- Use curly braces ``{ }`` for one line statement bodies also.
53- Put open curly brace in the line below the function header.
54- Order function parameters so that input params are before output params.
55- Declare local variables at the beginning of the function.
56- Define macros in all caps i.e. ``CAPITAL_WITH_UNDERSCORE``.
57- Use typedefs **ONLY** for function prototype declarations.
58- Type definitions in ``lower_case_with_underscore`` ended by ``_t``.
59- Do not use typedef for other constructs as it obfuscates code.
60- Do not use bitfields.
61- Use static for all global variables to reduce the variable scope.
62- Use enumeration for error codes to keep the code readable.
63- Use descriptive variable and functions names.
64- Put the correct license header at the beginning of the file.
65- Keep the files (.h/.c) self-contained, i.e. put include dependencies in the
66  file.
67- Put appropriate header define guard in .h files: ``__HEADER_NAME__``.
68  Any divergence from this rules should be clearly documented.
69- In a .c file, #include it's own header file first.
70- Document all the public functions in the header file only.
71- Document all the private functions in the source file only.
72- Add "extern C " definition for C++ support in the header files.
73- In the switch statement, aligned cases with the switch keyword.
74- For enums, use upper case letters with digits and underscore only.
75- Do not code while eating.
76
77--------------
78
79*Copyright (c) 2018-2022, Arm Limited. All rights reserved.*
80