11972 resync smatch

          --- old/usr/src/tools/smatch/src/README
          +++ new/usr/src/tools/smatch/src/README
   1      -There are some documents under the Documentation/ directory.
   2      -
   3    1  For parsing implicit dependencies, see smatch_scripts/implicit_dependencies.
        2 +=======
        3 +  sparse (spärs), adj,., spars-er, spars-est.
        4 +        1. thinly scattered or distributed; "a sparse population"
        5 +        2. thin; not thick or dense: "sparse hair"
        6 +        3. scanty; meager.
        7 +        4. semantic parse
        8 +        [ from Latin: spars(us) scattered, past participle of
        9 +          spargere 'to sparge' ]
       10 +
       11 +        Antonym: abundant
       12 +
       13 +Sparse is a semantic parser of source files: it's neither a compiler
       14 +(although it could be used as a front-end for one) nor is it a
       15 +preprocessor (although it contains as a part of it a preprocessing
       16 +phase).
       17 +
       18 +It is meant to be a small - and simple - library.  Scanty and meager,
       19 +and partly because of that easy to use.  It has one mission in life:
       20 +create a semantic parse tree for some arbitrary user for further
       21 +analysis.  It's not a tokenizer, nor is it some generic context-free
       22 +parser.  In fact, context (semantics) is what it's all about - figuring
       23 +out not just what the grouping of tokens are, but what the _types_ are
       24 +that the grouping implies.
       25 +
       26 +And no, it doesn't use lex and yacc (or flex and bison).  In my personal
       27 +opinion, the result of using lex/yacc tends to end up just having to
       28 +fight the assumptions the tools make.
       29 +
       30 +The parsing is done in five phases:
       31 +
       32 + - full-file tokenization
       33 + - pre-processing (which can cause another tokenization phase of another
       34 +   file)
       35 + - semantic parsing.
       36 + - lazy type evaluation
       37 + - inline function expansion and tree simplification
       38 +
       39 +Note the "full file" part. Partly for efficiency, but mostly for ease of
       40 +use, there are no "partial results". The library completely parses one
       41 +whole source file, and builds up the _complete_ parse tree in memory.
       42 +
       43 +Also note the "lazy" in the type evaluation.  The semantic parsing
       44 +itself will know which symbols are typedefines (required for parsing C
       45 +correctly), but it will not have calculated what the details of the
       46 +different types are.  That will be done only on demand, as the back-end
       47 +requires the information. 
       48 +
       49 +This means that a user of the library will literally just need to do
       50 +
       51 +  struct string_list *filelist = NULL;
       52 +  char *file;
       53 +
       54 +  action(sparse_initialize(argc, argv, filelist));
       55 +
       56 +  FOR_EACH_PTR(filelist, file) {
       57 +    action(sparse(file));
       58 +  } END_FOR_EACH_PTR(file);
       59 +
       60 +and he is now done - having a full C parse of the file he opened.  The
       61 +library doesn't need any more setup, and once done does not impose any
       62 +more requirements.  The user is free to do whatever he wants with the
       63 +parse tree that got built up, and needs not worry about the library ever
       64 +again.  There is no extra state, there are no parser callbacks, there is
       65 +only the parse tree that is described by the header files. The action
       66 +funtion takes a pointer to a symbol_list and does whatever it likes with it.
       67 +
       68 +The library also contains (as an example user) a few clients that do the
       69 +preprocessing, parsing and type evaluation and just print out the
       70 +results.  These clients were done to verify and debug the library, and
       71 +also as trivial examples of what you can do with the parse tree once it
       72 +is formed, so that users can see how the tree is organized.
    

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX