lkml.org 
[lkml]   [2007]   [May]   [10]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    Date
    From
    SubjectRe: [patch 07/10] Linux Kernel Markers - Documentation
    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().
    -
    To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
    the body of a message to majordomo@vger.kernel.org
    More majordomo info at http://vger.kernel.org/majordomo-info.html
    Please read the FAQ at http://www.tux.org/lkml/

    \
     
     \ /
      Last update: 2007-05-10 17:55    [W:0.046 / U:122.084 seconds]
    ©2003-2016 Jasper Spaans. hosted at Digital OceanAdvertise on this site