There are several exported enum by libkmod without document, so this
patch mainly added documentation for below enums:
* kmod_resources_status
* kmod_module_insert_flags
* kmod_module_remove_flags
* kmod_module_probe_flags
* kmod_filter
* kmod_module_initstate
Signed-off-by: Chengwei Yang <chengwei.yang@xxxxxxxxx>
---
libkmod/docs/libkmod-sections.txt | 6 +++
libkmod/libkmod-module.c | 79 ++++++++++++++++++++++++++++++++-----
libkmod/libkmod.c | 17 +++++---
libkmod/libkmod.h | 32 ++++++++-------
4 files changed, 105 insertions(+), 29 deletions(-)
diff --git a/libkmod/docs/libkmod-sections.txt b/libkmod/docs/libkmod-sections.txt
index e59ab7a..d826daf 100644
--- a/libkmod/docs/libkmod-sections.txt
+++ b/libkmod/docs/libkmod-sections.txt
@@ -5,6 +5,7 @@ kmod_new
kmod_ref
kmod_unref
+kmod_resources_status
kmod_load_resources
kmod_unload_resources
kmod_validate_resources
@@ -53,13 +54,17 @@ kmod_module_ref
kmod_module_unref
kmod_module_unref_list
+kmod_module_insert_flags
kmod_module_insert_module
+kmod_module_probe_flags
kmod_module_probe_insert_module
+kmod_module_remove_flags
kmod_module_remove_module
kmod_module_get_module
kmod_module_get_dependencies
kmod_module_get_softdeps
+kmod_filter
kmod_module_apply_filter
kmod_module_get_filtered_blacklist
kmod_module_get_install_commands
@@ -98,6 +103,7 @@ kmod_module_info_get_value
<SECTION>
<FILE>libkmod-loaded</FILE>
kmod_module_new_from_loaded
+kmod_module_initstate
kmod_module_get_initstate
kmod_module_initstate_str
kmod_module_get_size
diff --git a/libkmod/libkmod-module.c b/libkmod/libkmod-module.c
index 4754eeb..6086379 100644
--- a/libkmod/libkmod-module.c
+++ b/libkmod/libkmod-module.c
@@ -581,6 +581,15 @@ KMOD_EXPORT int kmod_module_unref_list(struct kmod_list *list)
}
/**
+ * kmod_filter:
+ * @KMOD_FILTER_BLACKLIST: filter modules in blacklist out
+ * @KMOD_FILTER_BUILTIN: filter builtin modules out
+ *
+ * kmod module filter flags, used to filter modules, used by
+ * kmod_module_apply_filter().
+ */
+
+/**
* kmod_module_get_filtered_blacklist:
* @ctx: kmod library context
* @input: list of kmod_module to be filtered with blacklist
@@ -736,9 +745,18 @@ KMOD_EXPORT const char *kmod_module_get_path(const struct kmod_module *mod)
extern long delete_module(const char *name, unsigned int flags);
/**
+ * kmod_module_remove_flags:
+ * @KMOD_REMOVE_FORCE: force remove module regardless its reference count
+ * @KMOD_REMOVE_NOWAIT: return immediately
+ *
+ * kmod module flags used by kmod_module_remove_module().
+ */
+
+/**
* 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,
+ * see #kmod_module_remove_flags.
*
* Remove a module from Linux kernel.
*
@@ -767,10 +785,19 @@ KMOD_EXPORT int kmod_module_remove_module(struct kmod_module *mod,
extern long init_module(const void *mem, unsigned long len, const char *args);
/**
+ * kmod_module_insert_flags:
+ * @KMOD_INSERT_FORCE_VERMAGIC: remove version magic to force insert module
+ * @KMOD_INSERT_FORCE_MODVERSION: remove interface version to force insert module
+ * insert module
+ *
+ * kmod module flags used by kmod_module_insert_module().
+ */
+
+/**
* 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. See #kmod_module_insert_flags.
* @options: module's options to pass to Linux Kernel.
*
* Insert a module in Linux kernel. It opens the file pointed by @mod,
@@ -879,7 +906,7 @@ 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, see #kmod_filter.
* @input: list of kmod_module to be filtered
* @output: where to save the new list
*
@@ -890,7 +917,7 @@ static bool module_is_blacklisted(struct kmod_module *mod)
* list.
*/
KMOD_EXPORT int kmod_module_apply_filter(const struct kmod_ctx *ctx,
- enum kmod_filter filter_type,
+ kmod_filter filter_type,
const struct kmod_list *input,
struct kmod_list **output)
{
@@ -1147,10 +1174,31 @@ static int kmod_module_get_probe_list(struct kmod_module *mod,
}
/**
+ * kmod_module_probe_flags:
+ * @KMOD_PROBE_FORCE_VERMAGIC: remove version magic to force insert module
+ * @KMOD_PROBE_FORCE_MODVERSION: remove interface version to force insert module
+ * @KMOD_PROBE_IGNORE_COMMAND: whether the module's command and softdep should
+ * be ignored
+ * @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
+ * @KMOD_PROBE_FAIL_ON_LOADED: if KMOD_PROBE_IGNORE_LOADED not specified and
+ * the module is already live in kernel, the function will fail if this flag
+ * specified
+ * @KMOD_PROBE_APPLY_BLACKLIST_ALL: probe will fail if the module is in
+ * blacklist
+ * @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 in blacklist
+ *
+ * kmod module probe flags used by kmod_module_probe_insert_module().
+ */
+
+/**
* 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. See #kmod_module_probe_flags.
* @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.
@@ -1619,15 +1667,28 @@ KMOD_EXPORT int kmod_module_new_from_loaded(struct kmod_ctx *ctx,
}
/**
+ * kmod_module_initstate:
+ * @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_MODULE_PAD: do not use it
+ *
+ * kmod module init state, used by kmod_module_get_initstate()
+ * and kmod_module_initstate_str().
+ */
+
+/**
* kmod_module_initstate_str:
- * @state: the state as returned by kmod_module_get_initstate()
+ * @state: the state as returned by kmod_module_get_initstate(), see
+ * #kmod_module_initstate.
*
* Translate a initstate to a string.
*
* Returns: the string associated to the @state. This string is statically
* allocated, do not free it.
*/
-KMOD_EXPORT const char *kmod_module_initstate_str(enum kmod_module_initstate state)
+KMOD_EXPORT const char *kmod_module_initstate_str(kmod_module_initstate state)
{
switch (state) {
case KMOD_MODULE_BUILTIN:
@@ -1650,7 +1711,7 @@ 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 #kmod_module_initstate if module is found in kernel.
*/
KMOD_EXPORT int kmod_module_get_initstate(const struct kmod_module *mod)
{
@@ -2378,7 +2439,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.
diff --git a/libkmod/libkmod.c b/libkmod/libkmod.c
index 1113614..98cf15e 100644
--- a/libkmod/libkmod.c
+++ b/libkmod/libkmod.c
@@ -48,6 +48,16 @@
* and is passed to all library operations.
*/
+/**
+ * kmod_resources_status:
+ * @KMOD_RESOURCES_OK: kmod resources are still valid
+ * @KMOD_RESOURCES_MUST_RELOAD: kmod resources are sufficient to call
+ * kmod_load_resources() and kmod_unload_resources()
+ * @KMOD_RESOURCES_MUST_RECREATE: kmod resources #kmod_ctx must be re-created.
+ *
+ * kmod resources status, see kmod_load_resources(), kmod_unload_resources()
+ * and kmod_validate_resources().
+ */
static struct _index_files {
const char *fn;
const char *prefix;
@@ -740,12 +750,9 @@ static bool is_cache_invalid(const char *path, unsigned long long stamp)
* Check if indexes and configuration files changed on disk and the current
* context is not valid anymore.
*
- * Returns: KMOD_RESOURCES_OK if resources are still valid,
- * KMOD_RESOURCES_MUST_RELOAD if it's sufficient to call
- * kmod_unload_resources() and kmod_load_resources() or
- * KMOD_RESOURCES_MUST_RECREATE if @ctx must be re-created.
+ * Returns: kmod resources status, see #kmod_resources_status
*/
-KMOD_EXPORT int kmod_validate_resources(struct kmod_ctx *ctx)
+KMOD_EXPORT kmod_resources_status kmod_validate_resources(struct kmod_ctx *ctx)
{
struct kmod_list *l;
size_t i;
diff --git a/libkmod/libkmod.h b/libkmod/libkmod.h
index 3397f87..c1bec07 100644
--- a/libkmod/libkmod.h
+++ b/libkmod/libkmod.h
@@ -59,13 +59,15 @@ void kmod_set_userdata(struct kmod_ctx *ctx, const void *userdata);
int kmod_load_resources(struct kmod_ctx *ctx);
void kmod_unload_resources(struct kmod_ctx *ctx);
-enum kmod_resources {
+/* kmod resources status */
+typedef enum {
KMOD_RESOURCES_OK = 0,
KMOD_RESOURCES_MUST_RELOAD = 1,
KMOD_RESOURCES_MUST_RECREATE = 2,
-};
-int kmod_validate_resources(struct kmod_ctx *ctx);
+} kmod_resources_status;
+kmod_resources_status kmod_validate_resources(struct kmod_ctx *ctx);
+/* kmod module type */
enum kmod_index {
KMOD_INDEX_MODULES_DEP = 0,
KMOD_INDEX_MODULES_ALIAS,
@@ -138,19 +140,19 @@ struct kmod_module *kmod_module_get_module(const struct kmod_list *entry);
/* Removal flags */
-enum kmod_remove {
+typedef enum {
KMOD_REMOVE_FORCE = O_TRUNC,
KMOD_REMOVE_NOWAIT = O_NONBLOCK,
-};
+} kmod_module_remove_flags;
/* Insertion flags */
-enum kmod_insert {
+typedef enum {
KMOD_INSERT_FORCE_VERMAGIC = 0x1,
KMOD_INSERT_FORCE_MODVERSION = 0x2,
-};
+} kmod_module_insert_flags;
/* Flags to kmod_module_probe_insert_module() */
-enum kmod_probe {
+typedef enum {
KMOD_PROBE_FORCE_VERMAGIC = 0x00001,
KMOD_PROBE_FORCE_MODVERSION = 0x00002,
KMOD_PROBE_IGNORE_COMMAND = 0x00004,
@@ -162,13 +164,13 @@ enum kmod_probe {
KMOD_PROBE_APPLY_BLACKLIST_ALL = 0x10000,
KMOD_PROBE_APPLY_BLACKLIST = 0x20000,
KMOD_PROBE_APPLY_BLACKLIST_ALIAS_ONLY = 0x40000,
-};
+} kmod_module_probe_flags;
/* Flags to kmod_module_apply_filter() */
-enum kmod_filter {
+typedef enum {
KMOD_FILTER_BLACKLIST = 0x00001,
KMOD_FILTER_BUILTIN = 0x00002,
-};
+} kmod_filter;
int kmod_module_remove_module(struct kmod_module *mod, unsigned int flags);
int kmod_module_insert_module(struct kmod_module *mod, unsigned int flags,
@@ -194,7 +196,7 @@ int kmod_module_get_filtered_blacklist(const struct kmod_ctx *ctx,
const struct kmod_list *input,
struct kmod_list **output) __attribute__ ((deprecated));
int kmod_module_apply_filter(const struct kmod_ctx *ctx,
- enum kmod_filter filter_type,
+ kmod_filter filter_type,
const struct kmod_list *input,
struct kmod_list **output);
@@ -205,15 +207,15 @@ int kmod_module_apply_filter(const struct kmod_ctx *ctx,
* by kernel
*/
-enum kmod_module_initstate {
+typedef enum {
KMOD_MODULE_BUILTIN = 0,
KMOD_MODULE_LIVE,
KMOD_MODULE_COMING,
KMOD_MODULE_GOING,
/* Padding to make sure enum is not mapped to char */
_KMOD_MODULE_PAD = (1 << 31),
-};
-const char *kmod_module_initstate_str(enum kmod_module_initstate state);
+} kmod_module_initstate;
+const char *kmod_module_initstate_str(kmod_module_initstate state);
int kmod_module_get_initstate(const struct kmod_module *mod);
int kmod_module_get_refcnt(const struct kmod_module *mod);
struct kmod_list *kmod_module_get_holders(const struct kmod_module *mod);
--
1.7.9.5
--
To unsubscribe from this list: send the line "unsubscribe linux-modules" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
