* [PATCH 02/22] docs-rst: convert usb docbooks to ReST
2017-03-29 18:54 [PATCH 01/22] driver-api/basics.rst: add device table header Mauro Carvalho Chehab
@ 2017-03-29 18:54 ` Mauro Carvalho Chehab
2017-03-30 7:48 ` Markus Heiser
2017-03-29 18:54 ` [PATCH 03/22] usb.rst: Enrich its ReST representation Mauro Carvalho Chehab
` (20 subsequent siblings)
21 siblings, 1 reply; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-29 18:54 UTC (permalink / raw)
To: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, John Youn,
linux-usb, linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab, Jani Nikula, Markus Heiser, Takashi Iwai,
Daniel Vetter, Oliver Neukum, Martyn Welch, Alexander Dahl,
Jonathan Cameron
As we're moving out of DocBook, let's convert the remaining
USB docbooks to ReST.
The transformation itself on this patch is a no-brainer
conversion using pandoc.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/DocBook/Makefile | 7 +-
Documentation/DocBook/gadget.tmpl | 793 -------------------
Documentation/DocBook/writing_musb_glue_layer.tmpl | 873 ---------------------
Documentation/DocBook/writing_usb_driver.tmpl | 412 ----------
Documentation/driver-api/index.rst | 2 +-
Documentation/driver-api/usb/gadget.rst | 501 ++++++++++++
Documentation/driver-api/usb/index.rst | 17 +
Documentation/driver-api/{ => usb}/usb.rst | 168 ++--
.../driver-api/usb/writing_musb_glue_layer.rst | 731 +++++++++++++++++
.../driver-api/usb/writing_usb_driver.rst | 338 ++++++++
10 files changed, 1675 insertions(+), 2167 deletions(-)
delete mode 100644 Documentation/DocBook/gadget.tmpl
delete mode 100644 Documentation/DocBook/writing_musb_glue_layer.tmpl
delete mode 100644 Documentation/DocBook/writing_usb_driver.tmpl
create mode 100644 Documentation/driver-api/usb/gadget.rst
create mode 100644 Documentation/driver-api/usb/index.rst
rename Documentation/driver-api/{ => usb}/usb.rst (87%)
create mode 100644 Documentation/driver-api/usb/writing_musb_glue_layer.rst
create mode 100644 Documentation/driver-api/usb/writing_usb_driver.rst
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 164c1c76971f..7d94db2b53cd 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -8,12 +8,11 @@
DOCBOOKS := z8530book.xml \
kernel-hacking.xml kernel-locking.xml \
- writing_usb_driver.xml networking.xml \
+ networking.xml \
kernel-api.xml filesystems.xml lsm.xml kgdb.xml \
- gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
+ libata.xml mtdnand.xml librs.xml rapidio.xml \
genericirq.xml s390-drivers.xml scsi.xml \
- sh.xml w1.xml \
- writing_musb_glue_layer.xml
+ sh.xml w1.xml
ifeq ($(DOCBOOKS),)
diff --git a/Documentation/DocBook/gadget.tmpl b/Documentation/DocBook/gadget.tmpl
deleted file mode 100644
index 641629221176..000000000000
--- a/Documentation/DocBook/gadget.tmpl
+++ /dev/null
@@ -1,793 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="USB-Gadget-API">
- <bookinfo>
- <title>USB Gadget API for Linux</title>
- <date>20 August 2004</date>
- <edition>20 August 2004</edition>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License as published by the Free Software Foundation; either
- version 2 of the License, or (at your option) any later
- version.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- <copyright>
- <year>2003-2004</year>
- <holder>David Brownell</holder>
- </copyright>
-
- <author>
- <firstname>David</firstname>
- <surname>Brownell</surname>
- <affiliation>
- <address><email>dbrownell@users.sourceforge.net</email></address>
- </affiliation>
- </author>
- </bookinfo>
-
-<toc></toc>
-
-<chapter id="intro"><title>Introduction</title>
-
-<para>This document presents a Linux-USB "Gadget"
-kernel mode
-API, for use within peripherals and other USB devices
-that embed Linux.
-It provides an overview of the API structure,
-and shows how that fits into a system development project.
-This is the first such API released on Linux to address
-a number of important problems, including: </para>
-
-<itemizedlist>
- <listitem><para>Supports USB 2.0, for high speed devices which
- can stream data at several dozen megabytes per second.
- </para></listitem>
- <listitem><para>Handles devices with dozens of endpoints just as
- well as ones with just two fixed-function ones. Gadget drivers
- can be written so they're easy to port to new hardware.
- </para></listitem>
- <listitem><para>Flexible enough to expose more complex USB device
- capabilities such as multiple configurations, multiple interfaces,
- composite devices,
- and alternate interface settings.
- </para></listitem>
- <listitem><para>USB "On-The-Go" (OTG) support, in conjunction
- with updates to the Linux-USB host side.
- </para></listitem>
- <listitem><para>Sharing data structures and API models with the
- Linux-USB host side API. This helps the OTG support, and
- looks forward to more-symmetric frameworks (where the same
- I/O model is used by both host and device side drivers).
- </para></listitem>
- <listitem><para>Minimalist, so it's easier to support new device
- controller hardware. I/O processing doesn't imply large
- demands for memory or CPU resources.
- </para></listitem>
-</itemizedlist>
-
-
-<para>Most Linux developers will not be able to use this API, since they
-have USB "host" hardware in a PC, workstation, or server.
-Linux users with embedded systems are more likely to
-have USB peripheral hardware.
-To distinguish drivers running inside such hardware from the
-more familiar Linux "USB device drivers",
-which are host side proxies for the real USB devices,
-a different term is used:
-the drivers inside the peripherals are "USB gadget drivers".
-In USB protocol interactions, the device driver is the master
-(or "client driver")
-and the gadget driver is the slave (or "function driver").
-</para>
-
-<para>The gadget API resembles the host side Linux-USB API in that both
-use queues of request objects to package I/O buffers, and those requests
-may be submitted or canceled.
-They share common definitions for the standard USB
-<emphasis>Chapter 9</emphasis> messages, structures, and constants.
-Also, both APIs bind and unbind drivers to devices.
-The APIs differ in detail, since the host side's current
-URB framework exposes a number of implementation details
-and assumptions that are inappropriate for a gadget API.
-While the model for control transfers and configuration
-management is necessarily different (one side is a hardware-neutral master,
-the other is a hardware-aware slave), the endpoint I/0 API used here
-should also be usable for an overhead-reduced host side API.
-</para>
-
-</chapter>
-
-<chapter id="structure"><title>Structure of Gadget Drivers</title>
-
-<para>A system running inside a USB peripheral
-normally has at least three layers inside the kernel to handle
-USB protocol processing, and may have additional layers in
-user space code.
-The "gadget" API is used by the middle layer to interact
-with the lowest level (which directly handles hardware).
-</para>
-
-<para>In Linux, from the bottom up, these layers are:
-</para>
-
-<variablelist>
-
- <varlistentry>
- <term><emphasis>USB Controller Driver</emphasis></term>
-
- <listitem>
- <para>This is the lowest software level.
- It is the only layer that talks to hardware,
- through registers, fifos, dma, irqs, and the like.
- The <filename><linux/usb/gadget.h></filename> API abstracts
- the peripheral controller endpoint hardware.
- That hardware is exposed through endpoint objects, which accept
- streams of IN/OUT buffers, and through callbacks that interact
- with gadget drivers.
- Since normal USB devices only have one upstream
- port, they only have one of these drivers.
- The controller driver can support any number of different
- gadget drivers, but only one of them can be used at a time.
- </para>
-
- <para>Examples of such controller hardware include
- the PCI-based NetChip 2280 USB 2.0 high speed controller,
- the SA-11x0 or PXA-25x UDC (found within many PDAs),
- and a variety of other products.
- </para>
-
- </listitem></varlistentry>
-
- <varlistentry>
- <term><emphasis>Gadget Driver</emphasis></term>
-
- <listitem>
- <para>The lower boundary of this driver implements hardware-neutral
- USB functions, using calls to the controller driver.
- Because such hardware varies widely in capabilities and restrictions,
- and is used in embedded environments where space is at a premium,
- the gadget driver is often configured at compile time
- to work with endpoints supported by one particular controller.
- Gadget drivers may be portable to several different controllers,
- using conditional compilation.
- (Recent kernels substantially simplify the work involved in
- supporting new hardware, by <emphasis>autoconfiguring</emphasis>
- endpoints automatically for many bulk-oriented drivers.)
- Gadget driver responsibilities include:
- </para>
- <itemizedlist>
- <listitem><para>handling setup requests (ep0 protocol responses)
- possibly including class-specific functionality
- </para></listitem>
- <listitem><para>returning configuration and string descriptors
- </para></listitem>
- <listitem><para>(re)setting configurations and interface
- altsettings, including enabling and configuring endpoints
- </para></listitem>
- <listitem><para>handling life cycle events, such as managing
- bindings to hardware,
- USB suspend/resume, remote wakeup,
- and disconnection from the USB host.
- </para></listitem>
- <listitem><para>managing IN and OUT transfers on all currently
- enabled endpoints
- </para></listitem>
- </itemizedlist>
-
- <para>
- Such drivers may be modules of proprietary code, although
- that approach is discouraged in the Linux community.
- </para>
- </listitem></varlistentry>
-
- <varlistentry>
- <term><emphasis>Upper Level</emphasis></term>
-
- <listitem>
- <para>Most gadget drivers have an upper boundary that connects
- to some Linux driver or framework in Linux.
- Through that boundary flows the data which the gadget driver
- produces and/or consumes through protocol transfers over USB.
- Examples include:
- </para>
- <itemizedlist>
- <listitem><para>user mode code, using generic (gadgetfs)
- or application specific files in
- <filename>/dev</filename>
- </para></listitem>
- <listitem><para>networking subsystem (for network gadgets,
- like the CDC Ethernet Model gadget driver)
- </para></listitem>
- <listitem><para>data capture drivers, perhaps video4Linux or
- a scanner driver; or test and measurement hardware.
- </para></listitem>
- <listitem><para>input subsystem (for HID gadgets)
- </para></listitem>
- <listitem><para>sound subsystem (for audio gadgets)
- </para></listitem>
- <listitem><para>file system (for PTP gadgets)
- </para></listitem>
- <listitem><para>block i/o subsystem (for usb-storage gadgets)
- </para></listitem>
- <listitem><para>... and more </para></listitem>
- </itemizedlist>
- </listitem></varlistentry>
-
- <varlistentry>
- <term><emphasis>Additional Layers</emphasis></term>
-
- <listitem>
- <para>Other layers may exist.
- These could include kernel layers, such as network protocol stacks,
- as well as user mode applications building on standard POSIX
- system call APIs such as
- <emphasis>open()</emphasis>, <emphasis>close()</emphasis>,
- <emphasis>read()</emphasis> and <emphasis>write()</emphasis>.
- On newer systems, POSIX Async I/O calls may be an option.
- Such user mode code will not necessarily be subject to
- the GNU General Public License (GPL).
- </para>
- </listitem></varlistentry>
-
-
-</variablelist>
-
-<para>OTG-capable systems will also need to include a standard Linux-USB
-host side stack,
-with <emphasis>usbcore</emphasis>,
-one or more <emphasis>Host Controller Drivers</emphasis> (HCDs),
-<emphasis>USB Device Drivers</emphasis> to support
-the OTG "Targeted Peripheral List",
-and so forth.
-There will also be an <emphasis>OTG Controller Driver</emphasis>,
-which is visible to gadget and device driver developers only indirectly.
-That helps the host and device side USB controllers implement the
-two new OTG protocols (HNP and SRP).
-Roles switch (host to peripheral, or vice versa) using HNP
-during USB suspend processing, and SRP can be viewed as a
-more battery-friendly kind of device wakeup protocol.
-</para>
-
-<para>Over time, reusable utilities are evolving to help make some
-gadget driver tasks simpler.
-For example, building configuration descriptors from vectors of
-descriptors for the configurations interfaces and endpoints is
-now automated, and many drivers now use autoconfiguration to
-choose hardware endpoints and initialize their descriptors.
-
-A potential example of particular interest
-is code implementing standard USB-IF protocols for
-HID, networking, storage, or audio classes.
-Some developers are interested in KDB or KGDB hooks, to let
-target hardware be remotely debugged.
-Most such USB protocol code doesn't need to be hardware-specific,
-any more than network protocols like X11, HTTP, or NFS are.
-Such gadget-side interface drivers should eventually be combined,
-to implement composite devices.
-</para>
-
-</chapter>
-
-
-<chapter id="api"><title>Kernel Mode Gadget API</title>
-
-<para>Gadget drivers declare themselves through a
-<emphasis>struct usb_gadget_driver</emphasis>, which is responsible for
-most parts of enumeration for a <emphasis>struct usb_gadget</emphasis>.
-The response to a set_configuration usually involves
-enabling one or more of the <emphasis>struct usb_ep</emphasis> objects
-exposed by the gadget, and submitting one or more
-<emphasis>struct usb_request</emphasis> buffers to transfer data.
-Understand those four data types, and their operations, and
-you will understand how this API works.
-</para>
-
-<note><title>Incomplete Data Type Descriptions</title>
-
-<para>This documentation was prepared using the standard Linux
-kernel <filename>docproc</filename> tool, which turns text
-and in-code comments into SGML DocBook and then into usable
-formats such as HTML or PDF.
-Other than the "Chapter 9" data types, most of the significant
-data types and functions are described here.
-</para>
-
-<para>However, docproc does not understand all the C constructs
-that are used, so some relevant information is likely omitted from
-what you are reading.
-One example of such information is endpoint autoconfiguration.
-You'll have to read the header file, and use example source
-code (such as that for "Gadget Zero"), to fully understand the API.
-</para>
-
-<para>The part of the API implementing some basic
-driver capabilities is specific to the version of the
-Linux kernel that's in use.
-The 2.6 kernel includes a <emphasis>driver model</emphasis>
-framework that has no analogue on earlier kernels;
-so those parts of the gadget API are not fully portable.
-(They are implemented on 2.4 kernels, but in a different way.)
-The driver model state is another part of this API that is
-ignored by the kerneldoc tools.
-</para>
-</note>
-
-<para>The core API does not expose
-every possible hardware feature, only the most widely available ones.
-There are significant hardware features, such as device-to-device DMA
-(without temporary storage in a memory buffer)
-that would be added using hardware-specific APIs.
-</para>
-
-<para>This API allows drivers to use conditional compilation to handle
-endpoint capabilities of different hardware, but doesn't require that.
-Hardware tends to have arbitrary restrictions, relating to
-transfer types, addressing, packet sizes, buffering, and availability.
-As a rule, such differences only matter for "endpoint zero" logic
-that handles device configuration and management.
-The API supports limited run-time
-detection of capabilities, through naming conventions for endpoints.
-Many drivers will be able to at least partially autoconfigure
-themselves.
-In particular, driver init sections will often have endpoint
-autoconfiguration logic that scans the hardware's list of endpoints
-to find ones matching the driver requirements
-(relying on those conventions), to eliminate some of the most
-common reasons for conditional compilation.
-</para>
-
-<para>Like the Linux-USB host side API, this API exposes
-the "chunky" nature of USB messages: I/O requests are in terms
-of one or more "packets", and packet boundaries are visible to drivers.
-Compared to RS-232 serial protocols, USB resembles
-synchronous protocols like HDLC
-(N bytes per frame, multipoint addressing, host as the primary
-station and devices as secondary stations)
-more than asynchronous ones
-(tty style: 8 data bits per frame, no parity, one stop bit).
-So for example the controller drivers won't buffer
-two single byte writes into a single two-byte USB IN packet,
-although gadget drivers may do so when they implement
-protocols where packet boundaries (and "short packets")
-are not significant.
-</para>
-
-<sect1 id="lifecycle"><title>Driver Life Cycle</title>
-
-<para>Gadget drivers make endpoint I/O requests to hardware without
-needing to know many details of the hardware, but driver
-setup/configuration code needs to handle some differences.
-Use the API like this:
-</para>
-
-<orderedlist numeration='arabic'>
-
-<listitem><para>Register a driver for the particular device side
-usb controller hardware,
-such as the net2280 on PCI (USB 2.0),
-sa11x0 or pxa25x as found in Linux PDAs,
-and so on.
-At this point the device is logically in the USB ch9 initial state
-("attached"), drawing no power and not usable
-(since it does not yet support enumeration).
-Any host should not see the device, since it's not
-activated the data line pullup used by the host to
-detect a device, even if VBUS power is available.
-</para></listitem>
-
-<listitem><para>Register a gadget driver that implements some higher level
-device function. That will then bind() to a usb_gadget, which
-activates the data line pullup sometime after detecting VBUS.
-</para></listitem>
-
-<listitem><para>The hardware driver can now start enumerating.
-The steps it handles are to accept USB power and set_address requests.
-Other steps are handled by the gadget driver.
-If the gadget driver module is unloaded before the host starts to
-enumerate, steps before step 7 are skipped.
-</para></listitem>
-
-<listitem><para>The gadget driver's setup() call returns usb descriptors,
-based both on what the bus interface hardware provides and on the
-functionality being implemented.
-That can involve alternate settings or configurations,
-unless the hardware prevents such operation.
-For OTG devices, each configuration descriptor includes
-an OTG descriptor.
-</para></listitem>
-
-<listitem><para>The gadget driver handles the last step of enumeration,
-when the USB host issues a set_configuration call.
-It enables all endpoints used in that configuration,
-with all interfaces in their default settings.
-That involves using a list of the hardware's endpoints, enabling each
-endpoint according to its descriptor.
-It may also involve using <function>usb_gadget_vbus_draw</function>
-to let more power be drawn from VBUS, as allowed by that configuration.
-For OTG devices, setting a configuration may also involve reporting
-HNP capabilities through a user interface.
-</para></listitem>
-
-<listitem><para>Do real work and perform data transfers, possibly involving
-changes to interface settings or switching to new configurations, until the
-device is disconnect()ed from the host.
-Queue any number of transfer requests to each endpoint.
-It may be suspended and resumed several times before being disconnected.
-On disconnect, the drivers go back to step 3 (above).
-</para></listitem>
-
-<listitem><para>When the gadget driver module is being unloaded,
-the driver unbind() callback is issued. That lets the controller
-driver be unloaded.
-</para></listitem>
-
-</orderedlist>
-
-<para>Drivers will normally be arranged so that just loading the
-gadget driver module (or statically linking it into a Linux kernel)
-allows the peripheral device to be enumerated, but some drivers
-will defer enumeration until some higher level component (like
-a user mode daemon) enables it.
-Note that at this lowest level there are no policies about how
-ep0 configuration logic is implemented,
-except that it should obey USB specifications.
-Such issues are in the domain of gadget drivers,
-including knowing about implementation constraints
-imposed by some USB controllers
-or understanding that composite devices might happen to
-be built by integrating reusable components.
-</para>
-
-<para>Note that the lifecycle above can be slightly different
-for OTG devices.
-Other than providing an additional OTG descriptor in each
-configuration, only the HNP-related differences are particularly
-visible to driver code.
-They involve reporting requirements during the SET_CONFIGURATION
-request, and the option to invoke HNP during some suspend callbacks.
-Also, SRP changes the semantics of
-<function>usb_gadget_wakeup</function>
-slightly.
-</para>
-
-</sect1>
-
-<sect1 id="ch9"><title>USB 2.0 Chapter 9 Types and Constants</title>
-
-<para>Gadget drivers
-rely on common USB structures and constants
-defined in the
-<filename><linux/usb/ch9.h></filename>
-header file, which is standard in Linux 2.6 kernels.
-These are the same types and constants used by host
-side drivers (and usbcore).
-</para>
-
-!Iinclude/linux/usb/ch9.h
-</sect1>
-
-<sect1 id="core"><title>Core Objects and Methods</title>
-
-<para>These are declared in
-<filename><linux/usb/gadget.h></filename>,
-and are used by gadget drivers to interact with
-USB peripheral controller drivers.
-</para>
-
- <!-- yeech, this is ugly in nsgmls PDF output.
-
- the PDF bookmark and refentry output nesting is wrong,
- and the member/argument documentation indents ugly.
-
- plus something (docproc?) adds whitespace before the
- descriptive paragraph text, so it can't line up right
- unless the explanations are trivial.
- -->
-
-!Iinclude/linux/usb/gadget.h
-</sect1>
-
-<sect1 id="utils"><title>Optional Utilities</title>
-
-<para>The core API is sufficient for writing a USB Gadget Driver,
-but some optional utilities are provided to simplify common tasks.
-These utilities include endpoint autoconfiguration.
-</para>
-
-!Edrivers/usb/gadget/usbstring.c
-!Edrivers/usb/gadget/config.c
-<!-- !Edrivers/usb/gadget/epautoconf.c -->
-</sect1>
-
-<sect1 id="composite"><title>Composite Device Framework</title>
-
-<para>The core API is sufficient for writing drivers for composite
-USB devices (with more than one function in a given configuration),
-and also 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.
-</para>
-
-<para>Devices using this framework provide a <emphasis>struct
-usb_composite_driver</emphasis>, which in turn provides one or
-more <emphasis>struct usb_configuration</emphasis> instances.
-Each such configuration includes at least one
-<emphasis>struct usb_function</emphasis>, which packages a user
-visible role such as "network link" or "mass storage device".
-Management functions may also exist, such as "Device Firmware
-Upgrade".
-</para>
-
-!Iinclude/linux/usb/composite.h
-!Edrivers/usb/gadget/composite.c
-
-</sect1>
-
-<sect1 id="functions"><title>Composite Device Functions</title>
-
-<para>At this writing, a few of the current gadget drivers have
-been converted to this framework.
-Near-term plans include converting all of them, except for "gadgetfs".
-</para>
-
-!Edrivers/usb/gadget/function/f_acm.c
-!Edrivers/usb/gadget/function/f_ecm.c
-!Edrivers/usb/gadget/function/f_subset.c
-!Edrivers/usb/gadget/function/f_obex.c
-!Edrivers/usb/gadget/function/f_serial.c
-
-</sect1>
-
-
-</chapter>
-
-<chapter id="controllers"><title>Peripheral Controller Drivers</title>
-
-<para>The first hardware supporting this API was the NetChip 2280
-controller, which supports USB 2.0 high speed and is based on PCI.
-This is the <filename>net2280</filename> driver module.
-The driver supports Linux kernel versions 2.4 and 2.6;
-contact NetChip Technologies for development boards and product
-information.
-</para>
-
-<para>Other hardware working in the "gadget" framework includes:
-Intel's PXA 25x and IXP42x series processors
-(<filename>pxa2xx_udc</filename>),
-Toshiba TC86c001 "Goku-S" (<filename>goku_udc</filename>),
-Renesas SH7705/7727 (<filename>sh_udc</filename>),
-MediaQ 11xx (<filename>mq11xx_udc</filename>),
-Hynix HMS30C7202 (<filename>h7202_udc</filename>),
-National 9303/4 (<filename>n9604_udc</filename>),
-Texas Instruments OMAP (<filename>omap_udc</filename>),
-Sharp LH7A40x (<filename>lh7a40x_udc</filename>),
-and more.
-Most of those are full speed controllers.
-</para>
-
-<para>At this writing, there are people at work on drivers in
-this framework for several other USB device controllers,
-with plans to make many of them be widely available.
-</para>
-
-<!-- !Edrivers/usb/gadget/net2280.c -->
-
-<para>A partial USB simulator,
-the <filename>dummy_hcd</filename> driver, is available.
-It can act like a net2280, a pxa25x, or an sa11x0 in terms
-of available endpoints and device speeds; and it simulates
-control, bulk, and to some extent interrupt transfers.
-That lets you develop some parts of a gadget driver on a normal PC,
-without any special hardware, and perhaps with the assistance
-of tools such as GDB running with User Mode Linux.
-At least one person has expressed interest in adapting that
-approach, hooking it up to a simulator for a microcontroller.
-Such simulators can help debug subsystems where the runtime hardware
-is unfriendly to software development, or is not yet available.
-</para>
-
-<para>Support for other controllers is expected to be developed
-and contributed
-over time, as this driver framework evolves.
-</para>
-
-</chapter>
-
-<chapter id="gadget"><title>Gadget Drivers</title>
-
-<para>In addition to <emphasis>Gadget Zero</emphasis>
-(used primarily for testing and development with drivers
-for usb controller hardware), other gadget drivers exist.
-</para>
-
-<para>There's an <emphasis>ethernet</emphasis> gadget
-driver, which implements one of the most useful
-<emphasis>Communications Device Class</emphasis> (CDC) models.
-One of the standards for cable modem interoperability even
-specifies the use of this ethernet model as one of two
-mandatory options.
-Gadgets using this code look to a USB host as if they're
-an Ethernet adapter.
-It provides access to a network where the gadget's CPU is one host,
-which could easily be bridging, routing, or firewalling
-access to other networks.
-Since some hardware can't fully implement the CDC Ethernet
-requirements, this driver also implements a "good parts only"
-subset of CDC Ethernet.
-(That subset doesn't advertise itself as CDC Ethernet,
-to avoid creating problems.)
-</para>
-
-<para>Support for Microsoft's <emphasis>RNDIS</emphasis>
-protocol has been contributed by Pengutronix and Auerswald GmbH.
-This is like CDC Ethernet, but it runs on more slightly USB hardware
-(but less than the CDC subset).
-However, its main claim to fame is being able to connect directly to
-recent versions of Windows, using drivers that Microsoft bundles
-and supports, making it much simpler to network with Windows.
-</para>
-
-<para>There is also support for user mode gadget drivers,
-using <emphasis>gadgetfs</emphasis>.
-This provides a <emphasis>User Mode API</emphasis> that presents
-each endpoint as a single file descriptor. I/O is done using
-normal <emphasis>read()</emphasis> and <emphasis>read()</emphasis> calls.
-Familiar tools like GDB and pthreads can be used to
-develop and debug user mode drivers, so that once a robust
-controller driver is available many applications for it
-won't require new kernel mode software.
-Linux 2.6 <emphasis>Async I/O (AIO)</emphasis>
-support is available, so that user mode software
-can stream data with only slightly more overhead
-than a kernel driver.
-</para>
-
-<para>There's a USB Mass Storage class driver, which provides
-a different solution for interoperability with systems such
-as MS-Windows and MacOS.
-That <emphasis>Mass Storage</emphasis> driver uses a
-file or block device as backing store for a drive,
-like the <filename>loop</filename> driver.
-The USB host uses the BBB, CB, or CBI versions of the mass
-storage class specification, using transparent SCSI commands
-to access the data from the backing store.
-</para>
-
-<para>There's a "serial line" driver, useful for TTY style
-operation over USB.
-The latest version of that driver supports CDC ACM style
-operation, like a USB modem, and so on most hardware it can
-interoperate easily with MS-Windows.
-One interesting use of that driver is in boot firmware (like a BIOS),
-which can sometimes use that model with very small systems without
-real serial lines.
-</para>
-
-<para>Support for other kinds of gadget is expected to
-be developed and contributed
-over time, as this driver framework evolves.
-</para>
-
-</chapter>
-
-<chapter id="otg"><title>USB On-The-GO (OTG)</title>
-
-<para>USB OTG support on Linux 2.6 was initially developed
-by Texas Instruments for
-<ulink url="http://www.omap.com">OMAP</ulink> 16xx and 17xx
-series processors.
-Other OTG systems should work in similar ways, but the
-hardware level details could be very different.
-</para>
-
-<para>Systems need specialized hardware support to implement OTG,
-notably including a special <emphasis>Mini-AB</emphasis> jack
-and associated transceiver to support <emphasis>Dual-Role</emphasis>
-operation:
-they can act either as a host, using the standard
-Linux-USB host side driver stack,
-or as a peripheral, using this "gadget" framework.
-To do that, the system software relies on small additions
-to those programming interfaces,
-and on a new internal component (here called an "OTG Controller")
-affecting which driver stack connects to the OTG port.
-In each role, the system can re-use the existing pool of
-hardware-neutral drivers, layered on top of the controller
-driver interfaces (<emphasis>usb_bus</emphasis> or
-<emphasis>usb_gadget</emphasis>).
-Such drivers need at most minor changes, and most of the calls
-added to support OTG can also benefit non-OTG products.
-</para>
-
-<itemizedlist>
- <listitem><para>Gadget drivers test the <emphasis>is_otg</emphasis>
- flag, and use it to determine whether or not to include
- an OTG descriptor in each of their configurations.
- </para></listitem>
- <listitem><para>Gadget drivers may need changes to support the
- two new OTG protocols, exposed in new gadget attributes
- such as <emphasis>b_hnp_enable</emphasis> flag.
- HNP support should be reported through a user interface
- (two LEDs could suffice), and is triggered in some cases
- when the host suspends the peripheral.
- SRP support can be user-initiated just like remote wakeup,
- probably by pressing the same button.
- </para></listitem>
- <listitem><para>On the host side, USB device drivers need
- to be taught to trigger HNP at appropriate moments, using
- <function>usb_suspend_device()</function>.
- That also conserves battery power, which is useful even
- for non-OTG configurations.
- </para></listitem>
- <listitem><para>Also on the host side, a driver must support the
- OTG "Targeted Peripheral List". That's just a whitelist,
- used to reject peripherals not supported with a given
- Linux OTG host.
- <emphasis>This whitelist is product-specific;
- each product must modify <filename>otg_whitelist.h</filename>
- to match its interoperability specification.
- </emphasis>
- </para>
- <para>Non-OTG Linux hosts, like PCs and workstations,
- normally have some solution for adding drivers, so that
- peripherals that aren't recognized can eventually be supported.
- That approach is unreasonable for consumer products that may
- never have their firmware upgraded, and where it's usually
- unrealistic to expect traditional PC/workstation/server kinds
- of support model to work.
- For example, it's often impractical to change device firmware
- once the product has been distributed, so driver bugs can't
- normally be fixed if they're found after shipment.
- </para></listitem>
-</itemizedlist>
-
-<para>
-Additional changes are needed below those hardware-neutral
-<emphasis>usb_bus</emphasis> and <emphasis>usb_gadget</emphasis>
-driver interfaces; those aren't discussed here in any detail.
-Those affect the hardware-specific code for each USB Host or Peripheral
-controller, and how the HCD initializes (since OTG can be active only
-on a single port).
-They also involve what may be called an <emphasis>OTG Controller
-Driver</emphasis>, managing the OTG transceiver and the OTG state
-machine logic as well as much of the root hub behavior for the
-OTG port.
-The OTG controller driver needs to activate and deactivate USB
-controllers depending on the relevant device role.
-Some related changes were needed inside usbcore, so that it
-can identify OTG-capable devices and respond appropriately
-to HNP or SRP protocols.
-</para>
-
-</chapter>
-
-</book>
-<!--
- vim:syntax=sgml:sw=4
--->
diff --git a/Documentation/DocBook/writing_musb_glue_layer.tmpl b/Documentation/DocBook/writing_musb_glue_layer.tmpl
deleted file mode 100644
index 837eca77f274..000000000000
--- a/Documentation/DocBook/writing_musb_glue_layer.tmpl
+++ /dev/null
@@ -1,873 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="Writing-MUSB-Glue-Layer">
- <bookinfo>
- <title>Writing an MUSB Glue Layer</title>
-
- <authorgroup>
- <author>
- <firstname>Apelete</firstname>
- <surname>Seketeli</surname>
- <affiliation>
- <address>
- <email>apelete at seketeli.net</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2014</year>
- <holder>Apelete Seketeli</holder>
- </copyright>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute it
- and/or modify it under the terms of the GNU General Public
- License as published by the Free Software Foundation; either
- version 2 of the License, or (at your option) any later version.
- </para>
-
- <para>
- This documentation is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public License
- along with this documentation; if not, write to the Free Software
- Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
- 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the Linux kernel source
- tree.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="introduction">
- <title>Introduction</title>
- <para>
- The Linux MUSB subsystem is part of the larger Linux USB
- subsystem. It provides support for embedded USB Device Controllers
- (UDC) that do not use Universal Host Controller Interface (UHCI)
- or Open Host Controller Interface (OHCI).
- </para>
- <para>
- Instead, these embedded UDC rely on the USB On-the-Go (OTG)
- specification which they implement at least partially. The silicon
- reference design used in most cases is the Multipoint USB
- Highspeed Dual-Role Controller (MUSB HDRC) found in the Mentor
- Graphics Inventra™ design.
- </para>
- <para>
- As a self-taught exercise I have written an MUSB glue layer for
- the Ingenic JZ4740 SoC, modelled after the many MUSB glue layers
- in the kernel source tree. This layer can be found at
- drivers/usb/musb/jz4740.c. In this documentation I will walk
- through the basics of the jz4740.c glue layer, explaining the
- different pieces and what needs to be done in order to write your
- own device glue layer.
- </para>
- </chapter>
-
- <chapter id="linux-musb-basics">
- <title>Linux MUSB Basics</title>
- <para>
- To get started on the topic, please read USB On-the-Go Basics (see
- Resources) which provides an introduction of USB OTG operation at
- the hardware level. A couple of wiki pages by Texas Instruments
- and Analog Devices also provide an overview of the Linux kernel
- MUSB configuration, albeit focused on some specific devices
- provided by these companies. Finally, getting acquainted with the
- USB specification at USB home page may come in handy, with
- practical instance provided through the Writing USB Device Drivers
- documentation (again, see Resources).
- </para>
- <para>
- Linux USB stack is a layered architecture in which the MUSB
- controller hardware sits at the lowest. The MUSB controller driver
- abstract the MUSB controller hardware to the Linux USB stack.
- </para>
- <programlisting>
- ------------------------
- | | <------- drivers/usb/gadget
- | Linux USB Core Stack | <------- drivers/usb/host
- | | <------- drivers/usb/core
- ------------------------
- ⬍
- --------------------------
- | | <------ drivers/usb/musb/musb_gadget.c
- | MUSB Controller driver | <------ drivers/usb/musb/musb_host.c
- | | <------ drivers/usb/musb/musb_core.c
- --------------------------
- ⬍
- ---------------------------------
- | MUSB Platform Specific Driver |
- | | <-- drivers/usb/musb/jz4740.c
- | aka "Glue Layer" |
- ---------------------------------
- ⬍
- ---------------------------------
- | MUSB Controller Hardware |
- ---------------------------------
- </programlisting>
- <para>
- As outlined above, the glue layer is actually the platform
- specific code sitting in between the controller driver and the
- controller hardware.
- </para>
- <para>
- Just like a Linux USB driver needs to register itself with the
- Linux USB subsystem, the MUSB glue layer needs first to register
- itself with the MUSB controller driver. This will allow the
- controller driver to know about which device the glue layer
- supports and which functions to call when a supported device is
- detected or released; remember we are talking about an embedded
- controller chip here, so no insertion or removal at run-time.
- </para>
- <para>
- All of this information is passed to the MUSB controller driver
- through a platform_driver structure defined in the glue layer as:
- </para>
- <programlisting linenumbering="numbered">
-static struct platform_driver jz4740_driver = {
- .probe = jz4740_probe,
- .remove = jz4740_remove,
- .driver = {
- .name = "musb-jz4740",
- },
-};
- </programlisting>
- <para>
- The probe and remove function pointers are called when a matching
- device is detected and, respectively, released. The name string
- describes the device supported by this glue layer. In the current
- case it matches a platform_device structure declared in
- arch/mips/jz4740/platform.c. Note that we are not using device
- tree bindings here.
- </para>
- <para>
- In order to register itself to the controller driver, the glue
- layer goes through a few steps, basically allocating the
- controller hardware resources and initialising a couple of
- circuits. To do so, it needs to keep track of the information used
- throughout these steps. This is done by defining a private
- jz4740_glue structure:
- </para>
- <programlisting linenumbering="numbered">
-struct jz4740_glue {
- struct device *dev;
- struct platform_device *musb;
- struct clk *clk;
-};
- </programlisting>
- <para>
- The dev and musb members are both device structure variables. The
- first one holds generic information about the device, since it's
- the basic device structure, and the latter holds information more
- closely related to the subsystem the device is registered to. The
- clk variable keeps information related to the device clock
- operation.
- </para>
- <para>
- Let's go through the steps of the probe function that leads the
- glue layer to register itself to the controller driver.
- </para>
- <para>
- N.B.: For the sake of readability each function will be split in
- logical parts, each part being shown as if it was independent from
- the others.
- </para>
- <programlisting linenumbering="numbered">
-static int jz4740_probe(struct platform_device *pdev)
-{
- struct platform_device *musb;
- struct jz4740_glue *glue;
- struct clk *clk;
- int ret;
-
- glue = devm_kzalloc(&pdev->dev, sizeof(*glue), GFP_KERNEL);
- if (!glue)
- return -ENOMEM;
-
- musb = platform_device_alloc("musb-hdrc", PLATFORM_DEVID_AUTO);
- if (!musb) {
- dev_err(&pdev->dev, "failed to allocate musb device\n");
- return -ENOMEM;
- }
-
- clk = devm_clk_get(&pdev->dev, "udc");
- if (IS_ERR(clk)) {
- dev_err(&pdev->dev, "failed to get clock\n");
- ret = PTR_ERR(clk);
- goto err_platform_device_put;
- }
-
- ret = clk_prepare_enable(clk);
- if (ret) {
- dev_err(&pdev->dev, "failed to enable clock\n");
- goto err_platform_device_put;
- }
-
- musb->dev.parent = &pdev->dev;
-
- glue->dev = &pdev->dev;
- glue->musb = musb;
- glue->clk = clk;
-
- return 0;
-
-err_platform_device_put:
- platform_device_put(musb);
- return ret;
-}
- </programlisting>
- <para>
- The first few lines of the probe function allocate and assign the
- glue, musb and clk variables. The GFP_KERNEL flag (line 8) allows
- the allocation process to sleep and wait for memory, thus being
- usable in a blocking situation. The PLATFORM_DEVID_AUTO flag (line
- 12) allows automatic allocation and management of device IDs in
- order to avoid device namespace collisions with explicit IDs. With
- devm_clk_get() (line 18) the glue layer allocates the clock -- the
- <literal>devm_</literal> prefix indicates that clk_get() is
- managed: it automatically frees the allocated clock resource data
- when the device is released -- and enable it.
- </para>
- <para>
- Then comes the registration steps:
- </para>
- <programlisting linenumbering="numbered">
-static int jz4740_probe(struct platform_device *pdev)
-{
- struct musb_hdrc_platform_data *pdata = &jz4740_musb_platform_data;
-
- pdata->platform_ops = &jz4740_musb_ops;
-
- platform_set_drvdata(pdev, glue);
-
- ret = platform_device_add_resources(musb, pdev->resource,
- pdev->num_resources);
- if (ret) {
- dev_err(&pdev->dev, "failed to add resources\n");
- goto err_clk_disable;
- }
-
- ret = platform_device_add_data(musb, pdata, sizeof(*pdata));
- if (ret) {
- dev_err(&pdev->dev, "failed to add platform_data\n");
- goto err_clk_disable;
- }
-
- return 0;
-
-err_clk_disable:
- clk_disable_unprepare(clk);
-err_platform_device_put:
- platform_device_put(musb);
- return ret;
-}
- </programlisting>
- <para>
- The first step is to pass the device data privately held by the
- glue layer on to the controller driver through
- platform_set_drvdata() (line 7). Next is passing on the device
- resources information, also privately held at that point, through
- platform_device_add_resources() (line 9).
- </para>
- <para>
- Finally comes passing on the platform specific data to the
- controller driver (line 16). Platform data will be discussed in
- <link linkend="device-platform-data">Chapter 4</link>, but here
- we are looking at the platform_ops function pointer (line 5) in
- musb_hdrc_platform_data structure (line 3). This function
- pointer allows the MUSB controller driver to know which function
- to call for device operation:
- </para>
- <programlisting linenumbering="numbered">
-static const struct musb_platform_ops jz4740_musb_ops = {
- .init = jz4740_musb_init,
- .exit = jz4740_musb_exit,
-};
- </programlisting>
- <para>
- Here we have the minimal case where only init and exit functions
- are called by the controller driver when needed. Fact is the
- JZ4740 MUSB controller is a basic controller, lacking some
- features found in other controllers, otherwise we may also have
- pointers to a few other functions like a power management function
- or a function to switch between OTG and non-OTG modes, for
- instance.
- </para>
- <para>
- At that point of the registration process, the controller driver
- actually calls the init function:
- </para>
- <programlisting linenumbering="numbered">
-static int jz4740_musb_init(struct musb *musb)
-{
- musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2);
- if (!musb->xceiv) {
- pr_err("HS UDC: no transceiver configured\n");
- return -ENODEV;
- }
-
- /* Silicon does not implement ConfigData register.
- * Set dyn_fifo to avoid reading EP config from hardware.
- */
- musb->dyn_fifo = true;
-
- musb->isr = jz4740_musb_interrupt;
-
- return 0;
-}
- </programlisting>
- <para>
- The goal of jz4740_musb_init() is to get hold of the transceiver
- driver data of the MUSB controller hardware and pass it on to the
- MUSB controller driver, as usual. The transceiver is the circuitry
- inside the controller hardware responsible for sending/receiving
- the USB data. Since it is an implementation of the physical layer
- of the OSI model, the transceiver is also referred to as PHY.
- </para>
- <para>
- Getting hold of the MUSB PHY driver data is done with
- usb_get_phy() which returns a pointer to the structure
- containing the driver instance data. The next couple of
- instructions (line 12 and 14) are used as a quirk and to setup
- IRQ handling respectively. Quirks and IRQ handling will be
- discussed later in <link linkend="device-quirks">Chapter
- 5</link> and <link linkend="handling-irqs">Chapter 3</link>.
- </para>
- <programlisting linenumbering="numbered">
-static int jz4740_musb_exit(struct musb *musb)
-{
- usb_put_phy(musb->xceiv);
-
- return 0;
-}
- </programlisting>
- <para>
- Acting as the counterpart of init, the exit function releases the
- MUSB PHY driver when the controller hardware itself is about to be
- released.
- </para>
- <para>
- Again, note that init and exit are fairly simple in this case due
- to the basic set of features of the JZ4740 controller hardware.
- When writing an musb glue layer for a more complex controller
- hardware, you might need to take care of more processing in those
- two functions.
- </para>
- <para>
- Returning from the init function, the MUSB controller driver jumps
- back into the probe function:
- </para>
- <programlisting linenumbering="numbered">
-static int jz4740_probe(struct platform_device *pdev)
-{
- ret = platform_device_add(musb);
- if (ret) {
- dev_err(&pdev->dev, "failed to register musb device\n");
- goto err_clk_disable;
- }
-
- return 0;
-
-err_clk_disable:
- clk_disable_unprepare(clk);
-err_platform_device_put:
- platform_device_put(musb);
- return ret;
-}
- </programlisting>
- <para>
- This is the last part of the device registration process where the
- glue layer adds the controller hardware device to Linux kernel
- device hierarchy: at this stage, all known information about the
- device is passed on to the Linux USB core stack.
- </para>
- <programlisting linenumbering="numbered">
-static int jz4740_remove(struct platform_device *pdev)
-{
- struct jz4740_glue *glue = platform_get_drvdata(pdev);
-
- platform_device_unregister(glue->musb);
- clk_disable_unprepare(glue->clk);
-
- return 0;
-}
- </programlisting>
- <para>
- Acting as the counterpart of probe, the remove function unregister
- the MUSB controller hardware (line 5) and disable the clock (line
- 6), allowing it to be gated.
- </para>
- </chapter>
-
- <chapter id="handling-irqs">
- <title>Handling IRQs</title>
- <para>
- Additionally to the MUSB controller hardware basic setup and
- registration, the glue layer is also responsible for handling the
- IRQs:
- </para>
- <programlisting linenumbering="numbered">
-static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci)
-{
- unsigned long flags;
- irqreturn_t retval = IRQ_NONE;
- struct musb *musb = __hci;
-
- spin_lock_irqsave(&musb->lock, flags);
-
- musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB);
- musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX);
- musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX);
-
- /*
- * The controller is gadget only, the state of the host mode IRQ bits is
- * undefined. Mask them to make sure that the musb driver core will
- * never see them set
- */
- musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME |
- MUSB_INTR_RESET | MUSB_INTR_SOF;
-
- if (musb->int_usb || musb->int_tx || musb->int_rx)
- retval = musb_interrupt(musb);
-
- spin_unlock_irqrestore(&musb->lock, flags);
-
- return retval;
-}
- </programlisting>
- <para>
- Here the glue layer mostly has to read the relevant hardware
- registers and pass their values on to the controller driver which
- will handle the actual event that triggered the IRQ.
- </para>
- <para>
- The interrupt handler critical section is protected by the
- spin_lock_irqsave() and counterpart spin_unlock_irqrestore()
- functions (line 7 and 24 respectively), which prevent the
- interrupt handler code to be run by two different threads at the
- same time.
- </para>
- <para>
- Then the relevant interrupt registers are read (line 9 to 11):
- </para>
- <itemizedlist>
- <listitem>
- <para>
- MUSB_INTRUSB: indicates which USB interrupts are currently
- active,
- </para>
- </listitem>
- <listitem>
- <para>
- MUSB_INTRTX: indicates which of the interrupts for TX
- endpoints are currently active,
- </para>
- </listitem>
- <listitem>
- <para>
- MUSB_INTRRX: indicates which of the interrupts for TX
- endpoints are currently active.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- Note that musb_readb() is used to read 8-bit registers at most,
- while musb_readw() allows us to read at most 16-bit registers.
- There are other functions that can be used depending on the size
- of your device registers. See musb_io.h for more information.
- </para>
- <para>
- Instruction on line 18 is another quirk specific to the JZ4740
- USB device controller, which will be discussed later in <link
- linkend="device-quirks">Chapter 5</link>.
- </para>
- <para>
- The glue layer still needs to register the IRQ handler though.
- Remember the instruction on line 14 of the init function:
- </para>
- <programlisting linenumbering="numbered">
-static int jz4740_musb_init(struct musb *musb)
-{
- musb->isr = jz4740_musb_interrupt;
-
- return 0;
-}
- </programlisting>
- <para>
- This instruction sets a pointer to the glue layer IRQ handler
- function, in order for the controller hardware to call the handler
- back when an IRQ comes from the controller hardware. The interrupt
- handler is now implemented and registered.
- </para>
- </chapter>
-
- <chapter id="device-platform-data">
- <title>Device Platform Data</title>
- <para>
- In order to write an MUSB glue layer, you need to have some data
- describing the hardware capabilities of your controller hardware,
- which is called the platform data.
- </para>
- <para>
- Platform data is specific to your hardware, though it may cover a
- broad range of devices, and is generally found somewhere in the
- arch/ directory, depending on your device architecture.
- </para>
- <para>
- For instance, platform data for the JZ4740 SoC is found in
- arch/mips/jz4740/platform.c. In the platform.c file each device of
- the JZ4740 SoC is described through a set of structures.
- </para>
- <para>
- Here is the part of arch/mips/jz4740/platform.c that covers the
- USB Device Controller (UDC):
- </para>
- <programlisting linenumbering="numbered">
-/* USB Device Controller */
-struct platform_device jz4740_udc_xceiv_device = {
- .name = "usb_phy_gen_xceiv",
- .id = 0,
-};
-
-static struct resource jz4740_udc_resources[] = {
- [0] = {
- .start = JZ4740_UDC_BASE_ADDR,
- .end = JZ4740_UDC_BASE_ADDR + 0x10000 - 1,
- .flags = IORESOURCE_MEM,
- },
- [1] = {
- .start = JZ4740_IRQ_UDC,
- .end = JZ4740_IRQ_UDC,
- .flags = IORESOURCE_IRQ,
- .name = "mc",
- },
-};
-
-struct platform_device jz4740_udc_device = {
- .name = "musb-jz4740",
- .id = -1,
- .dev = {
- .dma_mask = &jz4740_udc_device.dev.coherent_dma_mask,
- .coherent_dma_mask = DMA_BIT_MASK(32),
- },
- .num_resources = ARRAY_SIZE(jz4740_udc_resources),
- .resource = jz4740_udc_resources,
-};
- </programlisting>
- <para>
- The jz4740_udc_xceiv_device platform device structure (line 2)
- describes the UDC transceiver with a name and id number.
- </para>
- <para>
- At the time of this writing, note that
- "usb_phy_gen_xceiv" is the specific name to be used for
- all transceivers that are either built-in with reference USB IP or
- autonomous and doesn't require any PHY programming. You will need
- to set CONFIG_NOP_USB_XCEIV=y in the kernel configuration to make
- use of the corresponding transceiver driver. The id field could be
- set to -1 (equivalent to PLATFORM_DEVID_NONE), -2 (equivalent to
- PLATFORM_DEVID_AUTO) or start with 0 for the first device of this
- kind if we want a specific id number.
- </para>
- <para>
- The jz4740_udc_resources resource structure (line 7) defines the
- UDC registers base addresses.
- </para>
- <para>
- The first array (line 9 to 11) defines the UDC registers base
- memory addresses: start points to the first register memory
- address, end points to the last register memory address and the
- flags member defines the type of resource we are dealing with. So
- IORESOURCE_MEM is used to define the registers memory addresses.
- The second array (line 14 to 17) defines the UDC IRQ registers
- addresses. Since there is only one IRQ register available for the
- JZ4740 UDC, start and end point at the same address. The
- IORESOURCE_IRQ flag tells that we are dealing with IRQ resources,
- and the name "mc" is in fact hard-coded in the MUSB core
- in order for the controller driver to retrieve this IRQ resource
- by querying it by its name.
- </para>
- <para>
- Finally, the jz4740_udc_device platform device structure (line 21)
- describes the UDC itself.
- </para>
- <para>
- The "musb-jz4740" name (line 22) defines the MUSB
- driver that is used for this device; remember this is in fact
- the name that we used in the jz4740_driver platform driver
- structure in <link linkend="linux-musb-basics">Chapter
- 2</link>. The id field (line 23) is set to -1 (equivalent to
- PLATFORM_DEVID_NONE) since we do not need an id for the device:
- the MUSB controller driver was already set to allocate an
- automatic id in <link linkend="linux-musb-basics">Chapter
- 2</link>. In the dev field we care for DMA related information
- here. The dma_mask field (line 25) defines the width of the DMA
- mask that is going to be used, and coherent_dma_mask (line 26)
- has the same purpose but for the alloc_coherent DMA mappings: in
- both cases we are using a 32 bits mask. Then the resource field
- (line 29) is simply a pointer to the resource structure defined
- before, while the num_resources field (line 28) keeps track of
- the number of arrays defined in the resource structure (in this
- case there were two resource arrays defined before).
- </para>
- <para>
- With this quick overview of the UDC platform data at the arch/
- level now done, let's get back to the MUSB glue layer specific
- platform data in drivers/usb/musb/jz4740.c:
- </para>
- <programlisting linenumbering="numbered">
-static struct musb_hdrc_config jz4740_musb_config = {
- /* Silicon does not implement USB OTG. */
- .multipoint = 0,
- /* Max EPs scanned, driver will decide which EP can be used. */
- .num_eps = 4,
- /* RAMbits needed to configure EPs from table */
- .ram_bits = 9,
- .fifo_cfg = jz4740_musb_fifo_cfg,
- .fifo_cfg_size = ARRAY_SIZE(jz4740_musb_fifo_cfg),
-};
-
-static struct musb_hdrc_platform_data jz4740_musb_platform_data = {
- .mode = MUSB_PERIPHERAL,
- .config = &jz4740_musb_config,
-};
- </programlisting>
- <para>
- First the glue layer configures some aspects of the controller
- driver operation related to the controller hardware specifics.
- This is done through the jz4740_musb_config musb_hdrc_config
- structure.
- </para>
- <para>
- Defining the OTG capability of the controller hardware, the
- multipoint member (line 3) is set to 0 (equivalent to false)
- since the JZ4740 UDC is not OTG compatible. Then num_eps (line
- 5) defines the number of USB endpoints of the controller
- hardware, including endpoint 0: here we have 3 endpoints +
- endpoint 0. Next is ram_bits (line 7) which is the width of the
- RAM address bus for the MUSB controller hardware. This
- information is needed when the controller driver cannot
- automatically configure endpoints by reading the relevant
- controller hardware registers. This issue will be discussed when
- we get to device quirks in <link linkend="device-quirks">Chapter
- 5</link>. Last two fields (line 8 and 9) are also about device
- quirks: fifo_cfg points to the USB endpoints configuration table
- and fifo_cfg_size keeps track of the size of the number of
- entries in that configuration table. More on that later in <link
- linkend="device-quirks">Chapter 5</link>.
- </para>
- <para>
- Then this configuration is embedded inside
- jz4740_musb_platform_data musb_hdrc_platform_data structure (line
- 11): config is a pointer to the configuration structure itself,
- and mode tells the controller driver if the controller hardware
- may be used as MUSB_HOST only, MUSB_PERIPHERAL only or MUSB_OTG
- which is a dual mode.
- </para>
- <para>
- Remember that jz4740_musb_platform_data is then used to convey
- platform data information as we have seen in the probe function
- in <link linkend="linux-musb-basics">Chapter 2</link>
- </para>
- </chapter>
-
- <chapter id="device-quirks">
- <title>Device Quirks</title>
- <para>
- Completing the platform data specific to your device, you may also
- need to write some code in the glue layer to work around some
- device specific limitations. These quirks may be due to some
- hardware bugs, or simply be the result of an incomplete
- implementation of the USB On-the-Go specification.
- </para>
- <para>
- The JZ4740 UDC exhibits such quirks, some of which we will discuss
- here for the sake of insight even though these might not be found
- in the controller hardware you are working on.
- </para>
- <para>
- Let's get back to the init function first:
- </para>
- <programlisting linenumbering="numbered">
-static int jz4740_musb_init(struct musb *musb)
-{
- musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2);
- if (!musb->xceiv) {
- pr_err("HS UDC: no transceiver configured\n");
- return -ENODEV;
- }
-
- /* Silicon does not implement ConfigData register.
- * Set dyn_fifo to avoid reading EP config from hardware.
- */
- musb->dyn_fifo = true;
-
- musb->isr = jz4740_musb_interrupt;
-
- return 0;
-}
- </programlisting>
- <para>
- Instruction on line 12 helps the MUSB controller driver to work
- around the fact that the controller hardware is missing registers
- that are used for USB endpoints configuration.
- </para>
- <para>
- Without these registers, the controller driver is unable to read
- the endpoints configuration from the hardware, so we use line 12
- instruction to bypass reading the configuration from silicon, and
- rely on a hard-coded table that describes the endpoints
- configuration instead:
- </para>
- <programlisting linenumbering="numbered">
-static struct musb_fifo_cfg jz4740_musb_fifo_cfg[] = {
-{ .hw_ep_num = 1, .style = FIFO_TX, .maxpacket = 512, },
-{ .hw_ep_num = 1, .style = FIFO_RX, .maxpacket = 512, },
-{ .hw_ep_num = 2, .style = FIFO_TX, .maxpacket = 64, },
-};
- </programlisting>
- <para>
- Looking at the configuration table above, we see that each
- endpoints is described by three fields: hw_ep_num is the endpoint
- number, style is its direction (either FIFO_TX for the controller
- driver to send packets in the controller hardware, or FIFO_RX to
- receive packets from hardware), and maxpacket defines the maximum
- size of each data packet that can be transmitted over that
- endpoint. Reading from the table, the controller driver knows that
- endpoint 1 can be used to send and receive USB data packets of 512
- bytes at once (this is in fact a bulk in/out endpoint), and
- endpoint 2 can be used to send data packets of 64 bytes at once
- (this is in fact an interrupt endpoint).
- </para>
- <para>
- Note that there is no information about endpoint 0 here: that one
- is implemented by default in every silicon design, with a
- predefined configuration according to the USB specification. For
- more examples of endpoint configuration tables, see musb_core.c.
- </para>
- <para>
- Let's now get back to the interrupt handler function:
- </para>
- <programlisting linenumbering="numbered">
-static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci)
-{
- unsigned long flags;
- irqreturn_t retval = IRQ_NONE;
- struct musb *musb = __hci;
-
- spin_lock_irqsave(&musb->lock, flags);
-
- musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB);
- musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX);
- musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX);
-
- /*
- * The controller is gadget only, the state of the host mode IRQ bits is
- * undefined. Mask them to make sure that the musb driver core will
- * never see them set
- */
- musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME |
- MUSB_INTR_RESET | MUSB_INTR_SOF;
-
- if (musb->int_usb || musb->int_tx || musb->int_rx)
- retval = musb_interrupt(musb);
-
- spin_unlock_irqrestore(&musb->lock, flags);
-
- return retval;
-}
- </programlisting>
- <para>
- Instruction on line 18 above is a way for the controller driver to
- work around the fact that some interrupt bits used for USB host
- mode operation are missing in the MUSB_INTRUSB register, thus left
- in an undefined hardware state, since this MUSB controller
- hardware is used in peripheral mode only. As a consequence, the
- glue layer masks these missing bits out to avoid parasite
- interrupts by doing a logical AND operation between the value read
- from MUSB_INTRUSB and the bits that are actually implemented in
- the register.
- </para>
- <para>
- These are only a couple of the quirks found in the JZ4740 USB
- device controller. Some others were directly addressed in the MUSB
- core since the fixes were generic enough to provide a better
- handling of the issues for others controller hardware eventually.
- </para>
- </chapter>
-
- <chapter id="conclusion">
- <title>Conclusion</title>
- <para>
- Writing a Linux MUSB glue layer should be a more accessible task,
- as this documentation tries to show the ins and outs of this
- exercise.
- </para>
- <para>
- The JZ4740 USB device controller being fairly simple, I hope its
- glue layer serves as a good example for the curious mind. Used
- with the current MUSB glue layers, this documentation should
- provide enough guidance to get started; should anything gets out
- of hand, the linux-usb mailing list archive is another helpful
- resource to browse through.
- </para>
- </chapter>
-
- <chapter id="acknowledgements">
- <title>Acknowledgements</title>
- <para>
- Many thanks to Lars-Peter Clausen and Maarten ter Huurne for
- answering my questions while I was writing the JZ4740 glue layer
- and for helping me out getting the code in good shape.
- </para>
- <para>
- I would also like to thank the Qi-Hardware community at large for
- its cheerful guidance and support.
- </para>
- </chapter>
-
- <chapter id="resources">
- <title>Resources</title>
- <para>
- USB Home Page:
- <ulink url="http://www.usb.org">http://www.usb.org</ulink>
- </para>
- <para>
- linux-usb Mailing List Archives:
- <ulink url="http://marc.info/?l=linux-usb">http://marc.info/?l=linux-usb</ulink>
- </para>
- <para>
- USB On-the-Go Basics:
- <ulink url="http://www.maximintegrated.com/app-notes/index.mvp/id/1822">http://www.maximintegrated.com/app-notes/index.mvp/id/1822</ulink>
- </para>
- <para>
- Writing USB Device Drivers:
- <ulink url="https://www.kernel.org/doc/htmldocs/writing_usb_driver/index.html">https://www.kernel.org/doc/htmldocs/writing_usb_driver/index.html</ulink>
- </para>
- <para>
- Texas Instruments USB Configuration Wiki Page:
- <ulink url="http://processors.wiki.ti.com/index.php/Usbgeneralpage">http://processors.wiki.ti.com/index.php/Usbgeneralpage</ulink>
- </para>
- <para>
- Analog Devices Blackfin MUSB Configuration:
- <ulink url="http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:musb">http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:musb</ulink>
- </para>
- </chapter>
-
-</book>
diff --git a/Documentation/DocBook/writing_usb_driver.tmpl b/Documentation/DocBook/writing_usb_driver.tmpl
deleted file mode 100644
index 3210dcf741c9..000000000000
--- a/Documentation/DocBook/writing_usb_driver.tmpl
+++ /dev/null
@@ -1,412 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="USBDeviceDriver">
- <bookinfo>
- <title>Writing USB Device Drivers</title>
-
- <authorgroup>
- <author>
- <firstname>Greg</firstname>
- <surname>Kroah-Hartman</surname>
- <affiliation>
- <address>
- <email>greg@kroah.com</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2001-2002</year>
- <holder>Greg Kroah-Hartman</holder>
- </copyright>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License as published by the Free Software Foundation; either
- version 2 of the License, or (at your option) any later
- version.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
-
- <para>
- This documentation is based on an article published in
- Linux Journal Magazine, October 2001, Issue 90.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="intro">
- <title>Introduction</title>
- <para>
- The Linux USB subsystem has grown from supporting only two different
- types of devices in the 2.2.7 kernel (mice and keyboards), to over 20
- different types of devices in the 2.4 kernel. Linux currently supports
- almost all USB class devices (standard types of devices like keyboards,
- mice, modems, printers and speakers) and an ever-growing number of
- vendor-specific devices (such as USB to serial converters, digital
- cameras, Ethernet devices and MP3 players). For a full list of the
- different USB devices currently supported, see Resources.
- </para>
- <para>
- The remaining kinds of USB devices that do not have support on Linux are
- almost all vendor-specific devices. Each vendor decides to implement a
- custom protocol to talk to their device, so a custom driver usually needs
- to be created. Some vendors are open with their USB protocols and help
- with the creation of Linux drivers, while others do not publish them, and
- developers are forced to reverse-engineer. See Resources for some links
- to handy reverse-engineering tools.
- </para>
- <para>
- Because each different protocol causes a new driver to be created, I have
- written a generic USB driver skeleton, modelled after the pci-skeleton.c
- file in the kernel source tree upon which many PCI network drivers have
- been based. This USB skeleton can be found at drivers/usb/usb-skeleton.c
- in the kernel source tree. In this article I will walk through the basics
- of the skeleton driver, explaining the different pieces and what needs to
- be done to customize it to your specific device.
- </para>
- </chapter>
-
- <chapter id="basics">
- <title>Linux USB Basics</title>
- <para>
- If you are going to write a Linux USB driver, please become familiar with
- the USB protocol specification. It can be found, along with many other
- useful documents, at the USB home page (see Resources). An excellent
- introduction to the Linux USB subsystem can be found at the USB Working
- Devices List (see Resources). It explains how the Linux USB subsystem is
- structured and introduces the reader to the concept of USB urbs
- (USB Request Blocks), which are essential to USB drivers.
- </para>
- <para>
- The first thing a Linux USB driver needs to do is register itself with
- the Linux USB subsystem, giving it some information about which devices
- the driver supports and which functions to call when a device supported
- by the driver is inserted or removed from the system. All of this
- information is passed to the USB subsystem in the usb_driver structure.
- The skeleton driver declares a usb_driver as:
- </para>
- <programlisting>
-static struct usb_driver skel_driver = {
- .name = "skeleton",
- .probe = skel_probe,
- .disconnect = skel_disconnect,
- .fops = &skel_fops,
- .minor = USB_SKEL_MINOR_BASE,
- .id_table = skel_table,
-};
- </programlisting>
- <para>
- The variable name is a string that describes the driver. It is used in
- informational messages printed to the system log. The probe and
- disconnect function pointers are called when a device that matches the
- information provided in the id_table variable is either seen or removed.
- </para>
- <para>
- The fops and minor variables are optional. Most USB drivers hook into
- another kernel subsystem, such as the SCSI, network or TTY subsystem.
- These types of drivers register themselves with the other kernel
- subsystem, and any user-space interactions are provided through that
- interface. But for drivers that do not have a matching kernel subsystem,
- such as MP3 players or scanners, a method of interacting with user space
- is needed. The USB subsystem provides a way to register a minor device
- number and a set of file_operations function pointers that enable this
- user-space interaction. The skeleton driver needs this kind of interface,
- so it provides a minor starting number and a pointer to its
- file_operations functions.
- </para>
- <para>
- The USB driver is then registered with a call to usb_register, usually in
- the driver's init function, as shown here:
- </para>
- <programlisting>
-static int __init usb_skel_init(void)
-{
- int result;
-
- /* 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);
- return -1;
- }
-
- return 0;
-}
-module_init(usb_skel_init);
- </programlisting>
- <para>
- When the driver is unloaded from the system, it needs to deregister
- itself with the USB subsystem. This is done with the usb_deregister
- function:
- </para>
- <programlisting>
-static void __exit usb_skel_exit(void)
-{
- /* deregister this driver with the USB subsystem */
- usb_deregister(&skel_driver);
-}
-module_exit(usb_skel_exit);
- </programlisting>
- <para>
- To enable the linux-hotplug system to load the driver automatically when
- the device is plugged in, you need to create a MODULE_DEVICE_TABLE. The
- following code tells the hotplug scripts that this module supports a
- single device with a specific vendor and product ID:
- </para>
- <programlisting>
-/* table of devices that work with this driver */
-static struct usb_device_id skel_table [] = {
- { USB_DEVICE(USB_SKEL_VENDOR_ID, USB_SKEL_PRODUCT_ID) },
- { } /* Terminating entry */
-};
-MODULE_DEVICE_TABLE (usb, skel_table);
- </programlisting>
- <para>
- There are other macros that can be used in describing a usb_device_id for
- drivers that support a whole class of USB drivers. See usb.h for more
- information on this.
- </para>
- </chapter>
-
- <chapter id="device">
- <title>Device operation</title>
- <para>
- When a device is plugged into the USB bus that matches the device ID
- pattern that your driver registered with the USB core, the probe function
- is called. The usb_device structure, interface number and the interface ID
- are passed to the function:
- </para>
- <programlisting>
-static int skel_probe(struct usb_interface *interface,
- const struct usb_device_id *id)
- </programlisting>
- <para>
- The driver now needs to verify that this device is actually one that it
- can accept. If so, it returns 0.
- If not, or if any error occurs during initialization, an errorcode
- (such as <literal>-ENOMEM</literal> or <literal>-ENODEV</literal>)
- is returned from the probe function.
- </para>
- <para>
- In the skeleton driver, we determine what end points are marked as bulk-in
- and bulk-out. We create buffers to hold the data that will be sent and
- received from the device, and a USB urb to write data to the device is
- initialized.
- </para>
- <para>
- Conversely, when the device is removed from the USB bus, the disconnect
- function is called with the device pointer. The driver needs to clean any
- private data that has been allocated at this time and to shut down any
- pending urbs that are in the USB system.
- </para>
- <para>
- Now that the device is plugged into the system and the driver is bound to
- the device, any of the functions in the file_operations structure that
- were passed to the USB subsystem will be called from a user program trying
- to talk to the device. The first function called will be open, as the
- program tries to open the device for I/O. We increment our private usage
- count and save a pointer to our internal structure in the file
- 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:
- </para>
- <programlisting>
-/* increment our usage count for the module */
-++skel->open_count;
-
-/* save our object in the file's private structure */
-file->private_data = dev;
- </programlisting>
- <para>
- After the open function is called, the read and write functions are called
- to receive and send data to the device. In the skel_write function, we
- receive a pointer to some data that the user wants to send to the device
- and the size of the data. The function determines how much data it can
- send to the device based on the size of the write urb it has created (this
- size depends on the size of the bulk out end point that the device has).
- Then it copies the data from user space to kernel space, points the urb to
- the data and submits the urb to the USB subsystem. This can be seen in
- the following code:
- </para>
- <programlisting>
-/* we can only write as much as 1 urb will hold */
-bytes_written = (count > skel->bulk_out_size) ? skel->bulk_out_size : count;
-
-/* copy the data from user space into our urb */
-copy_from_user(skel->write_urb->transfer_buffer, buffer, bytes_written);
-
-/* 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,
- skel_write_bulk_callback,
- skel);
-
-/* send the data out the bulk port */
-result = usb_submit_urb(skel->write_urb);
-if (result) {
- err("Failed submitting write urb, error %d", result);
-}
- </programlisting>
- <para>
- When the write urb is filled up with the proper information using the
- usb_fill_bulk_urb function, we point the urb's completion callback to call our
- own skel_write_bulk_callback function. This function is called when the
- urb is finished by the USB subsystem. The callback function is called in
- interrupt context, so caution must be taken not to do very much processing
- at that time. Our implementation of skel_write_bulk_callback merely
- reports if the urb was completed successfully or not and then returns.
- </para>
- <para>
- The read function works a bit differently from the write function in that
- we do not use an urb to transfer data from the device to the driver.
- Instead we call the usb_bulk_msg function, which can be used to send or
- receive data from a device without having to create urbs and handle
- urb completion callback functions. We call the usb_bulk_msg function,
- giving it a buffer into which to place any data received from the device
- and a timeout value. If the timeout period expires without receiving any
- data from the device, the function will fail and return an error message.
- This can be shown with the following code:
- </para>
- <programlisting>
-/* do an immediate bulk read to get data from the device */
-retval = usb_bulk_msg (skel->dev,
- usb_rcvbulkpipe (skel->dev,
- skel->bulk_in_endpointAddr),
- skel->bulk_in_buffer,
- skel->bulk_in_size,
- &count, HZ*10);
-/* if the read was successful, copy the data to user space */
-if (!retval) {
- if (copy_to_user (buffer, skel->bulk_in_buffer, count))
- retval = -EFAULT;
- else
- retval = count;
-}
- </programlisting>
- <para>
- The usb_bulk_msg function can be very useful for doing single reads or
- writes to a device; however, if you need to read or write constantly to a
- device, it is recommended to set up your own urbs and submit them to the
- USB subsystem.
- </para>
- <para>
- When the user program releases the file handle that it has been using to
- talk to the device, the release function in the driver is called. In this
- function we decrement our private usage count and wait for possible
- pending writes:
- </para>
- <programlisting>
-/* decrement our usage count for the device */
---skel->open_count;
- </programlisting>
- <para>
- One of the more difficult problems that USB drivers must be able to handle
- smoothly is the fact that the USB device may be removed from the system at
- any point in time, even if a program is currently talking to it. It needs
- to be able to shut down any current reads and writes and notify the
- user-space programs that the device is no longer there. The following
- code (function <function>skel_delete</function>)
- is an example of how to do this: </para>
- <programlisting>
-static inline void skel_delete (struct usb_skel *dev)
-{
- kfree (dev->bulk_in_buffer);
- if (dev->bulk_out_buffer != NULL)
- usb_free_coherent (dev->udev, dev->bulk_out_size,
- dev->bulk_out_buffer,
- dev->write_urb->transfer_dma);
- usb_free_urb (dev->write_urb);
- kfree (dev);
-}
- </programlisting>
- <para>
- If a program currently has an open handle to the device, we reset the flag
- <literal>device_present</literal>. For
- every read, write, release and other functions that expect a device to be
- present, the driver first checks this flag to see if the device is
- still present. If not, it releases that the device has disappeared, and a
- -ENODEV error is returned to the user-space program. When the release
- function is eventually called, it determines if there is no device
- and if not, it does the cleanup that the skel_disconnect
- function normally does if there are no open files on the device (see
- Listing 5).
- </para>
- </chapter>
-
- <chapter id="iso">
- <title>Isochronous Data</title>
- <para>
- This usb-skeleton driver does not have any examples of interrupt or
- isochronous data being sent to or from the device. Interrupt data is sent
- almost exactly as bulk data is, with a few minor exceptions. Isochronous
- data works differently with continuous streams of data being sent to or
- from the device. The audio and video camera drivers are very good examples
- of drivers that handle isochronous data and will be useful if you also
- need to do this.
- </para>
- </chapter>
-
- <chapter id="Conclusion">
- <title>Conclusion</title>
- <para>
- Writing Linux USB device drivers is not a difficult task as the
- usb-skeleton driver shows. This driver, combined with the other current
- USB drivers, should provide enough examples to help a beginning author
- create a working driver in a minimal amount of time. The linux-usb-devel
- mailing list archives also contain a lot of helpful information.
- </para>
- </chapter>
-
- <chapter id="resources">
- <title>Resources</title>
- <para>
- The Linux USB Project: <ulink url="http://www.linux-usb.org">http://www.linux-usb.org/</ulink>
- </para>
- <para>
- Linux Hotplug Project: <ulink url="http://linux-hotplug.sourceforge.net">http://linux-hotplug.sourceforge.net/</ulink>
- </para>
- <para>
- Linux USB Working Devices List: <ulink url="http://www.qbik.ch/usb/devices">http://www.qbik.ch/usb/devices/</ulink>
- </para>
- <para>
- linux-usb-devel Mailing List Archives: <ulink url="http://marc.theaimsgroup.com/?l=linux-usb-devel">http://marc.theaimsgroup.com/?l=linux-usb-devel</ulink>
- </para>
- <para>
- Programming Guide for Linux USB Device Drivers: <ulink url="http://usb.cs.tum.edu/usbdoc">http://usb.cs.tum.edu/usbdoc</ulink>
- </para>
- <para>
- USB Home Page: <ulink url="http://www.usb.org">http://www.usb.org</ulink>
- </para>
- </chapter>
-
-</book>
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index 60db00d1532b..90e742577dfc 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -26,7 +26,7 @@ available subsections can be seen below.
regulator
iio/index
input
- usb
+ usb/index
spi
i2c
hsi
diff --git a/Documentation/driver-api/usb/gadget.rst b/Documentation/driver-api/usb/gadget.rst
new file mode 100644
index 000000000000..4fd9862f3f21
--- /dev/null
+++ b/Documentation/driver-api/usb/gadget.rst
@@ -0,0 +1,501 @@
+Introduction
+============
+
+This document presents a Linux-USB "Gadget" kernel mode API, for use
+within peripherals and other USB devices that embed Linux. It provides
+an overview of the API structure, and shows how that fits into a system
+development project. This is the first such API released on Linux to
+address a number of important problems, including:
+
+- Supports USB 2.0, for high speed devices which can stream data at
+ several dozen megabytes per second.
+
+- Handles devices with dozens of endpoints just as well as ones with
+ just two fixed-function ones. Gadget drivers can be written so
+ they're easy to port to new hardware.
+
+- Flexible enough to expose more complex USB device capabilities such
+ as multiple configurations, multiple interfaces, composite devices,
+ and alternate interface settings.
+
+- USB "On-The-Go" (OTG) support, in conjunction with updates to the
+ Linux-USB host side.
+
+- Sharing data structures and API models with the Linux-USB host side
+ API. This helps the OTG support, and looks forward to more-symmetric
+ frameworks (where the same I/O model is used by both host and device
+ side drivers).
+
+- Minimalist, so it's easier to support new device controller hardware.
+ I/O processing doesn't imply large demands for memory or CPU
+ resources.
+
+Most Linux developers will not be able to use this API, since they have
+USB "host" hardware in a PC, workstation, or server. Linux users with
+embedded systems are more likely to have USB peripheral hardware. To
+distinguish drivers running inside such hardware from the more familiar
+Linux "USB device drivers", which are host side proxies for the real USB
+devices, a different term is used: the drivers inside the peripherals
+are "USB gadget drivers". In USB protocol interactions, the device
+driver is the master (or "client driver") and the gadget driver is the
+slave (or "function driver").
+
+The gadget API resembles the host side Linux-USB API in that both use
+queues of request objects to package I/O buffers, and those requests may
+be submitted or canceled. They share common definitions for the standard
+USB *Chapter 9* messages, structures, and constants. Also, both APIs
+bind and unbind drivers to devices. The APIs differ in detail, since the
+host side's current URB framework exposes a number of implementation
+details and assumptions that are inappropriate for a gadget API. While
+the model for control transfers and configuration management is
+necessarily different (one side is a hardware-neutral master, the other
+is a hardware-aware slave), the endpoint I/0 API used here should also
+be usable for an overhead-reduced host side API.
+
+Structure of Gadget Drivers
+===========================
+
+A system running inside a USB peripheral normally has at least three
+layers inside the kernel to handle USB protocol processing, and may have
+additional layers in user space code. The "gadget" API is used by the
+middle layer to interact with the lowest level (which directly handles
+hardware).
+
+In Linux, from the bottom up, these layers are:
+
+*USB Controller Driver*
+ This is the lowest software level. It is the only layer that talks
+ to hardware, through registers, fifos, dma, irqs, and the like. The
+ ``<linux/usb/gadget.h>`` API abstracts the peripheral controller
+ endpoint hardware. That hardware is exposed through endpoint
+ objects, which accept streams of IN/OUT buffers, and through
+ callbacks that interact with gadget drivers. Since normal USB
+ devices only have one upstream port, they only have one of these
+ drivers. The controller driver can support any number of different
+ gadget drivers, but only one of them can be used at a time.
+
+ Examples of such controller hardware include the PCI-based NetChip
+ 2280 USB 2.0 high speed controller, the SA-11x0 or PXA-25x UDC
+ (found within many PDAs), and a variety of other products.
+
+*Gadget Driver*
+ The lower boundary of this driver implements hardware-neutral USB
+ functions, using calls to the controller driver. Because such
+ hardware varies widely in capabilities and restrictions, and is used
+ in embedded environments where space is at a premium, the gadget
+ driver is often configured at compile time to work with endpoints
+ supported by one particular controller. Gadget drivers may be
+ portable to several different controllers, using conditional
+ compilation. (Recent kernels substantially simplify the work
+ involved in supporting new hardware, by *autoconfiguring* endpoints
+ automatically for many bulk-oriented drivers.) Gadget driver
+ responsibilities include:
+
+ - handling setup requests (ep0 protocol responses) possibly
+ including class-specific functionality
+
+ - returning configuration and string descriptors
+
+ - (re)setting configurations and interface altsettings, including
+ enabling and configuring endpoints
+
+ - handling life cycle events, such as managing bindings to
+ hardware, USB suspend/resume, remote wakeup, and disconnection
+ from the USB host.
+
+ - managing IN and OUT transfers on all currently enabled endpoints
+
+ Such drivers may be modules of proprietary code, although that
+ approach is discouraged in the Linux community.
+
+*Upper Level*
+ Most gadget drivers have an upper boundary that connects to some
+ Linux driver or framework in Linux. Through that boundary flows the
+ data which the gadget driver produces and/or consumes through
+ protocol transfers over USB. Examples include:
+
+ - user mode code, using generic (gadgetfs) or application specific
+ files in ``/dev``
+
+ - networking subsystem (for network gadgets, like the CDC Ethernet
+ Model gadget driver)
+
+ - data capture drivers, perhaps video4Linux or a scanner driver; or
+ test and measurement hardware.
+
+ - input subsystem (for HID gadgets)
+
+ - sound subsystem (for audio gadgets)
+
+ - file system (for PTP gadgets)
+
+ - block i/o subsystem (for usb-storage gadgets)
+
+ - ... and more
+
+*Additional Layers*
+ Other layers may exist. These could include kernel layers, such as
+ network protocol stacks, as well as user mode applications building
+ on standard POSIX system call APIs such as *open()*, *close()*,
+ *read()* and *write()*. On newer systems, POSIX Async I/O calls may
+ be an option. Such user mode code will not necessarily be subject to
+ the GNU General Public License (GPL).
+
+OTG-capable systems will also need to include a standard Linux-USB host
+side stack, with *usbcore*, one or more *Host Controller Drivers*
+(HCDs), *USB Device Drivers* to support the OTG "Targeted Peripheral
+List", and so forth. There will also be an *OTG Controller Driver*,
+which is visible to gadget and device driver developers only indirectly.
+That helps the host and device side USB controllers implement the two
+new OTG protocols (HNP and SRP). Roles switch (host to peripheral, or
+vice versa) using HNP during USB suspend processing, and SRP can be
+viewed as a more battery-friendly kind of device wakeup protocol.
+
+Over time, reusable utilities are evolving to help make some gadget
+driver tasks simpler. For example, building configuration descriptors
+from vectors of descriptors for the configurations interfaces and
+endpoints is now automated, and many drivers now use autoconfiguration
+to choose hardware endpoints and initialize their descriptors. A
+potential example of particular interest is code implementing standard
+USB-IF protocols for HID, networking, storage, or audio classes. Some
+developers are interested in KDB or KGDB hooks, to let target hardware
+be remotely debugged. Most such USB protocol code doesn't need to be
+hardware-specific, any more than network protocols like X11, HTTP, or
+NFS are. Such gadget-side interface drivers should eventually be
+combined, to implement composite devices.
+
+Kernel Mode Gadget API
+======================
+
+Gadget drivers declare themselves through a *struct
+usb\_gadget\_driver*, which is responsible for most parts of enumeration
+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.
+
+ **Note**
+
+ This documentation was prepared using the standard Linux kernel
+ ``docproc`` tool, which turns text and in-code comments into SGML
+ DocBook and then into usable formats such as HTML or PDF. Other than
+ the "Chapter 9" data types, most of the significant data types and
+ functions are described here.
+
+ However, docproc does not understand all the C constructs that are
+ used, so some relevant information is likely omitted from what you
+ are reading. One example of such information is endpoint
+ autoconfiguration. You'll have to read the header file, and use
+ example source code (such as that for "Gadget Zero"), to fully
+ understand the API.
+
+ The part of the API implementing some basic driver capabilities is
+ specific to the version of the Linux kernel that's in use. The 2.6
+ kernel includes a *driver model* framework that has no analogue on
+ earlier kernels; so those parts of the gadget API are not fully
+ portable. (They are implemented on 2.4 kernels, but in a different
+ way.) The driver model state is another part of this API that is
+ ignored by the kerneldoc tools.
+
+The core API does not expose every possible hardware feature, only the
+most widely available ones. There are significant hardware features,
+such as device-to-device DMA (without temporary storage in a memory
+buffer) that would be added using hardware-specific APIs.
+
+This API allows drivers to use conditional compilation to handle
+endpoint capabilities of different hardware, but doesn't require that.
+Hardware tends to have arbitrary restrictions, relating to transfer
+types, addressing, packet sizes, buffering, and availability. As a rule,
+such differences only matter for "endpoint zero" logic that handles
+device configuration and management. The API supports limited run-time
+detection of capabilities, through naming conventions for endpoints.
+Many drivers will be able to at least partially autoconfigure
+themselves. In particular, driver init sections will often have endpoint
+autoconfiguration logic that scans the hardware's list of endpoints to
+find ones matching the driver requirements (relying on those
+conventions), to eliminate some of the most common reasons for
+conditional compilation.
+
+Like the Linux-USB host side API, this API exposes the "chunky" nature
+of USB messages: I/O requests are in terms of one or more "packets", and
+packet boundaries are visible to drivers. Compared to RS-232 serial
+protocols, USB resembles synchronous protocols like HDLC (N bytes per
+frame, multipoint addressing, host as the primary station and devices as
+secondary stations) more than asynchronous ones (tty style: 8 data bits
+per frame, no parity, one stop bit). So for example the controller
+drivers won't buffer two single byte writes into a single two-byte USB
+IN packet, although gadget drivers may do so when they implement
+protocols where packet boundaries (and "short packets") are not
+significant.
+
+Driver Life Cycle
+-----------------
+
+Gadget drivers make endpoint I/O requests to hardware without needing to
+know many details of the hardware, but driver setup/configuration code
+needs to handle some differences. Use the API like this:
+
+1. Register a driver for the particular device side usb controller
+ hardware, such as the net2280 on PCI (USB 2.0), sa11x0 or pxa25x as
+ found in Linux PDAs, and so on. At this point the device is logically
+ in the USB ch9 initial state ("attached"), drawing no power and not
+ usable (since it does not yet support enumeration). Any host should
+ not see the device, since it's not activated the data line pullup
+ used by the host to detect a device, even if VBUS power is available.
+
+2. Register a gadget driver that implements some higher level device
+ function. That will then bind() to a usb\_gadget, which activates the
+ data line pullup sometime after detecting VBUS.
+
+3. The hardware driver can now start enumerating. The steps it handles
+ are to accept USB power and set\_address requests. Other steps are
+ handled by the gadget driver. If the gadget driver module is unloaded
+ before the host starts to enumerate, steps before step 7 are skipped.
+
+4. The gadget driver's setup() call returns usb descriptors, based both
+ on what the bus interface hardware provides and on the functionality
+ being implemented. That can involve alternate settings or
+ configurations, unless the hardware prevents such operation. For OTG
+ devices, each configuration descriptor includes an OTG descriptor.
+
+5. The gadget driver handles the last step of enumeration, when the USB
+ host issues a set\_configuration call. It enables all endpoints used
+ in that configuration, with all interfaces in their default settings.
+ That involves using a list of the hardware's endpoints, enabling each
+ endpoint according to its descriptor. It may also involve using
+ ``usb_gadget_vbus_draw`` to let more power be drawn from VBUS, as
+ allowed by that configuration. For OTG devices, setting a
+ configuration may also involve reporting HNP capabilities through a
+ user interface.
+
+6. Do real work and perform data transfers, possibly involving changes
+ to interface settings or switching to new configurations, until the
+ device is disconnect()ed from the host. Queue any number of transfer
+ requests to each endpoint. It may be suspended and resumed several
+ times before being disconnected. On disconnect, the drivers go back
+ to step 3 (above).
+
+7. When the gadget driver module is being unloaded, the driver unbind()
+ callback is issued. That lets the controller driver be unloaded.
+
+Drivers will normally be arranged so that just loading the gadget driver
+module (or statically linking it into a Linux kernel) allows the
+peripheral device to be enumerated, but some drivers will defer
+enumeration until some higher level component (like a user mode daemon)
+enables it. Note that at this lowest level there are no policies about
+how ep0 configuration logic is implemented, except that it should obey
+USB specifications. Such issues are in the domain of gadget drivers,
+including knowing about implementation constraints imposed by some USB
+controllers or understanding that composite devices might happen to be
+built by integrating reusable components.
+
+Note that the lifecycle above can be slightly different for OTG devices.
+Other than providing an additional OTG descriptor in each configuration,
+only the HNP-related differences are particularly visible to driver
+code. They involve reporting requirements during the SET\_CONFIGURATION
+request, and the option to invoke HNP during some suspend callbacks.
+Also, SRP changes the semantics of ``usb_gadget_wakeup`` slightly.
+
+USB 2.0 Chapter 9 Types and Constants
+-------------------------------------
+
+Gadget drivers rely on common USB structures and constants defined in
+the ``<linux/usb/ch9.h>`` header file, which is standard in Linux 2.6
+kernels. These are the same types and constants used by host side
+drivers (and usbcore).
+
+!Iinclude/linux/usb/ch9.h
+Core Objects and Methods
+------------------------
+
+These are declared in ``<linux/usb/gadget.h>``, and are used by gadget
+drivers to interact with USB peripheral controller drivers.
+
+!Iinclude/linux/usb/gadget.h
+Optional Utilities
+------------------
+
+The core API is sufficient for writing a USB Gadget Driver, but some
+optional utilities are provided to simplify common tasks. These
+utilities include endpoint autoconfiguration.
+
+!Edrivers/usb/gadget/usbstring.c !Edrivers/usb/gadget/config.c
+Composite Device Framework
+--------------------------
+
+The core API is sufficient for writing drivers for composite USB devices
+(with more than one function in a given configuration), and also
+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 usb\_composite\_driver*,
+which in turn provides one or more *struct usb\_configuration*
+instances. Each such configuration includes at least one *struct
+usb\_function*, which packages a user visible role such as "network
+link" or "mass storage device". Management functions may also exist,
+such as "Device Firmware Upgrade".
+
+!Iinclude/linux/usb/composite.h !Edrivers/usb/gadget/composite.c
+Composite Device Functions
+--------------------------
+
+At this writing, a few of the current gadget drivers have been converted
+to this framework. Near-term plans include converting all of them,
+except for "gadgetfs".
+
+!Edrivers/usb/gadget/function/f\_acm.c
+!Edrivers/usb/gadget/function/f\_ecm.c
+!Edrivers/usb/gadget/function/f\_subset.c
+!Edrivers/usb/gadget/function/f\_obex.c
+!Edrivers/usb/gadget/function/f\_serial.c
+Peripheral Controller Drivers
+=============================
+
+The first hardware supporting this API was the NetChip 2280 controller,
+which supports USB 2.0 high speed and is based on PCI. This is the
+``net2280`` driver module. The driver supports Linux kernel versions 2.4
+and 2.6; contact NetChip Technologies for development boards and product
+information.
+
+Other hardware working in the "gadget" framework includes: Intel's PXA
+25x and IXP42x series processors (``pxa2xx_udc``), Toshiba TC86c001
+"Goku-S" (``goku_udc``), Renesas SH7705/7727 (``sh_udc``), MediaQ 11xx
+(``mq11xx_udc``), Hynix HMS30C7202 (``h7202_udc``), National 9303/4
+(``n9604_udc``), Texas Instruments OMAP (``omap_udc``), Sharp LH7A40x
+(``lh7a40x_udc``), and more. Most of those are full speed controllers.
+
+At this writing, there are people at work on drivers in this framework
+for several other USB device controllers, with plans to make many of
+them be widely available.
+
+A partial USB simulator, the ``dummy_hcd`` driver, is available. It can
+act like a net2280, a pxa25x, or an sa11x0 in terms of available
+endpoints and device speeds; and it simulates control, bulk, and to some
+extent interrupt transfers. That lets you develop some parts of a gadget
+driver on a normal PC, without any special hardware, and perhaps with
+the assistance of tools such as GDB running with User Mode Linux. At
+least one person has expressed interest in adapting that approach,
+hooking it up to a simulator for a microcontroller. Such simulators can
+help debug subsystems where the runtime hardware is unfriendly to
+software development, or is not yet available.
+
+Support for other controllers is expected to be developed and
+contributed over time, as this driver framework evolves.
+
+Gadget Drivers
+==============
+
+In addition to *Gadget Zero* (used primarily for testing and development
+with drivers for usb controller hardware), other gadget drivers exist.
+
+There's an *ethernet* gadget driver, which implements one of the most
+useful *Communications Device Class* (CDC) models. One of the standards
+for cable modem interoperability even specifies the use of this ethernet
+model as one of two mandatory options. Gadgets using this code look to a
+USB host as if they're an Ethernet adapter. It provides access to a
+network where the gadget's CPU is one host, which could easily be
+bridging, routing, or firewalling access to other networks. Since some
+hardware can't fully implement the CDC Ethernet requirements, this
+driver also implements a "good parts only" subset of CDC Ethernet. (That
+subset doesn't advertise itself as CDC Ethernet, to avoid creating
+problems.)
+
+Support for Microsoft's *RNDIS* protocol has been contributed by
+Pengutronix and Auerswald GmbH. This is like CDC Ethernet, but it runs
+on more slightly USB hardware (but less than the CDC subset). However,
+its main claim to fame is being able to connect directly to recent
+versions of Windows, using drivers that Microsoft bundles and supports,
+making it much simpler to network with Windows.
+
+There is also support for user mode gadget drivers, using *gadgetfs*.
+This provides a *User Mode API* that presents each endpoint as a single
+file descriptor. I/O is done using normal *read()* and *read()* calls.
+Familiar tools like GDB and pthreads can be used to develop and debug
+user mode drivers, so that once a robust controller driver is available
+many applications for it won't require new kernel mode software. Linux
+2.6 *Async I/O (AIO)* support is available, so that user mode software
+can stream data with only slightly more overhead than a kernel driver.
+
+There's a USB Mass Storage class driver, which provides a different
+solution for interoperability with systems such as MS-Windows and MacOS.
+That *Mass Storage* driver uses a file or block device as backing store
+for a drive, like the ``loop`` driver. The USB host uses the BBB, CB, or
+CBI versions of the mass storage class specification, using transparent
+SCSI commands to access the data from the backing store.
+
+There's a "serial line" driver, useful for TTY style operation over USB.
+The latest version of that driver supports CDC ACM style operation, like
+a USB modem, and so on most hardware it can interoperate easily with
+MS-Windows. One interesting use of that driver is in boot firmware (like
+a BIOS), which can sometimes use that model with very small systems
+without real serial lines.
+
+Support for other kinds of gadget is expected to be developed and
+contributed over time, as this driver framework evolves.
+
+USB On-The-GO (OTG)
+===================
+
+USB OTG support on Linux 2.6 was initially developed by Texas
+Instruments for `OMAP <http://www.omap.com>`__ 16xx and 17xx series
+processors. Other OTG systems should work in similar ways, but the
+hardware level details could be very different.
+
+Systems need specialized hardware support to implement OTG, notably
+including a special *Mini-AB* jack and associated transceiver to support
+*Dual-Role* operation: they can act either as a host, using the standard
+Linux-USB host side driver stack, or as a peripheral, using this
+"gadget" framework. To do that, the system software relies on small
+additions to those programming interfaces, and on a new internal
+component (here called an "OTG Controller") affecting which driver stack
+connects to the OTG port. In each role, the system can re-use the
+existing pool of hardware-neutral drivers, layered on top of the
+controller driver interfaces (*usb\_bus* or *usb\_gadget*). Such drivers
+need at most minor changes, and most of the calls added to support OTG
+can also benefit non-OTG products.
+
+- Gadget drivers test the *is\_otg* flag, and use it to determine
+ whether or not to include an OTG descriptor in each of their
+ configurations.
+
+- Gadget drivers may need changes to support the two new OTG protocols,
+ exposed in new gadget attributes such as *b\_hnp\_enable* flag. HNP
+ support should be reported through a user interface (two LEDs could
+ suffice), and is triggered in some cases when the host suspends the
+ peripheral. SRP support can be user-initiated just like remote
+ wakeup, probably by pressing the same button.
+
+- On the host side, USB device drivers need to be taught to trigger HNP
+ at appropriate moments, using ``usb_suspend_device()``. That also
+ conserves battery power, which is useful even for non-OTG
+ configurations.
+
+- Also on the host side, a driver must support the OTG "Targeted
+ Peripheral List". That's just a whitelist, used to reject peripherals
+ not supported with a given Linux OTG host. *This whitelist is
+ product-specific; each product must modify ``otg_whitelist.h`` to
+ match its interoperability specification.*
+
+ Non-OTG Linux hosts, like PCs and workstations, normally have some
+ solution for adding drivers, so that peripherals that aren't
+ recognized can eventually be supported. That approach is unreasonable
+ for consumer products that may never have their firmware upgraded,
+ and where it's usually unrealistic to expect traditional
+ PC/workstation/server kinds of support model to work. For example,
+ it's often impractical to change device firmware once the product has
+ been distributed, so driver bugs can't normally be fixed if they're
+ found after shipment.
+
+Additional changes are needed below those hardware-neutral *usb\_bus*
+and *usb\_gadget* driver interfaces; those aren't discussed here in any
+detail. Those affect the hardware-specific code for each USB Host or
+Peripheral controller, and how the HCD initializes (since OTG can be
+active only on a single port). They also involve what may be called an
+*OTG Controller Driver*, managing the OTG transceiver and the OTG state
+machine logic as well as much of the root hub behavior for the OTG port.
+The OTG controller driver needs to activate and deactivate USB
+controllers depending on the relevant device role. Some related changes
+were needed inside usbcore, so that it can identify OTG-capable devices
+and respond appropriately to HNP or SRP protocols.
diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst
new file mode 100644
index 000000000000..cf2fa2e8d236
--- /dev/null
+++ b/Documentation/driver-api/usb/index.rst
@@ -0,0 +1,17 @@
+=============
+Linux USB API
+=============
+
+.. toctree::
+
+ usb
+ gadget
+ writing_usb_driver
+ writing_musb_glue_layer
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/driver-api/usb.rst b/Documentation/driver-api/usb/usb.rst
similarity index 87%
rename from Documentation/driver-api/usb.rst
rename to Documentation/driver-api/usb/usb.rst
index 851cc40b66b5..b856abb3200e 100644
--- a/Documentation/driver-api/usb.rst
+++ b/Documentation/driver-api/usb/usb.rst
@@ -329,11 +329,11 @@ to detect when devices are added or removed:
fd = open("/proc/bus/usb/devices", O_RDONLY);
pfd = { fd, POLLIN, 0 };
for (;;) {
- /* The first time through, this call will return immediately. */
- poll(&pfd, 1, -1);
+ /* The first time through, this call will return immediately. */
+ poll(&pfd, 1, -1);
- /* To see what's changed, compare the file's previous and current
- contents or scan the filesystem. (Scanning is more precise.) */
+ /* To see what's changed, compare the file's previous and current
+ contents or scan the filesystem. (Scanning is more precise.) */
}
Note that this behavior is intended to be used for informational and
@@ -462,10 +462,10 @@ USBDEVFS_CONNECTINFO
::
- struct usbdevfs_connectinfo {
- unsigned int devnum;
- unsigned char slow;
- };
+ struct usbdevfs_connectinfo {
+ unsigned int devnum;
+ unsigned char slow;
+ };
File modification time is not updated by this request.
@@ -481,10 +481,10 @@ USBDEVFS_GETDRIVER
::
- struct usbdevfs_getdriver {
- unsigned int interface;
- char driver[USBDEVFS_MAXDRIVERNAME + 1];
- };
+ struct usbdevfs_getdriver {
+ unsigned int interface;
+ char driver[USBDEVFS_MAXDRIVERNAME + 1];
+ };
File modification time is not updated by this request.
@@ -494,28 +494,28 @@ USBDEVFS_IOCTL
::
- struct usbdevfs_ioctl {
- int ifno;
- int ioctl_code;
- void *data;
- };
+ struct usbdevfs_ioctl {
+ int ifno;
+ int ioctl_code;
+ void *data;
+ };
- /* user mode call looks like this.
- * 'request' becomes the driver->ioctl() 'code' parameter.
- * the size of 'param' is encoded in 'request', and that data
- * is copied to or from the driver->ioctl() 'buf' parameter.
- */
- static int
- usbdev_ioctl (int fd, int ifno, unsigned request, void *param)
- {
- struct usbdevfs_ioctl wrapper;
+ /* user mode call looks like this.
+ * 'request' becomes the driver->ioctl() 'code' parameter.
+ * the size of 'param' is encoded in 'request', and that data
+ * is copied to or from the driver->ioctl() 'buf' parameter.
+ */
+ static int
+ usbdev_ioctl (int fd, int ifno, unsigned request, void *param)
+ {
+ struct usbdevfs_ioctl wrapper;
- wrapper.ifno = ifno;
- wrapper.ioctl_code = request;
- wrapper.data = param;
+ wrapper.ifno = ifno;
+ wrapper.ioctl_code = request;
+ wrapper.data = param;
- return ioctl (fd, USBDEVFS_IOCTL, &wrapper);
- }
+ return ioctl (fd, USBDEVFS_IOCTL, &wrapper);
+ }
File modification time is not updated by this request.
@@ -534,11 +534,11 @@ USBDEVFS_RELEASEINTERFACE
the number of the interface (bInterfaceNumber from descriptor); File
modification time is not updated by this request.
- **Warning**
+ **Warning**
- *No security check is made to ensure that the task which made
- the claim is the one which is releasing it. This means that user
- mode driver may interfere other ones.*
+ *No security check is made to ensure that the task which made
+ the claim is the one which is releasing it. This means that user
+ mode driver may interfere other ones.*
USBDEVFS_RESETEP
Resets the data toggle value for an endpoint (bulk or interrupt) to
@@ -546,13 +546,13 @@ USBDEVFS_RESETEP
as identified in the endpoint descriptor), with USB_DIR_IN added
if the device's endpoint sends data to the host.
- **Warning**
+ **Warning**
- *Avoid using this request. It should probably be removed.* Using
- it typically means the device and driver will lose toggle
- synchronization. If you really lost synchronization, you likely
- need to completely handshake with the device, using a request
- like CLEAR_HALT or SET_INTERFACE.
+ *Avoid using this request. It should probably be removed.* Using
+ it typically means the device and driver will lose toggle
+ synchronization. If you really lost synchronization, you likely
+ need to completely handshake with the device, using a request
+ like CLEAR_HALT or SET_INTERFACE.
USBDEVFS_DROP_PRIVILEGES
This is used to relinquish the ability to do certain operations
@@ -578,12 +578,12 @@ USBDEVFS_BULK
::
- struct usbdevfs_bulktransfer {
- unsigned int ep;
- unsigned int len;
- unsigned int timeout; /* in milliseconds */
- void *data;
- };
+ struct usbdevfs_bulktransfer {
+ unsigned int ep;
+ unsigned int len;
+ unsigned int timeout; /* in milliseconds */
+ void *data;
+ };
The "ep" value identifies a bulk endpoint number (1 to 15, as
identified in an endpoint descriptor), masked with USB_DIR_IN when
@@ -610,15 +610,15 @@ USBDEVFS_CONTROL
::
- struct usbdevfs_ctrltransfer {
- __u8 bRequestType;
- __u8 bRequest;
- __u16 wValue;
- __u16 wIndex;
- __u16 wLength;
- __u32 timeout; /* in milliseconds */
- void *data;
- };
+ struct usbdevfs_ctrltransfer {
+ __u8 bRequestType;
+ __u8 bRequest;
+ __u16 wValue;
+ __u16 wIndex;
+ __u16 wLength;
+ __u32 timeout; /* in milliseconds */
+ void *data;
+ };
The first eight bytes of this structure are the contents of the
SETUP packet to be sent to the device; see the USB 2.0 specification
@@ -638,11 +638,11 @@ USBDEVFS_RESET
the reset, this rebinds all device interfaces. File modification
time is not updated by this request.
- **Warning**
+ **Warning**
- *Avoid using this call* until some usbcore bugs get fixed, since
- it does not fully synchronize device, interface, and driver (not
- just usbfs) state.
+ *Avoid using this call* until some usbcore bugs get fixed, since
+ it does not fully synchronize device, interface, and driver (not
+ just usbfs) state.
USBDEVFS_SETINTERFACE
Sets the alternate setting for an interface. The ioctl parameter is
@@ -650,10 +650,10 @@ USBDEVFS_SETINTERFACE
::
- struct usbdevfs_setinterface {
- unsigned int interface;
- unsigned int altsetting;
- };
+ struct usbdevfs_setinterface {
+ unsigned int interface;
+ unsigned int altsetting;
+ };
File modification time is not updated by this request.
@@ -669,11 +669,11 @@ USBDEVFS_SETCONFIGURATION
configuration (bConfigurationValue from descriptor). File
modification time is not updated by this request.
- **Warning**
+ **Warning**
- *Avoid using this call* until some usbcore bugs get fixed, since
- it does not fully synchronize device, interface, and driver (not
- just usbfs) state.
+ *Avoid using this call* until some usbcore bugs get fixed, since
+ it does not fully synchronize device, interface, and driver (not
+ just usbfs) state.
Asynchronous I/O Support
~~~~~~~~~~~~~~~~~~~~~~~~
@@ -707,25 +707,25 @@ fewer bytes were read than were requested then you get an error report.
::
struct usbdevfs_iso_packet_desc {
- unsigned int length;
- unsigned int actual_length;
- unsigned int status;
+ unsigned int length;
+ unsigned int actual_length;
+ unsigned int status;
};
struct usbdevfs_urb {
- unsigned char type;
- unsigned char endpoint;
- int status;
- unsigned int flags;
- void *buffer;
- int buffer_length;
- int actual_length;
- int start_frame;
- int number_of_packets;
- int error_count;
- unsigned int signr;
- void *usercontext;
- struct usbdevfs_iso_packet_desc iso_frame_desc[];
+ unsigned char type;
+ unsigned char endpoint;
+ int status;
+ unsigned int flags;
+ void *buffer;
+ int buffer_length;
+ int actual_length;
+ int start_frame;
+ int number_of_packets;
+ int error_count;
+ unsigned int signr;
+ void *usercontext;
+ struct usbdevfs_iso_packet_desc iso_frame_desc[];
};
For these asynchronous requests, the file modification time reflects
diff --git a/Documentation/driver-api/usb/writing_musb_glue_layer.rst b/Documentation/driver-api/usb/writing_musb_glue_layer.rst
new file mode 100644
index 000000000000..2546a102394f
--- /dev/null
+++ b/Documentation/driver-api/usb/writing_musb_glue_layer.rst
@@ -0,0 +1,731 @@
+Introduction
+============
+
+The Linux MUSB subsystem is part of the larger Linux USB subsystem. It
+provides support for embedded USB Device Controllers (UDC) that do not
+use Universal Host Controller Interface (UHCI) or Open Host Controller
+Interface (OHCI).
+
+Instead, these embedded UDC rely on the USB On-the-Go (OTG)
+specification which they implement at least partially. The silicon
+reference design used in most cases is the Multipoint USB Highspeed
+Dual-Role Controller (MUSB HDRC) found in the Mentor Graphics Inventra™
+design.
+
+As a self-taught exercise I have written an MUSB glue layer for the
+Ingenic JZ4740 SoC, modelled after the many MUSB glue layers in the
+kernel source tree. This layer can be found at
+drivers/usb/musb/jz4740.c. In this documentation I will walk through the
+basics of the jz4740.c glue layer, explaining the different pieces and
+what needs to be done in order to write your own device glue layer.
+
+Linux MUSB Basics
+=================
+
+To get started on the topic, please read USB On-the-Go Basics (see
+Resources) which provides an introduction of USB OTG operation at the
+hardware level. A couple of wiki pages by Texas Instruments and Analog
+Devices also provide an overview of the Linux kernel MUSB configuration,
+albeit focused on some specific devices provided by these companies.
+Finally, getting acquainted with the USB specification at USB home page
+may come in handy, with practical instance provided through the Writing
+USB Device Drivers documentation (again, see Resources).
+
+Linux USB stack is a layered architecture in which the MUSB controller
+hardware sits at the lowest. The MUSB controller driver abstract the
+MUSB controller hardware to the Linux USB stack.
+
+::
+
+ ------------------------
+ | | <------- drivers/usb/gadget
+ | Linux USB Core Stack | <------- drivers/usb/host
+ | | <------- drivers/usb/core
+ ------------------------
+ ⬍
+ --------------------------
+ | | <------ drivers/usb/musb/musb_gadget.c
+ | MUSB Controller driver | <------ drivers/usb/musb/musb_host.c
+ | | <------ drivers/usb/musb/musb_core.c
+ --------------------------
+ ⬍
+ ---------------------------------
+ | MUSB Platform Specific Driver |
+ | | <-- drivers/usb/musb/jz4740.c
+ | aka "Glue Layer" |
+ ---------------------------------
+ ⬍
+ ---------------------------------
+ | MUSB Controller Hardware |
+ ---------------------------------
+
+
+As outlined above, the glue layer is actually the platform specific code
+sitting in between the controller driver and the controller hardware.
+
+Just like a Linux USB driver needs to register itself with the Linux USB
+subsystem, the MUSB glue layer needs first to register itself with the
+MUSB controller driver. This will allow the controller driver to know
+about which device the glue layer supports and which functions to call
+when a supported device is detected or released; remember we are talking
+about an embedded controller chip here, so no insertion or removal at
+run-time.
+
+All of this information is passed to the MUSB controller driver through
+a platform\_driver structure defined in the glue layer as:
+
+::
+
+ static struct platform_driver jz4740_driver = {
+ .probe = jz4740_probe,
+ .remove = jz4740_remove,
+ .driver = {
+ .name = "musb-jz4740",
+ },
+ };
+
+
+The probe and remove function pointers are called when a matching device
+is detected and, respectively, released. The name string describes the
+device supported by this glue layer. In the current case it matches a
+platform\_device structure declared in arch/mips/jz4740/platform.c. Note
+that we are not using device tree bindings here.
+
+In order to register itself to the controller driver, the glue layer
+goes through a few steps, basically allocating the controller hardware
+resources and initialising a couple of circuits. To do so, it needs to
+keep track of the information used throughout these steps. This is done
+by defining a private jz4740\_glue structure:
+
+::
+
+ struct jz4740_glue {
+ struct device *dev;
+ struct platform_device *musb;
+ struct clk *clk;
+ };
+
+
+The dev and musb members are both device structure variables. The first
+one holds generic information about the device, since it's the basic
+device structure, and the latter holds information more closely related
+to the subsystem the device is registered to. The clk variable keeps
+information related to the device clock operation.
+
+Let's go through the steps of the probe function that leads the glue
+layer to register itself to the controller driver.
+
+N.B.: For the sake of readability each function will be split in logical
+parts, each part being shown as if it was independent from the others.
+
+::
+
+ static int jz4740_probe(struct platform_device *pdev)
+ {
+ struct platform_device *musb;
+ struct jz4740_glue *glue;
+ struct clk *clk;
+ int ret;
+
+ glue = devm_kzalloc(&pdev->dev, sizeof(*glue), GFP_KERNEL);
+ if (!glue)
+ return -ENOMEM;
+
+ musb = platform_device_alloc("musb-hdrc", PLATFORM_DEVID_AUTO);
+ if (!musb) {
+ dev_err(&pdev->dev, "failed to allocate musb device\n");
+ return -ENOMEM;
+ }
+
+ clk = devm_clk_get(&pdev->dev, "udc");
+ if (IS_ERR(clk)) {
+ dev_err(&pdev->dev, "failed to get clock\n");
+ ret = PTR_ERR(clk);
+ goto err_platform_device_put;
+ }
+
+ ret = clk_prepare_enable(clk);
+ if (ret) {
+ dev_err(&pdev->dev, "failed to enable clock\n");
+ goto err_platform_device_put;
+ }
+
+ musb->dev.parent = &pdev->dev;
+
+ glue->dev = &pdev->dev;
+ glue->musb = musb;
+ glue->clk = clk;
+
+ return 0;
+
+ err_platform_device_put:
+ platform_device_put(musb);
+ return ret;
+ }
+
+
+The first few lines of the probe function allocate and assign the glue,
+musb and clk variables. The GFP\_KERNEL flag (line 8) allows the
+allocation process to sleep and wait for memory, thus being usable in a
+blocking situation. The PLATFORM\_DEVID\_AUTO flag (line 12) allows
+automatic allocation and management of device IDs in order to avoid
+device namespace collisions with explicit IDs. With devm\_clk\_get()
+(line 18) the glue layer allocates the clock -- the ``devm_`` prefix
+indicates that clk\_get() is managed: it automatically frees the
+allocated clock resource data when the device is released -- and enable
+it.
+
+Then comes the registration steps:
+
+::
+
+ static int jz4740_probe(struct platform_device *pdev)
+ {
+ struct musb_hdrc_platform_data *pdata = &jz4740_musb_platform_data;
+
+ pdata->platform_ops = &jz4740_musb_ops;
+
+ platform_set_drvdata(pdev, glue);
+
+ ret = platform_device_add_resources(musb, pdev->resource,
+ pdev->num_resources);
+ if (ret) {
+ dev_err(&pdev->dev, "failed to add resources\n");
+ goto err_clk_disable;
+ }
+
+ ret = platform_device_add_data(musb, pdata, sizeof(*pdata));
+ if (ret) {
+ dev_err(&pdev->dev, "failed to add platform_data\n");
+ goto err_clk_disable;
+ }
+
+ return 0;
+
+ err_clk_disable:
+ clk_disable_unprepare(clk);
+ err_platform_device_put:
+ platform_device_put(musb);
+ return ret;
+ }
+
+
+The first step is to pass the device data privately held by the glue
+layer on to the controller driver through platform\_set\_drvdata() (line
+7). Next is passing on the device resources information, also privately
+held at that point, through platform\_device\_add\_resources() (line 9).
+
+Finally comes passing on the platform specific data to the controller
+driver (line 16). Platform data will be discussed in `Chapter
+4 <#device-platform-data>`__, but here we are looking at the
+platform\_ops function pointer (line 5) in musb\_hdrc\_platform\_data
+structure (line 3). This function pointer allows the MUSB controller
+driver to know which function to call for device operation:
+
+::
+
+ static const struct musb_platform_ops jz4740_musb_ops = {
+ .init = jz4740_musb_init,
+ .exit = jz4740_musb_exit,
+ };
+
+
+Here we have the minimal case where only init and exit functions are
+called by the controller driver when needed. Fact is the JZ4740 MUSB
+controller is a basic controller, lacking some features found in other
+controllers, otherwise we may also have pointers to a few other
+functions like a power management function or a function to switch
+between OTG and non-OTG modes, for instance.
+
+At that point of the registration process, the controller driver
+actually calls the init function:
+
+::
+
+ static int jz4740_musb_init(struct musb *musb)
+ {
+ musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2);
+ if (!musb->xceiv) {
+ pr_err("HS UDC: no transceiver configured\n");
+ return -ENODEV;
+ }
+
+ /* Silicon does not implement ConfigData register.
+ * Set dyn_fifo to avoid reading EP config from hardware.
+ */
+ musb->dyn_fifo = true;
+
+ musb->isr = jz4740_musb_interrupt;
+
+ return 0;
+ }
+
+
+The goal of jz4740\_musb\_init() is to get hold of the transceiver
+driver data of the MUSB controller hardware and pass it on to the MUSB
+controller driver, as usual. The transceiver is the circuitry inside the
+controller hardware responsible for sending/receiving the USB data.
+Since it is an implementation of the physical layer of the OSI model,
+the transceiver is also referred to as PHY.
+
+Getting hold of the MUSB PHY driver data is done with usb\_get\_phy()
+which returns a pointer to the structure containing the driver instance
+data. The next couple of instructions (line 12 and 14) are used as a
+quirk and to setup IRQ handling respectively. Quirks and IRQ handling
+will be discussed later in `Chapter 5 <#device-quirks>`__ and `Chapter
+3 <#handling-irqs>`__.
+
+::
+
+ static int jz4740_musb_exit(struct musb *musb)
+ {
+ usb_put_phy(musb->xceiv);
+
+ return 0;
+ }
+
+
+Acting as the counterpart of init, the exit function releases the MUSB
+PHY driver when the controller hardware itself is about to be released.
+
+Again, note that init and exit are fairly simple in this case due to the
+basic set of features of the JZ4740 controller hardware. When writing an
+musb glue layer for a more complex controller hardware, you might need
+to take care of more processing in those two functions.
+
+Returning from the init function, the MUSB controller driver jumps back
+into the probe function:
+
+::
+
+ static int jz4740_probe(struct platform_device *pdev)
+ {
+ ret = platform_device_add(musb);
+ if (ret) {
+ dev_err(&pdev->dev, "failed to register musb device\n");
+ goto err_clk_disable;
+ }
+
+ return 0;
+
+ err_clk_disable:
+ clk_disable_unprepare(clk);
+ err_platform_device_put:
+ platform_device_put(musb);
+ return ret;
+ }
+
+
+This is the last part of the device registration process where the glue
+layer adds the controller hardware device to Linux kernel device
+hierarchy: at this stage, all known information about the device is
+passed on to the Linux USB core stack.
+
+::
+
+ static int jz4740_remove(struct platform_device *pdev)
+ {
+ struct jz4740_glue *glue = platform_get_drvdata(pdev);
+
+ platform_device_unregister(glue->musb);
+ clk_disable_unprepare(glue->clk);
+
+ return 0;
+ }
+
+
+Acting as the counterpart of probe, the remove function unregister the
+MUSB controller hardware (line 5) and disable the clock (line 6),
+allowing it to be gated.
+
+Handling IRQs
+=============
+
+Additionally to the MUSB controller hardware basic setup and
+registration, the glue layer is also responsible for handling the IRQs:
+
+::
+
+ static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci)
+ {
+ unsigned long flags;
+ irqreturn_t retval = IRQ_NONE;
+ struct musb *musb = __hci;
+
+ spin_lock_irqsave(&musb->lock, flags);
+
+ musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB);
+ musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX);
+ musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX);
+
+ /*
+ * The controller is gadget only, the state of the host mode IRQ bits is
+ * undefined. Mask them to make sure that the musb driver core will
+ * never see them set
+ */
+ musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME |
+ MUSB_INTR_RESET | MUSB_INTR_SOF;
+
+ if (musb->int_usb || musb->int_tx || musb->int_rx)
+ retval = musb_interrupt(musb);
+
+ spin_unlock_irqrestore(&musb->lock, flags);
+
+ return retval;
+ }
+
+
+Here the glue layer mostly has to read the relevant hardware registers
+and pass their values on to the controller driver which will handle the
+actual event that triggered the IRQ.
+
+The interrupt handler critical section is protected by the
+spin\_lock\_irqsave() and counterpart spin\_unlock\_irqrestore()
+functions (line 7 and 24 respectively), which prevent the interrupt
+handler code to be run by two different threads at the same time.
+
+Then the relevant interrupt registers are read (line 9 to 11):
+
+- MUSB\_INTRUSB: indicates which USB interrupts are currently active,
+
+- MUSB\_INTRTX: indicates which of the interrupts for TX endpoints are
+ currently active,
+
+- MUSB\_INTRRX: indicates which of the interrupts for TX endpoints are
+ currently active.
+
+Note that musb\_readb() is used to read 8-bit registers at most, while
+musb\_readw() allows us to read at most 16-bit registers. There are
+other functions that can be used depending on the size of your device
+registers. See musb\_io.h for more information.
+
+Instruction on line 18 is another quirk specific to the JZ4740 USB
+device controller, which will be discussed later in `Chapter
+5 <#device-quirks>`__.
+
+The glue layer still needs to register the IRQ handler though. Remember
+the instruction on line 14 of the init function:
+
+::
+
+ static int jz4740_musb_init(struct musb *musb)
+ {
+ musb->isr = jz4740_musb_interrupt;
+
+ return 0;
+ }
+
+
+This instruction sets a pointer to the glue layer IRQ handler function,
+in order for the controller hardware to call the handler back when an
+IRQ comes from the controller hardware. The interrupt handler is now
+implemented and registered.
+
+Device Platform Data
+====================
+
+In order to write an MUSB glue layer, you need to have some data
+describing the hardware capabilities of your controller hardware, which
+is called the platform data.
+
+Platform data is specific to your hardware, though it may cover a broad
+range of devices, and is generally found somewhere in the arch/
+directory, depending on your device architecture.
+
+For instance, platform data for the JZ4740 SoC is found in
+arch/mips/jz4740/platform.c. In the platform.c file each device of the
+JZ4740 SoC is described through a set of structures.
+
+Here is the part of arch/mips/jz4740/platform.c that covers the USB
+Device Controller (UDC):
+
+::
+
+ /* USB Device Controller */
+ struct platform_device jz4740_udc_xceiv_device = {
+ .name = "usb_phy_gen_xceiv",
+ .id = 0,
+ };
+
+ static struct resource jz4740_udc_resources[] = {
+ [0] = {
+ .start = JZ4740_UDC_BASE_ADDR,
+ .end = JZ4740_UDC_BASE_ADDR + 0x10000 - 1,
+ .flags = IORESOURCE_MEM,
+ },
+ [1] = {
+ .start = JZ4740_IRQ_UDC,
+ .end = JZ4740_IRQ_UDC,
+ .flags = IORESOURCE_IRQ,
+ .name = "mc",
+ },
+ };
+
+ struct platform_device jz4740_udc_device = {
+ .name = "musb-jz4740",
+ .id = -1,
+ .dev = {
+ .dma_mask = &jz4740_udc_device.dev.coherent_dma_mask,
+ .coherent_dma_mask = DMA_BIT_MASK(32),
+ },
+ .num_resources = ARRAY_SIZE(jz4740_udc_resources),
+ .resource = jz4740_udc_resources,
+ };
+
+
+The jz4740\_udc\_xceiv\_device platform device structure (line 2)
+describes the UDC transceiver with a name and id number.
+
+At the time of this writing, note that "usb\_phy\_gen\_xceiv" is the
+specific name to be used for all transceivers that are either built-in
+with reference USB IP or autonomous and doesn't require any PHY
+programming. You will need to set CONFIG\_NOP\_USB\_XCEIV=y in the
+kernel configuration to make use of the corresponding transceiver
+driver. The id field could be set to -1 (equivalent to
+PLATFORM\_DEVID\_NONE), -2 (equivalent to PLATFORM\_DEVID\_AUTO) or
+start with 0 for the first device of this kind if we want a specific id
+number.
+
+The jz4740\_udc\_resources resource structure (line 7) defines the UDC
+registers base addresses.
+
+The first array (line 9 to 11) defines the UDC registers base memory
+addresses: start points to the first register memory address, end points
+to the last register memory address and the flags member defines the
+type of resource we are dealing with. So IORESOURCE\_MEM is used to
+define the registers memory addresses. The second array (line 14 to 17)
+defines the UDC IRQ registers addresses. Since there is only one IRQ
+register available for the JZ4740 UDC, start and end point at the same
+address. The IORESOURCE\_IRQ flag tells that we are dealing with IRQ
+resources, and the name "mc" is in fact hard-coded in the MUSB core in
+order for the controller driver to retrieve this IRQ resource by
+querying it by its name.
+
+Finally, the jz4740\_udc\_device platform device structure (line 21)
+describes the UDC itself.
+
+The "musb-jz4740" name (line 22) defines the MUSB driver that is used
+for this device; remember this is in fact the name that we used in the
+jz4740\_driver platform driver structure in `Chapter
+2 <#linux-musb-basics>`__. The id field (line 23) is set to -1
+(equivalent to PLATFORM\_DEVID\_NONE) since we do not need an id for the
+device: the MUSB controller driver was already set to allocate an
+automatic id in `Chapter 2 <#linux-musb-basics>`__. In the dev field we
+care for DMA related information here. The dma\_mask field (line 25)
+defines the width of the DMA mask that is going to be used, and
+coherent\_dma\_mask (line 26) has the same purpose but for the
+alloc\_coherent DMA mappings: in both cases we are using a 32 bits mask.
+Then the resource field (line 29) is simply a pointer to the resource
+structure defined before, while the num\_resources field (line 28) keeps
+track of the number of arrays defined in the resource structure (in this
+case there were two resource arrays defined before).
+
+With this quick overview of the UDC platform data at the arch/ level now
+done, let's get back to the MUSB glue layer specific platform data in
+drivers/usb/musb/jz4740.c:
+
+::
+
+ static struct musb_hdrc_config jz4740_musb_config = {
+ /* Silicon does not implement USB OTG. */
+ .multipoint = 0,
+ /* Max EPs scanned, driver will decide which EP can be used. */
+ .num_eps = 4,
+ /* RAMbits needed to configure EPs from table */
+ .ram_bits = 9,
+ .fifo_cfg = jz4740_musb_fifo_cfg,
+ .fifo_cfg_size = ARRAY_SIZE(jz4740_musb_fifo_cfg),
+ };
+
+ static struct musb_hdrc_platform_data jz4740_musb_platform_data = {
+ .mode = MUSB_PERIPHERAL,
+ .config = &jz4740_musb_config,
+ };
+
+
+First the glue layer configures some aspects of the controller driver
+operation related to the controller hardware specifics. This is done
+through the jz4740\_musb\_config musb\_hdrc\_config structure.
+
+Defining the OTG capability of the controller hardware, the multipoint
+member (line 3) is set to 0 (equivalent to false) since the JZ4740 UDC
+is not OTG compatible. Then num\_eps (line 5) defines the number of USB
+endpoints of the controller hardware, including endpoint 0: here we have
+3 endpoints + endpoint 0. Next is ram\_bits (line 7) which is the width
+of the RAM address bus for the MUSB controller hardware. This
+information is needed when the controller driver cannot automatically
+configure endpoints by reading the relevant controller hardware
+registers. This issue will be discussed when we get to device quirks in
+`Chapter 5 <#device-quirks>`__. Last two fields (line 8 and 9) are also
+about device quirks: fifo\_cfg points to the USB endpoints configuration
+table and fifo\_cfg\_size keeps track of the size of the number of
+entries in that configuration table. More on that later in `Chapter
+5 <#device-quirks>`__.
+
+Then this configuration is embedded inside jz4740\_musb\_platform\_data
+musb\_hdrc\_platform\_data structure (line 11): config is a pointer to
+the configuration structure itself, and mode tells the controller driver
+if the controller hardware may be used as MUSB\_HOST only,
+MUSB\_PERIPHERAL only or MUSB\_OTG which is a dual mode.
+
+Remember that jz4740\_musb\_platform\_data is then used to convey
+platform data information as we have seen in the probe function in
+`Chapter 2 <#linux-musb-basics>`__
+
+Device Quirks
+=============
+
+Completing the platform data specific to your device, you may also need
+to write some code in the glue layer to work around some device specific
+limitations. These quirks may be due to some hardware bugs, or simply be
+the result of an incomplete implementation of the USB On-the-Go
+specification.
+
+The JZ4740 UDC exhibits such quirks, some of which we will discuss here
+for the sake of insight even though these might not be found in the
+controller hardware you are working on.
+
+Let's get back to the init function first:
+
+::
+
+ static int jz4740_musb_init(struct musb *musb)
+ {
+ musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2);
+ if (!musb->xceiv) {
+ pr_err("HS UDC: no transceiver configured\n");
+ return -ENODEV;
+ }
+
+ /* Silicon does not implement ConfigData register.
+ * Set dyn_fifo to avoid reading EP config from hardware.
+ */
+ musb->dyn_fifo = true;
+
+ musb->isr = jz4740_musb_interrupt;
+
+ return 0;
+ }
+
+
+Instruction on line 12 helps the MUSB controller driver to work around
+the fact that the controller hardware is missing registers that are used
+for USB endpoints configuration.
+
+Without these registers, the controller driver is unable to read the
+endpoints configuration from the hardware, so we use line 12 instruction
+to bypass reading the configuration from silicon, and rely on a
+hard-coded table that describes the endpoints configuration instead:
+
+::
+
+ static struct musb_fifo_cfg jz4740_musb_fifo_cfg[] = {
+ { .hw_ep_num = 1, .style = FIFO_TX, .maxpacket = 512, },
+ { .hw_ep_num = 1, .style = FIFO_RX, .maxpacket = 512, },
+ { .hw_ep_num = 2, .style = FIFO_TX, .maxpacket = 64, },
+ };
+
+
+Looking at the configuration table above, we see that each endpoints is
+described by three fields: hw\_ep\_num is the endpoint number, style is
+its direction (either FIFO\_TX for the controller driver to send packets
+in the controller hardware, or FIFO\_RX to receive packets from
+hardware), and maxpacket defines the maximum size of each data packet
+that can be transmitted over that endpoint. Reading from the table, the
+controller driver knows that endpoint 1 can be used to send and receive
+USB data packets of 512 bytes at once (this is in fact a bulk in/out
+endpoint), and endpoint 2 can be used to send data packets of 64 bytes
+at once (this is in fact an interrupt endpoint).
+
+Note that there is no information about endpoint 0 here: that one is
+implemented by default in every silicon design, with a predefined
+configuration according to the USB specification. For more examples of
+endpoint configuration tables, see musb\_core.c.
+
+Let's now get back to the interrupt handler function:
+
+::
+
+ static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci)
+ {
+ unsigned long flags;
+ irqreturn_t retval = IRQ_NONE;
+ struct musb *musb = __hci;
+
+ spin_lock_irqsave(&musb->lock, flags);
+
+ musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB);
+ musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX);
+ musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX);
+
+ /*
+ * The controller is gadget only, the state of the host mode IRQ bits is
+ * undefined. Mask them to make sure that the musb driver core will
+ * never see them set
+ */
+ musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME |
+ MUSB_INTR_RESET | MUSB_INTR_SOF;
+
+ if (musb->int_usb || musb->int_tx || musb->int_rx)
+ retval = musb_interrupt(musb);
+
+ spin_unlock_irqrestore(&musb->lock, flags);
+
+ return retval;
+ }
+
+
+Instruction on line 18 above is a way for the controller driver to work
+around the fact that some interrupt bits used for USB host mode
+operation are missing in the MUSB\_INTRUSB register, thus left in an
+undefined hardware state, since this MUSB controller hardware is used in
+peripheral mode only. As a consequence, the glue layer masks these
+missing bits out to avoid parasite interrupts by doing a logical AND
+operation between the value read from MUSB\_INTRUSB and the bits that
+are actually implemented in the register.
+
+These are only a couple of the quirks found in the JZ4740 USB device
+controller. Some others were directly addressed in the MUSB core since
+the fixes were generic enough to provide a better handling of the issues
+for others controller hardware eventually.
+
+Conclusion
+==========
+
+Writing a Linux MUSB glue layer should be a more accessible task, as
+this documentation tries to show the ins and outs of this exercise.
+
+The JZ4740 USB device controller being fairly simple, I hope its glue
+layer serves as a good example for the curious mind. Used with the
+current MUSB glue layers, this documentation should provide enough
+guidance to get started; should anything gets out of hand, the linux-usb
+mailing list archive is another helpful resource to browse through.
+
+Acknowledgements
+================
+
+Many thanks to Lars-Peter Clausen and Maarten ter Huurne for answering
+my questions while I was writing the JZ4740 glue layer and for helping
+me out getting the code in good shape.
+
+I would also like to thank the Qi-Hardware community at large for its
+cheerful guidance and support.
+
+Resources
+=========
+
+USB Home Page: http://www.usb.org
+
+linux-usb Mailing List Archives: http://marc.info/?l=linux-usb
+
+USB On-the-Go Basics:
+http://www.maximintegrated.com/app-notes/index.mvp/id/1822
+
+Writing USB Device Drivers:
+https://www.kernel.org/doc/htmldocs/writing_usb_driver/index.html
+
+Texas Instruments USB Configuration Wiki Page:
+http://processors.wiki.ti.com/index.php/Usbgeneralpage
+
+Analog Devices Blackfin MUSB Configuration:
+http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:musb
diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst b/Documentation/driver-api/usb/writing_usb_driver.rst
new file mode 100644
index 000000000000..48f2fdb4745b
--- /dev/null
+++ b/Documentation/driver-api/usb/writing_usb_driver.rst
@@ -0,0 +1,338 @@
+Introduction
+============
+
+The Linux USB subsystem has grown from supporting only two different
+types of devices in the 2.2.7 kernel (mice and keyboards), to over 20
+different types of devices in the 2.4 kernel. Linux currently supports
+almost all USB class devices (standard types of devices like keyboards,
+mice, modems, printers and speakers) and an ever-growing number of
+vendor-specific devices (such as USB to serial converters, digital
+cameras, Ethernet devices and MP3 players). For a full list of the
+different USB devices currently supported, see Resources.
+
+The remaining kinds of USB devices that do not have support on Linux are
+almost all vendor-specific devices. Each vendor decides to implement a
+custom protocol to talk to their device, so a custom driver usually
+needs to be created. Some vendors are open with their USB protocols and
+help with the creation of Linux drivers, while others do not publish
+them, and developers are forced to reverse-engineer. See Resources for
+some links to handy reverse-engineering tools.
+
+Because each different protocol causes a new driver to be created, I
+have written a generic USB driver skeleton, modelled after the
+pci-skeleton.c file in the kernel source tree upon which many PCI
+network drivers have been based. This USB skeleton can be found at
+drivers/usb/usb-skeleton.c in the kernel source tree. In this article I
+will walk through the basics of the skeleton driver, explaining the
+different pieces and what needs to be done to customize it to your
+specific device.
+
+Linux USB Basics
+================
+
+If you are going to write a Linux USB driver, please become familiar
+with the USB protocol specification. It can be found, along with many
+other useful documents, at the USB home page (see Resources). An
+excellent introduction to the Linux USB subsystem can be found at the
+USB Working Devices List (see Resources). It explains how the Linux USB
+subsystem is structured and introduces the reader to the concept of USB
+urbs (USB Request Blocks), which are essential to USB drivers.
+
+The first thing a Linux USB driver needs to do is register itself with
+the Linux USB subsystem, giving it some information about which devices
+the driver supports and which functions to call when a device supported
+by the driver is inserted or removed from the system. All of this
+information is passed to the USB subsystem in the usb\_driver structure.
+The skeleton driver declares a usb\_driver as:
+
+::
+
+ static struct usb_driver skel_driver = {
+ .name = "skeleton",
+ .probe = skel_probe,
+ .disconnect = skel_disconnect,
+ .fops = &skel_fops,
+ .minor = USB_SKEL_MINOR_BASE,
+ .id_table = skel_table,
+ };
+
+
+The variable name is a string that describes the driver. It is used in
+informational messages printed to the system log. The probe and
+disconnect function pointers are called when a device that matches the
+information provided in the id\_table variable is either seen or
+removed.
+
+The fops and minor variables are optional. Most USB drivers hook into
+another kernel subsystem, such as the SCSI, network or TTY subsystem.
+These types of drivers register themselves with the other kernel
+subsystem, and any user-space interactions are provided through that
+interface. But for drivers that do not have a matching kernel subsystem,
+such as MP3 players or scanners, a method of interacting with user space
+is needed. The USB subsystem provides a way to register a minor device
+number and a set of file\_operations function pointers that enable this
+user-space interaction. The skeleton driver needs this kind of
+interface, so it provides a minor starting number and a pointer to its
+file\_operations functions.
+
+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)
+ {
+ int result;
+
+ /* 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);
+ return -1;
+ }
+
+ return 0;
+ }
+ module_init(usb_skel_init);
+
+
+When the driver is unloaded from the system, it needs to deregister
+itself with the USB subsystem. This is done with the usb\_deregister
+function:
+
+::
+
+ static void __exit usb_skel_exit(void)
+ {
+ /* deregister this driver with the USB subsystem */
+ usb_deregister(&skel_driver);
+ }
+ module_exit(usb_skel_exit);
+
+
+To enable the linux-hotplug system to load the driver automatically when
+the device is plugged in, you need to create a MODULE\_DEVICE\_TABLE.
+The following code tells the hotplug scripts that this module supports a
+single device with a specific vendor and product ID:
+
+::
+
+ /* table of devices that work with this driver */
+ static struct usb_device_id skel_table [] = {
+ { USB_DEVICE(USB_SKEL_VENDOR_ID, USB_SKEL_PRODUCT_ID) },
+ { } /* Terminating entry */
+ };
+ MODULE_DEVICE_TABLE (usb, skel_table);
+
+
+There are other macros that can be used in describing a usb\_device\_id
+for drivers that support a whole class of USB drivers. See usb.h for
+more information on this.
+
+Device operation
+================
+
+When a device is plugged into the USB bus that matches the device ID
+pattern that your driver registered with the USB core, the probe
+function is called. The usb\_device structure, interface number and the
+interface ID are passed to the function:
+
+::
+
+ static int skel_probe(struct usb_interface *interface,
+ const struct usb_device_id *id)
+
+
+The driver now needs to verify that this device is actually one that it
+can accept. If so, it returns 0. If not, or if any error occurs during
+initialization, an errorcode (such as ``-ENOMEM`` or ``-ENODEV``) is
+returned from the probe function.
+
+In the skeleton driver, we determine what end points are marked as
+bulk-in and bulk-out. We create buffers to hold the data that will be
+sent and received from the device, and a USB urb to write data to the
+device is initialized.
+
+Conversely, when the device is removed from the USB bus, the disconnect
+function is called with the device pointer. The driver needs to clean
+any private data that has been allocated at this time and to shut down
+any pending urbs that are in the USB system.
+
+Now that the device is plugged into the system and the driver is bound
+to the device, any of the functions in the file\_operations structure
+that were passed to the USB subsystem will be called from a user program
+trying to talk to the device. The first function called will be open, as
+the program tries to open the device for I/O. We increment our private
+usage count and save a pointer to our internal structure in the file
+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;
+
+ /* save our object in the file's private structure */
+ file->private_data = dev;
+
+
+After the open function is called, the read and write functions are
+called to receive and send data to the device. In the skel\_write
+function, we receive a pointer to some data that the user wants to send
+to the device and the size of the data. The function determines how much
+data it can send to the device based on the size of the write urb it has
+created (this size depends on the size of the bulk out end point that
+the device has). Then it copies the data from user space to kernel
+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;
+
+ /* copy the data from user space into our urb */
+ copy_from_user(skel->write_urb->transfer_buffer, buffer, bytes_written);
+
+ /* 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,
+ skel_write_bulk_callback,
+ skel);
+
+ /* send the data out the bulk port */
+ result = usb_submit_urb(skel->write_urb);
+ if (result) {
+ err("Failed submitting write urb, error %d", result);
+ }
+
+
+When the write urb is filled up with the proper information using the
+usb\_fill\_bulk\_urb function, we point the urb's completion callback to
+call our own skel\_write\_bulk\_callback function. This function is
+called when the urb is finished by the USB subsystem. The callback
+function is called in interrupt context, so caution must be taken not to
+do very much processing at that time. Our implementation of
+skel\_write\_bulk\_callback merely reports if the urb was completed
+successfully or not and then returns.
+
+The read function works a bit differently from the write function in
+that we do not use an urb to transfer data from the device to the
+driver. Instead we call the usb\_bulk\_msg function, which can be used
+to send or receive data from a device without having to create urbs and
+handle urb completion callback functions. We call the usb\_bulk\_msg
+function, giving it a buffer into which to place any data received from
+the device and a timeout value. If the timeout period expires without
+receiving any data from the device, the function will fail and return an
+error message. This can be shown with the following code:
+
+::
+
+ /* do an immediate bulk read to get data from the device */
+ retval = usb_bulk_msg (skel->dev,
+ usb_rcvbulkpipe (skel->dev,
+ skel->bulk_in_endpointAddr),
+ skel->bulk_in_buffer,
+ skel->bulk_in_size,
+ &count, HZ*10);
+ /* if the read was successful, copy the data to user space */
+ if (!retval) {
+ if (copy_to_user (buffer, skel->bulk_in_buffer, count))
+ retval = -EFAULT;
+ else
+ retval = count;
+ }
+
+
+The usb\_bulk\_msg function can be very useful for doing single reads or
+writes to a device; however, if you need to read or write constantly to
+a device, it is recommended to set up your own urbs and submit them to
+the USB subsystem.
+
+When the user program releases the file handle that it has been using to
+talk to the device, the release function in the driver is called. In
+this function we decrement our private usage count and wait for possible
+pending writes:
+
+::
+
+ /* decrement our usage count for the device */
+ --skel->open_count;
+
+
+One of the more difficult problems that USB drivers must be able to
+handle smoothly is the fact that the USB device may be removed from the
+system at any point in time, even if a program is currently talking to
+it. It needs to be able to shut down any current reads and writes and
+notify the user-space programs that the device is no longer there. The
+following code (function ``skel_delete``) is an example of how to do
+this:
+
+::
+
+ static inline void skel_delete (struct usb_skel *dev)
+ {
+ kfree (dev->bulk_in_buffer);
+ if (dev->bulk_out_buffer != NULL)
+ usb_free_coherent (dev->udev, dev->bulk_out_size,
+ dev->bulk_out_buffer,
+ dev->write_urb->transfer_dma);
+ usb_free_urb (dev->write_urb);
+ kfree (dev);
+ }
+
+
+If a program currently has an open handle to the device, we reset the
+flag ``device_present``. For every read, write, release and other
+functions that expect a device to be present, the driver first checks
+this flag to see if the device is still present. If not, it releases
+that the device has disappeared, and a -ENODEV error is returned to the
+user-space program. When the release function is eventually called, it
+determines if there is no device and if not, it does the cleanup that
+the skel\_disconnect function normally does if there are no open files
+on the device (see Listing 5).
+
+Isochronous Data
+================
+
+This usb-skeleton driver does not have any examples of interrupt or
+isochronous data being sent to or from the device. Interrupt data is
+sent almost exactly as bulk data is, with a few minor exceptions.
+Isochronous data works differently with continuous streams of data being
+sent to or from the device. The audio and video camera drivers are very
+good examples of drivers that handle isochronous data and will be useful
+if you also need to do this.
+
+Conclusion
+==========
+
+Writing Linux USB device drivers is not a difficult task as the
+usb-skeleton driver shows. This driver, combined with the other current
+USB drivers, should provide enough examples to help a beginning author
+create a working driver in a minimal amount of time. The linux-usb-devel
+mailing list archives also contain a lot of helpful information.
+
+Resources
+=========
+
+The Linux USB Project:
+`http://www.linux-usb.org/ <http://www.linux-usb.org>`__
+
+Linux Hotplug Project:
+`http://linux-hotplug.sourceforge.net/ <http://linux-hotplug.sourceforge.net>`__
+
+Linux USB Working Devices List:
+`http://www.qbik.ch/usb/devices/ <http://www.qbik.ch/usb/devices>`__
+
+linux-usb-devel Mailing List Archives:
+http://marc.theaimsgroup.com/?l=linux-usb-devel
+
+Programming Guide for Linux USB Device Drivers:
+http://usb.cs.tum.edu/usbdoc
+
+USB Home Page: http://www.usb.org
--
2.9.3
^ permalink raw reply related [flat|nested] 52+ messages in thread* Re: [PATCH 02/22] docs-rst: convert usb docbooks to ReST
2017-03-29 18:54 ` [PATCH 02/22] docs-rst: convert usb docbooks to ReST Mauro Carvalho Chehab
@ 2017-03-30 7:48 ` Markus Heiser
2017-03-30 8:21 ` Jani Nikula
0 siblings, 1 reply; 52+ messages in thread
From: Markus Heiser @ 2017-03-30 7:48 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman, Mauro Carvalho Chehab, John Youn, linux-usb,
linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab, Jani Nikula, Takashi Iwai, Daniel Vetter,
Oliver Neukum, Martyn Welch, Alexander Dahl, Jonathan Cameron
Hi Mauro,
Am 29.03.2017 um 20:54 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> As we're moving out of DocBook, let's convert the remaining
> USB docbooks to ReST.
>
> The transformation itself on this patch is a no-brainer
> conversion using pandoc.
right, its a no-brainer ;-) I'am not very happy with this
conversions, some examples see below.
I recommend to use a more elaborate conversion as starting point,
e.g. from my sphkerneldoc project:
* https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/gadget
* https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/writing_musb_glue_layer
* https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/writing_usb_driver
Since these DocBooks hasn't been changed in the last month, the linked reST
should be up to date.
> +Kernel Mode Gadget API
> +======================
> +
> +Gadget drivers declare themselves through a *struct
> +usb\_gadget\_driver*, which is responsible for most parts of enumeration
> +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
quoting of all underlines is not needed.
> +!Iinclude/linux/usb/composite.h !Edrivers/usb/gadget/composite.c
> +Composite Device Functions
> +--------------------------
> +
> +At this writing, a few of the current gadget drivers have been converted
> +to this framework. Near-term plans include converting all of them,
> +except for "gadgetfs".
> +
> +!Edrivers/usb/gadget/function/f\_acm.c
> +!Edrivers/usb/gadget/function/f\_ecm.c
> +!Edrivers/usb/gadget/function/f\_subset.c
> +!Edrivers/usb/gadget/function/f\_obex.c
> +!Edrivers/usb/gadget/function/f\_serial.c
> +Peripheral Controller Drivers
> +=============================
I guess we miss some documentation here.
-- Markus --
^ permalink raw reply [flat|nested] 52+ messages in thread
* Re: [PATCH 02/22] docs-rst: convert usb docbooks to ReST
2017-03-30 7:48 ` Markus Heiser
@ 2017-03-30 8:21 ` Jani Nikula
2017-03-30 9:20 ` Markus Heiser
0 siblings, 1 reply; 52+ messages in thread
From: Jani Nikula @ 2017-03-30 8:21 UTC (permalink / raw)
To: Markus Heiser, Mauro Carvalho Chehab
Cc: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman, Mauro Carvalho Chehab, John Youn, linux-usb,
linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab, Takashi Iwai, Daniel Vetter, Oliver Neukum,
Martyn Welch, Alexander Dahl, Jonathan Cameron
On Thu, 30 Mar 2017, Markus Heiser <markus.heiser@darmarit.de> wrote:
> Hi Mauro,
>
> Am 29.03.2017 um 20:54 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
>
>> As we're moving out of DocBook, let's convert the remaining
>> USB docbooks to ReST.
>>
>> The transformation itself on this patch is a no-brainer
>> conversion using pandoc.
>
> right, its a no-brainer ;-) I'am not very happy with this
> conversions, some examples see below.
>
> I recommend to use a more elaborate conversion as starting point,
> e.g. from my sphkerneldoc project:
>
> * https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/gadget
> * https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/writing_musb_glue_layer
> * https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/writing_usb_driver
>
> Since these DocBooks hasn't been changed in the last month, the linked reST
> should be up to date.
Markus, I know you've done a lot of work on your conversions, and you
like to advocate them, but AFAICT you have never posted the conversions
as patches to the list. Your project isn't a clone of the kernel
tree. It's a pile of .rst files that nobody knows how to produce from
current upstream DocBook .tmpl files. I'm sorry, but this just doesn't
work that way.
At this point I'd just go with what Mauro has. It's here now, as
patches. We've seen from the GPU documentation that polishing the
one-time initial conversion is, after a point, wasted effort. Having the
documentation in rst attracts more attention and contributions, and any
remaining issues will get ironed out in rst.
This is also one reason I'm in favor of just bulk converting the rest of
the .tmpl files using Documentation/sphinx/tmplcvt, get rid of DocBook
and be done with it, and have the crowds focus on rst.
BR,
Jani.
--
Jani Nikula, Intel Open Source Technology Center
^ permalink raw reply [flat|nested] 52+ messages in thread
* Re: [PATCH 02/22] docs-rst: convert usb docbooks to ReST
2017-03-30 8:21 ` Jani Nikula
@ 2017-03-30 9:20 ` Markus Heiser
2017-03-30 10:12 ` Mauro Carvalho Chehab
2017-03-31 14:46 ` Jonathan Corbet
0 siblings, 2 replies; 52+ messages in thread
From: Markus Heiser @ 2017-03-30 9:20 UTC (permalink / raw)
To: Jani Nikula
Cc: Mauro Carvalho Chehab, Linux Media Mailing List,
Linux Doc Mailing List, Greg Kroah-Hartman, Mauro Carvalho Chehab,
John Youn, linux-usb, linux-rpi-kernel, Laurent Pinchart,
Jonathan Corbet, Mauro Carvalho Chehab, Takashi Iwai,
Daniel Vetter, Oliver Neukum, Martyn Welch, Alexander Dahl,
Jonathan Cameron
Am 30.03.2017 um 10:21 schrieb Jani Nikula <jani.nikula@intel.com>:
> On Thu, 30 Mar 2017, Markus Heiser <markus.heiser@darmarit.de> wrote:
>> Hi Mauro,
>>
>> Am 29.03.2017 um 20:54 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
>>
>>> As we're moving out of DocBook, let's convert the remaining
>>> USB docbooks to ReST.
>>>
>>> The transformation itself on this patch is a no-brainer
>>> conversion using pandoc.
>>
>> right, its a no-brainer ;-) I'am not very happy with this
>> conversions, some examples see below.
>>
>> I recommend to use a more elaborate conversion as starting point,
>> e.g. from my sphkerneldoc project:
>>
>> * https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/gadget
>> * https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/writing_musb_glue_layer
>> * https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/writing_usb_driver
>>
>> Since these DocBooks hasn't been changed in the last month, the linked reST
>> should be up to date.
>
> Markus, I know you've done a lot of work on your conversions, and you
> like to advocate them, but AFAICT you have never posted the conversions
> as patches to the list. Your project isn't a clone of the kernel
> tree. It's a pile of .rst files that nobody knows how to produce from
> current upstream DocBook .tmpl files. I'm sorry, but this just doesn't
> work that way.
The conversion is done with the dbxml2rst tool:
https://github.com/return42/dbxml2rst
But you are right, the links I send are decoupled from kernel. It is
a 5 month old snapshot of a DocBook to reST conversion (now updated,
with no affect to the linked files, since they have not been patched
in the meantime) ...
> At this point I'd just go with what Mauro has. It's here now, as
> patches. We've seen from the GPU documentation that polishing the
> one-time initial conversion is, after a point, wasted effort. Having the
> documentation in rst attracts more attention and contributions, and any
> remaining issues will get ironed out in rst.
I totally agree with you (I have never said something different)
> This is also one reason I'm in favor of just bulk converting the rest of
> the .tmpl files using Documentation/sphinx/tmplcvt, get rid of DocBook
> and be done with it, and have the crowds focus on rst.
I also agree with that. The tmplcvt script is good enough for this task,
the dbxml2rst tool is more elaborate.
If Jonathan also likes to have a bulk conversion of the rest DocBooks,
we can use tmplcvt or even dbxml2rst for this task. Everything under
https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated
is just a "make dbxm2rst", I can update every time and if a bulk conversion
is the way ... I can send such patches or you send a tmplcvt conversion.
@Jon: what do you think about a bulk conversion?
-- Markus --
^ permalink raw reply [flat|nested] 52+ messages in thread
* Re: [PATCH 02/22] docs-rst: convert usb docbooks to ReST
2017-03-30 9:20 ` Markus Heiser
@ 2017-03-30 10:12 ` Mauro Carvalho Chehab
2017-03-30 11:17 ` Markus Heiser
2017-03-31 14:46 ` Jonathan Corbet
1 sibling, 1 reply; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-30 10:12 UTC (permalink / raw)
To: Markus Heiser
Cc: Jani Nikula, Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman, Mauro Carvalho Chehab, John Youn, linux-usb,
linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab, Takashi Iwai, Daniel Vetter, Oliver Neukum,
Martyn Welch, Alexander Dahl, Jonathan Cameron
Em Thu, 30 Mar 2017 11:20:14 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:
> Am 30.03.2017 um 10:21 schrieb Jani Nikula <jani.nikula@intel.com>:
>
> > On Thu, 30 Mar 2017, Markus Heiser <markus.heiser@darmarit.de> wrote:
> >> Hi Mauro,
> >>
> >> Am 29.03.2017 um 20:54 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> >>
> >>> As we're moving out of DocBook, let's convert the remaining
> >>> USB docbooks to ReST.
> >>>
> >>> The transformation itself on this patch is a no-brainer
> >>> conversion using pandoc.
> >>
> >> right, its a no-brainer ;-) I'am not very happy with this
> >> conversions, some examples see below.
> >>
> >> I recommend to use a more elaborate conversion as starting point,
> >> e.g. from my sphkerneldoc project:
> >>
> >> * https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/gadget
> >> * https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/writing_musb_glue_layer
> >> * https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/writing_usb_driver
> >>
> >> Since these DocBooks hasn't been changed in the last month, the linked reST
> >> should be up to date.
> >
> > Markus, I know you've done a lot of work on your conversions, and you
> > like to advocate them, but AFAICT you have never posted the conversions
> > as patches to the list. Your project isn't a clone of the kernel
> > tree. It's a pile of .rst files that nobody knows how to produce from
> > current upstream DocBook .tmpl files. I'm sorry, but this just doesn't
> > work that way.
>
> The conversion is done with the dbxml2rst tool:
>
> https://github.com/return42/dbxml2rst
>
> But you are right, the links I send are decoupled from kernel. It is
> a 5 month old snapshot of a DocBook to reST conversion (now updated,
> with no affect to the linked files, since they have not been patched
> in the meantime) ...
>
> > At this point I'd just go with what Mauro has. It's here now, as
> > patches. We've seen from the GPU documentation that polishing the
> > one-time initial conversion is, after a point, wasted effort. Having the
> > documentation in rst attracts more attention and contributions, and any
> > remaining issues will get ironed out in rst.
>
> I totally agree with you (I have never said something different)
>
> > This is also one reason I'm in favor of just bulk converting the rest of
> > the .tmpl files using Documentation/sphinx/tmplcvt, get rid of DocBook
> > and be done with it, and have the crowds focus on rst.
>
> I also agree with that. The tmplcvt script is good enough for this task,
> the dbxml2rst tool is more elaborate.
I like the idea of a bulk conversion. My personal preference here is to
use the tmplcvt for such task, at least for simple books like the ones
I converted from USB.
The advantage is that it places everything on a single rst file, with,
IMHO, works best for books that aren't too complex.
Of course, it doesn't hurt to compare the end result with dbxml2rst
and see if something could be improved.
>
> If Jonathan also likes to have a bulk conversion of the rest DocBooks,
> we can use tmplcvt or even dbxml2rst for this task. Everything under
>
> https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated
>
> is just a "make dbxm2rst", I can update every time and if a bulk conversion
> is the way ... I can send such patches or you send a tmplcvt conversion.
>
> @Jon: what do you think about a bulk conversion?
>
> -- Markus --
>
Thanks,
Mauro
^ permalink raw reply [flat|nested] 52+ messages in thread
* Re: [PATCH 02/22] docs-rst: convert usb docbooks to ReST
2017-03-30 10:12 ` Mauro Carvalho Chehab
@ 2017-03-30 11:17 ` Markus Heiser
2017-03-30 11:35 ` Markus Heiser
2017-03-30 12:10 ` Mauro Carvalho Chehab
0 siblings, 2 replies; 52+ messages in thread
From: Markus Heiser @ 2017-03-30 11:17 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Jani Nikula, Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman, Mauro Carvalho Chehab, John Youn, linux-usb,
linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab, Takashi Iwai, Daniel Vetter, Oliver Neukum,
Martyn Welch, Alexander Dahl, Jonathan Cameron
Am 30.03.2017 um 12:12 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
>>> At this point I'd just go with what Mauro has. It's here now, as
>>> patches. We've seen from the GPU documentation that polishing the
>>> one-time initial conversion is, after a point, wasted effort. Having the
>>> documentation in rst attracts more attention and contributions, and any
>>> remaining issues will get ironed out in rst.
>>
>> I totally agree with you (I have never said something different)
>>
>>> This is also one reason I'm in favor of just bulk converting the rest of
>>> the .tmpl files using Documentation/sphinx/tmplcvt, get rid of DocBook
>>> and be done with it, and have the crowds focus on rst.
>>
>> I also agree with that. The tmplcvt script is good enough for this task,
>> the dbxml2rst tool is more elaborate.
>
> I like the idea of a bulk conversion. My personal preference here is to
> use the tmplcvt for such task, at least for simple books like the ones
> I converted from USB.
>
> The advantage is that it places everything on a single rst file, with,
> IMHO, works best for books that aren't too complex.
> Of course, it doesn't hurt to compare the end result with dbxml2rst
> and see if something could be improved.
If it helps ... dbxml2rst also supports single file conversion ... I updated:
https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated
There you find a folder for each DocBook conversion with only one rst file (index.rst)
in .. If you like, use it for comparison.
-- Markus --
^ permalink raw reply [flat|nested] 52+ messages in thread
* Re: [PATCH 02/22] docs-rst: convert usb docbooks to ReST
2017-03-30 11:17 ` Markus Heiser
@ 2017-03-30 11:35 ` Markus Heiser
2017-03-30 12:10 ` Mauro Carvalho Chehab
1 sibling, 0 replies; 52+ messages in thread
From: Markus Heiser @ 2017-03-30 11:35 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Jani Nikula, Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman, Mauro Carvalho Chehab, John Youn, linux-usb,
linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab, Takashi Iwai, Daniel Vetter, Oliver Neukum,
Martyn Welch, Alexander Dahl, Jonathan Cameron
Am 30.03.2017 um 13:17 schrieb Markus Heiser <markus.heiser@darmarIT.de>:
>
> If it helps ... dbxml2rst also supports single file conversion ... I updated:
>
> https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated
>
> There you find a folder for each DocBook conversion with only one rst file (index.rst)
> in .. If you like, use it for comparison.
Forget to mentioning one of the main benefits:
The conversion with dbxml2rst produce tables with directive ".. flat-table::"
instead of building ASCII tables (like pandoc does).
-- Markus --
^ permalink raw reply [flat|nested] 52+ messages in thread
* Re: [PATCH 02/22] docs-rst: convert usb docbooks to ReST
2017-03-30 11:17 ` Markus Heiser
2017-03-30 11:35 ` Markus Heiser
@ 2017-03-30 12:10 ` Mauro Carvalho Chehab
1 sibling, 0 replies; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-30 12:10 UTC (permalink / raw)
To: Markus Heiser
Cc: Jani Nikula, Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman, Mauro Carvalho Chehab, John Youn, linux-usb,
linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab, Takashi Iwai, Daniel Vetter, Oliver Neukum,
Martyn Welch, Alexander Dahl, Jonathan Cameron
Em Thu, 30 Mar 2017 13:17:16 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:
> Am 30.03.2017 um 12:12 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> >>> At this point I'd just go with what Mauro has. It's here now, as
> >>> patches. We've seen from the GPU documentation that polishing the
> >>> one-time initial conversion is, after a point, wasted effort. Having the
> >>> documentation in rst attracts more attention and contributions, and any
> >>> remaining issues will get ironed out in rst.
> >>
> >> I totally agree with you (I have never said something different)
> >>
> >>> This is also one reason I'm in favor of just bulk converting the rest of
> >>> the .tmpl files using Documentation/sphinx/tmplcvt, get rid of DocBook
> >>> and be done with it, and have the crowds focus on rst.
> >>
> >> I also agree with that. The tmplcvt script is good enough for this task,
> >> the dbxml2rst tool is more elaborate.
> >
> > I like the idea of a bulk conversion. My personal preference here is to
> > use the tmplcvt for such task, at least for simple books like the ones
> > I converted from USB.
> >
> > The advantage is that it places everything on a single rst file, with,
> > IMHO, works best for books that aren't too complex.
> > Of course, it doesn't hurt to compare the end result with dbxml2rst
> > and see if something could be improved.
>
> If it helps ... dbxml2rst also supports single file conversion ... I updated:
>
> https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated
Ok, I double-checked the results from dbxml2rst with pandoc (via
the script). Those are the differences after running the following commands:
$ wget https://raw.githubusercontent.com/return42/sphkerneldoc/master/Documentation/books_migrated/writing_usb_driver/index.rst
$ Documentation/sphinx/tmplcvt Documentation/DocBook/writing_usb_driver.tmpl writing_usb_driver.rst
$ diff -uprBw writing_usb_driver.rst index.rst
1) Author data:
-:Author: Greg Kroah-Hartman
+:author: Kroah-Hartman Greg
+:address: greg@kroah.com
dbxml2rst inverted the author's name. It also added author's e-mail.
IMHO, it is better to not have email address there, as it could be
outdated, but this is just my personal preference.
2) dbxml2rst added a copyright information:
+**Copyright** 2001-2002 : Greg Kroah-Hartman
This is a good thing.
3) dbxml2rst added a GPL information.
IMHO, we should add just one GPL information, per hole book
(and not per converted file).
4) dbxml2rst created some references that won't be unique:
+.. _intro:
That's a bad thing, as I bet most converted documents will have "intro"
sections.
5) dbxml2rst use ".. code-block:: c" instead of "::"
I prefer using "::"
6) dbxml2rst appends a commentary at the end:
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/dbxml2rst). The origin XML comes
+.. from the linux kernel:
+..
+.. http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git
+.. ------------------------------------------------------------------------------
7) dbxml2rst did a worse job with URB conversions:
-USB Home Page: http://www.usb.org
+USB Home Page: `http://www.usb.org <http://www.usb.org>`__
So, in summary, at least for this document, the only thing good with
dbxml2rst was that it filled the copyright info.
Maybe for more complex documents, it would do a better job.
Yet, in order to standardize it everywhere, I guess the best would be to
produce copyright data like:
.. include:: <isonum.txt>
:Copyright: |copy| 2001-2002 : Greg Kroah-Hartman
Regards,
Mauro
^ permalink raw reply [flat|nested] 52+ messages in thread
* Re: [PATCH 02/22] docs-rst: convert usb docbooks to ReST
2017-03-30 9:20 ` Markus Heiser
2017-03-30 10:12 ` Mauro Carvalho Chehab
@ 2017-03-31 14:46 ` Jonathan Corbet
1 sibling, 0 replies; 52+ messages in thread
From: Jonathan Corbet @ 2017-03-31 14:46 UTC (permalink / raw)
To: Markus Heiser
Cc: Jani Nikula, Mauro Carvalho Chehab, Linux Media Mailing List,
Linux Doc Mailing List, Greg Kroah-Hartman, Mauro Carvalho Chehab,
John Youn, linux-usb, linux-rpi-kernel, Laurent Pinchart,
Mauro Carvalho Chehab, Takashi Iwai, Daniel Vetter, Oliver Neukum,
Martyn Welch, Alexander Dahl, Jonathan Cameron
On Thu, 30 Mar 2017 11:20:14 +0200
Markus Heiser <markus.heiser@darmarit.de> wrote:
> @Jon: what do you think about a bulk conversion?
I'm a bit leery of it, to tell the truth. We're trying to create a
better set of kernel docs, and I'm far from convinced that dumping a
bunch of unloved stuff there in a mechanical way will get us there.
Each of those docs needs to be looked at, and, first of all, we need to
decide whether it's worth keeping or not. Nobody wants to delete docs,
but old and unmaintained stuff doesn't help our users, IMO. For the
stuff we want to keep, we need to look at how it fits into the new
scheme, probably split it up, etc.
It's a lot slower, but we've been getting rid of 3-6 template files in
each of the last few cycles, so we are getting there. I don't think we
need to just give up on the rest.
Thanks,
jon
^ permalink raw reply [flat|nested] 52+ messages in thread
* [PATCH 03/22] usb.rst: Enrich its ReST representation
2017-03-29 18:54 [PATCH 01/22] driver-api/basics.rst: add device table header Mauro Carvalho Chehab
2017-03-29 18:54 ` [PATCH 02/22] docs-rst: convert usb docbooks to ReST Mauro Carvalho Chehab
@ 2017-03-29 18:54 ` Mauro Carvalho Chehab
2017-03-29 18:54 ` [PATCH 04/22] gadget.rst: Enrich its ReST representation and add kernel-doc tag Mauro Carvalho Chehab
` (19 subsequent siblings)
21 siblings, 0 replies; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-29 18:54 UTC (permalink / raw)
To: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, John Youn,
linux-usb, linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab, Oliver Neukum
- use the proper warning and note markups;
- add references for parts of the document that will be
cross-referenced on other USB docs;
- some minor adjustments to make it better to read in
text mode and in html.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/driver-api/usb/usb.rst | 48 +++++++++++++-----------------------
1 file changed, 17 insertions(+), 31 deletions(-)
diff --git a/Documentation/driver-api/usb/usb.rst b/Documentation/driver-api/usb/usb.rst
index b856abb3200e..7e820768ee4f 100644
--- a/Documentation/driver-api/usb/usb.rst
+++ b/Documentation/driver-api/usb/usb.rst
@@ -102,6 +102,8 @@ disconnect testing (while the device is active) with each different host
controller driver, to make sure drivers don't have bugs of their own as
well as to make sure they aren't relying on some HCD-specific behavior.
+.. _usb_chapter9:
+
USB-Standard Types
==================
@@ -112,6 +114,8 @@ USB, and in APIs including this host side API, gadget APIs, and usbfs.
.. kernel-doc:: include/linux/usb/ch9.h
:internal:
+.. _usb_header:
+
Host-Side Data Types and Macros
===============================
@@ -209,7 +213,7 @@ library that wraps it. Such libraries include
`libusb <http://libusb.sourceforge.net>`__ for C/C++, and
`jUSB <http://jUSB.sourceforge.net>`__ for Java.
- **Note**
+.. note::
This particular documentation is incomplete, especially with respect
to the asynchronous mode. As of kernel 2.5.66 the code and this
@@ -319,9 +323,7 @@ files. For information about the current format of this file, see the
sources.
This file, in combination with the poll() system call, can also be used
-to detect when devices are added or removed:
-
-::
+to detect when devices are added or removed::
int fd;
struct pollfd pfd;
@@ -407,9 +409,7 @@ The ioctl() Requests
--------------------
To use these ioctls, you need to include the following headers in your
-userspace program:
-
-::
+userspace program::
#include <linux/usb.h>
#include <linux/usbdevice_fs.h>
@@ -458,9 +458,7 @@ USBDEVFS_CLAIMINTERFACE
USBDEVFS_CONNECTINFO
Says whether the device is lowspeed. The ioctl parameter points to a
- structure like this:
-
- ::
+ structure like this::
struct usbdevfs_connectinfo {
unsigned int devnum;
@@ -477,9 +475,7 @@ USBDEVFS_CONNECTINFO
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
- modified:
-
- ::
+ modified::
struct usbdevfs_getdriver {
unsigned int interface;
@@ -490,9 +486,7 @@ USBDEVFS_GETDRIVER
USBDEVFS_IOCTL
Passes a request from userspace through to a kernel driver that has
- an ioctl entry in the *struct usb_driver* it registered.
-
- ::
+ an ioctl entry in the *struct usb_driver* it registered::
struct usbdevfs_ioctl {
int ifno;
@@ -534,7 +528,7 @@ USBDEVFS_RELEASEINTERFACE
the number of the interface (bInterfaceNumber from descriptor); File
modification time is not updated by this request.
- **Warning**
+.. warning::
*No security check is made to ensure that the task which made
the claim is the one which is releasing it. This means that user
@@ -574,9 +568,7 @@ a time.
USBDEVFS_BULK
Issues a bulk read or write request to the device. The ioctl
- parameter is a pointer to this structure:
-
- ::
+ parameter is a pointer to this structure::
struct usbdevfs_bulktransfer {
unsigned int ep;
@@ -606,9 +598,7 @@ USBDEVFS_CLEAR_HALT
USBDEVFS_CONTROL
Issues a control request to the device. The ioctl parameter points
- to a structure like this:
-
- ::
+ to a structure like this::
struct usbdevfs_ctrltransfer {
__u8 bRequestType;
@@ -638,7 +628,7 @@ USBDEVFS_RESET
the reset, this rebinds all device interfaces. File modification
time is not updated by this request.
- **Warning**
+.. warning::
*Avoid using this call* until some usbcore bugs get fixed, since
it does not fully synchronize device, interface, and driver (not
@@ -646,9 +636,7 @@ USBDEVFS_RESET
USBDEVFS_SETINTERFACE
Sets the alternate setting for an interface. The ioctl parameter is
- a pointer to a structure like this:
-
- ::
+ a pointer to a structure like this::
struct usbdevfs_setinterface {
unsigned int interface;
@@ -669,7 +657,7 @@ USBDEVFS_SETCONFIGURATION
configuration (bConfigurationValue from descriptor). File
modification time is not updated by this request.
- **Warning**
+.. warning::
*Avoid using this call* until some usbcore bugs get fixed, since
it does not fully synchronize device, interface, and driver (not
@@ -702,9 +690,7 @@ When usbfs returns these urbs, the status value is updated, and the
buffer may have been modified. Except for isochronous transfers, the
actual_length is updated to say how many bytes were transferred; if the
USBDEVFS_URB_DISABLE_SPD flag is set ("short packets are not OK"), if
-fewer bytes were read than were requested then you get an error report.
-
-::
+fewer bytes were read than were requested then you get an error report::
struct usbdevfs_iso_packet_desc {
unsigned int length;
--
2.9.3
^ permalink raw reply related [flat|nested] 52+ messages in thread* [PATCH 04/22] gadget.rst: Enrich its ReST representation and add kernel-doc tag
2017-03-29 18:54 [PATCH 01/22] driver-api/basics.rst: add device table header Mauro Carvalho Chehab
2017-03-29 18:54 ` [PATCH 02/22] docs-rst: convert usb docbooks to ReST Mauro Carvalho Chehab
2017-03-29 18:54 ` [PATCH 03/22] usb.rst: Enrich its ReST representation Mauro Carvalho Chehab
@ 2017-03-29 18:54 ` Mauro Carvalho Chehab
2017-03-30 7:01 ` Jani Nikula
2017-03-29 18:54 ` [PATCH 05/22] writing_usb_driver.rst: Enrich its ReST representation Mauro Carvalho Chehab
` (18 subsequent siblings)
21 siblings, 1 reply; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-29 18:54 UTC (permalink / raw)
To: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, John Youn,
linux-usb, linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab
The pandoc conversion is not perfect. Do handwork in order to:
- add a title to this chapter;
- use the proper warning and note markups;
- use kernel-doc to include Kernel header and c files;
- remove legacy notes with regards to DocBook;
- some other minor adjustments to make it better to read in
text mode and in html.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/driver-api/usb/gadget.rst | 69 +++++++++++++++++++++------------
1 file changed, 45 insertions(+), 24 deletions(-)
diff --git a/Documentation/driver-api/usb/gadget.rst b/Documentation/driver-api/usb/gadget.rst
index 4fd9862f3f21..c4c76ebb51d3 100644
--- a/Documentation/driver-api/usb/gadget.rst
+++ b/Documentation/driver-api/usb/gadget.rst
@@ -1,3 +1,7 @@
+Linux-USB "Gadget" kernel mode API
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
Introduction
============
@@ -175,16 +179,12 @@ 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.
- **Note**
+.. Note::
- This documentation was prepared using the standard Linux kernel
- ``docproc`` tool, which turns text and in-code comments into SGML
- DocBook and then into usable formats such as HTML or PDF. Other than
- the "Chapter 9" data types, most of the significant data types and
- functions are described here.
+ Other than the "Chapter 9" data types, most of the significant data
+ types and functions are described here.
- However, docproc does not understand all the C constructs that are
- used, so some relevant information is likely omitted from what you
+ However, some relevant information is likely omitted from what you
are reading. One example of such information is endpoint
autoconfiguration. You'll have to read the header file, and use
example source code (such as that for "Gadget Zero"), to fully
@@ -192,10 +192,10 @@ and you will understand how this API works.
The part of the API implementing some basic driver capabilities is
specific to the version of the Linux kernel that's in use. The 2.6
- kernel includes a *driver model* framework that has no analogue on
- earlier kernels; so those parts of the gadget API are not fully
- portable. (They are implemented on 2.4 kernels, but in a different
- way.) The driver model state is another part of this API that is
+ and upper kernel versions include a *driver model* framework that has
+ no analogue on earlier kernels; so those parts of the gadget API are
+ not fully portable. (They are implemented on 2.4 kernels, but in a
+ different way.) The driver model state is another part of this API that is
ignored by the kerneldoc tools.
The core API does not expose every possible hardware feature, only the
@@ -301,18 +301,19 @@ USB 2.0 Chapter 9 Types and Constants
-------------------------------------
Gadget drivers rely on common USB structures and constants defined in
-the ``<linux/usb/ch9.h>`` header file, which is standard in Linux 2.6
-kernels. These are the same types and constants used by host side
+the :ref:`linux/usb/ch9.h <usb_chapter9>` header file, which is standard in
+Linux 2.6+ kernels. These are the same types and constants used by host side
drivers (and usbcore).
-!Iinclude/linux/usb/ch9.h
Core Objects and Methods
------------------------
These are declared in ``<linux/usb/gadget.h>``, and are used by gadget
drivers to interact with USB peripheral controller drivers.
-!Iinclude/linux/usb/gadget.h
+.. kernel-doc:: include/linux/usb/gadget.h
+ :internal:
+
Optional Utilities
------------------
@@ -320,7 +321,12 @@ The core API is sufficient for writing a USB Gadget Driver, but some
optional utilities are provided to simplify common tasks. These
utilities include endpoint autoconfiguration.
-!Edrivers/usb/gadget/usbstring.c !Edrivers/usb/gadget/config.c
+.. kernel-doc:: drivers/usb/gadget/usbstring.c
+ :export:
+
+.. kernel-doc:: drivers/usb/gadget/config.c
+ :export:
+
Composite Device Framework
--------------------------
@@ -337,7 +343,12 @@ usb\_function*, which packages a user visible role such as "network
link" or "mass storage device". Management functions may also exist,
such as "Device Firmware Upgrade".
-!Iinclude/linux/usb/composite.h !Edrivers/usb/gadget/composite.c
+.. kernel-doc:: include/linux/usb/composite.h
+ :internal:
+
+.. kernel-doc:: drivers/usb/gadget/composite.c
+ :export:
+
Composite Device Functions
--------------------------
@@ -345,11 +356,21 @@ At this writing, a few of the current gadget drivers have been converted
to this framework. Near-term plans include converting all of them,
except for "gadgetfs".
-!Edrivers/usb/gadget/function/f\_acm.c
-!Edrivers/usb/gadget/function/f\_ecm.c
-!Edrivers/usb/gadget/function/f\_subset.c
-!Edrivers/usb/gadget/function/f\_obex.c
-!Edrivers/usb/gadget/function/f\_serial.c
+.. kernel-doc:: drivers/usb/gadget/function/f_acm.c
+ :export:
+
+.. kernel-doc:: drivers/usb/gadget/function/f_ecm.c
+ :export:
+
+.. kernel-doc:: drivers/usb/gadget/function/f_subset.c
+ :export:
+
+.. kernel-doc:: drivers/usb/gadget/function/f_obex.c
+ :export:
+
+.. kernel-doc:: drivers/usb/gadget/function/f_serial.c
+ :export:
+
Peripheral Controller Drivers
=============================
@@ -475,7 +496,7 @@ can also benefit non-OTG products.
- Also on the host side, a driver must support the OTG "Targeted
Peripheral List". That's just a whitelist, used to reject peripherals
not supported with a given Linux OTG host. *This whitelist is
- product-specific; each product must modify ``otg_whitelist.h`` to
+ product-specific; each product must modify* ``otg_whitelist.h`` *to
match its interoperability specification.*
Non-OTG Linux hosts, like PCs and workstations, normally have some
--
2.9.3
^ permalink raw reply related [flat|nested] 52+ messages in thread* Re: [PATCH 04/22] gadget.rst: Enrich its ReST representation and add kernel-doc tag
2017-03-29 18:54 ` [PATCH 04/22] gadget.rst: Enrich its ReST representation and add kernel-doc tag Mauro Carvalho Chehab
@ 2017-03-30 7:01 ` Jani Nikula
2017-03-30 7:04 ` Jani Nikula
2017-03-30 8:45 ` Mauro Carvalho Chehab
0 siblings, 2 replies; 52+ messages in thread
From: Jani Nikula @ 2017-03-30 7:01 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Linux Media Mailing List,
Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, John Youn,
linux-usb, linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab
On Wed, 29 Mar 2017, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> The pandoc conversion is not perfect. Do handwork in order to:
>
> - add a title to this chapter;
> - use the proper warning and note markups;
> - use kernel-doc to include Kernel header and c files;
Please look at Documentation/sphinx/tmplcvt which takes care of all of
that.
BR,
Jani.
> - remove legacy notes with regards to DocBook;
> - some other minor adjustments to make it better to read in
> text mode and in html.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
> Documentation/driver-api/usb/gadget.rst | 69 +++++++++++++++++++++------------
> 1 file changed, 45 insertions(+), 24 deletions(-)
>
> diff --git a/Documentation/driver-api/usb/gadget.rst b/Documentation/driver-api/usb/gadget.rst
> index 4fd9862f3f21..c4c76ebb51d3 100644
> --- a/Documentation/driver-api/usb/gadget.rst
> +++ b/Documentation/driver-api/usb/gadget.rst
> @@ -1,3 +1,7 @@
> +Linux-USB "Gadget" kernel mode API
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +
> Introduction
> ============
>
> @@ -175,16 +179,12 @@ 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.
>
> - **Note**
> +.. Note::
>
> - This documentation was prepared using the standard Linux kernel
> - ``docproc`` tool, which turns text and in-code comments into SGML
> - DocBook and then into usable formats such as HTML or PDF. Other than
> - the "Chapter 9" data types, most of the significant data types and
> - functions are described here.
> + Other than the "Chapter 9" data types, most of the significant data
> + types and functions are described here.
>
> - However, docproc does not understand all the C constructs that are
> - used, so some relevant information is likely omitted from what you
> + However, some relevant information is likely omitted from what you
> are reading. One example of such information is endpoint
> autoconfiguration. You'll have to read the header file, and use
> example source code (such as that for "Gadget Zero"), to fully
> @@ -192,10 +192,10 @@ and you will understand how this API works.
>
> The part of the API implementing some basic driver capabilities is
> specific to the version of the Linux kernel that's in use. The 2.6
> - kernel includes a *driver model* framework that has no analogue on
> - earlier kernels; so those parts of the gadget API are not fully
> - portable. (They are implemented on 2.4 kernels, but in a different
> - way.) The driver model state is another part of this API that is
> + and upper kernel versions include a *driver model* framework that has
> + no analogue on earlier kernels; so those parts of the gadget API are
> + not fully portable. (They are implemented on 2.4 kernels, but in a
> + different way.) The driver model state is another part of this API that is
> ignored by the kerneldoc tools.
>
> The core API does not expose every possible hardware feature, only the
> @@ -301,18 +301,19 @@ USB 2.0 Chapter 9 Types and Constants
> -------------------------------------
>
> Gadget drivers rely on common USB structures and constants defined in
> -the ``<linux/usb/ch9.h>`` header file, which is standard in Linux 2.6
> -kernels. These are the same types and constants used by host side
> +the :ref:`linux/usb/ch9.h <usb_chapter9>` header file, which is standard in
> +Linux 2.6+ kernels. These are the same types and constants used by host side
> drivers (and usbcore).
>
> -!Iinclude/linux/usb/ch9.h
> Core Objects and Methods
> ------------------------
>
> These are declared in ``<linux/usb/gadget.h>``, and are used by gadget
> drivers to interact with USB peripheral controller drivers.
>
> -!Iinclude/linux/usb/gadget.h
> +.. kernel-doc:: include/linux/usb/gadget.h
> + :internal:
> +
> Optional Utilities
> ------------------
>
> @@ -320,7 +321,12 @@ The core API is sufficient for writing a USB Gadget Driver, but some
> optional utilities are provided to simplify common tasks. These
> utilities include endpoint autoconfiguration.
>
> -!Edrivers/usb/gadget/usbstring.c !Edrivers/usb/gadget/config.c
> +.. kernel-doc:: drivers/usb/gadget/usbstring.c
> + :export:
> +
> +.. kernel-doc:: drivers/usb/gadget/config.c
> + :export:
> +
> Composite Device Framework
> --------------------------
>
> @@ -337,7 +343,12 @@ usb\_function*, which packages a user visible role such as "network
> link" or "mass storage device". Management functions may also exist,
> such as "Device Firmware Upgrade".
>
> -!Iinclude/linux/usb/composite.h !Edrivers/usb/gadget/composite.c
> +.. kernel-doc:: include/linux/usb/composite.h
> + :internal:
> +
> +.. kernel-doc:: drivers/usb/gadget/composite.c
> + :export:
> +
> Composite Device Functions
> --------------------------
>
> @@ -345,11 +356,21 @@ At this writing, a few of the current gadget drivers have been converted
> to this framework. Near-term plans include converting all of them,
> except for "gadgetfs".
>
> -!Edrivers/usb/gadget/function/f\_acm.c
> -!Edrivers/usb/gadget/function/f\_ecm.c
> -!Edrivers/usb/gadget/function/f\_subset.c
> -!Edrivers/usb/gadget/function/f\_obex.c
> -!Edrivers/usb/gadget/function/f\_serial.c
> +.. kernel-doc:: drivers/usb/gadget/function/f_acm.c
> + :export:
> +
> +.. kernel-doc:: drivers/usb/gadget/function/f_ecm.c
> + :export:
> +
> +.. kernel-doc:: drivers/usb/gadget/function/f_subset.c
> + :export:
> +
> +.. kernel-doc:: drivers/usb/gadget/function/f_obex.c
> + :export:
> +
> +.. kernel-doc:: drivers/usb/gadget/function/f_serial.c
> + :export:
> +
> Peripheral Controller Drivers
> =============================
>
> @@ -475,7 +496,7 @@ can also benefit non-OTG products.
> - Also on the host side, a driver must support the OTG "Targeted
> Peripheral List". That's just a whitelist, used to reject peripherals
> not supported with a given Linux OTG host. *This whitelist is
> - product-specific; each product must modify ``otg_whitelist.h`` to
> + product-specific; each product must modify* ``otg_whitelist.h`` *to
> match its interoperability specification.*
>
> Non-OTG Linux hosts, like PCs and workstations, normally have some
--
Jani Nikula, Intel Open Source Technology Center
^ permalink raw reply [flat|nested] 52+ messages in thread
* Re: [PATCH 04/22] gadget.rst: Enrich its ReST representation and add kernel-doc tag
2017-03-30 7:01 ` Jani Nikula
@ 2017-03-30 7:04 ` Jani Nikula
2017-03-30 9:29 ` Mauro Carvalho Chehab
2017-03-30 8:45 ` Mauro Carvalho Chehab
1 sibling, 1 reply; 52+ messages in thread
From: Jani Nikula @ 2017-03-30 7:04 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Linux Media Mailing List,
Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, John Youn,
linux-usb, linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab
On Thu, 30 Mar 2017, Jani Nikula <jani.nikula@linux.intel.com> wrote:
> On Wed, 29 Mar 2017, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
>> The pandoc conversion is not perfect. Do handwork in order to:
>>
>> - add a title to this chapter;
>> - use the proper warning and note markups;
>> - use kernel-doc to include Kernel header and c files;
>
> Please look at Documentation/sphinx/tmplcvt which takes care of all of
> that.
That said, since you've already manually done the work, you might want
to do another conversion using the script, and diff the results to see
if there's something you've perhaps missed. I'm pretty sure nobody's
going to read patch 2 line-by-line...
BR,
Jani.
>
> BR,
> Jani.
>
>> - remove legacy notes with regards to DocBook;
>> - some other minor adjustments to make it better to read in
>> text mode and in html.
>>
>> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
>> ---
>> Documentation/driver-api/usb/gadget.rst | 69 +++++++++++++++++++++------------
>> 1 file changed, 45 insertions(+), 24 deletions(-)
>>
>> diff --git a/Documentation/driver-api/usb/gadget.rst b/Documentation/driver-api/usb/gadget.rst
>> index 4fd9862f3f21..c4c76ebb51d3 100644
>> --- a/Documentation/driver-api/usb/gadget.rst
>> +++ b/Documentation/driver-api/usb/gadget.rst
>> @@ -1,3 +1,7 @@
>> +Linux-USB "Gadget" kernel mode API
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>> +
>> +
>> Introduction
>> ============
>>
>> @@ -175,16 +179,12 @@ 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.
>>
>> - **Note**
>> +.. Note::
>>
>> - This documentation was prepared using the standard Linux kernel
>> - ``docproc`` tool, which turns text and in-code comments into SGML
>> - DocBook and then into usable formats such as HTML or PDF. Other than
>> - the "Chapter 9" data types, most of the significant data types and
>> - functions are described here.
>> + Other than the "Chapter 9" data types, most of the significant data
>> + types and functions are described here.
>>
>> - However, docproc does not understand all the C constructs that are
>> - used, so some relevant information is likely omitted from what you
>> + However, some relevant information is likely omitted from what you
>> are reading. One example of such information is endpoint
>> autoconfiguration. You'll have to read the header file, and use
>> example source code (such as that for "Gadget Zero"), to fully
>> @@ -192,10 +192,10 @@ and you will understand how this API works.
>>
>> The part of the API implementing some basic driver capabilities is
>> specific to the version of the Linux kernel that's in use. The 2.6
>> - kernel includes a *driver model* framework that has no analogue on
>> - earlier kernels; so those parts of the gadget API are not fully
>> - portable. (They are implemented on 2.4 kernels, but in a different
>> - way.) The driver model state is another part of this API that is
>> + and upper kernel versions include a *driver model* framework that has
>> + no analogue on earlier kernels; so those parts of the gadget API are
>> + not fully portable. (They are implemented on 2.4 kernels, but in a
>> + different way.) The driver model state is another part of this API that is
>> ignored by the kerneldoc tools.
>>
>> The core API does not expose every possible hardware feature, only the
>> @@ -301,18 +301,19 @@ USB 2.0 Chapter 9 Types and Constants
>> -------------------------------------
>>
>> Gadget drivers rely on common USB structures and constants defined in
>> -the ``<linux/usb/ch9.h>`` header file, which is standard in Linux 2.6
>> -kernels. These are the same types and constants used by host side
>> +the :ref:`linux/usb/ch9.h <usb_chapter9>` header file, which is standard in
>> +Linux 2.6+ kernels. These are the same types and constants used by host side
>> drivers (and usbcore).
>>
>> -!Iinclude/linux/usb/ch9.h
>> Core Objects and Methods
>> ------------------------
>>
>> These are declared in ``<linux/usb/gadget.h>``, and are used by gadget
>> drivers to interact with USB peripheral controller drivers.
>>
>> -!Iinclude/linux/usb/gadget.h
>> +.. kernel-doc:: include/linux/usb/gadget.h
>> + :internal:
>> +
>> Optional Utilities
>> ------------------
>>
>> @@ -320,7 +321,12 @@ The core API is sufficient for writing a USB Gadget Driver, but some
>> optional utilities are provided to simplify common tasks. These
>> utilities include endpoint autoconfiguration.
>>
>> -!Edrivers/usb/gadget/usbstring.c !Edrivers/usb/gadget/config.c
>> +.. kernel-doc:: drivers/usb/gadget/usbstring.c
>> + :export:
>> +
>> +.. kernel-doc:: drivers/usb/gadget/config.c
>> + :export:
>> +
>> Composite Device Framework
>> --------------------------
>>
>> @@ -337,7 +343,12 @@ usb\_function*, which packages a user visible role such as "network
>> link" or "mass storage device". Management functions may also exist,
>> such as "Device Firmware Upgrade".
>>
>> -!Iinclude/linux/usb/composite.h !Edrivers/usb/gadget/composite.c
>> +.. kernel-doc:: include/linux/usb/composite.h
>> + :internal:
>> +
>> +.. kernel-doc:: drivers/usb/gadget/composite.c
>> + :export:
>> +
>> Composite Device Functions
>> --------------------------
>>
>> @@ -345,11 +356,21 @@ At this writing, a few of the current gadget drivers have been converted
>> to this framework. Near-term plans include converting all of them,
>> except for "gadgetfs".
>>
>> -!Edrivers/usb/gadget/function/f\_acm.c
>> -!Edrivers/usb/gadget/function/f\_ecm.c
>> -!Edrivers/usb/gadget/function/f\_subset.c
>> -!Edrivers/usb/gadget/function/f\_obex.c
>> -!Edrivers/usb/gadget/function/f\_serial.c
>> +.. kernel-doc:: drivers/usb/gadget/function/f_acm.c
>> + :export:
>> +
>> +.. kernel-doc:: drivers/usb/gadget/function/f_ecm.c
>> + :export:
>> +
>> +.. kernel-doc:: drivers/usb/gadget/function/f_subset.c
>> + :export:
>> +
>> +.. kernel-doc:: drivers/usb/gadget/function/f_obex.c
>> + :export:
>> +
>> +.. kernel-doc:: drivers/usb/gadget/function/f_serial.c
>> + :export:
>> +
>> Peripheral Controller Drivers
>> =============================
>>
>> @@ -475,7 +496,7 @@ can also benefit non-OTG products.
>> - Also on the host side, a driver must support the OTG "Targeted
>> Peripheral List". That's just a whitelist, used to reject peripherals
>> not supported with a given Linux OTG host. *This whitelist is
>> - product-specific; each product must modify ``otg_whitelist.h`` to
>> + product-specific; each product must modify* ``otg_whitelist.h`` *to
>> match its interoperability specification.*
>>
>> Non-OTG Linux hosts, like PCs and workstations, normally have some
--
Jani Nikula, Intel Open Source Technology Center
^ permalink raw reply [flat|nested] 52+ messages in thread
* Re: [PATCH 04/22] gadget.rst: Enrich its ReST representation and add kernel-doc tag
2017-03-30 7:04 ` Jani Nikula
@ 2017-03-30 9:29 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-30 9:29 UTC (permalink / raw)
To: Jani Nikula
Cc: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman, Mauro Carvalho Chehab, John Youn, linux-usb,
linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab
Em Thu, 30 Mar 2017 10:04:32 +0300
Jani Nikula <jani.nikula@linux.intel.com> escreveu:
> On Thu, 30 Mar 2017, Jani Nikula <jani.nikula@linux.intel.com> wrote:
> > On Wed, 29 Mar 2017, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> >> The pandoc conversion is not perfect. Do handwork in order to:
> >>
> >> - add a title to this chapter;
> >> - use the proper warning and note markups;
> >> - use kernel-doc to include Kernel header and c files;
> >
> > Please look at Documentation/sphinx/tmplcvt which takes care of all of
> > that.
>
> That said, since you've already manually done the work, you might want
> to do another conversion using the script, and diff the results to see
> if there's something you've perhaps missed. I'm pretty sure nobody's
> going to read patch 2 line-by-line...
Done. The only thing left was the original docbook title and author
information.
The diff also showed that I was a little lazy manually adjust the
gadget.rst document ;) The enclosed patch should fix those issues.
I'll likely fold it with other patches when sending a version 2.
Regards,
Mauro
[PATCH] docs-rst: improve docbook-converted documents
The output of Documentation/sphinx/tmplcvt showed that a few
adjustments could be done in order to improve the output of
the two files that were converted from docbook:
- Use the original title from docbook;
- Add author info;
- Add C references for source code xrefs;
- Use monospaced fonts to be consistent with other docs.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
diff --git a/Documentation/driver-api/usb/gadget.rst b/Documentation/driver-api/usb/gadget.rst
index 0488b89de21c..4b02c61a389d 100644
--- a/Documentation/driver-api/usb/gadget.rst
+++ b/Documentation/driver-api/usb/gadget.rst
@@ -1,6 +1,9 @@
-Linux-USB "Gadget" kernel mode API
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~
+USB Gadget API for Linux
+~~~~~~~~~~~~~~~~~~~~~~~~
+:Author: David Brownell
+:Date: 20 August 2004
Introduction
============
@@ -35,7 +38,7 @@ address a number of important problems, including:
resources.
Most Linux developers will not be able to use this API, since they have
-USB "host" hardware in a PC, workstation, or server. Linux users with
+USB ``host`` hardware in a PC, workstation, or server. Linux users with
embedded systems are more likely to have USB peripheral hardware. To
distinguish drivers running inside such hardware from the more familiar
Linux "USB device drivers", which are host side proxies for the real USB
@@ -61,7 +64,7 @@ Structure of Gadget Drivers
A system running inside a USB peripheral normally has at least three
layers inside the kernel to handle USB protocol processing, and may have
-additional layers in user space code. The "gadget" API is used by the
+additional layers in user space code. The ``gadget`` API is used by the
middle layer to interact with the lowest level (which directly handles
hardware).
@@ -140,13 +143,13 @@ In Linux, from the bottom up, these layers are:
*Additional Layers*
Other layers may exist. These could include kernel layers, such as
network protocol stacks, as well as user mode applications building
- on standard POSIX system call APIs such as *open()*, *close()*,
- *read()* and *write()*. On newer systems, POSIX Async I/O calls may
+ on standard POSIX system call APIs such as ``open()``, ``close()``,
+ ``read()`` and ``write()``. On newer systems, POSIX Async I/O calls may
be an option. Such user mode code will not necessarily be subject to
the GNU General Public License (GPL).
OTG-capable systems will also need to include a standard Linux-USB host
-side stack, with *usbcore*, one or more *Host Controller Drivers*
+side stack, with ``usbcore``, one or more *Host Controller Drivers*
(HCDs), *USB Device Drivers* to support the OTG "Targeted Peripheral
List", and so forth. There will also be an *OTG Controller Driver*,
which is visible to gadget and device driver developers only indirectly.
@@ -171,11 +174,11 @@ combined, to implement composite devices.
Kernel Mode Gadget API
======================
-Gadget drivers declare themselves through a *struct
-usb\_gadget\_driver*, which is responsible for most parts of enumeration
-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
+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
transfer data. Understand those four data types, and their operations,
and you will understand how this API works.
@@ -239,28 +242,28 @@ needs to handle some differences. Use the API like this:
1. Register a driver for the particular device side usb controller
hardware, such as the net2280 on PCI (USB 2.0), sa11x0 or pxa25x as
found in Linux PDAs, and so on. At this point the device is logically
- in the USB ch9 initial state ("attached"), drawing no power and not
+ in the USB ch9 initial state (``attached``), drawing no power and not
usable (since it does not yet support enumeration). Any host should
not see the device, since it's not activated the data line pullup
used by the host to detect a device, even if VBUS power is available.
2. Register a gadget driver that implements some higher level device
- function. That will then bind() to a usb\_gadget, which activates the
- data line pullup sometime after detecting VBUS.
+ function. That will then bind() to a :c:type:`usb_gadget`, which activates
+ the data line pullup sometime after detecting VBUS.
3. The hardware driver can now start enumerating. The steps it handles
- are to accept USB power and set\_address requests. Other steps are
+ are to accept USB ``power`` and ``set_address`` requests. Other steps are
handled by the gadget driver. If the gadget driver module is unloaded
before the host starts to enumerate, steps before step 7 are skipped.
-4. The gadget driver's setup() call returns usb descriptors, based both
+4. The gadget driver's ``setup()`` call returns usb descriptors, based both
on what the bus interface hardware provides and on the functionality
being implemented. That can involve alternate settings or
configurations, unless the hardware prevents such operation. For OTG
devices, each configuration descriptor includes an OTG descriptor.
5. The gadget driver handles the last step of enumeration, when the USB
- host issues a set\_configuration call. It enables all endpoints used
+ host issues a ``set_configuration`` call. It enables all endpoints used
in that configuration, with all interfaces in their default settings.
That involves using a list of the hardware's endpoints, enabling each
endpoint according to its descriptor. It may also involve using
@@ -293,7 +296,7 @@ built by integrating reusable components.
Note that the lifecycle above can be slightly different for OTG devices.
Other than providing an additional OTG descriptor in each configuration,
only the HNP-related differences are particularly visible to driver
-code. They involve reporting requirements during the SET\_CONFIGURATION
+code. They involve reporting requirements during the ``SET_CONFIGURATION``
request, and the option to invoke HNP during some suspend callbacks.
Also, SRP changes the semantics of ``usb_gadget_wakeup`` slightly.
@@ -336,10 +339,10 @@ 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 usb\_composite\_driver*,
-which in turn provides one or more *struct usb\_configuration*
-instances. Each such configuration includes at least one *struct
-usb\_function*, which packages a user visible role such as "network
+Devices using this framework provide a struct :c:type:`usb_composite_driver`,
+which in turn provides one or more struct :c:type:`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,
such as "Device Firmware Upgrade".
@@ -354,7 +357,7 @@ Composite Device Functions
At this writing, a few of the current gadget drivers have been converted
to this framework. Near-term plans include converting all of them,
-except for "gadgetfs".
+except for ``gadgetfs``.
Peripheral Controller Drivers
=============================
@@ -365,7 +368,7 @@ which supports USB 2.0 high speed and is based on PCI. This is the
and 2.6; contact NetChip Technologies for development boards and product
information.
-Other hardware working in the "gadget" framework includes: Intel's PXA
+Other hardware working in the ``gadget`` framework includes: Intel's PXA
25x and IXP42x series processors (``pxa2xx_udc``), Toshiba TC86c001
"Goku-S" (``goku_udc``), Renesas SH7705/7727 (``sh_udc``), MediaQ 11xx
(``mq11xx_udc``), Hynix HMS30C7202 (``h7202_udc``), National 9303/4
@@ -396,7 +399,7 @@ Gadget Drivers
In addition to *Gadget Zero* (used primarily for testing and development
with drivers for usb controller hardware), other gadget drivers exist.
-There's an *ethernet* gadget driver, which implements one of the most
+There's an ``ethernet`` gadget driver, which implements one of the most
useful *Communications Device Class* (CDC) models. One of the standards
for cable modem interoperability even specifies the use of this ethernet
model as one of two mandatory options. Gadgets using this code look to a
@@ -408,16 +411,16 @@ driver also implements a "good parts only" subset of CDC Ethernet. (That
subset doesn't advertise itself as CDC Ethernet, to avoid creating
problems.)
-Support for Microsoft's *RNDIS* protocol has been contributed by
+Support for Microsoft's ``RNDIS`` protocol has been contributed by
Pengutronix and Auerswald GmbH. This is like CDC Ethernet, but it runs
on more slightly USB hardware (but less than the CDC subset). However,
its main claim to fame is being able to connect directly to recent
versions of Windows, using drivers that Microsoft bundles and supports,
making it much simpler to network with Windows.
-There is also support for user mode gadget drivers, using *gadgetfs*.
+There is also support for user mode gadget drivers, using ``gadgetfs``.
This provides a *User Mode API* that presents each endpoint as a single
-file descriptor. I/O is done using normal *read()* and *read()* calls.
+file descriptor. I/O is done using normal ``read()`` and ``read()`` calls.
Familiar tools like GDB and pthreads can be used to develop and debug
user mode drivers, so that once a robust controller driver is available
many applications for it won't require new kernel mode software. Linux
@@ -453,21 +456,21 @@ Systems need specialized hardware support to implement OTG, notably
including a special *Mini-AB* jack and associated transceiver to support
*Dual-Role* operation: they can act either as a host, using the standard
Linux-USB host side driver stack, or as a peripheral, using this
-"gadget" framework. To do that, the system software relies on small
+``gadget`` framework. To do that, the system software relies on small
additions to those programming interfaces, and on a new internal
component (here called an "OTG Controller") affecting which driver stack
connects to the OTG port. In each role, the system can re-use the
existing pool of hardware-neutral drivers, layered on top of the
-controller driver interfaces (*usb\_bus* or *usb\_gadget*). Such drivers
-need at most minor changes, and most of the calls added to support OTG
-can also benefit non-OTG products.
+controller driver interfaces (:c:type:`usb_bus` or :c:type:`usb_gadget`).
+Such drivers need at most minor changes, and most of the calls added to
+support OTG can also benefit non-OTG products.
-- Gadget drivers test the *is\_otg* flag, and use it to determine
+- Gadget drivers test the ``is_otg`` flag, and use it to determine
whether or not to include an OTG descriptor in each of their
configurations.
- Gadget drivers may need changes to support the two new OTG protocols,
- exposed in new gadget attributes such as *b\_hnp\_enable* flag. HNP
+ exposed in new gadget attributes such as ``b_hnp_enable`` flag. HNP
support should be reported through a user interface (two LEDs could
suffice), and is triggered in some cases when the host suspends the
peripheral. SRP support can be user-initiated just like remote
@@ -494,8 +497,8 @@ can also benefit non-OTG products.
been distributed, so driver bugs can't normally be fixed if they're
found after shipment.
-Additional changes are needed below those hardware-neutral *usb\_bus*
-and *usb\_gadget* driver interfaces; those aren't discussed here in any
+Additional changes are needed below those hardware-neutral :c:type:`usb_bus`
+and :c:type:`usb_gadget` driver interfaces; those aren't discussed here in any
detail. Those affect the hardware-specific code for each USB Host or
Peripheral controller, and how the HCD initializes (since OTG can be
active only on a single port). They also involve what may be called an
diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst b/Documentation/driver-api/usb/writing_usb_driver.rst
index 180859f664db..c751c2e99fb0 100644
--- a/Documentation/driver-api/usb/writing_usb_driver.rst
+++ b/Documentation/driver-api/usb/writing_usb_driver.rst
@@ -1,7 +1,10 @@
.. _writing-usb-driver:
-Writing USB drivers
-~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+Writing USB Device Drivers
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:Author: Greg Kroah-Hartman
Introduction
============
Thanks,
Mauro
^ permalink raw reply related [flat|nested] 52+ messages in thread
* Re: [PATCH 04/22] gadget.rst: Enrich its ReST representation and add kernel-doc tag
2017-03-30 7:01 ` Jani Nikula
2017-03-30 7:04 ` Jani Nikula
@ 2017-03-30 8:45 ` Mauro Carvalho Chehab
1 sibling, 0 replies; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-30 8:45 UTC (permalink / raw)
To: Jani Nikula
Cc: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman, Mauro Carvalho Chehab, John Youn, linux-usb,
linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab
Em Thu, 30 Mar 2017 10:01:29 +0300
Jani Nikula <jani.nikula@linux.intel.com> escreveu:
> On Wed, 29 Mar 2017, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> > The pandoc conversion is not perfect. Do handwork in order to:
> >
> > - add a title to this chapter;
> > - use the proper warning and note markups;
> > - use kernel-doc to include Kernel header and c files;
>
> Please look at Documentation/sphinx/tmplcvt which takes care of all of
> that.
Ah, didn't know about such script!
Trying it here:
$ Documentation/sphinx/tmplcvt Documentation/DocBook/writing_usb_driver.tmpl
sed: couldn't open file convert_template.sed: No such file or directory
It would be good to change the script for it to seek for convert_template.sed
at the right place.
So, please consider the following patch.
Regards,
Mauro
[PATCH] tmplcvt: make the tool more robust
Currently, the script just assumes to be called at
Documentation/sphinx/. Change it to work on any directory,
and make it abort if something gets wrong.
Also, be sure that both parameters are specified.
That should avoid troubles like this:
$ Documentation/sphinx/tmplcvt Documentation/DocBook/writing_usb_driver.tmpl
sed: couldn't open file convert_template.sed: No such file or directory
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
diff --git a/Documentation/sphinx/tmplcvt b/Documentation/sphinx/tmplcvt
index 909a73065e0a..31df8eb7feca 100755
--- a/Documentation/sphinx/tmplcvt
+++ b/Documentation/sphinx/tmplcvt
@@ -7,13 +7,22 @@
# fix \_
# title line?
#
+set -eu
+
+if [ "$2" == "" ]; then
+ echo "$0 <docbook file> <rst file>"
+ exit
+fi
+
+DIR=$(dirname $0)
in=$1
rst=$2
tmp=$rst.tmp
cp $in $tmp
-sed --in-place -f convert_template.sed $tmp
+sed --in-place -f $DIR/convert_template.sed $tmp
pandoc -s -S -f docbook -t rst -o $rst $tmp
-sed --in-place -f post_convert.sed $rst
+sed --in-place -f $DIR/post_convert.sed $rst
rm $tmp
+echo "book writen to $rst"
^ permalink raw reply related [flat|nested] 52+ messages in thread
* [PATCH 05/22] writing_usb_driver.rst: Enrich its ReST representation
2017-03-29 18:54 [PATCH 01/22] driver-api/basics.rst: add device table header Mauro Carvalho Chehab
` (2 preceding siblings ...)
2017-03-29 18:54 ` [PATCH 04/22] gadget.rst: Enrich its ReST representation and add kernel-doc tag Mauro Carvalho Chehab
@ 2017-03-29 18:54 ` Mauro Carvalho Chehab
2017-03-29 18:54 ` [PATCH 06/22] writing_musb_glue_layer.rst: " Mauro Carvalho Chehab
` (17 subsequent siblings)
21 siblings, 0 replies; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-29 18:54 UTC (permalink / raw)
To: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, John Youn,
linux-usb, linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab
The pandoc conversion is not perfect. Do handwork in order to:
- add a title to this chapter;
- adjust function and struct references;
- use monospaced fonts for C code names;
- some other minor adjustments to make it better to read in
text mode and in html.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
.../driver-api/usb/writing_usb_driver.rst | 97 +++++++++-------------
1 file changed, 41 insertions(+), 56 deletions(-)
diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst b/Documentation/driver-api/usb/writing_usb_driver.rst
index 48f2fdb4745b..180859f664db 100644
--- a/Documentation/driver-api/usb/writing_usb_driver.rst
+++ b/Documentation/driver-api/usb/writing_usb_driver.rst
@@ -1,3 +1,8 @@
+.. _writing-usb-driver:
+
+Writing USB drivers
+~~~~~~~~~~~~~~~~~~~
+
Introduction
============
@@ -42,10 +47,8 @@ The first thing a Linux USB driver needs to do is register itself with
the Linux USB subsystem, giving it some information about which devices
the driver supports and which functions to call when a device supported
by the driver is inserted or removed from the system. All of this
-information is passed to the USB subsystem in the usb\_driver structure.
-The skeleton driver declares a usb\_driver as:
-
-::
+information is passed to the USB subsystem in the :c:type:`usb_driver`
+structure. The skeleton driver declares a :c:type:`usb_driver` as::
static struct usb_driver skel_driver = {
.name = "skeleton",
@@ -60,7 +63,7 @@ The skeleton driver declares a usb\_driver as:
The variable name is a string that describes the driver. It is used in
informational messages printed to the system log. The probe and
disconnect function pointers are called when a device that matches the
-information provided in the id\_table variable is either seen or
+information provided in the ``id_table`` variable is either seen or
removed.
The fops and minor variables are optional. Most USB drivers hook into
@@ -70,15 +73,13 @@ subsystem, and any user-space interactions are provided through that
interface. But for drivers that do not have a matching kernel subsystem,
such as MP3 players or scanners, a method of interacting with user space
is needed. The USB subsystem provides a way to register a minor device
-number and a set of file\_operations function pointers that enable this
-user-space interaction. The skeleton driver needs this kind of
+number and a set of :c:type:`file_operations` function pointers that enable
+this user-space interaction. The skeleton driver needs this kind of
interface, so it provides a minor starting number and a pointer to its
-file\_operations functions.
+:c:type:`file_operations` functions.
-The USB driver is then registered with a call to usb\_register, usually
-in the driver's init function, as shown here:
-
-::
+The USB driver is then registered with a call to :c:func:`usb_register`,
+usually in the driver's init function, as shown here::
static int __init usb_skel_init(void)
{
@@ -98,10 +99,8 @@ 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 usb\_deregister
-function:
-
-::
+itself with the USB subsystem. This is done with the :c:func:`usb_deregister`
+function::
static void __exit usb_skel_exit(void)
{
@@ -112,11 +111,9 @@ function:
To enable the linux-hotplug system to load the driver automatically when
-the device is plugged in, you need to create a MODULE\_DEVICE\_TABLE.
+the device is plugged in, you need to create a ``MODULE_DEVICE_TABLE``.
The following code tells the hotplug scripts that this module supports a
-single device with a specific vendor and product ID:
-
-::
+single device with a specific vendor and product ID::
/* table of devices that work with this driver */
static struct usb_device_id skel_table [] = {
@@ -126,19 +123,17 @@ single device with a specific vendor and product ID:
MODULE_DEVICE_TABLE (usb, skel_table);
-There are other macros that can be used in describing a usb\_device\_id
-for drivers that support a whole class of USB drivers. See usb.h for
-more information on this.
+There are other macros that can be used in describing a struct
+:c:type:`usb_device_id` for drivers that support a whole class of USB
+drivers. See :ref:`usb.h <usb_header>` for more information on this.
Device operation
================
When a device is plugged into the USB bus that matches the device ID
pattern that your driver registered with the USB core, the probe
-function is called. The usb\_device structure, interface number and the
-interface ID are passed to the function:
-
-::
+function is called. The :c:type:`usb_device` structure, interface number and
+the interface ID are passed to the function::
static int skel_probe(struct usb_interface *interface,
const struct usb_device_id *id)
@@ -160,16 +155,14 @@ any private data that has been allocated at this time and to shut down
any pending urbs that are in the USB system.
Now that the device is plugged into the system and the driver is bound
-to the device, any of the functions in the file\_operations structure
+to the device, any of the functions in the :c:type:`file_operations` structure
that were passed to the USB subsystem will be called from a user program
trying to talk to the device. The first function called will be open, as
the program tries to open the device for I/O. We increment our private
usage count and save a pointer to our internal structure in the file
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:
-
-::
+of this is done with the following code::
/* increment our usage count for the module */
++skel->open_count;
@@ -179,16 +172,14 @@ of this is done with the following code:
After the open function is called, the read and write functions are
-called to receive and send data to the device. In the skel\_write
+called to receive and send data to the device. In the ``skel_write``
function, we receive a pointer to some data that the user wants to send
to the device and the size of the data. The function determines how much
data it can send to the device based on the size of the write urb it has
created (this size depends on the size of the bulk out end point that
the device has). Then it copies the data from user space to kernel
space, points the urb to the data and submits the urb to the USB
-subsystem. This can be seen in the following code:
-
-::
+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;
@@ -213,25 +204,23 @@ subsystem. This can be seen in the following code:
When the write urb is filled up with the proper information using the
-usb\_fill\_bulk\_urb function, we point the urb's completion callback to
-call our own skel\_write\_bulk\_callback function. This function is
+:c:func:`usb_fill_bulk_urb` function, we point the urb's completion callback
+to call our own ``skel_write_bulk_callback`` function. This function is
called when the urb is finished by the USB subsystem. The callback
function is called in interrupt context, so caution must be taken not to
do very much processing at that time. Our implementation of
-skel\_write\_bulk\_callback merely reports if the urb was completed
+``skel_write_bulk_callback`` merely reports if the urb was completed
successfully or not and then returns.
The read function works a bit differently from the write function in
that we do not use an urb to transfer data from the device to the
-driver. Instead we call the usb\_bulk\_msg function, which can be used
+driver. Instead we call the :c:func:`usb_bulk_msg` function, which can be used
to send or receive data from a device without having to create urbs and
-handle urb completion callback functions. We call the usb\_bulk\_msg
+handle urb completion callback functions. We call the :c:func:`usb_bulk_msg`
function, giving it a buffer into which to place any data received from
the device and a timeout value. If the timeout period expires without
receiving any data from the device, the function will fail and return an
-error message. This can be shown with the following code:
-
-::
+error message. This can be shown with the following code::
/* do an immediate bulk read to get data from the device */
retval = usb_bulk_msg (skel->dev,
@@ -249,17 +238,15 @@ error message. This can be shown with the following code:
}
-The usb\_bulk\_msg function can be very useful for doing single reads or
-writes to a device; however, if you need to read or write constantly to
+The :c:func:`usb_bulk_msg` function can be very useful for doing single reads
+or writes to a device; however, if you need to read or write constantly to
a device, it is recommended to set up your own urbs and submit them to
the USB subsystem.
When the user program releases the file handle that it has been using to
talk to the device, the release function in the driver is called. In
this function we decrement our private usage count and wait for possible
-pending writes:
-
-::
+pending writes::
/* decrement our usage count for the device */
--skel->open_count;
@@ -271,9 +258,7 @@ system at any point in time, even if a program is currently talking to
it. It needs to be able to shut down any current reads and writes and
notify the user-space programs that the device is no longer there. The
following code (function ``skel_delete``) is an example of how to do
-this:
-
-::
+this::
static inline void skel_delete (struct usb_skel *dev)
{
@@ -291,10 +276,10 @@ If a program currently has an open handle to the device, we reset the
flag ``device_present``. For every read, write, release and other
functions that expect a device to be present, the driver first checks
this flag to see if the device is still present. If not, it releases
-that the device has disappeared, and a -ENODEV error is returned to the
+that the device has disappeared, and a ``-ENODEV`` error is returned to the
user-space program. When the release function is eventually called, it
determines if there is no device and if not, it does the cleanup that
-the skel\_disconnect function normally does if there are no open files
+the ``skel_disconnect`` function normally does if there are no open files
on the device (see Listing 5).
Isochronous Data
@@ -321,13 +306,13 @@ Resources
=========
The Linux USB Project:
-`http://www.linux-usb.org/ <http://www.linux-usb.org>`__
+http://www.linux-usb.org/
Linux Hotplug Project:
-`http://linux-hotplug.sourceforge.net/ <http://linux-hotplug.sourceforge.net>`__
+http://linux-hotplug.sourceforge.net/
Linux USB Working Devices List:
-`http://www.qbik.ch/usb/devices/ <http://www.qbik.ch/usb/devices>`__
+http://www.qbik.ch/usb/devices/
linux-usb-devel Mailing List Archives:
http://marc.theaimsgroup.com/?l=linux-usb-devel
--
2.9.3
^ permalink raw reply related [flat|nested] 52+ messages in thread* [PATCH 06/22] writing_musb_glue_layer.rst: Enrich its ReST representation
2017-03-29 18:54 [PATCH 01/22] driver-api/basics.rst: add device table header Mauro Carvalho Chehab
` (3 preceding siblings ...)
2017-03-29 18:54 ` [PATCH 05/22] writing_usb_driver.rst: Enrich its ReST representation Mauro Carvalho Chehab
@ 2017-03-29 18:54 ` Mauro Carvalho Chehab
2017-03-29 18:54 ` [PATCH 07/22] usb/anchors.txt: convert to ReST and add to driver-api book Mauro Carvalho Chehab
` (16 subsequent siblings)
21 siblings, 0 replies; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-29 18:54 UTC (permalink / raw)
To: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, John Youn,
linux-usb, linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab
This file is actually quite complex, and required several
manual handwork:
- add a title for the document;
- use the right tags for monospaced fonts;
- use c references where needed;
- adjust cross-reference to writing_usb_driver.rst
- hightlight cross-referenced lines.
With regards to C code snippet line highlights, the better would be
to use :linenos: for the C code snippets that are referenced by
the line number. However, at least with Sphinx 1.4.9, enabling
it cause the line number to be misaligned with the code,
making it even more confusing. So, instead, let's use
:emphasize-lines: tag to mark the lines that are referenced
at the text.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
.../driver-api/usb/writing_musb_glue_layer.rst | 251 ++++++++++-----------
1 file changed, 120 insertions(+), 131 deletions(-)
diff --git a/Documentation/driver-api/usb/writing_musb_glue_layer.rst b/Documentation/driver-api/usb/writing_musb_glue_layer.rst
index 2546a102394f..89333a69d4ba 100644
--- a/Documentation/driver-api/usb/writing_musb_glue_layer.rst
+++ b/Documentation/driver-api/usb/writing_musb_glue_layer.rst
@@ -1,3 +1,6 @@
+Writing MUSB Glue Layer
+~~~~~~~~~~~~~~~~~~~~~~~
+
Introduction
============
@@ -15,10 +18,12 @@ design.
As a self-taught exercise I have written an MUSB glue layer for the
Ingenic JZ4740 SoC, modelled after the many MUSB glue layers in the
kernel source tree. This layer can be found at
-drivers/usb/musb/jz4740.c. In this documentation I will walk through the
-basics of the jz4740.c glue layer, explaining the different pieces and
+``drivers/usb/musb/jz4740.c``. In this documentation I will walk through the
+basics of the ``jz4740.c`` glue layer, explaining the different pieces and
what needs to be done in order to write your own device glue layer.
+.. _musb-basics:
+
Linux MUSB Basics
=================
@@ -33,9 +38,7 @@ USB Device Drivers documentation (again, see Resources).
Linux USB stack is a layered architecture in which the MUSB controller
hardware sits at the lowest. The MUSB controller driver abstract the
-MUSB controller hardware to the Linux USB stack.
-
-::
+MUSB controller hardware to the Linux USB stack::
------------------------
| | <------- drivers/usb/gadget
@@ -59,7 +62,6 @@ MUSB controller hardware to the Linux USB stack.
| MUSB Controller Hardware |
---------------------------------
-
As outlined above, the glue layer is actually the platform specific code
sitting in between the controller driver and the controller hardware.
@@ -72,9 +74,7 @@ about an embedded controller chip here, so no insertion or removal at
run-time.
All of this information is passed to the MUSB controller driver through
-a platform\_driver structure defined in the glue layer as:
-
-::
+a :c:type:`platform_driver` structure defined in the glue layer as::
static struct platform_driver jz4740_driver = {
.probe = jz4740_probe,
@@ -84,20 +84,17 @@ a platform\_driver structure defined in the glue layer as:
},
};
-
The probe and remove function pointers are called when a matching device
is detected and, respectively, released. The name string describes the
device supported by this glue layer. In the current case it matches a
-platform\_device structure declared in arch/mips/jz4740/platform.c. Note
+platform_device structure declared in ``arch/mips/jz4740/platform.c``. Note
that we are not using device tree bindings here.
In order to register itself to the controller driver, the glue layer
goes through a few steps, basically allocating the controller hardware
resources and initialising a couple of circuits. To do so, it needs to
keep track of the information used throughout these steps. This is done
-by defining a private jz4740\_glue structure:
-
-::
+by defining a private ``jz4740_glue`` structure::
struct jz4740_glue {
struct device *dev;
@@ -115,10 +112,13 @@ information related to the device clock operation.
Let's go through the steps of the probe function that leads the glue
layer to register itself to the controller driver.
-N.B.: For the sake of readability each function will be split in logical
-parts, each part being shown as if it was independent from the others.
+.. note::
-::
+ For the sake of readability each function will be split in logical
+ parts, each part being shown as if it was independent from the others:
+
+ .. code-block:: c
+ :emphasize-lines: 8,12,18
static int jz4740_probe(struct platform_device *pdev)
{
@@ -163,21 +163,23 @@ parts, each part being shown as if it was independent from the others.
return ret;
}
+ The first few lines of the probe function allocate and assign the glue,
+ musb and clk variables. The ``GFP_KERNEL`` flag (line 8) allows the
+ allocation process to sleep and wait for memory, thus being usable in a
+ locking situation. The ``PLATFORM_DEVID_AUTO`` flag (line 12) allows
+ automatic allocation and management of device IDs in order to avoid
+ device namespace collisions with explicit IDs. With :c:func:`devm_clk_get`
+ (line 18) the glue layer allocates the clock -- the ``devm_`` prefix
+ indicates that :c:func:`clk_get` is managed: it automatically frees the
+ allocated clock resource data when the device is released -- and enable
+ it.
+
-The first few lines of the probe function allocate and assign the glue,
-musb and clk variables. The GFP\_KERNEL flag (line 8) allows the
-allocation process to sleep and wait for memory, thus being usable in a
-blocking situation. The PLATFORM\_DEVID\_AUTO flag (line 12) allows
-automatic allocation and management of device IDs in order to avoid
-device namespace collisions with explicit IDs. With devm\_clk\_get()
-(line 18) the glue layer allocates the clock -- the ``devm_`` prefix
-indicates that clk\_get() is managed: it automatically frees the
-allocated clock resource data when the device is released -- and enable
-it.
Then comes the registration steps:
-::
+.. code-block:: c
+ :emphasize-lines: 3,5,7,9,16
static int jz4740_probe(struct platform_device *pdev)
{
@@ -209,27 +211,23 @@ Then comes the registration steps:
return ret;
}
-
The first step is to pass the device data privately held by the glue
-layer on to the controller driver through platform\_set\_drvdata() (line
-7). Next is passing on the device resources information, also privately
-held at that point, through platform\_device\_add\_resources() (line 9).
+layer on to the controller driver through :c:func:`platform_set_drvdata`
+(line 7). Next is passing on the device resources information, also privately
+held at that point, through :c:func:`platform_device_add_resources` (line 9).
Finally comes passing on the platform specific data to the controller
-driver (line 16). Platform data will be discussed in `Chapter
-4 <#device-platform-data>`__, but here we are looking at the
-platform\_ops function pointer (line 5) in musb\_hdrc\_platform\_data
+driver (line 16). Platform data will be discussed in
+:ref:`musb-dev-platform-data`, but here we are looking at the
+``platform_ops`` function pointer (line 5) in ``musb_hdrc_platform_data``
structure (line 3). This function pointer allows the MUSB controller
-driver to know which function to call for device operation:
-
-::
+driver to know which function to call for device operation::
static const struct musb_platform_ops jz4740_musb_ops = {
.init = jz4740_musb_init,
.exit = jz4740_musb_exit,
};
-
Here we have the minimal case where only init and exit functions are
called by the controller driver when needed. Fact is the JZ4740 MUSB
controller is a basic controller, lacking some features found in other
@@ -240,7 +238,8 @@ between OTG and non-OTG modes, for instance.
At that point of the registration process, the controller driver
actually calls the init function:
-::
+ .. code-block:: c
+ :emphasize-lines: 12,14
static int jz4740_musb_init(struct musb *musb)
{
@@ -260,22 +259,19 @@ actually calls the init function:
return 0;
}
-
-The goal of jz4740\_musb\_init() is to get hold of the transceiver
+The goal of ``jz4740_musb_init()`` is to get hold of the transceiver
driver data of the MUSB controller hardware and pass it on to the MUSB
controller driver, as usual. The transceiver is the circuitry inside the
controller hardware responsible for sending/receiving the USB data.
Since it is an implementation of the physical layer of the OSI model,
the transceiver is also referred to as PHY.
-Getting hold of the MUSB PHY driver data is done with usb\_get\_phy()
+Getting hold of the ``MUSB PHY`` driver data is done with ``usb_get_phy()``
which returns a pointer to the structure containing the driver instance
data. The next couple of instructions (line 12 and 14) are used as a
quirk and to setup IRQ handling respectively. Quirks and IRQ handling
-will be discussed later in `Chapter 5 <#device-quirks>`__ and `Chapter
-3 <#handling-irqs>`__.
-
-::
+will be discussed later in :ref:`musb-dev-quirks` and
+:ref:`musb-handling-irqs`\ ::
static int jz4740_musb_exit(struct musb *musb)
{
@@ -284,7 +280,6 @@ will be discussed later in `Chapter 5 <#device-quirks>`__ and `Chapter
return 0;
}
-
Acting as the counterpart of init, the exit function releases the MUSB
PHY driver when the controller hardware itself is about to be released.
@@ -294,9 +289,7 @@ musb glue layer for a more complex controller hardware, you might need
to take care of more processing in those two functions.
Returning from the init function, the MUSB controller driver jumps back
-into the probe function:
-
-::
+into the probe function::
static int jz4740_probe(struct platform_device *pdev)
{
@@ -315,13 +308,13 @@ into the probe function:
return ret;
}
-
This is the last part of the device registration process where the glue
layer adds the controller hardware device to Linux kernel device
hierarchy: at this stage, all known information about the device is
-passed on to the Linux USB core stack.
+passed on to the Linux USB core stack:
-::
+ .. code-block:: c
+ :emphasize-lines: 5,6
static int jz4740_remove(struct platform_device *pdev)
{
@@ -333,18 +326,20 @@ passed on to the Linux USB core stack.
return 0;
}
-
Acting as the counterpart of probe, the remove function unregister the
MUSB controller hardware (line 5) and disable the clock (line 6),
allowing it to be gated.
+.. _musb-handling-irqs:
+
Handling IRQs
=============
Additionally to the MUSB controller hardware basic setup and
registration, the glue layer is also responsible for handling the IRQs:
-::
+ .. code-block:: c
+ :emphasize-lines: 7,9-11,14,24
static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci)
{
@@ -374,39 +369,35 @@ registration, the glue layer is also responsible for handling the IRQs:
return retval;
}
-
Here the glue layer mostly has to read the relevant hardware registers
and pass their values on to the controller driver which will handle the
actual event that triggered the IRQ.
The interrupt handler critical section is protected by the
-spin\_lock\_irqsave() and counterpart spin\_unlock\_irqrestore()
+:c:func:`spin_lock_irqsave` and counterpart :c:func:`spin_unlock_irqrestore`
functions (line 7 and 24 respectively), which prevent the interrupt
handler code to be run by two different threads at the same time.
Then the relevant interrupt registers are read (line 9 to 11):
-- MUSB\_INTRUSB: indicates which USB interrupts are currently active,
+- ``MUSB_INTRUSB``: indicates which USB interrupts are currently active,
-- MUSB\_INTRTX: indicates which of the interrupts for TX endpoints are
+- ``MUSB_INTRTX``: indicates which of the interrupts for TX endpoints are
currently active,
-- MUSB\_INTRRX: indicates which of the interrupts for TX endpoints are
+- ``MUSB_INTRRX``: indicates which of the interrupts for TX endpoints are
currently active.
-Note that musb\_readb() is used to read 8-bit registers at most, while
-musb\_readw() allows us to read at most 16-bit registers. There are
+Note that :c:func:`musb_readb` is used to read 8-bit registers at most, while
+:c:func:`musb_readw` allows us to read at most 16-bit registers. There are
other functions that can be used depending on the size of your device
-registers. See musb\_io.h for more information.
+registers. See ``musb_io.h`` for more information.
Instruction on line 18 is another quirk specific to the JZ4740 USB
-device controller, which will be discussed later in `Chapter
-5 <#device-quirks>`__.
+device controller, which will be discussed later in :ref:`musb-dev-quirks`.
The glue layer still needs to register the IRQ handler though. Remember
-the instruction on line 14 of the init function:
-
-::
+the instruction on line 14 of the init function::
static int jz4740_musb_init(struct musb *musb)
{
@@ -415,12 +406,13 @@ the instruction on line 14 of the init function:
return 0;
}
-
This instruction sets a pointer to the glue layer IRQ handler function,
in order for the controller hardware to call the handler back when an
IRQ comes from the controller hardware. The interrupt handler is now
implemented and registered.
+.. _musb-dev-platform-data:
+
Device Platform Data
====================
@@ -429,17 +421,18 @@ describing the hardware capabilities of your controller hardware, which
is called the platform data.
Platform data is specific to your hardware, though it may cover a broad
-range of devices, and is generally found somewhere in the arch/
+range of devices, and is generally found somewhere in the ``arch/``
directory, depending on your device architecture.
For instance, platform data for the JZ4740 SoC is found in
-arch/mips/jz4740/platform.c. In the platform.c file each device of the
+``arch/mips/jz4740/platform.c``. In the ``platform.c`` file each device of the
JZ4740 SoC is described through a set of structures.
-Here is the part of arch/mips/jz4740/platform.c that covers the USB
+Here is the part of ``arch/mips/jz4740/platform.c`` that covers the USB
Device Controller (UDC):
-::
+ .. code-block:: c
+ :emphasize-lines: 2,7,14-17,21,22,25,26,28,29
/* USB Device Controller */
struct platform_device jz4740_udc_xceiv_device = {
@@ -472,59 +465,58 @@ Device Controller (UDC):
.resource = jz4740_udc_resources,
};
-
-The jz4740\_udc\_xceiv\_device platform device structure (line 2)
+The ``jz4740_udc_xceiv_device`` platform device structure (line 2)
describes the UDC transceiver with a name and id number.
-At the time of this writing, note that "usb\_phy\_gen\_xceiv" is the
+At the time of this writing, note that ``usb_phy_gen_xceiv`` is the
specific name to be used for all transceivers that are either built-in
with reference USB IP or autonomous and doesn't require any PHY
-programming. You will need to set CONFIG\_NOP\_USB\_XCEIV=y in the
+programming. You will need to set ``CONFIG_NOP_USB_XCEIV=y`` in the
kernel configuration to make use of the corresponding transceiver
driver. The id field could be set to -1 (equivalent to
-PLATFORM\_DEVID\_NONE), -2 (equivalent to PLATFORM\_DEVID\_AUTO) or
+``PLATFORM_DEVID_NONE``), -2 (equivalent to ``PLATFORM_DEVID_AUTO``) or
start with 0 for the first device of this kind if we want a specific id
number.
-The jz4740\_udc\_resources resource structure (line 7) defines the UDC
+The ``jz4740_udc_resources`` resource structure (line 7) defines the UDC
registers base addresses.
The first array (line 9 to 11) defines the UDC registers base memory
addresses: start points to the first register memory address, end points
to the last register memory address and the flags member defines the
-type of resource we are dealing with. So IORESOURCE\_MEM is used to
+type of resource we are dealing with. So ``IORESOURCE_MEM`` is used to
define the registers memory addresses. The second array (line 14 to 17)
defines the UDC IRQ registers addresses. Since there is only one IRQ
register available for the JZ4740 UDC, start and end point at the same
-address. The IORESOURCE\_IRQ flag tells that we are dealing with IRQ
-resources, and the name "mc" is in fact hard-coded in the MUSB core in
+address. The ``IORESOURCE_IRQ`` flag tells that we are dealing with IRQ
+resources, and the name ``mc`` is in fact hard-coded in the MUSB core in
order for the controller driver to retrieve this IRQ resource by
querying it by its name.
-Finally, the jz4740\_udc\_device platform device structure (line 21)
+Finally, the ``jz4740_udc_device`` platform device structure (line 21)
describes the UDC itself.
-The "musb-jz4740" name (line 22) defines the MUSB driver that is used
+The ``musb-jz4740`` name (line 22) defines the MUSB driver that is used
for this device; remember this is in fact the name that we used in the
-jz4740\_driver platform driver structure in `Chapter
-2 <#linux-musb-basics>`__. The id field (line 23) is set to -1
-(equivalent to PLATFORM\_DEVID\_NONE) since we do not need an id for the
-device: the MUSB controller driver was already set to allocate an
-automatic id in `Chapter 2 <#linux-musb-basics>`__. In the dev field we
-care for DMA related information here. The dma\_mask field (line 25)
+``jz4740_driver`` platform driver structure in :ref:`musb-basics`.
+The id field (line 23) is set to -1 (equivalent to ``PLATFORM_DEVID_NONE``)
+since we do not need an id for the device: the MUSB controller driver was
+already set to allocate an automatic id in :ref:`musb-basics`. In the dev field
+we care for DMA related information here. The ``dma_mask`` field (line 25)
defines the width of the DMA mask that is going to be used, and
-coherent\_dma\_mask (line 26) has the same purpose but for the
-alloc\_coherent DMA mappings: in both cases we are using a 32 bits mask.
+``coherent_dma_mask`` (line 26) has the same purpose but for the
+``alloc_coherent`` DMA mappings: in both cases we are using a 32 bits mask.
Then the resource field (line 29) is simply a pointer to the resource
-structure defined before, while the num\_resources field (line 28) keeps
+structure defined before, while the ``num_resources`` field (line 28) keeps
track of the number of arrays defined in the resource structure (in this
case there were two resource arrays defined before).
-With this quick overview of the UDC platform data at the arch/ level now
+With this quick overview of the UDC platform data at the ``arch/`` level now
done, let's get back to the MUSB glue layer specific platform data in
-drivers/usb/musb/jz4740.c:
+``drivers/usb/musb/jz4740.c``:
-::
+ .. code-block:: c
+ :emphasize-lines: 3,5,7-9,11
static struct musb_hdrc_config jz4740_musb_config = {
/* Silicon does not implement USB OTG. */
@@ -542,35 +534,36 @@ drivers/usb/musb/jz4740.c:
.config = &jz4740_musb_config,
};
-
First the glue layer configures some aspects of the controller driver
operation related to the controller hardware specifics. This is done
-through the jz4740\_musb\_config musb\_hdrc\_config structure.
+through the ``jz4740_musb_config`` :c:type:`musb_hdrc_config` structure.
Defining the OTG capability of the controller hardware, the multipoint
member (line 3) is set to 0 (equivalent to false) since the JZ4740 UDC
-is not OTG compatible. Then num\_eps (line 5) defines the number of USB
+is not OTG compatible. Then ``num_eps`` (line 5) defines the number of USB
endpoints of the controller hardware, including endpoint 0: here we have
-3 endpoints + endpoint 0. Next is ram\_bits (line 7) which is the width
+3 endpoints + endpoint 0. Next is ``ram_bits`` (line 7) which is the width
of the RAM address bus for the MUSB controller hardware. This
information is needed when the controller driver cannot automatically
configure endpoints by reading the relevant controller hardware
registers. This issue will be discussed when we get to device quirks in
-`Chapter 5 <#device-quirks>`__. Last two fields (line 8 and 9) are also
-about device quirks: fifo\_cfg points to the USB endpoints configuration
-table and fifo\_cfg\_size keeps track of the size of the number of
-entries in that configuration table. More on that later in `Chapter
-5 <#device-quirks>`__.
+:ref:`musb-dev-quirks`. Last two fields (line 8 and 9) are also
+about device quirks: ``fifo_cfg`` points to the USB endpoints configuration
+table and ``fifo_cfg_size`` keeps track of the size of the number of
+entries in that configuration table. More on that later in
+:ref:`musb-dev-quirks`.
-Then this configuration is embedded inside jz4740\_musb\_platform\_data
-musb\_hdrc\_platform\_data structure (line 11): config is a pointer to
+Then this configuration is embedded inside ``jz4740_musb_platform_data``
+:c:type:`musb_hdrc_platform_data` structure (line 11): config is a pointer to
the configuration structure itself, and mode tells the controller driver
-if the controller hardware may be used as MUSB\_HOST only,
-MUSB\_PERIPHERAL only or MUSB\_OTG which is a dual mode.
+if the controller hardware may be used as ``MUSB_HOST`` only,
+``MUSB_PERIPHERAL`` only or ``MUSB_OTG`` which is a dual mode.
-Remember that jz4740\_musb\_platform\_data is then used to convey
+Remember that ``jz4740_musb_platform_data`` is then used to convey
platform data information as we have seen in the probe function in
-`Chapter 2 <#linux-musb-basics>`__
+:ref:`musb-basics`.
+
+.. _musb-dev-quirks:
Device Quirks
=============
@@ -587,7 +580,8 @@ controller hardware you are working on.
Let's get back to the init function first:
-::
+ .. code-block:: c
+ :emphasize-lines: 12
static int jz4740_musb_init(struct musb *musb)
{
@@ -607,7 +601,6 @@ Let's get back to the init function first:
return 0;
}
-
Instruction on line 12 helps the MUSB controller driver to work around
the fact that the controller hardware is missing registers that are used
for USB endpoints configuration.
@@ -615,21 +608,18 @@ for USB endpoints configuration.
Without these registers, the controller driver is unable to read the
endpoints configuration from the hardware, so we use line 12 instruction
to bypass reading the configuration from silicon, and rely on a
-hard-coded table that describes the endpoints configuration instead:
-
-::
+hard-coded table that describes the endpoints configuration instead::
static struct musb_fifo_cfg jz4740_musb_fifo_cfg[] = {
- { .hw_ep_num = 1, .style = FIFO_TX, .maxpacket = 512, },
- { .hw_ep_num = 1, .style = FIFO_RX, .maxpacket = 512, },
- { .hw_ep_num = 2, .style = FIFO_TX, .maxpacket = 64, },
+ { .hw_ep_num = 1, .style = FIFO_TX, .maxpacket = 512, },
+ { .hw_ep_num = 1, .style = FIFO_RX, .maxpacket = 512, },
+ { .hw_ep_num = 2, .style = FIFO_TX, .maxpacket = 64, },
};
-
Looking at the configuration table above, we see that each endpoints is
-described by three fields: hw\_ep\_num is the endpoint number, style is
-its direction (either FIFO\_TX for the controller driver to send packets
-in the controller hardware, or FIFO\_RX to receive packets from
+described by three fields: ``hw_ep_num`` is the endpoint number, style is
+its direction (either ``FIFO_TX`` for the controller driver to send packets
+in the controller hardware, or ``FIFO_RX`` to receive packets from
hardware), and maxpacket defines the maximum size of each data packet
that can be transmitted over that endpoint. Reading from the table, the
controller driver knows that endpoint 1 can be used to send and receive
@@ -640,11 +630,12 @@ at once (this is in fact an interrupt endpoint).
Note that there is no information about endpoint 0 here: that one is
implemented by default in every silicon design, with a predefined
configuration according to the USB specification. For more examples of
-endpoint configuration tables, see musb\_core.c.
+endpoint configuration tables, see ``musb_core.c``.
Let's now get back to the interrupt handler function:
-::
+ .. code-block:: c
+ :emphasize-lines: 18-19
static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci)
{
@@ -674,14 +665,13 @@ Let's now get back to the interrupt handler function:
return retval;
}
-
Instruction on line 18 above is a way for the controller driver to work
around the fact that some interrupt bits used for USB host mode
-operation are missing in the MUSB\_INTRUSB register, thus left in an
+operation are missing in the ``MUSB_INTRUSB`` register, thus left in an
undefined hardware state, since this MUSB controller hardware is used in
peripheral mode only. As a consequence, the glue layer masks these
missing bits out to avoid parasite interrupts by doing a logical AND
-operation between the value read from MUSB\_INTRUSB and the bits that
+operation between the value read from ``MUSB_INTRUSB`` and the bits that
are actually implemented in the register.
These are only a couple of the quirks found in the JZ4740 USB device
@@ -721,8 +711,7 @@ linux-usb Mailing List Archives: http://marc.info/?l=linux-usb
USB On-the-Go Basics:
http://www.maximintegrated.com/app-notes/index.mvp/id/1822
-Writing USB Device Drivers:
-https://www.kernel.org/doc/htmldocs/writing_usb_driver/index.html
+:ref:`Writing USB Device Drivers <writing-usb-driver>`
Texas Instruments USB Configuration Wiki Page:
http://processors.wiki.ti.com/index.php/Usbgeneralpage
--
2.9.3
^ permalink raw reply related [flat|nested] 52+ messages in thread* [PATCH 07/22] usb/anchors.txt: convert to ReST and add to driver-api book
2017-03-29 18:54 [PATCH 01/22] driver-api/basics.rst: add device table header Mauro Carvalho Chehab
` (4 preceding siblings ...)
2017-03-29 18:54 ` [PATCH 06/22] writing_musb_glue_layer.rst: " Mauro Carvalho Chehab
@ 2017-03-29 18:54 ` Mauro Carvalho Chehab
2017-03-29 18:54 ` [PATCH 08/22] usb/bulk-streams.txt: " Mauro Carvalho Chehab
` (15 subsequent siblings)
21 siblings, 0 replies; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-29 18:54 UTC (permalink / raw)
To: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, John Youn,
linux-usb, linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab
This document describe some USB core functions. Add it to the
driver-api book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
.../anchors.txt => driver-api/usb/anchors.rst} | 36 ++++++++++++----------
Documentation/driver-api/usb/index.rst | 1 +
2 files changed, 21 insertions(+), 16 deletions(-)
rename Documentation/{usb/anchors.txt => driver-api/usb/anchors.rst} (75%)
diff --git a/Documentation/usb/anchors.txt b/Documentation/driver-api/usb/anchors.rst
similarity index 75%
rename from Documentation/usb/anchors.txt
rename to Documentation/driver-api/usb/anchors.rst
index fe6a99a32bbd..4b248e691bd6 100644
--- a/Documentation/usb/anchors.txt
+++ b/Documentation/driver-api/usb/anchors.rst
@@ -1,3 +1,6 @@
+USB Anchors
+~~~~~~~~~~~
+
What is anchor?
===============
@@ -13,7 +16,7 @@ Allocation and Initialisation
=============================
There's no API to allocate an anchor. It is simply declared
-as struct usb_anchor. init_usb_anchor() must be called to
+as struct usb_anchor. :c:func:`init_usb_anchor` must be called to
initialise the data structure.
Deallocation
@@ -26,52 +29,53 @@ Association and disassociation of URBs with anchors
===================================================
An association of URBs to an anchor is made by an explicit
-call to usb_anchor_urb(). The association is maintained until
+call to :c:func:`usb_anchor_urb`. The association is maintained until
an URB is finished by (successful) completion. Thus disassociation
is automatic. A function is provided to forcibly finish (kill)
all URBs associated with an anchor.
-Furthermore, disassociation can be made with usb_unanchor_urb()
+Furthermore, disassociation can be made with :c:func:`usb_unanchor_urb`
Operations on multitudes of URBs
================================
-usb_kill_anchored_urbs()
-------------------------
+:c:func:`usb_kill_anchored_urbs`
+--------------------------------
This function kills all URBs associated with an anchor. The URBs
are called in the reverse temporal order they were submitted.
This way no data can be reordered.
-usb_unlink_anchored_urbs()
---------------------------
+:c:func:`usb_unlink_anchored_urbs`
+----------------------------------
+
This function unlinks all URBs associated with an anchor. The URBs
are processed in the reverse temporal order they were submitted.
-This is similar to usb_kill_anchored_urbs(), but it will not sleep.
+This is similar to :c:func:`usb_kill_anchored_urbs`, but it will not sleep.
Therefore no guarantee is made that the URBs have been unlinked when
the call returns. They may be unlinked later but will be unlinked in
finite time.
-usb_scuttle_anchored_urbs()
----------------------------
+:c:func:`usb_scuttle_anchored_urbs`
+-----------------------------------
All URBs of an anchor are unanchored en masse.
-usb_wait_anchor_empty_timeout()
--------------------------------
+:c:func:`usb_wait_anchor_empty_timeout`
+---------------------------------------
This function waits for all URBs associated with an anchor to finish
or a timeout, whichever comes first. Its return value will tell you
whether the timeout was reached.
-usb_anchor_empty()
-------------------
+:c:func:`usb_anchor_empty`
+--------------------------
Returns true if no URBs are associated with an anchor. Locking
is the caller's responsibility.
-usb_get_from_anchor()
----------------------
+:c:func:`usb_get_from_anchor`
+-----------------------------
Returns the oldest anchored URB of an anchor. The URB is unanchored
and returned with a reference. As you may mix URBs to several
diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst
index cf2fa2e8d236..5dfb04b2d730 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -6,6 +6,7 @@ Linux USB API
usb
gadget
+ anchors
writing_usb_driver
writing_musb_glue_layer
--
2.9.3
^ permalink raw reply related [flat|nested] 52+ messages in thread* [PATCH 08/22] usb/bulk-streams.txt: convert to ReST and add to driver-api book
2017-03-29 18:54 [PATCH 01/22] driver-api/basics.rst: add device table header Mauro Carvalho Chehab
` (5 preceding siblings ...)
2017-03-29 18:54 ` [PATCH 07/22] usb/anchors.txt: convert to ReST and add to driver-api book Mauro Carvalho Chehab
@ 2017-03-29 18:54 ` Mauro Carvalho Chehab
2017-03-29 18:54 ` [PATCH 09/22] usb/callbacks.txt: " Mauro Carvalho Chehab
` (14 subsequent siblings)
21 siblings, 0 replies; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-29 18:54 UTC (permalink / raw)
To: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, John Youn,
linux-usb, linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab
This document describe some USB core functions. Add it to the
driver-api book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
.../bulk-streams.txt => driver-api/usb/bulk-streams.rst} | 13 +++++++++----
Documentation/driver-api/usb/index.rst | 1 +
2 files changed, 10 insertions(+), 4 deletions(-)
rename Documentation/{usb/bulk-streams.txt => driver-api/usb/bulk-streams.rst} (94%)
diff --git a/Documentation/usb/bulk-streams.txt b/Documentation/driver-api/usb/bulk-streams.rst
similarity index 94%
rename from Documentation/usb/bulk-streams.txt
rename to Documentation/driver-api/usb/bulk-streams.rst
index ffc02021863e..99b515babdeb 100644
--- a/Documentation/usb/bulk-streams.txt
+++ b/Documentation/driver-api/usb/bulk-streams.rst
@@ -1,3 +1,6 @@
+USB bulk streams
+~~~~~~~~~~~~~~~~
+
Background
==========
@@ -25,7 +28,9 @@ time.
Driver implications
===================
-int usb_alloc_streams(struct usb_interface *interface,
+::
+
+ int usb_alloc_streams(struct usb_interface *interface,
struct usb_host_endpoint **eps, unsigned int num_eps,
unsigned int num_streams, gfp_t mem_flags);
@@ -53,7 +58,7 @@ controller driver, and may change in the future.
Picking new Stream IDs to use
-============================
+=============================
Stream ID 0 is reserved, and should not be used to communicate with devices. If
usb_alloc_streams() returns with a value of N, you may use streams 1 though N.
@@ -68,9 +73,9 @@ Clean up
========
If a driver wishes to stop using streams to communicate with the device, it
-should call
+should call::
-void usb_free_streams(struct usb_interface *interface,
+ void usb_free_streams(struct usb_interface *interface,
struct usb_host_endpoint **eps, unsigned int num_eps,
gfp_t mem_flags);
diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst
index 5dfb04b2d730..6fe7611f7332 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -7,6 +7,7 @@ Linux USB API
usb
gadget
anchors
+ bulk-streams
writing_usb_driver
writing_musb_glue_layer
--
2.9.3
^ permalink raw reply related [flat|nested] 52+ messages in thread* [PATCH 09/22] usb/callbacks.txt: convert to ReST and add to driver-api book
2017-03-29 18:54 [PATCH 01/22] driver-api/basics.rst: add device table header Mauro Carvalho Chehab
` (6 preceding siblings ...)
2017-03-29 18:54 ` [PATCH 08/22] usb/bulk-streams.txt: " Mauro Carvalho Chehab
@ 2017-03-29 18:54 ` Mauro Carvalho Chehab
2017-03-29 18:54 ` [PATCH 10/22] usb/power-management.txt: " Mauro Carvalho Chehab
` (13 subsequent siblings)
21 siblings, 0 replies; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-29 18:54 UTC (permalink / raw)
To: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, John Youn,
linux-usb, linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab
This document describe some USB core functions. Add it to the
driver-api book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
.../callbacks.txt => driver-api/usb/callbacks.rst} | 61 +++++++++++++++-------
Documentation/driver-api/usb/index.rst | 1 +
2 files changed, 43 insertions(+), 19 deletions(-)
rename Documentation/{usb/callbacks.txt => driver-api/usb/callbacks.rst} (78%)
diff --git a/Documentation/usb/callbacks.txt b/Documentation/driver-api/usb/callbacks.rst
similarity index 78%
rename from Documentation/usb/callbacks.txt
rename to Documentation/driver-api/usb/callbacks.rst
index 9e85846bdb98..93a8d53e27e7 100644
--- a/Documentation/usb/callbacks.txt
+++ b/Documentation/driver-api/usb/callbacks.rst
@@ -1,3 +1,6 @@
+USB core callbacks
+~~~~~~~~~~~~~~~~~~
+
What callbacks will usbcore do?
===============================
@@ -11,30 +14,42 @@ The callbacks defined in the driver structure are:
1. Hotplugging callbacks:
- * @probe: Called to see if the driver is willing to manage a particular
- * interface on a device.
- * @disconnect: Called when the interface is no longer accessible, usually
- * because its device has been (or is being) disconnected or the
- * driver module is being unloaded.
+ - @probe:
+ Called to see if the driver is willing to manage a particular
+ interface on a device.
+
+ - @disconnect:
+ Called when the interface is no longer accessible, usually
+ because its device has been (or is being) disconnected or the
+ driver module is being unloaded.
2. Odd backdoor through usbfs:
- * @ioctl: Used for drivers that want to talk to userspace through
- * the "usbfs" filesystem. This lets devices provide ways to
- * expose information to user space regardless of where they
- * do (or don't) show up otherwise in the filesystem.
+ - @ioctl:
+ Used for drivers that want to talk to userspace through
+ the "usbfs" filesystem. This lets devices provide ways to
+ expose information to user space regardless of where they
+ do (or don't) show up otherwise in the filesystem.
3. Power management (PM) callbacks:
- * @suspend: Called when the device is going to be suspended.
- * @resume: Called when the device is being resumed.
- * @reset_resume: Called when the suspended device has been reset instead
- * of being resumed.
+ - @suspend:
+ Called when the device is going to be suspended.
+
+ - @resume:
+ Called when the device is being resumed.
+
+ - @reset_resume:
+ Called when the suspended device has been reset instead
+ of being resumed.
4. Device level operations:
- * @pre_reset: Called when the device is about to be reset.
- * @post_reset: Called after the device has been reset
+ - @pre_reset:
+ Called when the device is about to be reset.
+
+ - @post_reset:
+ Called after the device has been reset
The ioctl interface (2) should be used only if you have a very good
reason. Sysfs is preferred these days. The PM callbacks are covered
@@ -58,7 +73,9 @@ an interface. A driver's bond to an interface is exclusive.
The probe() callback
--------------------
-int (*probe) (struct usb_interface *intf,
+::
+
+ int (*probe) (struct usb_interface *intf,
const struct usb_device_id *id);
Accept or decline an interface. If you accept the device return 0,
@@ -75,7 +92,9 @@ initialisation that doesn't take too long is a good idea here.
The disconnect() callback
-------------------------
-void (*disconnect) (struct usb_interface *intf);
+::
+
+ void (*disconnect) (struct usb_interface *intf);
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
@@ -93,7 +112,9 @@ Device level callbacks
pre_reset
---------
-int (*pre_reset)(struct usb_interface *intf);
+::
+
+ int (*pre_reset)(struct usb_interface *intf);
A driver or user space is triggering a reset on the device which
contains the interface passed as an argument. Cease IO, wait for all
@@ -107,7 +128,9 @@ are in atomic context.
post_reset
----------
-int (*post_reset)(struct usb_interface *intf);
+::
+
+ int (*post_reset)(struct usb_interface *intf);
The reset has completed. Restore any saved device state and begin
using the device again.
diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst
index 6fe7611f7332..441c5dacdf27 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -8,6 +8,7 @@ Linux USB API
gadget
anchors
bulk-streams
+ callbacks
writing_usb_driver
writing_musb_glue_layer
--
2.9.3
^ permalink raw reply related [flat|nested] 52+ messages in thread* [PATCH 10/22] usb/power-management.txt: convert to ReST and add to driver-api book
2017-03-29 18:54 [PATCH 01/22] driver-api/basics.rst: add device table header Mauro Carvalho Chehab
` (7 preceding siblings ...)
2017-03-29 18:54 ` [PATCH 09/22] usb/callbacks.txt: " Mauro Carvalho Chehab
@ 2017-03-29 18:54 ` Mauro Carvalho Chehab
2017-03-29 18:54 ` [PATCH 11/22] usb/dma.txt: " Mauro Carvalho Chehab
` (12 subsequent siblings)
21 siblings, 0 replies; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-29 18:54 UTC (permalink / raw)
To: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, John Youn,
linux-usb, linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab, Masanari Iida
This document describe some USB core functions. Add it to the
driver-api book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/driver-api/usb/index.rst | 1 +
.../usb/power-management.rst} | 403 +++++++++++----------
2 files changed, 214 insertions(+), 190 deletions(-)
rename Documentation/{usb/power-management.txt => driver-api/usb/power-management.rst} (69%)
diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst
index 441c5dacdf27..23c76c17fc19 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -9,6 +9,7 @@ Linux USB API
anchors
bulk-streams
callbacks
+ power-management
writing_usb_driver
writing_musb_glue_layer
diff --git a/Documentation/usb/power-management.txt b/Documentation/driver-api/usb/power-management.rst
similarity index 69%
rename from Documentation/usb/power-management.txt
rename to Documentation/driver-api/usb/power-management.rst
index 00e706997130..7c547d6b8372 100644
--- a/Documentation/usb/power-management.txt
+++ b/Documentation/driver-api/usb/power-management.rst
@@ -1,10 +1,13 @@
- Power Management for USB
+.. _usb-power-management:
- Alan Stern <stern@rowland.harvard.edu>
+Power Management for USB
+~~~~~~~~~~~~~~~~~~~~~~~~
- Last-updated: February 2014
+Alan Stern <stern@rowland.harvard.edu>
+Last-updated: February 2014
+..
Contents:
---------
* What is Power Management?
@@ -25,14 +28,14 @@
* Suggested Userspace Port Power Policy
- What is Power Management?
- -------------------------
+What is Power Management?
+-------------------------
Power Management (PM) is the practice of saving energy by suspending
parts of a computer system when they aren't being used. While a
-component is "suspended" it is in a nonfunctional low-power state; it
+component is ``suspended`` it is in a nonfunctional low-power state; it
might even be turned off completely. A suspended component can be
-"resumed" (returned to a functional full-power state) when the kernel
+``resumed`` (returned to a functional full-power state) when the kernel
needs to use it. (There also are forms of PM in which components are
placed in a less functional but still usable state instead of being
suspended; an example would be reducing the CPU's clock rate. This
@@ -44,22 +47,25 @@ device is turned off while the system as a whole remains running, we
call it a "dynamic suspend" (also known as a "runtime suspend" or
"selective suspend"). This document concentrates mostly on how
dynamic PM is implemented in the USB subsystem, although system PM is
-covered to some extent (see Documentation/power/*.txt for more
+covered to some extent (see ``Documentation/power/*.txt`` for more
information about system PM).
-System PM support is present only if the kernel was built with CONFIG_SUSPEND
-or CONFIG_HIBERNATION enabled. Dynamic PM support for USB is present whenever
-the kernel was built with CONFIG_PM enabled.
+System PM support is present only if the kernel was built with
+``CONFIG_SUSPEND`` or ``CONFIG_HIBERNATION`` enabled. Dynamic PM support
+
+for USB is present whenever
+the kernel was built with ``CONFIG_PM`` enabled.
[Historically, dynamic PM support for USB was present only if the
-kernel had been built with CONFIG_USB_SUSPEND enabled (which depended on
-CONFIG_PM_RUNTIME). Starting with the 3.10 kernel release, dynamic PM support
-for USB was present whenever the kernel was built with CONFIG_PM_RUNTIME
-enabled. The CONFIG_USB_SUSPEND option had been eliminated.]
+kernel had been built with ``CONFIG_USB_SUSPEND`` enabled (which depended on
+``CONFIG_PM_RUNTIME``). Starting with the 3.10 kernel release, dynamic PM
+support for USB was present whenever the kernel was built with
+``CONFIG_PM_RUNTIME`` enabled. The ``CONFIG_USB_SUSPEND`` option had been
+eliminated.]
- What is Remote Wakeup?
- ----------------------
+What is Remote Wakeup?
+----------------------
When a device has been suspended, it generally doesn't resume until
the computer tells it to. Likewise, if the entire computer has been
@@ -76,8 +82,8 @@ event. Examples include a suspended keyboard resuming when a key is
pressed, or a suspended USB hub resuming when a device is plugged in.
- When is a USB device idle?
- --------------------------
+When is a USB device idle?
+--------------------------
A device is idle whenever the kernel thinks it's not busy doing
anything important and thus is a candidate for being suspended. The
@@ -92,11 +98,11 @@ If a USB device has no driver, its usbfs file isn't open, and it isn't
being accessed through sysfs, then it definitely is idle.
- Forms of dynamic PM
- -------------------
+Forms of dynamic PM
+-------------------
Dynamic suspends occur when the kernel decides to suspend an idle
-device. This is called "autosuspend" for short. In general, a device
+device. This is called ``autosuspend`` for short. In general, a device
won't be autosuspended unless it has been idle for some minimum period
of time, the so-called idle-delay time.
@@ -125,51 +131,51 @@ all dynamic suspend events are internal; external agents are not
allowed to issue dynamic suspends.
- The user interface for dynamic PM
- ---------------------------------
+The user interface for dynamic PM
+---------------------------------
-The user interface for controlling dynamic PM is located in the power/
+The user interface for controlling dynamic PM is located in the ``power/``
subdirectory of each USB device's sysfs directory, that is, in
-/sys/bus/usb/devices/.../power/ where "..." is the device's ID. The
+``/sys/bus/usb/devices/.../power/`` where "..." is the device's ID. The
relevant attribute files are: wakeup, control, and
-autosuspend_delay_ms. (There may also be a file named "level"; this
+``autosuspend_delay_ms``. (There may also be a file named ``level``; this
file was deprecated as of the 2.6.35 kernel and replaced by the
-"control" file. In 2.6.38 the "autosuspend" file will be deprecated
-and replaced by the "autosuspend_delay_ms" file. The only difference
+``control`` file. In 2.6.38 the ``autosuspend`` file will be deprecated
+and replaced by the ``autosuspend_delay_ms`` file. The only difference
is that the newer file expresses the delay in milliseconds whereas the
older file uses seconds. Confusingly, both files are present in 2.6.37
-but only "autosuspend" works.)
+but only ``autosuspend`` works.)
- power/wakeup
+ ``power/wakeup``
This file is empty if the device does not support
remote wakeup. Otherwise the file contains either the
- word "enabled" or the word "disabled", and you can
+ word ``enabled`` or the word ``disabled``, and you can
write those words to the file. The setting determines
whether or not remote wakeup will be enabled when the
device is next suspended. (If the setting is changed
while the device is suspended, the change won't take
effect until the following suspend.)
- power/control
+ ``power/control``
- This file contains one of two words: "on" or "auto".
+ This file contains one of two words: ``on`` or ``auto``.
You can write those words to the file to change the
device's setting.
- "on" means that the device should be resumed and
- autosuspend is not allowed. (Of course, system
- suspends are still allowed.)
+ - ``on`` means that the device should be resumed and
+ autosuspend is not allowed. (Of course, system
+ suspends are still allowed.)
- "auto" is the normal state in which the kernel is
- allowed to autosuspend and autoresume the device.
+ - ``auto`` is the normal state in which the kernel is
+ allowed to autosuspend and autoresume the device.
(In kernels up to 2.6.32, you could also specify
- "suspend", meaning that the device should remain
+ ``suspend``, meaning that the device should remain
suspended and autoresume was not allowed. This
setting is no longer supported.)
- power/autosuspend_delay_ms
+ ``power/autosuspend_delay_ms``
This file contains an integer value, which is the
number of milliseconds the device should remain idle
@@ -180,31 +186,31 @@ but only "autosuspend" works.)
number to the file to change the autosuspend
idle-delay time.
-Writing "-1" to power/autosuspend_delay_ms and writing "on" to
-power/control do essentially the same thing -- they both prevent the
+Writing ``-1`` to ``power/autosuspend_delay_ms`` and writing ``on`` to
+``power/control`` do essentially the same thing -- they both prevent the
device from being autosuspended. Yes, this is a redundancy in the
API.
-(In 2.6.21 writing "0" to power/autosuspend would prevent the device
+(In 2.6.21 writing ``0`` to ``power/autosuspend`` would prevent the device
from being autosuspended; the behavior was changed in 2.6.22. The
-power/autosuspend attribute did not exist prior to 2.6.21, and the
-power/level attribute did not exist prior to 2.6.22. power/control
-was added in 2.6.34, and power/autosuspend_delay_ms was added in
+``power/autosuspend`` attribute did not exist prior to 2.6.21, and the
+``power/level`` attribute did not exist prior to 2.6.22. ``power/control``
+was added in 2.6.34, and ``power/autosuspend_delay_ms`` was added in
2.6.37 but did not become functional until 2.6.38.)
- Changing the default idle-delay time
- ------------------------------------
+Changing the default idle-delay time
+------------------------------------
The default autosuspend idle-delay time (in seconds) is controlled by
a module parameter in usbcore. You can specify the value when usbcore
is loaded. For example, to set it to 5 seconds instead of 2 you would
-do:
+do::
modprobe usbcore autosuspend=5
Equivalently, you could add to a configuration file in /etc/modprobe.d
-a line saying:
+a line saying::
options usbcore autosuspend=5
@@ -214,14 +220,14 @@ image. To alter the parameter value you would have to rebuild that
image.
If usbcore is compiled into the kernel rather than built as a loadable
-module, you can add
+module, you can add::
usbcore.autosuspend=5
to the kernel's boot command line.
Finally, the parameter value can be changed while the system is
-running. If you do:
+running. If you do::
echo 5 >/sys/module/usbcore/parameters/autosuspend
@@ -234,8 +240,8 @@ autosuspend of any USB device. This has the benefit of allowing you
then to enable autosuspend for selected devices.
- Warnings
- --------
+Warnings
+--------
The USB specification states that all USB devices must support power
management. Nevertheless, the sad fact is that many devices do not
@@ -246,7 +252,7 @@ among printers and scanners, but plenty of other types of device have
the same deficiency.
For this reason, by default the kernel disables autosuspend (the
-power/control attribute is initialized to "on") for all devices other
+``power/control`` attribute is initialized to ``on``) for all devices other
than hubs. Hubs, at least, appear to be reasonably well-behaved in
this regard.
@@ -284,30 +290,30 @@ device by suspending it at the wrong time. (Highly unlikely, but
possible.) Take care.
- The driver interface for Power Management
- -----------------------------------------
+The driver interface for Power Management
+-----------------------------------------
The requirements for a USB driver to support external power management
-are pretty modest; the driver need only define
+are pretty modest; the driver need only define::
.suspend
.resume
.reset_resume
-methods in its usb_driver structure, and the reset_resume method is
-optional. The methods' jobs are quite simple:
+methods in its :c:type:`usb_driver` structure, and the ``reset_resume`` method
+is optional. The methods' jobs are quite simple:
- The suspend method is called to warn the driver that the
+ - The ``suspend`` method is called to warn the driver that the
device is going to be suspended. If the driver returns a
negative error code, the suspend will be aborted. Normally
the driver will return 0, in which case it must cancel all
- outstanding URBs (usb_kill_urb()) and not submit any more.
+ outstanding URBs (:c:func:`usb_kill_urb`) and not submit any more.
- The resume method is called to tell the driver that the
+ - The ``resume`` method is called to tell the driver that the
device has been resumed and the driver can return to normal
operation. URBs may once more be submitted.
- The reset_resume method is called to tell the driver that
+ - The ``reset_resume`` method is called to tell the driver that
the device has been resumed and it also has been reset.
The driver should redo any necessary device initialization,
since the device has probably lost most or all of its state
@@ -315,22 +321,22 @@ optional. The methods' jobs are quite simple:
before the suspend).
If the device is disconnected or powered down while it is suspended,
-the disconnect method will be called instead of the resume or
-reset_resume method. This is also quite likely to happen when
+the ``disconnect`` method will be called instead of the ``resume`` or
+``reset_resume`` method. This is also quite likely to happen when
waking up from hibernation, as many systems do not maintain suspend
current to the USB host controllers during hibernation. (It's
possible to work around the hibernation-forces-disconnect problem by
using the USB Persist facility.)
-The reset_resume method is used by the USB Persist facility (see
-Documentation/usb/persist.txt) and it can also be used under certain
-circumstances when CONFIG_USB_PERSIST is not enabled. Currently, if a
+The ``reset_resume`` method is used by the USB Persist facility (see
+``Documentation/usb/persist.txt``) and it can also be used under certain
+circumstances when ``CONFIG_USB_PERSIST`` is not enabled. Currently, if a
device is reset during a resume and the driver does not have a
-reset_resume method, the driver won't receive any notification about
-the resume. Later kernels will call the driver's disconnect method;
+``reset_resume`` method, the driver won't receive any notification about
+the resume. Later kernels will call the driver's ``disconnect`` method;
2.6.23 doesn't do this.
-USB drivers are bound to interfaces, so their suspend and resume
+USB drivers are bound to interfaces, so their ``suspend`` and ``resume``
methods get called when the interfaces are suspended or resumed. In
principle one might want to suspend some interfaces on a device (i.e.,
force the drivers for those interface to stop all activity) without
@@ -341,15 +347,15 @@ to suspend or resume some but not all of a device's interfaces. The
closest you can come is to unbind the interfaces' drivers.
- The driver interface for autosuspend and autoresume
- ---------------------------------------------------
+The driver interface for autosuspend and autoresume
+---------------------------------------------------
To support autosuspend and autoresume, a driver should implement all
three of the methods listed above. In addition, a driver indicates
-that it supports autosuspend by setting the .supports_autosuspend flag
+that it supports autosuspend by setting the ``.supports_autosuspend`` flag
in its usb_driver structure. It is then responsible for informing the
USB core whenever one of its interfaces becomes busy or idle. The
-driver does so by calling these six functions:
+driver does so by calling these six functions::
int usb_autopm_get_interface(struct usb_interface *intf);
void usb_autopm_put_interface(struct usb_interface *intf);
@@ -368,41 +374,41 @@ autosuspend the device.
Drivers need not be concerned about balancing changes to the usage
counter; the USB core will undo any remaining "get"s when a driver
is unbound from its interface. As a corollary, drivers must not call
-any of the usb_autopm_* functions after their disconnect() routine has
-returned.
+any of the ``usb_autopm_*`` functions after their ``disconnect``
+routine has returned.
Drivers using the async routines are responsible for their own
synchronization and mutual exclusion.
- usb_autopm_get_interface() increments the usage counter and
+ :c:func:`usb_autopm_get_interface` increments the usage counter and
does an autoresume if the device is suspended. If the
autoresume fails, the counter is decremented back.
- usb_autopm_put_interface() decrements the usage counter and
+ :c:func:`usb_autopm_put_interface` decrements the usage counter and
attempts an autosuspend if the new value is = 0.
- usb_autopm_get_interface_async() and
- usb_autopm_put_interface_async() do almost the same things as
+ :c:func:`usb_autopm_get_interface_async` and
+ :c:func:`usb_autopm_put_interface_async` do almost the same things as
their non-async counterparts. The big difference is that they
use a workqueue to do the resume or suspend part of their
jobs. As a result they can be called in an atomic context,
such as an URB's completion handler, but when they return the
device will generally not yet be in the desired state.
- usb_autopm_get_interface_no_resume() and
- usb_autopm_put_interface_no_suspend() merely increment or
+ :c:func:`usb_autopm_get_interface_no_resume` and
+ :c:func:`usb_autopm_put_interface_no_suspend` merely increment or
decrement the usage counter; they do not attempt to carry out
an autoresume or an autosuspend. Hence they can be called in
an atomic context.
The simplest usage pattern is that a driver calls
-usb_autopm_get_interface() in its open routine and
-usb_autopm_put_interface() in its close or release routine. But other
+:c:func:`usb_autopm_get_interface` in its open routine and
+:c:func:`usb_autopm_put_interface` in its close or release routine. But other
patterns are possible.
The autosuspend attempts mentioned above will often fail for one
-reason or another. For example, the power/control attribute might be
-set to "on", or another interface in the same device might not be
+reason or another. For example, the ``power/control`` attribute might be
+set to ``on``, or another interface in the same device might not be
idle. This is perfectly normal. If the reason for failure was that
the device hasn't been idle for long enough, a timer is scheduled to
carry out the operation automatically when the autosuspend idle-delay
@@ -413,37 +419,37 @@ the device is no longer present or operating properly. Unlike
autosuspend, there's no idle-delay for an autoresume.
- Other parts of the driver interface
- -----------------------------------
+Other parts of the driver interface
+-----------------------------------
-Drivers can enable autosuspend for their devices by calling
+Drivers can enable autosuspend for their devices by calling::
usb_enable_autosuspend(struct usb_device *udev);
-in their probe() routine, if they know that the device is capable of
+in their :c:func:`probe` routine, if they know that the device is capable of
suspending and resuming correctly. This is exactly equivalent to
-writing "auto" to the device's power/control attribute. Likewise,
-drivers can disable autosuspend by calling
+writing ``auto`` to the device's ``power/control`` attribute. Likewise,
+drivers can disable autosuspend by calling::
usb_disable_autosuspend(struct usb_device *udev);
-This is exactly the same as writing "on" to the power/control attribute.
+This is exactly the same as writing ``on`` to the ``power/control`` attribute.
Sometimes a driver needs to make sure that remote wakeup is enabled
during autosuspend. For example, there's not much point
autosuspending a keyboard if the user can't cause the keyboard to do a
remote wakeup by typing on it. If the driver sets
-intf->needs_remote_wakeup to 1, the kernel won't autosuspend the
+``intf->needs_remote_wakeup`` to 1, the kernel won't autosuspend the
device if remote wakeup isn't available. (If the device is already
autosuspended, though, setting this flag won't cause the kernel to
-autoresume it. Normally a driver would set this flag in its probe
+autoresume it. Normally a driver would set this flag in its ``probe``
method, at which time the device is guaranteed not to be
autosuspended.)
If a driver does its I/O asynchronously in interrupt context, it
-should call usb_autopm_get_interface_async() before starting output and
-usb_autopm_put_interface_async() when the output queue drains. When
-it receives an input event, it should call
+should call :c:func:`usb_autopm_get_interface_async` before starting output and
+:c:func:`usb_autopm_put_interface_async` when the output queue drains. When
+it receives an input event, it should call::
usb_mark_last_busy(struct usb_device *udev);
@@ -453,41 +459,41 @@ be pushed back. Many of the usb_autopm_* routines also make this call,
so drivers need to worry only when interrupt-driven input arrives.
Asynchronous operation is always subject to races. For example, a
-driver may call the usb_autopm_get_interface_async() routine at a time
+driver may call the :c:func:`usb_autopm_get_interface_async` routine at a time
when the core has just finished deciding the device has been idle for
-long enough but not yet gotten around to calling the driver's suspend
-method. The suspend method must be responsible for synchronizing with
+long enough but not yet gotten around to calling the driver's ``suspend``
+method. The ``suspend`` method must be responsible for synchronizing with
the I/O request routine and the URB completion handler; it should
cause autosuspends to fail with -EBUSY if the driver needs to use the
device.
External suspend calls should never be allowed to fail in this way,
only autosuspend calls. The driver can tell them apart by applying
-the PMSG_IS_AUTO() macro to the message argument to the suspend
+the :c:func:`PMSG_IS_AUTO` macro to the message argument to the ``suspend``
method; it will return True for internal PM events (autosuspend) and
False for external PM events.
- Mutual exclusion
- ----------------
+Mutual exclusion
+----------------
For external events -- but not necessarily for autosuspend or
autoresume -- the device semaphore (udev->dev.sem) will be held when a
-suspend or resume method is called. This implies that external
-suspend/resume events are mutually exclusive with calls to probe,
-disconnect, pre_reset, and post_reset; the USB core guarantees that
+``suspend`` or ``resume`` method is called. This implies that external
+suspend/resume events are mutually exclusive with calls to ``probe``,
+``disconnect``, ``pre_reset``, and ``post_reset``; the USB core guarantees that
this is true of autosuspend/autoresume events as well.
If a driver wants to block all suspend/resume calls during some
critical section, the best way is to lock the device and call
-usb_autopm_get_interface() (and do the reverse at the end of the
+:c:func:`usb_autopm_get_interface` (and do the reverse at the end of the
critical section). Holding the device semaphore will block all
-external PM calls, and the usb_autopm_get_interface() will prevent any
+external PM calls, and the :c:func:`usb_autopm_get_interface` will prevent any
internal PM calls, even if it fails. (Exercise: Why?)
- Interaction between dynamic PM and system PM
- --------------------------------------------
+Interaction between dynamic PM and system PM
+--------------------------------------------
Dynamic power management and system power management can interact in
a couple of ways.
@@ -512,8 +518,8 @@ wakeup may fail and get lost. Which outcome occurs depends on timing
and on the hardware and firmware design.
- xHCI hardware link PM
- ---------------------
+xHCI hardware link PM
+---------------------
xHCI host controller provides hardware link power management to usb2.0
(xHCI 1.0 feature) and usb3.0 devices which support link PM. By
@@ -522,11 +528,11 @@ lower power state(L1 for usb2.0 devices, or U1/U2 for usb3.0 devices),
which state device can enter and resume very quickly.
The user interface for controlling hardware LPM is located in the
-power/ subdirectory of each USB device's sysfs directory, that is, in
-/sys/bus/usb/devices/.../power/ where "..." is the device's ID. The
-relevant attribute files are usb2_hardware_lpm and usb3_hardware_lpm.
+``power/`` subdirectory of each USB device's sysfs directory, that is, in
+``/sys/bus/usb/devices/.../power/`` where "..." is the device's ID. The
+relevant attribute files are ``usb2_hardware_lpm`` and ``usb3_hardware_lpm``.
- power/usb2_hardware_lpm
+ ``power/usb2_hardware_lpm``
When a USB2 device which support LPM is plugged to a
xHCI host root hub which support software LPM, the
@@ -537,8 +543,8 @@ relevant attribute files are usb2_hardware_lpm and usb3_hardware_lpm.
can write y/Y/1 or n/N/0 to the file to enable/disable
USB2 hardware LPM manually. This is for test purpose mainly.
- power/usb3_hardware_lpm_u1
- power/usb3_hardware_lpm_u2
+ ``power/usb3_hardware_lpm_u1``
+ ``power/usb3_hardware_lpm_u2``
When a USB 3.0 lpm-capable device is plugged in to a
xHCI host which supports link PM, it will check if U1
@@ -550,29 +556,31 @@ relevant attribute files are usb2_hardware_lpm and usb3_hardware_lpm.
indicating whether or not USB3 hardware LPM U1 or U2
is enabled for the device.
- USB Port Power Control
- ----------------------
+USB Port Power Control
+----------------------
In addition to suspending endpoint devices and enabling hardware
controlled link power management, the USB subsystem also has the
capability to disable power to ports under some conditions. Power is
-controlled through Set/ClearPortFeature(PORT_POWER) requests to a hub.
+controlled through ``Set/ClearPortFeature(PORT_POWER)`` requests to a hub.
In the case of a root or platform-internal hub the host controller
-driver translates PORT_POWER requests into platform firmware (ACPI)
+driver translates ``PORT_POWER`` requests into platform firmware (ACPI)
method calls to set the port power state. For more background see the
-Linux Plumbers Conference 2012 slides [1] and video [2]:
+Linux Plumbers Conference 2012 slides [#f1]_ and video [#f2]_:
-Upon receiving a ClearPortFeature(PORT_POWER) request a USB port is
-logically off, and may trigger the actual loss of VBUS to the port [3].
+Upon receiving a ``ClearPortFeature(PORT_POWER)`` request a USB port is
+logically off, and may trigger the actual loss of VBUS to the port [#f3]_.
VBUS may be maintained in the case where a hub gangs multiple ports into
a shared power well causing power to remain until all ports in the gang
are turned off. VBUS may also be maintained by hub ports configured for
a charging application. In any event a logically off port will lose
connection with its device, not respond to hotplug events, and not
-respond to remote wakeup events*.
+respond to remote wakeup events.
-WARNING: turning off a port may result in the inability to hot add a device.
-Please see "User Interface for Port Power Control" for details.
+.. warning::
+
+ turning off a port may result in the inability to hot add a device.
+ Please see "User Interface for Port Power Control" for details.
As far as the effect on the device itself it is similar to what a device
goes through during system suspend, i.e. the power session is lost. Any
@@ -581,38 +589,49 @@ similarly affected by a port power cycle event. For this reason the
implementation shares the same device recovery path (and honors the same
quirks) as the system resume path for the hub.
-[1]: http://dl.dropbox.com/u/96820575/sarah-sharp-lpt-port-power-off2-mini.pdf
-[2]: http://linuxplumbers.ubicast.tv/videos/usb-port-power-off-kerneluserspace-api/
-[3]: USB 3.1 Section 10.12
-* wakeup note: if a device is configured to send wakeup events the port
+.. [#f1]
+
+ http://dl.dropbox.com/u/96820575/sarah-sharp-lpt-port-power-off2-mini.pdf
+
+.. [#f2]
+
+ http://linuxplumbers.ubicast.tv/videos/usb-port-power-off-kerneluserspace-api/
+
+.. [#f3]
+
+ USB 3.1 Section 10.12
+
+ wakeup note: if a device is configured to send wakeup events the port
power control implementation will block poweroff attempts on that
port.
- User Interface for Port Power Control
- -------------------------------------
+User Interface for Port Power Control
+-------------------------------------
The port power control mechanism uses the PM runtime system. Poweroff is
-requested by clearing the power/pm_qos_no_power_off flag of the port device
+requested by clearing the ``power/pm_qos_no_power_off`` flag of the port device
(defaults to 1). If the port is disconnected it will immediately receive a
-ClearPortFeature(PORT_POWER) request. Otherwise, it will honor the pm runtime
-rules and require the attached child device and all descendants to be suspended.
-This mechanism is dependent on the hub advertising port power switching in its
-hub descriptor (wHubCharacteristics logical power switching mode field).
+``ClearPortFeature(PORT_POWER)`` request. Otherwise, it will honor the pm
+runtime rules and require the attached child device and all descendants to be
+suspended. This mechanism is dependent on the hub advertising port power
+switching in its hub descriptor (wHubCharacteristics logical power switching
+mode field).
Note, some interface devices/drivers do not support autosuspend. Userspace may
-need to unbind the interface drivers before the usb_device will suspend. An
-unbound interface device is suspended by default. When unbinding, be careful
-to unbind interface drivers, not the driver of the parent usb device. Also,
-leave hub interface drivers bound. If the driver for the usb device (not
-interface) is unbound the kernel is no longer able to resume the device. If a
-hub interface driver is unbound, control of its child ports is lost and all
-attached child-devices will disconnect. A good rule of thumb is that if the
-'driver/module' link for a device points to /sys/module/usbcore then unbinding
-it will interfere with port power control.
+need to unbind the interface drivers before the :c:type:`usb_device` will
+suspend. An unbound interface device is suspended by default. When unbinding,
+be careful to unbind interface drivers, not the driver of the parent usb
+device. Also, leave hub interface drivers bound. If the driver for the usb
+device (not interface) is unbound the kernel is no longer able to resume the
+device. If a hub interface driver is unbound, control of its child ports is
+lost and all attached child-devices will disconnect. A good rule of thumb is
+that if the 'driver/module' link for a device points to
+``/sys/module/usbcore`` then unbinding it will interfere with port power
+control.
Example of the relevant files for port power control. Note, in this example
-these files are relative to a usb hub device (prefix).
+these files are relative to a usb hub device (prefix)::
prefix=/sys/devices/pci0000:00/0000:00:14.0/usb3/3-1
@@ -631,10 +650,10 @@ these files are relative to a usb hub device (prefix).
In addition to these files some ports may have a 'peer' link to a port on
another hub. The expectation is that all superspeed ports have a
-hi-speed peer.
+hi-speed peer::
-$prefix/3-1:1.0/3-1-port1/peer -> ../../../../usb2/2-1/2-1:1.0/2-1-port1
-../../../../usb2/2-1/2-1:1.0/2-1-port1/peer -> ../../../../usb3/3-1/3-1:1.0/3-1-port1
+ $prefix/3-1:1.0/3-1-port1/peer -> ../../../../usb2/2-1/2-1:1.0/2-1-port1
+ ../../../../usb2/2-1/2-1:1.0/2-1-port1/peer -> ../../../../usb3/3-1/3-1:1.0/3-1-port1
Distinct from 'companion ports', or 'ehci/xhci shared switchover ports'
peer ports are simply the hi-speed and superspeed interface pins that
@@ -645,24 +664,26 @@ While a superspeed port is powered off a device may downgrade its
connection and attempt to connect to the hi-speed pins. The
implementation takes steps to prevent this:
-1/ Port suspend is sequenced to guarantee that hi-speed ports are powered-off
+1. Port suspend is sequenced to guarantee that hi-speed ports are powered-off
before their superspeed peer is permitted to power-off. The implication is
- that the setting pm_qos_no_power_off to zero on a superspeed port may not cause
- the port to power-off until its highspeed peer has gone to its runtime suspend
- state. Userspace must take care to order the suspensions if it wants to
- guarantee that a superspeed port will power-off.
+ that the setting ``pm_qos_no_power_off`` to zero on a superspeed port may
+ not cause the port to power-off until its highspeed peer has gone to its
+ runtime suspend state. Userspace must take care to order the suspensions
+ if it wants to guarantee that a superspeed port will power-off.
-2/ Port resume is sequenced to force a superspeed port to power-on prior to its
+2. Port resume is sequenced to force a superspeed port to power-on prior to its
highspeed peer.
-3/ Port resume always triggers an attached child device to resume. After a
+3. Port resume always triggers an attached child device to resume. After a
power session is lost the device may have been removed, or need reset.
Resuming the child device when the parent port regains power resolves those
- states and clamps the maximum port power cycle frequency at the rate the child
- device can suspend (autosuspend-delay) and resume (reset-resume latency).
+ states and clamps the maximum port power cycle frequency at the rate the
+ child device can suspend (autosuspend-delay) and resume (reset-resume
+ latency).
Sysfs files relevant for port power control:
- <hubdev-portX>/power/pm_qos_no_power_off:
+
+ ``<hubdev-portX>/power/pm_qos_no_power_off``:
This writable flag controls the state of an idle port.
Once all children and descendants have suspended the
port may suspend/poweroff provided that
@@ -670,24 +691,24 @@ Sysfs files relevant for port power control:
'1' the port will remain active/powered regardless of
the stats of descendants. Defaults to 1.
- <hubdev-portX>/power/runtime_status:
+ ``<hubdev-portX>/power/runtime_status``:
This file reflects whether the port is 'active' (power is on)
or 'suspended' (logically off). There is no indication to
userspace whether VBUS is still supplied.
- <hubdev-portX>/connect_type:
+ ``<hubdev-portX>/connect_type``:
An advisory read-only flag to userspace indicating the
location and connection type of the port. It returns
one of four values 'hotplug', 'hardwired', 'not used',
and 'unknown'. All values, besides unknown, are set by
platform firmware.
- "hotplug" indicates an externally connectable/visible
+ ``hotplug`` indicates an externally connectable/visible
port on the platform. Typically userspace would choose
to keep such a port powered to handle new device
connection events.
- "hardwired" refers to a port that is not visible but
+ ``hardwired`` refers to a port that is not visible but
connectable. Examples are internal ports for USB
bluetooth that can be disconnected via an external
switch or a port with a hardwired USB camera. It is
@@ -698,48 +719,50 @@ Sysfs files relevant for port power control:
powering off, or to activate the port prior to enabling
connection via a switch.
- "not used" refers to an internal port that is expected
+ ``not used`` refers to an internal port that is expected
to never have a device connected to it. These may be
empty internal ports, or ports that are not physically
exposed on a platform. Considered safe to be
powered-off at all times.
- "unknown" means platform firmware does not provide
+ ``unknown`` means platform firmware does not provide
information for this port. Most commonly refers to
external hub ports which should be considered 'hotplug'
for policy decisions.
- NOTE1: since we are relying on the BIOS to get this ACPI
- information correct, the USB port descriptions may be
- missing or wrong.
+ .. note::
- NOTE2: Take care in clearing pm_qos_no_power_off. Once
- power is off this port will
- not respond to new connect events.
+ - since we are relying on the BIOS to get this ACPI
+ information correct, the USB port descriptions may
+ be missing or wrong.
+
+ - Take care in clearing ``pm_qos_no_power_off``. Once
+ power is off this port will
+ not respond to new connect events.
Once a child device is attached additional constraints are
applied before the port is allowed to poweroff.
- <child>/power/control:
- Must be 'auto', and the port will not
- power down until <child>/power/runtime_status
+ ``<child>/power/control``:
+ Must be ``auto``, and the port will not
+ power down until ``<child>/power/runtime_status``
reflects the 'suspended' state. Default
value is controlled by child device driver.
- <child>/power/persist:
- This defaults to '1' for most devices and indicates if
+ ``<child>/power/persist``:
+ This defaults to ``1`` for most devices and indicates if
kernel can persist the device's configuration across a
power session loss (suspend / port-power event). When
- this value is '0' (quirky devices), port poweroff is
+ this value is ``0`` (quirky devices), port poweroff is
disabled.
- <child>/driver/unbind:
+ ``<child>/driver/unbind``:
Wakeup capable devices will block port poweroff. At
this time the only mechanism to clear the usb-internal
wakeup-capability for an interface device is to unbind
its driver.
-Summary of poweroff pre-requisite settings relative to a port device:
+Summary of poweroff pre-requisite settings relative to a port device::
echo 0 > power/pm_qos_no_power_off
echo 0 > peer/power/pm_qos_no_power_off # if it exists
@@ -747,14 +770,14 @@ Summary of poweroff pre-requisite settings relative to a port device:
echo auto > <child>/power/control
echo 1 > <child>/power/persist # this is the default value
- Suggested Userspace Port Power Policy
- -------------------------------------
+Suggested Userspace Port Power Policy
+-------------------------------------
As noted above userspace needs to be careful and deliberate about what
ports are enabled for poweroff.
The default configuration is that all ports start with
-power/pm_qos_no_power_off set to '1' causing ports to always remain
+``power/pm_qos_no_power_off`` set to ``1`` causing ports to always remain
active.
Given confidence in the platform firmware's description of the ports
@@ -764,7 +787,7 @@ done for 'hardwired' ports provided poweroff is coordinated with any
connection switch for the port.
A more aggressive userspace policy is to enable USB port power off for
-all ports (set <hubdev-portX>/power/pm_qos_no_power_off to '0') when
+all ports (set ``<hubdev-portX>/power/pm_qos_no_power_off`` to ``0``) when
some external factor indicates the user has stopped interacting with the
system. For example, a distro may want to enable power off all USB
ports when the screen blanks, and re-power them when the screen becomes
--
2.9.3
^ permalink raw reply related [flat|nested] 52+ messages in thread* [PATCH 11/22] usb/dma.txt: convert to ReST and add to driver-api book
2017-03-29 18:54 [PATCH 01/22] driver-api/basics.rst: add device table header Mauro Carvalho Chehab
` (8 preceding siblings ...)
2017-03-29 18:54 ` [PATCH 10/22] usb/power-management.txt: " Mauro Carvalho Chehab
@ 2017-03-29 18:54 ` Mauro Carvalho Chehab
2017-03-29 18:54 ` [PATCH 12/22] error-codes.rst: " Mauro Carvalho Chehab
` (11 subsequent siblings)
21 siblings, 0 replies; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-29 18:54 UTC (permalink / raw)
To: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, John Youn,
linux-usb, linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab
This document describe some USB core features. Add it to the
driver-api book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
.../{usb/dma.txt => driver-api/usb/dma.rst} | 51 ++++++++++++----------
Documentation/driver-api/usb/index.rst | 1 +
2 files changed, 28 insertions(+), 24 deletions(-)
rename Documentation/{usb/dma.txt => driver-api/usb/dma.rst} (79%)
diff --git a/Documentation/usb/dma.txt b/Documentation/driver-api/usb/dma.rst
similarity index 79%
rename from Documentation/usb/dma.txt
rename to Documentation/driver-api/usb/dma.rst
index 444651e70d95..59d5aee89e37 100644
--- a/Documentation/usb/dma.txt
+++ b/Documentation/driver-api/usb/dma.rst
@@ -1,16 +1,19 @@
+USB DMA
+~~~~~~~
+
In Linux 2.5 kernels (and later), USB device drivers have additional control
over how DMA may be used to perform I/O operations. The APIs are detailed
in the kernel usb programming guide (kerneldoc, from the source code).
-
-API OVERVIEW
+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
-the 2.4 (and earlier) kernels.
+``Documentation/DMA-API-HOWTO.txt``). That's how they've worked through
+the 2.4 (and earlier) kernels, or they can now be DMA-aware.
-OR: they can now be DMA-aware.
+DMA-aware usb drivers:
- New calls enable DMA-aware drivers, letting them allocate dma buffers and
manage dma mappings for existing dma-ready buffers (see below).
@@ -20,15 +23,15 @@ OR: they can now be DMA-aware.
drivers must not use it.)
- "usbcore" will map this DMA address, if a DMA-aware driver didn't do
- it first and set URB_NO_TRANSFER_DMA_MAP. HCDs
+ it first and set ``URB_NO_TRANSFER_DMA_MAP``. HCDs
don't manage dma mappings for URBs.
- There's a new "generic DMA API", parts of which are usable by USB device
drivers. Never use dma_set_mask() on any USB interface or device; that
would potentially break all devices sharing that bus.
-
-ELIMINATING COPIES
+Eliminating copies
+==================
It's good to avoid making CPUs copy data needlessly. The costs can add up,
and effects like cache-trashing can impose subtle penalties.
@@ -41,7 +44,7 @@ and effects like cache-trashing can impose subtle penalties.
For those specific cases, USB has primitives to allocate less expensive
memory. They work like kmalloc and kfree versions that give you the right
kind of addresses to store in urb->transfer_buffer and urb->transfer_dma.
- You'd also set URB_NO_TRANSFER_DMA_MAP in urb->transfer_flags:
+ You'd also set ``URB_NO_TRANSFER_DMA_MAP`` in urb->transfer_flags::
void *usb_alloc_coherent (struct usb_device *dev, size_t size,
int mem_flags, dma_addr_t *dma);
@@ -49,15 +52,15 @@ and effects like cache-trashing can impose subtle penalties.
void usb_free_coherent (struct usb_device *dev, size_t size,
void *addr, dma_addr_t dma);
- Most drivers should *NOT* be using these primitives; they don't need
+ Most drivers should **NOT** be using these primitives; they don't need
to use this type of memory ("dma-coherent"), and memory returned from
- kmalloc() will work just fine.
+ :c:func:`kmalloc` will work just fine.
The memory buffer returned is "dma-coherent"; sometimes you might need to
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/DMA-API-HOWTO.txt`` for definitions of "coherent" and
"streaming" DMA mappings.)
Asking for 1/Nth of a page (as well as asking for N pages) is reasonably
@@ -75,15 +78,15 @@ and effects like cache-trashing can impose subtle penalties.
way to expose these capabilities ... and in any case, HIGHMEM is mostly a
design wart specific to x86_32. So your best bet is to ensure you never
pass a highmem buffer into a USB driver. That's easy; it's the default
- behavior. Just don't override it; e.g. with NETIF_F_HIGHDMA.
+ behavior. Just don't override it; e.g. with ``NETIF_F_HIGHDMA``.
This may force your callers to do some bounce buffering, copying from
high memory to "normal" DMA memory. If you can come up with a good way
to fix this issue (for x86_32 machines with over 1 GByte of memory),
feel free to submit patches.
-
-WORKING WITH EXISTING BUFFERS
+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
@@ -92,7 +95,7 @@ of Documentation/DMA-API-HOWTO.txt, 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:
+ DMA transactions::
int usb_buffer_map_sg (struct usb_device *dev, unsigned pipe,
struct scatterlist *sg, int nents);
@@ -103,7 +106,7 @@ of Documentation/DMA-API-HOWTO.txt, titled "What memory is DMA-able?")
void usb_buffer_unmap_sg (struct usb_device *dev, unsigned pipe,
struct scatterlist *sg, int n_hw_ents);
- It's probably easier to use the new usb_sg_*() calls, which do the DMA
+ 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
@@ -112,10 +115,10 @@ of Documentation/DMA-API-HOWTO.txt, titled "What memory is DMA-able?")
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):
+ 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);
@@ -123,9 +126,9 @@ of Documentation/DMA-API-HOWTO.txt, titled "What memory is DMA-able?")
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.
+ 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
diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst
index 23c76c17fc19..d7610777784b 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -9,6 +9,7 @@ Linux USB API
anchors
bulk-streams
callbacks
+ dma
power-management
writing_usb_driver
writing_musb_glue_layer
--
2.9.3
^ permalink raw reply related [flat|nested] 52+ messages in thread* [PATCH 12/22] error-codes.rst: convert to ReST and add to driver-api book
2017-03-29 18:54 [PATCH 01/22] driver-api/basics.rst: add device table header Mauro Carvalho Chehab
` (9 preceding siblings ...)
2017-03-29 18:54 ` [PATCH 11/22] usb/dma.txt: " Mauro Carvalho Chehab
@ 2017-03-29 18:54 ` Mauro Carvalho Chehab
2017-03-29 18:54 ` [PATCH 13/22] usb/hotplug.txt: " Mauro Carvalho Chehab
` (10 subsequent siblings)
21 siblings, 0 replies; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-29 18:54 UTC (permalink / raw)
To: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, John Youn,
linux-usb, linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab
This document describe some USB core features. Add it to the
driver-api book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/driver-api/usb/error-codes.rst | 205 +++++++++++++++++++++++++++
Documentation/driver-api/usb/index.rst | 1 +
Documentation/usb/error-codes.txt | 175 -----------------------
3 files changed, 206 insertions(+), 175 deletions(-)
create mode 100644 Documentation/driver-api/usb/error-codes.rst
delete mode 100644 Documentation/usb/error-codes.txt
diff --git a/Documentation/driver-api/usb/error-codes.rst b/Documentation/driver-api/usb/error-codes.rst
new file mode 100644
index 000000000000..715cc35b29b0
--- /dev/null
+++ b/Documentation/driver-api/usb/error-codes.rst
@@ -0,0 +1,205 @@
+USB Error codes
+~~~~~~~~~~~~~~~
+
+Revised: 2004-Oct-21
+
+This is the documentation of (hopefully) all possible error codes (and
+their interpretation) that can be returned from usbcore.
+
+Some of them are returned by the Host Controller Drivers (HCDs), which
+device drivers only see through usbcore. As a rule, all the HCDs should
+behave the same except for transfer speed dependent behaviors and the
+way certain faults are reported.
+
+
+Error codes returned by :c:func:`usb_submit_urb`
+================================================
+
+Non-USB-specific:
+
+
+=============== ===============================================
+0 URB submission went fine
+
+``-ENOMEM`` no memory for allocation of internal structures
+=============== ===============================================
+
+USB-specific:
+
+======================= =======================================================
+``-EBUSY`` The URB is already active.
+
+``-ENODEV`` specified USB-device or bus doesn't exist
+
+``-ENOENT`` specified interface or endpoint does not exist or
+ is not enabled
+
+``-ENXIO`` host controller driver does not support queuing of
+ this type of urb. (treat as a host controller bug.)
+
+``-EINVAL`` a) Invalid transfer type specified (or not supported)
+ b) Invalid or unsupported periodic transfer interval
+ c) ISO: attempted to change transfer interval
+ d) ISO: ``number_of_packets`` is < 0
+ e) various other cases
+
+``-EXDEV`` ISO: ``URB_ISO_ASAP`` wasn't specified and all the
+ frames the URB would be scheduled in have already
+ expired.
+
+``-EFBIG`` Host controller driver can't schedule that many ISO
+ frames.
+
+``-EPIPE`` The pipe type specified in the URB doesn't match the
+ endpoint's actual type.
+
+``-EMSGSIZE`` (a) endpoint maxpacket size is zero; it is not usable
+ in the current interface altsetting.
+ (b) ISO packet is larger than the endpoint maxpacket.
+ (c) requested data transfer length is invalid: negative
+ or too large for the host controller.
+
+``-ENOSPC`` This request would overcommit the usb bandwidth reserved
+ for periodic transfers (interrupt, isochronous).
+
+``-ESHUTDOWN`` The device or host controller has been disabled due to
+ some problem that could not be worked around.
+
+``-EPERM`` Submission failed because ``urb->reject`` was set.
+
+``-EHOSTUNREACH`` URB was rejected because the device is suspended.
+
+``-ENOEXEC`` A control URB doesn't contain a Setup packet.
+======================= =======================================================
+
+Error codes returned by ``in urb->status`` or in ``iso_frame_desc[n].status`` (for ISO)
+=======================================================================================
+
+USB device drivers may only test urb status values in completion handlers.
+This is because otherwise there would be a race between HCDs updating
+these values on one CPU, and device drivers testing them on another CPU.
+
+A transfer's actual_length may be positive even when an error has been
+reported. That's because transfers often involve several packets, so that
+one or more packets could finish before an error stops further endpoint I/O.
+
+For isochronous URBs, the urb status value is non-zero only if the URB is
+unlinked, the device is removed, the host controller is disabled, or the total
+transferred length is less than the requested length and the
+``URB_SHORT_NOT_OK`` flag is set. Completion handlers for isochronous URBs
+should only see ``urb->status`` set to zero, ``-ENOENT``, ``-ECONNRESET``,
+``-ESHUTDOWN``, or ``-EREMOTEIO``. Individual frame descriptor status fields
+may report more status codes.
+
+
+=============================== ===============================================
+0 Transfer completed successfully
+
+``-ENOENT`` URB was synchronously unlinked by
+ :c:func:`usb_unlink_urb`
+
+``-EINPROGRESS`` URB still pending, no results yet
+ (That is, if drivers see this it's a bug.)
+
+``-EPROTO`` [#f1]_, [#f2]_ a) bitstuff error
+ b) no response packet received within the
+ prescribed bus turn-around time
+ c) unknown USB error
+
+``-EILSEQ`` [#f1]_, [#f2]_ a) CRC mismatch
+ b) no response packet received within the
+ prescribed bus turn-around time
+ c) unknown USB error
+
+ Note that often the controller hardware does
+ not distinguish among cases a), b), and c), so
+ a driver cannot tell whether there was a
+ protocol error, a failure to respond (often
+ caused by device disconnect), or some other
+ fault.
+
+``-ETIME`` [#f2]_ No response packet received within the
+ prescribed bus turn-around time. This error
+ may instead be reported as
+ ``-EPROTO`` or ``-EILSEQ``.
+
+``-ETIMEDOUT`` Synchronous USB message functions use this code
+ to indicate timeout expired before the transfer
+ completed, and no other error was reported
+ by HC.
+
+``-EPIPE`` [#f2]_ Endpoint stalled. For non-control endpoints,
+ reset this status with
+ :c:func:`usb_clear_halt`.
+
+``-ECOMM`` During an IN transfer, the host controller
+ received data from an endpoint faster than it
+ could be written to system memory
+
+``-ENOSR`` During an OUT transfer, the host controller
+ could not retrieve data from system memory fast
+ enough to keep up with the USB data rate
+
+``-EOVERFLOW`` [#f1]_ The amount of data returned by the endpoint was
+ greater than either the max packet size of the
+ endpoint or the remaining buffer size.
+ "Babble".
+
+``-EREMOTEIO`` The data read from the endpoint did not fill
+ the specified buffer, and ``URB_SHORT_NOT_OK``
+ was set in ``urb->transfer_flags``.
+
+``-ENODEV`` Device was removed. Often preceded by a burst
+ of other errors, since the hub driver doesn't
+ detect device removal events immediately.
+
+``-EXDEV`` ISO transfer only partially completed
+ (only set in ``iso_frame_desc[n].status``,
+ not ``urb->status``)
+
+``-EINVAL`` ISO madness, if this happens: Log off and
+ go home
+
+``-ECONNRESET`` URB was asynchronously unlinked by
+ :c:func:`usb_unlink_urb`
+
+``-ESHUTDOWN`` The device or host controller has been
+ disabled due to some problem that could not
+ be worked around, such as a physical
+ disconnect.
+=============================== ===============================================
+
+
+.. [#f1]
+
+ Error codes like ``-EPROTO``, ``-EILSEQ`` and ``-EOVERFLOW`` normally
+ indicate hardware problems such as bad devices (including firmware)
+ or cables.
+
+.. [#f2]
+
+ This is also one of several codes that different kinds of host
+ controller use to indicate a transfer has failed because of device
+ disconnect. In the interval before the hub driver starts disconnect
+ processing, devices may receive such fault reports for every request.
+
+
+
+Error codes returned by usbcore-functions
+=========================================
+
+.. note:: expect also other submit and transfer status codes
+
+:c:func:`usb_register`:
+
+======================= ===================================
+``-EINVAL`` error during registering new driver
+======================= ===================================
+
+``usb_get_*/usb_set_*()``,
+:c:func:`usb_control_msg`,
+:c:func:`usb_bulk_msg()`:
+
+======================= ==============================================
+``-ETIMEDOUT`` Timeout expired before the transfer completed.
+======================= ==============================================
diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst
index d7610777784b..1e2a0c54eb3d 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -11,6 +11,7 @@ Linux USB API
callbacks
dma
power-management
+ error-codes
writing_usb_driver
writing_musb_glue_layer
diff --git a/Documentation/usb/error-codes.txt b/Documentation/usb/error-codes.txt
deleted file mode 100644
index 9c3eb845ebe5..000000000000
--- a/Documentation/usb/error-codes.txt
+++ /dev/null
@@ -1,175 +0,0 @@
-Revised: 2004-Oct-21
-
-This is the documentation of (hopefully) all possible error codes (and
-their interpretation) that can be returned from usbcore.
-
-Some of them are returned by the Host Controller Drivers (HCDs), which
-device drivers only see through usbcore. As a rule, all the HCDs should
-behave the same except for transfer speed dependent behaviors and the
-way certain faults are reported.
-
-
-**************************************************************************
-* Error codes returned by usb_submit_urb *
-**************************************************************************
-
-Non-USB-specific:
-
-0 URB submission went fine
-
--ENOMEM no memory for allocation of internal structures
-
-USB-specific:
-
--EBUSY The URB is already active.
-
--ENODEV specified USB-device or bus doesn't exist
-
--ENOENT specified interface or endpoint does not exist or
- is not enabled
-
--ENXIO host controller driver does not support queuing of this type
- of urb. (treat as a host controller bug.)
-
--EINVAL a) Invalid transfer type specified (or not supported)
- b) Invalid or unsupported periodic transfer interval
- c) ISO: attempted to change transfer interval
- d) ISO: number_of_packets is < 0
- e) various other cases
-
--EXDEV ISO: URB_ISO_ASAP wasn't specified and all the frames
- the URB would be scheduled in have already expired.
-
--EFBIG Host controller driver can't schedule that many ISO frames.
-
--EPIPE The pipe type specified in the URB doesn't match the
- endpoint's actual type.
-
--EMSGSIZE (a) endpoint maxpacket size is zero; it is not usable
- in the current interface altsetting.
- (b) ISO packet is larger than the endpoint maxpacket.
- (c) requested data transfer length is invalid: negative
- or too large for the host controller.
-
--ENOSPC This request would overcommit the usb bandwidth reserved
- for periodic transfers (interrupt, isochronous).
-
--ESHUTDOWN The device or host controller has been disabled due to some
- problem that could not be worked around.
-
--EPERM Submission failed because urb->reject was set.
-
--EHOSTUNREACH URB was rejected because the device is suspended.
-
--ENOEXEC A control URB doesn't contain a Setup packet.
-
-
-**************************************************************************
-* Error codes returned by in urb->status *
-* or in iso_frame_desc[n].status (for ISO) *
-**************************************************************************
-
-USB device drivers may only test urb status values in completion handlers.
-This is because otherwise there would be a race between HCDs updating
-these values on one CPU, and device drivers testing them on another CPU.
-
-A transfer's actual_length may be positive even when an error has been
-reported. That's because transfers often involve several packets, so that
-one or more packets could finish before an error stops further endpoint I/O.
-
-For isochronous URBs, the urb status value is non-zero only if the URB is
-unlinked, the device is removed, the host controller is disabled, or the total
-transferred length is less than the requested length and the URB_SHORT_NOT_OK
-flag is set. Completion handlers for isochronous URBs should only see
-urb->status set to zero, -ENOENT, -ECONNRESET, -ESHUTDOWN, or -EREMOTEIO.
-Individual frame descriptor status fields may report more status codes.
-
-
-0 Transfer completed successfully
-
--ENOENT URB was synchronously unlinked by usb_unlink_urb
-
--EINPROGRESS URB still pending, no results yet
- (That is, if drivers see this it's a bug.)
-
--EPROTO (*, **) a) bitstuff error
- b) no response packet received within the
- prescribed bus turn-around time
- c) unknown USB error
-
--EILSEQ (*, **) a) CRC mismatch
- b) no response packet received within the
- prescribed bus turn-around time
- c) unknown USB error
-
- Note that often the controller hardware does not
- distinguish among cases a), b), and c), so a
- driver cannot tell whether there was a protocol
- error, a failure to respond (often caused by
- device disconnect), or some other fault.
-
--ETIME (**) No response packet received within the prescribed
- bus turn-around time. This error may instead be
- reported as -EPROTO or -EILSEQ.
-
--ETIMEDOUT Synchronous USB message functions use this code
- to indicate timeout expired before the transfer
- completed, and no other error was reported by HC.
-
--EPIPE (**) Endpoint stalled. For non-control endpoints,
- reset this status with usb_clear_halt().
-
--ECOMM During an IN transfer, the host controller
- received data from an endpoint faster than it
- could be written to system memory
-
--ENOSR During an OUT transfer, the host controller
- could not retrieve data from system memory fast
- enough to keep up with the USB data rate
-
--EOVERFLOW (*) The amount of data returned by the endpoint was
- greater than either the max packet size of the
- endpoint or the remaining buffer size. "Babble".
-
--EREMOTEIO The data read from the endpoint did not fill the
- specified buffer, and URB_SHORT_NOT_OK was set in
- urb->transfer_flags.
-
--ENODEV Device was removed. Often preceded by a burst of
- other errors, since the hub driver doesn't detect
- device removal events immediately.
-
--EXDEV ISO transfer only partially completed
- (only set in iso_frame_desc[n].status, not urb->status)
-
--EINVAL ISO madness, if this happens: Log off and go home
-
--ECONNRESET URB was asynchronously unlinked by usb_unlink_urb
-
--ESHUTDOWN The device or host controller has been disabled due
- to some problem that could not be worked around,
- such as a physical disconnect.
-
-
-(*) Error codes like -EPROTO, -EILSEQ and -EOVERFLOW normally indicate
-hardware problems such as bad devices (including firmware) or cables.
-
-(**) This is also one of several codes that different kinds of host
-controller use to indicate a transfer has failed because of device
-disconnect. In the interval before the hub driver starts disconnect
-processing, devices may receive such fault reports for every request.
-
-
-
-**************************************************************************
-* Error codes returned by usbcore-functions *
-* (expect also other submit and transfer status codes) *
-**************************************************************************
-
-usb_register():
--EINVAL error during registering new driver
-
-usb_get_*/usb_set_*():
-usb_control_msg():
-usb_bulk_msg():
--ETIMEDOUT Timeout expired before the transfer completed.
--
2.9.3
^ permalink raw reply related [flat|nested] 52+ messages in thread* [PATCH 13/22] usb/hotplug.txt: convert to ReST and add to driver-api book
2017-03-29 18:54 [PATCH 01/22] driver-api/basics.rst: add device table header Mauro Carvalho Chehab
` (10 preceding siblings ...)
2017-03-29 18:54 ` [PATCH 12/22] error-codes.rst: " Mauro Carvalho Chehab
@ 2017-03-29 18:54 ` Mauro Carvalho Chehab
2017-03-29 18:54 ` [PATCH 14/22] usb/persist.txt: " Mauro Carvalho Chehab
` (9 subsequent siblings)
21 siblings, 0 replies; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-29 18:54 UTC (permalink / raw)
To: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, John Youn,
linux-usb, linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab
This document describe some USB core features. Add it to the
driver-api book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
.../hotplug.txt => driver-api/usb/hotplug.rst} | 66 ++++++++++++----------
Documentation/driver-api/usb/index.rst | 1 +
2 files changed, 37 insertions(+), 30 deletions(-)
rename Documentation/{usb/hotplug.txt => driver-api/usb/hotplug.rst} (76%)
diff --git a/Documentation/usb/hotplug.txt b/Documentation/driver-api/usb/hotplug.rst
similarity index 76%
rename from Documentation/usb/hotplug.txt
rename to Documentation/driver-api/usb/hotplug.rst
index 5b243f315b2c..79663e653ca1 100644
--- a/Documentation/usb/hotplug.txt
+++ b/Documentation/driver-api/usb/hotplug.rst
@@ -1,4 +1,9 @@
-LINUX HOTPLUGGING
+USB hotplugging
+~~~~~~~~~~~~~~~
+
+Linux Hotplugging
+=================
+
In hotpluggable busses like USB (and Cardbus PCI), end-users plug devices
into the bus with power on. In most cases, users expect the devices to become
@@ -30,11 +35,11 @@ Because some of those actions rely on information about drivers (metadata)
that is currently available only when the drivers are dynamically linked,
you get the best hotplugging when you configure a highly modular system.
+Kernel Hotplug Helper (``/sbin/hotplug``)
+=========================================
-KERNEL HOTPLUG HELPER (/sbin/hotplug)
-
-There is a kernel parameter: /proc/sys/kernel/hotplug, which normally
-holds the pathname "/sbin/hotplug". That parameter names a program
+There is a kernel parameter: ``/proc/sys/kernel/hotplug``, which normally
+holds the pathname ``/sbin/hotplug``. That parameter names a program
which the kernel may invoke at various times.
The /sbin/hotplug program can be invoked by any subsystem as part of its
@@ -51,26 +56,26 @@ Hotplug software and other resources is available at:
Mailing list information is also available at that site.
---------------------------------------------------------------------------
+USB Policy Agent
+================
-
-USB POLICY AGENT
-
-The USB subsystem currently invokes /sbin/hotplug when USB devices
+The USB subsystem currently invokes ``/sbin/hotplug`` when USB devices
are added or removed from system. The invocation is done by the kernel
hub workqueue [hub_wq], or else as part of root hub initialization
(done by init, modprobe, kapmd, etc). Its single command line parameter
is the string "usb", and it passes these environment variables:
- ACTION ... "add", "remove"
- PRODUCT ... USB vendor, product, and version codes (hex)
- TYPE ... device class codes (decimal)
- INTERFACE ... interface 0 class codes (decimal)
+========== ============================================
+ACTION ``add``, ``remove``
+PRODUCT USB vendor, product, and version codes (hex)
+TYPE device class codes (decimal)
+INTERFACE interface 0 class codes (decimal)
+========== ============================================
If "usbdevfs" is configured, DEVICE and DEVFS are also passed. DEVICE is
the pathname of the device, and is useful for devices with multiple and/or
alternate interfaces that complicate driver selection. By design, USB
-hotplugging is independent of "usbdevfs": you can do most essential parts
+hotplugging is independent of ``usbdevfs``: you can do most essential parts
of USB device setup without using that filesystem, and without running a
user mode daemon to detect changes in system configuration.
@@ -79,19 +84,20 @@ modules, and can invoke driver-specific setup scripts. The newest ones
leverage USB module-init-tools support. Later agents might unload drivers.
-USB MODUTILS SUPPORT
+USB Modutils Support
+====================
-Current versions of module-init-tools will create a "modules.usbmap" file
-which contains the entries from each driver's MODULE_DEVICE_TABLE. Such
+Current versions of module-init-tools will create a ``modules.usbmap`` file
+which contains the entries from each driver's ``MODULE_DEVICE_TABLE``. Such
files can be used by various user mode policy agents to make sure all the
right driver modules get loaded, either at boot time or later.
-See <linux/usb.h> for full information about such table entries; or look
+See ``linux/usb.h`` for full information about such table entries; or look
at existing drivers. Each table entry describes one or more criteria to
be used when matching a driver to a device or class of devices. The
specific criteria are identified by bits set in "match_flags", paired
with field values. You can construct the criteria directly, or with
-macros such as these, and use driver_info to store more information.
+macros such as these, and use driver_info to store more information::
USB_DEVICE (vendorId, productId)
... matching devices with specified vendor and product ids
@@ -103,7 +109,7 @@ macros such as these, and use driver_info to store more information.
... matching specified device class info
A short example, for a driver that supports several specific USB devices
-and their quirks, might have a MODULE_DEVICE_TABLE like this:
+and their quirks, might have a MODULE_DEVICE_TABLE like this::
static const struct usb_device_id mydriver_id_table[] = {
{ USB_DEVICE (0x9999, 0xaaaa), driver_info: QUIRK_X },
@@ -116,10 +122,10 @@ 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 usb_driver".
+need such a struct :c:type:`usb_driver`.
Drivers that connect directly to the USB subsystem should be declared
-something like this:
+something like this::
static struct usb_driver mydriver = {
.name = "mydriver",
@@ -138,11 +144,11 @@ something like this:
When the USB subsystem knows about a driver's device ID table, it's used when
choosing drivers to probe(). The thread doing new device processing checks
-drivers' device ID entries from the MODULE_DEVICE_TABLE against interface and
-device descriptors for the device. It will only call probe() if there is a
-match, and the third argument to probe() will be the entry that matched.
-
-If you don't provide an id_table for your driver, then your driver may get
-probed for each new device; the third parameter to probe() will be null.
-
+drivers' device ID entries from the ``MODULE_DEVICE_TABLE`` against interface
+and device descriptors for the device. It will only call ``probe()`` if there
+is a match, and the third argument to ``probe()`` will be the entry that
+matched.
+If you don't provide an ``id_table`` for your driver, then your driver may get
+probed for each new device; the third parameter to ``probe()`` will be
+``NULL``.
diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst
index 1e2a0c54eb3d..43f0a8b72b11 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -11,6 +11,7 @@ Linux USB API
callbacks
dma
power-management
+ hotplug
error-codes
writing_usb_driver
writing_musb_glue_layer
--
2.9.3
^ permalink raw reply related [flat|nested] 52+ messages in thread* [PATCH 14/22] usb/persist.txt: convert to ReST and add to driver-api book
2017-03-29 18:54 [PATCH 01/22] driver-api/basics.rst: add device table header Mauro Carvalho Chehab
` (11 preceding siblings ...)
2017-03-29 18:54 ` [PATCH 13/22] usb/hotplug.txt: " Mauro Carvalho Chehab
@ 2017-03-29 18:54 ` Mauro Carvalho Chehab
2017-03-29 18:54 ` [PATCH 15/22] usb/URB.txt: convert to ReST and update it Mauro Carvalho Chehab
` (8 subsequent siblings)
21 siblings, 0 replies; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-29 18:54 UTC (permalink / raw)
To: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, John Youn,
linux-usb, linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab
This document describe some USB core features. Add it to the
driver-api book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/driver-api/usb/index.rst | 1 +
.../persist.txt => driver-api/usb/persist.rst} | 22 +++++++++++++---------
2 files changed, 14 insertions(+), 9 deletions(-)
rename Documentation/{usb/persist.txt => driver-api/usb/persist.rst} (94%)
diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst
index 43f0a8b72b11..3f08cb5d5feb 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -12,6 +12,7 @@ Linux USB API
dma
power-management
hotplug
+ persist
error-codes
writing_usb_driver
writing_musb_glue_layer
diff --git a/Documentation/usb/persist.txt b/Documentation/driver-api/usb/persist.rst
similarity index 94%
rename from Documentation/usb/persist.txt
rename to Documentation/driver-api/usb/persist.rst
index 35d70eda9ad6..af02baf61f57 100644
--- a/Documentation/usb/persist.txt
+++ b/Documentation/driver-api/usb/persist.rst
@@ -1,11 +1,12 @@
- USB device persistence during system suspend
+USB device persistence during system suspend
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Alan Stern <stern@rowland.harvard.edu>
+Alan Stern <stern@rowland.harvard.edu>
+September 2, 2006 (Updated February 25, 2008)
- September 2, 2006 (Updated February 25, 2008)
-
- What is the problem?
+What is the problem?
+====================
According to the USB specification, when a USB bus is suspended the
bus must continue to supply suspend current (around 1-5 mA). This
@@ -63,7 +64,8 @@ suspended -- but it will crash as soon as it wakes up, which isn't
much better.)
- What is the solution?
+What is the solution?
+=====================
The kernel includes a feature called USB-persist. It tries to work
around these issues by allowing the core USB device data structures to
@@ -99,7 +101,7 @@ now a good and happy place.
Note that the "USB-persist" feature will be applied only to those
devices for which it is enabled. You can enable the feature by doing
-(as root):
+(as root)::
echo 1 >/sys/bus/usb/devices/.../power/persist
@@ -110,7 +112,8 @@ doesn't even exist, so you only have to worry about setting it for
devices where it really matters.
- Is this the best solution?
+Is this the best solution?
+==========================
Perhaps not. Arguably, keeping track of mounted filesystems and
memory mappings across device disconnects should be handled by a
@@ -130,7 +133,8 @@ just mass-storage devices. It might turn out to be equally useful for
other device types, such as network interfaces.
- WARNING: USB-persist can be dangerous!!
+WARNING: USB-persist can be dangerous!!
+=======================================
When recovering an interrupted power session the kernel does its best
to make sure the USB device hasn't been changed; that is, the same
--
2.9.3
^ permalink raw reply related [flat|nested] 52+ messages in thread* [PATCH 15/22] usb/URB.txt: convert to ReST and update it
2017-03-29 18:54 [PATCH 01/22] driver-api/basics.rst: add device table header Mauro Carvalho Chehab
` (12 preceding siblings ...)
2017-03-29 18:54 ` [PATCH 14/22] usb/persist.txt: " Mauro Carvalho Chehab
@ 2017-03-29 18:54 ` Mauro Carvalho Chehab
2017-03-29 18:54 ` [PATCH 16/22] usb/gadget.rst: remove unused kernel-doc tags Mauro Carvalho Chehab
` (7 subsequent siblings)
21 siblings, 0 replies; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-29 18:54 UTC (permalink / raw)
To: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, John Youn,
linux-usb, linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab, Oliver Neukum
The URB doc describes the Kernel mechanism that do USB transfers.
While the functions are already described at urb.h, there are a
number of concepts and theory that are important for USB driver
developers.
Convert it to ReST and use C ref links to point to the places
at usb.h where each function and struct is located.
A few of those descriptions were incomplete. While here, update
to reflect the current API status.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
.../{usb/URB.txt => driver-api/usb/URB.rst} | 204 ++++++++++++---------
Documentation/driver-api/usb/index.rst | 1 +
Documentation/driver-api/usb/usb.rst | 2 +
3 files changed, 120 insertions(+), 87 deletions(-)
rename Documentation/{usb/URB.txt => driver-api/usb/URB.rst} (52%)
diff --git a/Documentation/usb/URB.txt b/Documentation/driver-api/usb/URB.rst
similarity index 52%
rename from Documentation/usb/URB.txt
rename to Documentation/driver-api/usb/URB.rst
index 50da0d455444..c5d2b68b4dae 100644
--- a/Documentation/usb/URB.txt
+++ b/Documentation/driver-api/usb/URB.rst
@@ -1,16 +1,25 @@
-Revised: 2000-Dec-05.
+USB Request Block (URB)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Revised: 2000-Dec-05
+
Again: 2002-Jul-06
+
Again: 2005-Sep-19
- NOTE:
+Again: 2017-Mar-29
- The USB subsystem now has a substantial section in "The Linux Kernel API"
- guide (in Documentation/DocBook), generated from the current source
- code. This particular documentation file isn't particularly current or
- complete; don't rely on it except for a quick overview.
+.. note::
-1.1. Basic concept or 'What is an URB?'
+ The USB subsystem now has a substantial section at :ref:`usb-hostside-api`
+ section, generated from the current source code.
+ This particular documentation file isn't complete and may not be
+ updated to the last version; don't rely on it except for a quick
+ overview.
+
+Basic concept or 'What is an URB?'
+==================================
The basic idea of the new driver is message passing, the message itself is
called USB Request Block, or URB for short.
@@ -19,10 +28,11 @@ called USB Request Block, or URB for short.
and deliver the data and status back.
- Execution of an URB is inherently an asynchronous operation, i.e. the
- usb_submit_urb(urb) call returns immediately after it has successfully
+ :c:func:`usb_submit_urb` call returns immediately after it has successfully
queued the requested action.
-- Transfers for one URB can be canceled with usb_unlink_urb(urb) at any time.
+- Transfers for one URB can be canceled with :c:func:`usb_unlink_urb`
+ at any time.
- Each URB has a completion handler, which is called after the action
has been successfully completed or canceled. The URB also contains a
@@ -35,53 +45,55 @@ called USB Request Block, or URB for short.
of data to (or from) devices when using periodic transfer modes.
-1.2. The URB structure
+The URB structure
+=================
-Some of the fields in an URB are:
+Some of the fields in struct :c:type:`urb` are::
-struct urb
-{
-// (IN) device and pipe specify the endpoint queue
+ struct urb
+ {
+ // (IN) device and pipe specify the endpoint queue
struct usb_device *dev; // pointer to associated USB device
unsigned int pipe; // endpoint information
- unsigned int transfer_flags; // ISO_ASAP, SHORT_NOT_OK, etc.
+ unsigned int transfer_flags; // URB_ISO_ASAP, URB_SHORT_NOT_OK, etc.
-// (IN) all urbs need completion routines
+ // (IN) all urbs need completion routines
void *context; // context for completion routine
- void (*complete)(struct urb *); // pointer to completion routine
+ usb_complete_t complete; // pointer to completion routine
-// (OUT) status after each completion
+ // (OUT) status after each completion
int status; // returned status
-// (IN) buffer used for data transfers
+ // (IN) buffer used for data transfers
void *transfer_buffer; // associated data buffer
- int transfer_buffer_length; // data buffer length
+ u32 transfer_buffer_length; // data buffer length
int number_of_packets; // size of iso_frame_desc
-// (OUT) sometimes only part of CTRL/BULK/INTR transfer_buffer is used
- int actual_length; // actual data buffer length
+ // (OUT) sometimes only part of CTRL/BULK/INTR transfer_buffer is used
+ u32 actual_length; // actual data buffer length
-// (IN) setup stage for CTRL (pass a struct usb_ctrlrequest)
- unsigned char* setup_packet; // setup packet (control only)
+ // (IN) setup stage for CTRL (pass a struct usb_ctrlrequest)
+ unsigned char *setup_packet; // setup packet (control only)
-// Only for PERIODIC transfers (ISO, INTERRUPT)
- // (IN/OUT) start_frame is set unless ISO_ASAP isn't set
+ // Only for PERIODIC transfers (ISO, INTERRUPT)
+ // (IN/OUT) start_frame is set unless URB_ISO_ASAP isn't set
int start_frame; // start frame
int interval; // polling interval
// ISO only: packets are only "best effort"; each can have errors
int error_count; // number of errors
struct usb_iso_packet_descriptor iso_frame_desc[0];
-};
+ };
Your driver must create the "pipe" value using values from the appropriate
endpoint descriptor in an interface that it's claimed.
-1.3. How to get an URB?
+How to get an URB?
+==================
-URBs are allocated with the following call
+URBs are allocated by calling :c:func:`usb_alloc_urb`::
struct urb *usb_alloc_urb(int isoframes, int mem_flags)
@@ -91,7 +103,7 @@ you want to schedule. For CTRL/BULK/INT, use 0. The mem_flags parameter
holds standard memory allocation flags, letting you control (among other
things) whether the underlying code may block or not.
-To free an URB, use
+To free an URB, use :c:func:`usb_free_urb`::
void usb_free_urb(struct urb *urb)
@@ -100,78 +112,84 @@ returned to you in a completion callback. It will automatically be
deallocated when it is no longer in use.
-1.4. What has to be filled in?
+What has to be filled in?
+=========================
Depending on the type of transaction, there are some inline functions
-defined in <linux/usb.h> to simplify the initialization, such as
-fill_control_urb() and fill_bulk_urb(). In general, they need the usb
-device pointer, the pipe (usual format from usb.h), the transfer buffer,
-the desired transfer length, the completion handler, and its context.
-Take a look at the some existing drivers to see how they're used.
+defined in ``linux/usb.h`` to simplify the initialization, such as
+:c:func:`usb_fill_control_urb`, :c:func:`usb_fill_bulk_urb` and
+:c:func:`usb_fill_int_urb`. In general, they need the usb device pointer,
+the pipe (usual format from usb.h), the transfer buffer, the desired transfer
+length, the completion handler, and its context. Take a look at the some
+existing drivers to see how they're used.
Flags:
-For ISO there are two startup behaviors: Specified start_frame or ASAP.
-For ASAP set URB_ISO_ASAP in transfer_flags.
-If short packets should NOT be tolerated, set URB_SHORT_NOT_OK in
+- For ISO there are two startup behaviors: Specified start_frame or ASAP.
+- For ASAP set ``URB_ISO_ASAP`` in transfer_flags.
+
+If short packets should NOT be tolerated, set ``URB_SHORT_NOT_OK`` in
transfer_flags.
-1.5. How to submit an URB?
+How to submit an URB?
+=====================
-Just call
+Just call :c:func:`usb_submit_urb`::
int usb_submit_urb(struct urb *urb, int mem_flags)
-The mem_flags parameter, such as SLAB_ATOMIC, controls memory allocation,
-such as whether the lower levels may block when memory is tight.
+The ``mem_flags`` parameter, such as ``GFP_ATOMIC``, controls memory
+allocation, such as whether the lower levels may block when memory is tight.
It immediately returns, either with status 0 (request queued) or some
error code, usually caused by the following:
-- Out of memory (-ENOMEM)
-- Unplugged device (-ENODEV)
-- Stalled endpoint (-EPIPE)
-- Too many queued ISO transfers (-EAGAIN)
-- Too many requested ISO frames (-EFBIG)
-- Invalid INT interval (-EINVAL)
-- More than one packet for INT (-EINVAL)
+- Out of memory (``-ENOMEM``)
+- Unplugged device (``-ENODEV``)
+- Stalled endpoint (``-EPIPE``)
+- Too many queued ISO transfers (``-EAGAIN``)
+- Too many requested ISO frames (``-EFBIG``)
+- Invalid INT interval (``-EINVAL``)
+- More than one packet for INT (``-EINVAL``)
-After submission, urb->status is -EINPROGRESS; however, you should never
-look at that value except in your completion callback.
+After submission, ``urb->status`` is ``-EINPROGRESS``; however, you should
+never look at that value except in your completion callback.
For isochronous endpoints, your completion handlers should (re)submit
-URBs to the same endpoint with the ISO_ASAP flag, using multi-buffering,
-to get seamless ISO streaming.
+URBs to the same endpoint with the ``URB_ISO_ASAP`` flag, using
+multi-buffering, to get seamless ISO streaming.
-1.6. How to cancel an already running URB?
+How to cancel an already running URB?
+=====================================
There are two ways to cancel an URB you've submitted but which hasn't
been returned to your driver yet. For an asynchronous cancel, call
+:c:func:`usb_unlink_urb`::
int usb_unlink_urb(struct urb *urb)
It removes the urb from the internal list and frees all allocated
HW descriptors. The status is changed to reflect unlinking. Note
-that the URB will not normally have finished when usb_unlink_urb()
+that the URB will not normally have finished when :c:func:`usb_unlink_urb`
returns; you must still wait for the completion handler to be called.
-To cancel an URB synchronously, call
+To cancel an URB synchronously, call :c:func:`usb_kill_urb`::
void usb_kill_urb(struct urb *urb)
-It does everything usb_unlink_urb does, and in addition it waits
+It does everything :c:func:`usb_unlink_urb` does, and in addition it waits
until after the URB has been returned and the completion handler
has finished. It also marks the URB as temporarily unusable, so
that if the completion handler or anyone else tries to resubmit it
-they will get a -EPERM error. Thus you can be sure that when
-usb_kill_urb() returns, the URB is totally idle.
+they will get a ``-EPERM`` error. Thus you can be sure that when
+:c:func:`usb_kill_urb` returns, the URB is totally idle.
There is a lifetime issue to consider. An URB may complete at any
time, and the completion handler may free the URB. If this happens
-while usb_unlink_urb or usb_kill_urb is running, it will cause a
-memory-access violation. The driver is responsible for avoiding this,
+while :c:func:`usb_unlink_urb` or :c:func:`usb_kill_urb` is running, it will
+cause a memory-access violation. The driver is responsible for avoiding this,
which often means some sort of lock will be needed to prevent the URB
from being deallocated while it is still in use.
@@ -181,24 +199,25 @@ when usb_unlink_urb is invoked. The general solution to this problem
is to increment the URB's reference count while holding the lock, then
drop the lock and call usb_unlink_urb or usb_kill_urb, and then
decrement the URB's reference count. You increment the reference
-count by calling
+count by calling :c:func`usb_get_urb`::
struct urb *usb_get_urb(struct urb *urb)
(ignore the return value; it is the same as the argument) and
-decrement the reference count by calling usb_free_urb. Of course,
+decrement the reference count by calling :c:func:`usb_free_urb`. Of course,
none of this is necessary if there's no danger of the URB being freed
by the completion handler.
-1.7. What about the completion handler?
+What about the completion handler?
+==================================
-The handler is of the following type:
+The handler is of the following type::
typedef void (*usb_complete_t)(struct urb *)
I.e., it gets the URB that caused the completion call. In the completion
-handler, you should have a look at urb->status to detect any USB errors.
+handler, you should have a look at ``urb->status`` to detect any USB errors.
Since the context parameter is included in the URB, you can pass
information to the completion handler.
@@ -208,26 +227,33 @@ sixteen packets to transfer your 1KByte buffer, and ten of them might
have transferred successfully before the completion was called.
-NOTE: ***** WARNING *****
-NEVER SLEEP IN A COMPLETION HANDLER. These are often called in atomic
-context.
+.. warning::
+
+ NEVER SLEEP IN A COMPLETION HANDLER.
+
+ These are often called in atomic context.
In the current kernel, completion handlers run with local interrupts
disabled, but in the future this will be changed, so don't assume that
local IRQs are always disabled inside completion handlers.
-1.8. How to do isochronous (ISO) transfers?
+How to do isochronous (ISO) transfers?
+======================================
-For ISO transfers you have to fill a usb_iso_packet_descriptor structure,
-allocated at the end of the URB by usb_alloc_urb(n,mem_flags), for each
-packet you want to schedule. You also 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.
+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
+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
+most ISO transfer fields.
-The usb_submit_urb() call modifies urb->interval to the implemented interval
-value that is less than or equal to the requested interval value. If
-ISO_ASAP scheduling is used, urb->start_frame is also updated.
+For ISO transfers you also have to fill a :c:type:`usb_iso_packet_descriptor`
+structure, allocated at the end of the URB by :c:func:`usb_alloc_urb`, for
+each packet you want to schedule.
+
+The :c:func:`usb_submit_urb` call modifies ``urb->interval`` to the implemented
+interval value that is less than or equal to the requested interval value. If
+``URB_ISO_ASAP`` scheduling is used, ``urb->start_frame`` is also updated.
For each entry you have to specify the data offset for this frame (base is
transfer_buffer), and the length you want to write/expect to read.
@@ -237,25 +263,29 @@ It is allowed to specify a varying length from frame to frame (e.g. for
audio synchronisation/adaptive transfer rates). You can also use the length
0 to omit one or more frames (striping).
-For scheduling you can choose your own start frame or ISO_ASAP. As explained
-earlier, if you always keep at least one URB queued and your completion
-keeps (re)submitting a later URB, you'll get smooth ISO streaming (if usb
-bandwidth utilization allows).
+For scheduling you can choose your own start frame or ``URB_ISO_ASAP``. As
+explained earlier, if you always keep at least one URB queued and your
+completion keeps (re)submitting a later URB, you'll get smooth ISO streaming
+(if usb bandwidth utilization allows).
If you specify your own start frame, make sure it's several frames in advance
of the current frame. You might want this model if you're synchronizing
ISO data with some other event stream.
-1.9. How to start interrupt (INT) transfers?
+How to start interrupt (INT) transfers?
+=======================================
Interrupt transfers, like isochronous transfers, are periodic, and happen
in intervals that are powers of two (1, 2, 4 etc) units. Units are frames
for full and low speed devices, and microframes for high speed ones.
-The usb_submit_urb() call modifies urb->interval to the implemented interval
-value that is less than or equal to the requested interval value.
+You can use the :c:func:`usb_fill_int_urb` macro to fill INT transfer fields.
+
+The :c:func:`usb_submit_urb` call modifies ``urb->interval`` to the implemented
+interval value that is less than or equal to the requested interval value.
In Linux 2.6, unlike earlier versions, interrupt URBs are not automagically
restarted when they complete. They end when the completion handler is
called, just like other URBs. If you want an interrupt URB to be restarted,
your completion handler must resubmit it.
+s
diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst
index 3f08cb5d5feb..1bf64edc8c8a 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -10,6 +10,7 @@ Linux USB API
bulk-streams
callbacks
dma
+ URB
power-management
hotplug
persist
diff --git a/Documentation/driver-api/usb/usb.rst b/Documentation/driver-api/usb/usb.rst
index 7e820768ee4f..d15ab8ae5239 100644
--- a/Documentation/driver-api/usb/usb.rst
+++ b/Documentation/driver-api/usb/usb.rst
@@ -1,3 +1,5 @@
+.. _usb-hostside-api:
+
===========================
The Linux-USB Host Side API
===========================
--
2.9.3
^ permalink raw reply related [flat|nested] 52+ messages in thread* [PATCH 16/22] usb/gadget.rst: remove unused kernel-doc tags
2017-03-29 18:54 [PATCH 01/22] driver-api/basics.rst: add device table header Mauro Carvalho Chehab
` (13 preceding siblings ...)
2017-03-29 18:54 ` [PATCH 15/22] usb/URB.txt: convert to ReST and update it Mauro Carvalho Chehab
@ 2017-03-29 18:54 ` Mauro Carvalho Chehab
2017-03-29 18:54 ` [PATCH 17/22] usb.rst: get rid of some Sphinx errors Mauro Carvalho Chehab
` (6 subsequent siblings)
21 siblings, 0 replies; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-29 18:54 UTC (permalink / raw)
To: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, John Youn,
linux-usb, linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab
The DocBook file used to have "!E" include tags for usb gadget functions.
However, there's nothing there to be documented:
./drivers/usb/gadget/function/f_acm.c:1: warning: no structured comments found
./drivers/usb/gadget/function/f_ecm.c:1: warning: no structured comments found
./drivers/usb/gadget/function/f_subset.c:1: warning: no structured comments found
./drivers/usb/gadget/function/f_obex.c:1: warning: no structured comments found
./drivers/usb/gadget/function/f_serial.c:1: warning: no structured comments found
So, let's remove it. If someone wants do document the function
there, they may just revert this patch in the future.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/driver-api/usb/gadget.rst | 15 ---------------
1 file changed, 15 deletions(-)
diff --git a/Documentation/driver-api/usb/gadget.rst b/Documentation/driver-api/usb/gadget.rst
index c4c76ebb51d3..0488b89de21c 100644
--- a/Documentation/driver-api/usb/gadget.rst
+++ b/Documentation/driver-api/usb/gadget.rst
@@ -356,21 +356,6 @@ At this writing, a few of the current gadget drivers have been converted
to this framework. Near-term plans include converting all of them,
except for "gadgetfs".
-.. kernel-doc:: drivers/usb/gadget/function/f_acm.c
- :export:
-
-.. kernel-doc:: drivers/usb/gadget/function/f_ecm.c
- :export:
-
-.. kernel-doc:: drivers/usb/gadget/function/f_subset.c
- :export:
-
-.. kernel-doc:: drivers/usb/gadget/function/f_obex.c
- :export:
-
-.. kernel-doc:: drivers/usb/gadget/function/f_serial.c
- :export:
-
Peripheral Controller Drivers
=============================
--
2.9.3
^ permalink raw reply related [flat|nested] 52+ messages in thread* [PATCH 17/22] usb.rst: get rid of some Sphinx errors
2017-03-29 18:54 [PATCH 01/22] driver-api/basics.rst: add device table header Mauro Carvalho Chehab
` (14 preceding siblings ...)
2017-03-29 18:54 ` [PATCH 16/22] usb/gadget.rst: remove unused kernel-doc tags Mauro Carvalho Chehab
@ 2017-03-29 18:54 ` Mauro Carvalho Chehab
2017-03-29 18:54 ` [PATCH 18/22] usb: get rid of some ReST doc build errors Mauro Carvalho Chehab
` (5 subsequent siblings)
21 siblings, 0 replies; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-29 18:54 UTC (permalink / raw)
To: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, John Youn,
linux-usb, linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab, Oliver Neukum
Get rid of those warnings:
Documentation/driver-api/usb/usb.rst:615: ERROR: Unknown target name: "usb_type".
Documentation/driver-api/usb/usb.rst:615: ERROR: Unknown target name: "usb_dir".
Documentation/driver-api/usb/usb.rst:615: ERROR: Unknown target name: "usb_recip".
Documentation/driver-api/usb/usb.rst:679: ERROR: Unknown target name: "usbdevfs_urb_type".
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/driver-api/usb/usb.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/driver-api/usb/usb.rst b/Documentation/driver-api/usb/usb.rst
index d15ab8ae5239..5ebaf669704c 100644
--- a/Documentation/driver-api/usb/usb.rst
+++ b/Documentation/driver-api/usb/usb.rst
@@ -615,8 +615,8 @@ USBDEVFS_CONTROL
The first eight bytes of this structure are the contents of the
SETUP packet to be sent to the device; see the USB 2.0 specification
for details. The bRequestType value is composed by combining a
- USB_TYPE_\* value, a USB_DIR_\* value, and a USB_RECIP_\*
- value (from *<linux/usb.h>*). If wLength is nonzero, it describes
+ ``USB_TYPE_*`` value, a ``USB_DIR_*`` value, and a ``USB_RECIP_*``
+ value (from ``linux/usb.h``). If wLength is nonzero, it describes
the length of the data buffer, which is either written to the device
(USB_DIR_OUT) or read from the device (USB_DIR_IN).
@@ -678,7 +678,7 @@ the blocking is separate.
These requests are packaged into a structure that resembles the URB used
by kernel device drivers. (No POSIX Async I/O support here, sorry.) It
-identifies the endpoint type (USBDEVFS_URB_TYPE_\*), endpoint
+identifies the endpoint type (``USBDEVFS_URB_TYPE_*``), endpoint
(number, masked with USB_DIR_IN as appropriate), buffer and length,
and a user "context" value serving to uniquely identify each request.
(It's usually a pointer to per-request data.) Flags can modify requests
--
2.9.3
^ permalink raw reply related [flat|nested] 52+ messages in thread* [PATCH 18/22] usb: get rid of some ReST doc build errors
2017-03-29 18:54 [PATCH 01/22] driver-api/basics.rst: add device table header Mauro Carvalho Chehab
` (15 preceding siblings ...)
2017-03-29 18:54 ` [PATCH 17/22] usb.rst: get rid of some Sphinx errors Mauro Carvalho Chehab
@ 2017-03-29 18:54 ` Mauro Carvalho Chehab
2017-03-29 18:54 ` [PATCH 19/22] usb: composite.h: fix two warnings when building docs Mauro Carvalho Chehab
` (4 subsequent siblings)
21 siblings, 0 replies; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-29 18:54 UTC (permalink / raw)
To: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, John Youn,
linux-usb, linux-rpi-kernel, Laurent Pinchart, David Mosberger,
Mauro Carvalho Chehab, Jaejoong Kim, Roger Quadros, Oliver Neukum,
Wolfram Sang
We need an space before a numbered list to avoid those warnings:
./drivers/usb/core/message.c:478: ERROR: Unexpected indentation.
./drivers/usb/core/message.c:479: WARNING: Block quote ends without a blank line; unexpected unindent.
./include/linux/usb/composite.h:455: ERROR: Unexpected indentation.
./include/linux/usb/composite.h:456: WARNING: Block quote ends without a blank line; unexpected unindent.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
drivers/usb/core/message.c | 1 +
include/linux/usb/composite.h | 1 +
2 files changed, 2 insertions(+)
diff --git a/drivers/usb/core/message.c b/drivers/usb/core/message.c
index 2184ef40a82a..4c38ea41ae96 100644
--- a/drivers/usb/core/message.c
+++ b/drivers/usb/core/message.c
@@ -474,6 +474,7 @@ EXPORT_SYMBOL_GPL(usb_sg_init);
* significantly improve USB throughput.
*
* There are three kinds of completion for this function.
+ *
* (1) success, where io->status is zero. The number of io->bytes
* transferred is as requested.
* (2) error, where io->status is a negative errno value. The number
diff --git a/include/linux/usb/composite.h b/include/linux/usb/composite.h
index 4616a49a1c2e..30a063e98c19 100644
--- a/include/linux/usb/composite.h
+++ b/include/linux/usb/composite.h
@@ -451,6 +451,7 @@ static inline struct usb_composite_driver *to_cdriver(
* sure doing that won't hurt too much.
*
* One notion for how to handle Wireless USB devices involves:
+ *
* (a) a second gadget here, discovery mechanism TBD, but likely
* needing separate "register/unregister WUSB gadget" calls;
* (b) updates to usb_gadget to include flags "is it wireless",
--
2.9.3
^ permalink raw reply related [flat|nested] 52+ messages in thread* [PATCH 19/22] usb: composite.h: fix two warnings when building docs
2017-03-29 18:54 [PATCH 01/22] driver-api/basics.rst: add device table header Mauro Carvalho Chehab
` (16 preceding siblings ...)
2017-03-29 18:54 ` [PATCH 18/22] usb: get rid of some ReST doc build errors Mauro Carvalho Chehab
@ 2017-03-29 18:54 ` Mauro Carvalho Chehab
2017-03-29 18:54 ` [PATCH 20/22] usb: gadget.h: be consistent at kernel doc macros Mauro Carvalho Chehab
` (3 subsequent siblings)
21 siblings, 0 replies; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-29 18:54 UTC (permalink / raw)
To: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, John Youn,
linux-usb, linux-rpi-kernel, Laurent Pinchart
By definition, we use /* private: */ tag when we won't be documenting
a parameter. However, those two parameters are documented:
./include/linux/usb/composite.h:510: warning: Excess struct/union/enum/typedef member 'setup_pending' description in 'usb_composite_dev'
./include/linux/usb/composite.h:510: warning: Excess struct/union/enum/typedef member 'os_desc_pending' description in 'usb_composite_dev'
So, we need to use /* public: */ to avoid a warning.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
include/linux/usb/composite.h | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/include/linux/usb/composite.h b/include/linux/usb/composite.h
index 30a063e98c19..f665d2ceac20 100644
--- a/include/linux/usb/composite.h
+++ b/include/linux/usb/composite.h
@@ -504,8 +504,9 @@ struct usb_composite_dev {
/* protects deactivations and delayed_status counts*/
spinlock_t lock;
- unsigned setup_pending:1;
- unsigned os_desc_pending:1;
+ /* public: */
+ unsigned int setup_pending:1;
+ unsigned int os_desc_pending:1;
};
extern int usb_string_id(struct usb_composite_dev *c);
--
2.9.3
^ permalink raw reply related [flat|nested] 52+ messages in thread* [PATCH 20/22] usb: gadget.h: be consistent at kernel doc macros
2017-03-29 18:54 [PATCH 01/22] driver-api/basics.rst: add device table header Mauro Carvalho Chehab
` (17 preceding siblings ...)
2017-03-29 18:54 ` [PATCH 19/22] usb: composite.h: fix two warnings when building docs Mauro Carvalho Chehab
@ 2017-03-29 18:54 ` Mauro Carvalho Chehab
2017-03-29 18:54 ` [PATCH 21/22] docs-rst: fix usb cross-references Mauro Carvalho Chehab
` (2 subsequent siblings)
21 siblings, 0 replies; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-29 18:54 UTC (permalink / raw)
To: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, John Youn,
linux-usb, linux-rpi-kernel, Laurent Pinchart, Felipe Balbi
There's one value that use spaces instead of tabs to ident.
That causes the following warning:
./include/linux/usb/gadget.h:193: ERROR: Unexpected indentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
include/linux/usb/gadget.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/include/linux/usb/gadget.h b/include/linux/usb/gadget.h
index e4516e9ded0f..fbc22a39e7bc 100644
--- a/include/linux/usb/gadget.h
+++ b/include/linux/usb/gadget.h
@@ -188,7 +188,7 @@ struct usb_ep_caps {
* @caps:The structure describing types and directions supported by endoint.
* @maxpacket:The maximum packet size used on this endpoint. The initial
* value can sometimes be reduced (hardware allowing), according to
- * the endpoint descriptor used to configure the endpoint.
+ * the endpoint descriptor used to configure the endpoint.
* @maxpacket_limit:The maximum packet size value which can be handled by this
* endpoint. It's set once by UDC driver when endpoint is initialized, and
* should not be changed. Should not be confused with maxpacket.
--
2.9.3
^ permalink raw reply related [flat|nested] 52+ messages in thread* [PATCH 21/22] docs-rst: fix usb cross-references
2017-03-29 18:54 [PATCH 01/22] driver-api/basics.rst: add device table header Mauro Carvalho Chehab
` (18 preceding siblings ...)
2017-03-29 18:54 ` [PATCH 20/22] usb: gadget.h: be consistent at kernel doc macros Mauro Carvalho Chehab
@ 2017-03-29 18:54 ` Mauro Carvalho Chehab
2017-03-29 18:54 ` [PATCH 22/22] usb: document that URB transfer_buffer should be aligned Mauro Carvalho Chehab
2017-03-31 1:26 ` [PATCH 01/22] driver-api/basics.rst: add device table header kbuild test robot
21 siblings, 0 replies; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-29 18:54 UTC (permalink / raw)
To: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, John Youn,
linux-usb, linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Rafael J. Wysocki, Len Brown, Pavel Machek, Mauro Carvalho Chehab,
Masanari Iida, Oliver Neukum, Christian Gromm, Andrey Shvetsov,
Rafał Miłecki, Heikki Krogerus, Peter Chen,
Masahiro Yamada, linux-pm, devel
As some USB documentation files got moved, adjust their
cross-references to their new place.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/ABI/stable/sysfs-bus-usb | 2 +-
Documentation/driver-api/usb/URB.rst | 2 ++
Documentation/driver-api/usb/callbacks.rst | 4 ++--
Documentation/driver-api/usb/error-codes.rst | 2 ++
Documentation/driver-api/usb/persist.rst | 2 ++
Documentation/driver-api/usb/power-management.rst | 2 +-
Documentation/driver-api/usb/usb.rst | 4 ++--
Documentation/power/swsusp.txt | 2 +-
drivers/staging/most/hdm-usb/hdm_usb.c | 2 +-
drivers/usb/core/Kconfig | 2 +-
10 files changed, 15 insertions(+), 9 deletions(-)
diff --git a/Documentation/ABI/stable/sysfs-bus-usb b/Documentation/ABI/stable/sysfs-bus-usb
index 831f15d9672f..b832eeff9999 100644
--- a/Documentation/ABI/stable/sysfs-bus-usb
+++ b/Documentation/ABI/stable/sysfs-bus-usb
@@ -9,7 +9,7 @@ Description:
hubs this facility is always enabled and their device
directories will not contain this file.
- For more information, see Documentation/usb/persist.txt.
+ For more information, see Documentation/driver-api/usb/persist.rst.
What: /sys/bus/usb/devices/.../power/autosuspend
Date: March 2007
diff --git a/Documentation/driver-api/usb/URB.rst b/Documentation/driver-api/usb/URB.rst
index c5d2b68b4dae..d9ea6a3996e7 100644
--- a/Documentation/driver-api/usb/URB.rst
+++ b/Documentation/driver-api/usb/URB.rst
@@ -1,3 +1,5 @@
+.. _usb-urb:
+
USB Request Block (URB)
~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/Documentation/driver-api/usb/callbacks.rst b/Documentation/driver-api/usb/callbacks.rst
index 93a8d53e27e7..2b80cf54bcc3 100644
--- a/Documentation/driver-api/usb/callbacks.rst
+++ b/Documentation/driver-api/usb/callbacks.rst
@@ -8,7 +8,7 @@ Usbcore will call into a driver through callbacks defined in the driver
structure and through the completion handler of URBs a driver submits.
Only the former are in the scope of this document. These two kinds of
callbacks are completely independent of each other. Information on the
-completion callback can be found in Documentation/usb/URB.txt.
+completion callback can be found in :ref:`usb-urb`.
The callbacks defined in the driver structure are:
@@ -53,7 +53,7 @@ The callbacks defined in the driver structure are:
The ioctl interface (2) should be used only if you have a very good
reason. Sysfs is preferred these days. The PM callbacks are covered
-separately in Documentation/usb/power-management.txt.
+separately in :ref:`usb-power-management`.
Calling conventions
===================
diff --git a/Documentation/driver-api/usb/error-codes.rst b/Documentation/driver-api/usb/error-codes.rst
index 715cc35b29b0..5bc5eda58520 100644
--- a/Documentation/driver-api/usb/error-codes.rst
+++ b/Documentation/driver-api/usb/error-codes.rst
@@ -1,3 +1,5 @@
+.. _usb-error-codes:
+
USB Error codes
~~~~~~~~~~~~~~~
diff --git a/Documentation/driver-api/usb/persist.rst b/Documentation/driver-api/usb/persist.rst
index af02baf61f57..8ee2a62d889b 100644
--- a/Documentation/driver-api/usb/persist.rst
+++ b/Documentation/driver-api/usb/persist.rst
@@ -1,3 +1,5 @@
+.. _usb-persist:
+
USB device persistence during system suspend
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/Documentation/driver-api/usb/power-management.rst b/Documentation/driver-api/usb/power-management.rst
index 7c547d6b8372..3e4ebbf47b76 100644
--- a/Documentation/driver-api/usb/power-management.rst
+++ b/Documentation/driver-api/usb/power-management.rst
@@ -329,7 +329,7 @@ possible to work around the hibernation-forces-disconnect problem by
using the USB Persist facility.)
The ``reset_resume`` method is used by the USB Persist facility (see
-``Documentation/usb/persist.txt``) and it can also be used under certain
+:ref:`usb-persist`) and it can also be used under certain
circumstances when ``CONFIG_USB_PERSIST`` is not enabled. Currently, if a
device is reset during a resume and the driver does not have a
``reset_resume`` method, the driver won't receive any notification about
diff --git a/Documentation/driver-api/usb/usb.rst b/Documentation/driver-api/usb/usb.rst
index 5ebaf669704c..6824089ef4c8 100644
--- a/Documentation/driver-api/usb/usb.rst
+++ b/Documentation/driver-api/usb/usb.rst
@@ -424,8 +424,8 @@ header.
Unless noted otherwise, the ioctl requests described here will update
the modification time on the usbfs file to which they are applied
(unless they fail). A return of zero indicates success; otherwise, a
-standard USB error code is returned. (These are documented in
-``Documentation/usb/error-codes.txt`` in your kernel sources.)
+standard USB error code is returned (These are documented in
+:ref:`usb-error-codes`).
Each of these files multiplexes access to several I/O streams, one per
endpoint. Each device has one control endpoint (endpoint zero) which
diff --git a/Documentation/power/swsusp.txt b/Documentation/power/swsusp.txt
index 8cc17ca71813..9f2f942a01cf 100644
--- a/Documentation/power/swsusp.txt
+++ b/Documentation/power/swsusp.txt
@@ -406,7 +406,7 @@ Firewire, CompactFlash, MMC, external SATA, or even IDE hotplug bays)
before suspending; then remount them after resuming.
There is a work-around for this problem. For more information, see
-Documentation/usb/persist.txt.
+Documentation/driver-api/usb/persist.rst.
Q: Can I suspend-to-disk using a swap partition under LVM?
diff --git a/drivers/staging/most/hdm-usb/hdm_usb.c b/drivers/staging/most/hdm-usb/hdm_usb.c
index 65211d1824b7..2bfea9b48366 100644
--- a/drivers/staging/most/hdm-usb/hdm_usb.c
+++ b/drivers/staging/most/hdm-usb/hdm_usb.c
@@ -490,7 +490,7 @@ static void hdm_write_completion(struct urb *urb)
* disconnect. In the interval before the hub driver starts disconnect
* processing, devices may receive such fault reports for every request.
*
- * See <https://www.kernel.org/doc/Documentation/usb/error-codes.txt>
+ * See <https://www.kernel.org/doc/Documentation/driver-api/usb/error-codes.rst>
*/
static void hdm_read_completion(struct urb *urb)
{
diff --git a/drivers/usb/core/Kconfig b/drivers/usb/core/Kconfig
index 0e5a889742b3..4d75d9a80001 100644
--- a/drivers/usb/core/Kconfig
+++ b/drivers/usb/core/Kconfig
@@ -26,7 +26,7 @@ config USB_DEFAULT_PERSIST
unplugged, causing any mounted filesystems to be lost. The
persist feature can still be enabled for individual devices
through the power/persist sysfs node. See
- Documentation/usb/persist.txt for more info.
+ Documentation/driver-api/usb/persist.rst for more info.
If you have any questions about this, say Y here, only say N
if you know exactly what you are doing.
--
2.9.3
^ permalink raw reply related [flat|nested] 52+ messages in thread* [PATCH 22/22] usb: document that URB transfer_buffer should be aligned
2017-03-29 18:54 [PATCH 01/22] driver-api/basics.rst: add device table header Mauro Carvalho Chehab
` (19 preceding siblings ...)
2017-03-29 18:54 ` [PATCH 21/22] docs-rst: fix usb cross-references Mauro Carvalho Chehab
@ 2017-03-29 18:54 ` Mauro Carvalho Chehab
2017-03-29 22:15 ` Laurent Pinchart
2017-03-31 1:26 ` [PATCH 01/22] driver-api/basics.rst: add device table header kbuild test robot
21 siblings, 1 reply; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-29 18:54 UTC (permalink / raw)
To: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, John Youn,
linux-usb, linux-rpi-kernel, Laurent Pinchart, Jonathan Corbet,
Mauro Carvalho Chehab, David Mosberger, Oliver Neukum,
Roger Quadros, Jaejoong Kim, Wolfram Sang
Several host controllers, commonly found on ARM, like dwc2,
require buffers that are CPU-word aligned for they to work.
Failing to do that will cause random troubles at the caller
drivers, causing them to fail.
Document it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/driver-api/usb/URB.rst | 18 ++++++++++++++++++
drivers/usb/core/message.c | 15 +++++++++++++++
include/linux/usb.h | 18 ++++++++++++++++++
3 files changed, 51 insertions(+)
diff --git a/Documentation/driver-api/usb/URB.rst b/Documentation/driver-api/usb/URB.rst
index d9ea6a3996e7..b83b557e9891 100644
--- a/Documentation/driver-api/usb/URB.rst
+++ b/Documentation/driver-api/usb/URB.rst
@@ -274,6 +274,24 @@ If you specify your own start frame, make sure it's several frames in advance
of the current frame. You might want this model if you're synchronizing
ISO data with some other event stream.
+.. note::
+
+ Several host drivers require that the ``transfer_buffer`` to be aligned
+ with the CPU word size (e. g. DWORD for 32 bits, QDWORD for 64 bits).
+ It is up to USB drivers should ensure that they'll only pass buffers
+ with such alignments.
+
+ Please also notice that, due to such restriction, the host driver
+ may also override PAD bytes at the end of the ``transfer_buffer``, up to the
+ size of the CPU word.
+
+ Please notice that ancillary routines that transfer URBs, like
+ usb_control_msg() also have such restriction.
+
+ Such word alignment condition is normally ensured if the buffer is
+ allocated with kmalloc(), but this may not be the case if the driver
+ allocates a bigger buffer and point to a random place inside it.
+
How to start interrupt (INT) transfers?
=======================================
diff --git a/drivers/usb/core/message.c b/drivers/usb/core/message.c
index 4c38ea41ae96..1662a4446475 100644
--- a/drivers/usb/core/message.c
+++ b/drivers/usb/core/message.c
@@ -128,6 +128,21 @@ static int usb_internal_control_msg(struct usb_device *usb_dev,
* make sure your disconnect() method can wait for it to complete. Since you
* don't have a handle on the URB used, you can't cancel the request.
*
+ * .. note::
+ *
+ * Several host drivers require that the @data buffer to be aligned
+ * with the CPU word size (e. g. DWORD for 32 bits, QDWORD for 64 bits).
+ * It is up to USB drivers should ensure that they'll only pass buffers
+ * with such alignments.
+ *
+ * Please also notice that, due to such restriction, the host driver
+ * may also override PAD bytes at the end of the @data buffer, up to the
+ * size of the CPU word.
+ *
+ * Such word alignment condition is normally ensured if the buffer is
+ * allocated with kmalloc(), but this may not be the case if the driver
+ * allocates a bigger buffer and point to a random place inside it.
+ *
* Return: If successful, the number of bytes transferred. Otherwise, a negative
* error number.
*/
diff --git a/include/linux/usb.h b/include/linux/usb.h
index 7e68259360de..8b5ad6624708 100644
--- a/include/linux/usb.h
+++ b/include/linux/usb.h
@@ -1373,6 +1373,24 @@ typedef void (*usb_complete_t)(struct urb *);
* capable, assign NULL to it, so that usbmon knows not to use the value.
* The setup_packet must always be set, so it cannot be located in highmem.
*
+ * .. note::
+ *
+ * Several host drivers require that the @transfer_buffer to be aligned
+ * with the CPU word size (e. g. DWORD for 32 bits, QDWORD for 64 bits).
+ * It is up to USB drivers should ensure that they'll only pass buffers
+ * with such alignments.
+ *
+ * Please also notice that, due to such restriction, the host driver
+ * may also override PAD bytes at the end of the @transfer_buffer, up to the
+ * size of the CPU word.
+ *
+ * Please notice that ancillary routines that start URB transfers, like
+ * usb_control_msg() also have such restriction.
+ *
+ * Such word alignment condition is normally ensured if the buffer is
+ * allocated with kmalloc(), but this may not be the case if the driver
+ * allocates a bigger buffer and point to a random place inside it.
+ *
* Initialization:
*
* All URBs submitted must initialize the dev, pipe, transfer_flags (may be
--
2.9.3
^ permalink raw reply related [flat|nested] 52+ messages in thread* Re: [PATCH 22/22] usb: document that URB transfer_buffer should be aligned
2017-03-29 18:54 ` [PATCH 22/22] usb: document that URB transfer_buffer should be aligned Mauro Carvalho Chehab
@ 2017-03-29 22:15 ` Laurent Pinchart
2017-03-30 1:06 ` Mauro Carvalho Chehab
2017-03-30 8:11 ` Oliver Neukum
0 siblings, 2 replies; 52+ messages in thread
From: Laurent Pinchart @ 2017-03-29 22:15 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman, Mauro Carvalho Chehab, John Youn, linux-usb,
linux-rpi-kernel, Jonathan Corbet, Mauro Carvalho Chehab,
David Mosberger, Oliver Neukum, Roger Quadros, Jaejoong Kim,
Wolfram Sang
Hi Mauro,
Thank you for the patch.
On Wednesday 29 Mar 2017 15:54:21 Mauro Carvalho Chehab wrote:
> Several host controllers, commonly found on ARM, like dwc2,
> require buffers that are CPU-word aligned for they to work.
>
> Failing to do that will cause random troubles at the caller
> drivers, causing them to fail.
>
> Document it.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
> Documentation/driver-api/usb/URB.rst | 18 ++++++++++++++++++
> drivers/usb/core/message.c | 15 +++++++++++++++
> include/linux/usb.h | 18 ++++++++++++++++++
> 3 files changed, 51 insertions(+)
>
> diff --git a/Documentation/driver-api/usb/URB.rst
> b/Documentation/driver-api/usb/URB.rst index d9ea6a3996e7..b83b557e9891
> 100644
> --- a/Documentation/driver-api/usb/URB.rst
> +++ b/Documentation/driver-api/usb/URB.rst
> @@ -274,6 +274,24 @@ If you specify your own start frame, make sure it's
> several frames in advance of the current frame. You might want this model
> if you're synchronizing ISO data with some other event stream.
>
> +.. note::
> +
> + Several host drivers require that the ``transfer_buffer`` to be aligned
> + with the CPU word size (e. g. DWORD for 32 bits, QDWORD for 64 bits).
Is it the CPU word size or the DMA transfer size ? I assume the latter, and I
wouldn't be surprised if the alignment requirement was 32-bit on at least some
of the 64-bit platforms.
> + It is up to USB drivers should ensure that they'll only pass buffers
> + with such alignments.
> +
> + Please also notice that, due to such restriction, the host driver
s/notice/note/ (and below as well) ?
> + may also override PAD bytes at the end of the ``transfer_buffer``, up to
> the
> + size of the CPU word.
"May" is quite weak here. If some host controller drivers require buffers to
be aligned, then it's an API requirement, and all buffers must be aligned. I'm
not even sure I would mention that some host drivers require it, I think we
should just state that the API requires buffers to be aligned.
> + Please notice that ancillary routines that transfer URBs, like
> + usb_control_msg() also have such restriction.
> +
> + Such word alignment condition is normally ensured if the buffer is
> + allocated with kmalloc(), but this may not be the case if the driver
> + allocates a bigger buffer and point to a random place inside it.
> +
>
> How to start interrupt (INT) transfers?
> =======================================
> diff --git a/drivers/usb/core/message.c b/drivers/usb/core/message.c
> index 4c38ea41ae96..1662a4446475 100644
> --- a/drivers/usb/core/message.c
> +++ b/drivers/usb/core/message.c
> @@ -128,6 +128,21 @@ static int usb_internal_control_msg(struct usb_device
> *usb_dev, * make sure your disconnect() method can wait for it to complete.
> Since you * don't have a handle on the URB used, you can't cancel the
> request. *
> + * .. note::
> + *
> + * Several host drivers require that the @data buffer to be aligned
> + * with the CPU word size (e. g. DWORD for 32 bits, QDWORD for 64 bits).
> + * It is up to USB drivers should ensure that they'll only pass buffers
> + * with such alignments.
> + *
> + * Please also notice that, due to such restriction, the host driver
> + * may also override PAD bytes at the end of the @data buffer, up to the
> + * size of the CPU word.
> + *
> + * Such word alignment condition is normally ensured if the buffer is
> + * allocated with kmalloc(), but this may not be the case if the driver
> + * allocates a bigger buffer and point to a random place inside it.
> + *
> * Return: If successful, the number of bytes transferred. Otherwise, a
> negative * error number.
> */
> diff --git a/include/linux/usb.h b/include/linux/usb.h
> index 7e68259360de..8b5ad6624708 100644
> --- a/include/linux/usb.h
> +++ b/include/linux/usb.h
> @@ -1373,6 +1373,24 @@ typedef void (*usb_complete_t)(struct urb *);
> * capable, assign NULL to it, so that usbmon knows not to use the value.
> * The setup_packet must always be set, so it cannot be located in highmem.
> *
> + * .. note::
> + *
> + * Several host drivers require that the @transfer_buffer to be aligned
> + * with the CPU word size (e. g. DWORD for 32 bits, QDWORD for 64 bits).
> + * It is up to USB drivers should ensure that they'll only pass buffers
> + * with such alignments.
> + *
> + * Please also notice that, due to such restriction, the host driver
> + * may also override PAD bytes at the end of the @transfer_buffer, up to
> the + * size of the CPU word.
> + *
> + * Please notice that ancillary routines that start URB transfers, like
> + * usb_control_msg() also have such restriction.
> + *
> + * Such word alignment condition is normally ensured if the buffer is
> + * allocated with kmalloc(), but this may not be the case if the driver
> + * allocates a bigger buffer and point to a random place inside it.
> + *
Couldn't we avoid three copies of the same text ? The chance they will get
out-of-sync is quite high.
> * Initialization:
> *
> * All URBs submitted must initialize the dev, pipe, transfer_flags (may be
--
Regards,
Laurent Pinchart
^ permalink raw reply [flat|nested] 52+ messages in thread
* Re: [PATCH 22/22] usb: document that URB transfer_buffer should be aligned
2017-03-29 22:15 ` Laurent Pinchart
@ 2017-03-30 1:06 ` Mauro Carvalho Chehab
2017-03-30 9:38 ` Laurent Pinchart
2017-03-30 8:11 ` Oliver Neukum
1 sibling, 1 reply; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-30 1:06 UTC (permalink / raw)
To: Laurent Pinchart
Cc: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman, Mauro Carvalho Chehab, John Youn, linux-usb,
linux-rpi-kernel, Jonathan Corbet, Mauro Carvalho Chehab,
David Mosberger, Oliver Neukum, Roger Quadros, Jaejoong Kim,
Wolfram Sang
Em Thu, 30 Mar 2017 01:15:27 +0300
Laurent Pinchart <laurent.pinchart@ideasonboard.com> escreveu:
> Hi Mauro,
>
> Thank you for the patch.
>
> On Wednesday 29 Mar 2017 15:54:21 Mauro Carvalho Chehab wrote:
> > Several host controllers, commonly found on ARM, like dwc2,
> > require buffers that are CPU-word aligned for they to work.
> >
> > Failing to do that will cause random troubles at the caller
> > drivers, causing them to fail.
> >
> > Document it.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > ---
> > Documentation/driver-api/usb/URB.rst | 18 ++++++++++++++++++
> > drivers/usb/core/message.c | 15 +++++++++++++++
> > include/linux/usb.h | 18 ++++++++++++++++++
> > 3 files changed, 51 insertions(+)
> >
> > diff --git a/Documentation/driver-api/usb/URB.rst
> > b/Documentation/driver-api/usb/URB.rst index d9ea6a3996e7..b83b557e9891
> > 100644
> > --- a/Documentation/driver-api/usb/URB.rst
> > +++ b/Documentation/driver-api/usb/URB.rst
> > @@ -274,6 +274,24 @@ If you specify your own start frame, make sure it's
> > several frames in advance of the current frame. You might want this model
> > if you're synchronizing ISO data with some other event stream.
> >
> > +.. note::
> > +
> > + Several host drivers require that the ``transfer_buffer`` to be aligned
> > + with the CPU word size (e. g. DWORD for 32 bits, QDWORD for 64 bits).
>
> Is it the CPU word size or the DMA transfer size ? I assume the latter, and I
> wouldn't be surprised if the alignment requirement was 32-bit on at least some
> of the 64-bit platforms.
Yeah, it is actually the DMA transfer size. Yet, worse case scenario is that
the DMA transfer size to be 64 bits on 64 bits CPU.
>
> > + It is up to USB drivers should ensure that they'll only pass buffers
> > + with such alignments.
> > +
> > + Please also notice that, due to such restriction, the host driver
>
> s/notice/note/ (and below as well) ?
OK.
> > + may also override PAD bytes at the end of the ``transfer_buffer``, up to
> > the
> > + size of the CPU word.
>
> "May" is quite weak here. If some host controller drivers require buffers to
> be aligned, then it's an API requirement, and all buffers must be aligned. I'm
> not even sure I would mention that some host drivers require it, I think we
> should just state that the API requires buffers to be aligned.
What I'm trying to say here is that, on a 32-bits system, if the driver do
a USB_DIR_IN transfer using some code similar to:
size = 4;
buffer = kmalloc(size, GFP_KERNEL);
usb_control_msg(udev, pipe, req, type, val, idx, buffer + 2, 2, timeout);
usb_control_msg(udev, pipe, req, type, val, idx, buffer, size, timeout);
Drivers like dwc2 will mess with the buffer.
The first transfer will actually work, due to a workaround inside the
driver that will create a temporary DWORD-aligned buffer, avoiding it
to go past the buffer.
However, the second transfer will destroy the data received from the
first usb_control_msg(), as it will write 4 bytes at the buffer.
Not all drivers would do that, though.
Please notice that, as kmalloc will always return a CPU-aligned buffer,
if the client do something like:
size = 2;
buffer = kmalloc(size, GFP_KERNEL);
usb_control_msg(udev, pipe, req, type, val, idx, buffer, 2, timeout);
What happens there is that the DMA engine will still write 4 bytes at
the buffer, but the 2 bytes that go past the end of buffer will be
written on a memory that will never be used.
>
> > + Please notice that ancillary routines that transfer URBs, like
> > + usb_control_msg() also have such restriction.
> > +
> > + Such word alignment condition is normally ensured if the buffer is
> > + allocated with kmalloc(), but this may not be the case if the driver
> > + allocates a bigger buffer and point to a random place inside it.
> > +
> >
> > How to start interrupt (INT) transfers?
> > =======================================
> > diff --git a/drivers/usb/core/message.c b/drivers/usb/core/message.c
> > index 4c38ea41ae96..1662a4446475 100644
> > --- a/drivers/usb/core/message.c
> > +++ b/drivers/usb/core/message.c
> > @@ -128,6 +128,21 @@ static int usb_internal_control_msg(struct usb_device
> > *usb_dev, * make sure your disconnect() method can wait for it to complete.
> > Since you * don't have a handle on the URB used, you can't cancel the
> > request. *
> > + * .. note::
> > + *
> > + * Several host drivers require that the @data buffer to be aligned
> > + * with the CPU word size (e. g. DWORD for 32 bits, QDWORD for 64 bits).
> > + * It is up to USB drivers should ensure that they'll only pass buffers
> > + * with such alignments.
> > + *
> > + * Please also notice that, due to such restriction, the host driver
> > + * may also override PAD bytes at the end of the @data buffer, up to the
> > + * size of the CPU word.
> > + *
> > + * Such word alignment condition is normally ensured if the buffer is
> > + * allocated with kmalloc(), but this may not be the case if the driver
> > + * allocates a bigger buffer and point to a random place inside it.
> > + *
> > * Return: If successful, the number of bytes transferred. Otherwise, a
> > negative * error number.
> > */
> > diff --git a/include/linux/usb.h b/include/linux/usb.h
> > index 7e68259360de..8b5ad6624708 100644
> > --- a/include/linux/usb.h
> > +++ b/include/linux/usb.h
> > @@ -1373,6 +1373,24 @@ typedef void (*usb_complete_t)(struct urb *);
> > * capable, assign NULL to it, so that usbmon knows not to use the value.
> > * The setup_packet must always be set, so it cannot be located in highmem.
> > *
> > + * .. note::
> > + *
> > + * Several host drivers require that the @transfer_buffer to be aligned
> > + * with the CPU word size (e. g. DWORD for 32 bits, QDWORD for 64 bits).
> > + * It is up to USB drivers should ensure that they'll only pass buffers
> > + * with such alignments.
> > + *
> > + * Please also notice that, due to such restriction, the host driver
> > + * may also override PAD bytes at the end of the @transfer_buffer, up to
> > the + * size of the CPU word.
> > + *
> > + * Please notice that ancillary routines that start URB transfers, like
> > + * usb_control_msg() also have such restriction.
> > + *
> > + * Such word alignment condition is normally ensured if the buffer is
> > + * allocated with kmalloc(), but this may not be the case if the driver
> > + * allocates a bigger buffer and point to a random place inside it.
> > + *
>
> Couldn't we avoid three copies of the same text ? The chance they will get
> out-of-sync is quite high.
IMHO, it is better to document it at those 3 parts, as this issue
cause buffer overflows, which is pretty serious, as it corrupts data.
The URB.rst file contains a quick overview of the URB data transfers,
and it is likely where a kernel newbie would read first. Experienced
programmers will look at urb.h.
usb_control_msg() is a different function, that one might not be
expecting to have the same issues.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 52+ messages in thread
* Re: [PATCH 22/22] usb: document that URB transfer_buffer should be aligned
2017-03-30 1:06 ` Mauro Carvalho Chehab
@ 2017-03-30 9:38 ` Laurent Pinchart
2017-03-30 10:51 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 52+ messages in thread
From: Laurent Pinchart @ 2017-03-30 9:38 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman, Mauro Carvalho Chehab, John Youn, linux-usb,
linux-rpi-kernel, Jonathan Corbet, Mauro Carvalho Chehab,
David Mosberger, Oliver Neukum, Roger Quadros, Jaejoong Kim,
Wolfram Sang
Hi Mauro,
On Wednesday 29 Mar 2017 22:06:33 Mauro Carvalho Chehab wrote:
> Em Thu, 30 Mar 2017 01:15:27 +0300 Laurent Pinchart escreveu:
> > On Wednesday 29 Mar 2017 15:54:21 Mauro Carvalho Chehab wrote:
> > > Several host controllers, commonly found on ARM, like dwc2,
> > > require buffers that are CPU-word aligned for they to work.
> > >
> > > Failing to do that will cause random troubles at the caller
> > > drivers, causing them to fail.
> > >
> > > Document it.
> > >
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > > ---
> > >
> > > Documentation/driver-api/usb/URB.rst | 18 ++++++++++++++++++
> > > drivers/usb/core/message.c | 15 +++++++++++++++
> > > include/linux/usb.h | 18 ++++++++++++++++++
> > > 3 files changed, 51 insertions(+)
> > >
> > > diff --git a/Documentation/driver-api/usb/URB.rst
> > > b/Documentation/driver-api/usb/URB.rst index d9ea6a3996e7..b83b557e9891
> > > 100644
> > > --- a/Documentation/driver-api/usb/URB.rst
> > > +++ b/Documentation/driver-api/usb/URB.rst
> > > @@ -274,6 +274,24 @@ If you specify your own start frame, make sure it's
> > > several frames in advance of the current frame. You might want this
> > > model
> > > if you're synchronizing ISO data with some other event stream.
> > >
> > > +.. note::
> > > +
> > > + Several host drivers require that the ``transfer_buffer`` to be
> > > aligned
> > > + with the CPU word size (e. g. DWORD for 32 bits, QDWORD for 64
> > > bits).
> >
> > Is it the CPU word size or the DMA transfer size ? I assume the latter,
> > and I wouldn't be surprised if the alignment requirement was 32-bit on at
> > least some of the 64-bit platforms.
>
> Yeah, it is actually the DMA transfer size. Yet, worse case scenario is that
> the DMA transfer size to be 64 bits on 64 bits CPU.
>
> > > + It is up to USB drivers should ensure that they'll only pass buffers
> > > + with such alignments.
> > > +
> > > + Please also notice that, due to such restriction, the host driver
> >
> > s/notice/note/ (and below as well) ?
>
> OK.
>
> > > + may also override PAD bytes at the end of the ``transfer_buffer``,
> > > up to the
> > > + size of the CPU word.
> >
> > "May" is quite weak here. If some host controller drivers require buffers
> > to be aligned, then it's an API requirement, and all buffers must be
> > aligned. I'm not even sure I would mention that some host drivers require
> > it, I think we should just state that the API requires buffers to be
> > aligned.
>
> What I'm trying to say here is that, on a 32-bits system, if the driver do
> a USB_DIR_IN transfer using some code similar to:
>
> size = 4;
> buffer = kmalloc(size, GFP_KERNEL);
>
> usb_control_msg(udev, pipe, req, type, val, idx, buffer + 2, 2,
timeout);
> usb_control_msg(udev, pipe, req, type, val, idx, buffer, size,
timeout);
>
> Drivers like dwc2 will mess with the buffer.
>
> The first transfer will actually work, due to a workaround inside the
> driver that will create a temporary DWORD-aligned buffer, avoiding it
> to go past the buffer.
>
> However, the second transfer will destroy the data received from the
> first usb_control_msg(), as it will write 4 bytes at the buffer.
>
> Not all drivers would do that, though.
>
> Please notice that, as kmalloc will always return a CPU-aligned buffer,
> if the client do something like:
>
> size = 2;
> buffer = kmalloc(size, GFP_KERNEL);
>
> usb_control_msg(udev, pipe, req, type, val, idx, buffer, 2, timeout);
>
> What happens there is that the DMA engine will still write 4 bytes at
> the buffer, but the 2 bytes that go past the end of buffer will be
> written on a memory that will never be used.
I understand that, but stating that host controller drivers "may" do this
won't help much. If they *may*, all USB device drivers *must* align buffers
correctly. That's the part that needs to be documented. Let's not confuse
developers by only stating that something may happened, let's be clear and
tell what they must do.
> > > + Please notice that ancillary routines that transfer URBs, like
> > > + usb_control_msg() also have such restriction.
> > > +
> > > + Such word alignment condition is normally ensured if the buffer is
> > > + allocated with kmalloc(), but this may not be the case if the driver
> > > + allocates a bigger buffer and point to a random place inside it.
> > > +
> > >
> > > How to start interrupt (INT) transfers?
> > > =======================================
> > >
> > > diff --git a/drivers/usb/core/message.c b/drivers/usb/core/message.c
> > > index 4c38ea41ae96..1662a4446475 100644
> > > --- a/drivers/usb/core/message.c
> > > +++ b/drivers/usb/core/message.c
> > > @@ -128,6 +128,21 @@ static int usb_internal_control_msg(struct
> > > usb_device
> > > *usb_dev, * make sure your disconnect() method can wait for it to
> > > complete.
> > > Since you * don't have a handle on the URB used, you can't cancel the
> > > request. *
> > > + * .. note::
> > > + *
> > > + * Several host drivers require that the @data buffer to be aligned
> > > + * with the CPU word size (e. g. DWORD for 32 bits, QDWORD for 64
> > > bits).
> > > + * It is up to USB drivers should ensure that they'll only pass
> > > buffers
> > > + * with such alignments.
> > > + *
> > > + * Please also notice that, due to such restriction, the host driver
> > > + * may also override PAD bytes at the end of the @data buffer, up to
> > > the
> > > + * size of the CPU word.
> > > + *
> > > + * Such word alignment condition is normally ensured if the buffer is
> > > + * allocated with kmalloc(), but this may not be the case if the
> > > driver
> > > + * allocates a bigger buffer and point to a random place inside it.
> > > + *
> > >
> > > * Return: If successful, the number of bytes transferred. Otherwise, a
> > >
> > > negative * error number.
> > >
> > > */
> > >
> > > diff --git a/include/linux/usb.h b/include/linux/usb.h
> > > index 7e68259360de..8b5ad6624708 100644
> > > --- a/include/linux/usb.h
> > > +++ b/include/linux/usb.h
> > > @@ -1373,6 +1373,24 @@ typedef void (*usb_complete_t)(struct urb *);
> > >
> > > * capable, assign NULL to it, so that usbmon knows not to use the
> > > value.
> > > * The setup_packet must always be set, so it cannot be located in
> > > highmem.
> > >
> > > *
> > > + * .. note::
> > > + *
> > > + * Several host drivers require that the @transfer_buffer to be
> > > aligned
> > > + * with the CPU word size (e. g. DWORD for 32 bits, QDWORD for 64
> > > bits).
> > > + * It is up to USB drivers should ensure that they'll only pass
> > > buffers
> > > + * with such alignments.
> > > + *
> > > + * Please also notice that, due to such restriction, the host driver
> > > + * may also override PAD bytes at the end of the @transfer_buffer, up
> > > to
> > > the + * size of the CPU word.
> > > + *
> > > + * Please notice that ancillary routines that start URB transfers,
> > > like
> > > + * usb_control_msg() also have such restriction.
> > > + *
> > > + * Such word alignment condition is normally ensured if the buffer is
> > > + * allocated with kmalloc(), but this may not be the case if the
> > > driver
> > > + * allocates a bigger buffer and point to a random place inside it.
> > > + *
> >
> > Couldn't we avoid three copies of the same text ? The chance they will get
> > out-of-sync is quite high.
>
> IMHO, it is better to document it at those 3 parts, as this issue
> cause buffer overflows, which is pretty serious, as it corrupts data.
>
> The URB.rst file contains a quick overview of the URB data transfers,
> and it is likely where a kernel newbie would read first. Experienced
> programmers will look at urb.h.
>
> usb_control_msg() is a different function, that one might not be
> expecting to have the same issues.
If you add the complete explanation to URB.rst, you can then reference it from
the functions' kerneldoc instead of copying it.
--
Regards,
Laurent Pinchart
^ permalink raw reply [flat|nested] 52+ messages in thread
* Re: [PATCH 22/22] usb: document that URB transfer_buffer should be aligned
2017-03-30 9:38 ` Laurent Pinchart
@ 2017-03-30 10:51 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-30 10:51 UTC (permalink / raw)
To: Laurent Pinchart
Cc: Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman, Mauro Carvalho Chehab, John Youn, linux-usb,
linux-rpi-kernel, Jonathan Corbet, Mauro Carvalho Chehab,
David Mosberger, Oliver Neukum, Roger Quadros, Jaejoong Kim,
Wolfram Sang
Em Thu, 30 Mar 2017 12:38:42 +0300
Laurent Pinchart <laurent.pinchart@ideasonboard.com> escreveu:
> Hi Mauro,
>
> On Wednesday 29 Mar 2017 22:06:33 Mauro Carvalho Chehab wrote:
> > Em Thu, 30 Mar 2017 01:15:27 +0300 Laurent Pinchart escreveu:
> > > On Wednesday 29 Mar 2017 15:54:21 Mauro Carvalho Chehab wrote:
> > > > Several host controllers, commonly found on ARM, like dwc2,
> > > > require buffers that are CPU-word aligned for they to work.
> > > >
> > > > Failing to do that will cause random troubles at the caller
> > > > drivers, causing them to fail.
> > > >
> > > > Document it.
> > > >
> > > > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > > > ---
> > > >
> > > > Documentation/driver-api/usb/URB.rst | 18 ++++++++++++++++++
> > > > drivers/usb/core/message.c | 15 +++++++++++++++
> > > > include/linux/usb.h | 18 ++++++++++++++++++
> > > > 3 files changed, 51 insertions(+)
> > > >
> > > > diff --git a/Documentation/driver-api/usb/URB.rst
> > > > b/Documentation/driver-api/usb/URB.rst index d9ea6a3996e7..b83b557e9891
> > > > 100644
> > > > --- a/Documentation/driver-api/usb/URB.rst
> > > > +++ b/Documentation/driver-api/usb/URB.rst
> > > > @@ -274,6 +274,24 @@ If you specify your own start frame, make sure it's
> > > > several frames in advance of the current frame. You might want this
> > > > model
> > > > if you're synchronizing ISO data with some other event stream.
> > > >
> > > > +.. note::
> > > > +
> > > > + Several host drivers require that the ``transfer_buffer`` to be
> > > > aligned
> > > > + with the CPU word size (e. g. DWORD for 32 bits, QDWORD for 64
> > > > bits).
> > >
> > > Is it the CPU word size or the DMA transfer size ? I assume the latter,
> > > and I wouldn't be surprised if the alignment requirement was 32-bit on at
> > > least some of the 64-bit platforms.
> >
> > Yeah, it is actually the DMA transfer size. Yet, worse case scenario is that
> > the DMA transfer size to be 64 bits on 64 bits CPU.
> >
> > > > + It is up to USB drivers should ensure that they'll only pass buffers
> > > > + with such alignments.
> > > > +
> > > > + Please also notice that, due to such restriction, the host driver
> > >
> > > s/notice/note/ (and below as well) ?
> >
> > OK.
> >
> > > > + may also override PAD bytes at the end of the ``transfer_buffer``,
> > > > up to the
> > > > + size of the CPU word.
> > >
> > > "May" is quite weak here. If some host controller drivers require buffers
> > > to be aligned, then it's an API requirement, and all buffers must be
> > > aligned. I'm not even sure I would mention that some host drivers require
> > > it, I think we should just state that the API requires buffers to be
> > > aligned.
> >
> > What I'm trying to say here is that, on a 32-bits system, if the driver do
> > a USB_DIR_IN transfer using some code similar to:
> >
> > size = 4;
> > buffer = kmalloc(size, GFP_KERNEL);
> >
> > usb_control_msg(udev, pipe, req, type, val, idx, buffer + 2, 2,
> timeout);
> > usb_control_msg(udev, pipe, req, type, val, idx, buffer, size,
> timeout);
> >
> > Drivers like dwc2 will mess with the buffer.
> >
> > The first transfer will actually work, due to a workaround inside the
> > driver that will create a temporary DWORD-aligned buffer, avoiding it
> > to go past the buffer.
> >
> > However, the second transfer will destroy the data received from the
> > first usb_control_msg(), as it will write 4 bytes at the buffer.
> >
> > Not all drivers would do that, though.
> >
> > Please notice that, as kmalloc will always return a CPU-aligned buffer,
> > if the client do something like:
> >
> > size = 2;
> > buffer = kmalloc(size, GFP_KERNEL);
> >
> > usb_control_msg(udev, pipe, req, type, val, idx, buffer, 2, timeout);
> >
> > What happens there is that the DMA engine will still write 4 bytes at
> > the buffer, but the 2 bytes that go past the end of buffer will be
> > written on a memory that will never be used.
>
> I understand that, but stating that host controller drivers "may" do this
> won't help much. If they *may*, all USB device drivers *must* align buffers
> correctly. That's the part that needs to be documented. Let's not confuse
> developers by only stating that something may happened, let's be clear and
> tell what they must do.
Ok, rewrote the entire text. Please see if the new version
works better.
>
> > > > + Please notice that ancillary routines that transfer URBs, like
> > > > + usb_control_msg() also have such restriction.
> > > > +
> > > > + Such word alignment condition is normally ensured if the buffer is
> > > > + allocated with kmalloc(), but this may not be the case if the driver
> > > > + allocates a bigger buffer and point to a random place inside it.
> > > > +
> > > >
> > > > How to start interrupt (INT) transfers?
> > > > =======================================
> > > >
> > > > diff --git a/drivers/usb/core/message.c b/drivers/usb/core/message.c
> > > > index 4c38ea41ae96..1662a4446475 100644
> > > > --- a/drivers/usb/core/message.c
> > > > +++ b/drivers/usb/core/message.c
> > > > @@ -128,6 +128,21 @@ static int usb_internal_control_msg(struct
> > > > usb_device
> > > > *usb_dev, * make sure your disconnect() method can wait for it to
> > > > complete.
> > > > Since you * don't have a handle on the URB used, you can't cancel the
> > > > request. *
> > > > + * .. note::
> > > > + *
> > > > + * Several host drivers require that the @data buffer to be aligned
> > > > + * with the CPU word size (e. g. DWORD for 32 bits, QDWORD for 64
> > > > bits).
> > > > + * It is up to USB drivers should ensure that they'll only pass
> > > > buffers
> > > > + * with such alignments.
> > > > + *
> > > > + * Please also notice that, due to such restriction, the host driver
> > > > + * may also override PAD bytes at the end of the @data buffer, up to
> > > > the
> > > > + * size of the CPU word.
> > > > + *
> > > > + * Such word alignment condition is normally ensured if the buffer is
> > > > + * allocated with kmalloc(), but this may not be the case if the
> > > > driver
> > > > + * allocates a bigger buffer and point to a random place inside it.
> > > > + *
> > > >
> > > > * Return: If successful, the number of bytes transferred. Otherwise, a
> > > >
> > > > negative * error number.
> > > >
> > > > */
> > > >
> > > > diff --git a/include/linux/usb.h b/include/linux/usb.h
> > > > index 7e68259360de..8b5ad6624708 100644
> > > > --- a/include/linux/usb.h
> > > > +++ b/include/linux/usb.h
> > > > @@ -1373,6 +1373,24 @@ typedef void (*usb_complete_t)(struct urb *);
> > > >
> > > > * capable, assign NULL to it, so that usbmon knows not to use the
> > > > value.
> > > > * The setup_packet must always be set, so it cannot be located in
> > > > highmem.
> > > >
> > > > *
> > > > + * .. note::
> > > > + *
> > > > + * Several host drivers require that the @transfer_buffer to be
> > > > aligned
> > > > + * with the CPU word size (e. g. DWORD for 32 bits, QDWORD for 64
> > > > bits).
> > > > + * It is up to USB drivers should ensure that they'll only pass
> > > > buffers
> > > > + * with such alignments.
> > > > + *
> > > > + * Please also notice that, due to such restriction, the host driver
> > > > + * may also override PAD bytes at the end of the @transfer_buffer, up
> > > > to
> > > > the + * size of the CPU word.
> > > > + *
> > > > + * Please notice that ancillary routines that start URB transfers,
> > > > like
> > > > + * usb_control_msg() also have such restriction.
> > > > + *
> > > > + * Such word alignment condition is normally ensured if the buffer is
> > > > + * allocated with kmalloc(), but this may not be the case if the
> > > > driver
> > > > + * allocates a bigger buffer and point to a random place inside it.
> > > > + *
> > >
> > > Couldn't we avoid three copies of the same text ? The chance they will get
> > > out-of-sync is quite high.
> >
> > IMHO, it is better to document it at those 3 parts, as this issue
> > cause buffer overflows, which is pretty serious, as it corrupts data.
> >
> > The URB.rst file contains a quick overview of the URB data transfers,
> > and it is likely where a kernel newbie would read first. Experienced
> > programmers will look at urb.h.
> >
> > usb_control_msg() is a different function, that one might not be
> > expecting to have the same issues.
>
> If you add the complete explanation to URB.rst, you can then reference it from
> the functions' kerneldoc instead of copying it.
True, but URB.txt has a note saying that the document may not be
fully updated, implying that urb.h header is the main reference.
So, I stand that the best here is to have this warning duplicated,
as this is a pretty serious issue and will require people to review
all USB drivers.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 52+ messages in thread
* Re: [PATCH 22/22] usb: document that URB transfer_buffer should be aligned
2017-03-29 22:15 ` Laurent Pinchart
2017-03-30 1:06 ` Mauro Carvalho Chehab
@ 2017-03-30 8:11 ` Oliver Neukum
2017-03-30 9:34 ` Laurent Pinchart
1 sibling, 1 reply; 52+ messages in thread
From: Oliver Neukum @ 2017-03-30 8:11 UTC (permalink / raw)
To: Laurent Pinchart, Mauro Carvalho Chehab
Cc: David Mosberger, Jaejoong Kim, Mauro Carvalho Chehab,
Mauro Carvalho Chehab, Greg Kroah-Hartman, linux-rpi-kernel,
Jonathan Corbet, Wolfram Sang, John Youn, Roger Quadros,
Linux Doc Mailing List, Linux Media Mailing List, linux-usb
Am Donnerstag, den 30.03.2017, 01:15 +0300 schrieb Laurent Pinchart:
> > + may also override PAD bytes at the end of the ``transfer_buffer``, up to
> > the
> > + size of the CPU word.
>
> "May" is quite weak here. If some host controller drivers require buffers to
> be aligned, then it's an API requirement, and all buffers must be aligned. I'm
> not even sure I would mention that some host drivers require it, I think we
> should just state that the API requires buffers to be aligned.
That effectively changes the API. Many network drivers are written with
the assumption that any contiguous buffer is valid. In fact you could
argue that those drivers are buggy and must use bounce buffers in those
cases.
So we need to include the full story here.
Regards
Oliver
^ permalink raw reply [flat|nested] 52+ messages in thread
* Re: [PATCH 22/22] usb: document that URB transfer_buffer should be aligned
2017-03-30 8:11 ` Oliver Neukum
@ 2017-03-30 9:34 ` Laurent Pinchart
2017-03-30 10:28 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 52+ messages in thread
From: Laurent Pinchart @ 2017-03-30 9:34 UTC (permalink / raw)
To: Oliver Neukum
Cc: Mauro Carvalho Chehab, David Mosberger, Jaejoong Kim,
Mauro Carvalho Chehab, Mauro Carvalho Chehab, Greg Kroah-Hartman,
linux-rpi-kernel, Jonathan Corbet, Wolfram Sang, John Youn,
Roger Quadros, Linux Doc Mailing List, Linux Media Mailing List,
linux-usb
Hi Oliver,
On Thursday 30 Mar 2017 10:11:31 Oliver Neukum wrote:
> Am Donnerstag, den 30.03.2017, 01:15 +0300 schrieb Laurent Pinchart:
> > > + may also override PAD bytes at the end of the ``transfer_buffer``,
> > > up to the
> > > + size of the CPU word.
> >
> > "May" is quite weak here. If some host controller drivers require buffers
> > to be aligned, then it's an API requirement, and all buffers must be
> > aligned. I'm not even sure I would mention that some host drivers require
> > it, I think we should just state that the API requires buffers to be
> > aligned.
>
> That effectively changes the API. Many network drivers are written with
> the assumption that any contiguous buffer is valid. In fact you could
> argue that those drivers are buggy and must use bounce buffers in those
> cases.
>
> So we need to include the full story here.
I personally don't care much about whose side is responsible for handling the
alignment constraints, but I want it to be documented before "fixing" any USB
driver.
--
Regards,
Laurent Pinchart
^ permalink raw reply [flat|nested] 52+ messages in thread
* Re: [PATCH 22/22] usb: document that URB transfer_buffer should be aligned
2017-03-30 9:34 ` Laurent Pinchart
@ 2017-03-30 10:28 ` Mauro Carvalho Chehab
2017-03-30 11:07 ` David Laight
` (2 more replies)
0 siblings, 3 replies; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-30 10:28 UTC (permalink / raw)
To: Laurent Pinchart
Cc: Oliver Neukum, David Mosberger, Jaejoong Kim,
Mauro Carvalho Chehab, Mauro Carvalho Chehab, Greg Kroah-Hartman,
linux-rpi-kernel, Jonathan Corbet, Wolfram Sang, John Youn,
Roger Quadros, Linux Doc Mailing List, Linux Media Mailing List,
linux-usb
Em Thu, 30 Mar 2017 12:34:32 +0300
Laurent Pinchart <laurent.pinchart@ideasonboard.com> escreveu:
> Hi Oliver,
>
> On Thursday 30 Mar 2017 10:11:31 Oliver Neukum wrote:
> > Am Donnerstag, den 30.03.2017, 01:15 +0300 schrieb Laurent Pinchart:
> > > > + may also override PAD bytes at the end of the ``transfer_buffer``,
> > > > up to the
> > > > + size of the CPU word.
> > >
> > > "May" is quite weak here. If some host controller drivers require buffers
> > > to be aligned, then it's an API requirement, and all buffers must be
> > > aligned. I'm not even sure I would mention that some host drivers require
> > > it, I think we should just state that the API requires buffers to be
> > > aligned.
> >
> > That effectively changes the API. Many network drivers are written with
> > the assumption that any contiguous buffer is valid. In fact you could
> > argue that those drivers are buggy and must use bounce buffers in those
> > cases.
Blaming the dwc2 driver was my first approach, but such patch got nacked ;)
Btw, the dwc2 driver has a routine that creates a temporary buffer if the
buffer pointer is not DWORD aligned. My first approach were to add
a logic there to also use the temporary buffer if the buffer size is
not DWORD aligned:
https://patchwork.linuxtv.org/patch/40093/
While debugging this issue, I saw *a lot* of network-generated URB
traffic from RPi3 Ethernet port drivers that were using non-aligned
buffers and were subject to the temporary buffer conversion.
My understanding here is that having a temporary bounce buffer sucks,
as the performance and latency are affected. So, I see the value of
adding this constraint to the API, pushing the task of getting
aligned buffers to the USB drivers, but you're right: that means a lot
of work, as all USB drivers should be reviewed.
Btw, I'm a lot more concerned about USB storage drivers. When I was
discussing about this issue at the #raspberrypi-devel IRC channel,
someone complained that, after switching from the RPi downstream Kernel
to upstream, his USB data storage got corrupted. Well, if the USB
storage drivers also assume that the buffer can be continuous,
that can corrupt data.
That's why I think that being verbose here is a good idea.
I'll rework on this patch to put more emphasis about this issue.
> >
> > So we need to include the full story here.
>
> I personally don't care much about whose side is responsible for handling the
> alignment constraints, but I want it to be documented before "fixing" any USB
> driver.
>
Thanks,
Mauro
^ permalink raw reply [flat|nested] 52+ messages in thread* RE: [PATCH 22/22] usb: document that URB transfer_buffer should be aligned
2017-03-30 10:28 ` Mauro Carvalho Chehab
@ 2017-03-30 11:07 ` David Laight
2017-03-30 12:05 ` Laurent Pinchart
2017-03-30 12:56 ` Oliver Neukum
2 siblings, 0 replies; 52+ messages in thread
From: David Laight @ 2017-03-30 11:07 UTC (permalink / raw)
To: 'Mauro Carvalho Chehab', Laurent Pinchart,
netdev@vger.kernel.org
Cc: Oliver Neukum, David Mosberger, Jaejoong Kim,
Mauro Carvalho Chehab, Mauro Carvalho Chehab, Greg Kroah-Hartman,
linux-rpi-kernel@lists.infradead.org, Jonathan Corbet,
Wolfram Sang, John Youn, Roger Quadros, Linux Doc Mailing List,
Linux Media Mailing List, linux-usb@vger.kernel.org
From: Mauro Carvalho Chehab
> Sent: 30 March 2017 11:28
...
> While debugging this issue, I saw *a lot* of network-generated URB
> traffic from RPi3 Ethernet port drivers that were using non-aligned
> buffers and were subject to the temporary buffer conversion.
Buffers from the network stack will almost always be 4n+2 aligned.
Receive data being fed into the network stack really needs to be
4n=2 aligned.
The USB stack almost certainly has to live with that.
If the USB ethernet device doesn't have two bytes of 'pad' before
the frame data (destination MAC address) then you have to solve
the problem within the USB stack.
For transmits it might be possible to send an initial 2 byte fragment
from a separate buffer - but only if arbitrary fragment sizes are
allowed.
A normal USB3 controller should allow this - but you have to be very
careful about what happens at the end of the ring.
David
^ permalink raw reply [flat|nested] 52+ messages in thread
* Re: [PATCH 22/22] usb: document that URB transfer_buffer should be aligned
2017-03-30 10:28 ` Mauro Carvalho Chehab
2017-03-30 11:07 ` David Laight
@ 2017-03-30 12:05 ` Laurent Pinchart
2017-03-30 12:37 ` Mauro Carvalho Chehab
2017-03-30 12:56 ` Oliver Neukum
2 siblings, 1 reply; 52+ messages in thread
From: Laurent Pinchart @ 2017-03-30 12:05 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Oliver Neukum, David Mosberger, Jaejoong Kim,
Mauro Carvalho Chehab, Mauro Carvalho Chehab, Greg Kroah-Hartman,
linux-rpi-kernel, Jonathan Corbet, Wolfram Sang, John Youn,
Roger Quadros, Linux Doc Mailing List, Linux Media Mailing List,
linux-usb
Hi Mauro,
On Thursday 30 Mar 2017 07:28:00 Mauro Carvalho Chehab wrote:
> Em Thu, 30 Mar 2017 12:34:32 +0300 Laurent Pinchart escreveu:
> > On Thursday 30 Mar 2017 10:11:31 Oliver Neukum wrote:
> >> Am Donnerstag, den 30.03.2017, 01:15 +0300 schrieb Laurent Pinchart:
> >>>> + may also override PAD bytes at the end of the
> >>>> ``transfer_buffer``, up to the
> >>>> + size of the CPU word.
> >>>
> >>> "May" is quite weak here. If some host controller drivers require
> >>> buffers to be aligned, then it's an API requirement, and all buffers
> >>> must be aligned. I'm not even sure I would mention that some host
> >>> drivers require it, I think we should just state that the API requires
> >>> buffers to be aligned.
> >>
> >> That effectively changes the API. Many network drivers are written with
> >> the assumption that any contiguous buffer is valid. In fact you could
> >> argue that those drivers are buggy and must use bounce buffers in those
> >> cases.
>
> Blaming the dwc2 driver was my first approach, but such patch got nacked ;)
>
> Btw, the dwc2 driver has a routine that creates a temporary buffer if the
> buffer pointer is not DWORD aligned. My first approach were to add
> a logic there to also use the temporary buffer if the buffer size is
> not DWORD aligned:
> https://patchwork.linuxtv.org/patch/40093/
>
> While debugging this issue, I saw *a lot* of network-generated URB
> traffic from RPi3 Ethernet port drivers that were using non-aligned
> buffers and were subject to the temporary buffer conversion.
>
> My understanding here is that having a temporary bounce buffer sucks,
> as the performance and latency are affected. So, I see the value of
> adding this constraint to the API, pushing the task of getting
> aligned buffers to the USB drivers,
This could however degrade performances when the HCD can handle unaligned
buffers.
> but you're right: that means a lot of work, as all USB drivers should be
> reviewed.
If we decide in the end to push the constraint on the USB device driver side,
then the dwc2 HCD driver should return an error when the buffer isn't
correctly aligned.
> Btw, I'm a lot more concerned about USB storage drivers. When I was
> discussing about this issue at the #raspberrypi-devel IRC channel,
> someone complained that, after switching from the RPi downstream Kernel
> to upstream, his USB data storage got corrupted. Well, if the USB
> storage drivers also assume that the buffer can be continuous,
> that can corrupt data.
>
> That's why I think that being verbose here is a good idea.
>
> I'll rework on this patch to put more emphasis about this issue.
>
> >> So we need to include the full story here.
> >
> > I personally don't care much about whose side is responsible for handling
> > the alignment constraints, but I want it to be documented before "fixing"
> > any USB driver.
--
Regards,
Laurent Pinchart
^ permalink raw reply [flat|nested] 52+ messages in thread
* Re: [PATCH 22/22] usb: document that URB transfer_buffer should be aligned
2017-03-30 12:05 ` Laurent Pinchart
@ 2017-03-30 12:37 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-30 12:37 UTC (permalink / raw)
To: Laurent Pinchart
Cc: Oliver Neukum, David Mosberger, Jaejoong Kim,
Mauro Carvalho Chehab, Mauro Carvalho Chehab, Greg Kroah-Hartman,
linux-rpi-kernel, Jonathan Corbet, Wolfram Sang, John Youn,
Roger Quadros, Linux Doc Mailing List, Linux Media Mailing List,
linux-usb
Em Thu, 30 Mar 2017 15:05:30 +0300
Laurent Pinchart <laurent.pinchart@ideasonboard.com> escreveu:
> Hi Mauro,
>
> On Thursday 30 Mar 2017 07:28:00 Mauro Carvalho Chehab wrote:
> > Em Thu, 30 Mar 2017 12:34:32 +0300 Laurent Pinchart escreveu:
> > > On Thursday 30 Mar 2017 10:11:31 Oliver Neukum wrote:
> > >> Am Donnerstag, den 30.03.2017, 01:15 +0300 schrieb Laurent Pinchart:
> > >>>> + may also override PAD bytes at the end of the
> > >>>> ``transfer_buffer``, up to the
> > >>>> + size of the CPU word.
> > >>>
> > >>> "May" is quite weak here. If some host controller drivers require
> > >>> buffers to be aligned, then it's an API requirement, and all buffers
> > >>> must be aligned. I'm not even sure I would mention that some host
> > >>> drivers require it, I think we should just state that the API requires
> > >>> buffers to be aligned.
> > >>
> > >> That effectively changes the API. Many network drivers are written with
> > >> the assumption that any contiguous buffer is valid. In fact you could
> > >> argue that those drivers are buggy and must use bounce buffers in those
> > >> cases.
> >
> > Blaming the dwc2 driver was my first approach, but such patch got nacked ;)
> >
> > Btw, the dwc2 driver has a routine that creates a temporary buffer if the
> > buffer pointer is not DWORD aligned. My first approach were to add
> > a logic there to also use the temporary buffer if the buffer size is
> > not DWORD aligned:
> > https://patchwork.linuxtv.org/patch/40093/
> >
> > While debugging this issue, I saw *a lot* of network-generated URB
> > traffic from RPi3 Ethernet port drivers that were using non-aligned
> > buffers and were subject to the temporary buffer conversion.
> >
> > My understanding here is that having a temporary bounce buffer sucks,
> > as the performance and latency are affected. So, I see the value of
> > adding this constraint to the API, pushing the task of getting
> > aligned buffers to the USB drivers,
>
> This could however degrade performances when the HCD can handle unaligned
> buffers.
No, it won't degrade performance out there, except if the driver
would need to do double buffering due to such constraint.
It will just waste memory.
>
> > but you're right: that means a lot of work, as all USB drivers should be
> > reviewed.
>
> If we decide in the end to push the constraint on the USB device driver side,
> then the dwc2 HCD driver should return an error when the buffer isn't
> correctly aligned.
Yeah, with such constraint, either the HCD drivers or the USB core
should complain.
There is another option: to add a field, filled by te USB driver,
telling the core that the buffer is aligned, e. g. drivers would
be doing something like:
urb->transfer_buffer_align = 4;
Something similar could be filled by the HCD driver:
hc_driver->transfer_buffer_align = 4;
The core will then check if the alignment required by the HCD driver
is compatible with the buffer alignment ensured by the USB driver.
If it doesn't, then the core would create a temporary buffer for the
transfers.
No idea about how easy/hard would be to implement something like
that.
In such case, it could make sense to generate a warning that
the driver should be fixed, or that the performance would
decrease due to double-buffering.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 52+ messages in thread
* Re: [PATCH 22/22] usb: document that URB transfer_buffer should be aligned
2017-03-30 10:28 ` Mauro Carvalho Chehab
2017-03-30 11:07 ` David Laight
2017-03-30 12:05 ` Laurent Pinchart
@ 2017-03-30 12:56 ` Oliver Neukum
2017-03-30 14:26 ` Alan Stern
2 siblings, 1 reply; 52+ messages in thread
From: Oliver Neukum @ 2017-03-30 12:56 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Laurent Pinchart
Cc: David Mosberger, Jaejoong Kim, Mauro Carvalho Chehab,
Mauro Carvalho Chehab, GregKroah-Hartman, linux-rpi-kernel,
Jonathan Corbet, Wolfram Sang, John Youn, Roger Quadros,
Linux Doc MailingList, Linux Media Mailing List, linux-usb
Am Donnerstag, den 30.03.2017, 07:28 -0300 schrieb Mauro Carvalho
Chehab:
> Em Thu, 30 Mar 2017 12:34:32 +0300
> Laurent Pinchart <laurent.pinchart@ideasonboard.com> escreveu:
>
> >
Hi,
> > > That effectively changes the API. Many network drivers are written with
> > > the assumption that any contiguous buffer is valid. In fact you could
> > > argue that those drivers are buggy and must use bounce buffers in those
> > > cases.
>
> Blaming the dwc2 driver was my first approach, but such patch got nacked ;)
That I am afraid was a mistake in a certain sense. This belongs into
usbcore. It does not belong into controller drivers or device drivers.
> Btw, the dwc2 driver has a routine that creates a temporary buffer if the
> buffer pointer is not DWORD aligned. My first approach were to add
> a logic there to also use the temporary buffer if the buffer size is
> not DWORD aligned:
> https://patchwork.linuxtv.org/patch/40093/
>
> While debugging this issue, I saw *a lot* of network-generated URB
> traffic from RPi3 Ethernet port drivers that were using non-aligned
> buffers and were subject to the temporary buffer conversion.
>
> My understanding here is that having a temporary bounce buffer sucks,
> as the performance and latency are affected. So, I see the value of
If you need it, you need it. Doing this in the device driver isn't any
less problematic in terms of performance. The only thing we can do
is do it in a central place to avoid code duplication.
> adding this constraint to the API, pushing the task of getting
> aligned buffers to the USB drivers, but you're right: that means a lot
> of work, as all USB drivers should be reviewed.
And it is wrong. To be blunt: The important drivers are EHCI and XHCI.
We must not degrade performance with them for the sake of controllers
with less capabilities.
> Btw, I'm a lot more concerned about USB storage drivers. When I was
> discussing about this issue at the #raspberrypi-devel IRC channel,
> someone complained that, after switching from the RPi downstream Kernel
> to upstream, his USB data storage got corrupted. Well, if the USB
> storage drivers also assume that the buffer can be continuous,
> that can corrupt data.
>
> That's why I think that being verbose here is a good idea.
They do assume that.
> I'll rework on this patch to put more emphasis about this issue.
For now that is the best. But even in the medium term this sucks.
At a minimum controller drivers need to export what they can do.
Regards
Oliver
^ permalink raw reply [flat|nested] 52+ messages in thread
* Re: [PATCH 22/22] usb: document that URB transfer_buffer should be aligned
2017-03-30 12:56 ` Oliver Neukum
@ 2017-03-30 14:26 ` Alan Stern
2017-03-30 15:45 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 52+ messages in thread
From: Alan Stern @ 2017-03-30 14:26 UTC (permalink / raw)
To: Oliver Neukum
Cc: Mauro Carvalho Chehab, Laurent Pinchart, David Mosberger,
Jaejoong Kim, Mauro Carvalho Chehab, Mauro Carvalho Chehab,
GregKroah-Hartman, linux-rpi-kernel, Jonathan Corbet,
Wolfram Sang, John Youn, Roger Quadros, Linux Doc MailingList,
Linux Media Mailing List, USB list
On Thu, 30 Mar 2017, Oliver Neukum wrote:
> > Btw, I'm a lot more concerned about USB storage drivers. When I was
> > discussing about this issue at the #raspberrypi-devel IRC channel,
> > someone complained that, after switching from the RPi downstream Kernel
> > to upstream, his USB data storage got corrupted. Well, if the USB
> > storage drivers also assume that the buffer can be continuous,
> > that can corrupt data.
>
> They do assume that.
Wait a minute. Where does that assumption occur?
And exactly what is the assumption? Mauro wrote "the buffer can be
continuous", but that is certainly not what he meant.
Alan Stern
^ permalink raw reply [flat|nested] 52+ messages in thread
* Re: [PATCH 22/22] usb: document that URB transfer_buffer should be aligned
2017-03-30 14:26 ` Alan Stern
@ 2017-03-30 15:45 ` Mauro Carvalho Chehab
2017-03-30 15:55 ` Alan Stern
0 siblings, 1 reply; 52+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-30 15:45 UTC (permalink / raw)
To: Alan Stern
Cc: Oliver Neukum, Laurent Pinchart, David Mosberger, Jaejoong Kim,
Mauro Carvalho Chehab, Mauro Carvalho Chehab, GregKroah-Hartman,
linux-rpi-kernel, Jonathan Corbet, Wolfram Sang, John Youn,
Roger Quadros, Linux Doc MailingList, Linux Media Mailing List,
USB list
Em Thu, 30 Mar 2017 10:26:32 -0400 (EDT)
Alan Stern <stern@rowland.harvard.edu> escreveu:
> On Thu, 30 Mar 2017, Oliver Neukum wrote:
>
> > > Btw, I'm a lot more concerned about USB storage drivers. When I was
> > > discussing about this issue at the #raspberrypi-devel IRC channel,
> > > someone complained that, after switching from the RPi downstream Kernel
> > > to upstream, his USB data storage got corrupted. Well, if the USB
> > > storage drivers also assume that the buffer can be continuous,
> > > that can corrupt data.
>
> >
> > They do assume that.
>
> Wait a minute. Where does that assumption occur?
>
> And exactly what is the assumption? Mauro wrote "the buffer can be
> continuous", but that is certainly not what he meant.
What I meant to say is that drivers like the uvcdriver (and maybe network and
usb-storage drivers) may allocate a big buffer and get data there on some
random order, e. g.:
int get_from_buf_pos(char *buf, int pos, int size)
{
/* or an equivalent call to usb_submit_urb() */
usb_control_msg(..., buf + pos, size, ...);
}
some_function ()
{
...
chr *buf = kzalloc(4, GFP_KERNEL);
/*
* Access the bytes at the array on a random order, with random size,
* Like:
*/
get_from_buf_pos(buf, 2, 2); /* should read 0x56, 0x78 */
get_from_buf_pos(buf, 0, 2); /* should read 0x12, 0x34 */
/*
* the expected value for the buffer would be:
* { 0x12, 0x34, 0x56, 0x78 }
*/
E. g. they assume that the transfer URB can work with any arbitrary
pointer and size, without needing of pre-align them.
This doesn't work with HCD drivers like dwc2, as each USB_IN operation will
actually write 4 bytes to the buffer.
So, what happens, instead, is that each data transfer will get four
bytes. Due to a hack inside dwc2, with checks if the transfer_buffer
is DWORD aligned. So, the first transfer will do what's expected: it will
read 4 bytes to a temporary buffer, allocated inside the driver,
copying just two bytes to buf. So, after the first read, the
buffer content will be:
buf = { 0x00, x00, 0x56, 0x78 }
But, on the second read, it won't be using any temporary
buffer. So, instead of reading a 16-bits word (0x5678),
it will actually read 32 bits, with 16-bits with some random value,
causing a buffer overflow. E. g. buffer content will now be:
buf = { 0x12, x34, 0xde, 0xad }
In other words, the second transfer corrupted the data from the
first transfer.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 52+ messages in thread* Re: [PATCH 22/22] usb: document that URB transfer_buffer should be aligned
2017-03-30 15:45 ` Mauro Carvalho Chehab
@ 2017-03-30 15:55 ` Alan Stern
2017-03-30 20:16 ` Laurent Pinchart
2017-03-30 20:57 ` Oliver Neukum
0 siblings, 2 replies; 52+ messages in thread
From: Alan Stern @ 2017-03-30 15:55 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Oliver Neukum, Laurent Pinchart, David Mosberger, Jaejoong Kim,
Mauro Carvalho Chehab, Mauro Carvalho Chehab, GregKroah-Hartman,
linux-rpi-kernel, Jonathan Corbet, Wolfram Sang, John Youn,
Roger Quadros, Linux Doc MailingList, Linux Media Mailing List,
USB list
On Thu, 30 Mar 2017, Mauro Carvalho Chehab wrote:
> Em Thu, 30 Mar 2017 10:26:32 -0400 (EDT)
> Alan Stern <stern@rowland.harvard.edu> escreveu:
>
> > On Thu, 30 Mar 2017, Oliver Neukum wrote:
> >
> > > > Btw, I'm a lot more concerned about USB storage drivers. When I was
> > > > discussing about this issue at the #raspberrypi-devel IRC channel,
> > > > someone complained that, after switching from the RPi downstream Kernel
> > > > to upstream, his USB data storage got corrupted. Well, if the USB
> > > > storage drivers also assume that the buffer can be continuous,
> > > > that can corrupt data.
> >
> > >
> > > They do assume that.
> >
> > Wait a minute. Where does that assumption occur?
> >
> > And exactly what is the assumption? Mauro wrote "the buffer can be
> > continuous", but that is certainly not what he meant.
>
> What I meant to say is that drivers like the uvcdriver (and maybe network and
> usb-storage drivers) may allocate a big buffer and get data there on some
> random order, e. g.:
>
> int get_from_buf_pos(char *buf, int pos, int size)
> {
> /* or an equivalent call to usb_submit_urb() */
> usb_control_msg(..., buf + pos, size, ...);
> }
>
> some_function ()
> {
> ...
>
> chr *buf = kzalloc(4, GFP_KERNEL);
>
> /*
> * Access the bytes at the array on a random order, with random size,
> * Like:
> */
> get_from_buf_pos(buf, 2, 2); /* should read 0x56, 0x78 */
> get_from_buf_pos(buf, 0, 2); /* should read 0x12, 0x34 */
>
> /*
> * the expected value for the buffer would be:
> * { 0x12, 0x34, 0x56, 0x78 }
> */
>
> E. g. they assume that the transfer URB can work with any arbitrary
> pointer and size, without needing of pre-align them.
>
> This doesn't work with HCD drivers like dwc2, as each USB_IN operation will
> actually write 4 bytes to the buffer.
>
> So, what happens, instead, is that each data transfer will get four
> bytes. Due to a hack inside dwc2, with checks if the transfer_buffer
> is DWORD aligned. So, the first transfer will do what's expected: it will
> read 4 bytes to a temporary buffer, allocated inside the driver,
> copying just two bytes to buf. So, after the first read, the
> buffer content will be:
>
> buf = { 0x00, x00, 0x56, 0x78 }
>
> But, on the second read, it won't be using any temporary
> buffer. So, instead of reading a 16-bits word (0x5678),
> it will actually read 32 bits, with 16-bits with some random value,
> causing a buffer overflow. E. g. buffer content will now be:
>
> buf = { 0x12, x34, 0xde, 0xad }
>
> In other words, the second transfer corrupted the data from the
> first transfer.
I'm pretty sure that usb-storage does not do this, at least, not when
operating in its normal Bulk-Only-Transport mode. It never tries to
read the results of an earlier transfer after carrying out a later
transfer to any part of the same buffer.
Alan Stern
^ permalink raw reply [flat|nested] 52+ messages in thread* Re: [PATCH 22/22] usb: document that URB transfer_buffer should be aligned
2017-03-30 15:55 ` Alan Stern
@ 2017-03-30 20:16 ` Laurent Pinchart
2017-03-30 20:57 ` Oliver Neukum
1 sibling, 0 replies; 52+ messages in thread
From: Laurent Pinchart @ 2017-03-30 20:16 UTC (permalink / raw)
To: Alan Stern
Cc: Mauro Carvalho Chehab, Oliver Neukum, David Mosberger,
Jaejoong Kim, Mauro Carvalho Chehab, Mauro Carvalho Chehab,
GregKroah-Hartman, linux-rpi-kernel, Jonathan Corbet,
Wolfram Sang, John Youn, Roger Quadros, Linux Doc MailingList,
Linux Media Mailing List, USB list
Hi Alan,
On Thursday 30 Mar 2017 11:55:18 Alan Stern wrote:
> On Thu, 30 Mar 2017, Mauro Carvalho Chehab wrote:
> > Em Thu, 30 Mar 2017 10:26:32 -0400 (EDT) Alan Stern escreveu:
> >> On Thu, 30 Mar 2017, Oliver Neukum wrote:
> >>>> Btw, I'm a lot more concerned about USB storage drivers. When I was
> >>>> discussing about this issue at the #raspberrypi-devel IRC channel,
> >>>> someone complained that, after switching from the RPi downstream
> >>>> Kernel to upstream, his USB data storage got corrupted. Well, if the
> >>>> USB storage drivers also assume that the buffer can be continuous,
> >>>> that can corrupt data.
> >>>
> >>> They do assume that.
> >>
> >> Wait a minute. Where does that assumption occur?
> >>
> >> And exactly what is the assumption? Mauro wrote "the buffer can be
> >> continuous", but that is certainly not what he meant.
> >
> > What I meant to say is that drivers like the uvcdriver (and maybe network
> > and usb-storage drivers) may allocate a big buffer and get data there on
> > some random order, e. g.:
> >
> > int get_from_buf_pos(char *buf, int pos, int size)
> > {
> > /* or an equivalent call to usb_submit_urb() */
> > usb_control_msg(..., buf + pos, size, ...);
> > }
> >
> > some_function ()
> > {
> > ...
> >
> > chr *buf = kzalloc(4, GFP_KERNEL);
> >
> > /*
> > * Access the bytes at the array on a random order, with random size,
> > * Like:
> > */
> > get_from_buf_pos(buf, 2, 2); /* should read 0x56, 0x78 */
> > get_from_buf_pos(buf, 0, 2); /* should read 0x12, 0x34 */
> >
> > /*
> > * the expected value for the buffer would be:
> > * { 0x12, 0x34, 0x56, 0x78 }
> > */
> >
> > E. g. they assume that the transfer URB can work with any arbitrary
> > pointer and size, without needing of pre-align them.
> >
> > This doesn't work with HCD drivers like dwc2, as each USB_IN operation
> > will actually write 4 bytes to the buffer.
> >
> > So, what happens, instead, is that each data transfer will get four
> > bytes. Due to a hack inside dwc2, with checks if the transfer_buffer
> > is DWORD aligned. So, the first transfer will do what's expected: it will
> > read 4 bytes to a temporary buffer, allocated inside the driver,
> > copying just two bytes to buf. So, after the first read, the
> >
> > buffer content will be:
> > buf = { 0x00, x00, 0x56, 0x78 }
> >
> > But, on the second read, it won't be using any temporary
> > buffer. So, instead of reading a 16-bits word (0x5678),
> > it will actually read 32 bits, with 16-bits with some random value,
> >
> > causing a buffer overflow. E. g. buffer content will now be:
> > buf = { 0x12, x34, 0xde, 0xad }
> >
> > In other words, the second transfer corrupted the data from the
> > first transfer.
>
> I'm pretty sure that usb-storage does not do this, at least, not when
> operating in its normal Bulk-Only-Transport mode. It never tries to
> read the results of an earlier transfer after carrying out a later
> transfer to any part of the same buffer.
The uvcvideo driver does something similar. Given the size of the transfer a
bounce buffer shouldn't affect performances. Handling this in the USB core
sounds like the best solution to me.
--
Regards,
Laurent Pinchart
^ permalink raw reply [flat|nested] 52+ messages in thread* Re: [PATCH 22/22] usb: document that URB transfer_buffer should be aligned
2017-03-30 15:55 ` Alan Stern
2017-03-30 20:16 ` Laurent Pinchart
@ 2017-03-30 20:57 ` Oliver Neukum
2017-03-31 14:07 ` Alan Stern
1 sibling, 1 reply; 52+ messages in thread
From: Oliver Neukum @ 2017-03-30 20:57 UTC (permalink / raw)
To: Alan Stern, Mauro Carvalho Chehab
Cc: David Mosberger, Jaejoong Kim, Laurent Pinchart,
Mauro Carvalho Chehab, Mauro Carvalho Chehab, GregKroah-Hartman,
linux-rpi-kernel, Jonathan Corbet, Wolfram Sang, John Youn,
Roger Quadros, Linux Doc MailingList, Linux Media Mailing List,
USB list
Am Donnerstag, den 30.03.2017, 11:55 -0400 schrieb Alan Stern:
>
> I'm pretty sure that usb-storage does not do this, at least, not when
> operating in its normal Bulk-Only-Transport mode. It never tries to
> read the results of an earlier transfer after carrying out a later
> transfer to any part of the same buffer.
The storage driver takes buffers as the block layer (or sg) provide
them, does it not?
Regards
Oliver
^ permalink raw reply [flat|nested] 52+ messages in thread
* Re: [PATCH 22/22] usb: document that URB transfer_buffer should be aligned
2017-03-30 20:57 ` Oliver Neukum
@ 2017-03-31 14:07 ` Alan Stern
0 siblings, 0 replies; 52+ messages in thread
From: Alan Stern @ 2017-03-31 14:07 UTC (permalink / raw)
To: Oliver Neukum
Cc: Mauro Carvalho Chehab, David Mosberger, Jaejoong Kim,
Laurent Pinchart, Mauro Carvalho Chehab, Mauro Carvalho Chehab,
GregKroah-Hartman, linux-rpi-kernel, Jonathan Corbet,
Wolfram Sang, John Youn, Roger Quadros, Linux Doc MailingList,
Linux Media Mailing List, USB list
On Thu, 30 Mar 2017, Oliver Neukum wrote:
> Am Donnerstag, den 30.03.2017, 11:55 -0400 schrieb Alan Stern:
> >
> > I'm pretty sure that usb-storage does not do this, at least, not when
> > operating in its normal Bulk-Only-Transport mode. It never tries to
> > read the results of an earlier transfer after carrying out a later
> > transfer to any part of the same buffer.
>
> The storage driver takes buffers as the block layer (or sg) provide
> them, does it not?
Yes. But it does not read the data from an earlier transfer after
carrying out a later transfer on the same buffer.
The only possible example would be if the sense buffer for a command
occupied part of the same block as the data buffer. But this can't
happen, because the sense buffer is allocated separately by its own
kzalloc_node() call in scsi_init_request().
Alan Stern
^ permalink raw reply [flat|nested] 52+ messages in thread
* Re: [PATCH 01/22] driver-api/basics.rst: add device table header
2017-03-29 18:54 [PATCH 01/22] driver-api/basics.rst: add device table header Mauro Carvalho Chehab
` (20 preceding siblings ...)
2017-03-29 18:54 ` [PATCH 22/22] usb: document that URB transfer_buffer should be aligned Mauro Carvalho Chehab
@ 2017-03-31 1:26 ` kbuild test robot
21 siblings, 0 replies; 52+ messages in thread
From: kbuild test robot @ 2017-03-31 1:26 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: kbuild-all, Linux Media Mailing List, Linux Doc Mailing List,
Greg Kroah-Hartman, Mauro Carvalho Chehab, Mauro Carvalho Chehab,
John Youn, linux-usb, linux-rpi-kernel, Laurent Pinchart,
Jonathan Corbet, Mauro Carvalho Chehab
[-- Attachment #1: Type: text/plain, Size: 10239 bytes --]
Hi Mauro,
[auto build test WARNING on linus/master]
[also build test WARNING on v4.11-rc4 next-20170330]
[if your patch is applied to the wrong git tree, please drop us a note to help improve the system]
url: https://github.com/0day-ci/linux/commits/Mauro-Carvalho-Chehab/driver-api-basics-rst-add-device-table-header/20170331-041911
reproduce: make htmldocs
All warnings (new ones prefixed by >>):
include/linux/init.h:1: warning: no structured comments found
>> include/linux/mod_devicetable.h:676: warning: Excess struct/union/enum/typedef member 'ver_major' description in 'fsl_mc_device_id'
>> include/linux/mod_devicetable.h:676: warning: Excess struct/union/enum/typedef member 'ver_minor' description in 'fsl_mc_device_id'
kernel/sched/core.c:2085: warning: No description found for parameter 'rf'
kernel/sched/core.c:2085: warning: Excess function parameter 'cookie' description in 'try_to_wake_up_local'
include/linux/kthread.h:26: warning: Excess function parameter '...' description in 'kthread_create'
kernel/sys.c:1: warning: no structured comments found
include/linux/device.h:969: warning: No description found for parameter 'dma_ops'
drivers/dma-buf/seqno-fence.c:1: warning: no structured comments found
include/linux/iio/iio.h:597: warning: No description found for parameter 'trig_readonly'
include/linux/iio/trigger.h:151: warning: No description found for parameter 'indio_dev'
include/linux/iio/trigger.h:151: warning: No description found for parameter 'trig'
include/linux/device.h:970: warning: No description found for parameter 'dma_ops'
drivers/regulator/core.c:1467: warning: Excess function parameter 'ret' description in 'regulator_dev_lookup'
include/drm/drm_drv.h:438: warning: No description found for parameter 'open'
include/drm/drm_drv.h:438: warning: No description found for parameter 'preclose'
include/drm/drm_drv.h:438: warning: No description found for parameter 'postclose'
include/drm/drm_drv.h:438: warning: No description found for parameter 'lastclose'
include/drm/drm_drv.h:438: warning: No description found for parameter 'set_busid'
include/drm/drm_drv.h:438: warning: No description found for parameter 'irq_handler'
include/drm/drm_drv.h:438: warning: No description found for parameter 'irq_preinstall'
include/drm/drm_drv.h:438: warning: No description found for parameter 'irq_postinstall'
include/drm/drm_drv.h:438: warning: No description found for parameter 'irq_uninstall'
include/drm/drm_drv.h:438: warning: No description found for parameter 'debugfs_init'
include/drm/drm_drv.h:438: warning: No description found for parameter 'debugfs_cleanup'
include/drm/drm_drv.h:438: warning: No description found for parameter 'gem_open_object'
include/drm/drm_drv.h:438: warning: No description found for parameter 'gem_close_object'
include/drm/drm_drv.h:438: warning: No description found for parameter 'prime_handle_to_fd'
include/drm/drm_drv.h:438: warning: No description found for parameter 'prime_fd_to_handle'
include/drm/drm_drv.h:438: warning: No description found for parameter 'gem_prime_export'
include/drm/drm_drv.h:438: warning: No description found for parameter 'gem_prime_import'
include/drm/drm_drv.h:438: warning: No description found for parameter 'gem_prime_pin'
include/drm/drm_drv.h:438: warning: No description found for parameter 'gem_prime_unpin'
include/drm/drm_drv.h:438: warning: No description found for parameter 'gem_prime_res_obj'
include/drm/drm_drv.h:438: warning: No description found for parameter 'gem_prime_get_sg_table'
include/drm/drm_drv.h:438: warning: No description found for parameter 'gem_prime_import_sg_table'
include/drm/drm_drv.h:438: warning: No description found for parameter 'gem_prime_vmap'
include/drm/drm_drv.h:438: warning: No description found for parameter 'gem_prime_vunmap'
include/drm/drm_drv.h:438: warning: No description found for parameter 'gem_prime_mmap'
include/drm/drm_drv.h:438: warning: No description found for parameter 'gem_vm_ops'
include/drm/drm_drv.h:438: warning: No description found for parameter 'major'
include/drm/drm_drv.h:438: warning: No description found for parameter 'minor'
include/drm/drm_drv.h:438: warning: No description found for parameter 'patchlevel'
include/drm/drm_drv.h:438: warning: No description found for parameter 'name'
include/drm/drm_drv.h:438: warning: No description found for parameter 'desc'
include/drm/drm_drv.h:438: warning: No description found for parameter 'date'
include/drm/drm_drv.h:438: warning: No description found for parameter 'driver_features'
include/drm/drm_drv.h:438: warning: No description found for parameter 'ioctls'
include/drm/drm_drv.h:438: warning: No description found for parameter 'num_ioctls'
include/drm/drm_drv.h:438: warning: No description found for parameter 'fops'
include/drm/drm_color_mgmt.h:1: warning: no structured comments found
drivers/gpu/drm/drm_fb_cma_helper.c:557: warning: Excess function parameter 'num_crtc' description in 'drm_fbdev_cma_init'
drivers/gpu/drm/drm_fb_cma_helper.c:558: warning: Excess function parameter 'num_crtc' description in 'drm_fbdev_cma_init'
drivers/gpu/drm/i915/intel_lpe_audio.c:342: warning: No description found for parameter 'pipe'
drivers/gpu/drm/i915/intel_lpe_audio.c:342: warning: No description found for parameter 'dp_output'
drivers/gpu/drm/i915/intel_lpe_audio.c:342: warning: No description found for parameter 'link_rate'
drivers/gpu/drm/i915/intel_lpe_audio.c:343: warning: No description found for parameter 'pipe'
drivers/gpu/drm/i915/intel_lpe_audio.c:343: warning: No description found for parameter 'dp_output'
drivers/gpu/drm/i915/intel_lpe_audio.c:343: warning: No description found for parameter 'link_rate'
drivers/media/dvb-core/dvb_frontend.h:677: warning: No description found for parameter 'refcount'
Documentation/core-api/assoc_array.rst:13: WARNING: Enumerated list ends without a blank line; unexpected unindent.
Documentation/doc-guide/sphinx.rst:110: ERROR: Unknown target name: "sphinx c domain".
kernel/sched/fair.c:7616: WARNING: Inline emphasis start-string without end-string.
kernel/time/timer.c:1200: ERROR: Unexpected indentation.
kernel/time/timer.c:1202: ERROR: Unexpected indentation.
kernel/time/timer.c:1203: WARNING: Block quote ends without a blank line; unexpected unindent.
include/linux/wait.h:122: WARNING: Block quote ends without a blank line; unexpected unindent.
include/linux/wait.h:125: ERROR: Unexpected indentation.
include/linux/wait.h:127: WARNING: Block quote ends without a blank line; unexpected unindent.
kernel/time/hrtimer.c:990: WARNING: Block quote ends without a blank line; unexpected unindent.
kernel/signal.c:322: WARNING: Inline literal start-string without end-string.
include/linux/iio/iio.h:219: ERROR: Unexpected indentation.
include/linux/iio/iio.h:220: WARNING: Block quote ends without a blank line; unexpected unindent.
include/linux/iio/iio.h:226: WARNING: Definition list ends without a blank line; unexpected unindent.
drivers/iio/industrialio-core.c:639: ERROR: Unknown target name: "iio_val".
drivers/iio/industrialio-core.c:646: ERROR: Unknown target name: "iio_val".
drivers/message/fusion/mptbase.c:5051: WARNING: Definition list ends without a blank line; unexpected unindent.
drivers/tty/serial/serial_core.c:1898: WARNING: Definition list ends without a blank line; unexpected unindent.
include/linux/regulator/driver.h:271: ERROR: Unknown target name: "regulator_regmap_x_voltage".
include/linux/spi/spi.h:369: ERROR: Unexpected indentation.
drivers/usb/core/message.c:478: ERROR: Unexpected indentation.
drivers/usb/core/message.c:479: WARNING: Block quote ends without a blank line; unexpected unindent.
Documentation/driver-api/usb.rst:623: ERROR: Unknown target name: "usb_type".
Documentation/driver-api/usb.rst:623: ERROR: Unknown target name: "usb_dir".
Documentation/driver-api/usb.rst:623: ERROR: Unknown target name: "usb_recip".
Documentation/driver-api/usb.rst:689: ERROR: Unknown target name: "usbdevfs_urb_type".
sound/soc/soc-core.c:2670: ERROR: Unknown target name: "snd_soc_daifmt".
sound/core/jack.c:312: ERROR: Unknown target name: "snd_jack_btn".
WARNING: dvipng command 'dvipng' cannot be run (needed for math display), check the imgmath_dvipng setting
vim +676 include/linux/mod_devicetable.h
289fcff4 Heikki Krogerus 2015-05-13 660 };
289fcff4 Heikki Krogerus 2015-05-13 661
0afef456 Stuart Yoder 2016-06-22 662 /**
0afef456 Stuart Yoder 2016-06-22 663 * struct fsl_mc_device_id - MC object device identifier
0afef456 Stuart Yoder 2016-06-22 664 * @vendor: vendor ID
0afef456 Stuart Yoder 2016-06-22 665 * @obj_type: MC object type
0afef456 Stuart Yoder 2016-06-22 666 * @ver_major: MC object version major number
0afef456 Stuart Yoder 2016-06-22 667 * @ver_minor: MC object version minor number
0afef456 Stuart Yoder 2016-06-22 668 *
0afef456 Stuart Yoder 2016-06-22 669 * Type of entries in the "device Id" table for MC object devices supported by
0afef456 Stuart Yoder 2016-06-22 670 * a MC object device driver. The last entry of the table has vendor set to 0x0
0afef456 Stuart Yoder 2016-06-22 671 */
0afef456 Stuart Yoder 2016-06-22 672 struct fsl_mc_device_id {
0afef456 Stuart Yoder 2016-06-22 673 __u16 vendor;
0afef456 Stuart Yoder 2016-06-22 674 const char obj_type[16];
0afef456 Stuart Yoder 2016-06-22 675 };
0afef456 Stuart Yoder 2016-06-22 @676
0afef456 Stuart Yoder 2016-06-22 677
^1da177e Linus Torvalds 2005-04-16 678 #endif /* LINUX_MOD_DEVICETABLE_H */
:::::: The code at line 676 was first introduced by commit
:::::: 0afef45654ae908536278ecb143ded5bbc713391 staging: fsl-mc: add support for device table matching
:::::: TO: Stuart Yoder <stuart.yoder@nxp.com>
:::::: CC: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
---
0-DAY kernel test infrastructure Open Source Technology Center
https://lists.01.org/pipermail/kbuild-all Intel Corporation
[-- Attachment #2: .config.gz --]
[-- Type: application/gzip, Size: 6576 bytes --]
^ permalink raw reply [flat|nested] 52+ messages in thread