Linux USB API

• The Linux-USB Host Side API
  • Introduction to USB on Linux
  • USB Host-Side API Model
  • USB-Standard Types
    • usb_ep_type_string()
    • usb_speed_string()
    • usb_get_maximum_speed()
    • usb_get_maximum_ssp_rate()
    • usb_state_string()
    • usb_get_role_switch_default_mode()
    • usb_decode_interval()
    • of_usb_get_dr_mode_by_phy()
    • of_usb_host_tpl_support()
    • of_usb_update_otg_caps()
    • usb_of_get_companion_dev()
  • Host-Side Data Types and Macros
    • usb_host_endpoint
    • usb_interface
    • usb_set_intfdata()
    • usb_interface_cache
    • usb_host_config
    • usb_device
    • usb_hub_for_each_child
    • usb_interface_claimed()
    • usb_make_path()
    • USB_DEVICE
    • USB_DEVICE_VER
    • USB_DEVICE_INTERFACE_CLASS
    • USB_DEVICE_INTERFACE_PROTOCOL
    • USB_DEVICE_INTERFACE_NUMBER
    • USB_DEVICE_INFO
    • USB_INTERFACE_INFO
    • USB_DEVICE_AND_INTERFACE_INFO
    • USB_VENDOR_AND_INTERFACE_INFO
    • usb_driver
    • usb_device_driver
    • usb_class_driver
    • module_usb_driver
    • urb
    • usb_fill_control_urb()
    • usb_fill_bulk_urb()
    • usb_fill_int_urb()
    • usb_urb_dir_in()
    • usb_urb_dir_out()
    • usb_sg_request
  • USB Core APIs
    • usb_init_urb()
    • usb_alloc_urb()
    • usb_free_urb()
    • usb_get_urb()
    • usb_anchor_urb()
    • usb_unanchor_urb()
    • usb_pipe_type_check()
    • usb_urb_ep_type_check()
    • usb_submit_urb()
    • usb_unlink_urb()
    • usb_kill_urb()
    • usb_poison_urb()
    • usb_block_urb()
    • usb_kill_anchored_urbs()
    • usb_poison_anchored_urbs()
    • usb_unpoison_anchored_urbs()
    • usb_unlink_anchored_urbs()
    • usb_anchor_suspend_wakeups()
    • usb_anchor_resume_wakeups()
    • usb_wait_anchor_empty_timeout()
    • usb_get_from_anchor()
    • usb_scuttle_anchored_urbs()
    • usb_anchor_empty()
    • usb_control_msg()
    • usb_control_msg_send()
    • usb_control_msg_recv()
    • usb_interrupt_msg()
    • usb_bulk_msg()
    • usb_sg_init()
    • usb_sg_wait()
    • usb_sg_cancel()
    • usb_get_descriptor()
    • usb_string()
    • usb_cache_string()
    • usb_get_status()
    • usb_clear_halt()
    • usb_reset_endpoint()
    • usb_set_interface()
    • usb_reset_configuration()
    • usb_set_wireless_status()
    • usb_driver_set_configuration()
    • cdc_parse_cdc_header()
    • usb_register_dev()
    • usb_deregister_dev()
    • usb_driver_claim_interface()
    • usb_driver_release_interface()
    • usb_match_id()
    • usb_register_device_driver()
    • usb_deregister_device_driver()
    • usb_register_driver()
    • usb_deregister()
    • usb_enable_autosuspend()
    • usb_disable_autosuspend()
    • usb_autopm_put_interface()
    • usb_autopm_put_interface_async()
    • usb_autopm_put_interface_no_suspend()
    • usb_autopm_get_interface()
    • usb_autopm_get_interface_async()
    • usb_autopm_get_interface_no_resume()
    • usb_find_common_endpoints()
    • usb_find_common_endpoints_reverse()
    • usb_check_bulk_endpoints()
    • usb_check_int_endpoints()
    • usb_find_alt_setting()
    • usb_ifnum_to_if()
    • usb_altnum_to_altsetting()
    • usb_find_interface()
    • usb_for_each_dev()
    • usb_alloc_dev()
    • usb_get_dev()
    • usb_put_dev()
    • usb_get_intf()
    • usb_put_intf()
    • usb_intf_get_dma_device()
    • usb_lock_device_for_reset()
    • usb_get_current_frame_number()
    • usb_alloc_coherent()
    • usb_free_coherent()
    • usb_hub_clear_tt_buffer()
    • usb_set_device_state()
    • usb_root_hub_lost_power()
    • usb_reset_device()
    • usb_queue_reset_device()
    • usb_hub_find_child()
  • Host Controller APIs
    • usb_calc_bus_time()
    • usb_hcd_link_urb_to_ep()
    • usb_hcd_check_unlink_urb()
    • usb_hcd_unlink_urb_from_ep()
    • usb_hcd_giveback_urb()
    • usb_alloc_streams()
    • usb_free_streams()
    • usb_hcd_resume_root_hub()
    • usb_bus_start_enum()
    • usb_hcd_irq()
    • usb_hc_died()
    • usb_create_shared_hcd()
    • usb_create_hcd()
    • usb_add_hcd()
    • usb_remove_hcd()
    • usb_hcd_pci_probe()
    • usb_hcd_pci_remove()
    • usb_hcd_pci_shutdown()
    • hcd_buffer_create()
    • hcd_buffer_destroy()
  • The USB character device nodes
    • What files are in “devtmpfs”?
    • /dev/bus/usb/BBB/DDD
    • Life Cycle of User Mode Drivers
    • The ioctl() Requests
      • Management/Status Requests
      • Synchronous I/O Support
      • Asynchronous I/O Support
  • The USB devices
    • /sys/kernel/debug/usb/devices
      • /sys/kernel/debug/usb/devices output format
        • Topology info
        • Bandwidth info
        • Device descriptor info & Product ID info
        • String descriptor info
        • Configuration descriptor info
        • Interface descriptor info (can be multiple per Config)
        • Endpoint descriptor info (can be multiple per Interface)
      • Usage examples
