tracepoint.h 12.4 KB
Newer Older
1
2
3
4
5
6
#ifndef _LINUX_TRACEPOINT_H
#define _LINUX_TRACEPOINT_H

/*
 * Kernel Tracepoint API.
 *
7
 * See Documentation/trace/tracepoints.txt.
8
9
10
11
12
13
14
15
16
 *
 * (C) Copyright 2008 Mathieu Desnoyers <mathieu.desnoyers@polymtl.ca>
 *
 * Heavily inspired from the Linux Kernel Markers.
 *
 * This file is released under the GPLv2.
 * See the file COPYING for more details.
 */

17
#include <linux/errno.h>
18
19
#include <linux/types.h>
#include <linux/rcupdate.h>
20
#include <linux/static_key.h>
21
22
23
24

struct module;
struct tracepoint;

25
26
27
28
29
struct tracepoint_func {
	void *func;
	void *data;
};

30
31
struct tracepoint {
	const char *name;		/* Tracepoint name */
32
	struct static_key key;
33
34
	void (*regfunc)(void);
	void (*unregfunc)(void);
35
	struct tracepoint_func __rcu *funcs;
36
};
37

38
39
40
41
/*
 * Connect a probe to a tracepoint.
 * Internal API, should not be used directly.
 */
42
extern int tracepoint_probe_register(const char *name, void *probe, void *data);
43
44
45
46
47

/*
 * Disconnect a probe from a tracepoint.
 * Internal API, should not be used directly.
 */
48
49
extern int
tracepoint_probe_unregister(const char *name, void *probe, void *data);
50

51
52
53
54
extern int tracepoint_probe_register_noupdate(const char *name, void *probe,
					      void *data);
extern int tracepoint_probe_unregister_noupdate(const char *name, void *probe,
						void *data);
55
56
extern void tracepoint_probe_update_all(void);

57
58
59
60
61
62
63
64
#ifdef CONFIG_MODULES
struct tp_module {
	struct list_head list;
	unsigned int num_tracepoints;
	struct tracepoint * const *tracepoints_ptrs;
};
#endif /* CONFIG_MODULES */

65
struct tracepoint_iter {
66
67
68
#ifdef CONFIG_MODULES
	struct tp_module *module;
#endif /* CONFIG_MODULES */
69
	struct tracepoint * const *tracepoint;
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
};

extern void tracepoint_iter_start(struct tracepoint_iter *iter);
extern void tracepoint_iter_next(struct tracepoint_iter *iter);
extern void tracepoint_iter_stop(struct tracepoint_iter *iter);
extern void tracepoint_iter_reset(struct tracepoint_iter *iter);

/*
 * tracepoint_synchronize_unregister must be called between the last tracepoint
 * probe unregistration and the end of module exit to make sure there is no
 * caller executing a probe when it is freed.
 */
static inline void tracepoint_synchronize_unregister(void)
{
	synchronize_sched();
}

#define PARAMS(args...) args

#endif /* _LINUX_TRACEPOINT_H */

/*
 * Note: we keep the TRACE_EVENT and DECLARE_TRACE outside the include
 *  file ifdef protection.
 *  This is due to the way trace events work. If a file includes two
 *  trace event headers under one "CREATE_TRACE_POINTS" the first include
 *  will override the TRACE_EVENT and break the second include.
 */

99
100
#ifndef DECLARE_TRACE

101
#define TP_PROTO(args...)	args
102
#define TP_ARGS(args...)	args
103
#define TP_CONDITION(args...)	args
104
105
106
107
108
109

#ifdef CONFIG_TRACEPOINTS

/*
 * it_func[0] is never NULL because there is at least one element in the array
 * when the array itself is non NULL.
110
111
112
113
114
115
 *
 * Note, the proto and args passed in includes "__data" as the first parameter.
 * The reason for this is to handle the "void" prototype. If a tracepoint
 * has a "void" prototype, then it is invalid to declare a function
 * as "(void *, void)". The DECLARE_TRACE_NOARGS() will pass in just
 * "void *data", where as the DECLARE_TRACE() will pass in "void *data, proto".
116
 */
