Here is some documentation explaining what is/how to use the Linux
Kernel Markers.
Signed-off-by: Mathieu Desnoyers <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
---
Documentation/marker.txt | 266 +++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 266 insertions(+)
Index: linux-2.6-lttng/Documentation/marker.txt
===================================================================
--- /dev/null 1970-01-01 00:00:00.000000000 +0000
+++ linux-2.6-lttng/Documentation/marker.txt 2007-05-09 18:16:13.000000000 -0400
@@ -0,0 +1,266 @@
+ Using the Linux Kernel Markers
+
+ Mathieu Desnoyers
+
+
+ This document introduces to markers and discusses its purpose. 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
+
+A marker placed in your code provides a hook to a function (probe) that
+you can provide at runtime. A marker can be "on" (a probe is connected to it)
+or "off" (no probe is attached). An "off" marker has no effect. When turned on,
+the function you provide is called each time the marker is executed in the
+execution context of the caller. When the function provided ends its execution,
+it returns to the caller (marker site).
+
+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 that 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
+
+In order to use the macro MARK, you should include linux/marker.h.
+
+#include <linux/marker.h>
+
+Add, in your code :
+
+trace_mark(subsystem_event, "%d %s", someint, somestring);
+Where :
+- subsystem_event is an identifier unique to your event
+ - subsystem is the name of your subsystem.
+ - event is the name of the event to mark.
+- "%d %s" is the formatted string for the serializer.
+- someint is an integer.
+- somestring is a char pointer.
+
+Connecting a function (probe) to a marker is done by providing a probe
+(function to call) for the specific marker through marker_set_probe(). It will
+automatically connect the function and enable the marker site. Removing a probe
+is done through marker_remove_probe(). Probe removal is preempt safe because
+preemption is disabled around the probe call. See the "Probe example" section
+below for a sample probe module.
+
+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 load,
+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.
+
+The MF_* flags can be used to control the type of marker. See the
+include/marker.h header for the list of flags. They can be specified as the
+first parameter of the _trace_mark() macro, such as the following example which
+is safe with respect to lockdep.c (useful for marking lockdep.c and printk
+functions).
+
+_trace_mark(MF_DEFAULT | ~MF_LOCKDEP, subsystem_eventb, MARK_NOARGS);
+
+Another example is to specify that a specific marker must never call printk :
+_trace_mark(MF_DEFAULT | ~MF_PRINTK, subsystem_eventc,
+ "%d %s", someint, somestring,);
+
+Flag compatibility is checked before connecting the probe to the marker : the
+right flags must be given to _marker_set_enable().
+
+
+* Probe example
+
+You can build the kernel modules, probe-example.ko and marker-example.ko,
+using the following Makefile:
+------------------------------ CUT -------------------------------------
+obj-m := probe-example.o marker-example.o
+KDIR := /lib/modules/$(shell uname -r)/build
+PWD := $(shell pwd)
+default:
+ $(MAKE) -C $(KDIR) SUBDIRS=$(PWD) modules
+clean:
+ rm -f *.mod.c *.ko *.o
+------------------------------ CUT -------------------------------------
+/* probe-example.c
+ *
+ * Connects two functions to marker call sites.
+ *
+ * (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>
+#include <linux/module.h>
+#include <linux/marker.h>
+#include <asm/atomic.h>
+
+#define NUM_PROBES ARRAY_SIZE(probe_array)
+
+struct probe_data {
+ const char *name;
+ const char *format;
+ marker_probe_func *probe_func;
+};
+
+void probe_subsystem_event(const struct __mark_marker_c *mdata,
+ const char *format, ...)
+{
+ va_list ap;
+ /* Declare args */
+ unsigned int value;
+ const char *mystr;
+
+ /* Assign args */
+ va_start(ap, format);
+ value = va_arg(ap, typeof(value));
+ mystr = va_arg(ap, typeof(mystr));
+
+ /* Call printk */
+ printk("Value %u, string %s\n", value, mystr);
+
+ /* or count, check rights, serialize data in a buffer */
+
+ va_end(ap);
+}
+
+atomic_t eventb_count = ATOMIC_INIT(0);
+
+void probe_subsystem_eventb(const struct __mark_marker_c *mdata,
+ const char *format, ...)
+{
+ /* Increment counter */
+ atomic_inc(&eventb_count);
+}
+
+static struct probe_data probe_array[] =
+{
+ { .name = "subsystem_event",
+ .format = "%d %s",
+ .probe_func = probe_subsystem_event },
+ { .name = "subsystem_eventb",
+ .format = MARK_NOARGS,
+ .probe_func = probe_subsystem_eventb },
+};
+
+static int __init probe_init(void)
+{
+ int result;
+ uint8_t eID;
+
+ for (eID = 0; eID < NUM_PROBES; eID++) {
+ result = marker_set_probe(probe_array[eID].name,
+ probe_array[eID].format,
+ probe_array[eID].probe_func, &probe_array[eID]);
+ if (!result)
+ printk(KERN_INFO "Unable to register probe %s\n",
+ probe_array[eID].name);
+ }
+ return 0;
+}
+
+static void __exit probe_fini(void)
+{
+ uint8_t eID;
+
+ for (eID = 0; eID < NUM_PROBES; eID++) {
+ marker_remove_probe(probe_array[eID].name);
+ }
+ synchronize_sched(); /* Wait for probes to finish */
+ printk("Number of event b : %u\n", atomic_read(&eventb_count));
+}
+
+module_init(probe_init);
+module_exit(probe_fini);
+
+MODULE_LICENSE("GPL");
+MODULE_AUTHOR("Mathieu Desnoyers");
+MODULE_DESCRIPTION("SUBSYSTEM Probe");
+------------------------------ CUT -------------------------------------
+/* marker-example.c
+ *
+ * Executes a marker when /proc/marker-example is opened.
+ *
+ * (C) Copyright 2007 Mathieu Desnoyers <[email protected]>
+ *
+ * This file is released under the GPLv2.
+ * See the file COPYING for more details.
+ */
+
+#include <linux/module.h>
+#include <linux/marker.h>
+#include <linux/sched.h>
+#include <linux/proc_fs.h>
+
+struct proc_dir_entry *pentry_example = NULL;
+
+static int my_open(struct inode *inode, struct file *file)
+{
+ int i;
+
+ trace_mark(subsystem_event, "%d %s", 123, "example string");
+ for (i=0; i<10; i++) {
+ trace_mark(subsystem_eventb, MARK_NOARGS);
+ }
+ return -EPERM;
+}
+
+static struct file_operations mark_ops = {
+ .open = my_open,
+};
+
+static int example_init(void)
+{
+ printk(KERN_ALERT "example init\n");
+ pentry_example = create_proc_entry("marker-example", 0444, NULL);
+ if (pentry_example)
+ pentry_example->proc_fops = &mark_ops;
+ else
+ return -EPERM;
+ return 0;
+}
+
+static void example_exit(void)
+{
+ printk(KERN_ALERT "example exit\n");
+ remove_proc_entry("marker-example", NULL);
+}
+
+module_init(example_init)
+module_exit(example_exit)
+
+MODULE_LICENSE("GPL");
+MODULE_AUTHOR("Mathieu Desnoyers");
+MODULE_DESCRIPTION("Linux Trace Toolkit example");
+------------------------------ CUT -------------------------------------
+Sequence of operations : (as root)
+make
+insmod marker-example.ko
+insmod probe-example.ko
+ (it is important to load the probe after the marked code)
+cat /proc/marker-example (returns an expected error)
+rmmod marker-example probe-example
+dmesg
+------------------------------ CUT -------------------------------------
--
Mathieu Desnoyers
Computer Engineering Ph.D. Student, Ecole Polytechnique de Montreal
OpenPGP key fingerprint: 8CD5 52C3 8E3C 4140 715F BA06 3F25 A8FE 3BAE 9A68
On Wed, May 09, 2007 at 09:56:02PM -0400, Mathieu Desnoyers wrote:
> Here is some documentation explaining what is/how to use the Linux
> Kernel Markers.
Please remove all references to out of tree code from the kernel documentation.
On Thu, 10 May 2007 07:58:47 +0100
Christoph Hellwig <[email protected]> wrote:
> On Wed, May 09, 2007 at 09:56:02PM -0400, Mathieu Desnoyers wrote:
> > Here is some documentation explaining what is/how to use the Linux
> > Kernel Markers.
>
> Please remove all references to out of tree code from the kernel documentation.
Christoph stop being ridiculous. Its one thing to object to kernel
markers and some of the rather nice tools they give you for
borderline technical reasons, but at the point you start saying "remove
references to" you are just trying to censor stuff you don't personally
approve of and you sound as stupid as RMS in his "don't link to non GPL
material" mode.
The kernel documentation is *FULL* of references to out of tree code and
documents precisely because the kernel does not exist in isolation.
Alan
On Thu, May 10, 2007 at 12:41:20PM +0100, Alan Cox wrote:
> On Thu, 10 May 2007 07:58:47 +0100
> Christoph Hellwig <[email protected]> wrote:
>
> > On Wed, May 09, 2007 at 09:56:02PM -0400, Mathieu Desnoyers wrote:
> > > Here is some documentation explaining what is/how to use the Linux
> > > Kernel Markers.
> >
> > Please remove all references to out of tree code from the kernel documentation.
>
> Christoph stop being ridiculous. Its one thing to object to kernel
> markers
I do not object kernel markers, and I have no idea where you got
that crap from. Quite contrary I've worked with Matthew on
getting both markers and lttng good enough that we can merge
it eventually.
Documentation of kernel facilities should not mention big outside
blobs of crap nerverless, which is something totally different from
not mentionining userspace code contrary to your ill-advised position.
> +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 that 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.
I don't think you should mention abuses like the selinux one, nor odd
projects that aren't merged. Just make this a generic:
"The can be used for tracing or performance accounting"
> +* Usage
> +
> +In order to use the macro MARK, you should include linux/marker.h.
It's trace_mark now.
> +* 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 load,
> +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.
I'm not sure this belong in here. As we already have good example it's
probably not needed at all.
> +#include <linux/sched.h>
> +#include <linux/kernel.h>
> +#include <linux/module.h>
> +#include <linux/marker.h>
> +#include <asm/atomic.h>
> +
> +#define NUM_PROBES ARRAY_SIZE(probe_array)
no need for this macro.
> +static int __init probe_init(void)
> +{
> + int result;
> + uint8_t eID;
please call the loop variable i and use int for it.
> Documentation of kernel facilities should not mention big outside
> blobs of crap nerverless, which is something totally different from
Christoph , you are sounding even more arrogant than RMS now, which is
quite an achievement, although one you shouldn't be proud of.
"blobs of crap" - in whose opinion. Yours. So you don't want the kernel
to mention things you personally don't approve of. Thats straight forward
censorship and has no place in free software.
If you want to control everything people say and think you might want to
apply from a job at the EU commission instead.
Alan
On 5/10/07, Alan Cox <[email protected]> wrote:
> "blobs of crap" - in whose opinion. Yours. So you don't want the kernel
> to mention things you personally don't approve of. Thats straight forward
> censorship and has no place in free software.
Out of kernel code comes and goes, so why mention it in-tree? Besides,
what's wrong with the suggested "can be used for tracing or
performance accounting?"
On Thu, 10 May 2007 15:52:26 +0300
"Pekka Enberg" <[email protected]> wrote:
> On 5/10/07, Alan Cox <[email protected]> wrote:
> > "blobs of crap" - in whose opinion. Yours. So you don't want the kernel
> > to mention things you personally don't approve of. Thats straight forward
> > censorship and has no place in free software.
>
> Out of kernel code comes and goes, so why mention it in-tree? Besides,
> what's wrong with the suggested "can be used for tracing or
> performance accounting?"
Because people want to know what it is really for ? It's quite amazing
really at the same time as people are posting crypto keys everywhere in
defiance of USSA law, we've got free software people trying to remove
references to a piece of out of tree software, and one that is free
software.
And as I keep saying the tree is full of references to out of tree stuff.
The documentation directory alone currently contains over a thousand http
URLS as of 2.6.21-rc6-mm1.
Alan
On Thu, 10 May 2007, Alan Cox wrote:
> Because people want to know what it is really for ? It's quite amazing
> really at the same time as people are posting crypto keys everywhere in
> defiance of USSA law, we've got free software people trying to remove
> references to a piece of out of tree software, and one that is free
> software.
Oh, I am not advocating censorship. I was merely pointing out that it
seems silly to mention out-of-tree users because they come and go. Who
knows whether LTTng or SystemTAP will be relevant five years from now?
Besides, are we sure the document includes all potential users now? We
wouldn't want to show favorism to any particular projects, now would we?
On Thu, 10 May 2007, Alan Cox wrote:
> And as I keep saying the tree is full of references to out of tree stuff.
> The documentation directory alone currently contains over a thousand http
> URLS as of 2.6.21-rc6-mm1.
Many of the already out of date or expiring in the near future... But
whatever, I don't care too much. Just wanted to say the review comment
makes sense to me.
Pekka
O> Oh, I am not advocating censorship. I was merely pointing out that it
> seems silly to mention out-of-tree users because they come and go. Who
> knows whether LTTng or SystemTAP will be relevant five years from now?
And in the intervening five years (or more likely 7 or more for
systemtap) the documentation will be very useful.
> Besides, are we sure the document includes all potential users now? We
> wouldn't want to show favorism to any particular projects, now would we?
Absolutely not - and isn't it more useful to let users know about all of
the tools that this enables ?
>
> On Thu, 10 May 2007, Alan Cox wrote:
> > And as I keep saying the tree is full of references to out of tree stuff.
> > The documentation directory alone currently contains over a thousand http
> > URLS as of 2.6.21-rc6-mm1.
>
> Many of the already out of date or expiring in the near future...
Have you done a statistically valid sampling or is this guessing ?
Alan
On Thu, 10 May 2007, Alan Cox wrote:
> > Besides, are we sure the document includes all potential users now? We
> > wouldn't want to show favorism to any particular projects, now would we?
>
> Absolutely not - and isn't it more useful to let users know about all of
> the tools that this enables ?
So set up a http//http://www.linux-markers.org/ and add the list there. We're not
going to start accepting patches that add "potentially useful new tools"
to Documentation/marker.txt are we?
On Thu, 10 May 2007, Alan Cox wrote:
> > Many of the already out of date or expiring in the near future...
>
> Have you done a statistically valid sampling or is this guessing ?
It's an educated guess which proves nothing but gets the point across
quite nicely ;-)
* Christoph Hellwig ([email protected]) wrote:
> On Wed, May 09, 2007 at 09:56:02PM -0400, Mathieu Desnoyers wrote:
> > Here is some documentation explaining what is/how to use the Linux
> > Kernel Markers.
>
> Please remove all references to out of tree code from the kernel documentation.
>
Since I expect people who will read this documentation to be familiar
with kprobes already, I tried to make the adaptation process as easy as
possible for them. You will find similar examples in
Documentation/kprobes.txt.
Also, this kind of example, which describes what kernel code is needed
to use the markers (this can be either a separate kernel module or
embedded in the kernel, like the blktrace example), seems to be a
straightforward way to teach people how to use the markers.
Mathieu
--
Mathieu Desnoyers
Computer Engineering Ph.D. Student, Ecole Polytechnique de Montreal
OpenPGP key fingerprint: 8CD5 52C3 8E3C 4140 715F BA06 3F25 A8FE 3BAE 9A68
* Christoph Hellwig ([email protected]) wrote:
> On Wed, May 09, 2007 at 09:56:02PM -0400, Mathieu Desnoyers wrote:
> > Here is some documentation explaining what is/how to use the Linux
> > Kernel Markers.
>
> Please remove all references to out of tree code from the kernel documentation.
>
Hrm, I see.. you are objecting to mentioning of "LTTng, LKET, SystemTAP"...
I agree : it belongs to a changelog (which is bounded in time) rather
than to the documentation itself.
--
Mathieu Desnoyers
Computer Engineering Ph.D. Student, Ecole Polytechnique de Montreal
OpenPGP key fingerprint: 8CD5 52C3 8E3C 4140 715F BA06 3F25 A8FE 3BAE 9A68
Hi,
Here is a patch to marker.txt to make the English read a little
better. I didn't change the references to out-of-tree packages.
@@ -3,33 +3,30 @@
Mathieu Desnoyers
- This document introduces to markers and discusses its purpose. 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.
-
+This document introduces Linux Kernel Markers and their use. It provides
+examples of how to insert markers in the kernel and connect probe functions to
+them and provides some examples of probe functions.
* Purpose of markers
-A marker placed in your code provides a hook to a function (probe) that
+A marker placed in your code provides a hook to call a function (probe) that
you can provide at runtime. A marker can be "on" (a probe is connected to it)
-or "off" (no probe is attached). An "off" marker has no effect. When turned on,
-the function you provide is called each time the marker is executed in the
-execution context of the caller. When the function provided ends its execution,
-it returns to the caller (marker site).
+or "off" (no probe is attached). When a marker is "off" it has no
+effect. When a marker is "on", the function you provide is called each
+time the marker is executed, in the execution context of the
+caller. When the function provided ends its execution, it returns to the
+caller (continuing from the marker site).
-You can put markers at important locations in the code. They act as
+You can put markers at important locations in the code. Markers are
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.
+described in a printk-like format string, to the attached probe function.
-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 that would have this
-kind of need.
+Markers can be used for tracing (LTTng, LKET over SystemTAP), overall
+performance accounting (SystemTAP), or to hook to monitoring
+subsystems (like SELinux) that need to observe kernel behavior.
-Using the markers for system audit (SELinux) would require to pass a
-variable by address that would be later checked by the marked routine.
+Using the markers for system audit (SELinux) would require passing a
+variable by address so that it could be checked by the marked routine.
* Usage
@@ -52,15 +49,15 @@ Where :
Connecting a function (probe) to a marker is done by providing a probe
(function to call) for the specific marker through marker_set_probe(). It will
automatically connect the function and enable the marker site. Removing a probe
-is done through marker_remove_probe(). Probe removal is preempt safe because
+is done through marker_remove_probe(). Probe removal is preempt-safe because
preemption is disabled around the probe call. See the "Probe example" section
below for a sample probe module.
-The marker mechanism supports multiple instances of the same marker.
-Markers can be put in inline functions, inlined static functions and
+The marker mechanism supports inserting 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()
+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().
@@ -68,23 +65,23 @@ will not call the scheduler due to the t
You will find, in asm-*/marker.h, optimisations for given architectures
(currently i386 and powerpc). They use a load immediate instead of a data load,
-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
+which saves a data cache hit, but also requires cross-CPU code modification. In
+order to support embedded systems that use read-only memory for their code, the
optimization can be disabled through menu options.
The MF_* flags can be used to control the type of marker. See the
include/marker.h header for the list of flags. They can be specified as the
-first parameter of the _trace_mark() macro, such as the following example which
+first parameter of the _trace_mark() macro, as in the following example, which
is safe with respect to lockdep.c (useful for marking lockdep.c and printk
functions).
_trace_mark(MF_DEFAULT | ~MF_LOCKDEP, subsystem_eventb, MARK_NOARGS);
-Another example is to specify that a specific marker must never call printk :
+Another example is to specify that a specific marker must never call printk:
_trace_mark(MF_DEFAULT | ~MF_PRINTK, subsystem_eventc,
"%d %s", someint, somestring,);
-Flag compatibility is checked before connecting the probe to the marker : the
+Flag compatibility is checked before connecting the probe to the marker: the
right flags must be given to _marker_set_enable().
On Thu, 10 May 2007 07:58:47 BST, Christoph Hellwig said:
> On Wed, May 09, 2007 at 09:56:02PM -0400, Mathieu Desnoyers wrote:
> > Here is some documentation explaining what is/how to use the Linux
> > Kernel Markers.
>
> Please remove all references to out of tree code from the kernel documentation.
[/usr/src/linux-2.6.21-mm2/Documentation] find . | xargs grep /sbin | wc -l
202
-ENOPATCH?
(The usefulness of a kernel documentation tree that doesn't mention hotplug,
udev, modprobe, and initrd, all of which are out-of-tree, is more than slightly
questionable...)