change option

[lttv.git] / genevent / README

diff --git a/genevent/README b/genevent/README
index 0edb12aba8d2048e3b846c1f5a7fb699fad59768..d38633d35cd22797ed87e03abb8d44e2daf45b65 100644 (file)
--- a/genevent/README
+++ b/genevent/README
@@ -1,22 +1,73 @@
 
 

-Mathieu Desnoyers -- September 2005
+Mathieu Desnoyers -- November 2005
+
+This is a complete rework of genevent.

 
 The 'genevent' program parses event descriptions and generates 
 the inline functions to record events in the kernel.
 
 
 The 'genevent' program parses event descriptions and generates 
 the inline functions to record events in the kernel.
 

-Right now, the program can only parse simple structure, if a 
-structure has a nested structure, it will not work.
-
-Genevent will soon go through a rewrite, but for now, the strings should be put
-at the beginning of a structure : they will be put there anyways.
-

 There are several files in the directory:
  genevent.c, genevent.h, crc32.tab, parser.c and parser.h
 
 In fact, crc32.tab, parser.c and parser.h are the same files as  
 those in LTT library.
 
 There are several files in the directory:
  genevent.c, genevent.h, crc32.tab, parser.c and parser.h
 
 In fact, crc32.tab, parser.c and parser.h are the same files as  
 those in LTT library.
 

-'core.xml' is an example event description file.
+Important notes : 
+       * Do not put "-" symbols in facilities name.
+       * Use the exact same name for facility xml file and for facility name.
+       * As from genevent 0.17, a standard XML 1.0 description is "required". It must
+               begin with the <?xml version="1.0"?> header.
+
+Note about strings :
+There are three methods to write strings in genevent, each suitable and
+efficient for a particular case. They are explained here from the fastest
+to the slowest.
+1 - The C code presents a fixed size string.
+       For example, you find :
+               char mystring[10];
+       as string definition.
+
+       you must then define it as an array of char :
+       <array size="10"><char></array>
+
+       Note, however, that you might not want to declare a fixed size for trace size
+       and unnecessary copy matters.
+       
+       For instance, on a 32 bits architecture, copying a n bytes array takes
+       approximately* n/4 memory read and write, for n/2 memory operations.
+       
+       Using the       slower method described in (3), with a strlen and memcpy, where
+       "u" is the number of used caracters, takes u+1 reads for the strlen, and
+       approximately* (u+1)/4 read and write for the memcpy, for a total of :
+       (3/2)*(u+1) memory access.
+
+       So, if (n/2) > (3/2)*(u+1), or : n > 3*u+3
+               where n is the size of the array
+                                       u is the average number of used caracters (excluding the \0)
+                               it becomes faster to use the method number 3 with strlen.
+
+2 - The C code presents a variable size string together with its
+               size.
+
+       A typical use for this case is filenames in the Linux kernel. The
+       dentry strucure has a d_name member, which is a struct qstr containing
+       a unsigned int len and const unsigned char *name.
+
+       you must use a sequence to declare this efficiently :
+       <sequence><uint><char></sequence>
+               
+3 - The C code presents a \0 terminated string.
+       
+       This is the slowest, but most convenient way to declare a string. You are
+       discouraged to use it when options 1 or 2 are available. It will dynamically
+       calculate the string length (byte by byte read) and only afterward do a
+       memcpy.
+
+       Note that, as explained in 1, if n > 3*u+3, it becomes faster to use this
+       method instead of copying the whole fixed size array.
+
+       Declare like this :
+       <string>

 
 Here is a brief description of how to use genevent.
 
 
 Here is a brief description of how to use genevent.
 


@@ -43,3 +94,8 @@ cp ltt-facility-loader-yourfacility.c ltt-facility-loader-yourfacility.h \
       /usr/src/linux-2.6.12-rc4-mm2-lttng-0.2/include/linux/ltt/ltt-facility-yourfacility.h
 
 
       /usr/src/linux-2.6.12-rc4-mm2-lttng-0.2/include/linux/ltt/ltt-facility-yourfacility.h
 
 

+
+* The approximation comes from the fact that copies of number of caracters non
+  multiple of the architecture size takes more operations (maximum of :
+       (architecture size (in bytes) - 1) operations).
+