Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 34132326 authored by Sam Bishop's avatar Sam Bishop Committed by Greg Kroah-Hartman
Browse files

USB: doc patch 1 



Grammar, spelling, and stylistic edits.

Signed-off-by: default avatarSam Bishop <sam@bishop.dhs.org>
Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@suse.de>
parent 39c2f3ac

Documentation/DocBook/usb.tmpl

+44 −54
Original line number Original line Diff line number Diff line
@@ -43,59 +43,52 @@ 




    <para>A Universal Serial Bus (USB) is used to connect a host,

    <para>A Universal Serial Bus (USB) is used to connect a host,

    such as a PC or workstation, to a number of peripheral

    such as a PC or workstation, to a number of peripheral

    devices.  USB uses a tree structure, with the host at the

    devices.  USB uses a tree structure, with the host as the

    root (the system's master), hubs as interior nodes, and

    root (the system's master), hubs as interior nodes, and

    peripheral devices as leaves (and slaves).

    peripherals as leaves (and slaves).

    Modern PCs support several such trees of USB devices, usually

    Modern PCs support several such trees of USB devices, usually

    one USB 2.0 tree (480 Mbit/sec each) with

    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

    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".

    connect a USB 1.1 device directly to the machine's "root hub".

    </para>

    </para>





    <para>That master/slave asymmetry was designed in part for

    <para>That master/slave asymmetry was designed-in for a number of

    ease of use.  It is not physically possible to assemble

    reasons, one being ease of use.  It is not physically possible to

    (legal) USB cables incorrectly:  all upstream "to-the-host"

    assemble (legal) USB cables incorrectly:  all upstream "to the host"

    connectors are the rectangular type, matching the sockets on

    connectors are the rectangular type (matching the sockets on

    root hubs, and the downstream type are the squarish type

    root hubs), and all downstream connectors are the squarish type

    (or they are built into the peripheral).

    (or they are built into the peripheral).

    Software doesn't need to deal with distributed autoconfiguration

    Also, the host software doesn't need to deal with distributed

    since the pre-designated master node manages all that.

    auto-configuration since the pre-designated master node manages all that.

    At the electrical level, bus protocol overhead is reduced by

    And finally, at the electrical level, bus protocol overhead is reduced by

    eliminating arbitration and moving scheduling into host software.

    eliminating arbitration and moving scheduling into the host software.

    </para>

    </para>





    <para>USB 1.0 was announced in January 1996, and was revised

    <para>USB 1.0 was announced in January 1996 and was revised

    as USB 1.1 (with improvements in hub specification and

    as USB 1.1 (with improvements in hub specification and

    support for interrupt-out transfers) in September 1998.

    support for interrupt-out transfers) in September 1998.

    USB 2.0 was released in April 2000, including high speed

    USB 2.0 was released in April 2000, adding high-speed

    transfers and transaction translating hubs (used for USB 1.1

    transfers and transaction-translating hubs (used for USB 1.1

    and 1.0 backward compatibility).

    and 1.0 backward compatibility).

    </para>

    </para>





    <para>USB support was added to Linux early in the 2.2 kernel series

    <para>Kernel developers added USB support to Linux early in the 2.2 kernel

    shortly before the 2.3 development forked off.  Updates

    series, shortly before 2.3 development forked.  Updates from 2.3 were

    from 2.3 were regularly folded back into 2.2 releases, bringing

    regularly folded back into 2.2 releases, which improved reliability and

    new features such as <filename>/sbin/hotplug</filename> support,

    brought <filename>/sbin/hotplug</filename> support as well more drivers.

    more drivers, and more robustness.

    Such improvements were continued in the 2.5 kernel series, where they added

    The 2.5 kernel series continued such improvements, and also

    USB 2.0 support, improved performance, and made the host controller drivers

    worked on USB 2.0 support,

    (HCDs) more consistent.  They also simplified the API (to make bugs less

    higher performance,

    likely) and added internal "kerneldoc" documentation.

    better consistency between host controller drivers,

    API simplification (to make bugs less likely),

    and providing internal "kerneldoc" documentation.

    </para>

    </para>





    <para>Linux can run inside USB devices as well as on

    <para>Linux can run inside USB devices as well as on

    the hosts that control the devices.

    the hosts that control the devices.

    Because the Linux 2.x USB support evolved to support mass market

    But USB device drivers running inside those peripherals

    platforms such as Apple Macintosh or PC-compatible systems,

    it didn't address design concerns for those types of USB systems.

    So it can't be used inside mass-market PDAs, or other peripherals.

    USB device drivers running inside those Linux peripherals

    don't do the same things as the ones running inside hosts,

    don't do the same things as the ones running inside hosts,

    and so they've been given a different name:

    so they've been given a different name:

    they're called <emphasis>gadget drivers</emphasis>.

    <emphasis>gadget drivers</emphasis>.

    This document does not present gadget drivers.

    This document does not cover gadget drivers.

    </para>

    </para>





    </chapter>

    </chapter>
@@ -103,17 +96,14 @@ 
<chapter id="host">

<chapter id="host">

    <title>USB Host-Side API Model</title>

    <title>USB Host-Side API Model</title>





    <para>Within the kernel,

    <para>Host-side drivers for USB devices talk to the "usbcore" APIs.

    host-side drivers for USB devices talk to the "usbcore" APIs.

    There are two.  One is intended for

    There are two types of public "usbcore" APIs, targetted at two different

    <emphasis>general-purpose</emphasis> drivers (exposed through

    layers of USB driver.  Those are

    driver frameworks), and the other is for drivers that are

    <emphasis>general purpose</emphasis> drivers, exposed through

    <emphasis>part of the core</emphasis>.

    driver frameworks such as block, character, or network devices;

    Such core drivers include the <emphasis>hub</emphasis> driver

    and drivers that are <emphasis>part of the core</emphasis>,

    (which manages trees of USB devices) and several different kinds

    which are involved in managing a USB bus.

    of <emphasis>host controller drivers</emphasis>,

    Such core drivers include the <emphasis>hub</emphasis> driver,

    which manages trees of USB devices, and several different kinds

    of <emphasis>host controller driver (HCD)</emphasis>,

    which control individual busses.

    which control individual busses.

    </para>

    </para>
@@ -122,21 +112,21 @@ 
     

     

    <itemizedlist>

    <itemizedlist>





	<listitem><para>USB supports four kinds of data transfer

	<listitem><para>USB supports four kinds of data transfers

	(control, bulk, interrupt, and isochronous).  Two transfer

	(control, bulk, interrupt, and isochronous).  Two of them (control

	types use bandwidth as it's available (control and bulk),

	and bulk) use bandwidth as it's available,

	while the other two types of transfer (interrupt and isochronous)

	while the other two (interrupt and isochronous)

	are scheduled to provide guaranteed bandwidth.

	are scheduled to provide guaranteed bandwidth.

	</para></listitem>

	</para></listitem>





	<listitem><para>The device description model includes one or more

	<listitem><para>The device description model includes one or more

	"configurations" per device, only one of which is active at a time.

	"configurations" per device, only one of which is active at a time.

	Devices that are capable of high speed operation must also support

	Devices that are capable of high-speed operation must also support

	full speed configurations, along with a way to ask about the

	full-speed configurations, along with a way to ask about the

	"other speed" configurations that might be used.

	"other speed" configurations which might be used.

	</para></listitem>

	</para></listitem>





	<listitem><para>Configurations have one or more "interface", each

	<listitem><para>Configurations have one or more "interfaces", each

	of which may have "alternate settings".  Interfaces may be

	of which may have "alternate settings".  Interfaces may be

	standardized by USB "Class" specifications, or may be specific to

	standardized by USB "Class" specifications, or may be specific to

	a vendor or device.</para>

	a vendor or device.</para>
@@ -162,7 +152,7 @@ 
	</para></listitem>

	</para></listitem>





	<listitem><para>The Linux USB API supports synchronous calls for

	<listitem><para>The Linux USB API supports synchronous calls for

	control and bulk messaging.

	control and bulk messages.

	It also supports asynchnous calls for all kinds of data transfer,

	It also supports asynchnous calls for all kinds of data transfer,

	using request structures called "URBs" (USB Request Blocks).

	using request structures called "URBs" (USB Request Blocks).

	</para></listitem>

	</para></listitem>