USB Host & Gadget Device Drivers in Linux

1. © 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
USB Drivers

2. 2© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
What to Expect?
USB Evolution
USB Subsystem: Host & Gadget
Understanding of USB Protocol
Writing USB Host Drivers
Writing USB Gadget Drivers

3. 3© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
USB Prologue
What was USB designed for?
A Unified Bus for Slow Devices
So, design based on Master-Slave concept
USB (Host) Controller is the “Single Master”
UHC polls the Slave Peripherals / Devices
Later Additions
High Speed Specifications
Bandwidth Allocation Ability
But even today, the polling continues

4. 4© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
USB Device Driver Types
2 Types: Both written for the Device
USB Host (Device) Driver
Runs on Host (Master)
Drives the USB Device (Slave)
USB Gadget (Device) Driver
Runs on the USB Gadget / Device (Slave)
Responds to a Host (Master)
Pre-requisite: Gadget is Linux based

5. 5© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
USB Host Subsystem View
FS
Layer
USB Host Device Drivers ...
USB Core
USB Host / OTG Controller Driver(s)
...
TTY
Layer
Char
Layer
Net
Layer
Block
Layer
Kernel Space
User Applications
USB Devices ...
Hardware Space
User Space
usbfs
User Mode
Drivers
USB Host / OTG Controller

6. 6© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
USB Host Subsystem
UHC Driver (uhci, ohci, ehci, otg)
Hardware-specific USB Host Controller driver
Hides all the hardware details from the layers above
Provides a uniform interface to USB Core
USB Core Module (usbcore)
Provides the generic USB Protocol APIs for the kernel, in general
By interfacing with the underlying UHC driver
USB File System Module (usbfs)
Uses USB Core to provide Kernel Windows & USB Devices as entries under /sys
Enables writing User Mode USB Drivers
USB Host Device Driver
USB Device specific Driver
Interfaces with the corresponding USB Device through the USB Core
Provides interface to the User Space through the relevant Vertical(s)

7. 7© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
USB Gadget Subsystem View
USB Gadget Device Drivers ...
USB Composite
USB Device / OTG Controller Driver
Kernel Space
USB Host
Hardware Space
USB Device / OTG Controller
Horizontal Layers
Vertical Layers
Peripherals
User Applications
User Space

8. 8© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
USB Gadget Subsystem
UDC Driver (*udc)
Hardware-specific USB Device Controller driver
Hides all the hardware details from the layers above
Provides a uniform interface to USB Composite
USB Composite Module (libcomposite)
Provides the generic USB Protocol APIs for the kernel, in general
By interfacing with the underlying UDC driver
USB Gadget Device Driver
USB Device specific Driver
Interfaces with the USB Host through the USB Composite
Exposes peripherals &/or (virtual) functionalities to the Host
May provide (virtual) functionalities to the User Space through the relevant
Layer(s) / Driver(s)

9. 9© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
USB Host & sysfs
Command: /sbin/lspci
<dom>:<bus>:<dev>:<fn> for <usbhubid>
Kernel Window
/sys/devices/pci0000:00/<usbhubid>/usb<hub>
usb_device fields
roothub-hubport:config.interface
usb_interface fields
PCI USB HC functions -> USB buses
/sys/kernel/debug/usb/devices

10. 10© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
USB Device Overview (Protocol)
Device
Config Interface
Endpoint
...
Endpoint
Endpoint
...
Interface
USB
Driver
USB
Driver
...

11. 11© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
USB Device Endpoints
Also called Pipes
Direction
OUT (host->device)
IN (device->host)
Four Types
Control
Interrupt
Bulk
Isochronous

12. 12© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
USB Host Device Driver

13. 13© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
USB Host Driver Data Structures
Header: <linux/usb.h>
Data Structures
struct usb_device
struct usb_host_config
struct usb_interface
interface_to_usbdev
struct usb_host_endpoint
struct usb_endpoint_descriptor

14. 14© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
USB Core Functionality
USB Host Device Driver Registration
USB Host Device Hot Plugability
probe: Vertical Registration
disconnect: Vertical Unregistration
USB Transfers through URBs

15. 15© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
USB Host Device Driver Registration
Header: <linux/usb.h>
Data Structure: struct usb_driver
struct module *owner
const char *name
const struct usb_device_id *id_table
int (*probe)(struct usb_interface *, struct usb_device_id *)
int (*disconnect)(struct usb_interface *)
APIs
int usb_register(struct usb_driver *);
int usb_deregister(struct usb_driver *);

