Skip to contentSkip to conversation

Several minor fixes for documentation

PATCH In review Chengwei Yang 2 participants 3 messages May 4, 2013 – May 6, 2013

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/2 Several minor fixes for documentation

---
 libkmod/libkmod-module.c |   12 +++++-------
 libkmod/libkmod.c        |    6 ++++--
 2 files changed, 9 insertions(+), 9 deletions(-)
libkmod/libkmod-module.c +5 -7
index 47d12ad..b6fcc3b 100644
@@ -570,8 +570,7 @@ fail:
  * Drop a reference of each kmod module in @list and releases the resources
  * taken by the list itself.
  *
- * Returns: NULL if @mod is NULL or if the module was released. Otherwise it
- * returns the passed @mod with its refcount decremented.
+ * Returns: 0
  */
 KMOD_EXPORT int kmod_module_unref_list(struct kmod_list *list)
 {
@@ -629,9 +628,8 @@ static const struct kmod_list *module_get_dependencies_noref(const struct kmod_m
  * The result is cached in @mod, so subsequent calls to this function will
  * return the already searched list of modules.
  *
- * Returns: NULL on failure or if there are any dependencies. Otherwise it
- * returns a list of kmod modules that can be released by calling
- * kmod_module_unref_list().
+ * Returns: NULL on failure. Otherwise it returns a list of kmod modules
+ * that can be released by calling kmod_module_unref_list().
  */
 KMOD_EXPORT struct kmod_list *kmod_module_get_dependencies(const struct kmod_module *mod)
 {
@@ -1564,7 +1562,7 @@ void kmod_module_set_remove_commands(struct kmod_module *mod, const char *cmd)
  * Create a new list of kmod modules with all modules currently loaded in
  * kernel. It uses /proc/modules to get the names of loaded modules and to
  * create kmod modules by calling kmod_module_new_from_name() in each of them.
- * They are put are put in @list in no particular order.
+ * They are put in @list in no particular order.
  *
  * The initial refcount is 1, and needs to be decremented to release the
  * resources of the kmod_module. The returned @list must be released by
@@ -2380,7 +2378,7 @@ list_error:
 }
 
 /**
- * kmod_module_versions_get_symbol:
+ * kmod_module_version_get_symbol:
  * @entry: a list entry representing a kmod module versions
  *
  * Get the symbol of a kmod module versions.
libkmod/libkmod.c +4 -2
index 66d4859..e8e3ea0 100644
@@ -219,8 +219,8 @@ static char *get_kernel_release(const char *dirname)
  * kmod_new:
  * @dirname: what to consider as linux module's directory, if NULL
  *           defaults to /lib/modules/`uname -r`. If it's relative,
- *           it's treated as relative to current the current working
- *           directory. Otherwise, give an absolute dirname.
+ *           it's treated as relative to the current working directory.
+ *           Otherwise, give an absolute dirname.
  * @config_paths: ordered array of paths (directories or files) where
  *                to load from user-defined configuration parameters such as
  *                alias, blacklists, commands (install, remove). If
@@ -307,6 +307,8 @@ KMOD_EXPORT struct kmod_ctx *kmod_ref(struct kmod_ctx *ctx)
  *
  * Drop a reference of the kmod library context. If the refcount
  * reaches zero, the resources of the context will be released.
+ *
+ * Returns: the passed kmod library context or NULL if it's freed
  */
 KMOD_EXPORT struct kmod_ctx *kmod_unref(struct kmod_ctx *ctx)
 {
Signature · 1 line
1.7.9.5
#1 lore raw

PATCH v2 2/2 Add document for exported enums

There are several exported enums by libkmod without document, this patch mainly added documentation for below enums like the way kmod_resources be documented in.
* kmod_index
* kmod_remove
* kmod_insert
* kmod_probe
* kmod_filter
* kmod_module_initstate

This is not the best way to document these exported enums, however, it's the simple way due to gtkdoc limits. It doesn't support export plain enum like below: see https://bugzilla.gnome.org/show_bug.cgi?id=657444
---------8<-------head.h--------------8<-----------
...

enum foo {
    ...
};

...
---------8<-------end of head.h-------8<----------- ---------8<-------source.c------------8<-----------
...
/**
* document for foo here
*/
...
typedef enum foo foo;
...
---------8<-------end of source.c-----8<----------

---
 libkmod/libkmod-module.c |   43 ++++++++++++++++++++++++++++++++++++++-----
 libkmod/libkmod.c        |    6 +++++-
 2 files changed, 43 insertions(+), 6 deletions(-)
libkmod/libkmod-module.c +38 -5
index b6fcc3b..b24ea8f 100644
@@ -738,7 +738,15 @@ extern long delete_module(const char *name, unsigned int flags);
 /**
  * kmod_module_remove_module:
  * @mod: kmod module
- * @flags: flags to pass to Linux kernel when removing the module
+ * @flags: flags to pass to Linux kernel when removing the module, valid flags are
+ * KMOD_REMOVE_FORCE: force remove module regardless if it's still in
+ * use by a kernel subsystem or other process;
+ * KMOD_REMOVE_NOWAIT: return immediately. It will fail if the module
+ * is in using and KMOD_REMOVE_FORCE is not specified.
+ * If this module is in use by any kernel subsystem or process, not using
+ * this flag will cause the call to block indefinitely, until the module
+ * is not in use anymore. Always use this flag, it's deprecated not using
+ * it and the default behavior might change in future to always set it.
  *
  * Remove a module from Linux kernel.
  *
@@ -770,7 +778,9 @@ extern long init_module(const void *mem, unsigned long len, const char *args);
  * kmod_module_insert_module:
  * @mod: kmod module
  * @flags: flags are not passed to Linux Kernel, but instead they dictate the
- * behavior of this function.
+ * behavior of this function, valid flags are
+ * KMOD_INSERT_FORCE_VERMAGIC: ignore kernel version magic;
+ * KMOD_INSERT_FORCE_MODVERSION: ignore symbol version hashes.
  * @options: module's options to pass to Linux Kernel.
  *
  * Insert a module in Linux kernel. It opens the file pointed by @mod,
@@ -879,7 +889,9 @@ static bool module_is_blacklisted(struct kmod_module *mod)
 /**
  * kmod_module_apply_filter
  * @ctx: kmod library context
- * @filter_type: bitmask to filter modules on
+ * @filter_type: bitmask to filter modules out, valid types are
+ * KMOD_FILTER_BLACKLIST: filter modules in blacklist out;
+ * KMOD_FILTER_BUILTIN: filter builtin modules out.
  * @input: list of kmod_module to be filtered
  * @output: where to save the new list
  *
@@ -1150,7 +1162,24 @@ static int kmod_module_get_probe_list(struct kmod_module *mod,
  * kmod_module_probe_insert_module:
  * @mod: kmod module
  * @flags: flags are not passed to Linux Kernel, but instead they dictate the
- * behavior of this function.
+ * behavior of this function, valid flags are
+ * KMOD_PROBE_FORCE_VERMAGIC: ignore kernel version magic;
+ * KMOD_PROBE_FORCE_MODVERSION: ignore symbol version hashes;
+ * KMOD_PROBE_IGNORE_COMMAND: whether the probe should ignore install
+ * commands and softdeps configured in the system;
+ * KMOD_PROBE_IGNORE_LOADED: do not check whether the module is already
+ * live in kernel or not;
+ * KMOD_PROBE_DRY_RUN: dry run, do not insert module, just call the
+ * associated callback function;
+ * KMOD_PROBE_FAIL_ON_LOADED: if KMOD_PROBE_IGNORE_LOADED is not specified
+ * and the module is already live in kernel, the function will fail if this
+ * flag is specified;
+ * KMOD_PROBE_APPLY_BLACKLIST_ALL: probe will apply KMOD_FILTER_BLACKLIST
+ * filter to this module and its dependencies. This will most likely fail
+ * the probe, unless a blacklisted module is already loaded;
+ * KMOD_PROBE_APPLY_BLACKLIST: probe will fail if the module is in blacklist;
+ * KMOD_PROBE_APPLY_BLACKLIST_ALIAS_ONLY: probe will fail if the module is an
+ * alias and is blacklisted.
  * @extra_options: module's options to pass to Linux Kernel. It applies only
  * to @mod, not to its dependencies.
  * @run_install: function to run when @mod is backed by an install command.
@@ -1650,7 +1679,11 @@ KMOD_EXPORT const char *kmod_module_initstate_str(enum kmod_module_initstate sta
  * Get the initstate of this @mod, as returned by Linux Kernel, by reading
  * /sys filesystem.
  *
- * Returns: < 0 on error or enum kmod_initstate if module is found in kernel.
+ * Returns: < 0 on error or module state if module is found in kernel, valid states are
+ * KMOD_MODULE_BUILTIN: module is builtin;
+ * KMOD_MODULE_LIVE: module is live in kernel;
+ * KMOD_MODULE_COMING: module is being loaded;
+ * KMOD_MODULE_GOING: module is being unloaded.
  */
 KMOD_EXPORT int kmod_module_get_initstate(const struct kmod_module *mod)
 {
libkmod/libkmod.c +5 -1
index e8e3ea0..788676c 100644
@@ -856,7 +856,11 @@ KMOD_EXPORT void kmod_unload_resources(struct kmod_ctx *ctx)
 /**
  * kmod_dump_index:
  * @ctx: kmod library context
- * @type: index to dump
+ * @type: index to dump, valid indexes are
+ * KMOD_INDEX_MODULES_DEP: index of module dependencies;
+ * KMOD_INDEX_MODULES_ALIAS: index of module aliases;
+ * KMOD_INDEX_MODULES_SYMBOL: index of symbol aliases;
+ * KMOD_INDEX_MODULES_BUILTIN: index of builtin module.
  * @fd: file descriptor to dump index to
  *
  * Dump index to file descriptor. Note that this function doesn't use stdio.h
Signature · 1 line
1.7.9.5
#2 lore raw

Re: [V2, 2/2] Add document for exported enums

Hi Chengwei,

Quoted 87 lines · Chengwei Yang

There are several exported enums by libkmod without document, this patch mainly added documentation for below enums like the way kmod_resources be documented in.
* kmod_index
* kmod_remove
* kmod_insert
* kmod_probe
* kmod_filter
* kmod_module_initstate

This is not the best way to document these exported enums, however, it's the simple way due to gtkdoc limits. It doesn't support export plain enum like below: see https://bugzilla.gnome.org/show_bug.cgi?id=657444
---------8<-------head.h--------------8<-----------
...

enum foo {
    ...
};

...
---------8<-------end of head.h-------8<----------- ---------8<-------source.c------------8<-----------
...
/**
* document for foo here
*/
...
typedef enum foo foo;
...
---------8<-------end of source.c-----8<----------

---
 libkmod/libkmod-module.c |   43 ++++++++++++++++++++++++++++++++++++++-----
 libkmod/libkmod.c        |    6 +++++-
 2 files changed, 43 insertions(+), 6 deletions(-)
libkmod/libkmod-module.c +20 -4
index b6fcc3b..b24ea8f 100644
@@ -738,7 +738,15 @@ extern long delete_module(const char *name, unsigned int flags);
 /**
  * kmod_module_remove_module:
  * @mod: kmod module
- * @flags: flags to pass to Linux kernel when removing the module
+ * @flags: flags to pass to Linux kernel when removing the module, valid flags are
+ * KMOD_REMOVE_FORCE: force remove module regardless if it's still in
+ * use by a kernel subsystem or other process;
+ * KMOD_REMOVE_NOWAIT: return immediately. It will fail if the module
+ * is in using and KMOD_REMOVE_FORCE is not specified.
+ * If this module is in use by any kernel subsystem or process, not using
+ * this flag will cause the call to block indefinitely, until the module
+ * is not in use anymore. Always use this flag, it's deprecated not using
+ * it and the default behavior might change in future to always set it.
  *
  * Remove a module from Linux kernel.
  *
@@ -770,7 +778,9 @@ extern long init_module(const void *mem, unsigned long len, const char *args);
  * kmod_module_insert_module:
  * @mod: kmod module
  * @flags: flags are not passed to Linux Kernel, but instead they dictate the
- * behavior of this function.
+ * behavior of this function, valid flags are
+ * KMOD_INSERT_FORCE_VERMAGIC: ignore kernel version magic;
+ * KMOD_INSERT_FORCE_MODVERSION: ignore symbol version hashes.
  * @options: module's options to pass to Linux Kernel.
  *
  * Insert a module in Linux kernel. It opens the file pointed by @mod,
@@ -879,7 +889,9 @@ static bool module_is_blacklisted(struct kmod_module *mod)
 /**
  * kmod_module_apply_filter
  * @ctx: kmod library context
- * @filter_type: bitmask to filter modules on
+ * @filter_type: bitmask to filter modules out, valid types are
+ * KMOD_FILTER_BLACKLIST: filter modules in blacklist out;
+ * KMOD_FILTER_BUILTIN: filter builtin modules out.
  * @input: list of kmod_module to be filtered
  * @output: where to save the new list
  *
@@ -1150,7 +1162,24 @@ static int kmod_module_get_probe_list(struct kmod_module *mod,
  * kmod_module_probe_insert_module:
  * @mod: kmod module
  * @flags: flags are not passed to Linux Kernel, but instead they dictate the
- * behavior of this function.
+ * behavior of this function, valid flags are
+ * KMOD_PROBE_FORCE_VERMAGIC: ignore kernel version magic;
+ * KMOD_PROBE_FORCE_MODVERSION: ignore symbol version hashes;
+ * KMOD_PROBE_IGNORE_COMMAND: whether the probe should ignore install
+ * commands and softdeps configured in the system;

libkmod/libkmod-module.c static int kmod_module_get_probe_list(struct kmod_module *mod, · line 1179

Quoted 10 lines
libkmod/libkmod-module.c +10 -0
+ * KMOD_PROBE_IGNORE_LOADED: do not check whether the module is already
+ * live in kernel or not;
+ * KMOD_PROBE_DRY_RUN: dry run, do not insert module, just call the
+ * associated callback function;
+ * KMOD_PROBE_FAIL_ON_LOADED: if KMOD_PROBE_IGNORE_LOADED is not specified
+ * and the module is already live in kernel, the function will fail if this
+ * flag is specified;
+ * KMOD_PROBE_APPLY_BLACKLIST_ALL: probe will apply KMOD_FILTER_BLACKLIST
+ * filter to this module and its dependencies. This will most likely fail
+ * the probe, unless a blacklisted module is already loaded;

I changed this description a little bit:

+ * KMOD_PROBE_APPLY_BLACKLIST_ALL: probe will apply KMOD_FILTER_BLACKLIST
+ * filter to this module and its dependencies. If any of the dependencies (or
+ * the module) is blacklisted, the probe will fail, unless the blacklisted
+ * module is already live in kernel;

Quoted 27 lines
libkmod/libkmod-module.c +8 -1
+ * KMOD_PROBE_APPLY_BLACKLIST: probe will fail if the module is in blacklist;
+ * KMOD_PROBE_APPLY_BLACKLIST_ALIAS_ONLY: probe will fail if the module is an
+ * alias and is blacklisted.
  * @extra_options: module's options to pass to Linux Kernel. It applies only
  * to @mod, not to its dependencies.
  * @run_install: function to run when @mod is backed by an install command.
@@ -1650,7 +1679,11 @@ KMOD_EXPORT const char *kmod_module_initstate_str(enum kmod_module_initstate sta
  * Get the initstate of this @mod, as returned by Linux Kernel, by reading
  * /sys filesystem.
  *
- * Returns: < 0 on error or enum kmod_initstate if module is found in kernel.
+ * Returns: < 0 on error or module state if module is found in kernel, valid states are
+ * KMOD_MODULE_BUILTIN: module is builtin;
+ * KMOD_MODULE_LIVE: module is live in kernel;
+ * KMOD_MODULE_COMING: module is being loaded;
+ * KMOD_MODULE_GOING: module is being unloaded.
  */
 KMOD_EXPORT int kmod_module_get_initstate(const struct kmod_module *mod)
 {
libkmod/libkmod.c +0 -0
index e8e3ea0..788676c 100644
@@ -856,7 +856,11 @@ KMOD_EXPORT void kmod_unload_resources(struct kmod_ctx *ctx)
 /**
  * kmod_dump_index:
  * @ctx: kmod library context

libkmod/libkmod.c KMOD_EXPORT void kmod_unload_resources(struct kmod_ctx *ctx)

Quoted 10 lines
libkmod/libkmod.c +5 -2
- * @type: index to dump
+ * @type: index to dump, valid indexes are
+ * KMOD_INDEX_MODULES_DEP: index of module dependencies;
+ * KMOD_INDEX_MODULES_ALIAS: index of module aliases;
+ * KMOD_INDEX_MODULES_SYMBOL: index of symbol aliases;
+ * KMOD_INDEX_MODULES_BUILTIN: index of builtin module.
  * @fd: file descriptor to dump index to
  *
  * Dump index to file descriptor. Note that this function doesn't use stdio.h
--

Thanks, both patches have been applied.

Lucas De Marchi