1Coding Style
2============
3
4Hafnium's coding style has been based on the `Linux coding style`_ with explicit
5modifications: always use braces for conditionals and loops.
6
7The project follows the subset of the `Google C++ style guide`_ that is applicable
8to C.
9
10Much of this is automated by the use of clang-format and clang-tidy, but that
11doesn't capture everything.
12Where the style enforced by this tooling conflicts with what is in this document,
13we accept what the tooling requires, and try to improve it if possible.
14
15Clarifications
16--------------
17
18* Yes, it does mean all variables are declared, C90-style, at the top of
19  scope, even those loop induction variables.
20* Linux encourages no braces around single-statement branches. We follow
21  Google style guide and require braces around all scope blocks.
22
23Naming symbols
24--------------
25
26* Arch-specific functions should start with `arch_`.
27* Platform-specific functions should start with `plat_`.
28* Non-static functions should generally start with the name of the file they
29  are declared in (after the `arch_` or `plat_` prefix if appropriate), though
30  there are quite a few exceptions to this rule.
31* Prefer `x_count` over `num_x`.
32
33Prose
34-----
35
36These rules apply to comments and other natural language text.
37
38* Capitalize acronyms.
39   * CPU, vCPU, VM, SP, EL2, FF-A, FVP.
40* Spell out Hafnium in full, not Hf.
41* Use single spaces.
42* Sentences end with full stops.
43* If the comment fits on one line use `/* */`, otherwise space it out:
44
45.. code:: C
46
47  /*
48   * Informative long comment
49   * with extra information.
50   */
51
52* Doc-ish comments start with `/**`.
53   * Use for:
54      *   Function definitions (not declarations)
55      *   Struct declarations
56      *   Enum values
57   * Do not use for:
58      *   Macros
59      *   Definitions of globals
60
61* References to code symbols use backticks, e.g. \`my_symbol\`.
62
63Coding practices
64----------------
65
66*   Function macros should be functions instead, that way you get types.
67*   Lock ordering is described at the top of `api.c`_.
68*   Use opaque types to avoid implicit casts when it will help avoid mistakes.
69    e.g. `addr.h`_.
70*   Avoid inline casting. C doesn't give much protection so be formal about the
71    transformations. e.g. `addr.h`_.
72*   If a function acquires a resource, there must be a single exit path to free
73    the resource. Tracking down multiple exit points is hard and requires
74    duplicated code which is harder. This may require splitting functions into
75    subfunctions. Early exit is okay if there aren't any clean up tasks.
76*   Don't use function pointers. It makes analysis hard and is often a target of
77    attacks.
78*   Be liberal with `CHECK`. Use it to assert pre-/post- conditions.
79*   No self-modifying code.
80*   Build targets should include all the direct dependencies for their sources,
81    where possible, rather than relying on transitive dependencies.
82
83Logging
84-------
85
86Hafnium uses the same log levels as |TF-A|. There are 5 log levels, in order
87of severity:
88
891.  `ERROR`:
90    Use this only for cases where there is an error in the partition manager
91    itself, perhaps caused by a coding error, bad configuration, unexpected
92    hardware behaviour or a malformed manifest. Errors should not be logged
93    during normal operation, even in case of a buggy or malicious VM.
94
952.  `NOTICE`:
96    Use this sparingly for important messages which should be logged even in
97    production builds because they will be useful for debugging. This is a
98    suitable level to use for events which may indicate a bug in a VM.
99
1003.  `WARNING`:
101    Use this for warnings which are important to developers but can generally be
102    ignored in production.
103
1044.  `INFO`:
105    Use this to provide extra information that is helpful for developers.
106
1075.  `VERBOSE`:
108    Use this to provide even more information which may be helpful when tracing
109    through execution in detail, such as when debugging test failures. This is
110    the only level which should include any sensitive data.
111
112Logging is done with the `dlog_*` macros, e.g. `dlog_info`. These accept
113printf-style format strings and arguments.
114
115The log level of a build is controlled by the `log_level` argument defined in
116`build/BUILD.gn`_. This defaults to `INFO` for debug builds and tests, meaning
117that all levels except `VERBOSE` will be logged. It is recommended to set the
118log level to `NOTICE` for production builds, to reduce binary size and log spam.
119Verbosity can also be changed for a given platform build only, in the respective
120platform configuration.
121
122--------------
123
124*copyright (c) 2023, arm limited and contributors. all rights reserved.*
125
126.. _Linux coding style: https://www.kernel.org/doc/html/v4.17/process/coding-style.html
127.. _Google C++ style guide: https://google.github.io/styleguide/cppguide.html
128.. _api.c: https://git.trustedfirmware.org/hafnium/hafnium.git/tree/src/api.c
129.. _addr.h: https://git.trustedfirmware.org/hafnium/hafnium.git/tree/inc/hf/addr.h
130.. _build/BUILD.gn: https://git.trustedfirmware.org/hafnium/hafnium.git/tree/build/BUILD.gn#n65
131