Kernel Korner

Miscellaneous Character Drivers
(January 1998)

Alessandro tells us how to register a small device needing a single entry point with the misc driver.

by Alessandro Rubini

Sometimes people need to write ``small'' device drivers, to support custom hacks--either hardware or software ones. To this end, as well as to host some real drivers, the Linux kernel exports an interface to allow modules to register their own small drivers. The misc driver was designed for this purpose. The code introduced here is meant to run with version 2.0 of the Linux kernel.

In UNIX, Linux and similar operating systems, every device is identified by two numbers: a ``major'' number and a ``minor'' number. These numbers can be seen by invoking ls -l /dev. Every device driver registers its major number with the kernel and is completely responsible for managing its minor numbers. Use of any device with that major number will fall on the same device driver, regardless of the minor number. As a result, every driver needs to register a major number, even if it only deals with a single device, like a pointing tool.

Since the kernel keeps a static table of device drivers, frivolous allocation of major numbers is rather wasteful of RAM. The Linux kernel, therefore, offers a simplified interface for simple drivers--those that will register a single entry point. Note that, in general, allocating the whole name space of a major number to every device is beneficial. This allows the handling of multiple terminals, multiple serial ports and several disk partitions without any overhead in the kernel proper: a single driver takes care of all of them, and uses the minor number to differentiate.

Major number 10 is officially assigned to the misc driver. Modules can register individual minor numbers with the misc driver and take care of a small device, needing only a single entry point.

Registering a Minor Number

The misc driver exports two functions for user modules to register and unregister their own minor number:

#include <linux/miscdevice.h>
int misc_register(struct miscdevice * misc);
int misc_deregister(struct miscdevice * misc);

The miscdevice.h file also declares struct miscdevice in the following way:

struct miscdevice {
        int minor;
        const char *name;
        struct file_operations *fops;
        struct miscdevice *next, *prev;
};

