USB Drivers in Linux: Data Transfer to & from USB Devices

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

<< Twelfth Article

USB miscellany

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 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. So, for the first time, it would call for all. 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 & from a USB device”, continued Pugs. “But before that tell me what is this MODULE_DEVICE_TABLE? This is bothering me since you explained the USB device id table macros”, asked Shweta pausing Pugs. “That’s another trivial stuff. It is mainly for the user-space depmod“, said Pugs. “Module” is another name for a driver, which is dynamically loadable and unloadable. 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>. modules.usbmap and modules.pcimap are two such files for USB & PCI device drivers, respectively. This enables auto-loading of these drivers, as we saw 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.”

USB being a hardware protocol, it 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 character (driver) vertical is already discussed, it is the current preferred choice for the connection with the USB horizontal, for understanding 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 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 the disconnect callbacks, respectively. First parameter in the above functions is the interface pointer received as the first parameter in both probe and disconnect. 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, …) are now provided, that is where exactly we need to do the data transfers to and from the USB device. So, pen_write() and pen_ read() below shows the possible calls to usb_bulk_msg() (prototyped in <linux/usb.h>) to do the transfers over the pen drive’s bulk end points 0x01 and 0x82, respectively. Refer to the ‘E’ lines of the middle section in Figure 19 for the endpoint number listings of our pen drive. Refer to the header file <linux/usb.h> under kernel sources, for the complete list of USB core API prototypes for the 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 bitmask to be passed to the various USB core APIs.

Figure 19: USB's proc window snippet

Figure 19: USB’s proc window snippet

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 summarizes the overall code flow of a USB driver. To get a feel of 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 at eSrijan.

