Re: [PATCH] Documentation: usb: the dumb conversion to Sphinx

[Oliver Neukum]

On Thu, 2016-10-20 at 10:29 -0600, Jonathan Corbet wrote:
> On Thu, 20 Oct 2016 18:22:28 +0200
> Oliver Neukum  wrote:
> 
> > >  Why does this not remove the .tmpl file?  
> > 
> > 1. We might want to keep it
> > 2. It is an operation beyond the scope of this patch.
> 
> I have to disagree with this part; the last thing we want is two copies of
> the documentation to get out of sync with each other.  If you're going to
> convert the template file (and I think you should!), please remove it in
> the process.
> 
> I also think that this documentation should be made part of the driver-api
> manual rather than going in at the top level.

UnderstoodThat wounds the pride of us USB developers, but I understand
the reasoning.
I shall redo the patch. Still the issue of updating the content first
remains. I'd feel more comfortable removing a least the most outdated
stuff before I convert formats.

Regards
Oliver


--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation: usb: the dumb conversion to Sphinx

[Jonathan Corbet]

On Thu, 20 Oct 2016 18:22:28 +0200
Oliver Neukum  wrote:

> >  Why does this not remove the .tmpl file?  
> 
> 1. We might want to keep it
> 2. It is an operation beyond the scope of this patch.

I have to disagree with this part; the last thing we want is two copies of
the documentation to get out of sync with each other.  If you're going to
convert the template file (and I think you should!), please remove it in
the process.

I also think that this documentation should be made part of the driver-api
manual rather than going in at the top level.

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation: usb: the dumb conversion to Sphinx

[Oliver Neukum]

On Thu, 2016-10-20 at 18:04 +0300, Jani Nikula wrote:
> On Thu, 20 Oct 2016, Oliver Neukum  wrote:

Hi,

> > 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]?

It is the second after that, as we want updated content, even if we
don't want to convert.

>  Why does this not remove the .tmpl file?

1. We might want to keep it
2. It is an operation beyond the scope of this patch.

Regards
Oliver


--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation: usb: the dumb conversion to Sphinx

[Jani Nikula]

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