Merge pull request #368 from sysprog21/params

Add module_param_cb() example

Author: jserv

examples/Makefile

@@ -3,6 +3,7 @@ obj-m += hello-2.o
 obj-m += hello-3.o
 obj-m += hello-4.o
 obj-m += hello-5.o
+obj-m += hello-6.o
 obj-m += startstop.o
 startstop-objs := start.o stop.o
 obj-m += chardev.o

examples/hello-6.c

@@ -0,0 +1,59 @@
+/*
+ * hello-6.c - Demonstrates module_param_cb() callbacks.
+ */
+#include <linux/init.h>
+#include <linux/module.h>
+#include <linux/moduleparam.h>
+#include <linux/printk.h>
+
+MODULE_LICENSE("GPL");
+MODULE_AUTHOR("LKMPG");
+MODULE_DESCRIPTION("A module_param_cb() example");
+
+static int watched = 42;
+
+static int watched_set(const char *val, const struct kernel_param *kp)
+{
+    int ret;
+
+    ret = param_set_int(val, kp);
+    if (ret)
+        return ret;
+
+    pr_info("watched updated to %d\n", watched);
+    return 0;
+}
+
+static int watched_get(char *buffer, const struct kernel_param *kp)
+{
+    int ret;
+
+    ret = param_get_int(buffer, kp);
+    if (ret >= 0)
+        pr_info("watched was read\n");
+
+    return ret;
+}
+
+static const struct kernel_param_ops watched_ops = {
+    .set = watched_set,
+    .get = watched_get,
+};
+
+module_param_cb(watched, &watched_ops, &watched, 0644);
+MODULE_PARM_DESC(watched, "An integer that logs every update");
+
+static int __init hello_6_init(void)
+{
+    pr_info("Hello, world 6\n");
+    pr_info("watched starts at %d\n", watched);
+    return 0;
+}
+
+static void __exit hello_6_exit(void)
+{
+    pr_info("Goodbye, world 6\n");
+}
+
+module_init(hello_6_init);
+module_exit(hello_6_exit);

lkmpg.tex

@@ -585,6 +585,38 @@ \subsection{Passing Command Line Arguments to a Module}
 
 \samplec{examples/hello-5.c}
 
+If you need to validate a parameter or react whenever it changes, use \cpp|module_param_cb()|.
+This variant takes four arguments: the parameter name, a pointer to a \cpp|struct kernel_param_ops|,
+an argument pointer (typically the address of the backing variable), and the sysfs permissions.
+The callbacks stored in \cpp|struct kernel_param_ops| let you override the \cpp|set| and \cpp|get|
+operations instead of relying on the default helpers such as \cpp|param_set_int()| and \cpp|param_get_int()|.
+With non-zero permissions, the parameter is also exposed through sysfs so the same callbacks can run after the module has already been loaded.
+
+\begin{code}
+static int watched = 42;
+
+static int watched_set(const char *val, const struct kernel_param *kp)
+{
+    int ret = param_set_int(val, kp);
+
+    if (ret)
+        return ret;
+
+    pr_info("watched updated to %d\n", watched);
+    return 0;
+}
+
+static const struct kernel_param_ops watched_ops = {
+    .set = watched_set,
+    .get = param_get_int,
+};
+
+module_param_cb(watched, &watched_ops, &watched, 0644);
+\end{code}
+
+The full example below also overrides \cpp|.get| so that every sysfs read is logged:
+\samplec{examples/hello-6.c}
+
 It is recommended to experiment with the following code:
 \begin{verbatim}
 $ sudo insmod hello-5.ko mystring="bebop" myintarray=-1
@@ -611,12 +643,30 @@ \subsection{Passing Command Line Arguments to a Module}
 myintarray[1] = -1
 got 2 arguments for myintarray.
 
-$ sudo rmmod hello_5
+$ sudo rmmod hello-5
 $ sudo dmesg -t | tail -1
 Goodbye, world 5
 
 $ sudo insmod hello-5.ko mylong=hello
 insmod: ERROR: could not insert module hello-5.ko: Invalid parameters
+
+$ sudo insmod hello-6.ko watched=7
+$ sudo dmesg -t | tail -3
+watched updated to 7
+Hello, world 6
+watched starts at 7
+
+$ cat /sys/module/hello_6/parameters/watched
+7
+$ sudo dmesg -t | tail -1
+watched was read
+
+$ echo 21 | sudo tee /sys/module/hello_6/parameters/watched
+21
+$ sudo dmesg -t | tail -1
+watched updated to 21
+
+$ sudo rmmod hello-6
 \end{verbatim}
 
 \subsection{Modules Spanning Multiple Files}
@@ -637,6 +687,7 @@ \subsection{Modules Spanning Multiple Files}
 obj-m += hello-3.o
 obj-m += hello-4.o
 obj-m += hello-5.o
+obj-m += hello-6.o
 obj-m += startstop.o
 startstop-objs := start.o stop.o