Add comments to kmod functions

Signed-off-by: Michael Jeanson <mjeanson@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

diff --git a/src/bin/lttng-sessiond/modprobe.c b/src/bin/lttng-sessiond/modprobe.c
index 90fec711b8120c740d0ac4d48239b68c7db097c4..3e41f5c1b6539a9eaa3af8706700c074c473c2b9 100644 (file)
--- a/src/bin/lttng-sessiond/modprobe.c
+++ b/src/bin/lttng-sessiond/modprobe.c
@@ -16,6 +16,13 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  */
 
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  */
 

+/**
+ * @file modprobe.c
+ *
+ * @brief modprobe related functions.
+ *
+ */
+

 #define _LGPL_SOURCE
 #include <assert.h>
 #include <stdio.h>
 #define _LGPL_SOURCE
 #include <assert.h>
 #include <stdio.h>


@@ -93,6 +100,9 @@ static int probes_capacity;
 #if HAVE_KMOD
 #include <libkmod.h>
 
 #if HAVE_KMOD
 #include <libkmod.h>
 

+/**
+ * @brief Logging function for libkmod integration.
+ */

 static void log_kmod(void *data, int priority, const char *file, int line,
                const char *fn, const char *format, va_list args)
 {
 static void log_kmod(void *data, int priority, const char *file, int line,
                const char *fn, const char *format, va_list args)
 {


@@ -106,6 +116,15 @@ static void log_kmod(void *data, int priority, const char *file, int line,
        free(str);
 }
 
        free(str);
 }
 

+/**
+ * @brief Setup the libkmod context.
+ *
+ * Create the context, add a custom logging function and preload the
+ * ressources for faster operation.
+ *
+ * @returns    \c 0 on success
+ *             \c < 0 on error
+ */

 static int setup_kmod_ctx(struct kmod_ctx **ctx)
 {
        int ret = 0;
 static int setup_kmod_ctx(struct kmod_ctx **ctx)
 {
        int ret = 0;


@@ -128,6 +147,19 @@ error:
        return ret;
 }
 
        return ret;
 }
 

+/**
+ * @brief Loads the kernel modules in \p modules
+ *
+ * @param modules      List of modules to load
+ * @param entries      Number of modules in the list
+ * @param required     Are the modules required or optionnal
+ *
+ * If the modules are required, we will return with error after the
+ * first failed module load, otherwise we continue loading.
+ *
+ * @returns            \c 0 on success
+ *                     \c < 0 on error
+ */

 static int modprobe_lttng(struct kern_modules_param *modules,
                int entries, int required)
 {
 static int modprobe_lttng(struct kern_modules_param *modules,
                int entries, int required)
 {


@@ -174,6 +206,18 @@ error:
        return ret;
 }
 
        return ret;
 }
 

+/**
+ * @brief Recursively unload modules.
+ *
+ * This function implements the same modules unloading behavior as
+ * 'modprobe -r' or rmmod, it will recursevily go trought the \p module
+ * dependencies and unload modules with a refcount of 0.
+ *
+ * @param mod          The module to unload
+ *
+ * @returns            \c 0 on success
+ *                     \c < 0 on error
+ */

 static int rmmod_recurse(struct kmod_module *mod) {
        int ret = 0;
        struct kmod_list *deps, *itr;
 static int rmmod_recurse(struct kmod_module *mod) {
        int ret = 0;
        struct kmod_list *deps, *itr;


@@ -202,6 +246,14 @@ static int rmmod_recurse(struct kmod_module *mod) {
        return ret;
 }
 
        return ret;
 }
 

+/**
+ * @brief Unloads the kernel modules in \p modules
+ *
+ * @param modules      List of modules to unload
+ * @param entries      Number of modules in the list
+ * @param required     Are the modules required or optionnal
+ *
+ */

 static void modprobe_remove_lttng(const struct kern_modules_param *modules,
                int entries, int required)
 {
 static void modprobe_remove_lttng(const struct kern_modules_param *modules,
                int entries, int required)
 {