1.. SPDX-License-Identifier: CC-BY-4.0
2
3Xen static analysis
4===================
5
6The Xen codebase integrates some scripts and tools that helps the developer to
7perform static analysis of the code, currently Xen supports three analysis tool
8that are eclair, coverity and cppcheck.
9The Xen tree has a script (xen-analysis.py) available to ease the analysis
10process and it integrates a way to suppress findings on these tools, please
11check the documenting-violation.rst document to know more about it.
12
13Analyse Xen with Coverity or Eclair
14-----------------------------------
15
16The xen-analysis.py script has two arguments to select which tool is used for
17the analysis:
18
19 - xen-analysis.py --run-coverity -- [optional make arguments]
20 - xen-analysis.py --run-eclair -- [optional make arguments]
21
22For example when using Coverity to analyse a Xen build obtained by passing these
23arguments to the make system: XEN_TARGET_ARCH=arm64
24CROSS_COMPILE=aarch64-linux-gnu-, the optional make arguments passed to
25xen-analysis.py must be the same and the command below should be passed to
26Coverity in its build phase:
27
28 - xen-analysis.py --run-coverity -- XEN_TARGET_ARCH=arm64
29   CROSS_COMPILE=aarch64-linux-gnu-
30
31Which tells to the script to prepare the codebase for an analysis by Coverity
32and forwards the make arguments to the make build invocation.
33
34When invoking the script, the procedure below will be followed:
35
36 1. Find which files among \*.c and \*.h has any in-code comment as
37    /* SAF-X-[...] \*/, the meaning of these comments is explained in
38    documenting-violation.rst.
39    Save the files obtained as <file>.safparse and generate <file> files where
40    the special in-code comments above are substituted with the proprietary
41    in-code comment used by the selected analysis tool. The safe.json and
42    false-positive-<tool>.json text file database are used to link each Xen tag
43    to the right proprietary in-code comment.
44 2. Now Xen compilation starts using every <additional make parameters> supplied
45    at the script invocation. Coverity and Eclair are capable of intercepting
46    the compiler running from make to perform their analysis without
47    instrumenting the makefile.
48 3. As final step every <file>.safparse file are reverted back as <file> and
49    every artifact related to the analysis will be cleaned.
50    This step is performed even in case any of the previous step fail, to skip
51    this step, call the script adding the --no-clean argument, but before
52    running again the script, call it with the --clean-only argument, that will
53    execute only this cleaning step.
54
55
56Analyse Xen with Cppcheck
57-------------------------
58
59Cppcheck tool is integrated in xen-analysis.py script, when using the script,
60the tool will be called on every source file compiled by the make build system.
61Here how to start the analysis with Cppcheck:
62
63 - xen-analysis.py --run-cppcheck [--cppcheck-misra] [--cppcheck-html] --
64   [optional make arguments]
65
66The command above tells the script to prepare the codebase and use Cppcheck tool
67for the analysis.
68The optional argument --cppcheck-misra activates the analysis also for MISRA
69compliance.
70The optional argument --cppcheck-html instruct cppcheck to produce an additional
71HTML report.
72
73When invoking the script for Cppcheck analysis, the followed procedure is
74similar to the one above for Coverity or Eclair, but it has some additional
75steps:
76
77 1. This step is the same as step 1 for Coverity/Eclair.
78 2. The cppcheck dependency are created, build directory for cppcheck analysis
79    and an header file containing internal compiler macro
80    (include/generated/compiler-def.h) are generated
81 3. Xen compilation starts using every <additional make parameters> supplied
82    at the script invocation, but because cppcheck is not able to intercept the
83    compiled files and flags on compiler invocation, a script (cppcheck-cc.sh)
84    is passed as CC to the make system, it is a wrapper for the compiler that
85    will also execute cppcheck on every compiled file.
86 4. After the compilation and analysis, the cppcheck report will be created
87    putting together all the cppcheck report fragments for every analysed file.
88    Cppcheck will produce a text fragment and an additional XML report fragment
89    if the script is configured to produce the HTML output.
90 5. This step is the same as step 3 for Coverity/Eclair.
91