Module Parameters

The Linux kernel provides a simple framework, allowing drivers to declare parameters that the user can specify on either boot or module load and then have these parameters exposed in your driver as global variables. These module parameters also show up in sysfs (see Chapter 17," kobjects and sysfs"). Consequently, creating and managing module parameters that can be specified in a myriad of convenient ways is trivial.

Defining a module parameter is done via the macro module_param():

module_param(name, type, perm);

where name is the name of both the parameter exposed to the user and the variable holding the parameter inside your module. The type argument holds the parameter's data type; it is one of byte, short, ushort, int, uint, long, ulong, charp, bool, or invbool. These types are, respectively, a byte, a short integer, an unsigned short integer, an integer, an unsigned integer, a long integer, an unsigned long integer, a pointer to a char, a Boolean, and a Boolean whose value is inverted from what the user specifies. The byte type is stored in a single char and the Boolean types are stored in variables of type int. The rest are stored in the corresponding primitive C types. Finally, the perm argument specifies the permissions of the corresponding file in sysfs. The permissions can be specified in the usual octal format, for example 0644 (owner can read and write, group can read, everyone else can read), or by ORing together the usual S_Ifoo defines, for example S_IRUGO | S_IWUSR (everyone can read, user can also write). A value of zero disables the sysfs entry altogether.

The macro does not declare the variable for you. You must do that before using the macro. Therefore, typical use might resemble

/* module parameter controlling the capability to allow live bait on the pole */
static int allow_live_bait = 1;             /* default to on */
module_param(allow_live_bait, bool, 0644);  /* a Boolean type */

This would be in the outermost scope of your module's source file. In other words, allow_live_bait is global.

It is possible to have the internal variable named differently than the external parameter. This is accomplished via module_param_named():

module_param_named(name, variable, type, perm);

where name is the externally viewable parameter name and variable is the name of the internal global variable. For example,

static unsigned int max_test = DEFAULT_MAX_LINE_TEST;
module_param_named(maximum_line_test, max_test, int, 0);

Normally, you would use a type of charp to define a module parameter that takes a string. The kernel copies the string provided by the user into memory and points your variable to the string. For example,

static char *name;
module_param(name, charp, 0);

If so desired, it is also possible to have the kernel copy the string directly into a character array that you supply. This is done via module_param_string():

module_param_string(name, string, len, perm);

where name is the external parameter name, string is the internal variable name, len is the size of the buffer named by string (or some smaller size, but that does not make much sense), and perm is the sysfs permissions (or zero to disable a sysfs entry altogether). For example,

static char species[BUF_LEN];
module_param_string(specifies, species, BUF_LEN, 0);

You can accept a comma-separated list of parameters that are stored in a C array via module_param_array():

module_param_array(name, type, nump, perm);

where name is again the external parameter and internal variable name, type is the data type, and perm is the sysfs permissions. The new argument, nump, is a pointer to an integer where the kernel will store the number of entries stored into the array. Note that the array pointed to by name must be statically allocated. The kernel determines the array's size at compile-time and ensures that it does not cause an overrun. Use is simple. For example,

static int fish[MAX_FISH];
static int nr_fish;
module_param_array(fish, int, &nr_fish, 0444);

You can name the internal array something different than the external parameter with module_param_array_named():

module_param_array_named(name, array, type, nump, perm);

The parameters are identical to the other macros.

Finally, you can document your parameters by using MODULE_PARM_DESC():

static unsigned short size = 1;
module_param(size, ushort, 0644);
MODULE_PARM_DESC(size, "The size in inches of the fishing pole " \
                 "connected to this computer.");

All these macros require the inclusion of <linux/moduleparam.h>.