#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 =
{
	.owner = THIS_MODULE,
	.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 */
		printk(KERN_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)))
	{
		printk(KERN_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@sarika-pugs.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 pen drive steps:

  • Build the driver (pen_driver.ko file) by running make.
  • Load the driver using insmod pen_driver.ko.
  • Plug-in the pen drive (after making sure that 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. (Though you may mostly get connection timeout and/or broken pipe errors because of non-conformant SCSI commands)
  • Unplug-out the pen drive and look out for gone /dev/pen0.
  • Unload the driver using rmmod pen_driver.

Summing up

Meanwhile, Pugs hooked up his first of its kind creation – the Linux device driver kit (LDDK) into his system to show a live demonstration of the USB data transfers. “A ha! Finally a cool complete working USB driver”, quipped excited Shweta. “Want to have more fun. We could do a block driver over it”, added Pugs. “O! Really”, Shweta asked with a glee on her face. “Yes. But before that we would need to understand the partitioning mechanisms”, commented Pugs.

Fourteenth Article >>

Notes

  1. Make sure that you replace the vendor id & device id in the above code examples by the ones of your pen drive. Also, make sure that the endpoint numbers used in the above code examples match the endpoint numbers of your pen drive. Otherwise, you may get an error like “… bulk message returned error 22 – Invalid argument …”, while reading from pen device.
  2. Also, make sure that the driver from the previous article is unloaded, i.e. pen_info is not loaded. Otherwise, it may give an error message “insmod: error inserting ‘pen_driver.ko’: -1 Device or resource busy”, while doing insmod pen_driver.ko.
  3. One may wonder, as how does the usb-storage get autoloaded. The answer lies in the module autoload rules written down in the file /lib/modules/<kernel_version>/modules.usbmap. If you are an expert, you may comment out the corresponding line, for it to not get autoloaded. And uncomment it back, once you are done with your experiments.
  4. In latest distros, you may not find the detailed description of the USB devices using cat /proc/bus/usb/devices, as the /proc/bus/usb/ itself has been deprecated. You can find the same detailed info using cat /sys/kernel/debug/usb/devices – though you may need root permissions for the same. Also, if you do not see any file under /sys/kernel/debug (even as root), then you may have to first mount the debug filesystem, as follows: mount -t debugfs none /sys/kernel/debug.
Anil Kumar Pugalia (123 Posts)

The author is a hobbyist in open source hardware and software, with a passion for mathematics, and philosopher in thoughts. A gold medallist from the Indian Institute of Science, Linux, mathematics and knowledge sharing are few of his passions. He experiments with Linux and embedded systems to share his learnings through his weekend workshops. Learn more about him and his experiments at https://sysplay.in.


   Send article as PDF   

32 thoughts on “USB Drivers in Linux: Data Transfer to & from USB Devices

  1. Pingback: USB Drivers in Linux (Continued) | Playing with Systems

  2. Pingback: Understanding the Partitions: A dive inside the hard disk | Playing with Systems

  3. Sandeep

    Nice Article. Thanks a lot for sharing this info.

    I tried the USB driver code. The data tranfer using “usb_bulk_msg” fails with error code “-8”. Please let me know if you have any comments on this?

    Reply
  4. Vijay Kanta

    Good tutorial, but would like to really understand the SCSI commands for a regular USB drive. Is it formatted specifically for each device?

    Reply
  5. vasle asin

    HEllo sir, I’m wokin as a system developer (Trainee..)………………
    I Searched many sites to know about Ldd , I failed to find a good one.
    But u provide an awsome article about Ldd…
    tanqs for dhat………..

    all are FINE .
    U -> pugs..
    ? -> swatha

    Reply
      1. vasle asin

        THanks sir.
        I hv one doubt about add a debug driver(xhci debug driver . v put som ‘printk’ to find the flow) to kernel…

        -> i hv xhci.c filess and kernel 3.19(not compiled and installed yet) .
        -> I also hv a compiled .ko file of .c files

        to c log messeges

        Can i replace the orginal .ko files (xhci .ko files) with mine at run time, Will it work?
        Or should i replace .c files in uncompiled kernel with mine , and compile the kernel then c the log messages…>>.?????????????????

        Reply
  6. Pingback: how to do USB devcies data transfer ,using your own module? | DL-UAT

  7. Vitor Barbosa

    Everything was done perfectly, but how do I do to create a file (with a single character, for example) inside a pendrive recognized by this driver?

    Reply
    1. Anil Kumar Pugalia Post author

      If you read the above comments, and mentions in the article, you’d realize that you cannot actually write into a pendrive using this driver. For that one needs to additionally implement the SCSI based usb storage logic in the read & write calls above. This driver just gives the framework for the same.

      Reply
        1. Anil Kumar Pugalia Post author

          I assume you are referring to that with our driver it doesn’t show in storage. It wouldn’t. As it is not a complete storage driver. It is just to demonstrate the USB working. For a complete storage driver, you need to integrate the block & then filesystem driver over it. And block driver also over SCSI protocol layer, as USB storage protocol is based on SCSI.

          Reply
    1. Anil Kumar Pugalia Post author

      Did you check as to who has acquired the pen driver? Do “cat /sys/kernel/debug/usb/devices” and check for the “Driver: …” row in the pen drive entry. It should be your driver. Typically it gets occupied by the usb-storage driver. You need to remove that and then re-plug your pen drive.

      Reply
      1. Viju

        Hi Anil,

        I tried your steps.
        $ sudo rmmod uas
        $ sudo rmmod usb-storage
        $ sudo insmod pen_driver.ko
        Now /dev/pen0 dynamically created, but i couldn’t read/write. I am getting following error

        Attached the dmesg log for further information:
        [ 8956.626947] usbcore: deregistering interface driver uas
        [ 8957.996753] usbcore: deregistering interface driver usb-storage
        [ 8969.531749] pen_driver: loading out-of-tree module taints kernel.
        [ 8969.531770] pen_driver: module verification failed: signature and/or required key missing – tainting kernel
        [ 8969.532086] Minor obtained: 0
        [ 8969.532100] usbcore: registered new interface driver pen_driver
        [ 9104.323168] Bulk message returned in read -110
        [ 9115.587159] Bulk message returned in read -110
        [ 9134.041047] Bulk message returned in read -32
        [ 9135.725897] Bulk message returned in read -32

        I hope I provided correct endpoints.

        Please help me to do read/write with usb device. Need to maintain rawusb format or any format?

        Thanks for your time.

        Reply
  8. Viju

    Hi Anil Kumar Pugalia ,

    Please add your suggestion. Seems like something went wrong at pen_read() function at my end.

    Thanks.

    Reply
        1. Anil Kumar Pugalia Post author

          It is a continuation of the previous two articles. Follow to 12th & then from there to 11th article from the above link at the beginning of the article. And you’ll find the details.

          Reply
    1. Anil Kumar Pugalia Post author

      This article is a continuation of the previous two articles. Follow to 12th & then from there to 11th article from the above link at the beginning of the article. And you’ll find the details.

      Reply
  9. Vivek Yadav

    Thanks for Writing these beautiful articles on Linux Device Drivers…..
    I made my Microcontroller STM32F103C8 a USB device ( POS ) and Successfully Emmurate that as HID.
    Now I want to read the data of its Endpoint(0x81 or 0x01 0r 0x82 etc) and want to see at my STDOUT screen.
    HOW CAN I DO THAT ????????

    copy_to_user ( ) and copy_from_user ( ) and not worthy for me or maybe I am not able to use them properly..

    Thanks

    Reply
    1. Anil Kumar Pugalia Post author

      Depending on what type of endpoints you have, use the appropriate usb_*_msg APIs. What exactly to send & recv should be based on the uC firmware you have written.

      Additionally, you may have to remove an existing pre-loaded HID driver, if it has acquired the device. Also, it may need control endpoint interactions – not really sure about it in HID protocol.

      Reply

Leave a Reply to Vijay Kanta Cancel reply

Your email address will not be published. Required fields are marked *