Attachment 19665 Details for Bug 34916 – file.diff

[patch] file.diff

file.diff (text/plain), 20.00 KB, created by setantae on 2002-02-13 22:00:02 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: setantae

Created: 2002-02-13 22:00:02 UTC

Size: 20.00 KB

patch

obsolete

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

Actions: View | Diff

Attachments on bug 34916: 19665