Here is some documentation explaining what is/how to use the Linux

Kernel Markers.
Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@polymtl.ca>

Acked-by: "Frank Ch. Eigler" <fche@redhat.com>

CC: Christoph Hellwig <hch@infradead.org>

---
 Documentation/markers/markers.txt          |   81 +++++++++++++++++++++++

 Documentation/markers/src/Makefile         |    7 ++

 Documentation/markers/src/marker-example.c |   55 ++++++++++++++++

 Documentation/markers/src/probe-example.c  |   98 +++++++++++++++++++++++++++++

 4 files changed, 241 insertions(+)
Index: linux-2.6-lttng/Documentation/markers/markers.txt

===================================================================

--- /dev/null	1970-01-01 00:00:00.000000000 +0000

+++ linux-2.6-lttng/Documentation/markers/markers.txt	2007-09-21 15:07:42.000000000 -0400

@@ -0,0 +1,81 @@

+ 	             Using the Linux Kernel Markers

+

+			    Mathieu Desnoyers

+

+

+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 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). When a marker is "off" it has no effect, except for

+adding a tiny time penalty (checking a condition for a branch) and space

+penalty (adding a few bytes for the function call at the end of the

+instrumented function and adds a data structure in a separate section).  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. Markers are

+lightweight hooks that can pass an arbitrary number of parameters,...
[ message continues ]

As mentioned in the tracing infrastructure thread I don't think

putting code into Documentation is a good idea.  Either of you really

should start a sample/ toplevel directory for this kind of stuff

including a Kconfig menu etc to be able to build these samples as

part of an allmodconfig.
-

looking at Documentation/lguest/
 Oh wait, nothing to see here. Move along please.
 ;-)
 -- Steve
-

lguest is an even bigger nightmare.  It's userspace code, but we can't

move it because it pokes into non-exported headers.
-

One should have a look at Documentation/kprobes.txt for that kind of

example code / documentation mix.
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

-

That one is particularly bad.  It's high on my todo list of things to fix.

-

I already have it split and building.   Just need to know

where to put it.  :)
---

~Randy

Phaedrus says that Quality is about caring.

-

I don't have a problem with a samples/ directory except (as I have

already pointed out) it means that people will end up having to look

in 2 places for the information that they need, i.e., both in

samples/ and in Documentation/.  So I really don't see a big need

to split the samples and docs.
What's wrong with building sample code in the Documentation/ directory?
---

~Randy

Phaedrus says that Quality is about caring.

-

It's not really documentation, it's code :)  If you want to build

documentation from the samples use kerneldoc or similar to extrace the

comments.  Having Documentation/ purely for things not affecting the build

make things a whole lot clearer, but if you absolutely insist on it

we can put it under Documentation/ as long as it's fully integrated into

kbuild and will be built as part of allmodconfig, unlike the current

two patches showing code there.

-

Yes, it has to be integrated into the build system, no doubt.
We really need to give Mathieu and David Wilder an answer so that they

can make progress (and I'm willing to help with this).
To do this, here's my test question:

How much of David's "trace code and documentation" patch can be put

into a samples/ directory?
 Documentation/trace/src/Makefile     |    7 +

 Documentation/trace/src/README       |   18 +

 Documentation/trace/src/fork_trace.c |  119 +++++++

 Documentation/trace/trace.txt        |  164 ++++++++++

 include/linux/trace.h                |   99 ++++++

 lib/Kconfig                          |    9 +

 lib/Makefile                         |    2 +

 lib/trace.c                          |  563 +++++++++++++++++++++++++++

+++++++

 8 files changed, 981 insertions(+), 0 deletions(-)
All of the trace/src/ subdirectory?
---

~Randy

Phaedrus says that Quality is about caring.

-

Yes, but only as a single file.  We don't really want READMES in source

directories.  Instead these 18 lines would do a perfect comment on the

top of the file.

-

That might be OK for this case, but sometimes it makes sense to have

README etc. about how to use the software.  So you would want this

in the Documentation/ tree?  That makes it harder on users.
--

~Randy

Phaedrus says that Quality is about caring.

-

If it's so complex that we can't describe it in a few dozens lines

it shouldn't be anywhere but the place it belongs and better have a

real use and not just be a sample.  And in the trace case I must

admit that I'd prefer a real use like some simple syscall-trace

over this hack anyway..
-

I think that samples are perfectly fine for documentation and

that the trace example is a good example.  I think that most people

who need something like that would need to customize it for their

specific needs anyway.
We don't seem to be making progress...
--

~Randy

Phaedrus says that Quality is about caring.

-

Time to bring in a Tie-Breaker :)
-

