Commit | Line | Data |
---|---|---|
9cfe06f8 SR |
1 | /* |
2 | * If TRACE_SYSTEM is defined, that will be the directory created | |
4e20e3a6 | 3 | * in the ftrace directory under /sys/kernel/tracing/events/<system> |
9cfe06f8 | 4 | * |
44ad18e0 | 5 | * The define_trace.h below will also look for a file name of |
9cfe06f8 | 6 | * TRACE_SYSTEM.h where TRACE_SYSTEM is what is defined here. |
44ad18e0 | 7 | * In this case, it would look for sample.h |
9cfe06f8 | 8 | * |
44ad18e0 SR |
9 | * If the header name will be different than the system name |
10 | * (as in this case), then you can override the header name that | |
11 | * define_trace.h will look up by defining TRACE_INCLUDE_FILE | |
9cfe06f8 | 12 | * |
44ad18e0 SR |
13 | * This file is called trace-events-sample.h but we want the system |
14 | * to be called "sample". Therefore we must define the name of this | |
15 | * file: | |
9cfe06f8 | 16 | * |
44ad18e0 | 17 | * #define TRACE_INCLUDE_FILE trace-events-sample |
9cfe06f8 | 18 | * |
44ad18e0 | 19 | * As we do an the bottom of this file. |
d0b6e04a LZ |
20 | * |
21 | * Notice that TRACE_SYSTEM should be defined outside of #if | |
22 | * protection, just like TRACE_INCLUDE_FILE. | |
9cfe06f8 SR |
23 | */ |
24 | #undef TRACE_SYSTEM | |
71e1c8ac | 25 | #define TRACE_SYSTEM sample |
9cfe06f8 | 26 | |
d0b6e04a LZ |
27 | /* |
28 | * Notice that this file is not protected like a normal header. | |
29 | * We also must allow for rereading of this file. The | |
30 | * | |
31 | * || defined(TRACE_HEADER_MULTI_READ) | |
32 | * | |
33 | * serves this purpose. | |
34 | */ | |
35 | #if !defined(_TRACE_EVENT_SAMPLE_H) || defined(TRACE_HEADER_MULTI_READ) | |
36 | #define _TRACE_EVENT_SAMPLE_H | |
37 | ||
38 | /* | |
39 | * All trace headers should include tracepoint.h, until we finally | |
40 | * make it into a standard header. | |
41 | */ | |
42 | #include <linux/tracepoint.h> | |
43 | ||
9cfe06f8 SR |
44 | /* |
45 | * The TRACE_EVENT macro is broken up into 5 parts. | |
46 | * | |
47 | * name: name of the trace point. This is also how to enable the tracepoint. | |
48 | * A function called trace_foo_bar() will be created. | |
49 | * | |
50 | * proto: the prototype of the function trace_foo_bar() | |
51 | * Here it is trace_foo_bar(char *foo, int bar). | |
52 | * | |
53 | * args: must match the arguments in the prototype. | |
54 | * Here it is simply "foo, bar". | |
55 | * | |
56 | * struct: This defines the way the data will be stored in the ring buffer. | |
4e20e3a6 SRRH |
57 | * The items declared here become part of a special structure |
58 | * called "__entry", which can be used in the fast_assign part of the | |
59 | * TRACE_EVENT macro. | |
60 | * | |
61 | * Here are the currently defined types you can use: | |
62 | * | |
63 | * __field : Is broken up into type and name. Where type can be any | |
64 | * primitive type (integer, long or pointer). | |
65 | * | |
66 | * __field(int, foo) | |
67 | * | |
68 | * __entry->foo = 5; | |
69 | * | |
70 | * __field_struct : This can be any static complex data type (struct, union | |
71 | * but not an array). Be careful using complex types, as each | |
72 | * event is limited in size, and copying large amounts of data | |
73 | * into the ring buffer can slow things down. | |
74 | * | |
75 | * __field_struct(struct bar, foo) | |
76 | * | |
77 | * __entry->bar.x = y; | |
78 | ||
79 | * __array: There are three fields (type, name, size). The type is the | |
80 | * type of elements in teh array, the name is the name of the array. | |
81 | * size is the number of items in the array (not the total size). | |
82 | * | |
83 | * __array( char, foo, 10) is the same as saying: char foo[10]; | |
84 | * | |
85 | * Assigning arrays can be done like any array: | |
86 | * | |
87 | * __entry->foo[0] = 'a'; | |
88 | * | |
89 | * memcpy(__entry->foo, bar, 10); | |
90 | * | |
91 | * __dynamic_array: This is similar to array, but can vary is size from | |
92 | * instance to instance of the tracepoint being called. | |
93 | * Like __array, this too has three elements (type, name, size); | |
94 | * type is the type of the element, name is the name of the array. | |
95 | * The size is different than __array. It is not a static number, | |
96 | * but the algorithm to figure out the length of the array for the | |
97 | * specific instance of tracepoint. Again, size is the numebr of | |
98 | * items in the array, not the total length in bytes. | |
99 | * | |
100 | * __dynamic_array( int, foo, bar) is similar to: int foo[bar]; | |
101 | * | |
102 | * Note, unlike arrays, you must use the __get_dynamic_array() macro | |
103 | * to access the array. | |
104 | * | |
105 | * memcpy(__get_dynamic_array(foo), bar, 10); | |
106 | * | |
107 | * Notice, that "__entry" is not needed here. | |
108 | * | |
109 | * __string: This is a special kind of __dynamic_array. It expects to | |
110 | * have a nul terminated character array passed to it (it allows | |
111 | * for NULL too, which would be converted into "(null)"). __string | |
112 | * takes two paramenter (name, src), where name is the name of | |
113 | * the string saved, and src is the string to copy into the | |
114 | * ring buffer. | |
115 | * | |
116 | * __string(foo, bar) is similar to: strcpy(foo, bar) | |
117 | * | |
118 | * To assign a string, use the helper macro __assign_str(). | |
119 | * | |
120 | * __assign_str(foo, bar); | |
121 | * | |
122 | * In most cases, the __assign_str() macro will take the same | |
123 | * parameters as the __string() macro had to declare the string. | |
124 | * | |
125 | * __bitmask: This is another kind of __dynamic_array, but it expects | |
126 | * an array of longs, and the number of bits to parse. It takes | |
127 | * two parameters (name, nr_bits), where name is the name of the | |
128 | * bitmask to save, and the nr_bits is the number of bits to record. | |
129 | * | |
130 | * __bitmask(target_cpu, nr_cpumask_bits) | |
131 | * | |
132 | * To assign a bitmask, use the __assign_bitmask() helper macro. | |
133 | * | |
134 | * __assign_bitmask(target_cpus, cpumask_bits(bar), nr_cpumask_bits); | |
9cfe06f8 | 135 | * |
9cfe06f8 SR |
136 | * |
137 | * fast_assign: This is a C like function that is used to store the items | |
4e20e3a6 SRRH |
138 | * into the ring buffer. A special variable called "__entry" will be the |
139 | * structure that points into the ring buffer and has the same fields as | |
140 | * described by the struct part of TRACE_EVENT above. | |
9cfe06f8 SR |
141 | * |
142 | * printk: This is a way to print out the data in pretty print. This is | |
143 | * useful if the system crashes and you are logging via a serial line, | |
144 | * the data can be printed to the console using this "printk" method. | |
4e20e3a6 SRRH |
145 | * This is also used to print out the data from the trace files. |
146 | * Again, the __entry macro is used to access the data from the ring buffer. | |
147 | * | |
148 | * Note, __dynamic_array, __string, and __bitmask require special helpers | |
149 | * to access the data. | |
150 | * | |
151 | * For __dynamic_array(int, foo, bar) use __get_dynamic_array(foo) | |
152 | * Use __get_dynamic_array_len(foo) to get the length of the array | |
153 | * saved. | |
154 | * | |
155 | * For __string(foo, bar) use __get_str(foo) | |
156 | * | |
157 | * For __bitmask(target_cpus, nr_cpumask_bits) use __get_bitmask(target_cpus) | |
158 | * | |
9cfe06f8 SR |
159 | * |
160 | * Note, that for both the assign and the printk, __entry is the handler | |
161 | * to the data structure in the ring buffer, and is defined by the | |
162 | * TP_STRUCT__entry. | |
163 | */ | |
4e20e3a6 SRRH |
164 | |
165 | /* | |
166 | * It is OK to have helper functions in the file, but they need to be protected | |
167 | * from being defined more than once. Remember, this file gets included more | |
168 | * than once. | |
169 | */ | |
170 | #ifndef __TRACE_EVENT_SAMPLE_HELPER_FUNCTIONS | |
171 | #define __TRACE_EVENT_SAMPLE_HELPER_FUNCTIONS | |
172 | static inline int __length_of(const int *list) | |
173 | { | |
174 | int i; | |
175 | ||
176 | if (!list) | |
177 | return 0; | |
178 | ||
179 | for (i = 0; list[i]; i++) | |
180 | ; | |
181 | return i; | |
182 | } | |
183 | #endif | |
184 | ||
9cfe06f8 SR |
185 | TRACE_EVENT(foo_bar, |
186 | ||
4e20e3a6 SRRH |
187 | TP_PROTO(const char *foo, int bar, const int *lst, |
188 | const char *string, const struct cpumask *mask), | |
9cfe06f8 | 189 | |
4e20e3a6 | 190 | TP_ARGS(foo, bar, lst, string, mask), |
9cfe06f8 SR |
191 | |
192 | TP_STRUCT__entry( | |
193 | __array( char, foo, 10 ) | |
194 | __field( int, bar ) | |
4e20e3a6 SRRH |
195 | __dynamic_array(int, list, __length_of(lst)) |
196 | __string( str, string ) | |
197 | __bitmask( cpus, num_possible_cpus() ) | |
9cfe06f8 SR |
198 | ), |
199 | ||
200 | TP_fast_assign( | |
d8fae2f6 | 201 | strlcpy(__entry->foo, foo, 10); |
9cfe06f8 | 202 | __entry->bar = bar; |
4e20e3a6 SRRH |
203 | memcpy(__get_dynamic_array(list), lst, |
204 | __length_of(lst) * sizeof(int)); | |
205 | __assign_str(str, string); | |
206 | __assign_bitmask(cpus, cpumask_bits(mask), num_possible_cpus()); | |
9cfe06f8 SR |
207 | ), |
208 | ||
4e20e3a6 SRRH |
209 | TP_printk("foo %s %d %s %s (%s)", __entry->foo, __entry->bar, |
210 | __print_array(__get_dynamic_array(list), | |
211 | __get_dynamic_array_len(list), | |
212 | sizeof(int)), | |
213 | __get_str(str), __get_bitmask(cpus)) | |
9cfe06f8 | 214 | ); |
c4c7eb29 SRRH |
215 | |
216 | /* | |
217 | * There may be a case where a tracepoint should only be called if | |
218 | * some condition is set. Otherwise the tracepoint should not be called. | |
219 | * But to do something like: | |
220 | * | |
221 | * if (cond) | |
222 | * trace_foo(); | |
223 | * | |
224 | * Would cause a little overhead when tracing is not enabled, and that | |
225 | * overhead, even if small, is not something we want. As tracepoints | |
226 | * use static branch (aka jump_labels), where no branch is taken to | |
227 | * skip the tracepoint when not enabled, and a jmp is placed to jump | |
228 | * to the tracepoint code when it is enabled, having a if statement | |
229 | * nullifies that optimization. It would be nice to place that | |
230 | * condition within the static branch. This is where TRACE_EVENT_CONDITION | |
231 | * comes in. | |
232 | * | |
233 | * TRACE_EVENT_CONDITION() is just like TRACE_EVENT, except it adds another | |
234 | * parameter just after args. Where TRACE_EVENT has: | |
235 | * | |
236 | * TRACE_EVENT(name, proto, args, struct, assign, printk) | |
237 | * | |
238 | * the CONDITION version has: | |
239 | * | |
240 | * TRACE_EVENT_CONDITION(name, proto, args, cond, struct, assign, printk) | |
241 | * | |
242 | * Everything is the same as TRACE_EVENT except for the new cond. Think | |
243 | * of the cond variable as: | |
244 | * | |
245 | * if (cond) | |
246 | * trace_foo_bar_with_cond(); | |
247 | * | |
248 | * Except that the logic for the if branch is placed after the static branch. | |
249 | * That is, the if statement that processes the condition will not be | |
250 | * executed unless that traecpoint is enabled. Otherwise it still remains | |
251 | * a nop. | |
252 | */ | |
253 | TRACE_EVENT_CONDITION(foo_bar_with_cond, | |
254 | ||
255 | TP_PROTO(const char *foo, int bar), | |
256 | ||
257 | TP_ARGS(foo, bar), | |
258 | ||
259 | TP_CONDITION(!(bar % 10)), | |
260 | ||
261 | TP_STRUCT__entry( | |
262 | __string( foo, foo ) | |
263 | __field( int, bar ) | |
264 | ), | |
265 | ||
266 | TP_fast_assign( | |
267 | __assign_str(foo, foo); | |
268 | __entry->bar = bar; | |
269 | ), | |
270 | ||
271 | TP_printk("foo %s %d", __get_str(foo), __entry->bar) | |
272 | ); | |
9cfe06f8 SR |
273 | #endif |
274 | ||
275 | /***** NOTICE! The #if protection ends here. *****/ | |
276 | ||
277 | ||
278 | /* | |
279 | * There are several ways I could have done this. If I left out the | |
280 | * TRACE_INCLUDE_PATH, then it would default to the kernel source | |
281 | * include/trace/events directory. | |
282 | * | |
283 | * I could specify a path from the define_trace.h file back to this | |
284 | * file. | |
285 | * | |
286 | * #define TRACE_INCLUDE_PATH ../../samples/trace_events | |
287 | * | |
44ad18e0 SR |
288 | * But the safest and easiest way to simply make it use the directory |
289 | * that the file is in is to add in the Makefile: | |
9cfe06f8 | 290 | * |
44ad18e0 | 291 | * CFLAGS_trace-events-sample.o := -I$(src) |
9cfe06f8 SR |
292 | * |
293 | * This will make sure the current path is part of the include | |
44ad18e0 | 294 | * structure for our file so that define_trace.h can find it. |
9cfe06f8 SR |
295 | * |
296 | * I could have made only the top level directory the include: | |
297 | * | |
298 | * CFLAGS_trace-events-sample.o := -I$(PWD) | |
299 | * | |
300 | * And then let the path to this directory be the TRACE_INCLUDE_PATH: | |
301 | * | |
302 | * #define TRACE_INCLUDE_PATH samples/trace_events | |
303 | * | |
44ad18e0 SR |
304 | * But then if something defines "samples" or "trace_events" as a macro |
305 | * then we could risk that being converted too, and give us an unexpected | |
9cfe06f8 SR |
306 | * result. |
307 | */ | |
308 | #undef TRACE_INCLUDE_PATH | |
71e1c8ac | 309 | #undef TRACE_INCLUDE_FILE |
9cfe06f8 | 310 | #define TRACE_INCLUDE_PATH . |
71e1c8ac SR |
311 | /* |
312 | * TRACE_INCLUDE_FILE is not needed if the filename and TRACE_SYSTEM are equal | |
313 | */ | |
314 | #define TRACE_INCLUDE_FILE trace-events-sample | |
9cfe06f8 | 315 | #include <trace/define_trace.h> |