Add indexterms, consistently spell CD-ROM, add more descriptive markup.

svn path=/head/; revision=24451

en_US.ISO8859-1/books/arch-handbook/scsi/chapter.sgml

@@ -14,6 +14,7 @@
   <sect1 id="scsi-synopsis">
     <title>Synopsis</title>
 
+    <indexterm><primary>SCSI</primary></indexterm>
     <para>This document assumes that the reader has a general
       understanding of device drivers in FreeBSD and of the SCSI
       protocol.  Much of the information in this document was
@@ -56,6 +57,8 @@
   <sect1 id="scsi-general">
     <title>General architecture</title>
 
+    <indexterm><primary>Common Access Method (CAM)</primary></indexterm>
+
     <para>CAM stands for Common Access Method. It is a generic way to
       address the I/O buses in a SCSI-like way. This allows a
       separation of the generic device drivers from the drivers
@@ -65,9 +68,12 @@
       modified) for every new I/O bus. Thus the two most important
       active entities are:</para>
 
+    <indexterm><primary>CD-ROM</primary></indexterm>
+    <indexterm><primary>tape</primary></indexterm>
+    <indexterm><primary>IDE</primary></indexterm>
     <itemizedlist>
       <listitem><para><emphasis>Peripheral Modules</emphasis> -  a
-        driver for peripheral devices (disk, tape, CDROM,
+        driver for peripheral devices (disk, tape, CD-ROM,
         etc.)</para></listitem>
       <listitem><para><emphasis>SCSI Interface Modules </emphasis>(SIM)
         - a Host Bus Adapter drivers for connecting to an I/O bus such
@@ -113,7 +119,7 @@
         error; /* some code to handle the error */
     }</programlisting>
 
-    <para>Here SIZE is the size of the queue to be allocated, maximal
+    <para>Here <literal>SIZE</literal> is the size of the queue to be allocated, maximal
       number of requests it could contain. It is the number of requests
       that the SIM driver can handle in parallel on one SCSI
       card. Commonly it can be calculated as:</para>
@@ -135,6 +141,7 @@
       free the <structname>devq</structname> also because we can do
       nothing else with it and we want to conserve memory.</para>
 
+    <indexterm><primary>SCSI</primary><secondary>bus</secondary></indexterm>
     <para>If a SCSI card has multiple SCSI buses on it then each bus
       requires its own <structname>cam_sim</structname>
       structure.</para>
@@ -207,6 +214,7 @@
       </itemizedlist>
     </para>
 
+    <indexterm><primary>SCSI</primary><secondary>adapter</secondary></indexterm>
     <para>Finally we register the SCSI buses associated with our SCSI
       adapter:</para>
 
@@ -585,13 +593,15 @@
         return;
     }</programlisting>
 
+      <indexterm><primary>hardware control block</primary></indexterm>
+
       <para>Then allocate whatever data structures (such as
         card-dependent hardware control block) we need to process this
         request. If we can not then freeze the SIM queue and remember
         that we have a pending operation, return the CCB back and ask
         CAM to re-queue it. Later when the resources become available
         the SIM queue must be unfrozen by returning a ccb with the
-        CAM_SIMQ_RELEASE bit set in its status. Otherwise, if all went
+        <varname>CAM_SIMQ_RELEASE<varname> bit set in its status. Otherwise, if all went
         well, link the CCB with the hardware control block (HCB) and
         mark it as queued.</para>
 
@@ -630,14 +640,14 @@
         always convert the address to the physical one.</para>
 
       <para>A NOT-QUITE RELATED NOTE: Normally this is done by a call
-        to vtophys(), but for the PCI device (which account for most
+        to <function>vtophys()</function>, but for the PCI device (which account for most
         of the SCSI controllers now) drivers' portability to the Alpha
-        architecture the conversion must be done by vtobus() instead
+        architecture the conversion must be done by <function>vtobus()</function> instead
         due to special Alpha quirks.  [IMHO it would be much better to
-        have two separate functions, vtop() and ptobus() then vtobus()
+        have two separate functions, <function>vtop()</function> and <function>ptobus()</function> then <function>vtobus()</function>
         would be a simple superposition of them.]  In case if a
         physical address is requested it is OK to return the CCB with
-        the status CAM_REQ_INVALID, the current drivers do that.  But
+        the status <errname>CAM_REQ_INVALID</errname>, the current drivers do that.  But
         it is also possible to compile the Alpha-specific piece of
         code, as in this example (there should be a more direct way to
         do that, without conditional compilation in the drivers). If
@@ -687,7 +697,7 @@
         handling for the details on the address-translation issues.
         If some variation is too difficult or impossible to implement
         with a particular card it is OK to return the status
-        CAM_REQ_INVALID. Actually, it seems like the scatter-gather
+        <errname>CAM_REQ_INVALID</errname>. Actually, it seems like the scatter-gather
         ability is not used anywhere in the CAM code now. But at least
         the case for a single non-scattered virtual buffer must be
         implemented, it is actively used by CAM.</para>
@@ -795,7 +805,7 @@
       request description) and sent to the controller or the SCSI
       controller may be immediately programmed to send this RESET
       message to the device or this request may be just not supported