16. 16© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
USB Host Device Hot-plug-ability
Callback probe
int usb_register_dev(intf, class);
Callback disconnect
int usb_deregister_dev(intf, class);
Other Useful APIs (Header: <linux/usb.h>
void usb_set_intfdata(intf, void *data);
void *usb_get_intfdata(intf);

17. 17© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
USB Request Block
Header: <linux/usb.h>
Data Structure: struct urb
struct usb_device *dev
unsigned int pipe
unsigned int transfer_flags
void *transfer_buffer
int transfer_buffer_length
usb_complete_t complete
int actual_length
int status
Pipe type specific fields

18. 18© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
URB Operations
Header: <linux/usb.h>
URB Storage
usb_alloc_urb(int iso_pkts, gfp_t flags);
usb_free_urb(struct urb *);
Populating the URB
usb_fill_control_urb(urb, dev, pipe, req, buf, len, fn, ctxt);
usb_fill_int_urb(urb, dev, pipe, buf, len, fn, ctxt, interval);
usb_fill_bulk_urb(urb, dev, pipe, buf, len, fn, ctxt);
Using the URB
usb_submit_urb(struct urb *, gfp_t flags);
usb_unlink_urb(struct urb *) / usb_kill_urb(struct urb *);

19. 19© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
URB Operations' Wrappers
Header: <linux/usb.h>
APIs
usb_control_msg(dev, pipe, req, req_type, value,
index, data, size, timeout);
usb_interrupt_msg(dev, pipe, data, len, &act_len,
timeout);
usb_bulk_msg(dev, pipe, data, len, &act_len,
timeout);

20. 20© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
USB Gadget Device Driver

21. 21© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
USB Gadget Data Structures
Header: <linux/usb/composite.h>
Data Structures
struct usb_device_descriptor
struct usb_gadget_strings
struct usb_string
struct usb_configuration
struct usb_descriptor_header
struct usb_interface_descriptor
struct usb_endpoint_descriptor

22. 22© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
USB Composite Functionality
USB Gadget Device Driver Registration
USB Gadget Device Creation
bind: Gadget Setup
unbind: Gadget Cleanup
USB Gadget Endpoint Interactions

23. 23© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
USB Gadget Driver Registration
Header: <linux/usb/composite.h>
Data Structure: struct usb_composite_driver
const char *name
const struct usb_device_descriptor *dev
struct usb_gadget_strings **strings
enum usb_device_speed max_speed
int (*bind)(struct usb_composite_dev *cdev)
int (*unbind)(struct usb_composite_dev *cdev)
APIs
int usb_composite_probe(struct usb_composite_driver *driver);
void usb_composite_unregister(struct usb_composite_driver *driver);

24. 24© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
USB Gadget Device Creation
Header: <linux/usb/composite.h>
Callback bind
int usb_string_ids_tab(struct usb_composite_dev *c,
struct usb_string *str);
int usb_add_config_only(comp_dev, usb_cfg)
int usb_add_function(usb_cfg, usb_fn);
Callback unbind
int usb_put_function(usb_fn);
// int usb_remove_function(usb_cfg, usb_fn);

25. 25© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
USB Gadget Function Addition
Header: <linux/usb/composite.h>
Callbacks in struct usb_function:
int (*bind)(struct usb_configuration *c, struct usb_function *f);
void (*unbind)(struct usb_configuration *c, struct usb_function *f);
void (*free_func)(struct usb_function *f);
int (*set_alt)(struct usb_function *f, unsigned interface, unsigned alt); // Must
int (*get_alt)(struct usb_function *f, unsigned interface);
void (*disable)(struct usb_function *f); // Must
int (*setup)(struct usb_function *f, const struct usb_ctrlrequest *ctrlreq);
...

26. 26© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
USB Gadget Descriptors Addition
Header: <linux/usb/gadget.h>
Through <linux/usb/composite.h>
Typical invocations through function's bind / unbind/free_func:
int usb_interface_id(struct usb_configuration *c, struct usb_function *f);
int usb_string_id(struct usb_composite_dev *c);
struct usb_ep *usb_ep_autoconfig(struct usb_gadget *gadget,
struct usb_endpoint_descriptor *usb_ep);
void usb_ep_autoconfig_reset(struct usb_gadget *gadget);
int usb_assign_descriptors(struct usb_function *f,
struct usb_descriptor_header **fs,
struct usb_descriptor_header **hs,
struct usb_descriptor_header **ss);
void usb_free_all_descriptors(struct usb_function *f);

27. 27© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
USB Gadget Endpoint Interactions
Header: <linux/usb/gadget.h>
Through <linux/usb/composite.h>
Typical (Endpoint Interaction) APIs for set_alt / disable:
int usb_ep_enable(struct usb_ep *ep);
int usb_ep_disable(struct usb_ep *ep);
struct usb_request *usb_ep_alloc_request(struct usb_ep *ep, gfp_t
gfp_flags);
void usb_ep_free_request(struct usb_ep *ep, struct usb_request *req);
int usb_ep_queue(struct usb_ep *ep, struct usb_request *req, gfp_t
gfp_flags);
int usb_ep_dequeue(struct usb_ep *ep, struct usb_request *req);
...

28. 28© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
USB Gadget Endpoint Request
Header: <linux/usb/gadget.h>
Through <linux/usb/composite.h>
Data Structure: struct usb_request
void *buf
unsigned length
void (*complete)(struct usb_ep *ep, struct usb_request *req);
int status
unsigned actual
...
APIs: As mentioned under “Endpoint Interactions”

29. 29© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
USB Gadget Function Driver
Registration
Header: <linux/usb/composite.h>
Data Structure: struct usb_function_driver
const char *name
struct usb_function_instance *(*alloc_inst)(void);
struct usb_function *(*alloc_func)(struct usb_function_instance *inst);
DECLARE_USB_FUNCTION(fn_name, fn_alloc_instance, fn_alloc);
APIs
int usb_function_register(struct usb_function_driver *);
int usb_function_unregister(struct usb_function_driver *);
Useful APIs for the function user gadget driver
struct usb_function_instance *usb_get_function_instance(char *fn);
struct usb_function *usb_get_function(struct usb_function_instance *);

30. 30© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
What all have we learnt?
Evolution of USB
USB Subsystem
Host: The Four Components
Gadget: The Three Components
Understanding of USB Protocol
USB Device Overview
Writing USB Host Device Drivers
Registration
Hot Plug-ability
Transfers
Writing USB Gadget Device Drivers
Registration
Gadget Device Creation
Function & Descriptors Addition
Endpoint Interactions
Writing USB Gadget Function Drivers

31. 31© 2010-15 SysPlay Workshops <workshop@sysplay.in>
All Rights Reserved.
Any Queries?