Writing Portable Device Drivers

Follow the kernel team's rules to make your drivers work on all architectures.
I/O Memory Access

Unlike on most typical embedded systems, accessing I/O memory on Linux cannot be done directly. This is due to the wide range of different memory types and maps present on the wide range of processors on which Linux runs. To access I/O memory in a portable manner, you must call ioremap() to gain access to a memory region and iounmap() to release access.

ioremap() is defined as:

void * ioremap (unsigned long offset,
    unsigned long size);

You pass in a starting offset of the region you wish to access and the size of the region in bytes. You cannot just use the return value as a memory location to read and write from directly, but rather it is a token that must be passed to different functions to read and write data.

The functions to read and write data using memory mapped by ioremap() are:

u8  readb (unsigned long token);    /* read 8 bits */
u16 readw (unsigned long token);    /* read 16 bits */
u32 readl (unsigned long token);    /* read 32 bits */
void writeb (u8 value,
    unsigned long token);   /* write 8 bits */
void writew (u16 value,
    unsigned long token);   /* write 16 bits */
void writel (u32 value,
    unsigned long token);   /* write 32 bits */

After you are finished accessing memory, you must call iounmap() to free up the memory so that others can use it if they want to.

The code example in Listing 4 from the Compaq PCI Hot Plug driver in drivers/hotplug/cpqphp_core.c shows how to access a PCI device's resource memory properly.

Listing 4. Accessing a PCI Device's Resource Memory

Accessing PCI Memory

To access the PCI memory of a device, you again must use some general functions and not try to access the memory directly. This is due to the different ways the PCI bus can be accessed, depending on the type of hardware you have. If you use the general functions, then your PCI driver will be able to work on any type of Linux system that has a PCI bus.

To read data from the PCI bus use the following functions:

int pci_read_config_byte(struct pci_dev *dev,
    int where, u8 *val);
int pci_read_config_word(struct pci_dev *dev,
    int where, u16 *val);
int pci_read_config_dword(struct pci_dev *dev,
    int where, u32 *val);

and to write data, use these functions:

int pci_write_config_byte(struct pci_dev *dev,
    int where, u8 val);
int pci_write_config_word(struct pci_dev *dev,
    int where, u16 val);
int pci_write_config_dword(struct pci_dev *dev,
    int where, u32 val);

Where are the pci_read_config_* and pci_write_config_* functions actually declared?

These functions allow you to write 8, 16 or 32 bits to a specific location that is assigned to a specific PCI device. If you wish to access the memory location of a specific PCI device that has not been initialized by the Linux PCI core yet, you can use the following functions that are present in the pci_hotplug core code:

int pci_read_config_byte_nodev(struct pci_ops *ops,
    u8 bus, u8 device, u8 function, int where, u8 *val);
int pci_read_config_word_nodev(struct pci_ops *ops,
    u8 bus, u8 device, u8 function, int where, u16 *val);
int pci_read_config_dword_nodev(struct pci_ops *ops,
    u8 bus, u8 device, u8 function, int where, u32 *val);
int pci_write_config_byte_nodev(struct pci_ops *ops,
    u8 bus, u8 device, u8 function, int where, u8 val);
int pci_write_config_word_nodev(struct pci_ops *ops,
    u8 bus, u8 device, u8 function, int where, u16 val);
int pci_write_config_dword_nodev(struct pci_ops *ops,
    u8 bus, u8 device, u8 function, int where, u32 val);

An example of reading and writing to PCI memory by a driver can be seen in the USB OHCI driver at drivers/usb/usb-ohci.c (see Listing 5).

Listing 5. Reading and Writing to PCI Memory

Conclusion

If you follow these different rules when creating a new Linux kernel device driver, or when modifying an existing one, the resulting code will run successfully on a wide range of processors. These rules are also good to remember when debugging a driver that only works on one platform (remember those endian issues).

The most important resource to remember is to look at existing kernel drivers that are known to work on different platforms. One of Linux's strengths is the open access of its code, which provides a powerful learning tool for aspiring driver authors.

Greg Kroah-Hartman is currently the Linux USB and PCI Hot Plug kernel maintainer. He works for IBM, doing various Linux kernel-related things and can be reached at greg@kroah.com.

______________________

Comments

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

re: interact wit pci using linux

sup's picture

hi,
i work on linux ver 2.2, i would like to interact with the pci bus and pci devices what apis and structures should i use and in which header file should i include for its proper functioning.

thanks and regards,

sup

Why all the kernel drivers

Don's picture

This is a fine article on kernel drivers, but why write all these things as kernel drivers? The I2C interface (and the USB interface) both provide for access to devices from user-space. For many devices, this is all that is needed. Yes for file systems and network, etc. a kernel driver is needed, but why clutter up the kernel for every gadget that comes along?

It's a must read document

Bhupesh's picture

It's a must read document for beginners :)

Re: Writing Portable Device Drivers

Anonymous's picture

It's really a helpful article !

Re: Writing Portable Device Drivers

Anonymous's picture

Its a good artical for newbies entering into driver deveopment.
The artical is very cear and understanding.

subash

Re: Writing Portable Device Drivers

Anonymous's picture

this is a good article specific to writing efficient and portable Linux device driver. It has cleared some of my confusion as well as raised a few.

I appreciate it.

nikhil bhargava

Hi,i wrote a device driver

anonymous's picture

Hi,

i wrote a device driver for USB for FC6. after writing the code and compiling it, how could i make it start when the usb is plugged in? should i also use insmod and rmmod?

thanks

White Paper
Linux Management with Red Hat Satellite: Measuring Business Impact and ROI

Linux has become a key foundation for supporting today's rapidly growing IT environments. Linux is being used to deploy business applications and databases, trading on its reputation as a low-cost operating environment. For many IT organizations, Linux is a mainstay for deploying Web servers and has evolved from handling basic file, print, and utility workloads to running mission-critical applications and databases, physically, virtually, and in the cloud. As Linux grows in importance in terms of value to the business, managing Linux environments to high standards of service quality — availability, security, and performance — becomes an essential requirement for business success.

Learn More

Sponsored by Red Hat

White Paper
Private PaaS for the Agile Enterprise

If you already use virtualized infrastructure, you are well on your way to leveraging the power of the cloud. Virtualization offers the promise of limitless resources, but how do you manage that scalability when your DevOps team doesn’t scale? In today’s hypercompetitive markets, fast results can make a difference between leading the pack vs. obsolescence. Organizations need more benefits from cloud computing than just raw resources. They need agility, flexibility, convenience, ROI, and control.

Stackato private Platform-as-a-Service technology from ActiveState extends your private cloud infrastructure by creating a private PaaS to provide on-demand availability, flexibility, control, and ultimately, faster time-to-market for your enterprise.

Learn More

Sponsored by ActiveState