Linux Kernel Markers - Architecture Independent Code - kerneldoc for implementation
Add kerneldoc to Linux Kernel Markers API. It applies after: "linux-kernel-markers-architecture-independent-code-remove-ifdef-kernel.patch" Signed-off-by: Mathieu Desnoyers <[EMAIL PROTECTED]> CC: [EMAIL PROTECTED] --- include/linux/marker.h | 37 +++++++++++++--- kernel/marker.c | 113 ++++++++++++++++++++++++++++++++++--------------- 2 files changed, 112 insertions(+), 38 deletions(-) Index: linux-2.6-lttng/include/linux/marker.h =================================================================== --- linux-2.6-lttng.orig/include/linux/marker.h 2007-07-15 19:19:10.000000000 -0400 +++ linux-2.6-lttng/include/linux/marker.h 2007-07-15 19:20:47.000000000 -0400 @@ -18,6 +18,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, ...); @@ -86,18 +95,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 */ Index: linux-2.6-lttng/kernel/marker.c =================================================================== --- linux-2.6-lttng.orig/kernel/marker.c 2007-07-15 19:20:53.000000000 -0400 +++ linux-2.6-lttng/kernel/marker.c 2007-07-15 19:26:53.000000000 -0400 @@ -62,7 +62,12 @@ struct marker_entry { static struct hlist_head marker_table[MARKER_TABLE_SIZE]; -/* +/** + * __mark_empty_function - Empty probe callback + * @mdata: pointer of type const struct __mark_marker + * @fmt: format string + * @...: variable argument list + * * Empty callback provided as a probe to the markers. By providing this to a * disabled marker, we makes sure the execution flow is always valid even * though the function pointer change and the marker enabling are two distinct @@ -199,7 +204,9 @@ static int _marker_set_format(struct mar return 0; } -/* Sets the probe callback corresponding to one marker. */ +/* + * Sets the probe callback corresponding to one marker. + */ static int _set_marker(struct marker_entry **entry, struct __mark_marker *elem) { @@ -320,11 +327,13 @@ static inline void __marker_update_probe } #ifdef CONFIG_MODULES -/* +/** + * module_marker_update - Update module's markers + * @mod: pointer of type struct module identifying the target module + * * Setup the marker according to the data present in the marker hash table - * upon module load. If an error occur during the set probe range, - * refuse to load the module. Must be called with module_mutex held. - * Since the probe_module parameter is NULL, it is safe for refcount to be NULL. + * upon module load. Must be called with module_mutex held. Since the + * probe_module parameter is NULL, it is safe for refcount to be NULL. */ void module_marker_update(struct module *mod) { @@ -334,7 +343,8 @@ void module_marker_update(struct module } /* - * Update the system wide probes, with modules. */ + * Update the system wide probes, with modules. + */ static inline void _marker_update_probes(struct module *probe_module) { mutex_lock(&module_mutex); @@ -342,16 +352,24 @@ static inline void _marker_update_probes mutex_unlock(&module_mutex); } #else -/* Update the system wide probes, without modules. */ +/* + * Update the system wide probes, without modules. + */ static inline void _marker_update_probes(struct module *probe_module) { __marker_update_probes(probe_module); } #endif -/* - * Register a probe : set the callback for each marker. - * Markers must be disarmed to be registered. +/** + * 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. */ int marker_probe_register(const char *name, const char *format, marker_probe_func *probe, void *pdata) @@ -379,10 +397,11 @@ end: } EXPORT_SYMBOL_GPL(marker_probe_register); -/* - * Unregister a probe : unset the callback for each marker. - * returns the pdata if ok. - * else, returns a ERR_PTR(). +/** + * marker_probe_unregister - Disconnect a probe from a marker + * @name: marker name + * + * Returns the pdata given to marker_probe_register, or an ERR_PTR(). */ void *marker_probe_unregister(const char *name) { @@ -408,11 +427,12 @@ end: } EXPORT_SYMBOL_GPL(marker_probe_unregister); -/* - * Unregister a probe by pdata : unset the callback for each marker. - * Markers must be disarmed to be unregistered. - * returns the pdata if ok. - * else, returns a ERR_PTR(). +/** + * 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, or an ERR_PTR(). */ void *marker_probe_unregister_pdata(void *pdata) { @@ -450,9 +470,13 @@ end: } EXPORT_SYMBOL_GPL(marker_probe_unregister_pdata); -/* - * Arm the probe : arm the immediate values. - * A probe must have been previously registered. +/** + * 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. */ int marker_arm(const char *name) { @@ -477,9 +501,13 @@ end: } EXPORT_SYMBOL_GPL(marker_arm); -/* - * Disarm the probe : disarm the immediate and set the empty callback for each - * marker. +/** + * 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. */ int marker_disarm(const char *name) { @@ -510,6 +538,15 @@ end: } EXPORT_SYMBOL_GPL(marker_disarm); +/** + * 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. + */ void *marker_get_pdata(const char *name) { struct hlist_head *head; @@ -530,7 +567,6 @@ void *marker_get_pdata(const char *name) } EXPORT_SYMBOL_GPL(marker_get_pdata); - /* * No markers are added to the core marker section, no lock needed. * Must be called with modules mutex held for modules markers. @@ -609,11 +645,12 @@ static inline int marker_get_next_module } #endif -/* - * Only need to increment the module use count. - * We allow modification of markers beneath us, since we only want to output - * their information. - * Returns NULL when it reaches the last marker. +/** + * 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(). */ struct __mark_marker *marker_get_next(struct __mark_marker *cur) { @@ -635,13 +672,23 @@ end: } EXPORT_SYMBOL_GPL(marker_get_next); +/** + * marker_get_first - Get first marker to start iteration + * + * Get the first marker found in the kernel. It should have a matching + * marker_release. + */ struct __mark_marker *marker_get_first(void) { return marker_get_next(NULL); } EXPORT_SYMBOL_GPL(marker_get_first); -/* +/** + * marker_release - Release the marker iterator + * @iter: previous marker + * + * Release the ressources held to insure iterator validity. * FIXME: suboptimal * Gets the markers until the end, so no module refcount is held when the * function ends. -- 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 [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/