Linux Character Device Driver Notes

The following is meant to be a set of notes for writing a device driver and is not intended to be a tutorial or handbook. I recommend the following sources as better references for device driver writing: Claus Schroeter's character device driver white paper, his PCI programming white paper, and his driver development kit whitepaper (ftp:ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers), Micheal Johnson's device driver whitepaper, Micheal Battersby's notes on device driver writing, David Rusling's book The Linux Kernel, and the Linux Kernel Hacker's Guide. Of course, the best reference of all is the source code for a device driver similar to the one you're trying to write.

I will concentrate on modular device drivers rather than those which are compiled into the kernel.

Introduction

Driver provides low level functions and access to the hardware without (necessarily) requiring root privileges.
Access is through file system (i.e., /dev/xxx files)
Driver types:

1.
Character - Sequential access (read/write one byte at a time in linear order)

2.
Block - Random access
Devices have MAJOR and MINOR numbers (see <linux/major.h>)
- The MAJOR number corresponds to the actual device used
- The MINOR number corresponds to multiple similar devices run by the same driver
- Create the character device in the file system using:
```
mknod /dev/filename b MAJOR MINOR
```

Inside the Kernel

The kernel is non-preemptive. Kernel functions do not get context switched.
None of the libc functions are available, but some are duplicated, such as the str* and mem* functions.

VFS File Operations

Devices ``export'' their functionality to the virtual filesystem by registering a file_operations structure with the kernel (see <linux/fs.h>):

struct file_operations {
  int (*lseek) (struct inode *, struct file *, off_t, int);
  int (*read) (struct inode *, struct file *, char *, int);
  int (*write) (struct inode *, struct file *, const char *, int);
  int (*readdir) (struct inode *, struct file *, void *, filldir_t);
  int (*select) (struct inode *, struct file *, int, select_table *);
  int (*ioctl) (struct inode *, struct file *, unsigned int, unsigned long);
  int (*mmap) (struct inode *, struct file *, struct vm_area_struct *);
  int (*open) (struct inode *, struct file *);
  void (*release) (struct inode *, struct file *);
  int (*fsync) (struct inode *, struct file *);
  int (*fasync) (struct inode *, struct file *, int);
  int (*check_media_change) (kdev_t dev);
  int (*revalidate) (kdev_t dev);
};

check_media_change() and revalidate() are really device operations, not file operations, and are rarely used.
When the device is opened, the open() function is called. Similarly, when it is closed, the release() function is called.
lseek() seeks to some point within the device space. For example, if a memory window is allocated during the call to open(), the default position can be set from user space using lseek(fd,position,whence), where whence is either 0 (file start), 1 (current position), or 2 (file end).
read() and write() read/write from/to the device at the current position.
ioctl() is a general purpose front-end for a variety of device-specific services.
mmap() is used to map regions in the user virtual memory space to device/physical memory space.
select() is used to determine whether the device is ready for access. See the select(2) man page.
The inode and file structures figure prominently in the driver as they contain information about the open device
- inode->i_rdev is the device number of the open device; use MAJOR(inode->i_rdev) and MINOR(inode->i_rdev) to get the major and minor numbers
- file->private_data can be used to store driver specific data

Working with memory

To allocate small amount of memory (< 4096 bytes) in the kernel, use the following set of functions:

#include <linux/malloc.h>
void *kmalloc(int size, int priority);
void  kfree_s(void *obj, int size);
void  kfree(void *obj);

