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