Date: Wed, 13 Feb 2002 21:55:40 +0000 From: Ceri <setantae@submonkey.net> To: FreeBSD-gnats-submit@freebsd.org Subject: docs/34916: Developer's Handbook fixes continued: ISA chapter Message-ID: <E16b7NM-000AsX-00@rhadamanth.private.submonkey.net>
next in thread | raw e-mail | index | archive | help
>Number: 34916
>Category: docs
>Synopsis: Developer's Handbook fixes continued: ISA chapter
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: doc-bug
>Submitter-Id: current-users
>Arrival-Date: Wed Feb 13 14:00:02 PST 2002
>Closed-Date:
>Last-Modified:
>Originator: Ceri <setantae@submonkey.net>
>Release: FreeBSD 4.5-STABLE i386
>Organization:
>Environment:
System: FreeBSD rhadamanth.private.submonkey.net 4.5-STABLE FreeBSD 4.5-STABLE #0: Tue Feb 12 17:56:57 GMT 2002 setantae@rhadamanth.private.submonkey.net:/usr/obj/usr/src/sys/RHADAMANTH i386
>Description:
Quite petty changes really.
- Couple of spelling errors.
- Change " for <quote>
- Minor grammatical changes
Ceri
>How-To-Repeat:
>Fix:
--- doc/en_US.ISO8859-1/books/developers-handbook/isa/chapter.sgml.old Wed Feb 13 20:58:48 2002
+++ doc/en_US.ISO8859-1/books/developers-handbook/isa/chapter.sgml Wed Feb 13 21:51:36 2002
@@ -242,15 +242,15 @@
colon to the message.</para>
<para>The device_t methods are implemented in the file
- kern/bus_subr.c.</para>
+ <filename>kern/bus_subr.c</filename>.</para>
</sect1>
<sect1>
- <title>Config file and the order of identifying and probing
+ <title>Configuration file and the order of identifying and probing
during auto-configuration</title>
- <para>The ISA devices are described in the kernel config file
+ <para>The ISA devices are described in the kernel configuration file
like:</para>
<programlisting>device xxx0 at isa? port 0x300 irq 10 drq 5
@@ -258,7 +258,7 @@
<para>The values of port, IRQ and so on are converted to the
resource values associated with the device. They are optional,
- depending on the device needs and abilities for
+ depending on the device's needs and abilities for
auto-configuration. For example, some devices do not need DRQ
at all and some allow the driver to read the IRQ setting from
the device configuration ports. If a machine has multiple ISA
@@ -266,7 +266,7 @@
line, like "isa0" or "isa1", otherwise the device would be
searched for on all the ISA buses.</para>
- <para>"sensitive" is a resource requesting that this device must
+ <para><quote>sensitive</quote> is a resource requesting that this device must
be probed before all non-sensitive devices. It is supported
but does not seem to be used in any current driver.</para>
@@ -307,7 +307,7 @@
prevent them from being probed as legacy devices.</para>
<para>The probe routines of non-PnP devices marked as
- "sensitive" are called. If probe for a device went
+ <quote>sensitive</quote> are called. If a probe for a device went
successfully, the attach routine is called for it.</para>
<para>The probe and attach routines of all non-PNP devices are
@@ -321,7 +321,7 @@
<para>Then for each PnP device the probe routines of all the
present ISA drivers are called. The first one that claims the
device gets attached. It is possible that multiple drivers
- would claim the device with different priority, the
+ would claim the device with different priority; in this case, the
highest-priority driver wins. The probe routines must call
<function>ISA_PNP_PROBE()</function> to compare the actual PnP
ID with the list of the IDs supported by the driver and if the
@@ -375,8 +375,8 @@
accessing the configuration resources directly with functions
of families <function>resource_query_*()</function> and
<function>resource_*_value()</function>. Their implementations
- are located in kern/subr_bus.h. The old IDE disk driver
- i386/isa/wd.c contains examples of such use. But the standard
+ are located in <filename>kern/subr_bus.h</filename>. The old IDE disk driver
+ <filename>i386/isa/wd.c</filename> contains examples of such use. But the standard
means of configuration must always be preferred. Leave parsing
the configuration resources to the bus configuration
code.</para>
@@ -393,8 +393,8 @@
device_t and the bus resources associated with it. The drivers
may access the configuration resources directly using
functions resource_* for more complex cases of
- configuration. But generally it is not needed nor recommended,
- so this issue is not discussed further.</para>
+ configuration. However, generally this is neither needed nor recommended,
+ so this issue is not discussed further here.</para>
<para>The bus resources are associated with each device. They
are identified by type and number within the type. For the ISA
@@ -424,12 +424,12 @@
</itemizedlist>
<para>The enumeration within types starts from 0, so if a device
- has two memory regions if would have resources of type
+ has two memory regions it would have resources of type
SYS_RES_MEMORY numbered 0 and 1. The resource type has
nothing to do with the C language type, all the resource
values have the C language type "unsigned long" and must be
cast as necessary. The resource numbers do not have to be
- contiguous although for ISA they normally would be. The
+ contiguous, although for ISA they normally would be. The
permitted resource numbers for ISA devices are:</para>
<programlisting> IRQ: 0-1
@@ -438,8 +438,8 @@
IOPORT: 0-7</programlisting>
<para>All the resources are represented as ranges, with a start
- value and count. For IRQ and DRQ resources the count would be
- normally equal to 1. The values for memory refer to the
+ value and count. For IRQ and DRQ resources the count would
+ normally be equal to 1. The values for memory refer to the
physical addresses.</para>
<para>Three types of activities can be performed on
@@ -455,7 +455,7 @@
reserves the requested range that no other driver would be
able to reserve it (and checking that no other driver reserved
this range already). Activation makes the resource accessible
- to the driver doing whatever is necessary for that (for
+ to the driver by doing whatever is necessary for that (for
example, for memory it would be mapping into the kernel
virtual address space).</para>
@@ -468,8 +468,8 @@
<para>Set a range for a resource. Returns 0 if successful,
error code otherwise. Normally the only reason this
- function would return an error is value of type, rid,
- start or count out of permitted range.</para>
+ function would return an error is if the value of type, rid,
+ start or count were out of permitted range.</para>
<itemizedlist>
<listitem>
@@ -505,7 +505,7 @@
has 0 among the legitimate values it would be impossible
to tell if the value is 0 or an error occurred. Luckily,
no ISA resources for add-on drivers may have a start value
- equal 0.</para>
+ equal to 0.</para>
</listitem>
<listitem>
@@ -671,7 +671,7 @@
</listitem>
</itemizedlist>
- <para>A number of methods is defined to operate on the resource
+ <para>A number of methods are defined to operate on the resource
handlers (struct resource *). Those of interest to the device
driver writers are:</para>
@@ -696,9 +696,9 @@
device through the memory. Two variants are possible:</para>
<para>(a) memory is located on the device card</para>
- <para>(b) memory is the main memory of computer</para>
+ <para>(b) memory is the main memory of the computer</para>
- <para>In the case (a) the driver always copies the data back and
+ <para>In case (a) the driver always copies the data back and
forth between the on-card memory and the main memory as
necessary. To map the on-card memory into the kernel virtual
address space the physical address and length of the on-card
@@ -717,13 +717,12 @@
limitation on the ISA bus). In that case if the machine has
more memory than the start address of the device memory (in
other words, they overlap) a memory hole must be configured at
- the address range used by devices. Many BIOSes allow to
- configure a memory hole of 1MB starting at 14MB or
+ the address range used by devices. Many BIOSes allow
+ configuration of a memory hole of 1MB starting at 14MB or
15MB. FreeBSD can handle the memory holes properly if the BIOS
- reports them properly (old BIOSes may have this feature
- broken).</para>
+ reports them properly (this feature may be broken on old BIOSes).</para>
- <para>In the case (b) just the address of the data is sent to
+ <para>In case (b) just the address of the data is sent to
the device, and the device uses DMA to actually access the
data in the main memory. Two limitations are present: First,
ISA cards can only access memory below 16MB. Second, the
@@ -741,7 +740,7 @@
<para>Tags are organized into a tree-like hierarchy with
inheritance of the properties. A child tag inherits all the
- requirements of its parent tag or may make them more strict
+ requirements of its parent tag, and may make them more strict
but never more loose.</para>
<para>Normally one top-level tag (with no parent) is created for
@@ -770,7 +769,7 @@
reading the data would go from the device to the bounce pages
and then copied to their non-conformant original pages. The
process of copying between the original and bounce pages is
- called synchronization. This is normally used on per-transfer
+ called synchronization. This is normally used on a per-transfer
basis: buffer for each transfer would be loaded, transfer done
and buffer unloaded.</para>
@@ -795,8 +794,11 @@
allocated for this tag. Use value 1 for "no specific
alignment". Applies only to the future
<function>bus_dmamem_alloc()</function> but not
- <function>bus_dmamap_create()</function> calls.
- <emphasis>boundary</emphasis> - physical address
+ <function>bus_dmamap_create()</function> calls.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>boundary</emphasis> - physical address
boundary that must not be crossed when allocating the
memory. Use value 0 for "no boundary". Applies only to
the future <function>bus_dmamem_alloc()</function> but
@@ -811,7 +813,7 @@
<listitem>
<para><emphasis>lowaddr, highaddr</emphasis> - the names
- are slighlty misleading; these values are used to limit
+ are slightly misleading; these values are used to limit
the permitted range of physical addresses used to
allocate the memory. The exact meaning varies depending
on the planned future use:</para>
@@ -853,7 +855,7 @@
[lowaddr; highaddr] is passed to the filter function
which decides if it is accessible. The prototype of the
filter function is: <function>int filterfunc(void *arg,
- bus_addr_t paddr)</function> It must return 0 if the
+ bus_addr_t paddr)</function>. It must return 0 if the
page is accessible, non-zero otherwise.</para>
</listitem>
@@ -875,9 +877,9 @@
BUS_SPACE_UNRESTRICTED may not be used to actually load
maps, they may be used only as parent tags. The
practical limit for nsegments seems to be about 250-300,
- higher values will cause kernel stack overflow. But
- anyway the hardware normally can not support that many
- scatter-gather buffers.</para>
+ higher values will cause kernel stack overflow (the hardware
+ can not normally support that many
+ scatter-gather buffers anyway).</para>
</listitem>
<listitem>
@@ -895,7 +897,7 @@
<listitem>
<para><emphasis>BUS_DMA_ALLOCNOW</emphasis> - requests
to allocate all the potentially needed bounce pages
- when creating the tag</para>
+ when creating the tag.</para>
</listitem>
<listitem>
@@ -910,7 +912,7 @@
<listitem>
<para><emphasis>dmat</emphasis> - pointer to the storage
- for the new tag to be returned</para>
+ for the new tag to be returned.</para>
</listitem>
</itemizedlist>
@@ -924,7 +926,7 @@
<para>Destroy a tag. Returns 0 on success, the error code
otherwise.</para>
- <para>dmat - the tag to be destroyed</para>
+ <para>dmat - the tag to be destroyed.</para>
</listitem>
@@ -937,7 +939,7 @@
tag. The size of memory to be allocated is tag's maxsize.
Returns 0 on success, the error code otherwise. The result
still has to be loaded by
- <function>bus_dmamap_load()</function> before used to get
+ <function>bus_dmamap_load()</function> before being used to get
the physical address of the memory.</para>
<!-- XXX What it is Wylie, I got to here -->
@@ -965,8 +967,8 @@
<emphasis>BUS_DMA_NOWAIT</emphasis> - if the
memory is not immediately available return the
error. If this flag is not set then the routine
- is allowed to sleep waiting until the memory
- will become available.
+ is allowed to sleep until the memory
+ becomes available.
</para>
</listitem>
</itemizedlist>
@@ -974,7 +976,7 @@
<listitem>
<para>
<emphasis>mapp</emphasis> - pointer to the storage
- for the new map to be returned
+ for the new map to be returned.
</para>
</listitem>
</itemizedlist>
@@ -987,7 +989,7 @@
</para>
<para>
Free the memory allocated by
- <function>bus_dmamem_alloc()</function>. As of now
+ <function>bus_dmamem_alloc()</function>. At present,
freeing of the memory allocated with ISA restrictions is
not implemented. Because of this the recommended model
of use is to keep and re-use the allocated areas for as
@@ -1038,7 +1040,7 @@
<listitem>
<para>
<emphasis>flags</emphasis> - theoretically, a bit map
- of flags. But no flags are defined yet, so as of now
+ of flags. But no flags are defined yet, so at present
it will be always 0.
</para>
</listitem>
@@ -1532,7 +1534,7 @@
<para>
Release a previously reserved DMA channel. No
transfers must be in progress when the channel is
- released (as well as the device must not try to
+ released (in addition the device must not try to
initiate transfer after the channel is released).
</para>
</listitem>
@@ -1682,8 +1684,8 @@
will be automatically reset back to the length of
buffer. The normal use is to check the number of bytes
left after the device signals that the transfer is
- completed. If the number of bytes is not 0 then probably
- something went wrong with that transfer.
+ completed. If the number of bytes is not 0 then something
+ probably went wrong with that transfer.
</para>
</listitem>
@@ -1753,8 +1755,8 @@
resources before returning and if necessary allocate them
again in the attach routine. When
<function>xxx_isa_probe()</function> returns 0 releasing the
- resources before returning is also a good idea, a
- well-behaved driver should do so. But in case if there is
+ resources before returning is also a good idea and a
+ well-behaved driver should do so. But in cases where there is
some problem with releasing the resources the driver is
allowed to keep resources between returning 0 from the probe
routine and execution of the attach routine.
@@ -1895,8 +1897,8 @@
better to be done in <function>probe()</function>: if this
probe would drive some other sensitive device crazy. The
probe routines are ordered with consideration of the
- "sensitive" flag: the sensitive devices get probed first and
- the rest of devices later. But the
+ <quote>sensitive</quote> flag: the sensitive devices get probed first and
+ the other devices later. But the
<function>identify()</function> routines are called before
any probes, so they show no respect to the sensitive devices
and may upset them.
@@ -2201,7 +2203,7 @@
the convention suggests passing the pointer to structure
softc. The important reason is that when the structures
softc are allocated dynamically then getting the unit number
- from softc is easy while getting softc from unit number is
+ from softc is easy while getting softc from the unit number is
difficult. Also this convention makes the drivers for
different buses look more uniform and allows them to share
the code: each bus gets its own probe, attach, detach and
@@ -2349,14 +2351,14 @@
the ISA devices. The ability to unload a driver may be
useful when debugging it, but in many cases installation of
the new version of the driver would be required only after
- the old version somehow wedges the system and reboot will be
+ the old version somehow wedges the system and a reboot will be
needed anyway, so the efforts spent on writing the detach
- routine may not be worth it. Another argument is that
+ routine may not be worth it. Another argument that
unloading would allow upgrading the drivers on a production
machine seems to be mostly theoretical. Installing a new
version of a driver is a dangerous operation which should
never be performed on a production machine (and which is not
- permitted when the system is running in secure mode). Still
+ permitted when the system is running in secure mode). Still,
the detach routine may be provided for the sake of
completeness.
</para>
@@ -2388,7 +2390,7 @@
transfers, disabling the DMA channels and interrupts to
avoid memory corruption by the device. For most of the
drivers this is exactly what the shutdown routine does, so
- if it is included in the driver we can as well just call it.
+ if it is included in the driver we can just call it.
</para>
<para><function>xxx_isa_shutdown(dev);</function></para>
@@ -2416,7 +2418,7 @@
disabling DMA and interrupts in the device registers and
stopping any ongoing transfers is a good idea. The exact
action depends on the hardware, so we do not consider it here
- in any details.
+ in any detail.
</para>
</sect1>
@@ -2426,17 +2428,17 @@
<para>
The interrupt handler is called when an interrupt is
received which may be from this particular device. The ISA
- bus does not support interrupt sharing (except some special
+ bus does not support interrupt sharing (except in some special
cases) so in practice if the interrupt handler is called
then the interrupt almost for sure came from its
- device. Still the interrupt handler must poll the device
+ device. Still, the interrupt handler must poll the device
registers and make sure that the interrupt was generated by
its device. If not it should just return.
</para>
<para>
The old convention for the ISA drivers was getting the
- device unit number as an argument. It is obsolete, and the
+ device unit number as an argument. This is obsolete, and the
new drivers receive whatever argument was specified for them
in the attach routine when calling
<function>bus_setup_intr()</function>. By the new convention
>Release-Note:
>Audit-Trail:
>Unformatted:
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?E16b7NM-000AsX-00>