Device Drivers, Part 13: Data Transfer to and from USB Devices

USB device drivers

This article, which is part of the series on Linux device drivers, continues from the previous two articles. It details the ultimate step of data transfer to and from a USB device, using your first USB driver in Linux.

Pugs continued, “To answer your question about how a driver selectively registers or skips a particular interface of a USB device, you need to understand the significance of the return value of the probe() callback.” Note that the USB core would invoke probe for all the interfaces of a detected device, except the ones which are already registered — thus, while doing it for the first time, it will probe for all interfaces. Now, if the probe returns 0, it means the driver has registered for that interface. Returning an error code indicates not registering for it. That’s all. “That was simple,” commented Shweta.

“Now, let’s talk about the ultimate — data transfers to and from a USB device,” continued Pugs.

“But before that, tell me, what is this MODULE_DEVICE_TABLE? This has been bothering me since you explained the USB device ID table macros,” asked Shweta, urging Pugs to slow down.

“That’s trivial stuff. It is mainly for the user-space depmod,” he said. ‘Module’ is another term for a driver, which can be dynamically loaded/unloaded. The macro MODULE_DEVICE_TABLE generates two variables in a module’s read-only section, which is extracted by depmod and stored in global map files under /lib/modules/<kernel_version>. Two such files are modules.usbmap and modules.pcimap, for USB and PCI device drivers, respectively. This enables auto-loading of these drivers, as we saw the usb-storage driver getting auto-loaded.

USB data transfer

“Time for USB data transfers. Let’s build upon the USB device driver coded in our previous sessions, using the same handy JetFlash pen drive from Transcend, with vendor ID 0x058f and product ID 0x6387,” said Pugs, enthusiastically.

USB, being a hardware protocol, forms the usual horizontal layer in the kernel space. And hence, for it to provide an interface to user-space, it has to connect through one of the vertical layers. As the character (driver) vertical has already been discussed, it is the current preferred choice for the connection with the USB horizontal, in order to understand the complete data transfer flow.

Also, we do not need to get a free unreserved character major number, but can use the character major number 180, reserved for USB-based character device files. Moreover, to achieve this complete character driver logic with the USB horizontal in one go, the following are the APIs declared in <linux/usb.h>:

int usb_register_dev(struct usb_interface *intf, struct usb_class_driver *class_driver);
void usb_deregister_dev(struct usb_interface *intf, struct usb_class_driver *class_driver);

Usually, we would expect these functions to be invoked in the constructor and the destructor of a module, respectively. However, to achieve the hot-plug-n-play behaviour for the (character) device files corresponding to USB devices, these are instead invoked in the probe and disconnect callbacks, respectively.

The first parameter in the above functions is the interface pointer received as the first parameter in both probe and disconnect. The second parameter, struct usb_class_driver, needs to be populated with the suggested device file name and the set of device file operations, before invoking usb_register_dev. For the actual usage, refer to the functions pen_probe and pen_disconnect in the code listing of pen_driver.c below.

Moreover, as the file operations (write, read, etc.,) are now provided, that is exactly where we need to do the data transfers to and from the USB device. So, pen_write and pen_ read below show the possible calls to usb_bulk_msg() (prototyped in <linux/usb.h>) to do the transfers over the pen drive’s bulk end-points 0×01 and 0×82, respectively. Refer to the ‘E’ lines of the middle section in Figure 1 for the endpoint number listings of our pen drive.

USB specifications for the pen drive

Figure 1: USB specifications for the pen drive

Refer to the header file <linux/usb.h> under kernel sources, for the complete list of USB core API prototypes for other endpoint-specific data transfer functions like usb_control_msg(), usb_interrupt_msg(), etc. usb_rcvbulkpipe(), usb_sndbulkpipe(), and many such other macros, also defined in <linux/usb.h>, compute the actual endpoint bit-mask to be passed to the various USB core APIs.

Note that a pen drive belongs to a USB mass storage class, which expects a set of SCSI-like commands to be transacted over the bulk endpoints. So, a raw read/write as shown in the code listing below may not really do a data transfer as expected, unless the data is appropriately formatted. But still, this summarises the overall code flow of a USB driver. To get a feel of a real working USB data transfer in a simple and elegant way, one would need some kind of custom USB device, something like the one available here.

