Today the CODING_STYLE contains a section "Handling unexpected
conditions" specific to the hypervisor. This section is kind of
misplaced for a coding style. It should rather be part of a "Coding
best practices" guide.
Add such a guide as docs/process/coding-best-practices.pandoc and
move the mentioned section from CODING_STYLE to the new file, while
converting the format to pandoc.
Signed-off-by: Juergen Gross <jgross@suse.com>
Acked-by: Julien Grall <jgrall@amazon.com>
Several maintainers have expressed a stronger preference
to use '-' when in filename and option that contains multiple
words.
So document it in CODING_STYLE.
Signed-off-by: Julien Grall <jgrall@amazon.com>
For easy spotting of struct/union/enum definitions we already commonly
place the opening braces on the initial line of such a definition.
We also often don't place the opening brace of an initializer on a
separate line.
And finally for compound literals placing the braces on separate lines
often makes the code more difficult to read, so it should (and in
practice does) typically go on the same line as well. The placement of
the closing brace often depends on how large such a compound literal is.
Signed-off-by: Jan Beulich <jbeulich@suse.com>
Acked-by: Stefano Stabellini <sstabellini@kernel.org>
Since the behavior of "diff -p" to use an unindented label as context
identifier often makes it harder to review patches, make explicit the
requirement for labels to be indented.
Signed-off-by: Jan Beulich <jbeulich@suse.com>
Acked-by: Stefano Stabellini <sstabellini@kernel.org>
Introduce a list of MISRA C rules that apply to the Xen hypervisor. The
list is in RST format.
Specify that rules deviations need to be documented. Introduce a
documentation tag for in-code comments to mark them as deviations. Also
mention that other documentation mechanisms are work-in-progress.
Add a mention of the new list to CODING_STYLE.
Signed-off-by: Stefano Stabellini <stefano.stabellini@xilinx.com>
Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>
Acked-by: Julien Grall <jgrall@amazon.com>
It's not always clear what the best way is to handle unexpected
conditions: whether with ASSERT(), domain_crash(), BUG_ON(), or some
other method. All methods have a risk of introducing security
vulnerabilities and unnecessary instabilities to production systems.
Provide guidelines for different options and when to use them.
Signed-off-by: George Dunlap <george.dunlap@citrix.com>
Acked-by: Jan Beulich <jbeulich@suse.com>
Acked-by: Julien Grall <julien@xen.org>
One of the common ways in which contributors trip up over the
CODING_STYLE guides is by not putting a full stop at the end of a
comment when there is only a single sentence. Calling these out is a
waste of everybody's time: The full stop at the end of a comment with
a single sentence (or a single phrase) adds absolutely nothing to the
legibility of the code.
Modify CODING_STYLE to allow comments with a single sentence or
sentence fragment to either have a full stop or not, while making it
clear that comments with multiple sentences must have a full stop at
the end of each sentence.
Signed-off-by: George Dunlap <george.dunlap@citrix.com>
Acked-by: Ian Jackson <ian.jackson@citrix.com>
Juergen Gross