Writing a Real Driver&mdash;In User Space

Now you can control USB hardware without touching the kernel and even make your driver run on BSD-based OSes with no code changes. Greg shows a working example for using the cross-platform USB library, libusb.

Last time we discussed how to create a simple USB driver that
controlled a USB LED device manufactured by Delcom Engineering
[LJ, April 2004]. I would
like to thank all of the readers who have given me feedback on the column.
It even enabled one reader to write a driver now in the main
kernel tree. I also would like to thank everyone who has given me
ideas about what kinds of devices to write about in future columns, but
please remember, let's try to cover simple devices. We don't have the
room here to go over how to reverse engineer a streaming video camera
that has about 12 different modes of operation.

usbfs Overview

At the end of the last column, I said it is simple
to talk to a USB device from user space, without needing a custom kernel
driver. Way back during the development of the original Linux USB code,
a few developers recognized that it would be wise to allow user programs
to get at the raw USB data in all devices in addition to
controlling the device. To that end, the usbfs filesystem was created.
It originally was called usbdevfs, but many people confused
it with the devfs filesystem and all of the nasty baggage that filesystem
brought on, so it was renamed usbfs.

Traditionally, usbfs is mounted in the /proc/bus/usb directory on your
machine. In that main directory exists a file called devices
and a directory for every different USB bus connected to the
machine. Those bus directories are named with a number that corresponds
to the number the kernel has given that particular USB bus.
In each bus directory is a file for every different USB device
connected to the bus. For example, a box that has six different USB
buses and a few USB devices connected might look like this:

If you do not have any USB host controller drivers loaded,
the main /proc/bus/usb/ directory should be empty.

The /proc/bus/usb/devices file contains a list of all USB devices
attached at that moment in time. It also shows how the devices are
connected to one another and a lot of other USB-specific information
about each device. For details on how the data in this file should be
interpreted, see the documentation in the kernel tree
at Documentation/usb/proc_usb_info.txt. Programs such as usbview or
usbtree use this file to show information about USB devices.

usbfs Device Files

The files within the /proc/bus/usb/BBB/ directories, where BBB is the
number of the USB bus, allow programs to talk directly to the different USB
devices. The name of the files are the same number as the
USB number assigned to the device: 001 for the first device, 002 for
the second and so on. Do not rely on these numbers to be unique, as
the USB subsystem reuses the numbers when devices are removed and added.
If device 003 is removed and another, different device is added,
it gets the 003 number.

If you read from the device file, the raw USB descriptor is
returned—first the USB device descriptor and then the different configuration
descriptors. For a detailed description of what format these descriptors
are in and what all of the data means, see the USB specification,
which is available for download at the USB Developers Web site (www.usb.org/developers).

The device file also supports a wide range of ioctl calls that allows
programs to send and receive USB data from the device. These ioctls
and the structures needed for the ioctls are described in the
kernel file include/linux/usbdevice_fs.h.

Armed with these ioctls, the structures defined in this header file and
a copy of the USB specification, we are set to write a user-space program
to talk to our device. But do we really want to do this? Wouldn't it
be great if someone wrote a library on top of this interface that would
enable us to write sane programs? Luckily, a group of developers has
created such a library, allowing programmers to ignore the ioctl
mess that usbfs uses. This library is called libusb.

libusb

libusb is a library that works on a number of
different operating systems: Linux, the various
BSDs and Mac OS X. It allows programs to be written
in a portable manner and yet still control USB
devices on vastly different operating systems.
Using this library lets us create a program to
control the USB LED device. libusb can be downloaded
from libusb.sf.net if it is not included in
your Linux distribution.

The first thing any libusb program must do is initialize the library
and have it scan all USB buses for all USB devices. This is done with
the following three function calls:

usb_init(); usb_find_busses(); usb_find_devices();

After the call is complete, the program needs to find a USB device that
matches the desired description. As all USB devices have
unique vendor and product identification values, it usually is
easiest to look for these values. As we remember from the kernel driver we
created last time, the USB LED device has the following vendor and
product values:

#define LED_VENDOR_ID 0x0fc5
#define LED_PRODUCT_ID 0x1223

With this information, the code to find this device using libusb is
the following:

If the device is found in the system, a pointer to it is returned,
otherwise NULL is returned. This pointer is of type struct usb_device.
After this structure is found, the USB device must be opened and a
handle must be created by libusb for the program to
communicate with the device. This is done with the following simple code:

This usb_handle variable is of type struct usb_dev_handle, and it is what
libusb uses to determine with which USB device it should communicate.
This handle is all that is needed to set up
our USB device to be ready to communicate with it.

When the program is finished with the USB device, a
call to usb_close(usb_handle);
is all that is necessary to clean up all of our structures and notify
libusb that the device is no longer needed.

Changing Colors

Last time we set the color of the USB LED device
from within our kernel driver with the following
code:

