Several minor fixes for documentation
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
@@ -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
@@ -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
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
@@ -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
@@ -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
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_resourcesbe documented in.
*kmod_index
*kmod_remove
*kmod_insert
*kmod_probe
*kmod_filter
*kmod_module_initstateThis 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@@ -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@@ -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