Documentation/clang-and-static-analysis.txt

   1                 ********************************************
   2                 * Clang/LLVM and Static Analysis on Lustre *
   3                 ********************************************
   4
   5 Original Authors:
   6 =================
   7 Timothy Day <timday@amazon.com>
   8
   9 Contents
  10 1. Introduction
  11 2. Clang/LLVM
  12         2.1 Background
  13         2.2 Usage
  14         2.3 References
  15 3. Compiler Plugins
  16         3.1 History
  17         3.2 Usage
  18         3.3 References
  19 4. Coverity
  20         4.1 Context
  21         4.2 References
  22 5. Miscellaneous Tools
  23
  24 ===================
  25 = 1. Introduction =
  26 ===================
  27
  28 Static analysis is the analysis of a program performed without executing it. The
  29 most familiar form of static analysis is performed by the compiler while building
  30 a program. Potential mistakes and oversights appear as warnings to the developer.
  31 There also exist a number of independent tools and compiler plugins which add
  32 additional warnings, and can detect a wider array of issues.
  33
  34 These automated checks counter some of the deficiencies of C while guarding
  35 against human programming mistakes. As such, Lustre has several mechanisms
  36 for making it easier to run static analysis over the entire tree.
  37
  38 =================
  39 = 2. Clang/LLVM =
  40 =================
  41
  42 2.1 Background
  43 ==============
  44
  45 LLVM is the second major open-source compiler toolchain supported by the Linux
  46 kernel. Clang is the C/C++ for the LLVM ecosystem. While Clang aims to be GCC
  47 compatible, its checks tend to be orthogonal and often stricter than those
  48 performed by GCC. Hence, a program that compiles under GCC may generate
  49 warnings under Clang.
  50
  51 2.2 Usage
  52 =========
  53
  54 To use Clang with Lustre, you must first compile the Linux kernel using Clang.
  55 Documentation for this is linked in the references. Afterwards, configure
  56 with:
  57
  58         ./configure LLVM=1
  59
  60 if your current kernel was compiled with Clang or:
  61
  62         ./configure LLVM=1 --with-linux=path/to/clang/built/linux
  63
  64 otherwise. The LLVM variable behaves identically for both Lustre and Linux.
  65
  66 Additionally, there is a configuration option `--disable-strict-errors` which
  67 attempts to stop compilation errors from blocking the build. This is useful
  68 for seeing all errors and warnings generated across the entire tree.
  69
  70 2.3 References
  71 ==============
  72
  73 Clang Project: https://clang.llvm.org/
  74 Clang/LLVM for Linux: https://docs.kernel.org/kbuild/llvm.html
  75
  76 =======================
  77 = 3. Compiler Plugins =
  78 =======================
  79
  80 3.1 History
  81 ===========
  82
  83 Work in the past was funded by openSFS to created Clang plugins to help cleanup
  84 cruft in the Lustre tree. This work currently lives in the 'lustre-static-analysis'
  85 repository on Gerrit. It consists of two plugins Endian and DeclUse. However, they
  86 haven't been updated in a number of years.
  87
  88 A new plugin, FindStatic, has been developed to find functions that could be made
  89 static. As a side effect, it makes it easier for the compiler to detect dead code.
  90 It also serves as an example of what a simple, up-to-date Clang plugin looks like.
  91
  92 3.2 Usage
  93 =========
  94
  95 The '--enable-compiler-plugins' configure options automatically builds and sets up
  96 the in-tree compiler plugins. When 'make' is run, the plugin will also get run.
  97 New warnings will get output alongside normal compiler warnings. Currently,
  98 only Clang is supported (since only Clang plugins have been developed).
  99
 100 3.3 References
 101 ==============
 102
 103 Old Plugins: https://wiki.whamcloud.com/pages/viewpage.action?pageId=18645101
 104 FindStatic: https://review.whamcloud.com/c/fs/lustre-release/+/51659
 105
 106 ===============
 107 = 4. Coverity =
 108 ===============
 109
 110 4.1 Context
 111 ===========
 112
 113 Coverity Scan is a free scanning service offered to open-source projects. It's used
 114 by Linux, openZFS, and a number of other major projects. An earlier version of Coverity
 115 has been used with Lustre in the past. However, that was many years ago.
 116
 117 To see the bugs, request access at the Coverity Scan website. Any patch that addresses
 118 a Coverity bug should ideally have a line in the commit message like:
 119
 120         Addresses-Coverity-ID: 397434 ("Unused value")
 121
 122 This makes it easier to track which bugs still need to be fixed. Currently, the Coverity
 123 Scan project is maintained in an adhoc manner. Hence, the build may be outdated. But it
 124 can be updated easily following the instructions on the site or using the script in
 125 'contrib/coverity' in the Lustre tree. Running 'coverity-run list' will provide more
 126 details.
 127
 128 4.2 References
 129 ==============
 130
 131 Early Coverity: https://wiki.lustre.org/images/8/8a/LUG2013-Lustre_Static_Code_Analysis-Bull.pdf
 132 Coverity Scan Page: https://scan.coverity.com/projects/lustre
 133
 134 ==========================
 135 = 5. Miscellaneous Tools =
 136 ==========================
 137
 138 Other tools that might be investigated, for those interested:
 139
 140 Cppcheck: https://cppcheck.sourceforge.io/ (Static analysis tool)
 141 Sparse: https://www.kernel.org/doc/html/latest/dev-tools/sparse.html (Semantic parser)
 142 Frama-C: https://frama-c.com/ (Formal verification)
 143 ARM MTE: https://learn.arm.com/learning-paths/smartphones-and-mobile/mte/mte/ (Hardware support for memory safety; can be tested via QEMU)
 144 Rust: https://www.rust-lang.org/ (Memory safe by default, recently gained support in the Linux kernel 🦀)
 145
 146 Static analysis is prone to false positives. It's easy to burn a lot of
 147 time on a non-issue. If you use any of these tools (or others), please
 148 consider updating this document with your experiences to help others
 149 in the future.