The advantage of scull is that it isn't hardware dependent, since every computer has memory. scull just acts on some memory, allocated using kmalloc. Anyone can compile and run scull, and scull is portable across the computer architectures on which Linux runs. On the other hand, the device doesn't do anything "useful" other than demonstrating the interface between the kernel and char drivers and allowing the user to run some tests.

To make scull be useful as a template for writing real drivers for real devices, we'll show you how to implement several device abstractions on top of the computer memory, each with a different personality.

The scull source implements the following devices. Each kind of device implemented by the module is referred to as a type :

Each of the scull devices demonstrates different features of a driver and presents different difficulties. This chapter covers the internals of scull0 to skull3; the more advanced devices are covered in Chapter 5, "Enhanced Char Driver Operations": scullpipe is described in "A Sample Implementation: scullpipe" and the others in "Access Control on a Device File".

 crw-rw-rw- 1 root   root    1, 3   Feb 23 1999  null
 crw------- 1 root   root   10, 1   Feb 23 1999  psaux
 crw------- 1 rubini tty     4, 1   Aug 16 22:22 tty1
 crw-rw-rw- 1 root   dialout 4, 64  Jun 30 11:19 ttyS0
 crw-rw-rw- 1 root   dialout 4, 65  Aug 16 00:00 ttyS1
 crw------- 1 root   sys     7, 1   Feb 23 1999  vcs1
 crw------- 1 root   sys     7, 129 Feb 23 1999  vcsa1
 crw-rw-rw- 1 root   root    1, 5   Feb 23 1999  zero

The major number identifies the driver associated with the device. For example, /dev/null and /dev/zero are both managed by driver 1, whereas virtual consoles and serial terminals are managed by driver 4; similarly, both vcs1 and vcsa1 devices are managed by driver 7. The kernel uses the major number at open time to dispatch execution to the appropriate driver.

 int register_chrdev(unsigned int major, const char *name,
      struct file_operations *fops);

The major number is a small integer that serves as the index into a static array of char drivers; "Dynamic Allocation of Major Numbers" later in this chapter explains how to select a major number. The 2.0 kernel supported 128 devices; 2.2 and 2.4 increased that number to 256 (while reserving the values 0 and 255 for future uses). Minor numbers, too, are eight-bit quantities; they aren't passed to register_chrdev because, as stated, they are only used by the driver itself. There is tremendous pressure from the developer community to increase the number of possible devices supported by the kernel; increasing device numbers to at least 16 bits is a stated goal for the 2.5 development series.

 mknod /dev/scull0 c 254 0

creates a char device (c) whose major number is 254 and whose minor number is 0. Minor numbers should be in the range 0 to 255 because, for historical reasons, they are sometimes stored in a single byte. There are sound reasons to extend the range of available minor numbers, but for the time being, the eight-bit limit is still in force.

Please note that once created by mknod, the special device file remains unless it is explicitly deleted, like any information stored on disk. You may want to remove the device created in this example by issuing rm /dev/scull0.

Dynamic Allocation of Major Numbers

For private drivers, we strongly suggest that you use dynamic allocation to obtain your major device number, rather than choosing a number randomly from the ones that are currently free. If, on the other hand, your driver is meant to be useful to the community at large and be included into the official kernel tree, you'll need to apply to be assigned a major number for exclusive use.

A typical /proc/devices file looks like the following:

Character devices:
 1 mem
 2 pty
 3 ttyp
 4 ttyS
 6 lp
 7 vcs
 10 misc
 13 input
 14 sound
 21 sg
180 usb

Block devices:
 2 fd
 8 sd
 11 sr
 65 sd
 66 sd

The following script, scull_load, is part of the scull distribution. The user of a driver that is distributed in the form of a module can invoke such a script from the system's rc.local file or call it manually whenever the module is needed.

 
#!/bin/sh
module="scull"
device="scull"
mode="664"

# invoke insmod with all arguments we were passed
# and use a pathname, as newer modutils don't look in . by default
/sbin/insmod -f ./$module.o $* || exit 1

# remove stale nodes
rm -f /dev/${device}[0-3]

major=`awk "\\$2==\"$module\" {print \\$1}" /proc/devices`

mknod /dev/${device}0 c $major 0
mknod /dev/${device}1 c $major 1
mknod /dev/${device}2 c $major 2
mknod /dev/${device}3 c $major 3

# give appropriate group/permissions, and change the group.
# Not all distributions have staff; some have "wheel" instead.
group="staff"
grep '^staff:' /etc/group > /dev/null || group="wheel"

