diff options
Diffstat (limited to 'Documentation/driver-api/usb')
| -rw-r--r-- | Documentation/driver-api/usb/URB.rst | 4 | ||||
| -rw-r--r-- | Documentation/driver-api/usb/bulk-streams.rst | 4 | ||||
| -rw-r--r-- | Documentation/driver-api/usb/callbacks.rst | 6 | ||||
| -rw-r--r-- | Documentation/driver-api/usb/dma.rst | 54 | ||||
| -rw-r--r-- | Documentation/driver-api/usb/dwc3.rst | 2 | ||||
| -rw-r--r-- | Documentation/driver-api/usb/error-codes.rst | 3 | ||||
| -rw-r--r-- | Documentation/driver-api/usb/gadget.rst | 10 | ||||
| -rw-r--r-- | Documentation/driver-api/usb/hotplug.rst | 2 | ||||
| -rw-r--r-- | Documentation/driver-api/usb/typec_bus.rst | 30 | ||||
| -rw-r--r-- | Documentation/driver-api/usb/usb.rst | 25 | ||||
| -rw-r--r-- | Documentation/driver-api/usb/usb3-debug-port.rst | 2 | ||||
| -rw-r--r-- | Documentation/driver-api/usb/writing_musb_glue_layer.rst | 6 | ||||
| -rw-r--r-- | Documentation/driver-api/usb/writing_usb_driver.rst | 56 |
13 files changed, 91 insertions, 113 deletions
diff --git a/Documentation/driver-api/usb/URB.rst b/Documentation/driver-api/usb/URB.rst index 61a54da9fce9..a182c0f5e38a 100644 --- a/Documentation/driver-api/usb/URB.rst +++ b/Documentation/driver-api/usb/URB.rst @@ -47,7 +47,7 @@ called USB Request Block, or URB for short. The URB structure ================= -Some of the fields in struct :c:type:`urb` are:: +Some of the fields in struct urb are:: struct urb { @@ -240,7 +240,7 @@ How to do isochronous (ISO) transfers? ====================================== Besides the fields present on a bulk transfer, for ISO, you also -also have to set ``urb->interval`` to say how often to make transfers; it's +have to set ``urb->interval`` to say how often to make transfers; it's often one per frame (which is once every microframe for highspeed devices). The actual interval used will be a power of two that's no bigger than what you specify. You can use the :c:func:`usb_fill_int_urb` macro to fill diff --git a/Documentation/driver-api/usb/bulk-streams.rst b/Documentation/driver-api/usb/bulk-streams.rst index 99b515babdeb..eeefe582f8ff 100644 --- a/Documentation/driver-api/usb/bulk-streams.rst +++ b/Documentation/driver-api/usb/bulk-streams.rst @@ -9,9 +9,9 @@ device driver to overload a bulk endpoint so that multiple transfers can be queued at once. Streams are defined in sections 4.4.6.4 and 8.12.1.4 of the Universal Serial Bus -3.0 specification at http://www.usb.org/developers/docs/ The USB Attached SCSI +3.0 specification at https://www.usb.org/developers/docs/ The USB Attached SCSI Protocol, which uses streams to queue multiple SCSI commands, can be found on -the T10 website (http://t10.org/). +the T10 website (https://t10.org/). Device-side implications diff --git a/Documentation/driver-api/usb/callbacks.rst b/Documentation/driver-api/usb/callbacks.rst index 2b80cf54bcc3..927da49b8f00 100644 --- a/Documentation/driver-api/usb/callbacks.rst +++ b/Documentation/driver-api/usb/callbacks.rst @@ -99,8 +99,10 @@ The disconnect() callback This callback is a signal to break any connection with an interface. You are not allowed any IO to a device after returning from this callback. You also may not do any other operation that may interfere -with another driver bound the interface, eg. a power management -operation. +with another driver bound to the interface, eg. a power management +operation. Outstanding operations on the device must be completed or +aborted before this callback may return. + If you are called due to a physical disconnection, all your URBs will be killed by usbcore. Note that in this case disconnect will be called some time after the physical disconnection. Thus your driver must be prepared diff --git a/Documentation/driver-api/usb/dma.rst b/Documentation/driver-api/usb/dma.rst index 59d5aee89e37..02f6825ff830 100644 --- a/Documentation/driver-api/usb/dma.rst +++ b/Documentation/driver-api/usb/dma.rst @@ -10,7 +10,7 @@ API overview The big picture is that USB drivers can continue to ignore most DMA issues, though they still must provide DMA-ready buffers (see -``Documentation/DMA-API-HOWTO.txt``). That's how they've worked through +Documentation/core-api/dma-api-howto.rst). That's how they've worked through the 2.4 (and earlier) kernels, or they can now be DMA-aware. DMA-aware usb drivers: @@ -60,7 +60,7 @@ and effects like cache-trashing can impose subtle penalties. force a consistent memory access ordering by using memory barriers. It's not using a streaming DMA mapping, so it's good for small transfers on systems where the I/O would otherwise thrash an IOMMU mapping. (See - ``Documentation/DMA-API-HOWTO.txt`` for definitions of "coherent" and + Documentation/core-api/dma-api-howto.rst for definitions of "coherent" and "streaming" DMA mappings.) Asking for 1/Nth of a page (as well as asking for N pages) is reasonably @@ -91,46 +91,20 @@ Working with existing buffers Existing buffers aren't usable for DMA without first being mapped into the DMA address space of the device. However, most buffers passed to your driver can safely be used with such DMA mapping. (See the first section -of Documentation/DMA-API-HOWTO.txt, titled "What memory is DMA-able?") +of Documentation/core-api/dma-api-howto.rst, titled "What memory is DMA-able?") -- When you're using scatterlists, you can map everything at once. On some - systems, this kicks in an IOMMU and turns the scatterlists into single - DMA transactions:: +- When you have the scatterlists which have been mapped for the USB controller, + you could use the new ``usb_sg_*()`` calls, which would turn scatterlist + into URBs:: - int usb_buffer_map_sg (struct usb_device *dev, unsigned pipe, - struct scatterlist *sg, int nents); + int usb_sg_init(struct usb_sg_request *io, struct usb_device *dev, + unsigned pipe, unsigned period, struct scatterlist *sg, + int nents, size_t length, gfp_t mem_flags); - void usb_buffer_dmasync_sg (struct usb_device *dev, unsigned pipe, - struct scatterlist *sg, int n_hw_ents); + void usb_sg_wait(struct usb_sg_request *io); - void usb_buffer_unmap_sg (struct usb_device *dev, unsigned pipe, - struct scatterlist *sg, int n_hw_ents); + void usb_sg_cancel(struct usb_sg_request *io); - It's probably easier to use the new ``usb_sg_*()`` calls, which do the DMA - mapping and apply other tweaks to make scatterlist i/o be fast. - -- Some drivers may prefer to work with the model that they're mapping large - buffers, synchronizing their safe re-use. (If there's no re-use, then let - usbcore do the map/unmap.) Large periodic transfers make good examples - here, since it's cheaper to just synchronize the buffer than to unmap it - each time an urb completes and then re-map it on during resubmission. - - These calls all work with initialized urbs: ``urb->dev``, ``urb->pipe``, - ``urb->transfer_buffer``, and ``urb->transfer_buffer_length`` must all be - valid when these calls are used (``urb->setup_packet`` must be valid too - if urb is a control request):: - - struct urb *usb_buffer_map (struct urb *urb); - - void usb_buffer_dmasync (struct urb *urb); - - void usb_buffer_unmap (struct urb *urb); - - The calls manage ``urb->transfer_dma`` for you, and set - ``URB_NO_TRANSFER_DMA_MAP`` so that usbcore won't map or unmap the buffer. - They cannot be used for setup_packet buffers in control requests. - -Note that several of those interfaces are currently commented out, since -they don't have current users. See the source code. Other than the dmasync -calls (where the underlying DMA primitives have changed), most of them can -easily be commented back in if you want to use them. + When the USB controller doesn't support DMA, the ``usb_sg_init()`` would try + to submit URBs in PIO way as long as the page in scatterlists is not in the + Highmem, which could be very rare in modern architectures. diff --git a/Documentation/driver-api/usb/dwc3.rst b/Documentation/driver-api/usb/dwc3.rst index 8b36ff11cef9..e3d6a620997f 100644 --- a/Documentation/driver-api/usb/dwc3.rst +++ b/Documentation/driver-api/usb/dwc3.rst @@ -18,7 +18,7 @@ controller which can be configured in one of 4 ways: 4. Hub configuration Linux currently supports several versions of this controller. In all -likelyhood, the version in your SoC is already supported. At the time +likelihood, the version in your SoC is already supported. At the time of this writing, known tested versions range from 2.02a to 3.10a. As a rule of thumb, anything above 2.02a should work reliably well. diff --git a/Documentation/driver-api/usb/error-codes.rst b/Documentation/driver-api/usb/error-codes.rst index a3e84bfac776..8f9790c2d6f8 100644 --- a/Documentation/driver-api/usb/error-codes.rst +++ b/Documentation/driver-api/usb/error-codes.rst @@ -61,6 +61,9 @@ USB-specific: (c) requested data transfer length is invalid: negative or too large for the host controller. +``-EBADR`` The wLength value in a control URB's setup packet does + not match the URB's transfer_buffer_length. + ``-ENOSPC`` This request would overcommit the usb bandwidth reserved for periodic transfers (interrupt, isochronous). diff --git a/Documentation/driver-api/usb/gadget.rst b/Documentation/driver-api/usb/gadget.rst index 3e8a3809c0b8..09396edd6131 100644 --- a/Documentation/driver-api/usb/gadget.rst +++ b/Documentation/driver-api/usb/gadget.rst @@ -176,9 +176,9 @@ Kernel Mode Gadget API Gadget drivers declare themselves through a struct :c:type:`usb_gadget_driver`, which is responsible for most parts of enumeration -for a struct :c:type:`usb_gadget`. The response to a set_configuration usually -involves enabling one or more of the struct :c:type:`usb_ep` objects exposed by -the gadget, and submitting one or more struct :c:type:`usb_request` buffers to +for a struct usb_gadget. The response to a set_configuration usually +involves enabling one or more of the struct usb_ep objects exposed by +the gadget, and submitting one or more struct usb_request buffers to transfer data. Understand those four data types, and their operations, and you will understand how this API works. @@ -339,8 +339,8 @@ multi-configuration devices (also more than one function, but not necessarily sharing a given configuration). There is however an optional framework which makes it easier to reuse and combine functions. -Devices using this framework provide a struct :c:type:`usb_composite_driver`, -which in turn provides one or more struct :c:type:`usb_configuration` +Devices using this framework provide a struct usb_composite_driver, +which in turn provides one or more struct usb_configuration instances. Each such configuration includes at least one struct :c:type:`usb_function`, which packages a user visible role such as "network link" or "mass storage device". Management functions may also exist, diff --git a/Documentation/driver-api/usb/hotplug.rst b/Documentation/driver-api/usb/hotplug.rst index 79663e653ca1..c1e13107c50e 100644 --- a/Documentation/driver-api/usb/hotplug.rst +++ b/Documentation/driver-api/usb/hotplug.rst @@ -122,7 +122,7 @@ and their quirks, might have a MODULE_DEVICE_TABLE like this:: Most USB device drivers should pass these tables to the USB subsystem as well as to the module management subsystem. Not all, though: some driver frameworks connect using interfaces layered over USB, and so they won't -need such a struct :c:type:`usb_driver`. +need such a struct usb_driver. Drivers that connect directly to the USB subsystem should be declared something like this:: diff --git a/Documentation/driver-api/usb/typec_bus.rst b/Documentation/driver-api/usb/typec_bus.rst index f47a69bff498..21c890ae17e5 100644 --- a/Documentation/driver-api/usb/typec_bus.rst +++ b/Documentation/driver-api/usb/typec_bus.rst @@ -53,9 +53,7 @@ in need to reconfigure the pins on the connector, the alternate mode driver needs to notify the bus using :c:func:`typec_altmode_notify()`. The driver passes the negotiated SVID specific pin configuration value to the function as parameter. The bus driver will then configure the mux behind the connector using -that value as the state value for the mux, and also call blocking notification -chain to notify the external drivers about the state of the connector that need -to know it. +that value as the state value for the mux. NOTE: The SVID specific pin configuration values must always start from ``TYPEC_STATE_MODAL``. USB Type-C specification defines two default states for @@ -80,19 +78,6 @@ Helper macro ``TYPEC_MODAL_STATE()`` can also be used:: #define ALTMODEX_CONF_A = TYPEC_MODAL_STATE(0); #define ALTMODEX_CONF_B = TYPEC_MODAL_STATE(1); -Notification chain -~~~~~~~~~~~~~~~~~~ - -The drivers for the components that the alternate modes are designed for need to -get details regarding the results of the negotiation with the partner, and the -pin configuration of the connector. In case of DisplayPort alternate mode for -example, the GPU drivers will need to know those details. In case of -Thunderbolt alternate mode, the thunderbolt drivers will need to know them, and -so on. - -The notification chain is designed for this purpose. The drivers can register -notifiers with :c:func:`typec_altmode_register_notifier()`. - Cable plug alternate modes ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -106,10 +91,16 @@ their control. Driver API ---------- +Alternate mode structs +~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: include/linux/usb/typec_altmode.h + :functions: typec_altmode_driver typec_altmode_ops + Alternate mode driver registering/unregistering ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. kernel-doc:: drivers/usb/typec/bus.c +.. kernel-doc:: include/linux/usb/typec_altmode.h :functions: typec_altmode_register_driver typec_altmode_unregister_driver Alternate mode driver operations @@ -129,8 +120,3 @@ Cable Plug operations .. kernel-doc:: drivers/usb/typec/bus.c :functions: typec_altmode_get_plug typec_altmode_put_plug - -Notifications -~~~~~~~~~~~~~ -.. kernel-doc:: drivers/usb/typec/class.c - :functions: typec_altmode_register_notifier typec_altmode_unregister_notifier diff --git a/Documentation/driver-api/usb/usb.rst b/Documentation/driver-api/usb/usb.rst index 078e981e2b16..fb41768696ec 100644 --- a/Documentation/driver-api/usb/usb.rst +++ b/Documentation/driver-api/usb/usb.rst @@ -109,13 +109,19 @@ well as to make sure they aren't relying on some HCD-specific behavior. USB-Standard Types ================== -In ``<linux/usb/ch9.h>`` you will find the USB data types defined in -chapter 9 of the USB specification. These data types are used throughout +In ``include/uapi/linux/usb/ch9.h`` you will find the USB data types defined +in chapter 9 of the USB specification. These data types are used throughout USB, and in APIs including this host side API, gadget APIs, usb character -devices and debugfs interfaces. +devices and debugfs interfaces. That file is itself included by +``include/linux/usb/ch9.h``, which also contains declarations of a few +utility routines for manipulating these data types; the implementations +are in ``drivers/usb/common/common.c``. -.. kernel-doc:: include/linux/usb/ch9.h - :internal: +.. kernel-doc:: drivers/usb/common/common.c + :export: + +In addition, some functions useful for creating debugging output are +defined in ``drivers/usb/common/debug.c``. .. _usb_header: @@ -414,6 +420,12 @@ USBDEVFS_CONNECTINFO know the devnum value already, it's the DDD value of the device file name. +USBDEVFS_GET_SPEED + Returns the speed of the device. The speed is returned as a + nummerical value in accordance with enum usb_device_speed + + File modification time is not updated by this request. + USBDEVFS_GETDRIVER Returns the name of the kernel driver bound to a given interface (a string). Parameter is a pointer to this structure, which is @@ -765,8 +777,7 @@ Speed may be: ======= ====================================================== 1.5 Mbit/s for low speed USB 12 Mbit/s for full speed USB - 480 Mbit/s for high speed USB (added for USB 2.0); - also used for Wireless USB, which has no fixed speed + 480 Mbit/s for high speed USB (added for USB 2.0) 5000 Mbit/s for SuperSpeed USB (added for USB 3.0) ======= ====================================================== diff --git a/Documentation/driver-api/usb/usb3-debug-port.rst b/Documentation/driver-api/usb/usb3-debug-port.rst index b9fd131f4723..d4610457b052 100644 --- a/Documentation/driver-api/usb/usb3-debug-port.rst +++ b/Documentation/driver-api/usb/usb3-debug-port.rst @@ -48,7 +48,7 @@ kernel boot parameter:: "earlyprintk=xdbc" If there are multiple xHCI controllers in your system, you can -append a host contoller index to this kernel parameter. This +append a host controller index to this kernel parameter. This index starts from 0. Current design doesn't support DbC runtime suspend/resume. As diff --git a/Documentation/driver-api/usb/writing_musb_glue_layer.rst b/Documentation/driver-api/usb/writing_musb_glue_layer.rst index 5bf7152fd76f..10416cc11cd5 100644 --- a/Documentation/driver-api/usb/writing_musb_glue_layer.rst +++ b/Documentation/driver-api/usb/writing_musb_glue_layer.rst @@ -707,12 +707,12 @@ cheerful guidance and support. Resources ========= -USB Home Page: http://www.usb.org +USB Home Page: https://www.usb.org -linux-usb Mailing List Archives: http://marc.info/?l=linux-usb +linux-usb Mailing List Archives: https://marc.info/?l=linux-usb USB On-the-Go Basics: -http://www.maximintegrated.com/app-notes/index.mvp/id/1822 +https://www.maximintegrated.com/app-notes/index.mvp/id/1822 :ref:`Writing USB Device Drivers <writing-usb-driver>` diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst b/Documentation/driver-api/usb/writing_usb_driver.rst index 4fe1c06b6a13..95c4f5d14052 100644 --- a/Documentation/driver-api/usb/writing_usb_driver.rst +++ b/Documentation/driver-api/usb/writing_usb_driver.rst @@ -57,9 +57,12 @@ structure. The skeleton driver declares a :c:type:`usb_driver` as:: .name = "skeleton", .probe = skel_probe, .disconnect = skel_disconnect, - .fops = &skel_fops, - .minor = USB_SKEL_MINOR_BASE, + .suspend = skel_suspend, + .resume = skel_resume, + .pre_reset = skel_pre_reset, + .post_reset = skel_post_reset, .id_table = skel_table, + .supports_autosuspend = 1, }; @@ -81,7 +84,7 @@ this user-space interaction. The skeleton driver needs this kind of interface, so it provides a minor starting number and a pointer to its :c:type:`file_operations` functions. -The USB driver is then registered with a call to :c:func:`usb_register`, +The USB driver is then registered with a call to usb_register(), usually in the driver's init function, as shown here:: static int __init usb_skel_init(void) @@ -91,8 +94,8 @@ usually in the driver's init function, as shown here:: /* register this driver with the USB subsystem */ result = usb_register(&skel_driver); if (result < 0) { - err("usb_register failed for the "__FILE__ "driver." - "Error number %d", result); + pr_err("usb_register failed for the %s driver. Error number %d\n", + skel_driver.name, result); return -1; } @@ -102,7 +105,7 @@ usually in the driver's init function, as shown here:: When the driver is unloaded from the system, it needs to deregister -itself with the USB subsystem. This is done with the :c:func:`usb_deregister` +itself with the USB subsystem. This is done with usb_deregister() function:: static void __exit usb_skel_exit(void) @@ -167,8 +170,8 @@ structure. This is done so that future calls to file operations will enable the driver to determine which device the user is addressing. All of this is done with the following code:: - /* increment our usage count for the module */ - ++skel->open_count; + /* increment our usage count for the device */ + kref_get(&dev->kref); /* save our object in the file's private structure */ file->private_data = dev; @@ -185,24 +188,26 @@ space, points the urb to the data and submits the urb to the USB subsystem. This can be seen in the following code:: /* we can only write as much as 1 urb will hold */ - bytes_written = (count > skel->bulk_out_size) ? skel->bulk_out_size : count; + size_t writesize = min_t(size_t, count, MAX_TRANSFER); /* copy the data from user space into our urb */ - copy_from_user(skel->write_urb->transfer_buffer, buffer, bytes_written); + copy_from_user(buf, user_buffer, writesize); /* set up our urb */ - usb_fill_bulk_urb(skel->write_urb, - skel->dev, - usb_sndbulkpipe(skel->dev, skel->bulk_out_endpointAddr), - skel->write_urb->transfer_buffer, - bytes_written, + usb_fill_bulk_urb(urb, + dev->udev, + usb_sndbulkpipe(dev->udev, dev->bulk_out_endpointAddr), + buf, + writesize, skel_write_bulk_callback, - skel); + dev); /* send the data out the bulk port */ - result = usb_submit_urb(skel->write_urb); - if (result) { - err("Failed submitting write urb, error %d", result); + retval = usb_submit_urb(urb, GFP_KERNEL); + if (retval) { + dev_err(&dev->interface->dev, + "%s - failed submitting write urb, error %d\n", + __func__, retval); } @@ -231,7 +236,7 @@ error message. This can be shown with the following code:: skel->bulk_in_endpointAddr), skel->bulk_in_buffer, skel->bulk_in_size, - &count, HZ*10); + &count, 5000); /* if the read was successful, copy the data to user space */ if (!retval) { if (copy_to_user (buffer, skel->bulk_in_buffer, count)) @@ -314,13 +319,10 @@ http://www.linux-usb.org/ Linux Hotplug Project: http://linux-hotplug.sourceforge.net/ -Linux USB Working Devices List: -http://www.qbik.ch/usb/devices/ - -linux-usb-devel Mailing List Archives: -http://marc.theaimsgroup.com/?l=linux-usb-devel +linux-usb Mailing List Archives: +https://lore.kernel.org/linux-usb/ Programming Guide for Linux USB Device Drivers: -http://lmu.web.psi.ch/docu/manuals/software_manuals/linux_sl/usb_linux_programming_guide.pdf +https://lmu.web.psi.ch/docu/manuals/software_manuals/linux_sl/usb_linux_programming_guide.pdf -USB Home Page: http://www.usb.org +USB Home Page: https://www.usb.org |