• USB Gadget API for Linux
  • Introduction
  • Structure of Gadget Drivers
  • Kernel Mode Gadget API
    • Driver Life Cycle
    • USB 2.0 Chapter 9 Types and Constants
    • Core Objects and Methods
      • usb_request
      • usb_ep_caps
      • usb_ep
      • free_usb_request()
      • usb_gadget
      • usb_ep_align()
      • usb_ep_align_maybe()
      • gadget_is_altset_supported()
      • gadget_is_stall_supported()
      • gadget_is_zlp_supported()
      • gadget_avoids_skb_reserve()
      • gadget_is_dualspeed()
      • gadget_is_superspeed()
      • gadget_is_superspeed_plus()
      • gadget_is_otg()
      • usb_gadget_driver
      • usb_gadget_register_driver_owner()
      • usb_gadget_unregister_driver()
      • usb_string
      • usb_gadget_strings
      • usb_free_descriptors()
    • Optional Utilities
      • usb_gadget_get_string()
      • usb_validate_langid()
      • usb_descriptor_fillbuf()
      • usb_gadget_config_buf()
      • usb_copy_descriptors()
    • Composite Device Framework
      • usb_os_desc_ext_prop
      • usb_os_desc
      • usb_os_desc_table
      • usb_function
      • usb_configuration
      • usb_composite_driver
      • module_usb_composite_driver
      • usb_composite_dev
      • config_ep_by_speed_and_alt()
      • config_ep_by_speed()
      • usb_add_function()
      • usb_function_deactivate()
      • usb_function_activate()
      • usb_interface_id()
      • usb_func_wakeup()
      • usb_add_config()
      • usb_string_id()
      • usb_string_ids_tab()
      • usb_gstrings_attach()
      • usb_string_ids_n()
      • usb_composite_probe()
      • usb_composite_unregister()
      • usb_composite_setup_continue()
    • Composite Device Functions
  • Peripheral Controller Drivers
  • Gadget Drivers
  • USB On-The-GO (OTG)
• USB Anchors
  • What is anchor?
  • Allocation and Initialisation
  • Deallocation
  • Association and disassociation of URBs with anchors
  • Operations on multitudes of URBs
    • usb_kill_anchored_urbs()
    • usb_unlink_anchored_urbs()
    • usb_scuttle_anchored_urbs()
    • usb_wait_anchor_empty_timeout()
    • usb_anchor_empty()
    • usb_get_from_anchor()
• USB bulk streams
  • Background
  • Device-side implications
  • Driver implications
  • Picking new Stream IDs to use
  • Clean up
• USB core callbacks
  • What callbacks will usbcore do?
  • Calling conventions
  • Hotplugging callbacks
    • The probe() callback
    • The disconnect() callback
  • Device level callbacks
    • pre_reset
    • post_reset
  • Call sequences
• USB DMA
  • API overview
  • Eliminating copies
  • Working with existing buffers
• USB Request Block (URB)
  • Basic concept or ‘What is an URB?’
  • The URB structure
  • How to get an URB?
  • What has to be filled in?
  • How to submit an URB?
  • How to cancel an already running URB?
  • What about the completion handler?
  • How to do isochronous (ISO) transfers?
  • How to start interrupt (INT) transfers?
• Power Management for USB
  • What is Power Management?
  • What is Remote Wakeup?
  • When is a USB device idle?
  • Forms of dynamic PM
  • The user interface for dynamic PM
  • Changing the default idle-delay time
  • Warnings
  • The driver interface for Power Management
  • The driver interface for autosuspend and autoresume
  • Other parts of the driver interface
  • Mutual exclusion
  • Interaction between dynamic PM and system PM
  • xHCI hardware link PM
  • USB Port Power Control
  • User Interface for Port Power Control
  • Suggested Userspace Port Power Policy
• USB hotplugging
  • Linux Hotplugging
  • Kernel Hotplug Helper (/sbin/hotplug)
  • USB Policy Agent
  • USB Modutils Support
• USB device persistence during system suspend
  • What is the problem?
  • What is the solution?
  • Is this the best solution?
  • WARNING: USB-persist can be dangerous!!
• USB Error codes
  • Error codes returned by usb_submit_urb()
  • Error codes returned by in urb->status or in iso_frame_desc[n].status (for ISO)
  • Error codes returned by usbcore-functions