#include <linux/module.h>
#include <linux/kernel.h>
#include <linux/usb.h>

#define MIN(a,b) (((a) <= (b)) ? (a) : (b))
#define BULK_EP_OUT 0x01
#define BULK_EP_IN 0x82
#define MAX_PKT_SIZE 512

static struct usb_device *device;
static struct usb_class_driver class;
static unsigned char bulk_buf[MAX_PKT_SIZE];

static int pen_open(struct inode *i, struct file *f)
{
    return 0;
}
static int pen_close(struct inode *i, struct file *f)
{
    return 0;
}
static ssize_t pen_read(struct file *f, char __user *buf, size_t cnt, loff_t *off)
{
    int retval;
    int read_cnt;

    /* Read the data from the bulk endpoint */
    retval = usb_bulk_msg(device, usb_rcvbulkpipe(device, BULK_EP_IN),
            bulk_buf, MAX_PKT_SIZE, &read_cnt, 5000);
    if (retval)
    {
        printk(KERN_ERR "Bulk message returned %d\n", retval);
        return retval;
    }
    if (copy_to_user(buf, bulk_buf, MIN(cnt, read_cnt)))
    {
        return -EFAULT;
    }

    return MIN(cnt, read_cnt);
}
static ssize_t pen_write(struct file *f, const char __user *buf, size_t cnt, loff_t *off)
{
    int retval;
    int wrote_cnt = MIN(cnt, MAX_PKT_SIZE);

    if (copy_from_user(bulk_buf, buf, MIN(cnt, MAX_PKT_SIZE)))
    {
        return -EFAULT;
    }

    /* Write the data into the bulk endpoint */
    retval = usb_bulk_msg(device, usb_sndbulkpipe(device, BULK_EP_OUT),
            bulk_buf, MIN(cnt, MAX_PKT_SIZE), &wrote_cnt, 5000);
    if (retval)
    {
        printk(KERN_ERR "Bulk message returned %d\n", retval);
        return retval;
    }

    return wrote_cnt;
}

static struct file_operations fops =
{
    .open = pen_open,
    .release = pen_close,
    .read = pen_read,
    .write = pen_write,
};

static int pen_probe(struct usb_interface *interface, const struct usb_device_id *id)
{
    int retval;

    device = interface_to_usbdev(interface);

    class.name = "usb/pen%d";
    class.fops = &fops;
    if ((retval = usb_register_dev(interface, &class)) < 0)
    {
        /* Something prevented us from registering this driver */
        err("Not able to get a minor for this device.");
    }
    else
    {
        printk(KERN_INFO "Minor obtained: %d\n", interface->minor);
    }

    return retval;
}

static void pen_disconnect(struct usb_interface *interface)
{
    usb_deregister_dev(interface, &class);
}

/* Table of devices that work with this driver */
static struct usb_device_id pen_table[] =
{
    { USB_DEVICE(0x058F, 0x6387) },
    {} /* Terminating entry */
};
MODULE_DEVICE_TABLE (usb, pen_table);

static struct usb_driver pen_driver =
{
    .name = "pen_driver",
    .probe = pen_probe,
    .disconnect = pen_disconnect,
    .id_table = pen_table,
};

static int __init pen_init(void)
{
    int result;

    /* Register this driver with the USB subsystem */
    if ((result = usb_register(&pen_driver)))
    {
        err("usb_register failed. Error number %d", result);
    }
    return result;
}

static void __exit pen_exit(void)
{
    /* Deregister this driver with the USB subsystem */
    usb_deregister(&pen_driver);
}

module_init(pen_init);
module_exit(pen_exit);

MODULE_LICENSE("GPL");
MODULE_AUTHOR("Anil Kumar Pugalia <email_at_sarika-pugs_dot_com>");
MODULE_DESCRIPTION("USB Pen Device Driver");

As a reminder, the usual steps for any Linux device driver may be repeated with the above code, along with the following steps for the pen drive:

  • Build the driver (pen_driver.ko) by running make.
  • Load the driver using insmod pen_driver.ko.
  • Plug in the pen drive (after making sure that the usb-storage driver is not already loaded).
  • Check for the dynamic creation of /dev/pen0 (0 being the minor number obtained — check dmesg logs for the value on your system).
  • Possibly try some write/read on /dev/pen0 (you most likely will get a connection timeout and/or broken pipe errors, because of non-conforming SCSI commands).
  • Unplug the pen drive and look for /dev/pen0 to be gone.
  • Unload the driver using rmmod pen_driver.