chgrp $group /dev/${device}[0-3]
chmod $mode /dev/${device}[0-3]

The script can be adapted for another driver by redefining the variables and adjusting the mknodlines. The script just shown creates four devices because four is the default in the scull sources.

The best way to assign major numbers, in our opinion, is by defaulting to dynamic allocation while leaving yourself the option of specifying the major number at load time, or even at compile time. The code we suggest using is similar to the code introduced for autodetection of port numbers. The scull implementation uses a global variable, scull_major, to hold the chosen number. The variable is initialized to SCULL_MAJOR, defined in scull.h. The default value of SCULL_MAJOR in the distributed source is 0, which means "use dynamic assignment." The user can accept the default or choose a particular major number, either by modifying the macro before compiling or by specifying a value for scull_major on the insmod command line. Finally, by using the scull_load script, the user can pass arguments to insmod on scull_load 's command line.[16]

Here's the code we use in scull 's source to get a major number:

 
 result = register_chrdev(scull_major, "scull", &scull_fops);
 if (result < 0) {
  printk(KERN_WARNING "scull: can't get major %d\n",scull_major);
  return result;
 }
 if (scull_major == 0) scull_major = result; /* dynamic */

Removing a Driver from the System

 int unregister_chrdev(unsigned int major, const char *name);

The arguments are the major number being released and the name of the associated device. The kernel compares the name to the registered name for that number, if any: if they differ, -EINVAL is returned. The kernel also returns -EINVAL if the major number is out of the allowed range.

When you unload the driver without unregistering the major number, recovery will be difficult because the strcmpfunction in unregister_chrdev must dereference a pointer (name) to the original module. If you ever fail to unregister a major number, you must reload both the same module and another one built on purpose to unregister the major. The faulty module will, with luck, get the same address, and the name string will be in the same place, if you didn't change the code. The safer alternative, of course, is to reboot the system.

dev_t and kdev_t

The following macros and functions are the operations you can perform on kdev_t:

The file_operations structure has been slowly getting bigger as new functionality is added to the kernel. The addition of new operations can, of course, create portability problems for device drivers. Instantiations of the structure in each driver used to be declared using standard C syntax, and new operations were normally added to the end of the structure; a simple recompilation of the drivers would place a NULL value for that operation, thus selecting the default behavior, usually what you wanted.

The following list introduces all the operations that an application can invoke on a device. We've tried to keep the list brief so it can be used as a reference, merely summarizing each operation and the default kernel behavior when a NULL pointer is used. You can skip over this list on your first reading and return to it later.

The rest of the chapter, after describing another important data structure (the file, which actually includes a pointer to its own file_operations), explains the role of the most important operations and offers hints, caveats, and real code examples. We defer discussion of the more complex operations to later chapters because we aren't ready to dig into topics like memory management, blocking operations, and asynchronous notification quite yet.

The following list shows what operations appear in struct file_operations for the 2.4 series of kernels, in the order in which they appear. Although there are minor differences between 2.4 and earlier kernels, they will be dealt with later in this chapter, so we are just sticking to 2.4 for a while. The return value of each operation is 0 for success or a negative error code to signal an error, unless otherwise noted.

 
struct file_operations scull_fops = {
 llseek:  scull_llseek,
 read:  scull_read,
 write:  scull_write,
 ioctl:  scull_ioctl,
 open:  scull_open,
 release: scull_release,
};

This declaration uses the tagged structure initialization syntax, as we described earlier. This syntax is preferred because it makes drivers more portable across changes in the definitions of the structures, and arguably makes the code more compact and readable. Tagged initialization allows the reordering of structure members; in some cases, substantial performance improvements have been realized by placing frequently accessed members in the same hardware cache line.

It is also necessary to set the owner field of the file_operations structure. In some kernel code, you will often see owner initialized with the rest of the structure, using the tagged syntax as follows:

 owner: THIS_MODULE,

 
 SET_MODULE_OWNER(&scull_fops);

The most important fields of struct file are shown here. As in the previous section, the list can be skipped on a first reading. In the next section though, when we face some real C code, we'll discuss some of the fields, so they are here for you to refer to.

The real structure has a few more fields, but they aren't useful to device drivers. We can safely ignore those fields because drivers never fill file structures; they only access structures created elsewhere.

The open Method

In most drivers, open should perform the following tasks:

• Increment the usage count

• Check for device-specific errors (such as device-not-ready or similar hardware problems)

• Initialize the device, if it is being opened for the first time

• Identify the minor number and update the f_op pointer, if necessary

