LKML Archive on lore.kernel.org
help / color / mirror / Atom feed
From: Mathieu Desnoyers <compudj@krystal.dyndns.org>
To: akpm@linux-foundation.org, linux-kernel@vger.kernel.org
Cc: Christoph Hellwig <hch@infradead.org>
Subject: [PATCH] Linux Kernel Markers -  Architecture Independent Code - kerneldoc
Date: Sat, 14 Jul 2007 21:40:56 -0400	[thread overview]
Message-ID: <20070715014056.GI23209@Krystal> (raw)
In-Reply-To: <20070715013431.GE23209@Krystal>

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

  reply	other threads:[~2007-07-15  1:41 UTC|newest]

Thread overview: 12+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2007-07-14  1:29 [patch 0/4] Linux Kernel Markers Mathieu Desnoyers
2007-07-14  1:29 ` [patch 1/4] Linux Kernel Markers, architecture independent code Mathieu Desnoyers
2007-07-15  1:34   ` [PATCH] Linux Kernel Markers - Architecture Independent Code Deferred Sync Mathieu Desnoyers
2007-07-15  1:40     ` Mathieu Desnoyers [this message]
2007-07-15 23:31       ` [PATCH] Linux Kernel Markers - Architecture Independent Code - kerneldoc Mathieu Desnoyers
2007-07-15 23:43     ` [PATCH] Linux Kernel Markers - Architecture Independent Code Remove ifdef KERNEL Mathieu Desnoyers
2007-07-15 23:46       ` [PATCH] Linux Kernel Markers - Architecture Independent Code - kerneldoc for implementation Mathieu Desnoyers
2007-07-15 23:47         ` Mathieu Desnoyers
2007-07-15 23:48       ` Mathieu Desnoyers
2007-07-14  1:29 ` [patch 2/4] Linux Kernel Markers - Add kconfig menus for the marker code Mathieu Desnoyers
2007-07-14  1:29 ` [patch 3/4] Linux Kernel Markers - Documentation Mathieu Desnoyers
2007-07-14  1:29 ` [patch 4/4] Port of blktrace to the Linux Kernel Markers Mathieu Desnoyers

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20070715014056.GI23209@Krystal \
    --to=compudj@krystal.dyndns.org \
    --cc=akpm@linux-foundation.org \
    --cc=hch@infradead.org \
    --cc=linux-kernel@vger.kernel.org \
    --subject='Re: [PATCH] Linux Kernel Markers -  Architecture Independent Code - kerneldoc' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).