117
#define __DO_TRACE(tp, proto, args, cond, prercu, postrcu)		\
118
	do {								\
119
120
121
		struct tracepoint_func *it_func_ptr;			\
		void *it_func;						\
		void *__data;						\
122
									\
123
124
		if (!(cond))						\
			return;						\
125
		prercu;							\
126
		rcu_read_lock_sched_notrace();				\
127
128
		it_func_ptr = rcu_dereference_sched((tp)->funcs);	\
		if (it_func_ptr) {					\
129
			do {						\
130
131
132
133
				it_func = (it_func_ptr)->func;		\
				__data = (it_func_ptr)->data;		\
				((void(*)(proto))(it_func))(args);	\
			} while ((++it_func_ptr)->func);		\
134
		}							\
135
		rcu_read_unlock_sched_notrace();			\
136
		postrcu;						\
137
138
	} while (0)

139
140
141
142
143
144
145
146
147
#ifndef MODULE
#define __DECLARE_TRACE_RCU(name, proto, args, cond, data_proto, data_args)	\
	static inline void trace_##name##_rcuidle(proto)		\
	{								\
		if (static_key_false(&__tracepoint_##name.key))		\
			__DO_TRACE(&__tracepoint_##name,		\
				TP_PROTO(data_proto),			\
				TP_ARGS(data_args),			\
				TP_CONDITION(cond),			\
148
149
				rcu_irq_enter(),			\
				rcu_irq_exit());			\
150
151
152
153
154
	}
#else
#define __DECLARE_TRACE_RCU(name, proto, args, cond, data_proto, data_args)
#endif

155
156
157
158
159
/*
 * Make sure the alignment of the structure in the __tracepoints section will
 * not add unwanted padding between the beginning of the section and the
 * structure. Force alignment to the same alignment as the section start.
 */
160
#define __DECLARE_TRACE(name, proto, args, cond, data_proto, data_args) \
161
	extern struct tracepoint __tracepoint_##name;			\
162
163
	static inline void trace_##name(proto)				\
	{								\
164
		if (static_key_false(&__tracepoint_##name.key))		\
165
			__DO_TRACE(&__tracepoint_##name,		\
166
				TP_PROTO(data_proto),			\
167
				TP_ARGS(data_args),			\
168
169
				TP_CONDITION(cond),,);			\
	}								\
170
171
	__DECLARE_TRACE_RCU(name, PARAMS(proto), PARAMS(args),		\
		PARAMS(cond), PARAMS(data_proto), PARAMS(data_args))	\
172
173
	static inline int						\
	register_trace_##name(void (*probe)(data_proto), void *data)	\
174
	{								\
175
176
		return tracepoint_probe_register(#name, (void *)probe,	\
						 data);			\
177
	}								\
178
179
	static inline int						\
	unregister_trace_##name(void (*probe)(data_proto), void *data)	\
180
	{								\
181
182
		return tracepoint_probe_unregister(#name, (void *)probe, \
						   data);		\
183
	}								\
184
185
	static inline void						\
	check_trace_callback_type_##name(void (*cb)(data_proto))	\
186
	{								\
187
188
	}

189
190
191
192
193
/*
 * We have no guarantee that gcc and the linker won't up-align the tracepoint
 * structures, so we create an array of pointers that will be used for iteration
 * on the tracepoints.
 */
194
195
196
197
198
#define DEFINE_TRACE_FN(name, reg, unreg)				 \
	static const char __tpstrtab_##name[]				 \
	__attribute__((section("__tracepoints_strings"))) = #name;	 \
	struct tracepoint __tracepoint_##name				 \
	__attribute__((section("__tracepoints"))) =			 \
199
		{ __tpstrtab_##name, STATIC_KEY_INIT_FALSE, reg, unreg, NULL };\
200
201
	static struct tracepoint * const __tracepoint_ptr_##name __used	 \
	__attribute__((section("__tracepoints_ptrs"))) =		 \
202
		&__tracepoint_##name;
203
204
205

#define DEFINE_TRACE(name)						\
	DEFINE_TRACE_FN(name, NULL, NULL);
206
207
208
209
210
211

#define EXPORT_TRACEPOINT_SYMBOL_GPL(name)				\
	EXPORT_SYMBOL_GPL(__tracepoint_##name)
#define EXPORT_TRACEPOINT_SYMBOL(name)					\
	EXPORT_SYMBOL(__tracepoint_##name)

212
#else /* !CONFIG_TRACEPOINTS */
213
#define __DECLARE_TRACE(name, proto, args, cond, data_proto, data_args) \
214
215
	static inline void trace_##name(proto)				\
	{ }								\
216
217
	static inline void trace_##name##_rcuidle(proto)		\
	{ }								\
218
219
220
	static inline int						\
	register_trace_##name(void (*probe)(data_proto),		\
			      void *data)				\
221
222
223
	{								\
		return -ENOSYS;						\
	}								\
224
225
226
	static inline int						\
	unregister_trace_##name(void (*probe)(data_proto),		\
				void *data)				\
227
228
	{								\
		return -ENOSYS;						\
229
	}								\
230
	static inline void check_trace_callback_type_##name(void (*cb)(data_proto)) \
231
	{								\
232
	}
233

234
#define DEFINE_TRACE_FN(name, reg, unreg)
235
236
237
238
#define DEFINE_TRACE(name)
#define EXPORT_TRACEPOINT_SYMBOL_GPL(name)
#define EXPORT_TRACEPOINT_SYMBOL(name)

239
#endif /* CONFIG_TRACEPOINTS */
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255

/*
 * The need for the DECLARE_TRACE_NOARGS() is to handle the prototype
 * (void). "void" is a special value in a function prototype and can
 * not be combined with other arguments. Since the DECLARE_TRACE()
 * macro adds a data element at the beginning of the prototype,
 * we need a way to differentiate "(void *data, proto)" from
 * "(void *data, void)". The second prototype is invalid.
 *
 * DECLARE_TRACE_NOARGS() passes "void" as the tracepoint prototype
 * and "void *__data" as the callback prototype.
 *
 * DECLARE_TRACE() passes "proto" as the tracepoint protoype and
 * "void *__data, proto" as the callback prototype.
 */
#define DECLARE_TRACE_NOARGS(name)					\
256
		__DECLARE_TRACE(name, void, , 1, void *__data, __data)
257
258

#define DECLARE_TRACE(name, proto, args)				\
259
		__DECLARE_TRACE(name, PARAMS(proto), PARAMS(args), 1,	\
260
261
262
				PARAMS(void *__data, proto),		\
				PARAMS(__data, args))

263
264
265
266
267
#define DECLARE_TRACE_CONDITION(name, proto, args, cond)		\
	__DECLARE_TRACE(name, PARAMS(proto), PARAMS(args), PARAMS(cond), \
			PARAMS(void *__data, proto),			\
			PARAMS(__data, args))

268
269
#define TRACE_EVENT_FLAGS(event, flag)

270
#endif /* DECLARE_TRACE */
271

272
#ifndef TRACE_EVENT
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
/*
 * For use with the TRACE_EVENT macro:
 *
 * We define a tracepoint, its arguments, its printk format
 * and its 'fast binay record' layout.
 *
 * Firstly, name your tracepoint via TRACE_EVENT(name : the
 * 'subsystem_event' notation is fine.
 *
 * Think about this whole construct as the
 * 'trace_sched_switch() function' from now on.
 *
 *
 *  TRACE_EVENT(sched_switch,
 *
 *	*
 *	* A function has a regular function arguments
 *	* prototype, declare it via TP_PROTO():
 *	*
 *
293
294
 *	TP_PROTO(struct rq *rq, struct task_struct *prev,
 *		 struct task_struct *next),
295
296
297
298
299
300
301
 *
 *	*
 *	* Define the call signature of the 'function'.
 *	* (Design sidenote: we use this instead of a
 *	*  TP_PROTO1/TP_PROTO2/TP_PROTO3 ugliness.)
 *	*
 *
302
 *	TP_ARGS(rq, prev, next),
303
304
305
306
307
308
309
310
311
 *
 *	*
 *	* Fast binary tracing: define the trace record via
 *	* TP_STRUCT__entry(). You can think about it like a
 *	* regular C structure local variable definition.
 *	*
 *	* This is how the trace record is structured and will
 *	* be saved into the ring buffer. These are the fields
 *	* that will be exposed to user-space in
312
 *	* /sys/kernel/debug/tracing/events/<*>/format.
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
 *	*
 *	* The declared 'local variable' is called '__entry'
 *	*
 *	* __field(pid_t, prev_prid) is equivalent to a standard declariton:
 *	*
 *	*	pid_t	prev_pid;
 *	*
 *	* __array(char, prev_comm, TASK_COMM_LEN) is equivalent to:
 *	*
 *	*	char	prev_comm[TASK_COMM_LEN];
 *	*
 *
 *	TP_STRUCT__entry(
 *		__array(	char,	prev_comm,	TASK_COMM_LEN	)
 *		__field(	pid_t,	prev_pid			)
 *		__field(	int,	prev_prio			)
 *		__array(	char,	next_comm,	TASK_COMM_LEN	)
 *		__field(	pid_t,	next_pid			)
 *		__field(	int,	next_prio			)
 *	),
 *
 *	*
 *	* Assign the entry into the trace record, by embedding
 *	* a full C statement block into TP_fast_assign(). You
 *	* can refer to the trace record as '__entry' -
 *	* otherwise you can put arbitrary C code in here.
 *	*
 *	* Note: this C code will execute every time a trace event
 *	* happens, on an active tracepoint.
 *	*
 *
344
345
346
347
 *	TP_fast_assign(
 *		memcpy(__entry->next_comm, next->comm, TASK_COMM_LEN);
 *		__entry->prev_pid	= prev->pid;
 *		__entry->prev_prio	= prev->prio;
348
349
 *		memcpy(__entry->prev_comm, prev->comm, TASK_COMM_LEN);
 *		__entry->next_pid	= next->pid;
350
 *		__entry->next_prio	= next->prio;
351
 *	),
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
 *
 *	*
 *	* Formatted output of a trace record via TP_printk().
 *	* This is how the tracepoint will appear under ftrace
 *	* plugins that make use of this tracepoint.
 *	*
 *	* (raw-binary tracing wont actually perform this step.)
 *	*
 *
 *	TP_printk("task %s:%d [%d] ==> %s:%d [%d]",
 *		__entry->prev_comm, __entry->prev_pid, __entry->prev_prio,
 *		__entry->next_comm, __entry->next_pid, __entry->next_prio),
 *
 * );
 *
 * This macro construct is thus used for the regular printk format
 * tracing setup, it is used to construct a function pointer based
 * tracepoint callback (this is used by programmatic plugins and
 * can also by used by generic instrumentation like SystemTap), and
 * it is also used to expose a structured trace record in
372
 * /sys/kernel/debug/tracing/events/.
373
374
375
 *
 * A set of (un)registration functions can be passed to the variant
 * TRACE_EVENT_FN to perform any (un)registration work.
376
377
 */

378
#define DECLARE_EVENT_CLASS(name, proto, args, tstruct, assign, print)
379
380
#define DEFINE_EVENT(template, name, proto, args)		\
	DECLARE_TRACE(name, PARAMS(proto), PARAMS(args))
381
382
#define DEFINE_EVENT_FN(template, name, proto, args, reg, unreg)\
	DECLARE_TRACE(name, PARAMS(proto), PARAMS(args))
383
384
#define DEFINE_EVENT_PRINT(template, name, proto, args, print)	\
	DECLARE_TRACE(name, PARAMS(proto), PARAMS(args))
385
386
387
388
#define DEFINE_EVENT_CONDITION(template, name, proto,		\
			       args, cond)			\
	DECLARE_TRACE_CONDITION(name, PARAMS(proto),		\
				PARAMS(args), PARAMS(cond))
389

390
#define TRACE_EVENT(name, proto, args, struct, assign, print)	\
391
	DECLARE_TRACE(name, PARAMS(proto), PARAMS(args))
392
393
394
#define TRACE_EVENT_FN(name, proto, args, struct,		\
		assign, print, reg, unreg)			\
	DECLARE_TRACE(name, PARAMS(proto), PARAMS(args))
395
396
397
398
#define TRACE_EVENT_CONDITION(name, proto, args, cond,		\
			      struct, assign, print)		\
	DECLARE_TRACE_CONDITION(name, PARAMS(proto),		\
				PARAMS(args), PARAMS(cond))
399

400
401
#define TRACE_EVENT_FLAGS(event, flag)

402
#endif /* ifdef TRACE_EVENT (see note above) */