The complete “memory” driver

The complete driver “memory”: initial part of the driver

I’ll now show how to build a complete device driver: memory.c. This device will allow a character to be read from or written into it. This device, while normally not very useful, provides a very illustrative example since it is a complete driver; it's also easy to implement, since it doesn’t interface to a real hardware device (besides the computer itself).

To develop this driver, several new #include statements which appear frequently in device drivers need to be added:

<memory initial> =

/* Necessary includes for device drivers */

#include <linux/init.h>

#include <linux/config.h>

#include <linux/module.h>

#include <linux/kernel.h> /* printk() */

#include <linux/slab.h> /* kmalloc() */

#include <linux/fs.h> /* everything... */

#include <linux/errno.h> /* error codes */

#include <linux/types.h> /* size_t */

#include <linux/proc_fs.h>

#include <linux/fcntl.h> /* O_ACCMODE */

#include <asm/system.h> /* cli(), *_flags */

#include <asm/uaccess.h> /* copy_from/to_user */

MODULE_LICENSE("Dual BSD/GPL");

/* Declaration of memory.c functions */

int memory_open(struct inode *inode, struct file *filp);

int memory_release(struct inode *inode, struct file *filp);

ssize_t memory_read(struct file *filp, char *buf, size_t count, loff_t *f_pos);

ssize_t memory_write(struct file *filp, char *buf, size_t count, loff_t *f_pos);

void memory_exit(void);

int memory_init(void);

/* Structure that declares the usual file */

/* access functions */

struct file_operations memory_fops = {

  read: memory_read,

  write: memory_write,

  open: memory_open,

  release: memory_release

};

/* Declaration of the init and exit functions */

module_init(memory_init);

module_exit(memory_exit);

/* Global variables of the driver */

/* Major number */

int memory_major = 60;

/* Buffer to store data */

char *memory_buffer;

After the #include files, the functions that will be defined later are declared. The common functions which are typically used to manipulate files are declared in the definition of the file_operations structure. These will also be explained in detail later. Next, the initialization and exit functions—used when loading and removing the module—are declared to the kernel. Finally, the global variables of the driver are declared: one of them is the major number of the driver, the other is a pointer to a region in memory, memory_buffer, which will be used as storage for the driver data.

The “memory” driver: connection of the device with its files

In UNIX and Linux, devices are accessed from user space in exactly the same way as files are accessed. These device files are normally subdirectories of the /dev directory.

To link normal files with a kernel module two numbers are used: major number and minor number. The major number is the one the kernel uses to link a file with its driver. The minor number is for internal use of the device and for simplicity it won’t be covered in this article.

To achieve this, a file (which will be used to access the device driver) must be created, by typing the following command as root:

# mknod /dev/memory c 60 0

In the above, c means that a char device is to be created, 60 is the major number and 0 is the minor number.

Within the driver, in order to link it with its corresponding /dev file in kernel space, the register_chrdev function is used. It is called with three arguments: major number, a string of characters showing the module name, and a file_operations structure which links the call with the file functions it defines. It is invoked, when installing the module, in this way:

<memory init module> =

int memory_init(void) {

  int result;

  /* Registering device */

  result = register_chrdev(memory_major, "memory", &memory_fops);

  if (result < 0) {

    printk(

      "<1>memory: cannot obtain major number %d\n", memory_major);

    return result;

  }

  /* Allocating memory for the buffer */

  memory_buffer = kmalloc(1, GFP_KERNEL);

  if (!memory_buffer) {

    result = -ENOMEM;

    goto fail;

  }

  memset(memory_buffer, 0, 1);

  printk("<1>Inserting memory module\n");

  return 0;

  fail:

    memory_exit();

    return result;

}

Also, note the use of the kmalloc function. This function is used for memory allocation of the buffer in the device driver which resides in kernel space. Its use is very similar to the well known malloc function. Finally, if registering the major number or allocating the memory fails, the module acts accordingly.

The “memory” driver: removing the driver

In order to remove the module inside the memory_exit function, the function unregsiter_chrdev needs to be present. This will free the major number for the kernel.

<memory exit module> =

void memory_exit(void) {

  /* Freeing the major number */

  unregister_chrdev(memory_major, "memory");

  /* Freeing buffer memory */

  if (memory_buffer) {

    kfree(memory_buffer);

  }

  printk("<1>Removing memory module\n");

}

The buffer memory is also freed in this function, in order to leave a clean kernel when removing the device driver.

The “memory” driver: opening the device as a file

The kernel space function, which corresponds to opening a file in user space (fopen), is the member open: of the file_operations structure in the call to register_chrdev. In this case, it is the memory_open function. It takes as arguments: an inode structure, which sends information to the kernel regarding the major number and minor number; and a file structure with information relative to the different operations that can be performed on a file. Neither of these functions will be covered in depth within this article.