libusb offers us an almost identical function call
to send control messages to a USB device. It also is
called usb_control_msg(), and to send the same
type of color message as we did from within the
kernel, our user-space program does it like this:

Listing 1 allows any
mixture of the three possible colors this device offers to be
set. Simply pass the colors as command-line arguments
to make changes:

To set the red led:
set_led red
To set the green and blue led:
set_led green blue
To turn off all leds:
set_led none

Conclusion

I hope that this example encourages you to
experiment with libusb as a simple alternative to
writing a kernel driver. USB devices almost
always can be controlled properly with user-space
programs instead of specialized kernel
drivers. User-space programs using libusb are much
easier to debug, do not require a special kernel
version to be used and work across a wide range of
operating systems.

Greg Kroah-Hartman currently is the Linux kernel maintainer for a
variety of different driver subsystems. He works
for IBM, doing Linux kernel-related things, and can
be reached at greg@kroah.com.

I've been trying to figure out how to do an isochronous read but I'm not having any luck. Could you please outline the sequence of steps to accomplish this. I'm using libusb_fill_iso_transfer () followed by libusb_submit_transfer () but this hangs up inside libusb. I'm suspicious that libusb is incomplete since I don't see any way of specifying the interval.
Also, I need to get at the manufacturers name string, but all I can find is an index (iManufacturer) in the device descriptor. There should be an access function.

So far I've been able to open this device, detach the kernel driver and claim the interface.

The device has a vendorId=18f5 and a productId=1000 (yes, it's in the Linux list). The device contains 2 joysticks and 16 switches (it's not a gaming device), I need to read the raw data so that I can extract the individual components. I have the memory map. Using usbviewer I found one endpoint at 0x81, the transfer size is 12 bytes and the interval is 5ms.
Hurst

Hello, it's a very nice posting and great help for newbie like me.
I'm trying to implement a usb driver that enables a programmer can write a program to communicate with a usb device. But your advice seems not working for me because our device has API that communicate with the device and I just want the api can initialize the device and programmers don't have to care about it.
Could you give me any advice on that?

Also, I'm confused about the header file you included in the program. It has usb.h instead of libusb.h. is it something different from the libusb.h or you just wrote another header that refers libusb.h?

Thanks for the great article. It's been a big help in writing a program to talk to a little communications board that I'm working with.

I have a question about the usb_control_msg() function, and I can't find any documentation on it (no man page, even on the Google?).

What are requesttype, request, value, and index for, exactly? Your program has requesttype 0x000000c8 (not sure where this is defined/how you chose it), request 0x00000012 (again, not sure how you decided this was the option to use), value (0x02 * 0x100) + 0x0a, index 0xff & (~color). It seems a little odd to me, wouldn't the request type/etc simply be part of the usb packet header and the data would be which pins you're setting? Probably my device is a little more complicated :).

I've been using SnoopyPro to sniff my device (i have a program for windows that interfaces with it correctly) and all the communication with the device is using Function "BULK_OR_INTERRUPT_TRANSFER" (0x09), so I'm guessing this would be my request_type? or my request? My device receives data via the buffer variable, so buffer and length are a no brainer (I know what these values need to be), I'm just not sure about these header-y things. If you have any idea or know a good place for documentation, toss it my way.

Hi,
I wanted to write just a simple driver for my usb-mass-storage (memory stick).
All I want to do is to flash (On/Off) the led on the device. It is only one led, I changed the LED_VENDOR_ID and LED_PRODUCT_ID Everything works fine, except that this usb_control_msg() doesnt work for this device :(!
Can someone help me with this? All I want is to switch this Led On and Off! Nothing more :).
Do I have to use another function? Is there a function that can manage to do this(put this only Led on)?
I hope u can help me with this.

And you don't use usb_claim_interface() anywhere. The doc's say this "Must be called!" I'm not entirely sure what an interface is yet though. libusb has terrible documentation. It is also the best example of why C++ is better than C that I've ever seen.

I just want to ask for some links to more information about USB in general, how to implement USB in Self build devices,
An overview, how USB (and pehaps also the serial and parallel interface) are implemented in Gnu/Linux and also BSD-Unix.

I'm an Engineer and it was easy to send some bytes to a device in the Dos Area - continued in Win9x. How can I do it - as easy as possible in Linux, especialy if new computers only have USB - this is the Future if we believe Intel

Trending Topics

Upcoming Webinar

Getting Started with DevOps - Including New Data on IT Performance from Puppet Labs 2015 State of DevOps Report

August 27, 2015
12:00 PM CDT

DevOps represents a profound change from the way most IT departments have traditionally worked: from siloed teams and high-anxiety releases to everyone collaborating on uneventful and more frequent releases of higher-quality code. It doesn't matter how large or small an organization is, or even whether it's historically slow moving or risk averse — there are ways to adopt DevOps sanely, and get measurable results in just weeks.