• Allocate and fill any data structure to be put in filp->private_data

 
#define TYPE(dev) (MINOR(dev) >> 4) /* high nibble */
#define NUM(dev) (MINOR(dev) & 0xf) /* low nibble */

 
struct file_operations *scull_fop_array[]={
 &scull_fops,  /* type 0 */
 &scull_priv_fops, /* type 1 */
 &scull_pipe_fops, /* type 2 */
 &scull_sngl_fops, /* type 3 */
 &scull_user_fops, /* type 4 */
 &scull_wusr_fops /* type 5 */
};
#define SCULL_MAX_TYPE 5

/* In scull_open, the fop_array is used according to TYPE(dev) */
 int type = TYPE(inode->i_rdev);

  if (type > SCULL_MAX_TYPE) return -ENODEV;
  filp->f_op = scull_fop_array[type];

The kernel invokes open according to the major number; scull uses the minor number in the macros just shown. TYPE is used to index into scull_fop_array in order to extract the right set of methods for the device type being opened.

The actual code for scull_open follows. It uses the TYPE and NUM macros defined in the previous code snapshot to split the minor number:

 
int scull_open(struct inode *inode, struct file *filp)
{
 Scull_Dev *dev; /* device information */
 int num = NUM(inode->i_rdev);
 int type = TYPE(inode->i_rdev);

 /*
  * If private data is not valid, we are not using devfs
  * so use the type (from minor nr.) to select a new f_op
  */
 if (!filp->private_data && type) {
  if (type > SCULL_MAX_TYPE) return -ENODEV;
  filp->f_op = scull_fop_array[type];
  return filp->f_op->open(inode, filp); /* dispatch to specific open */
 }

 /* type 0, check the device number (unless private_data valid) */
 dev = (Scull_Dev *)filp->private_data;
 if (!dev) {
  if (num >= scull_nr_devs) return -ENODEV;
  dev = &scull_devices[num];
  filp->private_data = dev; /* for other methods */
 }

 MOD_INC_USE_COUNT; /* Before we maybe sleep */
 /* now trim to 0 the length of the device if open was write-only */
 if ( (filp->f_flags & O_ACCMODE) == O_WRONLY) {
  if (down_interruptible(&dev->sem)) {
   MOD_DEC_USE_COUNT;
   return -ERESTARTSYS;
  }
  scull_trim(dev); /* ignore errors */
  up(&dev->sem);
 }

 return 0;   /* success */
}

A few explanations are due here. The data structure used to hold the region of memory is Scull_Dev, which will be introduced shortly. The global variables scull_nr_devs and scull_devices[] (all lowercase) are the number of available devices and the actual array of pointers to Scull_Dev.

The calls to down_interruptible and up can be ignored for now; we will get to them shortly.

The code looks pretty sparse because it doesn't do any particular device handling when open is called. It doesn't need to, because the scull0-3 device is global and persistent by design. Specifically, there's no action like "initializing the device on first open" because we don't keep an open count for sculls, just the module usage count.

The release Method

• Deallocate anything that open allocated in filp->private_data

• Shut down the device on last close

• Decrement the usage count

The basic form of scull has no hardware to shut down, so the code required is minimal:[20]

 
int scull_release(struct inode *inode, struct file *filp)
{
 MOD_DEC_USE_COUNT;
 return 0;
}

It is important to decrement the usage count if you incremented it at open time, because the kernel will never be able to unload the module if the counter doesn't drop to zero.

How can the counter remain consistent if sometimes a file is closed without having been opened? After all, the dupand fork system calls will create copies of open files without calling open; each of those copies is then closed at program termination. For example, most programs don't open their stdin file (or device), but all of them end up closing it.

The answer is simple: not every close system call causes the release method to be invoked. Only the ones that actually release the device data structure invoke the method -- hence its name. The kernel keeps a counter of how many times a file structure is being used. Neither fork nor dup creates a new file structure (only open does that); they just increment the counter in the existing structure.

The close system call executes the release method only when the counter for the file structure drops to zero, which happens when the structure is destroyed. This relationship between the release method and the closesystem call guarantees that the usage count for modules is always consistent.

As you may imagine, the previous discussion applies even when the application terminates without explicitly closing its open files: the kernel automatically closes any file at process exit time by internally using the close system call.

This section deals only with the memory allocation policy in scull and doesn't show the hardware management skills you'll need to write real drivers. Those skills are introduced in Chapter 8, "Hardware Management", and in Chapter 9, "Interrupt Handling". Therefore, you can skip this section if you're not interested in understanding the inner workings of the memory-oriented scull driver.

