1Coding Style for the Xen Hypervisor
2===================================
3
4The Xen coding style described below is the coding style used by the
5Xen hypervisor itself (xen/*) as well as various associated low-level
6libraries (e.g. tools/libxc/*).
7
8An exception is made for files which are imported from an external
9source. In these cases the prevailing coding style of the upstream
10source is generally used (commonly the Linux coding style).
11
12Other parts of the code base may use other coding styles, sometimes
13explicitly (e.g. tools/libxl/CODING_STYLE) but often implicitly (Linux
14coding style is fairly common). In general you should copy the style
15of the surrounding code. If you are unsure please ask.
16
17SPDX
18----
19
20New files should start with a single-line SPDX comment to express the
21license, e.g.:
22
23/* SPDX-License-Identifier: GPL-2.0 */
24
25See LICENSES/ for a list of licenses and SPDX tags currently used.
26
27MISRA C
28-------
29
30The Xen Hypervisor follows some MISRA C coding rules. See
31docs/misra/rules.rst for details.
32
33Indentation
34-----------
35
36Indenting uses spaces, not tabs - in contrast to Linux.  An indent
37level consists of four spaces.  Code within blocks is indented by one
38extra indent level.  The enclosing braces of a block are indented the
39same as the code _outside_ the block.  e.g.
40
41void fun(void)
42{
43    /* One level of indent. */
44
45    {
46        /* A second level of indent. */
47    }
48}
49
50Due to the behavior of GNU diffutils "diff -p", labels should be
51indented by at least one blank.  Non-case labels inside switch() bodies
52are preferred to be indented the same as the block's case labels.
53
54White space
55-----------
56
57Space characters are used to spread out logical statements, such as in
58the condition of an if or while.  Spaces are placed between the
59keyword and the brackets surrounding the condition, between the
60brackets and the condition itself, and around binary operators (except
61the structure access operators, '.' and '->'). e.g.
62
63if ( (wibble & wombat) == 42 )
64{
65    ...
66
67There should be no trailing white space at the end of lines (including
68after the opening /* of a comment block).
69
70Line Length
71-----------
72
73Lines should be less than 80 characters in length.  Long lines should
74be split at sensible places and the trailing portions indented.
75
76User visible strings (e.g., printk() messages) should not be split so
77they can searched for more easily.
78
79Bracing
80-------
81
82Braces ('{' and '}') are usually placed on a line of their own, except
83for
84- the do/while loop
85- the opening brace in definitions of enum, struct, and union
86- the opening brace in initializers
87- compound literals
88This is unlike the Linux coding style and unlike K&R.  do/while loops
89are one exception. e.g.:
90
91if ( condition )
92{
93    /* Do stuff. */
94}
95else
96{
97    /* Other stuff. */
98}
99
100while ( condition )
101{
102    /* Do stuff. */
103}
104
105do {
106    /* Do stuff. */
107} while ( condition );
108
109etc.
110
111Braces should be omitted for blocks with a single statement. e.g.,
112
113if ( condition )
114    single_statement();
115
116Types
117-----
118
119Use basic C types and C standard mandated typedef-s where possible (and
120with preference in this order).  This in particular means to avoid u8,
121u16, etc despite those types continuing to exist in our code base.
122Fixed width types should only be used when a fixed width quantity is
123meant (which for example may be a value read from or to be written to a
124register).
125
126Especially with pointer types, whenever the pointed to object is not
127(supposed to be) modified, qualify the pointed to type with "const".
128
129Comments
130--------
131
132Only C style /* ... */ comments are to be used.  C++ style // comments
133should not be used.  Multi-word comments should begin with a capital
134letter.  Comments containing a single sentence may end with a full
135stop; comments containing several sentences must have a full stop
136after each sentence.
137
138Multi-line comment blocks should start and end with comment markers on
139separate lines and each line should begin with a leading '*'.
140
141/*
142 * Example, multi-line comment block.
143 *
144 * Note beginning and end markers on separate lines and leading '*'.
145 */
146
147Naming convention for files and command line options
148----------------------------------------------------
149
150'-' should be used to separate words in commandline options and filenames.
151E.g. timer-works.
152
153Note that some of the options and filenames are using '_'. This is now
154deprecated.
155
156Emacs local variables
157---------------------
158
159A comment block containing local variables for emacs is permitted at
160the end of files.  It should be:
161
162/*
163 * Local variables:
164 * mode: C
165 * c-file-style: "BSD"
166 * c-basic-offset: 4
167 * indent-tabs-mode: nil
168 * End:
169 */
170