On Thu, 20 Oct 2016, Oliver Neukum wrote:
> This just is the result of the conversion script and its addition
> to the index. Just the plain automatic conversion.
How does this relate to [1]? Why does this not remove the .tmpl file?
BR,
Jani.
[1] http://lkml.kernel.org/r/1476969300-9603-1-git-send-email-oneu...@suse.com
>
> Signed-off-by: Oliver Neukum
> ---
> Documentation/index.rst | 1 +
> Documentation/usb/conf.py | 5 +
> Documentation/usb/usb.rst | 750
> ++
> 3 files changed, 756 insertions(+)
> create mode 100644 Documentation/usb/conf.py
> create mode 100644 Documentation/usb/usb.rst
>
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index c53d089..a5bbd22 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -18,6 +18,7 @@ Contents:
> media/index
> gpu/index
> 80211/index
> + usb/usb
>
> Indices and tables
> ==
> diff --git a/Documentation/usb/conf.py b/Documentation/usb/conf.py
> new file mode 100644
> index 000..308f907
> --- /dev/null
> +++ b/Documentation/usb/conf.py
> @@ -0,0 +1,5 @@
> +# -*- coding: utf-8; mode: python -*-
> +
> +project = "Linux USB project documentation and manual"
> +
> +tags.add("subproject")
> diff --git a/Documentation/usb/usb.rst b/Documentation/usb/usb.rst
> new file mode 100644
> index 000..dbbd14d
> --- /dev/null
> +++ b/Documentation/usb/usb.rst
> @@ -0,0 +1,750 @@
> +===
> +The Linux-USB Host Side API
> +===
> +
> +Introduction to USB on Linux
> +
> +
> +A Universal Serial Bus (USB) is used to connect a host, such as a PC or
> +workstation, to a number of peripheral devices. USB uses a tree
> +structure, with the host as the root (the system's master), hubs as
> +interior nodes, and peripherals as leaves (and slaves). Modern PCs
> +support several such trees of USB devices, usually a few USB 3.0 (5
> +GBit/s) or USB 3.1 (10 GBit/s) and some legacy USB 2.0 (480 MBit/s)
> +busses just in case.
> +
> +That master/slave asymmetry was designed-in for a number of reasons, one
> +being ease of use. It is not physically possible to mistake upstream and
> +downstream or it does not matter with a type C plug (or they are built
> +into the peripheral). Also, the host software doesn't need to deal with
> +distributed auto-configuration since the pre-designated master node
> +manages all that.
> +
> +Kernel developers added USB support to Linux early in the 2.2 kernel
> +series and have been developing it further since then. Besides support
> +for each new generation of USB, various host controllers gained support,
> +new drivers for peripherals have been added and advanced features for
> +latency measurement and improved power management introduced.
> +
> +Linux can run inside USB devices as well as on the hosts that control
> +the devices. But USB device drivers running inside those peripherals
> +don't do the same things as the ones running inside hosts, so they've
> +been given a different name: *gadget drivers*. This document does not
> +cover gadget drivers.
> +
> +USB Host-Side API Model
> +===
> +
> +Host-side drivers for USB devices talk to the "usbcore" APIs. There are
> +two. One is intended for *general-purpose* drivers (exposed through
> +driver frameworks), and the other is for drivers that are *part of the
> +core*. Such core drivers include the *hub* driver (which manages trees
> +of USB devices) and several different kinds of *host controller
> +drivers*, which control individual busses.
> +
> +The device model seen by USB drivers is relatively complex.
> +
> +- USB supports four kinds of data transfers (control, bulk, interrupt,
> + and isochronous). Two of them (control and bulk) use bandwidth as
> + it's available, while the other two (interrupt and isochronous) are
> + scheduled to provide guaranteed bandwidth.
> +
> +- The device description model includes one or more "configurations"
> + per device, only one of which is active at a time. Devices are
> + supposed to be capable of operating at lower than their top speeds
> + and may provide a BOS descriptor showing the lowest speed they remain
> + fully operational at.
> +
> +- From USB 3.0 on configurations have one or more "functions", which
> + provide a common functionality and are grouped together for purposes
> + of power management.
> +
> +- Configurations or functions have one or more "interfaces", each of
> + which may have "alternate settings". Interfaces may be standardized
> + by USB "Class" specifications, or may be specific to a vendor or
> + device.
> +
> + USB device drivers actually bind to interfaces, not devices. Think of
> + them as "interface drivers", though you may not see many devices
> + where the distinction is important. *Most USB devices are simple,
> + with only one