The region of memory used by scull, also called a device here, is variable in length. The more you write, the more it grows; trimming is performed by overwriting the device with a shorter file.

The chosen numbers are such that writing a single byte in scull consumes eight or twelve thousand bytes of memory: four thousand for the quantum and four or eight thousand for the quantum set (according to whether a pointer is represented in 32 bits or 64 bits on the target platform). If, instead, you write a huge amount of data, the overhead of the linked list is not too bad. There is only one list element for every four megabytes of data, and the maximum size of the device is limited by the computer's memory size.

Choosing the appropriate values for the quantum and the quantum set is a question of policy, rather than mechanism, and the optimal sizes depend on how the device is used. Thus, the scull driver should not force the use of any particular values for the quantum and quantum set sizes. In scull, the user can change the values in charge in several ways: by changing the macros SCULL_QUANTUM and SCULL_QSET in scull.h at compile time, by setting the integer values scull_quantum and scull_qset at module load time, or by changing both the current and default values using ioctl at runtime.

Using a macro and an integer value to allow both compile-time and load-time configuration is reminiscent of how the major number is selected. We use this technique for whatever value in the driver is arbitrary, or related to policy.

The only question left is how the default numbers have been chosen. In this particular case, the problem is finding the best balance between the waste of memory resulting from half-filled quanta and quantum sets and the overhead of allocation, deallocation, and pointer chaining that occurs if quanta and sets are small.

Additionally, the internal design of kmallocshould be taken into account. We won't touch the point now, though; the innards of kmalloc are explored in "The Real Story of kmalloc" in Chapter 7, "Getting Hold of Memory".

The choice of default numbers comes from the assumption that massive amounts of data are likely to be written to scull while testing it, although normal use of the device will most likely transfer just a few kilobytes of data.

The data structure used to hold device information is as follows:

 
typedef struct Scull_Dev {
 void **data;
 struct Scull_Dev *next; /* next list item */
 int quantum;    /* the current quantum size */
 int qset;     /* the current array size */
 unsigned long size;
 devfs_handle_t handle; /* only used if devfs is there */
 unsigned int access_key; /* used by sculluid and scullpriv */
 struct semaphore sem;  /* mutual exclusion semaphore  */
} Scull_Dev;

 
int scull_trim(Scull_Dev *dev)
{
 Scull_Dev *next, *dptr;
 int qset = dev->qset; /* "dev" is not null */
 int i;

 for (dptr = dev; dptr; dptr = next) { /* all the list items */
  if (dptr->data) {
   for (i = 0; i < qset; i++)
    if (dptr->data[i])
     kfree(dptr->data[i]);
   kfree(dptr->data);
   dptr->data=NULL;
  }
  next=dptr->next;
  if (dptr != dev) kfree(dptr); /* all of them but the first */
 }
 dev->size = 0;
 dev->quantum = scull_quantum;
 dev->qset = scull_qset;
 dev->next = NULL;
 return 0;
}

The result is trouble. Because both processes see the same scull device, each will store its new memory in the same place in the quantum set. If A stores its pointer first, B will overwrite that pointer when it does its store. Thus the memory allocated by A, and the data written therein, will be lost.

This situation is a classic race condition; the results vary depending on who gets there first, and usually something undesirable happens in any case. On uniprocessor Linux systems, the scull code would not have this sort of problem, because processes running kernel code are not preempted. On SMP systems, however, life is more complicated. Processes A and B could easily be running on different processors and could interfere with each other in this manner.

The Linux kernel provides several mechanisms for avoiding and managing race conditions. A full description of these mechanisms will have to wait until Chapter 9, "Interrupt Handling", but a beginning discussion is appropriate here.

 
 for (i=0; i < scull_nr_devs; i++) {
  scull_devices[i].quantum = scull_quantum;
  scull_devices[i].qset = scull_qset;
  sema_init(&scull_devices[i].sem, 1);
 }

 if (down_interruptible (&sem))
	return -ERESTARTSYS;

The -ERESTARTSYS return value tells the system that the operation was interrupted by a signal. The kernel function that called the device method will either retry it or return -EINTR to the application, according to how signal handling has been configured by the application. Of course, your code may have to perform cleanup work before returning if interrupted in this mode.

 up (&sem);

will increment the value of the semaphore and wake up any processes that are waiting for the semaphore to become available.

