Driver porting: more module changes

Module parameters

Modules with parameters should now include <linux/moduleparam.h> explicitly. Parameters are then declared with module_param:

    module_param(name, type, perm);

If the name of the parameter as seen outside the module differs from the name of the variable used to hold the parameter's value, a variant on module param may be used:

    module_param_named(name, value, type, perm);

String parameters will normally be declared with the charp type; the associated variable is a char pointer which will be set to the parameter's value. If you need to have a string value copied directly into a char array, declare it as:

    module_param_string(name, string, len, perm);

Finally, array parameters (supplied at module load time as a comma-separated list) may be declared with:

    module_param_array(name, type, num, perm);

The one parameter not found in module_param() (num) is an output parameter; if a value for name is supplied when the module is loaded, num will be set to the number of values given. This macro uses the declared length of the array to ensure that it is not overrun if too many values are provided.

As an example of how the new module parameter code works, here is a paramaterized version of the "hello world" module shown previously:

    #include <linux/init.h>
    #include <linux/module.h>
    #include <linux/moduleparam.h>
    
    MODULE_LICENSE("Dual BSD/GPL");
    
    /*
     * A couple of parameters that can be passed in: how many times we say
     * hello, and to whom.
     */
    static char *whom = "world";
    module_param(whom, charp, 0);
    static int howmany = 1;
    module_param(howmany, int, 0);
    
    
    static int hello_init(void)
    {
        int i;
        for (i = 0; i < howmany; i++)
	    printk(KERN_ALERT "(%d) Hello, %s\n", i, whom);
        return 0;
    }
    
    static void hello_exit(void)
    {
    	printk(KERN_ALERT "Goodbye, cruel %s\n", whom);
    }
    
    module_init(hello_init);
    module_exit(hello_exit);

    insmod ./hellop.ko howmany=2 whom=universe

Module aliases

    MODULE_ALIAS("alias-name");

The module use count

The only safe way to manipulate the count of references to a module is outside of the module's code. Otherwise, there will always be times when the kernel is executing within the module, but the reference count is zero. So this work has been moved outside of the modules, and life is generally easier for module authors.

Any code which wishes to call into a module (or use some other module resource) must first attempt to increment that module's reference count:

    int try_module_get(&module);

A reference to a module can be released with module_put().

Again, modules will not normally have to manage their own reference counts. The only exception may be if a module provides a reference to an internal data structure or function that is not accounted for otherwise. In that (rare) case, a module could conceivably call try_module_get() on itself.

As of this writing, modules are considered "live" during initialization, meaning that a try_module_get() will succeed at that time. There is still talk of changing things, however, so that modules are not accessible until they have completed their initialization process. That change will help prevent a whole set of race conditions that come about when a module fails initialization, but it also creates difficulties for modules which have to be available early on. For example, block drivers should be available to read partition tables off of disks when those disks are registered, which usually happens when the module is initializing itself. If the policy changes and modules go back off-limits during initialization, a call to a function like make_module_live() may be required for those modules which must be available sooner. (Update 2.6.0-test9: this change has not happened and seems highly unlikely at this point).

Finally, it is not entirely uncommon for driver authors to put in a special ioctl() function which sets the module use count to zero. Sometimes, during module development, errors can leave the module reference count in a state where it will never reach zero, and there was no other way to get the kernel to unload the module. The new module code supports forced unloading of modules which appear to have outstanding references - if the CONFIG_MODULE_FORCE_UNLOAD option has been set. Needless to say, this option should only be used on development systems, and, even then, with great caution.

Exporting symbols

Chances are that change will cause few problems. When you get a chance, however, you can remove EXPORT_NO_SYMBOLS lines from your module source. Exporting no symbols is now the default, so EXPORT_NO_SYMBOLS is a no-op.

The 2.4 inter_module_ functions have been deprecated as unsafe. The symbol_get() function exists for the cases when normal symbol linking does not work well enough. Its use requires setting up weak references at compile time, and is beyond the scope of this document; there are no users of symbol_get() in the 2.6.0-test9 kernel source.

Kernel version checking

In 2.5, things still work mostly that way. The kernel version is loaded into a separate, "link-once" ELF section, however, rather than being a visible variable within the module itself. As a result, multi-file modules no longer need to define __NO_VERSION__ before including <linux/module.h>.

The new "version magic" scheme also records other information, including the compiler version, SMP status, and preempt status; it is thus able to catch more incompatible situations than the old scheme did.

Module symbol versioning ("modversions") has been completely reworked for the 2.6 kernel. Module authors who use the makefiles shipped with the kernel (and that is about the only way to work now) will find that dealing with modversions has gotten easier than before. The #define hack which tacked checksums onto kernel symbols has gone away in favor of a scheme which stores checksum information in a separate ELF section.

 #define param_check_mytype(name, p) /* optional typechecking */
 int param_set_mytype(const char *val, struct kernel_param *kp) ...
 int param_get_mytype(char *buffer, struct kernel_param *kp) ...

 module_param(myparam, mytype, 000);