When a file is opened, it’s normally necessary to initialize driver variables or reset the device. In this simple example, though, these operations are not performed.

The memory_open function can be seen below:

<memory open> =

int memory_open(struct inode *inode, struct file *filp) {

  /* Success */

  return 0;

}

This new function is now shown in Table 5.

Events	User functions	Kernel functions
Load module	insmod	module_init()
Open device	fopen	file_operations: open
Read device
Write device
Close device
Remove module	rmmod	module_exit()

Table 5. Device driver events and their associated interfacing functions between kernel space and user space.

The “memory” driver: closing the device as a file

The corresponding function for closing a file in user space (fclose) is the release: member of the file_operations structure in the call to register_chrdev. In this particular case, it is the function memory_release, which has as arguments an inode structure and a file structure, just like before.

When a file is closed, it’s usually necessary to free the used memory and any variables related to the opening of the device. But, once again, due to the simplicity of this example, none of these operations are performed.

The memory_release function is shown below:

<memory release> =

int memory_release(struct inode *inode, struct file *filp) {

  /* Success */

  return 0;

}

This new function is shown in Table 6.

Events	User functions	Kernel functions
Load module	insmod	module_init()
Open device	fopen	file_operations: open
Read device
Write device
Close device	fclose	file_operations: release
Remove module	rmmod	module_exit()

Table 6. Device driver events and their associated interfacing functions between kernel space and user space.

The “memory” driver: reading the device

To read a device with the user function fread or similar, the member read: of the file_operations structure is used in the call to register_chrdev. This time, it is the function memory_read. Its arguments are: a type file structure; a buffer (buf), from which the user space function (fread) will read; a counter with the number of bytes to transfer (count), which has the same value as the usual counter in the user space function (fread); and finally, the position of where to start reading the file (f_pos).

In this simple case, the memory_read function transfers a single byte from the driver buffer (memory_buffer) to user space with the function copy_to_user:

<memory read> =

ssize_t memory_read(struct file *filp, char *buf,

                    size_t count, loff_t *f_pos) {

  /* Transfering data to user space */

  copy_to_user(buf,memory_buffer,1);

  /* Changing reading position as best suits */

  if (*f_pos == 0) {

    *f_pos+=1;

    return 1;

  } else {

    return 0;

  }

}

The reading position in the file (f_pos) is also changed. If the position is at the beginning of the file, it is increased by one and the number of bytes that have been properly read is given as a return value, 1. If not at the beginning of the file, an end of file (0) is returned since the file only stores one byte.

In Table 7 this new function has been added.

Events	User functions	Kernel functions
Load module	insmod	module_init()
Open device	fopen	file_operations: open
Read device	fread	file_operations: read
Write device
Close device	fclose	file_operations: release
Remove modules	rmmod	module_exit()

Table 7. Device driver events and their associated interfacing functions between kernel space and user space.

The “memory” driver: writing to a device

To write to a device with the user function fwrite or similar, the member write: of the file_operations structure is used in the call to register_chrdev. It is the function memory_write, in this particular example, which has the following as arguments: a type file structure; buf, a buffer in which the user space function (fwrite) will write; count, a counter with the number of bytes to transfer, which has the same values as the usual counter in the user space function (fwrite); and finally, f_pos, the position of where to start writing in the file.

<memory write> =

ssize_t memory_write( struct file *filp, char *buf,

                      size_t count, loff_t *f_pos) {

  char *tmp;

  tmp=buf+count-1;

  copy_from_user(memory_buffer,tmp,1);

  return 1;

}

In this case, the function copy_from_user transfers the data from user space to kernel space.

In Table 8 this new function is shown.

Events	User functions	Kernel functions
Load module	insmod	module_init()
Open device	fopen	file_operations: open
Close device	fread	file_operations: read
Write device	fwrite	file_operations: write
Close device	fclose	file_operations: release
Remove module	rmmod	module_exit()

Device driver events and their associated interfacing functions between kernel space and user space.

The complete “memory” driver

By joining all of the previously shown code, the complete driver is achieved:

<memory.c> =

<memory initial>

<memory init module>

<memory exit module>

<memory open>

<memory release>

<memory read>

<memory write>

Before this module can be used, you will need to compile it in the same way as with previous modules. The module can then be loaded with:

# insmod memory.ko

It’s also convenient to unprotect the device:

# chmod 666 /dev/memory

If everything went well, you will have a device /dev/memory to which you can write a string of characters and it will store the last one of them. You can perform the operation like this:

$ echo -n abcdef >/dev/memory

To check the content of the device you can use a simple cat:

$ cat /dev/memory

The stored character will not change until it is overwritten or the module is removed.