In scull, the per-device semaphore is used to protect access to the stored data. Any code that accesses the data field of the Scull_Dev structure must first have obtained the semaphore. To avoid deadlocks, only functions that implement device methods will try to obtain the semaphore. Internal routines, such as scull_trimshown earlier, assume that the semaphore has already been obtained. As long as these invariants hold, access to the Scull_Dev data structure is safe from race conditions.

The read and write methods perform a similar task, that is, copying data from and to application code. Therefore, their prototypes are pretty similar and it's worth introducing them at the same time:

 ssize_t read(struct file *filp, char *buff,
     size_t count, loff_t *offp);
 ssize_t write(struct file *filp, const char *buff,
     size_t count, loff_t *offp);

As far as data transfer is concerned, the main issue associated with the two device methods is the need to transfer data between the kernel address space and the user address space. The operation cannot be carried out through pointers in the usual way, or through memcpy. User-space addresses cannot be used directly in kernel space, for a number of reasons.

One big difference between kernel-space addresses and user-space addresses is that memory in user-space can be swapped out. When the kernel accesses a user-space pointer, the associated page may not be present in memory, and a page fault is generated. The functions we introduce in this section and in "Using the ioctl Argument" in Chapter 5, "Enhanced Char Driver Operations" use some hidden magic to deal with page faults in the proper way even when the CPU is executing in kernel space.

Also, it's interesting to note that the x86 port of Linux 2.0 used a completely different memory map for user space and kernel space. Thus, user-space pointers couldn't be dereferenced at all from kernel space.

If the target device is an expansion board instead of RAM, the same problem arises, because the driver must nonetheless copy data between user buffers and kernel space (and possibly between kernel space and I/O memory).

 unsigned long copy_to_user(void *to, const void *from, 
        unsigned long count);
 unsigned long copy_from_user(void *to, const void *from, 
        unsigned long count);

Although these functions behave like normal memcpy functions, a little extra care must be used when accessing user space from kernel code. The user pages being addressed might not be currently present in memory, and the page-fault handler can put the process to sleep while the page is being transferred into place. This happens, for example, when the page must be retrieved from swap space. The net result for the driver writer is that any function that accesses user space must be reentrant and must be able to execute concurrently with other driver functions (see also "Writing Reentrant Code" in Chapter 5, "Enhanced Char Driver Operations"). That's why we use semaphores to control concurrent access.

The role of the two functions is not limited to copying data to and from user-space: they also check whether the user space pointer is valid. If the pointer is invalid, no copy is performed; if an invalid address is encountered during the copy, on the other hand, only part of the data is copied. In both cases, the return value is the amount of memory still to be copied. The scull code looks for this error return, and returns -EFAULT to the user if it's not 0.

As far as the actual device methods are concerned, the task of the read method is to copy data from the device to user space (using copy_to_user), while the writemethod must copy data from user space to the device (using copy_from_user). Each reador write system call requests transfer of a specific number of bytes, but the driver is free to transfer less data -- the exact rules are slightly different for reading and writing and are described later in this chapter.

The read Method

What is missing from the preceding list is the case of "there is no data, but it may arrive later." In this case, the read system call should block. We won't deal with blocking input until "Blocking I/O" in Chapter 5, "Enhanced Char Driver Operations".

The scull code takes advantage of these rules. In particular, it takes advantage of the partial-read rule. Each invocation of scull_read deals only with a single data quantum, without implementing a loop to gather all the data; this makes the code shorter and easier to read. If the reading program really wants more data, it reiterates the call. If the standard I/O library (i.e., fread and friends) is used to read the device, the application won't even notice the quantization of the data transfer.

If the current read position is greater than the device size, the read method of scullreturns 0 to signal that there's no data available (in other words, we're at end-of-file). This situation can happen if process A is reading the device while process B opens it for writing, thus truncating the device to a length of zero. Process A suddenly finds itself past end-of-file, and the next read call returns 0.

 
ssize_t scull_read(struct file *filp, char *buf, size_t count,
    loff_t *f_pos)
{
 Scull_Dev *dev = filp->private_data; /* the first list item */
 Scull_Dev *dptr;
 int quantum = dev->quantum;
 int qset = dev->qset;
 int itemsize = quantum * qset; /* how many bytes in the list item */
 int item, s_pos, q_pos, rest;
 ssize_t ret = 0;

 if (down_interruptible(&dev->sem))
   return -ERESTARTSYS;
 if (*f_pos >= dev->size)
  goto out;
 if (*f_pos + count > dev->size)
  count = dev->size - *f_pos;
 /* find list item, qset index, and offset in the quantum */
 item = (long)*f_pos / itemsize;
 rest = (long)*f_pos % itemsize;
 s_pos = rest / quantum; q_pos = rest % quantum;

 /* follow the list up to the right position (defined elsewhere) */
 dptr = scull_follow(dev, item);

 if (!dptr->data)
  goto out; /* don't fill holes */
 if (!dptr->data[s_pos])
  goto out;
 /* read only up to the end of this quantum */
 if (count > quantum - q_pos)
  count = quantum - q_pos;

 if (copy_to_user(buf, dptr->data[s_pos]+q_pos, count)) {
  ret = -EFAULT;
	goto out;
 }
 *f_pos += count;
 ret = count;

 out:
 up(&dev->sem);
 return ret;
}

