blob: d9f50a19fa0c48185968e875aa2c9163bae3e6fa [file] [log] [blame]
Mathieu Desnoyers26e3d112007-10-18 23:41:08 -07001 Using the Linux Kernel Markers
2
3 Mathieu Desnoyers
4
5
6This document introduces Linux Kernel Markers and their use. It provides
7examples of how to insert markers in the kernel and connect probe functions to
8them and provides some examples of probe functions.
9
10
11* Purpose of markers
12
13A marker placed in code provides a hook to call a function (probe) that you can
14provide at runtime. A marker can be "on" (a probe is connected to it) or "off"
15(no probe is attached). When a marker is "off" it has no effect, except for
16adding a tiny time penalty (checking a condition for a branch) and space
17penalty (adding a few bytes for the function call at the end of the
18instrumented function and adds a data structure in a separate section). When a
19marker is "on", the function you provide is called each time the marker is
20executed, in the execution context of the caller. When the function provided
21ends its execution, it returns to the caller (continuing from the marker site).
22
23You can put markers at important locations in the code. Markers are
24lightweight hooks that can pass an arbitrary number of parameters,
25described in a printk-like format string, to the attached probe function.
26
27They can be used for tracing and performance accounting.
28
29
30* Usage
31
32In order to use the macro trace_mark, you should include linux/marker.h.
33
34#include <linux/marker.h>
35
36And,
37
Mathieu Desnoyers5f9468c2007-11-14 16:59:49 -080038trace_mark(subsystem_event, "myint %d mystring %s", someint, somestring);
Mathieu Desnoyers26e3d112007-10-18 23:41:08 -070039Where :
40- subsystem_event is an identifier unique to your event
41 - subsystem is the name of your subsystem.
42 - event is the name of the event to mark.
Mathieu Desnoyers5f9468c2007-11-14 16:59:49 -080043- "myint %d mystring %s" is the formatted string for the serializer. "myint" and
44 "mystring" are repectively the field names associated with the first and
45 second parameter.
Mathieu Desnoyers26e3d112007-10-18 23:41:08 -070046- someint is an integer.
47- somestring is a char pointer.
48
49Connecting a function (probe) to a marker is done by providing a probe (function
50to call) for the specific marker through marker_probe_register() and can be
51activated by calling marker_arm(). Marker deactivation can be done by calling
52marker_disarm() as many times as marker_arm() has been called. Removing a probe
53is done through marker_probe_unregister(); it will disarm the probe and make
54sure there is no caller left using the probe when it returns. Probe removal is
55preempt-safe because preemption is disabled around the probe call. See the
56"Probe example" section below for a sample probe module.
57
58The marker mechanism supports inserting multiple instances of the same marker.
59Markers can be put in inline functions, inlined static functions, and
60unrolled loops as well as regular functions.
61
62The naming scheme "subsystem_event" is suggested here as a convention intended
63to limit collisions. Marker names are global to the kernel: they are considered
64as being the same whether they are in the core kernel image or in modules.
65Conflicting format strings for markers with the same name will cause the markers
66to be detected to have a different format string not to be armed and will output
67a printk warning which identifies the inconsistency:
68
69"Format mismatch for probe probe_name (format), marker (format)"
70
71
72* Probe / marker example
73
74See the example provided in samples/markers/src
75
76Compile them with your kernel.
77
78Run, as root :
79modprobe marker-example (insmod order is not important)
80modprobe probe-example
81cat /proc/marker-example (returns an expected error)
82rmmod marker-example probe-example
83dmesg