Timeline

2026-05-21

init

Smatch is a static analysis tool specifically designed for the Linux kernel. It can deeply trace code execution paths and discover deeply hidden bugs, such as null pointer dereferences, lock usage errors, resource leaks, etc. Reference documentation:

smatch

https://github.com/error27/smatch/blob/master/Documentation/smatch.rst

Building smatch:

1
2
3
4
5
6
7
# Install dependencies
sudo apt-get install sqlite3 libsqlite3-dev libdbd-sqlite3-perl
# Build smatch
cd ~/repository/linux/
wget https://github.com/error27/smatch/archive/refs/tags/1.74.tar.gz -O smatch-1.74.tar.gz
cd smatch-1.74
make -j$(nproc)

Kernel

Smatch essentially hooks into the kernel build system, so it must be able to correctly locate the compiler and header files. Therefore, if cross-compilation is needed, environment variables must be set first.

1
2
export ARCH=arm64
export CROSS_COMPILE=aarch64-none-linux-gnu-

Analyze and build the database:

1
2
3
4
5
6
7
8
cd ~/repository/linux/linux-5.10.256

# Build Linux
make defconfig
make -j$(nproc) Image

# Static analysis and database building
~/repository/linux/smatch-1.74/smatch_scripts/build_kernel_data.sh

build_kernel_data.sh calls smatch_scripts/test_kernel.sh with --call-tree, --info, --spammy, --data=$DATA_DIR flags, then calls smatch_data/db/create_db.sh to build the smatch database.

smatch does not strictly require building a database, but having one makes it much more powerful. Once the global database is built, the next time you compile, Smatch can answer questions like: “How many times has printk been called across the entire kernel?”, “Has this struct pointer been freed in other C files?”, enabling epic-level cross-file vulnerability detection.

Run smatch for static analysis on the kernel: run smatch checks on the entire kernel

1
~/repository/linux/smatch-1.74/smatch_scripts/test_kernel.sh --data="$HOME/repository/linux/smatch-1.74/smatch_data"

Script parameters:

  • --endian: Enable big/little endian checks.
  • --target "bzImage": Specify build target (default is bzImage modules).
  • --log smatch_compile.warns: Specify the build log output file.
  • --wlog smatch_warns.txt: Custom Smatch warning output filename.

After compilation, two files are generated in the current directory:

  • smatch_compile.warns: Full kernel build log (including errors and warnings).
  • smatch_warns.txt: Pure Smatch static check warning messages.

You can also check only specific files or directories:

1
2
~/repository/linux/smatch-1.74/smatch_scripts/kchecker drivers/rpmsg/rpmsg_core.c
~/repository/linux/smatch-1.74/smatch_scripts/kchecker drivers/rpmsg/

The smatch author recommends frequently updating the smatch database, as each update improves the accuracy of cross-function checks:

1
~/repository/linux/smatch-1.74/smatch_data/db/create_db.sh -p=kernel smatch_warns.txt

When running, smatch reads rules set in smatch_data. The relevant logic is in ~/repository/linux/smatch-1.74/smatch.c in static char *get_data_dir(char *arg0): the data directory can be specified with --data=/path/to/smatch_data.

Out-of-tree Module

For non-kernel projects, use the following method to build the database and analyze:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
export ARCH=arm64
export CROSS_COMPILE=aarch64-none-linux-gnu-

make -C ~/repository/linux/linux-5.10.256 \
     M=$PWD \
     -j$(nproc) \
     CHECK="$HOME/repository/linux/smatch-1.74/smatch -p=kernel --file-output --succeed --call-tree --info --spammy --data=$HOME/repository/linux/smatch-1.74/smatch_data" \
     C=2

~/repository/linux/smatch-1.74/smatch_data/db/create_db.sh -p=kernel hello_world.c.smatch

make -C ~/repository/linux/linux-5.10.256 \
     M=$PWD \
     -j$(nproc) \
     CHECK="$HOME/repository/linux/smatch-1.74/smatch -p=kernel --succeed --data=$HOME/repository/linux/smatch-1.74/smatch_data" \
     C=2
  • --file-output: Output one result file per source file.
  • --succeed: Continue analysis even on errors.
  • --call-tree: Enable cross-function call analysis.
  • --info: More detailed analysis logs.
  • --spammy: More aggressive checks.

When using the --file-output parameter, smatch will not print warnings directly to stdout/stderr by default. Instead, it generates a bunch of hidden text files alongside your source code:

  • .hello_world.c.smatch (regular warnings)
  • .hello_world.c.smatch.caller_info (if you added --info, etc.)
    Static check analysis.

References

[1]
Tools for Automatically Detecting Linux Errors - Static Analysis
[2]
Kernel Testing Guide