-      (and return the status CAM_REQ_INVALID).  Also on completion of
+      (and return the status <errname>CAM_REQ_INVALID</errname>).  Also on completion of
       the request all the disconnected transactions for this target
       must be aborted (probably in the interrupt routine).</para>
 
@@ -1213,6 +1223,8 @@ of the union ccb:</para>
       are set then the existing drivers return the current
       settings). Set all the bits in the valid field.</para></listitem>
 
+    <indexterm><primary>BIOS</primary></indexterm>
+
     <listitem><para><emphasis>XPT_CALC_GEOMETRY</emphasis> - calculate logical
       (BIOS) geometry of the disk</para>
 
@@ -1238,6 +1250,7 @@ of the union ccb:</para>
 
     </itemizedlist>
 
+    <indexterm><primary>SCSI</primary><secondary>BIOS</secondary></indexterm>
     <para>If the returned geometry differs much enough from what the
       SCSI controller BIOS thinks and a disk on this SCSI controller
       is used as bootable the system may not be able to boot. The
@@ -1493,6 +1506,8 @@ ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)<
   <sect1 id="scsi-interrupts">
     <title>Interrupts</title>
 
+    <indexterm><primary>SCSI</primary><secondary>interrupts</secondary></indexterm>
+
     <para>The exact type of the interrupt routine depends on the type
       of the peripheral bus (PCI, ISA and so on) to which the SCSI
       controller is connected.</para>
@@ -1856,6 +1871,8 @@ ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)<
   <sect1 id="scsi-errors">
     <title>Errors Summary</title>
 
+    <indexterm><primary>SCSI</primary><secondary>errors</secondary></indexterm>
+
     <para>When executing an I/O request many things may go wrong. The
       reason of error can be reported in the CCB status with great
       detail. Examples of use are spread throughout this document. For

en_US.ISO8859-1/books/arch-handbook/usb/chapter.sgml

@@ -13,6 +13,9 @@
   <sect1 id="usb-intro">
     <title>Introduction</title>
 
+    <indexterm><primary>Universal Serial Bus (USB)</primary></indexterm>
+    <indexterm><primary>NetBSD</primary></indexterm>
+
     <para>The Universal Serial Bus (USB) is a new way of attaching
       devices to personal computers. The bus architecture features
       two-way communication and has been developed as a response to
@@ -108,6 +111,7 @@
   <sect1 id="usb-hc">
     <title>Host Controllers</title>
 
+    <indexterm><primary>USB</primary><secondary>host controllers</secondary></indexterm>
     <para>The host controller (HC) controls the transmission of
       packets on the bus. Frames of 1 millisecond are used. At the
       start of each frame the host controller generates a Start of
@@ -166,6 +170,8 @@
     <sect2>
       <title>UHCI</title>
 
+    <indexterm><primary>USB</primary><secondary>UHCI</secondary></indexterm>
+
       <para>The UHCI host controller maintains a framelist with 1024
         pointers to per frame data structures. It understands two
         different data types: transfer descriptors (TD) and queue
@@ -220,6 +226,7 @@
     <sect2>
       <title>OHCI</title>
 
+      <indexterm><primary>USB</primary><secondary>OHCI</secondary></indexterm>      
       <para>Programming an OHCI host controller is much simpler. The
         controller assumes that a set of endpoints is available, and
         is aware of scheduling priorities and the ordering of the
@@ -446,6 +453,7 @@
   <sect1 id="usb-devprobe">
     <title>Device probe and attach</title>
 
+    <indexterm><primary>USB</primary><secondary>probe</secondary></indexterm>      
     <para>After the notification by the hub that a new device has been
       connected, the service layer switches on the port, providing the
       device with 100 mA of current. At this point the device is in
@@ -485,6 +493,7 @@
     <sect2>
       <title>Device disconnect and detach</title>
 
+      <indexterm><primary>USB</primary><secondary>disconnect</secondary></indexterm>      
       <para>A device driver should expect to receive errors during any
         transaction with the device. The design of USB supports and
         encourages the disconnection of devices at any point in
@@ -568,6 +577,7 @@
       interface and allocate the pipes to the two independent
       endpoints.</para>
 
+    <indexterm><primary>USB</primary><secondary>firmware</secondary></indexterm>
     <para>Example: Firmware download Many devices that have been
       developed are based on a general purpose processor with
       an additional USB core added to it. Because the development of
@@ -600,6 +610,8 @@
       emulating a SCSI controller over the USB wire. ATAPI and UFI
       commands are supported in a similar fashion.</para>
 
+    <indexterm><primary>ATAPI</primary></indexterm>
+
     <para>The Mass Storage Specification supports 2 different types of
       wrapping of the command block.The initial attempt was based on
       sending the command and status through the default pipe and