genevent-new/README

   1
   2 Mathieu Desnoyers -- November 2005
   3
   4 This is a complete rework of genevent.
   5
   6 The 'genevent' program parses event descriptions and generates
   7 the inline functions to record events in the kernel.
   8
   9 There are several files in the directory:
  10  genevent.c, genevent.h, crc32.tab, parser.c and parser.h
  11
  12 In fact, crc32.tab, parser.c and parser.h are the same files as
  13 those in LTT library.
  14
  15 Important notes :
  16         * Do not put "-" symbols in facilities name.
  17         * Use the exact same name for facility xml file and for facility name.
  18
  19 Note about strings :
  20 There are three methods to write strings in genevent, each suitable and
  21 efficient for a particular case. They are explained here from the fastest
  22 to the slowest.
  23 1 - The C code presents a fixed size string.
  24         For example, you find :
  25                 char mystring[10];
  26         as string definition.
  27
  28         you must then define it as an array of char :
  29         <array size=10/><char></array>
  30
  31         Note, however, that you might not want to declare a fixed size for trace size
  32         and unnecessary copy matters.
  33
  34         For instance, on a 32 bits architecture, copying a n bytes array takes
  35         approximately* n/4 memory read and write, for n/2 memory operations.
  36
  37         Using the       slower method described in (3), with a strlen and memcpy, where
  38         "u" is the number of used caracters, takes u+1 reads for the strlen, and
  39         approximately* (u+1)/4 read and write for the memcpy, for a total of :
  40         (3/2)*(u+1) memory access.
  41
  42         So, if (n/2) > (3/2)*(u+1), or : n > 3*u+3
  43                 where n is the size of the array
  44                                         u is the average number of used caracters (excluding the \0)
  45                                 it becomes faster to use the method number 3 with strlen.
  46
  47 2 - The C code presents a variable size string together with its
  48                 size.
  49
  50         A typical use for this case is filenames in the Linux kernel. The
  51         dentry strucure has a d_name member, which is a struct qstr containing
  52         a unsigned int len and const unsigned char *name.
  53
  54         you must use a sequence to declare this efficiently :
  55         <sequence><uint><char></sequence>
  56
  57 3 - The C code presents a \0 terminated string.
  58
  59         This is the slowest, but most convenient way to declare a string. You are
  60         discouraged to use it when options 1 or 2 are available. It will dynamically
  61         calculate the string length (byte by byte read) and only afterward do a
  62         memcpy.
  63
  64         Note that, as explained in 1, if n > 3*u+3, it becomes faster to use this
  65         method instead of copying the whole fixed size array.
  66
  67         Declare like this :
  68         <string>
  69
  70 Here is a brief description of how to use genevent.
  71
  72 make
  73 make install
  74
  75
  76 * Add new events to the kernel with genevent
  77
  78 su -
  79 cd /usr/local/share/LinuxTraceToolkitViewer/facilities
  80 cp process.xml yourfacility.xml
  81   * edit yourfacility.xml to fit your needs.
  82 cd /tmp
  83 /usr/local/bin/genevent /usr/local/share/LinuxTraceToolkitViewer/yourfacility.xml
  84 cp ltt-facility-yourfacility.h ltt-facility-id-yourfacility.h \
  85          /usr/src/linux-2.6.12-rc4-mm2-lttng-0.2/include/linux/ltt
  86 cp ltt-facility-loader-yourfacility.c ltt-facility-loader-yourfacility.h \
  87          /usr/src/linux-2.6.12-rc4-mm2-lttng-0.2/ltt
  88   * edit the kernel file you want to instrument
  89     - Add #include <linux/ltt/ltt-facility-yourfacility.h> at the beginning
  90       of the file.
  91     - Add a call to the tracing functions. See their names and parameters in
  92       /usr/src/linux-2.6.12-rc4-mm2-lttng-0.2/include/linux/ltt/ltt-facility-yourfacility.h
  93
  94
  95
  96 * The approximation comes from the fact that copies of number of caracters non
  97   multiple of the architecture size takes more operations (maximum of :
  98         (architecture size (in bytes) - 1) operations).
  99