libkmod/docs: document and reference kmod_probe

Mostly move the existing documentation from
kmod_module_probe_insert_module().

Signed-off-by: Emil Velikov <emil.l.velikov@gmail.com>
Link: https://github.com/kmod-project/kmod/pull/94
Signed-off-by: Lucas De Marchi <lucas.de.marchi@gmail.com>

diff --git a/libkmod/docs/libkmod-sections.txt b/libkmod/docs/libkmod-sections.txt
index 6bde32e313bc5ab6b09cfcdfef190647ce579e5d..a8f84ca785fe9249321a9238d110c9f0b29bdd9d 100644 (file)
--- a/libkmod/docs/libkmod-sections.txt
+++ b/libkmod/docs/libkmod-sections.txt
@@ -60,6 +60,7 @@ kmod_module_unref_list
 
 kmod_insert
 kmod_module_insert_module
+kmod_probe
 kmod_module_probe_insert_module
 kmod_module_remove_module
 

diff --git a/libkmod/libkmod.h b/libkmod/libkmod.h
index b197c69df9984142d5a8cbe5bdf4860da297f536..65a1f30d46db53c9675208e97a151fd5f38f5c2f 100644 (file)
--- a/libkmod/libkmod.h
+++ b/libkmod/libkmod.h
@@ -640,21 +640,6 @@ struct kmod_module *kmod_module_unref(struct kmod_module *mod);
 int kmod_module_unref_list(struct kmod_list *list);
 
 
-/* Flags to kmod_module_probe_insert_module() */
-enum kmod_probe {
-       KMOD_PROBE_FORCE_VERMAGIC =             0x00001,
-       KMOD_PROBE_FORCE_MODVERSION =           0x00002,
-       KMOD_PROBE_IGNORE_COMMAND =             0x00004,
-       KMOD_PROBE_IGNORE_LOADED =              0x00008,
-       KMOD_PROBE_DRY_RUN =                    0x00010,
-       KMOD_PROBE_FAIL_ON_LOADED =             0x00020,
-
-       /* codes below can be used in return value, too */
-       KMOD_PROBE_APPLY_BLACKLIST_ALL =        0x10000,
-       KMOD_PROBE_APPLY_BLACKLIST =            0x20000,
-       KMOD_PROBE_APPLY_BLACKLIST_ALIAS_ONLY = 0x40000,
-};
-
 /* Flags to kmod_module_apply_filter() */
 enum kmod_filter {
        KMOD_FILTER_BLACKLIST = 0x00001,
@@ -689,29 +674,48 @@ enum kmod_insert {
 int kmod_module_insert_module(struct kmod_module *mod, unsigned int flags,
                                                        const char *options);
 
+/**
+ * kmod_probe:
+ * @KMOD_PROBE_FORCE_VERMAGIC: ignore kernel version magic
+ * @KMOD_PROBE_FORCE_MODVERSION: ignore symbol version hashes
+ * @KMOD_PROBE_IGNORE_COMMAND: 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: probe will fail if KMOD_PROBE_IGNORE_LOADED is
+ * not specified and the module is already live in kernel
+ * @KMOD_PROBE_APPLY_BLACKLIST_ALL: prior to probe, apply KMOD_FILTER_BLACKLIST
+ * filter to this module and its dependencies. If any of them are blacklisted
+ * and the blacklisted module is not live in the kernel, the function returns
+ * early with thus enum
+ * @KMOD_PROBE_APPLY_BLACKLIST: probe will return early with this enum, if the
+ * module is blacklisted
+ * @KMOD_PROBE_APPLY_BLACKLIST_ALIAS_ONLY: probe will return early with this
+ * enum, if the module is an alias and is blacklisted
+ *
+ * Bitmask which defines the behaviour of kmod_module_probe_insert_module().
+ */
+enum kmod_probe {
+       KMOD_PROBE_FORCE_VERMAGIC =             0x00001,
+       KMOD_PROBE_FORCE_MODVERSION =           0x00002,
+       KMOD_PROBE_IGNORE_COMMAND =             0x00004,
+       KMOD_PROBE_IGNORE_LOADED =              0x00008,
+       KMOD_PROBE_DRY_RUN =                    0x00010,
+       KMOD_PROBE_FAIL_ON_LOADED =             0x00020,
+
+       /* codes below can be used in return value, too */
+       KMOD_PROBE_APPLY_BLACKLIST_ALL =        0x10000,
+       KMOD_PROBE_APPLY_BLACKLIST =            0x20000,
+       KMOD_PROBE_APPLY_BLACKLIST_ALIAS_ONLY = 0x40000,
+};
+
 /**
  * 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, 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. If any of the dependencies (or
- * the module) is blacklisted, the probe will fail, unless the blacklisted
- * module is already live in kernel;
- * KMOD_PROBE_APPLY_BLACKLIST: probe will fail if the module is blacklisted;
- * KMOD_PROBE_APPLY_BLACKLIST_ALIAS_ONLY: probe will fail if the module is an
- * alias and is blacklisted.
+ * @flags: flags are not passed to the kernel, but instead they dictate the
+ * behavior of this function, valid flags are #kmod_probe
  * @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.