To allocate larger amounts of (virtual) memory, such as device buffers, use:
```
#include <linux/mm.h>
void *vmalloc(long size);
void  vfree(void *obj);
```
the priority is either GFP_KERNEL for normal cases, or GFP_ATOMIC for allocating memory inside interrupts
To access a specific location in physical memory, use:
```
#include <linux/mm.h>
void * vremap(unsigned long offset, unsigned long size);
```
where offset is the location in physical memory. Note that the address returned is different from the hardware address.
To map a memory location in user space to a physical address (in a mmap() call to your device, use:
```
#include <linux/mm.h>
int remap_page_range(unsigned long from, unsigned long to, 
                     unsigned long size, pgprot_t prot);
```
where from is a pointer to the region to be mapped, to is the physical memory location, and prot is the set of memory protection flags applied to the region (i.e., PROT_READ, PROT_WRITE, etc.)
To verify that use space memory (passed to your kernel functions) is valid, use:
```
#include <linux/mm.h>
int verify_area(int type, void * area, unsigned long size);
```
where type is either VERIFY_READ if the kernel is to read from the buffer, or VERIFY_WRITE if the kernel is to write to the buffer.

To move data between user (fs) and kernel memory space (which are at different memory segments), use:

#include <asm/segment.h>
inline unsigned char get_fs_byte(const char * addr);
inline unsigned char get_fs_word(const unsigned short * addr);
inline unsigned char get_fs_long(const unsigned long * addr);

inline void put_fs_byte(char val, char * addr);
inline void put_fs_word(short val, short * addr);
inline void put_fs_long(long val, long * addr);

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

Working with I/O ports

Call check_region() before probing for your hardware.
Once you have found your hardware, register it with request_region().
If you unload the driver, use release_region() to free ports.
The following macros are available to write to/read from I/O ports:
```
#include <asm/io.h>
char  inb(int port); 
short inw(int port);
void  outb(char  val, int port);
void  outw(short val, int port);
```
Alternative versions of these macros, identified by a ``_p'' suffix, perform a short (~ 1 usec) pause after the I/O access. This is sometimes necessary because the CPU can execute I/O instructions faster than the device/bus can keep up.
From user space, permission must be given to the user process to access I/O ports:
- For ports 0x000 to 0x3ff, use ioperm() to gain access to the desired range of ports.
- For ports higher than 0x3ff, use iopl() to gain access to all ports at once.
- Use of either of these functions requires root privileges.

Working with PCI devices

The hardware addresses of PCI devices are not known prior to booting. Rather, the PCI BIOS interrogates each device on the bus for its requirements and allocates resources at boot time.
A list of devices found and the allocated resources can be found in /proc/pci.
A list of PCI devices recognized by the kernel and general defines can be found in <linux/pci.h>

The Linux PCI-BIOS support is built atop the Bios32 routines and defines some useful routines for reading the PCI configuration block for each device on the bus

Check if PCI-BIOS support is enabled in the kernel using pcibios_present().

Get the configuration block for the desired device using:

int pcibios_find_device (unsigned short vendor, unsigned short dev_id,
                         unsigned short index, unsigned char *bus,
                         unsigned char *dev_fn);

Get the desired parameters from the configuration block using:

#include <linux/bios32.h>
int pcibios_read_config_byte (unsigned char bus, unsigned char dev_fn,
                              unsigned char where, unsigned char *val);
int pcibios_read_config_word (unsigned char bus, unsigned char dev_fn,
                              unsigned char where, unsigned short *val);
int pcibios_read_config_dword (unsigned char bus, unsigned char dev_fn,
                               unsigned char where, unsigned int *val);

Set the desired parameters in the configuration block using:

#include <linux/bios32.h>
int pcibios_write_config_byte (unsigned char bus, unsigned char dev_fn,
                               unsigned char where, unsigned char val);
int pcibios_write_config_word (unsigned char bus, unsigned char dev_fn,
                               unsigned char where, unsigned short val);
int pcibios_write_config_dword (unsigned char bus, unsigned char dev_fn,
                                unsigned char where, unsigned int val);

Addresses read from the configuration block contain information in the lower bits which indicate what type of address is given (i.e., memory or I/O). Mask these bits out using the macros PCI_BASE_ADDRESS_MEM_MASK or PCI_BASE_ADDRESS_IO_MASK.

Debugging and Messages

Use printk() to print messages to a log file, typically /var/log/messages
For more immediate gratification, sprintf() your message to a string and send that string to console_print(), which displays your message on the console.

Kernel Modules

The following includes must be part of the driver source:
```
#include <linux/module.h>
#include <linux/version.h>
```
Define the file_operations structure to include the desired member functions.
The init_module() call initializes the device, determining, checking, and reserving the address ranges used by the device, and registering the character driver with the kernel through a call to register_chrdev().
cleanup_module() is called when the device is to be removed from the kernel. It frees up allocated memory, releases the allocated ranges in I/O address space, and unregisters the device via a call to unregister_chrdev()
Do MOD_INC_USE_COUNT on each open().
Do MOD_DEC_USE_COUNT on each release().
To install a device driver foo.o: insmod foo.o
To remove a device driver foo.o: rmmod foo.o
To list the modules in use: lsmod

General Coding Practices

Use static wherever possible for functions and global variables.
Use inline functions instead of macros.
Always initialize static variables.
Name member functions of the file_operations structure following the convention foo_read(), etc. if the driver name is ``foo.''
Compile with the following flags: -Wall -O2 -DMODULE -D__KERNEL__

About this document ...

This document was generated using the LaTeX2HTML translator Version 97.1 (release) (July 13th, 1997)

The command line arguments were:
latex2html -split 0 -no_math -no_images -no_navigation ddrive.tex.

The translation was initiated by Nick Maliszewskyj on 8/27/1997

Nick Maliszewskyj
8/27/1997