Re: [PATCH] Linux Kernel Markers Documentation

Randy Dunlap
2007-02-16T01:51:27Z

On Thu, 15 Feb 2007 20:33:48 -0500 Mathieu Desnoyers wrote:

> Linux Kernel Markers - Documentation
>
> Here is some documentation explaining what is/how to use the Linux
> Kernel Markers.
>
> Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@polymtl.ca>
>
> --- /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
that

> +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.

so is the MARK() supposed to be:
MARK(subsystem, event, ...

Please make the 2 doc. lines above match the parameters...
or the parameters match the text.

> +- "%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.
refers.

> +
> +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 <mathieu.desnoyers@polymtl.ca>
> + *
> + * 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]"

Is SUBSYSTEM_EVENT_FORMAT used implicitly below? or elsewhere?

> +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);

Do FS_CLOSE_FORMAT and probe_fs_close() need to be defined here?
I.e., is this a complete example?

> + 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 -------------------------------------

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***