The write Method

• If the value equals count, the requested number of bytes has been transferred.

• If the value is positive, but smaller than count, only part of the data has been transferred. The program will most likely retry writing the rest of the data.

• If the value is 0, nothing was written. This result is not an error, and there is no reason to return an error code. Once again, the standard library retries the call to write. We'll examine the exact meaning of this case in "Blocking I/O" in Chapter 5, "Enhanced Char Driver Operations", where blocking write is introduced.

• A negative value means an error occurred; like for read, valid error values are those defined in <linux/errno.h>.

Unfortunately, there may be misbehaving programs that issue an error message and abort when a partial transfer is performed. This happens because some programmers are accustomed to seeing write calls that either fail or succeed completely, which is actually what happens most of the time and should be supported by devices as well. This limitation in the scull implementation could be fixed, but we didn't want to complicate the code more than necessary.

 
ssize_t scull_write(struct file *filp, const char *buf, size_t count,
    loff_t *f_pos)
{
 Scull_Dev *dev = filp->private_data;
 Scull_Dev *dptr;
 int quantum = dev->quantum;
 int qset = dev->qset;
 int itemsize = quantum * qset;
 int item, s_pos, q_pos, rest;
 ssize_t ret = -ENOMEM; /* value used in "goto out" statements */

 if (down_interruptible(&dev->sem))
   return -ERESTARTSYS;

 /* find list item, qset index and offset in the quantum */
 item = (long)*f_pos / itemsize;
 rest = (long)*f_pos % itemsize;
 s_pos = rest / quantum; q_pos = rest % quantum;

 /* follow the list up to the right position */
 dptr = scull_follow(dev, item);
 if (!dptr->data) {
  dptr->data = kmalloc(qset * sizeof(char *), GFP_KERNEL);
  if (!dptr->data)
   goto out;
  memset(dptr->data, 0, qset * sizeof(char *));
 }
 if (!dptr->data[s_pos]) {
  dptr->data[s_pos] = kmalloc(quantum, GFP_KERNEL);
  if (!dptr->data[s_pos])
   goto out;
 }
 /* write only up to the end of this quantum */
 if (count > quantum - q_pos)
  count = quantum - q_pos;

 if (copy_from_user(dptr->data[s_pos]+q_pos, buf, count)) {
  ret = -EFAULT;
	goto out;
 }
 *f_pos += count;
 ret = count;

 /* update the size */
 if (dev->size < *f_pos)
  dev-> size = *f_pos;

 out:
 up(&dev->sem);
 return ret;
}

readv and writev

Until version 2.3.44 of the kernel, however, Linux always emulated readv and writev with multiple calls to read and write. If your driver does not supply methods to handle the vector operations, they will still be implemented that way. In many situations, however, greater efficiency is achieved by implementing readv and writev directly in the driver.

The prototypes for the vector operations are as follows:

 ssize_t (*readv) (struct file *filp, const struct iovec *iov, 
      unsigned long count, loff_t *ppos);
 ssize_t (*writev) (struct file *filp, const struct iovec *iov, 
      unsigned long count, loff_t *ppos);

 struct iovec
 {
  void *iov_base;
  _ _kernel_size_t iov_len;
 };

Each iovec describes one chunk of data to be transferred; it starts at iov_base (in user space) and is iov_len bytes long. The count parameter to the method tells how many iovec structures there are. These structures are created by the application, but the kernel copies them into kernel space before calling the driver.

The simplest implementation of the vectored operations would be a simple loop that just passes the address and length out of each iovec to the driver's read or write function. Often, however, efficient and correct behavior requires that the driver do something smarter. For example, a writev on a tape drive should write the contents of all the iovec structures as a single record on the tape.

• Device entry points in /dev are created at device initialization and removed at device removal.

