Merge branch 'doc-tweaks' into docs-next
The creation of the admin and process guides is a great thing, but, without
care, we risk replacing a messy docs directory with a few messy Sphinx
books. In an attempt to head that off and show what I'm thinking, here's a
set of tweaks that, I think, make the existing Sphinx-formatted docs a bit
more accessible.
diff --git a/Documentation/80211/conf.py b/Documentation/80211/conf.py
index 20c7c27..4424b4b 100644
--- a/Documentation/80211/conf.py
+++ b/Documentation/80211/conf.py
@@ -3,3 +3,8 @@
project = "Linux 802.11 Driver Developer's Guide"
tags.add("subproject")
+
+latex_documents = [
+ ('index', '80211.tex', project,
+ 'The kernel development community', 'manual'),
+]
diff --git a/Documentation/80211/index.rst b/Documentation/80211/index.rst
index 90bba47..af21085 100644
--- a/Documentation/80211/index.rst
+++ b/Documentation/80211/index.rst
@@ -9,7 +9,7 @@
mac80211
mac80211-advanced
-.. only:: subproject
+.. only:: subproject and html
Indices
=======
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.
</para>
<para>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.
- </para>
-
- <para>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).
</para>
<para>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 <filename>/sbin/hotplug</filename> 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.
</para>
<para>Linux can run inside USB devices as well as on
@@ -121,12 +106,17 @@
<listitem><para>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.
</para></listitem>
- <listitem><para>Configurations have one or more "interfaces", each
+ <listitem><para>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.
+ </para></listitem>
+
+ <listitem><para>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.</para>
@@ -135,7 +125,7 @@
Think of them as "interface drivers", though you
may not see many devices where the distinction is important.
<emphasis>Most USB devices are simple, with only one configuration,
- one interface, and one alternate setting.</emphasis>
+ one function, one interface, and one alternate setting.</emphasis>
</para></listitem>
<listitem><para>Interfaces have one or more "endpoints", each of
@@ -161,26 +151,25 @@
<para>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.
</para>
<para>The only host-side drivers that actually touch hardware
(reading/writing registers, handling IRQs, and so on) are the HCDs.
In theory, all HCDs provide the same functionality through the same
- API. In practice, that's becoming more true on the 2.5 kernels,
+ API. In practice, that's becoming mostly true,
but there are still differences that crop up especially with
- fault handling. Different controllers don't necessarily report
+ fault handling on the less common controllers.
+ Different controllers don't necessarily report
the same aspects of failures, and recovery from faults (including
software-induced ones like unlinking an URB) isn't yet fully
consistent.
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
HCD-specific behavior.
- (You will need external USB 1.1 and/or
- USB 2.0 hubs to perform all those tests.)
</para>
</chapter>
@@ -216,7 +205,7 @@
<para>There are two basic I/O models in the USB API.
The most elemental one is asynchronous: drivers submit requests
in the form of an URB, and the URB's completion callback
- handle the next step.
+ handles the next step.
All USB transfer types support that model, although there
are special cases for control URBs (which always have setup
and status stages, but may not have a data stage) and
@@ -252,7 +241,7 @@
<para>These APIs are only for use by host controller drivers,
most of which implement standard register interfaces such as
- EHCI, OHCI, or UHCI.
+ XHCI, EHCI, OHCI, or UHCI.
UHCI was one of the first interfaces, designed by Intel and
also used by VIA; it doesn't do much in hardware.
OHCI was designed later, to have the hardware do more work
@@ -260,13 +249,16 @@
EHCI was designed with USB 2.0; its design has features that
resemble OHCI (hardware does much more work) as well as
UHCI (some parts of ISO support, TD list processing).
+ XHCI was designed with USB 3.0. It continues to shift support
+ for functionality into hardware.
</para>
<para>There are host controllers other than the "big three",
although most PCI based controllers (and a few non-PCI based
ones) use one of those interfaces.
Not all host controllers use DMA; some use PIO, and there
- is also a simulator.
+ is also a simulator and a virtual host controller to pipe
+ USB over the network.
</para>
<para>The same basic APIs are available to drivers for all
@@ -275,7 +267,7 @@
<structname>struct usb_bus</structname> is a rather thin
layer that became available in the 2.2 kernels, while
<structname>struct usb_hcd</structname> is a more featureful
- layer (available in later 2.4 kernels and in 2.5) that
+ layer that
lets HCDs share common code, to shrink driver size
and significantly reduce hcd-specific behaviors.
</para>
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 2872c0c..368845e 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -58,3 +58,10 @@
binfmt-misc
mono
java
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/dev-tools/conf.py b/Documentation/dev-tools/conf.py
new file mode 100644
index 0000000..7faafa3
--- /dev/null
+++ b/Documentation/dev-tools/conf.py
@@ -0,0 +1,10 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = "Development tools for the kernel"
+
+tags.add("subproject")
+
+latex_documents = [
+ ('index', 'dev-tools.tex', project,
+ 'The kernel development community', 'manual'),
+]
diff --git a/Documentation/dev-tools/tools.rst b/Documentation/dev-tools/index.rst
similarity index 86%
rename from Documentation/dev-tools/tools.rst
rename to Documentation/dev-tools/index.rst
index 824ae8e..07d8811 100644
--- a/Documentation/dev-tools/tools.rst
+++ b/Documentation/dev-tools/index.rst
@@ -23,3 +23,11 @@
kmemleak
kmemcheck
gdb-kernel-debugging
+
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/driver-api/conf.py b/Documentation/driver-api/conf.py
new file mode 100644
index 0000000..202726d
--- /dev/null
+++ b/Documentation/driver-api/conf.py
@@ -0,0 +1,10 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = "The Linux driver implementer's API guide"
+
+tags.add("subproject")
+
+latex_documents = [
+ ('index', 'driver-api.tex', project,
+ 'The kernel development community', 'manual'),
+]
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index b567907..e18135b 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -25,3 +25,11 @@
hsi
miscellaneous
vme
+
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/gpu/conf.py b/Documentation/gpu/conf.py
index 6314d17..1757b04 100644
--- a/Documentation/gpu/conf.py
+++ b/Documentation/gpu/conf.py
@@ -3,3 +3,8 @@
project = "Linux GPU Driver Developer's Guide"
tags.add("subproject")
+
+latex_documents = [
+ ('index', 'gpu.tex', project,
+ 'The kernel development community', 'manual'),
+]
diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst
index be0dafc..367d7c3 100644
--- a/Documentation/gpu/index.rst
+++ b/Documentation/gpu/index.rst
@@ -14,7 +14,7 @@
vga-switcheroo
vgaarbiter
-.. only:: subproject
+.. only:: subproject and html
Indices
=======
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 7cec843..85a6627 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -37,7 +37,7 @@
:maxdepth: 2
process/index
- dev-tools/tools
+ dev-tools/index
kernel-documentation
Kernel API documentation
diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst
index 0557144c..10aa692 100644
--- a/Documentation/process/index.rst
+++ b/Documentation/process/index.rst
@@ -49,3 +49,9 @@
magic-number
volatile-considered-harmful
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`