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

Various grammar, typo and syntax fixes.

Browse source 
PR:		docs/34916
Submitted by:	Ceri <setantae@submonkey.net>
This commit is contained in:
Giorgos Keramidas 2002-02-16 23:35:35 +00:00
parent 830c679cc9
commit 5c3012928b
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=12216
2 changed files with 120 additions and 112 deletions
en_US.ISO8859-1/books
arch-handbook/isa
chapter.sgml
developers-handbook/isa
chapter.sgml

116
en_US.ISO8859-1/books/arch-handbook/isa/chapter.sgml
View file

@ -247,10 +247,10 @@
</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
@ -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
@ -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 <literal>unsigned long</literal> 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>
@ -467,9 +467,11 @@
int rid, u_long start, u_long count)</function></para>
<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>
error code otherwise. Normally, this function will
return an error only if one of <literal>type</literal>,
<literal>rid</literal>, <literal>start</literal> or
<literal>count</literal> has a value that falls out of the
permitted range.</para>
<itemizedlist>
<listitem>
@ -505,7 +507,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 +673,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 +698,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 +719,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 +742,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 +771,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 +796,11 @@
allocated for this tag. Use value 1 for <quote>no specific
alignment</quote>. 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 <quote>no boundary</quote>. Applies only to
the future <function>bus_dmamem_alloc()</function> but
@ -811,7 +815,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 +857,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 +879,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 +899,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 +914,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 +928,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 +941,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 +969,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 +978,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 +991,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 +1042,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 +1536,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 +1686,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 +1757,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.
@ -1896,7 +1900,7 @@
probe would drive some other sensitive device crazy. The
probe routines are ordered with consideration of the
<literal>sensitive</literal> flag: the sensitive devices get probed first and
the rest of devices later. But the
the rest of the 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 +2205,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 +2353,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 +2392,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 +2420,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 +2430,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

116
en_US.ISO8859-1/books/developers-handbook/isa/chapter.sgml
View file

@ -247,10 +247,10 @@
</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
@ -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
@ -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 <literal>unsigned long</literal> 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>
@ -467,9 +467,11 @@
int rid, u_long start, u_long count)</function></para>
<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>
error code otherwise. Normally, this function will
return an error only if one of <literal>type</literal>,
<literal>rid</literal>, <literal>start</literal> or
<literal>count</literal> has a value that falls out of the
permitted range.</para>
<itemizedlist>
<listitem>
@ -505,7 +507,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 +673,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 +698,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 +719,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 +742,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 +771,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 +796,11 @@
allocated for this tag. Use value 1 for <quote>no specific
alignment</quote>. 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 <quote>no boundary</quote>. Applies only to
the future <function>bus_dmamem_alloc()</function> but
@ -811,7 +815,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 +857,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 +879,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 +899,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 +914,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 +928,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 +941,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 +969,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 +978,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 +991,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 +1042,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 +1536,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 +1686,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 +1757,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.
@ -1896,7 +1900,7 @@
probe would drive some other sensitive device crazy. The
probe routines are ordered with consideration of the
<literal>sensitive</literal> flag: the sensitive devices get probed first and
the rest of devices later. But the
the rest of the 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 +2205,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 +2353,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 +2392,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 +2420,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 +2430,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