• The device driver can specify device names, ownership, and permission bits, but user-space programs can still change ownership and permission (but not the filename).

• There is no need to allocate a major number for the device driver and deal with minor numbers.

As a result, there is no need to run a script to create device special files when a module is loaded or unloaded, because the driver is autonomous in managing its own special files.

#include <linux/devfs_fs_kernel.h>

devfs_handle_t devfs_mk_dir (devfs_handle_t dir,
  const char *name, void *info);

devfs_handle_t devfs_register (devfs_handle_t dir,
  const char *name, unsigned int flags,
  unsigned int major, unsigned int minor,
  umode_t mode, void *ops, void *info);

  void devfs_unregister (devfs_handle_t de);

The devfs implementation offers several other functions for kernel code to use. They allow creation of symbolic links, access to the internal data structures to retrieve devfs_handle_t items from inodes, and other tasks. Those other functions are not covered here because they are not very important or easily understood. The curious reader could look at the header file for further information.

The various arguments to the register/unregister functions are as follows:

dir

The parent directory where the new special file should be created. Most drivers will use NULL to create special files in /dev directly. To create an owned directory, a driver should call devfs_mk_dir.

name

The name of the device, without the leading /dev/. The name can include slashes if you want the device to be in a subdirectory; the subdirectory is created during the registration process. Alternatively, you can specify a valid dir pointer to the hosting subdirectory.

flags

A bit mask of devfsflags. DEVFS_FL_DEFAULT can be a good choice, and DEVFS_FL_AUTO_DEVNUM is the flag you need for automatic assignment of major and minor numbers. The actual flags are described later.

major

minor

The major and minor numbers for the device. Unused if DEVFS_FL_AUTO_DEVNUM is specified in the flags.

mode

Access mode of the new device.

ops

A pointer to the file operation structure for the device.

info

A default value for filp->private_data. The filesystem will initialize the pointer to this value when the device is opened. The info pointer passed to devfs_mk_dir is not used by devfs and acts as a "client data" pointer.

de

A "devfs entry" obtained by a previous call to devfs_register.

int devfs_get_flags (devfs_handle_t de, unsigned int *flags);
int devfs_set_flags (devfs_handle_t de, unsigned int flags);

Using devfs in Practice

The code needed to implement a device driver that only runs with devfs installed is a subset of the code you need to support both environments, so we only show the dual-mode initialization. Instead of writing a specific sample driver to try out devfs, we added devfs support to the scull driver. If you load scull to a kernel that uses devfs, you'll need to directly invoke insmod instead of running the scull_load script.

We chose to create a directory to host all scull special files because the structure of devfs is highly hierarchical and there's no reason not to adhere to this convention. Moreover, we can thus show how a directory is created and removed.

 
 /* If we have devfs, create /dev/scull to put files in there */
 scull_devfs_dir = devfs_mk_dir(NULL, "scull", NULL);
 if (!scull_devfs_dir) return -EBUSY; /* problem */

 for (i=0; i < scull_nr_devs; i++) {
  sprintf(devname, "%i", i);
  devfs_register(scull_devfs_dir, devname,
      DEVFS_FL_AUTO_DEVNUM,
      0, 0, S_IFCHR | S_IRUGO | S_IWUGO,
      &scull_fops,
      scull_devices+i);
 }

The previous code is paired by the two lines that are part of the following excerpt from scull_cleanup:

 
 if (scull_devices) {
  for (i=0; i<scull_nr_devs; i++) {
   scull_trim(scull_devices+i);
   /* the following line is only used for devfs */
   devfs_unregister(scull_devices[i].handle);
  }
  kfree(scull_devices);
 }

 /* once again, only for devfs */
 devfs_unregister(scull_devfs_dir);

Part of the previous code fragments is protected by #ifdef CONFIG_DEVFS_FS. If the feature is not enabled in the current kernel, scull will revert to register_chrdev.

 
 /*
  * If private data is not valid, we are not using devfs
  * so use the type (from minor nr.) to select a new f_op
  */
 if (!filp->private_data && type) {
  if (type > SCULL_MAX_TYPE) return -ENODEV;
  filp->f_op = scull_fop_array[type];
  return filp->f_op->open(inode, filp); /* dispatch to specific open */
 }

 /* type 0, check the device number (unless private_data valid) */
 dev = (Scull_Dev *)filp->private_data;
 if (!dev) {
  if (num >= scull_nr_devs) return -ENODEV;
  dev = &scull_devices[num];
  filp->private_data = dev; /* for other methods */
 }

