README-smatch

   1         ***Compiling Smatch***
   2
   3 make
   4
   5 This compiles creates a binary called "smatch".
   6
   7         ***Using Smatch***
   8
   9 Normally you can do this:
  10
  11         make CC=/path/to/cgcc CHECK="/path/to/smatch --full-path" | tee warns.txt
  12
  13 Smatch has specific checks for some projects which you can enable
  14 with the "-p" parameter.
  15
  16         make CC=/path/to/cgcc CHECK="/path/to/smatch --full-path -p=wine" | tee warns.txt
  17
  18 For the Linux kernel use this command:
  19
  20         make C=1 CHECK="/path/to/smatch --full-path -p=kernel" | tee warns.txt
  21
  22 After the compile finishes and you have a warns.txt file, you can view the errors
  23 with the following command:
  24
  25         egrep '(warn|error):' warns.txt | tee err-list
  26
  27 There are also a couple helper scripts for specific types of errors in the
  28 smatch_scripts/ directory.
  29
  30         smatch_scripts/filter_kernel_deref_check.sh
  31         smatch_scripts/show_unreachable.sh
  32         smatch_scripts/show_ifs.sh
  33
  34 BTW, if you are testing the kernel and only want to test one file you can do:
  35
  36         /path/to/smatch_scripts/kchecker drivers/whatever/file.c
  37
  38 The kchecker script also has an option "--sparse" which runs sparse on the file
  39 instead of smatch.  So when I am writing kernel patches in vim I do:
  40
  41         :! kchecker % && kchecker --sparse %
  42
  43
  44         ***Debugging Hints***
  45
  46 Sometimes it is not obvious why smatch is printing an error.  The --debug
  47 option is useful here.  It prints a message on each state change.
  48
  49 Also if smatch crashes, use:  kchecker --valgrind drivers/whatever/file.c and
  50 send me the stack dump.
  51
  52         ***How Smatch Works***
  53
  54 It's basically a state machine that tracks the flow of code.
  55
  56 int a;  <- state is unitialized.
  57
  58 if (b) {
  59        a = foo();  <- state is initialized.
  60        if (a) {
  61               bar(a);  <- state is non zero.
  62        }
  63 }
  64 baz(a);  <- state is undefined.  possibly unitialized, zero, or non-zero
  65
  66 The core parts of smatch understand how code flows, if conditions, loops,
  67 and merging states back together.  The checker bits keep track of states
  68 that they are interested in and print error messages and so on.
  69
  70         ***Coding Smatch***
  71
  72 The core smatch files start with "smatch_" the check scripts are named
  73 "check_*.c".  There is a template check script called check_template.c
  74 that is designed to teach the basics.  Rename it and edit out the bits
  75 you want.
  76
  77 The first file you should look at is smatch.h.  All the
  78 functions for check scripts are at the top.
  79
  80 Smatch is based on sparse.  You will want to understand a couple sparse
  81 data types:
  82         struct expression from expression.h
  83         struct symbol from symbol.h
  84         struct statement from parse.h
  85
  86 More complicated scripts are also going to need functions from smatch_slist.h
  87