1 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 38trace_mark(subsystem_event, "myint %d mystring %s", someint, somestring); 39Where : 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. 43- "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. 46- 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. 54 55marker_synchronize_unregister() must be called between probe unregistration and 56the first occurrence of 57- the end of module exit function, 58 to make sure there is no caller left using the probe; 59- the free of any resource used by the probes, 60 to make sure the probes wont be accessing invalid data. 61This, and the fact that preemption is disabled around the probe call, make sure 62that probe removal and module unload are safe. See the "Probe example" section 63below for a sample probe module. 64 65The marker mechanism supports inserting multiple instances of the same marker. 66Markers can be put in inline functions, inlined static functions, and 67unrolled loops as well as regular functions. 68 69The naming scheme "subsystem_event" is suggested here as a convention intended 70to limit collisions. Marker names are global to the kernel: they are considered 71as being the same whether they are in the core kernel image or in modules. 72Conflicting format strings for markers with the same name will cause the markers 73to be detected to have a different format string not to be armed and will output 74a printk warning which identifies the inconsistency: 75 76"Format mismatch for probe probe_name (format), marker (format)" 77 78Another way to use markers is to simply define the marker without generating any 79function call to actually call into the marker. This is useful in combination 80with tracepoint probes in a scheme like this : 81 82void probe_tracepoint_name(unsigned int arg1, struct task_struct *tsk); 83 84DEFINE_MARKER_TP(marker_eventname, tracepoint_name, probe_tracepoint_name, 85 "arg1 %u pid %d"); 86 87notrace void probe_tracepoint_name(unsigned int arg1, struct task_struct *tsk) 88{ 89 struct marker *marker = &GET_MARKER(kernel_irq_entry); 90 /* write data to trace buffers ... */ 91} 92 93* Probe / marker example 94 95See the example provided in samples/markers/src 96 97Compile them with your kernel. 98 99Run, as root : 100modprobe marker-example (insmod order is not important) 101modprobe probe-example 102cat /proc/marker-example (returns an expected error) 103rmmod marker-example probe-example 104dmesg 105