lkml.org 
[lkml]   [2007]   [Jul]   [14]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    Date
    From
    Subject[PATCH] Linux Kernel Markers - Architecture Independent Code - kerneldoc
    Linux Kernel Markers - Architecture Independent Code - kerneldoc

    Add kerneldoc to Linux Kernel Markers API.

    Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@polymtl.ca>
    CC: hch@infradead.org
    ---
    include/linux/marker.h | 108 ++++++++++++++++++++++++++++++++++++++++++++-----
    1 file changed, 99 insertions(+), 9 deletions(-)

    Index: linux-2.6-lttng/include/linux/marker.h
    ===================================================================
    --- linux-2.6-lttng.orig/include/linux/marker.h 2007-07-14 20:58:16.000000000 -0400
    +++ linux-2.6-lttng/include/linux/marker.h 2007-07-14 21:16:01.000000000 -0400
    @@ -20,6 +20,15 @@
    struct module;
    struct __mark_marker;

    +/**
    + * marker_probe_func - Type of a marker probe function
    + * @mdata: pointer of type struct __mark_marker
    + * @fmt: format string
    + * @...: variable argument list
    + *
    + * Type of marker probe functions. They receive the mdata and need to parse the
    + * format string to recover the variable argument list.
    + */
    typedef void marker_probe_func(const struct __mark_marker *mdata,
    const char *fmt, ...);

    @@ -88,18 +97,36 @@ extern void module_marker_update(struct
    static inline void module_marker_update(struct module *mod) { }
    #endif /* CONFIG_MARKERS */

    -/* Marker with default behavior */
    +/**
    + * trace_mark - Marker using code patching
    + * @name: marker name, not quoted.
    + * @format: format string
    + * @args...: variable argument list
    + *
    + * Places a marker using optimized code patching technique (immediate_if ())
    + * to be enabled.
    + */
    #define trace_mark(name, format, args...) \
    __trace_mark(0, name, format, ## args)
    -/*
    - * Map to the generic marker. Should be used for markers in __init and __exit
    - * functions and in lockdep code.
    +
    +/**
    + * _trace_mark - Marker using variable read
    + * @name: marker name, not quoted.
    + * @format: format string
    + * @args...: variable argument list
    + *
    + * Places a marker using a standard memory read (_immediate_if ()) to be
    + * enabled. Should be used for markers in __init and __exit functions and in
    + * lockdep code.
    */
    #define _trace_mark(name, format, args...) \
    __trace_mark(1, name, format, ## args)

    #define MARK_MAX_FORMAT_LEN 1024
    -/* Pass this as a format string for a marker with no argument */
    +
    +/**
    + * MARK_NOARGS - Format string for a marker with no argument.
    + */
    #define MARK_NOARGS " "

    /* To be used for string format validity checking with gcc */
    @@ -109,27 +136,90 @@ static inline void __mark_check_format(c

    extern marker_probe_func __mark_empty_function;

    -/*
    - * Connect a probe to a markers.
    +/**
    + * marker_probe_register - Connect a probe to a marker
    + * @name: marker name
    + * @format: format string
    + * @probe: probe handler
    + * @pdata: probe private data
    + *
    * pdata must be a valid allocated memory address, or NULL.
    + * Returns 0 if ok, error value on error.
    */
    extern int marker_probe_register(const char *name, const char *format,
    marker_probe_func *probe, void *pdata);

    -/*
    +/**
    + * marker_probe_unregister - Disconnect a probe from a marker
    + * @name: marker name
    + *
    * Returns the pdata given to marker_probe_register.
    */
    extern void *marker_probe_unregister(const char *name);
    -/*
    +
    +/**
    + * marker_probe_unregister - Disconnect a probe from a marker
    + * @pdata: probe private data
    + *
    * Unregister a marker by providing the registered pdata.
    + * Returns the pdata given to marker_probe_register.
    */
    extern void *marker_probe_unregister_pdata(void *pdata);

    +/**
    + * marker_arm - Arm a marker
    + * @name: marker name
    + *
    + * Activate a marker. It keeps a reference count of the number of
    + * arming/disarming done.
    + * Returns 0 if ok, error value on error.
    + */
    extern int marker_arm(const char *name);
    +
    +/**
    + * marker_disarm - Disarm a marker
    + * @name: marker name
    + *
    + * Disarm a marker. It keeps a reference count of the number of arming/disarming
    + * done.
    + * Returns 0 if ok, error value on error.
    + */
    extern int marker_disarm(const char *name);
    +
    +/**
    + * marker_get_first - Get first marker to start iteration
    + *
    + * Get the first marker found in the kernel. It should have a matching
    + * marker_release.
    + */
    extern struct __mark_marker *marker_get_first(void);
    +
    +/**
    + * marker_get_next - Get next marker of an iteration
    + * @iter: previous marker
    + *
    + * Get the next marker found in the kernel. It should get its previous marker
    + * from either marker_get_first() or marker_get_next().
    + */
    extern struct __mark_marker *marker_get_next(struct __mark_marker *iter);
    +
    +/**
    + * marker_release - Release the marker iterator
    + * @iter: previous marker
    + *
    + * Release the ressources held to insure iterator validity.
    + */
    extern void marker_release(struct __mark_marker *iter);
    +
    +/**
    + * marker_get_pdata - Get a marker's probe private data
    + * @name: marker name
    + *
    + * Returns the pdata pointer, or an ERR_PTR.
    + * The pdata pointer should _only_ be dereferenced if the caller is the owner of
    + * the data, or its content could vanish. This is mostly used to confirm that a
    + * caller is the owner of a registered probe.
    + */
    extern void *marker_get_pdata(const char *name);

    #endif /* __KERNEL__ */
    --
    Mathieu Desnoyers
    Computer Engineering Ph.D. Student, 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 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-07-15 03:43    [W:3.874 / U:0.092 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site