readme about strings

git-svn-id: http://ltt.polymtl.ca/svn@1316 04897980-b3bd-0310-b5e0-8ef037075253

diff --git a/genevent-new/README b/genevent-new/README
index 5c9fb4e90f890e866aa9fd8f60f4ba0662b33d7f..ad31d648e4d39986cd3d84184b5c765eca7532bc 100644 (file)
--- a/genevent-new/README
+++ b/genevent-new/README
@@ -12,6 +12,57 @@ There are several files in the directory:
 In fact, crc32.tab, parser.c and parser.h are the same files as  
 those in LTT library.
 
+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 members, 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 lengthtype=<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.
 
 make
@@ -37,3 +88,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
 
 
+
+* 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).
+