Linux Kernel Markers - Documentation Here is some documentation explaining what is/how to use the Linux Kernel Markers.
Signed-off-by: Mathieu Desnoyers <[EMAIL PROTECTED]> --- /dev/null +++ b/Documentation/marker.txt @@ -0,0 +1,130 @@ + Using the Linux Kernel Markers + + Mathieu Desnoyers + + + This document discusses the purpose of markers. It shows some usage +examples of the Linux Kernel Markers : how to insert markers within the kernel +and how to connect probes to a marker. Finally, it has some probe module +examples. This is what connects to a marker. + + +* Purpose of markers + +You can put markers at important locations in the code. They act as +lightweight hooks that can pass an arbitrary number of parameters, +described in a printk-like format string, to a function whenever the marker +code is reached. + +They can be used for tracing (LTTng, LKET over SystemTAP), overall performance +accounting (SystemTAP). They could also be used to implement +efficient hooks for SELinux or any other subsystem the would have this +kind of need. + +Using the markers for system audit (SELinux) would require to pass a +variable by address that would be later checked by the marked routine. + + +* Usage + +MARK(subsystem_event, "%d %s %p[struct task_struct]", + someint, somestring, current); +Where : +- Subsystem is the name of your subsystem. +- event is the name of the event to mark. +- "%d %s %p[struct task_struct]" is the formatted string for (printk-style). +- someint is an integer. +- somestring is a char pointer. +- current is a pointer to a struct task_struct. + +The expression %p[struct task_struct] is a suggested marker definition +standard that could eventually be used for pointer type checking in +sparse. The brackets contain the type to which the pointer refer. + +The marker mechanism supports multiple instances of the same marker. +Markers can be put in inline functions, inlined static functions and +unrolled loops. + +Note : It is safe to put markers within preempt-safe code : preempt_enable() +will not call the scheduler due to the tests in preempt_schedule(). + + +* Optimization for a given architecture + +You will find, in asm-*/marker.h, optimisations for given architectures +(currently i386 and powerpc). They use a load immediate instead of a data read, +which saves a data cache hit, but also requires cross CPU code modification. In +order to support embedded systems which use read-only memory for their code, the +optimization can be disabled through menu options. + + +* Probe example + +------------------------------ CUT ------------------------------------- +/* probe-example.c + * + * Loads a function at a marker call site. + * + * (C) Copyright 2007 Mathieu Desnoyers <[EMAIL PROTECTED]> + * + * This file is released under the GPLv2. + * See the file COPYING for more details. + */ + +#include <linux/sched.h> +#include <linux/kernel.h> + +#define SUBSYSTEM_EVENT_FORMAT "%d %s %p[struct task_struct]" +void probe_subsystem_event(const char *format, ...) +{ + va_list ap; + /* Declare args */ + unsigned int value; + const char *mystr; + struct task_struct *task; + + /* Assign args */ + va_start(ap, format); + value = va_arg(ap, typeof(value)); + mystr = va_arg(ap, typeof(mystr)); + task = va_arg(ap, typeof(task)); + + /* Call tracer */ + trace_subsystem_event(value, mystr, task); + + /* Or call printk */ + vprintk(format, ap); + + /* or count, check rights... */ + + va_end(ap); +} + +static int __init probe_init(void) +{ + int result; + result = marker_set_probe("subsystem_event", + FS_CLOSE_FORMAT, + probe_fs_close); + if (!result) + goto cleanup; + return 0; + +cleanup: + marker_remove_probe(probe_subsystem_event); + return -EPERM; +} + +static void __exit probe_fini(void) +{ + marker_remove_probe(probe_subsystem_event); +} + +module_init(probe_init); +module_exit(probe_fini); + +MODULE_LICENSE("GPL"); +MODULE_AUTHOR("Mathieu Desnoyers"); +MODULE_DESCRIPTION("SUBSYSTEM Probe"); +------------------------------ CUT ------------------------------------- + -- Mathieu Desnoyers Computer Engineering Ph.D. Candidate, Ecole Polytechnique de Montreal OpenPGP key fingerprint: 8CD5 52C3 8E3C 4140 715F BA06 3F25 A8FE 3BAE 9A68 - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/