• minor is the minor number being registered. Every misc device must feature a different minor number, because such a number is the only link between the file in /dev and the driver.
• name is the name for this device, meant for human consumption: users will find the name in the /proc/misc file.
• fops is a pointer to the file operations which must be used to act on the device. File operations have been described in a previous ``Kernel Korner'' in April 1996. (That article is available on the web at http://www.linuxjournal.com/issue24/kk24.html.) Anyway, the topic is refreshed later in this article.
• next and prev are used to manage a circularly-linked list of registered drivers.

The real question with the misc device driver is ``what is a sensible value for the minor field?'' Assignment of minor numbers is performed in two ways: either you can use an ``officially assigned'' number, or you can resort to dynamic assignment. In the latter case, your driver asks for a free minor number, and the kernel returns one.

The typical code sequence for assigning a dynamic minor number is as follows:

static struct miscdevice my_dev;
int init_module(void)
{
    int retval;
    my_dev.minor = MISC_DYNAMIC_MINOR;
    my_dev.name = "my";
    my_dev.fops = &my_fops;
    retval = misc_register(&my_dev);
    if (retval) return retval;
    printk("my: got minor %i\n",my_dev.minor);
    return 0;
}

63 my

#!/bin/sh

if [ "x$1" = "x" ]; then
	echo "usage: load_misc  [ [ []]]"
fi
insmod $1 || exit 1
major=10
minor=`grep $DEV /proc/devices | awk "{print \\$1}"`
mknod /dev/$1 c $major $minor

if [ "x$2" != "x"]; then
	chmod $2 /dev/$1
fi
if [ "x$3" != "x"]; then
	chown $3 /dev/$1
fi
if [ "x$4" != "x"]; then
	chgrp $4 /dev/$1
fi
exit 0

You might choose to find an unused minor number and hardwire it in your driver. This would save invoking a script to load the module, but the practice is strongly discouraged. To keep the code compact, drivers/char/misc.c doesn't check for duplication of minor numbers. If the number you chose is later assigned to an official driver, you'll be in trouble when you try to access both your module and the official one.

If the same minor number is registered twice, only the first one will be accessible from user space. Although seemingly unfair, this can't be considered a kernel bug, as no data structure is corrupted. If you wish to register a safe minor number, you should use dynamic allocation.

The file Documentation/devices.txt in the kernel source tree lists all of the official device numbers, including all the minor numbers for the misc driver.

Kernel Configuration

If you have tried to write your own misc driver but insmod returned unresolved symbol misc_register, you have a problem in your kernel configuration.

Originally, the misc driver was designed as a wrapper for all the ``busmouse'' drivers--the kernel drivers for every non-serial pointer device. The driver was only compiled if the current configuration included at least one such mouse driver. Just before version 2.0, the generality of the implementation was widely accepted, and the driver was renamed from ``mouse'' to ``misc''. It is still true, however, that the driver is not available unless you chose to compile at least one of the misc devices as either a module or a native driver.

If you don't have any such devices installed on your system, you can still load your custom misc modules, provided you reply affirmatively, while configuring your kernel, to the question:

Support for user misc device modules (CONFIG_UMISC)

Note that if your kernel is configured to load busmice only as modules, everything will work with the exception of /proc/misc. The /proc file is created only if miscdevice.c is directly linked in the kernel. CONFIG_UMISC takes care of this situation as well.

How Operations are Dispatched

Every time a process interacts with a device driver, the implementation of the system call gives control to the correct driver by means of the file_operations structure. This structure is carried around by struct file: every open file descriptor is associated to one such structure, and file.f_op points to its own file_operations structure.

This setup is similar to object-oriented languages: every object (here, every file) declares how to act on itself, so that high-level code is independent of the actual file being accessed. The Linux kernel is full of object-oriented programming in its implementations, and several ``operations'' structures exist in it, one for each different ``object'' (inodes, memory regions, etc.).

Back to the misc driver. How does my_dev.fops participate in the game? At open time, the kernel allocates a new file structure to describe the object being opened, and initializes its operations structure according to what the file is. Sockets, FIFOs, disk files and devices get their own, different, operations. When a device is opened, its operations are looked up according to the major device number by referencing an array. The open method within the driver is then called. Any other system call that acts on a file will then use file.f_op without checking any other source of information. As a result, a driver can replace the value of file.f_op to tailor the behaviour of a struct file to some inner feature, even if that feature is at a finer grain than the major number, and thus is not visible from the kernel proper.

The open method of the misc driver is able to dispatch operations to the actual low-level driver by modifying file.f_op; the assigned value is the one in my_dev.f_op. After the operations have been overridden, the method calls file.f_op->open(), so that the low-level driver can perform its own initialization. Every other system call invoked on the file will use the new value of file.f_op, and the low-level driver keeps complete control over its device.

An Example: Keyboard LEDs

Since the discussion up to now has been much too philosophical, it's time to move to a working example. The kiss module (Keyboard Informative Status Signals) is a simple tool to play with the keyboard LEDs. It registers itself as a misc device using dynamic minor-number assignment and is controlled by writing textual commands to it. It accepts several one-byte commands, such as ``N'' and ``n'' (to turn the Num-Lock LED on and off), the digits from 0 to 7 (to display binary numbers in that range using the LEDs) and so on.

I don't think there's any need to include source code here, as the driver does little more than the misc_register code shown above. Most of the additional code deals with interpretation of the commands and actual lighting of the LEDs. The tar file with source code and a README file can be retrieved from here (or ftp://ftp.ssc.com/pub/lj/listings/issue51/2920.tgz.

As usual, the sample module that accompanies this article is pretty simple and is of little interest in the real world. This time, however, I think it can be of some interest. As a matter of fact, custom hardware in my computer includes three LEDs to monitor the number of running processes. In my opinion, this is useful information when you are wondering why the computer is not responding--a situation quite common whenever you write buggy drivers or drivers that print too many diagnostic messages.

Alessandro is still using Linux 2.0, because he's spending his spare time building his own misc devices with a soldering iron. He enjoys open source and open air, and reads e-mail as rubini@linux.it.