README-smatch

   1     ***Compiling Smatch***
   2
   3 make
   4
   5 This compiles creates a binary called "smatch".
   6
   7     ***Using Smatch***
   8
   9 ./smatch filename.c
  10
  11 For the kernel use:  make -k CHECK=/path/to/smatch C=y bzImage | tee warns.txt
  12
  13 There is also a smatch_scripts/kchecker script for checking individual .c kernel files.
  14
  15 Most of the things that smatch prints out is not actually warnings.
  16 What I was trying to do with that was catch errors where a NULL is
  17 passed to a function that dereferences the parameter without checking.
  18 There is a script that parses that information.
  19
  20       smatch_scripts/find_null_params.sh
  21
  22 Sorry the output is a mess right now.  This needs to be cleaned up.
  23
  24 Sometimes you it is not obvious why smatch is printing an error.
  25 The --debug option is usefull here.  It prints a message on each state change.
  26
  27 Sometimes smatch segfaults.  Use valgrind to get a stack dump.  For the kernel
  28 do:  make -k CHECK="valgrind /path/to/smatch" C=y failing/file.o
  29
  30     ***How Smatch Works***
  31
  32 It's basically a state machine that tracks the flow of code.
  33
  34 int a;  <- state is unitialized.
  35
  36 if (b) {
  37        a = foo();  <- state is initialized.
  38        if (a) {
  39               bar(a);  <- state is non zero.
  40        }
  41 }
  42 baz(a);  <- state is undefined.  possibly unitialized, zero, or non-zero
  43
  44 The core parts of smatch understand how code flows, if conditions, loops,
  45 and merging states back together.  The checker bits keep track of states
  46 that they are interested in and print error messages and so on.
  47
  48     ***Coding Smatch***
  49
  50 The core smatch files start with "smatch_" the check scripts are named
  51 "check_*.c".  There is a template check script called check_template.c
  52 that is designed to teach the basics.  Rename it and edit out the bits
  53 you want.
  54
  55
  56 The first file you should look at is smatch.h.  All the
  57 functions for check scripts are at the top.
  58
  59 Smatch is based on sparse.  You will want to understand a couple sparse
  60 data types:
  61      struct expression from expression.h
  62      struct symbol from symbol.h
  63      struct statement from parse.h
  64
  65 More complicated scripts are also going to need functions from smatch_slist.h
  66