Re: [PATCH] USB: update intro of documentation

[Jonathan Corbet]

On Mon, 24 Oct 2016 14:25:27 +0200
Greg KH  wrote:

> I don't have any objection to the changes, please take them through your
> documentation tree:

I have now done so.

Thanks,

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

Re: [PATCH] USB: update intro of documentation

[Greg KH]

On Fri, Oct 21, 2016 at 03:17:14PM -0600, Jonathan Corbet wrote:
> On Thu, 20 Oct 2016 15:15:00 +0200
> Oliver Neukum  wrote:
> 
> > It does no good to mention The 2.4 kernel series and neglect
> > USB 3.x and XHCI. Also with type C and micro/mini USB we better
> > not talk about the shape of connectors.
> 
> ...except that USB 2 connectors will be with us for some time yet.  I'm all
> for updating the documentation, but stuff like this:
> 
> >  That master/slave asymmetry was designed-in for a number of
> >  reasons, one being ease of use.  It is not physically possible to
> > -assemble (legal) USB cables incorrectly:  all upstream "to the host"
> > -connectors are the rectangular type (matching the sockets on
> > -root hubs), and all downstream connectors are the squarish type
> > +mistake upstream and downstream or it does not matter with a type C
> > +plug
> 
> seems to me like it loses information.  Greg, do you have an opinion on the
> changes here?  I'll apply this if it's OK with you.

I don't have any objection to the changes, please take them through your
documentation tree:

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

Re: [PATCH] USB: update intro of documentation

[Oliver Neukum]

On Fri, 2016-10-21 at 15:17 -0600, Jonathan Corbet wrote:
> On Thu, 20 Oct 2016 15:15:00 +0200
> Oliver Neukum  wrote:
> 
> > It does no good to mention The 2.4 kernel series and neglect
> > USB 3.x and XHCI. Also with type C and micro/mini USB we better
> > not talk about the shape of connectors.
> 
> ...except that USB 2 connectors will be with us for some time yet.  I'm all
> for updating the documentation, but stuff like this:
> 
> >  That master/slave asymmetry was designed-in for a number of
> >  reasons, one being ease of use.  It is not physically possible to
> > -assemble (legal) USB cables incorrectly:  all upstream "to the host"
> > -connectors are the rectangular type (matching the sockets on
> > -root hubs), and all downstream connectors are the squarish type
> > +mistake upstream and downstream or it does not matter with a type C
> > +plug
> 
> seems to me like it loses information.  Greg, do you have an opinion on the
> changes here?  I'll apply this if it's OK with you.

It absolutely loses information, because that information is no longer
true. We have micro and mini USB downstream and the upstream is usually
square but not universally true since On-the-Go.

Regards
Oliver


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

Re: [PATCH] USB: update intro of documentation

[Rami Rosen]

Hi Oliver,
Thanks for your patch.

Typo: Should be "their" instead of " thei1r" in the following paragraph:

>  Device driver authors should make a point of doing 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
> +thei1r own as well as to make sure they aren't relying on some

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

[PATCH] USB: update intro of documentation

[Oliver Neukum]

It does no good to mention The 2.4 kernel series and neglect
USB 3.x and XHCI. Also with type C and micro/mini USB we better
not talk about the shape of connectors.

Signed-off-by: Oliver Neukum 
---
 Documentation/DocBook/usb.tmpl | 68 +++---
 1 file changed, 30 insertions(+), 38 deletions(-)

diff --git a/Documentation/DocBook/usb.tmpl b/Documentation/DocBook/usb.tmpl
index bc776be0..8ec4d59 100644
--- a/Documentation/DocBook/usb.tmpl
+++ b/Documentation/DocBook/usb.tmpl
@@ -47,39 +47,24 @@
 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
-one USB 2.0 tree (480 Mbit/sec each) with
-a few USB 1.1 trees (12 Mbit/sec each) that are used when you
-connect a USB 1.1 device directly to the machine's "root hub".
+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
-assemble (legal) USB cables incorrectly:  all upstream "to the host"
-connectors are the rectangular type (matching the sockets on
-root hubs), and all downstream connectors are the squarish type
+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.
-And finally, at the electrical level, bus protocol overhead is reduced by
-eliminating arbitration and moving scheduling into the host software.
-
-
-USB 1.0 was announced in January 1996 and was revised
-as USB 1.1 (with improvements in hub specification and
-support for interrupt-out transfers) in September 1998.
-USB 2.0 was released in April 2000, adding high-speed
-transfers and transaction-translating hubs (used for USB 1.1
-and 1.0 backward compatibility).
 
 
 Kernel developers added USB support to Linux early in the 2.2 kernel
-series, shortly before 2.3 development forked.  Updates from 2.3 were
-regularly folded back into 2.2 releases, which improved reliability and
-brought /sbin/hotplug support as well more drivers.
-Such improvements were continued in the 2.5 kernel series, where they added
-USB 2.0 support, improved performance, and made the host controller drivers
-(HCDs) more consistent.  They also simplified the API (to make bugs less
-likely) and added internal "kerneldoc" documentation.
+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
@@ -121,12 +106,17 @@
 
The device description model includes one or more
"configurations" per device, only one of which is active at a time.
-   Devices that are capable of high-speed operation must also support
-   full-speed configurations, along with a way to ask about the
-   "other speed" configurations which might be used.
+   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 have one or more "interfaces", each
+   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.
@@ -135,7 +125,7 @@
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 configuration,
-   one interface, and one alternate setting.
+   one function, one interface, and one alternate setting.

 
Interfaces have one or more "endpoints", each of
@@ -161,26 +151,25 @@
 
 Accordingly, the USB Core API exposed to device drivers
 covers quite a lot of territory.  You'll probably need to consult
-the USB 2.0 specification, available online from www.usb.org at
+the USB 3.0 specification, available online from www.usb.org at
 no cost, as well as class or device specifications.
 
 
 The only host-side drivers that actually touch hardware
 (reading/writing