Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   1) .. _clangformat:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   2) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   3) clang-format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   4) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   5) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   6) ``clang-format`` is a tool to format C/C++/... code according to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   7) a set of rules and heuristics. Like most tools, it is not perfect
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   8) nor covers every single case, but it is good enough to be helpful.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   9) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  10) ``clang-format`` can be used for several purposes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12)   - Quickly reformat a block of code to the kernel style. Specially useful
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13)     when moving code around and aligning/sorting. See clangformatreformat_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15)   - Spot style mistakes, typos and possible improvements in files
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16)     you maintain, patches you review, diffs, etc. See clangformatreview_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18)   - Help you follow the coding style rules, specially useful for those
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19)     new to kernel development or working at the same time in several
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20)     projects with different coding styles.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22) Its configuration file is ``.clang-format`` in the root of the kernel tree.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23) The rules contained there try to approximate the most common kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  24) coding style. They also try to follow :ref:`Documentation/process/coding-style.rst <codingstyle>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  25) as much as possible. Since not all the kernel follows the same style,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  26) it is possible that you may want to tweak the defaults for a particular
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27) subsystem or folder. To do so, you can override the defaults by writing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28) another ``.clang-format`` file in a subfolder.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30) The tool itself has already been included in the repositories of popular
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31) Linux distributions for a long time. Search for ``clang-format`` in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) your repositories. Otherwise, you can either download pre-built
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33) LLVM/clang binaries or build the source code from:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35)     https://releases.llvm.org/download.html
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  36) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  37) See more information about the tool at:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  38) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39)     https://clang.llvm.org/docs/ClangFormat.html
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41)     https://clang.llvm.org/docs/ClangFormatStyleOptions.html
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44) .. _clangformatreview:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46) Review files and patches for coding style
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47) -----------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49) By running the tool in its inline mode, you can review full subsystems,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50) folders or individual files for code style mistakes, typos or improvements.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52) To do so, you can run something like::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54)     # Make sure your working directory is clean!
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55)     clang-format -i kernel/*.[ch]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57) And then take a look at the git diff.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59) Counting the lines of such a diff is also useful for improving/tweaking
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60) the style options in the configuration file; as well as testing new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61) ``clang-format`` features/versions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63) ``clang-format`` also supports reading unified diffs, so you can review
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64) patches and git diffs easily. See the documentation at:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66)     https://clang.llvm.org/docs/ClangFormat.html#script-for-patch-reformatting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68) To avoid ``clang-format`` formatting some portion of a file, you can do::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70)     int formatted_code;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71)     // clang-format off
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72)         void    unformatted_code  ;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73)     // clang-format on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74)     void formatted_code_again;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76) While it might be tempting to use this to keep a file always in sync with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77) ``clang-format``, specially if you are writing new files or if you are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78) a maintainer, please note that people might be running different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79) ``clang-format`` versions or not have it available at all. Therefore,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80) you should probably refrain yourself from using this in kernel sources;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81) at least until we see if ``clang-format`` becomes commonplace.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84) .. _clangformatreformat:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86) Reformatting blocks of code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87) ---------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89) By using an integration with your text editor, you can reformat arbitrary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90) blocks (selections) of code with a single keystroke. This is specially
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91) useful when moving code around, for complex code that is deeply intended,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92) for multi-line macros (and aligning their backslashes), etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94) Remember that you can always tweak the changes afterwards in those cases
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95) where the tool did not do an optimal job. But as a first approximation,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96) it can be very useful.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98) There are integrations for many popular text editors. For some of them,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99) like vim, emacs, BBEdit and Visual Studio you can find support built-in.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) For instructions, read the appropiate section at:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102)     https://clang.llvm.org/docs/ClangFormat.html
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) For Atom, Eclipse, Sublime Text, Visual Studio Code, XCode and other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) editors and IDEs you should be able to find ready-to-use plugins.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) For this use case, consider using a secondary ``.clang-format``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) so that you can tweak a few options. See clangformatextra_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) .. _clangformatmissing:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) Missing support
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) ---------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) ``clang-format`` is missing support for some things that are common
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) in kernel code. They are easy to remember, so if you use the tool
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) regularly, you will quickly learn to avoid/ignore those.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) In particular, some very common ones you will notice are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122)   - Aligned blocks of one-line ``#defines``, e.g.::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)         #define TRACING_MAP_BITS_DEFAULT       11
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)         #define TRACING_MAP_BITS_MAX           17
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126)         #define TRACING_MAP_BITS_MIN           7
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128)     vs.::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130)         #define TRACING_MAP_BITS_DEFAULT 11
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131)         #define TRACING_MAP_BITS_MAX 17
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132)         #define TRACING_MAP_BITS_MIN 7
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134)   - Aligned designated initializers, e.g.::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)         static const struct file_operations uprobe_events_ops = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137)                 .owner          = THIS_MODULE,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)                 .open           = probes_open,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139)                 .read           = seq_read,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140)                 .llseek         = seq_lseek,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)                 .release        = seq_release,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142)                 .write          = probes_write,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)         };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145)     vs.::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)         static const struct file_operations uprobe_events_ops = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)                 .owner = THIS_MODULE,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)                 .open = probes_open,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)                 .read = seq_read,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)                 .llseek = seq_lseek,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)                 .release = seq_release,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)                 .write = probes_write,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154)         };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) .. _clangformatextra:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) Extra features/options
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) Some features/style options are not enabled by default in the configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) file in order to minimize the differences between the output and the current
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) code. In other words, to make the difference as small as possible,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) which makes reviewing full-file style, as well diffs and patches as easy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) as possible.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) In other cases (e.g. particular subsystems/folders/files), the kernel style
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) might be different and enabling some of these options may approximate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) better the style there.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) For instance:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174)   - Aligning assignments (``AlignConsecutiveAssignments``).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176)   - Aligning declarations (``AlignConsecutiveDeclarations``).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178)   - Reflowing text in comments (``ReflowComments``).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180)   - Sorting ``#includes`` (``SortIncludes``).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) They are typically useful for block re-formatting, rather than full-file.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) You might want to create another ``.clang-format`` file and use that one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) from your editor/IDE instead.