Documentation/markers.txt

   1                      Using the Linux Kernel Markers
   2
   3                             Mathieu Desnoyers
   4
   5
   6 This document introduces Linux Kernel Markers and their use. It provides
   7 examples of how to insert markers in the kernel and connect probe functions to
   8 them and provides some examples of probe functions.
   9
  10
  11 * Purpose of markers
  12
  13 A marker placed in code provides a hook to call a function (probe) that you can
  14 provide 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
  16 adding a tiny time penalty (checking a condition for a branch) and space
  17 penalty (adding a few bytes for the function call at the end of the
  18 instrumented function and adds a data structure in a separate section).  When a
  19 marker is "on", the function you provide is called each time the marker is
  20 executed, in the execution context of the caller. When the function provided
  21 ends its execution, it returns to the caller (continuing from the marker site).
  22
  23 You can put markers at important locations in the code. Markers are
  24 lightweight hooks that can pass an arbitrary number of parameters,
  25 described in a printk-like format string, to the attached probe function.
  26
  27 They can be used for tracing and performance accounting.
  28
  29
  30 * Usage
  31
  32 In order to use the macro trace_mark, you should include linux/marker.h.
  33
  34 #include <linux/marker.h>
  35
  36 And,
  37
  38 trace_mark(subsystem_event, "myint %d mystring %s", someint, somestring);
  39 Where :
  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
  49 Connecting a function (probe) to a marker is done by providing a probe (function
  50 to call) for the specific marker through marker_probe_register() and can be
  51 activated by calling marker_arm(). Marker deactivation can be done by calling
  52 marker_disarm() as many times as marker_arm() has been called. Removing a probe
  53 is done through marker_probe_unregister(); it will disarm the probe.
  54 marker_synchronize_unregister() must be called before the end of the module exit
  55 function to make sure there is no caller left using the probe. This, and the
  56 fact that preemption is disabled around the probe call, make sure that probe
  57 removal and module unload are safe. See the "Probe example" section below for a
  58 sample probe module.
  59
  60 The marker mechanism supports inserting multiple instances of the same marker.
  61 Markers can be put in inline functions, inlined static functions, and
  62 unrolled loops as well as regular functions.
  63
  64 The naming scheme "subsystem_event" is suggested here as a convention intended
  65 to limit collisions. Marker names are global to the kernel: they are considered
  66 as being the same whether they are in the core kernel image or in modules.
  67 Conflicting format strings for markers with the same name will cause the markers
  68 to be detected to have a different format string not to be armed and will output
  69 a printk warning which identifies the inconsistency:
  70
  71 "Format mismatch for probe probe_name (format), marker (format)"
  72
  73 Another way to use markers is to simply define the marker without generating any
  74 function call to actually call into the marker. This is useful in combination
  75 with tracepoint probes in a scheme like this :
  76
  77 void probe_tracepoint_name(unsigned int arg1, struct task_struct *tsk);
  78
  79 DEFINE_MARKER_TP(marker_eventname, tracepoint_name, probe_tracepoint_name,
  80         "arg1 %u pid %d");
  81
  82 notrace void probe_tracepoint_name(unsigned int arg1, struct task_struct *tsk)
  83 {
  84         struct marker *marker = &GET_MARKER(kernel_irq_entry);
  85         /* write data to trace buffers ... */
  86 }
  87
  88 * Probe / marker example
  89
  90 See the example provided in samples/markers/src
  91
  92 Compile them with your kernel.
  93
  94 Run, as root :
  95 modprobe marker-example (insmod order is not important)
  96 modprobe probe-example
  97 cat /proc/marker-example (returns an expected error)
  98 rmmod marker-example probe-example
  99 dmesg