Linux USB Driver Basics
Introduction
Drivers are software components that operating systems use to provide hardware specific services to applications. This webpage attempts to document the basics of USB drivers on Linux. The goal here is to provide you with a basic understanding of how USB device drivers on Linux work.
The File Abstraction
Linux, like other Unix derived operating systems, tries to make applications simpler by providing a common hardware abstraction, the File. Essentially, interactions with almost all hardware can be abstracted into the same interface that the operating system provides for manipulating files. Hence, you can "Open" a driver, "Read" a driver, "Write" to a driver and "Close" a driver. This abstraction extends all the way into the application, who can use the same system calls that it uses to open and manipulate files to talk to hardware.
The way this works is that the kernel creates nodes in the file system, typically located in /dev that represent a particular interface to a driver. To talk to a particular driver an application will open the /dev entry associated with that driver. The file descriptor returned by that open is passed to all future system calls (read, write, select), and is eventually passed to close.
Besides drivers, Unix also uses this file paradigm for various different kinds of IPC, and even for socket communications over a network.
It is quite surprising how many completely different kinds of hardware can be modeled with just 4 operations (open, close, read and write). That said, their is another very important system call that unix applications developers commonly use, select(). The select() system call allows applications to poll and determine whether data could be read from, or written to a file descriptor without blocking.
Sometimes a piece of hardware provides some functionality that doesn't fit well into this file centric paradigm. To allow for this, unix applications typically make use of the ioctl() system call. This call takes a numeric value that is essentially an identifier for a specific piece of functionality in the driver.
The Job of the Device Driver
Simply stated, it is the job of the driver to provide functions that the kernel can use to implement this file programming paradigm. Applications do not directly call functions in the driver, instead they call functions in libc that eventually call into the kernel (via the system call interface). The kernel implementations of these system calls call into your driver.
As you might expect, this means that you're going to be implementating open, close, read and write inside your driver. To implement select(), the kernel needs you to implement a method in your driver called poll(). Other than these, their are only a handfull of other functions that need to be implemented, and you have a driver!
Loading a Driver
Linux supports essentially two kinds of driver development models: 1) Compiled into the kernel, 2) Dynamically loadable driver modules. If configured properly, option 2 has the advantage that drivers can be loaded automatically by the kernel only when they are actually needed to service an application request. Option 1 presents a logically cleaner, and slightly faster scenario.
The choice is up to you. That said, we will now cover the basics of loading and unloading a kernel module into a running kernel.
First, understand that a Linux kernel driver cannot be dynamically linked against any librarys (not even libc, which many programmers dont even know they are linking against). The only code external to your driver that your allowed to make use of are functions that are implemented within the kernel. In fact, kernel modules are never "Linked", instead they are relocatable object files, .o's or sometimes .ko's.
The following command is used to install a driver into a running kernel:
[td@objective ~]$ insmod driver.ko
The following command is used to show what drivers are currently loaded into the kernel:
[td@objective ~]$ lsmod
Module Size Used by
md5 4033 1
ipv6 263105 22
ipt_REJECT 5441 1
ipt_state 1857 5
ip_conntrack 41369 1 ipt_state
iptable_filter 2881 1
ip_tables 19521 3 ipt_REJECT,ipt_state,iptable_filter
video 15685 0
button 4033 0
battery 9285 0
ac 4805 0
uhci_hcd 35025 0
ehci_hcd 40013 0
hw_random 5973 0
i2c_i801 8653 0
i2c_core 21313 1 i2c_i801
snd_intel8x0 34177 0
snd_ac97_codec 74937 1 snd_intel8x0
snd_pcm_oss 50673 0
snd_mixer_oss 17729 1 snd_pcm_oss
snd_pcm 98889 3 snd_intel8x0,snd_ac97_codec
snd_timer 32837 1 snd_pcm
snd 57285 6 snd_intel8x0,snd_ac97_codec
soundcore 10785 1 snd
snd_page_alloc 9669 2 snd_intel8x0,snd_pcm
e1000 102573 0
dm_snapshot 17413 0
dm_zero 2113 0
dm_mirror 25645 0
ext3 130633 2
jbd 83161 1 ext3
dm_mod 57333 6 dm_snapshot,dm_zero,dm_mirror
ata_piix 9413 0
libata 46917 1 ata_piix
sd_mod 20289 0
scsi_mod 146313 2 libata,sd_mod
The following command is used to remove a driver from a running kernel:
[td@objective ~]$ rmmod driver.ko
Since you never link your driver, you will not know about unresolved symbols until you actually load your driver into the kernel. It is during the "insmod" process that the kernel binds all of the calls to kernel functions in your code to their actual current locations in memory. This process is called "resolving symbol dependancies".
Understanding the Universal Serial Bus
From the highest level
As I'm sure you know from your own use of USB, the USB bus, besides offering communications also offers power to devices connected to it. The USB can offer up to 500mA for the devices connected to it. Devices that need more than this can be self powered.
Besides this, your probably aware of the fact that the USB can be expanded with hubs.
How hardware is about to make your life easier
Thankfully, your driver will not have to communicate directly on the Universal Serial Bus. Instead, your driver will communicate to the USB host controller, which will communicate on the bus on your behalf. The USB host controller is a piece of hardware that acts as a focal point for all of the CPU's interaction with the USB hardware. It hides most of the complexity of dealing with USB and also protects the USB hardware from potentially badly written driver software that might otherwise affect the whole bus.
Their are two kinds of host controller hardware commonly in use, UHCI (Universal Host Controller Interface) and OHCI (Open Host Controller Interface). The good news is that both of these host controllers present the same interface to your driver, so you really dont have to care about what kind of host controller hardware is present. As you might expect, UHCI & OHCI hardware has its own driver, that thankfully you will not need to touch. It will be the job of your driver to communicate (indirectly) with the host controller driver, to configure, read from or write to devices on the USB.
Types of Communications on the USB
USB devices have the full range of different speed, latency and reliability requirements. Things like mice and keyboard transfer only small amounts of data, relatively rarely, but they care a lot about latency. No one like a slow keyboard.
On the other hand, USB webcams often transfer compressed MPEG video, which is extremely high bandwidth, but because MPEG was designed to be transmitted over lossy communications channels, it is OK if the occasional packet is lost.
To support these differing requirements, USB supports a number of communications types.
-
Control Transfers - Control transfers are used when you need reliable (the data MUST get their) communications and you are sending a very small amount of data. Essentially, these transfers are commands, and their are a few commands that every device is required to support (GET_STATUS, CLEAR_FEATURE, SET_FEATURE, SET_ADDRESS, GET_DESCRIPTOR, SET_DESCRIPTOR, GET_CONFIGURATION, SET_CONFIGURATION, GET_INTERFACE, SET_INTERFACE, SYNCH_FRAME).
-
Bulk Transfers - Bulk transfers are used when you need reliable (the data MUST get their) communications and you are sending large amounts of data.
-
Interrupt Transfers - Interrupt transfers are simmilar to bulk transfers except they are configured to occur automatically at some interval. These types of transfers are useful for devices that stream constant data of the USB.
-
Isochronous Transfers - Isochronous transfers are very fast, and have guaranteed bus bandwidth, but they have no reliability. This transfer type seems to have been designed with MPEG in mind.
The code that you write is going to have to specify to the host controller what types of communcations you want to use. Thankfully, an extremely wide range of device types fit nicely into the above types of data transfers.
The heirarchical view of the USB
If you think about what I have described so far, it should be fairly apparent that since you will be dealing only indirectly with actual USB devices and instead be communicating through a host controller, that host controller must have some kind of data model for the devices that are connected to it on the USB bus. It must present some description of the devices connected, and their capabilities.
The capabilites of a USB device are modeled heirarchically by the host controller. Your driver will communicate to a USB device by making requests to nodes of this heirarchy. To fully understand the reasoning for all of the layers of the heirarchy I am about to tell you about please consider how generic a host controller must be, given how wide ranging the functionality of USB hardware can be.
When a USB is first plugged into the bus it is detected by the host controller. The host controller sends it the GET_DESCRIPTOR command and retrieves what is called the device descriptor. This structure is itself of a heirarchical nature and describes the features and capabilities of a particular device.
This "Device Descriptor" has 1 or more "Configuration Descriptors", which in turn has 1 or more "Interfaces", which in turn has 0 to N "Endpoints". I know this is a lot to swallow, but its the genericness and flexibility of this structure that lets USB work for so many different types of devices.
Remember, we're talking about 1 USB device here. Every device you have connected to your bus has a structure like this. Simple devices may not have multiple configurations or interfaces. Almost all devices will have at least 1 endpoint however, which means they will also have at least 1 interface and 1 configuration. The reason for this is that the endpoint is typically the part of this tree that the application interacts with.
The Importance of Endpoints
Endpoints are logically the parts of this tree that you write to or read from. If your goal is to read the mpeg coming out of a USB webcam, then you will be reading that data from an Endpoint. We talked a little about communications types above (remember Control, Bulk, Interrupt and Isochronous?) but a key to understanding USB is to understand that Endpoints support a particular type of communication. If you need to do bulk transfers to your device you'll need to find an endpoint on your device that supports bulk transfers. If you dont find it, then your out of luck. You cannot create endpoints, what you find represents the capabilities that this particular USB hardware is presenting to the host controller on your machine.
Endpoints can also be used as a secondary form of device identification. We will discuss the primary form of device identification employed shortly, but for now consider that you could identify a device by the presence of a particular heirarchy of configurations, interfaces and endpoints. In fact, the presence of the right number and types of nodes in this heirarchy is arguably the most important thing you care about. If a device identifies itself to you as being of a particular kind, that does you no good if the hardware doesn't support the endpoints you expect.
Coding details
USB Identification
All USB devices have two very important numbers that serve as our primary form of device identification. These numbers are the devices Vendor ID and Product ID. The idea is that if a company would mark all of the USB devices it creates with an id that identifies the company, it should be really easy to determine if a particular device was made by your company. Because a company might create many different kinds of USB devices, their is a second number, the Product ID. This number can be used to identify a particular product.
When a device is plugged into the USB bus, the kernel query's the installed drivers to find out which supports this particular piece of hardware. Essentially, the kernel calls a method in your driver called "probe". This function is passed the vendor and product id's, as well as a structure used to check for the availability of particular nodes in the devices USB heirarchy. If everything checks out, your driver should eventually call usb_register_dev() to let the kernel know that you do indeed handle this particular piece of hardware.
How it all begins
Now that you know some of the basic fundamentals, it's time we discuss some of the details in a little more depth. The first driver code that gets called by the kernel is your module init routine. Likewise, when your driver is unloaded (via rmmod), the last function that is called is your modules exit routine. It is the job of your init function to register a struct with the kernel called 'usb_driver'. This struct has information like your drivers name, (indirectly through another structure) the vendor and product id's of the usb hardware your driver services, and a pointer to a couple of functions called probe and disconnect (which we'll talk about shortly).
#define USB_VENDOR_ID 0x22FF
#define USB_PRODUCT_ID_1 0x1111
#define USB_PRODUCT_ID_2 0x2222
static struct usb_device_id generic_usb_id_table [] =
{
{
USB_DEVICE(USB_VENDOR_ID,USB_PRODUCT_ID_1)
},
{
USB_DEVICE(USB_VENDOR_ID,USB_PRODUCT_ID_2)
}
{
}
};
MODULE_DEVICE_TABLE (usb, generic_usb_id_table);
static struct usb_driver generic_usb_driver =
{
.owner = THIS_MODULE,
.name = "generic_usb_driver",
.id_table = generic_usb_id_table,
.probe = generic_usb_probe,
.disconnect = generic_usb_disconnect
};
static int __init generic_usb_driver_init( void )
{
return usb_register( &generic_usb_driver );
}
static void __exit generic_usb_driver_exit( void )
{
usb_deregister( &generic_usb_driver )
}
module_init (generic_usb_driver_init);
module_exit (generic_usb_driver_exit);
Their is a bit of macro magic here at the end, but the basic idea is pretty simple. We fill out a structure and we implement some standard entry points that register and unregister that structure. What we have done at this point is told the kernel what vendor and product id's we handle, and what functions it should call when devices that match those id's are added or removed from the USB bus.
Getting Probed by the kernel
When a device is plugged into the USB bus, the USB host controller hardware generates an interrupt that wakes up the host controller driver. Eventually, the kernel finds the usb driver associated with the vendor and product id of the new device. It then calls that drivers probe method. When a device is removed, that also generates an interrupt and eventually, a call to your drivers disconnect function.
The drivers probe method is very important. First, consider that most USB drivers dont really run all the time. They are called by the kernel when they have work to do (such as reading and writing). Since it is usually possible for more than 1 kind of the same USB device to be plugged in, drivers cannot use global data to store information about their state. Instead they must declare some type of structure, which they allocate and populate an instance of when they are probe()'d by the kernel and they determine that they really do handle the hardware in question. Theirfore, it is the job of your probe function to examine the passed usb_interface structure to make sure it has all of the endpoints you need to function. Once that determination has been made you should kmalloc() your instance data structure, populate it (perhaps storing endpoint addresses or pre-allocating URB's) and return it by calling usb_set_intfdata() on the passed interface object. This instance data is passed back to you when the kernel calls into your driver from then on.
Another critical thing you have to do in your probe function is call usb_register_dev, passing a pointer to an instance of a usb_class_driver struct. This struct (the second structure down) is populated with a number of important fields.
static struct file_operations generic_fops =
{
.owner = THIS_MODULE,
.read = generic_read,
.write = generic_write,
.poll = generic_poll,
.ioctl = generic_ioctl
};
static struct usb_class_driver generic_class =
{
.name = "generic_%d",
.fops = &generic_fops,
.mode = S_IFCHR | S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH,
.minor_base = 42
};
The first structure above contains pointers to all of the functions used to support the file paradigm for this driver (read, write, poll and ioctl). The second structure contains a pointer to the first structure. It also contains a field that is used by the kernel when it creates your device nodes under /dev. The .name field of the usb_class_driver structure is used as a format string, combined with a number, to uniquely identify all of the devices on the USB bus that are serviced by your particular driver.
write
static ssize_t generic_write( struct file* file,
const char __user* user_buffer,
size_t count,
loff_t* ppos );
Probably the first thing you'll want to do in your write function is access the instance data for this device that you allocated in probe(). You do this by looking at the "private_data" field of the struct file* passed to the function.
Basically, an URB is the unit of communication on the USB bus. Writing or reading from a device on the USB consists of creating and submitting properly constructed URBs. Given that, the next thing you need to do is call usb_alloc_urb() to create the urb for this write operation. Next, you need to create a kernel memory buffer, attach it to the URB, copy the write data from user space into your kernel buffer, finalize the initialization of the URB and finally call usb_submit_urb() to send it.
char* buf = NULL;
struct urb* urb = usb_alloc_urb( 0, GFP_KERNEL );
buf = usb_buffer_alloc( dev->udev, count, GFP_KERNEL, &urb->transfer_dma );
if( buf )
{
copy_from_user( buf, user_buffer, count );
usb_fill_bulk_urb( urb, dev->udev,
usb_sndbulkpipe(dev->udev,dev->bulk_out_endpointAddr),
buf,
count,
generic_write_bulk_callback,
dev );
usb_submit_urb( urb, GFP_KERNEL );
usb_free_urb( urb );
}
Not the best code in the world, but shows you the steps of what your going to have to do.
read
Read is a lot simpler than write. Again, the first thing you'll probably want to do is get your instance data from the private_data field of the passed file* structure. Once thats done, you can get to the fun stuff:
usb_bulk_msg( dev->udev,
usb_recvbulkpipe( dev->udev, dev->bulk_in_endpointAddr),
dev->bulk_in_buffer,
min(dev->bulk_in_size,count),
&count, HZ*2 );
copy_to_user( buffer, dev->bulk_in_buffer, count );
The heart of your read() implementation may be as simple as this.
ioctl
ioctl is the back door. Essentially, ioctl exists because sometimes not every piece of hardware can operate exactly like a file in all cases. Sometimes, you just need to request a specific piece of functionality be performed on your behalf in the driver. You'd also like to be able to pass parameters to such a function, and be returned some kind of indication of the success of such a call.
static int generic_reader_ioctl( struct inode* inode,
struct file* file,
unsigned in cmd,
unsigned long arg )
{
struct usb_generic_instance_data* dev =
(struct usb_generic_instance_data*)file->private_data;
switch( cmd )
{
case GET_STATE:
return dev->global_state;
break;
default:
break;
}
return -1;
}
The above is a complete ioctl() function that implements a single logical function, GET_STATE. Any number of additional function can be added here simply by adding cases to the switch statement.
exit(0);
This article is a bit longer than I had hoped it would be. The goal was a short introduction that would give you a place to start in your understanding of the Linux USB drivers. I hope I have done at least that much!
