os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

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

Browse source
This commit is contained in:
Murray Stokely 2005-05-04 23:37:19 +00:00
parent c8495b0052
commit 2129a93f77
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=24451
2 changed files with 39 additions and 10 deletions
en_US.ISO8859-1/books/arch-handbook
scsi
chapter.sgml
usb
chapter.sgml

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

@ -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

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

@ -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
@ -219,7 +225,8 @@
<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