Commit | Line | Data |
---|---|---|
5e0cbfb0 PP |
1 | --- |
2 | id: lttng-adaptation-layer | |
3 | --- | |
4 | ||
5 | The steps to write the LTTng adaptation layer are, in your | |
6 | LTTng-modules copy's source code tree: | |
7 | ||
8 | 1. In `instrumentation/events/lttng-module`, | |
9 | add a header <code><em>subsys</em>.h</code> for your custom | |
10 | subsystem <code><em>subsys</em></code> and write your | |
11 | tracepoint definitions using LTTng-modules macros in it. | |
12 | Those macros look like the mainline kernel equivalents, | |
13 | but they present subtle, yet important differences. | |
14 | 2. In `probes`, create the C source file of the LTTng probe kernel | |
15 | module for your subsystem. It should be named | |
16 | <code>lttng-probe-<em>subsys</em>.c</code>. | |
17 | 3. Edit `probes/Makefile` so that the LTTng-modules project | |
18 | builds your custom LTTng probe kernel module. | |
19 | 4. Build and install LTTng kernel modules. | |
20 | ||
21 | Following our `hello_world` event example, here's the content of | |
22 | `instrumentation/events/lttng-module/hello.h`: | |
23 | ||
24 | ~~~ c | |
25 | #undef TRACE_SYSTEM | |
26 | #define TRACE_SYSTEM hello | |
27 | ||
28 | #if !defined(_TRACE_HELLO_H) || defined(TRACE_HEADER_MULTI_READ) | |
29 | #define _TRACE_HELLO_H | |
30 | ||
41aea258 | 31 | #include "../../../probes/lttng-tracepoint-event.h" |
5e0cbfb0 PP |
32 | #include <linux/tracepoint.h> |
33 | ||
34 | LTTNG_TRACEPOINT_EVENT( | |
35 | /* format identical to mainline version for those */ | |
36 | hello_world, | |
37 | TP_PROTO(int foo, const char* bar), | |
38 | TP_ARGS(foo, bar), | |
39 | ||
40 | /* possible differences */ | |
41 | TP_STRUCT__entry( | |
42 | __field(int, my_int) | |
43 | __field(char, char0) | |
44 | __field(char, char1) | |
45 | __string(product, bar) | |
46 | ), | |
47 | ||
48 | /* notice the use of tp_assign()/tp_strcpy() and no semicolons */ | |
49 | TP_fast_assign( | |
50 | tp_assign(my_int, foo) | |
51 | tp_assign(char0, bar[0]) | |
52 | tp_assign(char1, bar[1]) | |
53 | tp_strcpy(product, bar) | |
54 | ), | |
55 | ||
56 | /* This one is actually not used by LTTng either, but must be | |
57 | * present for the moment. | |
58 | */ | |
59 | TP_printk("", 0) | |
60 | ||
61 | /* no semicolon after this either */ | |
62 | ) | |
63 | ||
64 | #endif | |
65 | ||
66 | /* other difference: do NOT include <trace/define_trace.h> */ | |
67 | #include "../../../probes/define_trace.h" | |
68 | ~~~ | |
69 | ||
70 | Some possible entries for `TP_STRUCT__entry()` and `TP_fast_assign()`, | |
71 | in the case of LTTng-modules, are shown in the | |
72 | [LTTng-modules reference](#doc-lttng-modules-ref) section. | |
73 | ||
74 | The best way to learn how to use the above macros is to inspect | |
75 | existing LTTng tracepoint definitions in `instrumentation/events/lttng-module` | |
76 | header files. Compare them with the Linux kernel mainline versions | |
77 | in `include/trace/events`. | |
78 | ||
79 | The next step is writing the LTTng probe kernel module C source file. | |
80 | This one is named <code>lttng-probe-<em>subsys</em>.c</code> | |
81 | in `probes`. You may always use the following template: | |
82 | ||
83 | ~~~ c | |
84 | #include <linux/module.h> | |
85 | #include "../lttng-tracer.h" | |
86 | ||
87 | /* Build time verification of mismatch between mainline TRACE_EVENT() | |
88 | * arguments and LTTng adaptation layer LTTNG_TRACEPOINT_EVENT() arguments. | |
89 | */ | |
90 | #include <trace/events/hello.h> | |
91 | ||
92 | /* create LTTng tracepoint probes */ | |
93 | #define LTTNG_PACKAGE_BUILD | |
94 | #define CREATE_TRACE_POINTS | |
95 | #define TRACE_INCLUDE_PATH ../instrumentation/events/lttng-module | |
96 | ||
97 | #include "../instrumentation/events/lttng-module/hello.h" | |
98 | ||
99 | MODULE_LICENSE("GPL and additional rights"); | |
100 | MODULE_AUTHOR("Your name <your-email>"); | |
101 | MODULE_DESCRIPTION("LTTng hello probes"); | |
102 | MODULE_VERSION(__stringify(LTTNG_MODULES_MAJOR_VERSION) "." | |
103 | __stringify(LTTNG_MODULES_MINOR_VERSION) "." | |
104 | __stringify(LTTNG_MODULES_PATCHLEVEL_VERSION) | |
105 | LTTNG_MODULES_EXTRAVERSION); | |
106 | ~~~ | |
107 | ||
108 | Just replace `hello` with your subsystem name. In this example, | |
109 | `<trace/events/hello.h>`, which is the original mainline tracepoint | |
110 | definition header, is included for verification purposes: the | |
111 | LTTng-modules build system is able to emit an error at build time when | |
112 | the arguments of the mainline `TRACE_EVENT()` definitions do not match | |
113 | the ones of the LTTng-modules adaptation layer | |
114 | (`LTTNG_TRACEPOINT_EVENT()`). | |
115 | ||
116 | Edit `probes/Makefile` and add your new kernel module object | |
117 | next to existing ones: | |
118 | ||
119 | ~~~ makefile | |
120 | # ... | |
121 | ||
122 | obj-m += lttng-probe-module.o | |
123 | obj-m += lttng-probe-power.o | |
124 | ||
125 | obj-m += lttng-probe-hello.o | |
126 | ||
127 | # ... | |
128 | ~~~ | |
129 | ||
130 | Time to build! Point to your custom Linux kernel source tree using | |
131 | the `KERNELDIR` variable: | |
132 | ||
133 | <pre class="term"> | |
134 | make <strong>KERNELDIR=/path/to/custom/linux</strong> | |
135 | </pre> | |
136 | ||
137 | Finally, install modules: | |
138 | ||
139 | <pre class="term"> | |
140 | sudo make modules_install | |
141 | </pre> |