11972 resync smatch

          --- old/usr/src/tools/smatch/src/Documentation/smatch.txt
          +++ new/usr/src/tools/smatch/src/Documentation/smatch.txt

   1    1  Smatch
   2    2  
   3    3  1.  Building Smatch
   4    4  2.  Using Smatch
   5    5  3.  Smatch vs Sparse
   6    6  
   7    7  
   8    8  Section 1:  Building Smatch
   9    9  ---------------------------
  10   10  
  11   11  Smatch requires sqlite3.  It requires the binaries and the C, Perl and
  12   12  Python libraries for sqlite3.
  13   13  
  14   14  apt-get install sqlite3 libsqlite3-dev libdbd-sqlite3-perl
  15   15  
  16   16  Smatch is easy to build.  Just type `make`.  There isn't an install process
  17   17  right now so just run it from the build directory.
  18   18  
  19   19  
  20   20  Section 2:  Using Smatch
  21   21  ------------------------
  22   22  
  23   23  Smatch can be used with a cross function database. It's not mandatory to
  24   24  build the database but it's a useful thing to do.  Building the database
  25   25  for the kernel takes 2-3 hours on my computer.  For the kernel you build
  26   26  the database with:
  27   27  
  28   28          cd ~/path/to/kernel_dir
  29   29          ~/path/to/smatch_dir/smatch_scripts/build_kernel_data.sh
  30   30  
  31   31  For projects other than the kernel you run Smatch with the options
  32   32  "--call-tree --info --param-mapper --spammy" and finish building the
  33   33  database by running the script:
  34   34  
  35   35          ~/progs/smatch/devel/smatch_data/db/create_db.sh
  36   36  
  37   37  Each time you rebuild the cross function database it becomes more accurate. I
  38   38  normally rebuild the database every morning.
  39   39  
  40   40  If you are running Smatch over the whole kernel you can use the following
  41   41  command:
  42   42  
  43   43          ~/progs/smatch/devel/smatch_scripts/test_kernel.sh
  44   44  
  45   45  The test_kernel.sh script will create a .c.smatch file for every file it tests
  46   46  and a combined smatch_warns.txt file with all the warnings.
  47   47  

  48   48  If you are running Smatch just over one kernel file:
  49   49  
  50   50          ~/progs/smatch/devel/smatch_scripts/kchecker drivers/whatever/file.c
  51   51  
  52   52  You can also build a directory like this:
  53   53  
  54   54          ~/progs/smatch/devel/smatch_scripts/kchecker drivers/whatever/
  55   55  
  56   56  The kchecker script prints its warnings to stdout.
  57   57  
       58 +The above scripts will ensure that any ARCH or CROSS_COMPILE environment
       59 +variables are passed to kernel build system - thus allowing for the use of
       60 +Smatch with kernels that are normally built with cross-compilers.
       61 +
  58   62  If you are building something else (which is not the Linux kernel) then use
  59   63  something like:
  60   64  
  61   65          make CHECK="~/progs/smatch/devel/smatch --full-path" \
  62   66                  CC=~/progs/smatch/devel/smatch/cgcc | tee smatch_warns.txt
  63   67  
  64   68  The makefile has to let people set the CC with an environment variable for that
  65   69  to work, of course.
  66   70  
  67   71  
  68   72  Section 3:  Smatch vs Sparse
  69   73  ----------------------------
  70   74  
  71   75  Smatch uses Sparse as a C parser.  I have made a few hacks to Sparse so I
  72   76  have to distribute the two together.  Sparse is released under the MIT license
  73   77  and Smatch is GPLv2+.  If you make changes to Sparse please send those to the
  74   78  Sparse mailing list linux-sparse@vger.kernel.org and I will pick them up from
  75   79  there.  Partly I do that for licensing reasons because I don't want to pull GPL
  76   80  changes into the Sparse code I re-distribute.
  77   81  
    

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX