"Fossies" - the Fresh Open Source Software Archive

Member "sfk-1.9.6/mtk/readme.txt" (22 Feb 2020, 4135 Bytes) of package /linux/misc/sfk-1.9.6.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. For more information about "readme.txt" see the Fossies "Dox" file reference documentation.

    1 
    2 The SFK Micro Tracing Kernel (MTK)
    3 ==================================
    4 
    5 LICENSE
    6    The Micro Tracing Kernel by StahlWorks Technologies
    7    is provided as unlimited open source, and free for use
    8    in any project, no matter if commercial or non-commercial.
    9    LIKE ANYTHING ELSE THAT'S FREE, MTK IS PROVIDED AS IS AND COMES
   10    WITH NO WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED.
   11 
   12 HOW TO USE
   13 
   14 Imagine you have a large source code base with thousands of .cpp files,
   15 including either a buggy, inefficient tracing system, or even no
   16 tracing system at all ("printf everywhere"). some companies even have
   17 many different tracing systems within the same source code which,
   18 in the end, also leads to everyone using "printf" again...
   19 
   20 if you want to try out a decent, easy-to-use tracing, do this:
   21 
   22 make a backup of all sources, and then
   23 
   24    -  cd into the root directory of your source base.
   25 
   26    -  copy the mtk/ directory supplied with sfk into there.
   27       this dir contains the micro tracing kernel sources.
   28       they are unlimited open source and can be used for free
   29       in any project, both commercial and non-commercial.
   30 
   31    -  then say
   32 
   33          sfk inst mtk/mtktrace.hpp _mtkb_ -dir . !save_ -file .cpp
   34 
   35       and wait a while. all .cpp files will be processed ("instrumented"),
   36       and afterwards, in (most) c++ methods you will find that
   37       some "_mtkb_" statement has been added at the method entry.
   38 
   39       furthermore, the changed .cpp files contain an include statement
   40 
   41          #include "mtk/mtktrace.hpp"
   42 
   43       just like what you specified with the 'inst' command.
   44 
   45       the source code now contains Block Nesting Control.
   46       you may now add your actual tracing statements.
   47       for example:
   48 
   49          mtklog("main entered with %d parms", argc);
   50 
   51       traces a printf-like text.
   52 
   53    -  now configure what is done with the traces:
   54 
   55          export MTK_TRACE=ring:twe,term:twe,filename:log.txt
   56 
   57       this will
   58       -  trace all mtklog, mtkwarn, mtkerr statements into an internal ring buffer
   59       -  trace them also to terminal and into file "log.txt".
   60          notice that the text is indented according to each thread's nesting level.
   61 
   62       furthermore, if you say somewhere in your sourcecode
   63 
   64          mtkDumpStackTrace(1);
   65 
   66       then you get a stack trace of the current thread
   67       written into log.txt. if you say
   68 
   69          mtkDumpLastSteps(1);
   70 
   71       then you get the last steps of the current thread
   72       written into log.txt.
   73 
   74       other examples:
   75 
   76          mtkDumpStackTrace(0);
   77          mtkDumpLastSteps(0);
   78 
   79       dumps the stack trace/last steps of ALL threads.
   80       this could become a long list (last steps by default
   81       lists up to 10000 records), therefore it's written to file.
   82 
   83          export MTK_TRACE=ring:tb,term:tb,filename:log.txt
   84 
   85       lists every single block (method) entry and exit
   86       both into the ring buffer and onto terminal.
   87 
   88 this is just a short introduction about how to use mtk.
   89 experienced  developers will find out by themselves how this can be used,
   90 for example, in combination with other tracing systems already present
   91 in their source base. mtk is very low-level, low-overhead, and can be
   92 used as a layer below anything else, to mix tracing statements
   93 of different tracing systems back together.
   94 
   95 NOTE: if you decide to integrate mtk permanently within a project,
   96       be careful, and make sure that you provide some compile option
   97       to disable the whole tracing. mtk is intended as an analysis tool,
   98       and as with all free things, there is no guarantee whatsoever 
   99       that mtk will work reliantly, especially within production systems.
  100 
  101 NOTE: if you use temporary (non-check-in) sfk instrumentation together
  102       with sfk patching, it is recommended that you instrument first,
  103       and patch second. this way you can redo your patches easily
  104       and anytime, whereas re-instrumentation ususally takes much longer.
  105 
  106 A further technical note: mtk does not use mutex semaphores so far.
  107 this way it stays as low-overhead as possible. however, you have to expect
  108 that the one or other tracing record may get lost on heavy multithreading.