Do not need to write a USB driver? Writing a real driver-in user space

Http://www.linuxjournal.com/article/7466

June 1st, 2004 by Greg kroah-Harman
In

• Software

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
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
, Using L 2004]. I wowould
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 wowould like to thank everyone who has given me
Ideas about what kinds of devices to write about in future columns,
Please remember, let's try to cover simple devices. We don't have
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 wocould be wise to allow user programs
To get at the raw USB data in all devices in addition
Controlling the device. To that end, the usbfs filesystem was created.
It originally was called usbdevfs, but cannot 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
Machine. Those bus directories are named with a number that corresponds
To the number the kernel has given that pays 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:

$ tree /proc/bus/usb/
/proc/bus/usb/
|-- 001
|   `-- 001
|-- 002
|   `-- 001
|-- 003
|   `-- 001
|-- 004
|   |-- 001
|   |-- 002
|   `-- 003
|-- 005
|   `-- 001
|-- 006
|   `-- 001
`-- devices

If you do not have any USB Host Controller drivers loaded,
The main/proc/bus/USB/directory shocould 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 shocould be
Interpreted, see the documentation in the kernel tree
At documentation/USB/proc_usb_info.txt. programs such as usbview or
USB tree use this file to show information about USB devices.

Usbfs Device Files

The files within the/proc/bus/USB/BBB/directories, where BBB is
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
USB number assigned to the device: 001 for the first device, 002
The second and so on. Do not rely on these numbers to be unique,
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 cils that allows
Programs to send and receive USB data from the device. These IOCTLs
And the structures needed for The IOCTLs are described in
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 wowould
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
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
Control the USB led device. libusb can be downloaded
From libusb.sf.net
If it is not supported ded in
Your Linux distribution.

The first thing any libusb program must do is initialize the library
And have it scan all USB buckets for all USB devices. This is done
The following three function cballs:

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_ID0x0fc5
#define LED_PRODUCT_ID  0x1223

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

for (usb_bus = usb_busses; usb_bus;
     usb_bus = usb_bus->next) {
        for (dev = usb_bus->devices; dev;
             dev = dev->next) {
            if ((dev->descriptor.idVendor ==
                 LED_VENDOR_ID) &&
                (dev->descriptor.idProduct ==
                 LED_PRODUCT_ID))
                return dev;
}
}
return NULL;

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
Handle must be created by libusb for the program
Communicate with the device. This is done with the following simple code:

usb_handle = usb_open(usb_dev);
if (usb_handle == NULL) {
    fprintf(stderr,
            "Not able to claim the USB device/n");
    goto exit;
}

This usb_handle variable is of Type struct usb_dev_handle, and it is what
Libusb uses to determine with which USB device it shoshould 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,
CallUsb_close (usb_handle );
Is all that is necessary to clean up all of our structures and between Y
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:

usb_control_msg(led->udev,
                usb_sndctrlpipe(led->udev, 0),
                0x12,
                0xc8,
                (0x02 * 0x100) + 0x0a,
                (0x00 * 0x100) + color,
                buffer,
                8,
                2 * HZ);

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
Kernel, our user-space program does it like this:

usb_control_msg(handle,
                0xc8,
                0x12,
                (0x02 * 0x100) + 0x0a,
                (0c00 * 0x100) + color,
                buffer,
                8,
                5000);

Other than the request type and request Variables
Being reversed from the kernel function call, it
Looks identical.

Using libusb cuts down extremely
The complexities of writing to a USB device, and it gives us
Cross-platform program that is much better than a specific kernel driver
For most devices.

Listing 1. Controlling a usb led Device

/*
 * Set LED - program to control a USB LED device
 * from user space using libusb
 *
 * Copyright (C) 2004
 *     Greg Kroah-Hartman (greg@kroah.com)
 *
 * This program is free software; you can
 * redistribute it and/or modify it under the terms
 * of the GNU General Public License as published by
 * the Free Software Foundation, version 2 of the
 * License.
 *
 */
#include <stdio.h>
#include <string.h>
#include <usb.h>

#define NONE    0x00
#define BLUE    0x04
#define RED     0x02
#define GREEN   0x01


#define LED_VENDOR_ID   0x0fc5
#define LED_PRODUCT_ID  0x1223

static void change_color
        (struct usb_dev_handle *handle,
         unsigned char color)
{
    char *dummy;

    usb_control_msg(handle,
                    0x000000c8,
                    0x00000012,
                    (0x02 * 0x100) + 0x0a,
                    0xff & (~color),
                    dummy,
                    0x00000008,
                    5000);
}

static struct usb_device *device_init(void)
{
    struct usb_bus *usb_bus;
    struct usb_device *dev;

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

    for (usb_bus = usb_busses;
         usb_bus;
         usb_bus = usb_bus->next) {
        for (dev = usb_bus->devices;
             dev;
             dev = dev->next) {
            if ((dev->descriptor.idVendor
                  == LED_VENDOR_ID) &&
                (dev->descriptor.idProduct
                  == LED_PRODUCT_ID))
                return dev;
        }
    }
    return NULL;
}

int main(int argc, char **argv)
{
    struct usb_device *usb_dev;
    struct usb_dev_handle *usb_handle;
    int retval = 1;
    int i;
    unsigned char color = NONE;

    usb_dev = device_init();
    if (usb_dev == NULL) {
        fprintf(stderr, "Device not foundn/n");
        goto exit;
    }

    usb_handle = usb_open(usb_dev);
    if (usb_handle == NULL) {
        fprintf(stderr,
        goto exit;
    }

    usb_handle = usb_open(usb_dev);
    if (usb_handle == NULL) {
        fprintf(stderr,
             "Not able to claim the USB device/n");
        goto exit;
    }

    if (argc == 1) {
        fprintf(stderr,
                "specify at least 1 color/n");
        goto exit;
    }

    for (i = 1; i < argc; ++i) {
        if (strcasecmp(argv[i], "red") == 0)
            color |= RED;
        if (strcasecmp(argv[i], "blue") == 0)
            color |= BLUE;
        if (strcasecmp(argv[i], "green") == 0)
            color |= GREEN;
        if (strcasecmp(argv[i], "none") == 0)
            color = NONE;
    }
    change_color(usb_handle, color);
    retval = 0;

exit:
    usb_close(usb_handle);
    return retval;
}

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
Experiment with libusb as a simple alternative
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 ss a wide range
Operating systems.

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