Meanwhile, Pugs hooked up his first-of-its-kind creation — the Linux device driver kit (LDDK) — into his system for a live demonstration of the USB data transfers.

“Aha! Finally a cool complete working USB driver,” quipped Shweta, excited. “Want to have more fun? We could do a block driver over it…,” added Pugs. “Oh! Really?” asked Shweta, with glee. “Yes. But before that, we need to understand the partitioning mechanisms,” commented Pugs.

  • Braian Agustin Lopez

    FUA ES RE CROTO LINUX PERO NO ENTRAN VIRUS ESO ES LO BUENO

  • Braian Agustin Lopez

    TIENEN QUE HACER QUE TODOS LOS PROGRAMAS QUE VIENEN PARA WINDOWS TAMBIEN SEAN PARA LINUX

  • rkarthikreddy

    where can i get linux DDK  ? i found a link to a web site for downloading DDK but the server is down!

    • anil_pugalia

      You can get it here: http://lddk.esrijan.com

      • Marjan

        There is an error in source! You should not allocate buffer globally. Microchip FSUSB demo board did not work by me. I allocated buffer in write_msg function. Then, it worked.

        • anil_pugalia

          Can you explain as what do you mean by “not working” with global buffer? I assume that when you allocated the buffer in write_msg, you freed it also, there itself.

          • Marjan

            One more thing: this was kernel 3.5.0.

            What happened was this: static buffer contained correct data from userspace. Device however received corrupted data. When I moved this buffer variable into red/write rutines, it fixed the problem.

            It was just a char array.

            One more question: how does kernel distinguish between identical devices (literally cloned; same deviceID, same vendor ID, same serial, BCD code, etc.)? Kernel assigns different minor numbers. But I have a problem “how to send data to correct device (or read from it)” when device file read/write in userspace happens.

          • anil_pugalia

            Possibly a race condition of simultaneous access of the buffer.

            Your probe will get called multiple times for each interface of the multiple devices, and accordingly distinct minors should be allotted to each. Also, in each probe the corresponding device pointer should be preserved into the private data of the corresponding interface, and then possibly the struct file, in case of system calls. With that the system calls would access the correct device, from their struct file’s private data.

          • Marjan

            There was one single access to driver at the time (as far as I am aware of), and this was my test program.

            So I guess I’ll have to implement this multiple devices handling mechanysm inside of the driver by myself.

          • anil_pugalia

            Agreed that you had only single access from the user space – but there could be other accesses from within the kernel, itself.

            And yes, support for handling multiple devices has to be provided from within the driver only. Once the support is there, then it is left to the applications, what do they do with that.

          • Harish Nanjasetty
          • anil_pugalia

            This doesn’t implement the complete usb storage protocol – so you may not be able to do an actual read/write.

          • Harish Nanjasetty

            Thanks for u reply Sir i want about high mem,and low mem.
            kmalloc allocates memory in low mem i.e after linux image sits?
            what is high mem, entire 896> to 4GB is high mem

            how different is this memory from 4 GB process address space

            How exactly CFS works

          • anil_pugalia

            high mem – 896> to 4GB is DOS days concept. The high mem in Linux kernel context is a very different thing. In kernel, low mem & high mem is just the differentiation whether the memory is directly mapped & accessed or indirectly mapped through a window. 4GB process address space could map to any one or both of them, but typically done with low mem.

            For working of CFS, check out the CFS code.

          • Harish Nanjasetty

            What is difference between fast irq and irq.
            With respect to x86 there is INTR line which interfaced to 8059 PIC based on flag given in handler what actions are take with respect to INTR and 8059 controller

            As an interrupt occurs, handler is called and all interrupts are disabled then on exit of handler interrupts are enabled
            then what are nested interrupts are they software interrupts occuring inside handler as interrupts are disabled in the handler

          • anil_pugalia
          • Harish Nanjasetty

            Thank you soo much for valuable time and sharing such good links Hope you do not mind if i come up with more questions in near future

          • anil_pugalia

            Sure, I do have a mind :) You are welcome.

          • Harish Nanjasetty

            Hi Sir,

            when exactly to go for semaphore and when for mutex.
            binary sema is itself mutex??
            when we use counting?
            semaphore any process can release it .mutex parent itself as to relase it

          • anil_pugalia

            For such typical questions, you may do google and very well get the answers. Here’s one detailed link, I got, by doing the same:

            http://www.geeksforgeeks.org/mutex-vs-semaphore/

          • Harish Nanjasetty

            It seems to be typical but they are not clear can you please explain me what exactly you have understood from it.
            It is clear with mutext,But semaphore not getting properly.

          • anil_pugalia

            In Linux kernel, we only need mutex, for synchronization i.e. concurrent access protection – typically no use case for semaphore.

          • Harish Nanjasetty

            Hello sir, How can we create file inside a device file .
            I mean when i open device file inside pen drive if i am doing copy of a file the file as to be created how it is done.
            What is driver level create call??

          • anil_pugalia

            Device files are just place holders – they are not devices and hence we do not create file inside a device file but onto the device only – device file just represents it, to connect/mount the device to a particular folder under /

          • Harish Nanjasetty

            i want to implement copy into my pendrive meaning i have file1 which has to be copied to pendrive what exactly will happen with driver level calls .
            How exactly file1 on disk map to pendrive location.
            i am clear about read and write

          • anil_pugalia

            This is done by the file system driver and system calls provided by it – the driver for the file system which is created/formatted on the pen drive.

          • Harish Nanjasetty

            Sir please clearly explain me when binary semaphore is used and when counting semaphore is used with respect to OS

          • Harish Nanjasetty

            Please explain more clearly on this line

            4GB process address space could map to any one or both of them, but typically done with low mem.

          • anil_pugalia
  • shiavng

    very nice explanation and it gives motivation to those who are learning device driver…
    very admiring work….keep world more technical through sharing such information and innovation on drivers.

    • anil_pugalia

      Thanks for your admiration.

  • plr

    hi sir,
    To answer your question about how a driver selectively registers or
    skips a particular interface of a USB device, you need to understand the
    significance of the return value of the probe() callback.”
    Note that the USB core would invoke probe for all the interfaces of a
    detected device, except the ones which are already registered — thus,
    while doing it for the first time, it will probe for all interfaces.
    Now, if the probe returns 0, it means the driver has registered for that
    interface. Returning an error code indicates not registering for it.
    That’s all. “That was simple,” commented Shweta.

    I dint understand this correctly.

    What I have understood is , an usb device can be multifunctional and for each functionality there will be a corresponding interface . So a driver is written for an interface rather than the device itself . Now when the device is plugged in , there would be multiple drivers written for multiple interfaces . So the probe function of all the interfaces is called ?

    This is ok . But there can be different vertical drivers assciated with different interfaces and these verticals can have thier own operations defined (fops in case of charcter vertical) . So when a open is called , how will the kernel know ,open is associated with which particular interface ?

    • http://www.facebook.com/anil.pugalia Anil Pugalia

      Kernel would know about the open, as per the registration done by the vertical with the VFS

      • anil_pugalia

        And in the driver, we would register the corresponding minor, as to which interface we are going to handle (as per the USB device data sheet). So, there would always be a unique mapping.

  • Avijit Sur

    Very nicely explained!!! Could you please start another chapter on “partitioning mechanisms” ?

  • manas jyoti sarmah

    Sir,

    Please explain the read() and write() methods.I am unable to implement them.

    • anil_pugalia

      Please share your problem in implementation, and we’ll try to solve that.

  • aaa

    Sir,

    probe is called per interface and it gets called by the usb-core . But In a multifunctional device , how to distinguish between different interfaces becoz what I observed is , we are just mentioning the vendor id and device id in the usb driver structure , which will be same for all the interfaces becoz the device is same . My question is how will the kernel know , which interface has to be called in a multifunctional device ? how does the kernel distinguish between different interfaces of the same device ?

    • anil_pugalia

      Note that the probe function has the first parameter as the pointer to the interface structure, which contains the interface number. So, on probe invocation, we know as for which interface has this probe been called.

  • MenDuong

    Dear, Why I insmod pen_driver.ko appear error message “insmod: error inserting ‘pen_driver.ko’: -1 Device or resource busy”. Thanks

    • http://twitter.com/anil_pugalia Anil Pugalia

      Please paste the output of “dmesg | tail -20″, to be able to decode that error.

      • MenDuong

        Okays. I resolved that error. Cause I haven’t removed pen_info module previous. Thanks!

  • http://twitter.com/jayasantosh1 jayasantosh

    not required to recompile the kernel as anil describe . just compile your module in the name of usb-storage and replace the .ko file in the folder /lib/modules/{your kernel version}/kernel/drivers/usb/storage/usb-storage.ko with your usb-storage.ko file.(note pls take backup of kernel usb-storage.ko)

  • MELWIN

    In the pen_read function the usb_bulk_msg returns an ERROR NO of -32, which is the PIPE BROKEN errno. I ran the same code here. Help !!!

    • anil_pugalia

      That’s as expected. Refer to the article.

  • resque

    While reading from pen device cat /dev/pen0 bulk message returned error 22 – Invalid argument

    • http://twitter.com/anil_pugalia Anil Pugalia

      Possibly the endpoint number on your pen drive is different. Check it out & correct it accordingly.

  • anon

    I stuck with the problem – while reading, usb_bulk_msg returns error 22 – Invalid argument. Write operation succeeds.

    • anon

      sorry for spamming, i was confused how to read newest posts.

  • anon

    stuck with the problem – while reading, usb_bulk_msg returns error 22 – Invalid argument. Write operation succeeds.

    • http://twitter.com/anil_pugalia Anil Pugalia

      As mentioned below, check out the endpoint number on your pen drive. If it is different correct it accordingly.

  • ayush

    can any one pls tell me what are the parameter passed in this
    usb_bulk_msg function ..

    retval = usb_bulk_msg(device, usb_rcvbulkpipe(device, BULK_EP_IN),
    bulk_buf, MAX_PKT_SIZE, &read_cnt, 5000);

    • http://twitter.com/anil_pugalia Anil Pugalia

      Check out its prototype in the header file <linux/usb.h>

  • jaya

    pls tell me differrence btw

    usb_register_dev(interface, &class)) && usb_register(&pen_driver)) function call i think both are for registering usb with usb subsystem

    • http://twitter.com/anil_pugalia Anil Pugalia

      usb_register registers with the horizontal usb core. usb_register_dev registers the vertical with VFS.

  • jaya

    getting error of permisions inspite of doing chmod command …..pls reply

    root@pcch-ee206270:/home/pcch-ee206270/Desktop/bb/usb_read_write# chmod 777 /dev/pen0
    root@pcch-ee206270:/home/pcch-ee206270/Desktop/bb/usb_read_write# echo “hi” | /dev/pen0
    bash: /dev/pen0: Permission denied
    root@pcch-ee206270:/home/pcch-ee206270/Desktop/bb/usb_read_write#

    • http://twitter.com/anil_pugalia Anil Pugalia

      Please replace | by >, i.e. echo “hi” > /dev/pen0
      Moreover, you do not need chmod 777, just 666 should be good enough.

  • jaya

    PLS someone tell me abt the funda of this usb_class_drive .. its been used many times in above code .. like below .. what this struct actually defines ..??

    static struct usb_class_driver class;
    class.name = “usb/pen%d”;

    class.fops = &fops;
    if ((retval = usb_register_dev(interface, &class)) < 0)

    • http://twitter.com/anil_pugalia Anil Pugalia

      This is more like giving the suggested device file name & the file operations for the vertical layer.

  • jaya

    i have successfully completed all process /dev/pen0 is also there in /dev … now what is next … what should i do next to see read and write working ….

    i tried this .. but error is coming ..

    root@pcch-ee206270:/home/pcch-ee206270/Desktop/bb/usb_read_write# echo “hi” > /dev/pen0
    bash: echo: write error: Invalid argument

    • http://twitter.com/anil_pugalia Anil Pugalia

      These various errors are expected and as mentioned in the last para of the article.

  • Midhun

    Hi Anil,thanks for this session of knowledge transfer.
    I have one query about how the file system inside usb is mounting to linux existing filesystem.Could u help us with that also?

    • anil_pugalia

      For that you may have to read my article #18 to #24 on file system modules. As of this comment, most of these 7 articles are available only in LFY hard copy.

  • Sid

    Sir, I would like to know which of the function gets the access first. .read or .write?

    • anil_pugalia

      What do you mean by access first? It is which the user calls first.

  • brajesh

    Sir as i’v seen in my usb.c(old- usb-storage.c) usb is registered to VFS by block driver api’s , so can you tell me in which USB devices char API’s are used as in our article code

    • anil_pugalia

      For example in usb to serial convertor.

      • brajesh sharma

        okay , but can we see this in usbkdb.c (keyboard) driver i guess that is also byte oriented ???

        • anil_pugalia

          Check it out. You may be able to see, along with the input layer over it.

  • brajesh

    One more thing sir , in statement class.name = /dev/pen%d
    how exactly we are getting minor number in place of %d

    • anil_pugalia

      That’s done by usb_register_dev.

  • brajesh sharma

    Sir after inserting the module i am not able to see any file in /dev/ i’v unloaded
    the usb-storage.ko as well , pls suggest something

    • anil_pugalia

      Check out if your /sys filesystem is mounted and udevd daemon is running.

  • Shar

    i am writing a device driver for CDC-EEM class device. it has two interfaces one for control and other for bulk transfers. the device probe is called for two interfaces. how to deal with two probes. if i register only one interface , is there any way that i can use other interface in read/write functions of registered interface??

    • anil_pugalia

      Register for both the probes in your driver.

  • brajesh sharma

    after inserting the module (after unloading the usb-storage.ko) from the kernel another driver (pen_driver ) picks up the pen drive instead of my driver , suggest something … pls

    • anil_pugalia

      pen_driver is the driver created by the article above – so that is anyway expected, right.

  • Tanmay

    Hello Sir,
    How can we implement read and write through our code.Please tell me.

    • anil_pugalia

      Read & write of what?

      • Tanmay

        Sir, how can we implement the basic steps of reading and writing of data or any string with the help of our code. Please do let me know.

        • anil_pugalia

          As far as I understand, the implementation is shown in the above article. Or, by reading / writing do you mean something like what a user application does using scanf / printf. If yes, then drivers are not meant for that.

  • Tanmay

    Sir,
    How can i test my usb device driver code with the help of Pandaboard. What are the steps to implement our code ??

    • anil_pugalia

      Just cross compile the driver for your Pandaboard’s kernel.

      • Tanmay

        How to do that i don’t know, just let me know the basic steps how to do that???

        • anil_pugalia

          Have the Pandaboard’s kernel. Compile it. Once you have done that, you would know the rest.

  • Nandan Bharadwaj

    Hi Anil,
    Thank you for the this great work, really good articles to understand the basics of Linux Device drivers. Can you please give us readers an idea on media drivers like JPEG.

    • anil_pugalia

      Didn’t really understand? What do you mean by a JPEG media driver? Is it a Linux device driver?

  • shiv

    here i am getting as broken pipe how to conform scsi commands sir please explain

    • anil_pugalia

      For that, you have to study the usb storage protocol.

  • Umar Amin

    I have followed all the steps, the device is getting registered as you can see in the attached image but i am unable to read or write data from/to usb because the device is not mounting. Plz help…

    • anil_pugalia

      The above driver is not supposed to expose the device as a block device, and hence not expected to support mounting. It is just to demonstrate the basic workings of the USB protocol, not even data read/write as per the usb storage protocol.

      • Umar Amin

        Then how can i test pen_read and pen_write operations.

        • anil_pugalia

          By directly reading/writing into /dev/usb/pen0. Though don’t expect it to do any meaningful read/write.

  • manish

    how do we call the read and write method? Do we have to write the app which call the read and write method?

    • anil_pugalia

      You may simply use cat and echo with /dev/pen0 to respectively call the read and write methods. Or, if you want, you may write a simple C program (app) to do the same.

  • CM

    Hello Anil, nice article. . .
    I have tried this and i am able to see /dev/pen0. Now If i try to read then it gives connection time out error, as you have mentioned.
    I want to read first 512 bytes of raw data of storage device. Is it possible?

    • anil_pugalia

      Thanks for your appreciation. For data transaction for the storage device, you may have read up the usb storage protocol and write commands as per that into the corresponding out endpoint.

All published articles are released under Creative Commons Attribution-NonCommercial 3.0 Unported License, unless otherwise noted.
Open Source For You is powered by WordPress, which gladly sits on top of a CentOS-based LEMP stack.

Creative Commons License.