• Writing USB Device Drivers
  • Introduction
  • Linux USB Basics
  • Device operation
  • Isochronous Data
  • Conclusion
  • Resources
• Synopsys DesignWare Core SuperSpeed USB 3.0 Controller
  • Introduction
  • Summary of Features
  • Driver Design
  • Known Limitations
    • OUT Transfer Size Requirements
    • TRB Ring Size Limitation
  • Reporting Bugs
    • Required Information
  • Debugging
    • DebugFS
      • link_state
      • regdump
      • testmode
      • ep[0..15]{in,out}
        • transfer_type
        • trb_ring
    • Trace Events
      • MMIO
      • Interrupt Events
      • Control Request
      • Lifetime of a struct usb_request
      • Generic Commands
      • Endpoint Commands
      • Lifetime of a TRB
      • Lifetime of an Endpoint
  • Structures, Methods and Definitions
    • dwc3_event_buffer
    • dwc3_ep
    • dwc3_trb
    • dwc3_hwparams
    • dwc3_request
    • dwc3
    • dwc3_event_depevt
    • dwc3_event_devt
    • dwc3_event_gevt
    • dwc3_event
    • dwc3_gadget_ep_cmd_params
    • dwc3_mdwidth()
    • next_request()
    • dwc3_gadget_move_started_request()
    • dwc3_gadget_move_cancelled_request()
    • dwc3_gadget_ep_get_transfer_index()
    • dwc3_gadget_dctl_write_safe()
    • dwc3_gadget_set_test_mode()
    • dwc3_gadget_get_link_state()
    • dwc3_gadget_set_link_state()
    • dwc3_ep_inc_trb()
    • dwc3_ep_inc_enq()
    • dwc3_ep_inc_deq()
    • dwc3_gadget_giveback()
    • dwc3_send_gadget_generic_command()
    • dwc3_send_gadget_ep_cmd()
    • dwc3_gadget_start_config()
    • dwc3_gadget_calc_tx_fifo_size()
    • dwc3_gadget_calc_ram_depth()
    • dwc3_gadget_clear_tx_fifos()
    • __dwc3_gadget_ep_enable()
    • __dwc3_gadget_ep_disable()
    • dwc3_ep_prev_trb()
    • dwc3_prepare_one_trb()
    • dwc3_prepare_last_sg()
    • __dwc3_stop_active_transfer()
    • dwc3_gadget_start_isoc_quirk()
    • dwc3_gadget_setup_nump()
    • dwc3_gadget_check_config()
    • dwc3_gadget_init()
    • dwc3_get_dr_mode()
    • dwc3_core_soft_reset()
    • dwc3_ref_clk_period()
    • dwc3_free_one_event_buffer()
    • dwc3_alloc_one_event_buffer()
    • dwc3_free_event_buffers()
    • dwc3_alloc_event_buffers()
    • dwc3_event_buffers_setup()
    • dwc3_phy_setup()
    • dwc3_core_init()
• Writing a MUSB Glue Layer
  • Introduction
  • Linux MUSB Basics
  • Handling IRQs
  • Device Platform Data
  • Device Quirks
  • Conclusion
  • Acknowledgements
  • Resources
• USB Type-C connector class
  • Introduction
  • User space interface
  • Driver API
    • Registering the ports
      • typec_register_port()
      • typec_unregister_port()
    • Registering Partners
      • typec_register_partner()
      • typec_unregister_partner()
      • typec_partner_set_identity()
    • Registering Cables
      • typec_register_plug()
      • typec_unregister_plug()
      • typec_register_cable()
      • typec_unregister_cable()
      • typec_cable_set_identity()
    • Notifications
      • typec_set_data_role()
      • typec_set_pwr_role()
      • typec_set_vconn_role()
      • typec_set_pwr_opmode()
    • Alternate Modes
      • typec_port_register_altmode()
      • typec_partner_register_altmode()
      • typec_plug_register_altmode()
      • typec_unregister_altmode()
      • typec_altmode_update_active()
    • Multiplexer/DeMultiplexer Switches
      • typec_switch_register()
      • typec_switch_unregister()
      • typec_mux_register()
      • typec_mux_unregister()
      • typec_set_orientation()
      • typec_set_mode()
• API for USB Type-C Alternate Mode drivers
  • Introduction
  • Usage:
    • General
    • Cable plug alternate modes
  • Driver API
    • Alternate mode structs
      • typec_altmode_ops
      • typec_altmode_driver
    • Alternate mode driver registering/unregistering
      • typec_altmode_register_driver
      • typec_altmode_unregister_driver()
    • Alternate mode driver operations
      • typec_altmode_notify()
      • typec_altmode_enter()
      • typec_altmode_exit()
      • typec_altmode_attention()
      • typec_altmode_vdm()
    • API for the port drivers
      • typec_match_altmode()
    • Cable Plug operations
      • typec_altmode_get_plug()
      • typec_altmode_put_plug()
• USB3 debug port
  • GENERAL
  • INTRODUCTION
  • EARLY PRINTK
  • Serial TTY