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