Yes.  Is anyone else interested?   :(
--

~Randy

Phaedrus says that Quality is about caring.

-

I guess that's everyone (except those who are sleeping).
Let's not hold up progress.  Just use samples/ for code.
---

~Randy

Phaedrus says that Quality is about caring.

-

Would you already have the 
Makefile

samples/Kconfig

samples/Makefile
core code handy per chance ? (and probably Kconfig sourcing in every

arch ?)
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

-

Yes.  Here it is.  I'm working on add kprobes to it, but you

can go ahead with markers also.
From: Randy Dunlap <randy.dunlap@oracle.com>
Begin infrastructure for kernel code samples in the samples/ directory.

Add its Kconfig and Kbuild files.

Source its Kconfig file in all arch/ Kconfigs.
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>

---

 Makefile               |   10 +++++++---

 arch/alpha/Kconfig     |    2 ++

 arch/arm/Kconfig       |    2 ++

 arch/avr32/Kconfig     |    2 ++

 arch/blackfin/Kconfig  |    2 ++

 arch/cris/Kconfig      |    2 ++

 arch/frv/Kconfig       |    2 ++

 arch/h8300/Kconfig     |    2 ++

 arch/i386/Kconfig      |    2 ++

 arch/ia64/Kconfig      |    2 ++

 arch/m32r/Kconfig      |    2 ++

 arch/m68k/Kconfig      |    2 ++

 arch/m68knommu/Kconfig |    2 ++

 arch/mips/Kconfig      |    2 ++

 arch/parisc/Kconfig    |    2 ++

 arch/powerpc/Kconfig   |    2 ++

 arch/ppc/Kconfig       |    2 ++

 arch/s390/Kconfig      |    2 ++

 arch/sh/Kconfig        |    2 ++

 arch/sh64/Kconfig      |    2 ++

 arch/sparc/Kconfig     |    2 ++

 arch/sparc64/Kconfig   |    2 ++

 arch/um/Kconfig        |    2 ++

 arch/v850/Kconfig      |    2 ++

 arch/x86_64/Kconfig    |    2 ++

 arch/xtensa/Kconfig    |    3 ++-

 samples/Kbuild         |    2 ++

 samples/Kconfig        |   11 +++++++++++

 28 files changed, 70 insertions(+), 4 deletions(-)
--- linux-2.6.23-rc7.orig/Makefile

+++ linux-2.6.23-rc7/Makefile

@@ -436,6 +436,7 @@ drivers-y	:= drivers/ sound/

 net-y		:= net/

 libs-y		:= lib/

 core-y		:= usr/

+samples-y	:= samples/

 endif # KBUILD_EXTMOD
 ifeq ($(dot-config),1)

@@ -564,10 +565,12 @@ core-y		+= kernel/ mm/ fs/ ipc/ security
 vmlinux-dirs	:= $(patsubst %/,%,$(filter %/, $(init-y) $(init-m) \

 		     $(core-y) $(core-m) $(drivers-y) $(drivers-m) \

-		     $(net-y) $(net-m) $(libs-y) $(libs-m)))

+		     $(net-y) $(net-m) $(libs-y) $(libs-m))	\

+		     $(samples-y) $(samples-m))

+
 vmlinux-alldirs	:= $(sort $(vml...
[ message continues ]

Hi Randy,
I got everything working and I'm thinking about posting all this stuff

soon. Do you think your patch (having renamed Kbuild to Makefile) is

ready to post ?
--

Mathieu Desnoyers

Computer Engineering Ph.D. Student, Ecole Polytechnique de Montreal

OpenPGP key fingerprint: 8CD5 52C3 8E3C 4140 715F  BA06 3F25 A8FE 3BAE 9A68

-

Yes, AFAIK it is.  Do you want me to resend it or do you want to

make it patch M/N in your patches?
--

~Randy

Phaedrus says that Quality is about caring.

-

I'll include it with my patches. Thanks!
--

Mathieu Desnoyers

Computer Engineering Ph.D. Student, Ecole Polytechnique de Montreal

OpenPGP key fingerprint: 8CD5 52C3 8E3C 4140 715F  BA06 3F25 A8FE 3BAE 9A68

-