5e0a073c |
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 | Note about strings : |
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 |
18 | to the slowest. |
19 | 1 - The C code presents a fixed size string. |
20 | For example, you find : |
21 | char mystring[10]; |
22 | as string definition. |
23 | |
24 | you must then define it as an array of char : |
25 | <array size=10/><char></array> |
26 | |
27 | Note, however, that you might not want to declare a fixed size for trace size |
28 | and unnecessary copy matters. |
29 | |
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. |
32 | |
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. |
37 | |
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. |
42 | |
43 | 2 - The C code presents a variable size string together with its |
44 | size. |
45 | |
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. |
49 | |
50 | you must use a sequence to declare this efficiently : |
51 | <sequence><uint><char></sequence> |
52 | |
53 | 3 - The C code presents a \0 terminated string. |
54 | |
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 |
58 | memcpy. |
59 | |
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. |
62 | |
63 | Declare like this : |
64 | <string> |
65 | |
66 | Here is a brief description of how to use genevent. |
67 | |
68 | make |
69 | make install |
70 | |
71 | |
72 | * Add new events to the kernel with genevent |
73 | |
74 | su - |
75 | cd /usr/local/share/LinuxTraceToolkitViewer/facilities |
76 | cp process.xml yourfacility.xml |
77 | * edit yourfacility.xml to fit your needs. |
78 | cd /tmp |
79 | /usr/local/bin/genevent /usr/local/share/LinuxTraceToolkitViewer/yourfacility.xml |
80 | cp ltt-facility-yourfacility.h ltt-facility-id-yourfacility.h \ |
11701f4d |
81 | /usr/src/linux-2.6.12-rc4-lttng-0.5.0/include/linux/ltt |
5e0a073c |
82 | cp ltt-facility-loader-yourfacility.c ltt-facility-loader-yourfacility.h \ |
11701f4d |
83 | /usr/src/linux-2.6.12-rc4-lttng-0.5.0/ltt |
5e0a073c |
84 | * edit the kernel file you want to instrument |
85 | - Add #include <linux/ltt/ltt-facility-yourfacility.h> at the beginning |
86 | of the file. |
87 | - Add a call to the tracing functions. See their names and parameters in |
11701f4d |
88 | /usr/src/linux-2.6.12-rc4-lttng-0.5.0/include/linux/ltt/ltt-facility-yourfacility.h |
5e0a073c |
89 | |
90 | |
91 | |
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). |
95 | |