Once equipped with the code shown, the scull module can be loaded to a system running devfs. It will show the following lines as output of ls -l /dev/scull:

crw-rw-rw- 1 root  root  144,  1 Jan 1 1970 0
crw-rw-rw- 1 root  root  144,  2 Jan 1 1970 1
crw-rw-rw- 1 root  root  144,  3 Jan 1 1970 2
crw-rw-rw- 1 root  root  144,  4 Jan 1 1970 3
crw-rw-rw- 1 root  root  144,  5 Jan 1 1970 pipe0
crw-rw-rw- 1 root  root  144,  6 Jan 1 1970 pipe1
crw-rw-rw- 1 root  root  144,  7 Jan 1 1970 pipe2
crw-rw-rw- 1 root  root  144,  8 Jan 1 1970 pipe3
crw-rw-rw- 1 root  root  144, 12 Jan 1 1970 priv
crw-rw-rw- 1 root  root  144,  9 Jan 1 1970 single
crw-rw-rw- 1 root  root  144, 10 Jan 1 1970 user
crw-rw-rw- 1 root  root  144, 11 Jan 1 1970 wuser

The functionality of the various files is the same as that of the "normal" scull module, the only difference being in device pathnames: what used to be /dev/scull0 is now /dev/scull/0.

Portability Issues and devfs

If your code is meant to only be used with version 2.4 of the kernel, you can avoid conditional compilation by calling kernel functions to initialize the driver in both ways; things are arranged so that one of the initializations will do nothing at all, while returning success. The following is an example of what initialization might look like:

 #include <devfs_fs_kernel.h>

 int init_module()
 {
  /* request a major: does nothing if devfs is used */
  result = devfs_register_chrdev(major, "name", &fops);
  if (result < 0) return result;

  /* register using devfs: does nothing if not in use */
  devfs_register(NULL, "name", /* .... */ );
  return 0;
 }

This is, for example, how scull.h avoids conditional compilation in the cleanup part of the program. This code is portable to all kernel versions because it doesn't depend on devfs being known to the header files:

 
#ifdef CONFIG_DEVFS_FS /* only if enabled, to avoid errors in 2.0 */
#include <linux/devfs_fs_kernel.h>
#else
 typedef void * devfs_handle_t; /* avoid #ifdef inside the structure */
#endif

The end result is that the prototypes of the commonly used file_operations methods looked like this in 2.0:

There have been many other changes to the file_operations structure; we will cover them in the following chapters as we get to them. Meanwhile, it is worth a moment to look at how portable code can be written that accounts for the changes we have seen so far. The changes in these methods are large, and there is no simple, elegant way to cover them over.

 
/*
 * The following wrappers are meant to make things work with 2.0 kernels
 */
#ifdef LINUX_20
int scull_lseek_20(struct inode *ino, struct file *f,
    off_t offset, int whence)
{
 return (int)scull_llseek(f, offset, whence);
}

int scull_read_20(struct inode *ino, struct file *f, char *buf, 
   int count)
{
 return (int)scull_read(f, buf, count, &f->f_pos);
}

int scull_write_20(struct inode *ino, struct file *f, const char *b, 
   int c)
{
 return (int)scull_write(f, b, c, &f->f_pos);
}

void scull_release_20(struct inode *ino, struct file *f)
{
 scull_release(ino, f);
}

/* Redefine "real" names to the 2.0 ones */
#define scull_llseek scull_lseek_20
#define scull_read scull_read_20
#define scull_write scull_write_20
#define scull_release scull_release_20
#define llseek lseek
#endif /* LINUX_20 */

Redefining names in this manner can also account for structure members whose names have changed over time (such as the change from lseek to llseek).

Needless to say, this sort of redefinition of the names should be done with care; these lines should appear before the definition of the file_operations structure, but after any other use of those names.

 
#ifdef LINUX_20
# define INODE_FROM_F(filp) ((filp)->f_inode)
#else
# define INODE_FROM_F(filp) ((filp)->f_dentry->d_inode)
#endif

The Module Usage Count

Changes in Semaphore Support

 
#ifdef LINUX_20
# ifdef MUTEX_LOCKED /* Only if semaphore.h included */
  extern inline void sema_init (struct semaphore *sem, int val)
  {
   sem->count = val;
   sem->waking = sem->lock = 0;
   sem->wait = NULL;
  }
# endif
#endif /* LINUX_20 */

Changes in Access to User Space

 void memcpy_fromfs(void *to, const void *from, unsigned long count);
 void memcpy_tofs(void *to, const void *from, unsigned long count);