Attachment #19665 for bug #34916

View | Details | Raw Unified | Return to bug 34916
Collapse All | Expand All




	colon to the message.</para>

      <para>The device_t methods are implemented in the file
        <filename>kern/bus_subr.c</filename>.</para>

    </sect1>

    <sect1>
      <title>Configuration file and the order of identifying and probing
	during auto-configuration</title>

      <para>The ISA devices are described in the kernel configuration file
  	like:</para>

      <programlisting>device xxx0 at isa? port 0x300 irq 10 drq 5


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

	line, like "isa0" or "isa1", otherwise the device would be
	searched for on all the ISA buses.</para>

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


        prevent them from being probed as legacy devices.</para>

      <para>The probe routines of non-PnP devices marked as
        <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

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

        accessing the configuration resources directly with functions
        of families <function>resource_query_*()</function> and
        <function>resource_*_value()</function>. Their implementations
        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>

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

      </itemizedlist>

      <para>The enumeration within types starts from 0, so if a device
        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
        permitted resource numbers for ISA devices are:</para>

      <programlisting>          IRQ: 0-1

          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
        normally be equal to 1. The values for memory refer to the
        physical addresses.</para>

      <para>Three types of activities can be performed on

        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 by doing whatever is necessary for that (for
        example, for memory it would be mapping into the kernel
        virtual address space).</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 if the value of type, rid,
            start or count were out of permitted range.</para>

          <itemizedlist>
            <listitem>

            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 to 0.</para>
        </listitem>

        <listitem>

        </listitem>
      </itemizedlist>

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


        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 the computer</para>

      <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

        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
        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 (this feature may be broken on old BIOSes).</para>
        broken).</para>

      <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


      <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, and may make them more strict
        but never more loose.</para>

      <para>Normally one top-level tag (with no parent) is created for

        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 a per-transfer
        basis: buffer for each transfer would be loaded, transfer done
        and buffer unloaded.</para>


              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.</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


          <listitem>
            <para><emphasis>lowaddr, highaddr</emphasis> - the names
              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>

              [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
              page is accessible, non-zero otherwise.</para>
          </listitem>


              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 (the hardware
	      can not normally support that many
              scatter-gather buffers anyway).</para>
          </listitem>

	  <listitem>

	      <listitem>
                <para><emphasis>BUS_DMA_ALLOCNOW</emphasis> - requests
                  to allocate all the potentially needed bounce pages
                  when creating the tag.</para>
              </listitem>

	      <listitem>


          <listitem>
            <para><emphasis>dmat</emphasis> - pointer to the storage
              for the new tag to be returned.</para>
          </listitem>

	</itemizedlist>

        <para>Destroy a tag. Returns 0 on success, the error code
	  otherwise.</para>

        <para>dmat - the tag to be destroyed.</para>

      </listitem>


          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 being used to get
          the physical address of the memory.</para>

<!-- XXX What it is Wylie, I got to here -->

                      <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 until the memory
                      becomes available.
                    </para>
                  </listitem>
                </itemizedlist>

              <listitem>
                <para>
                  <emphasis>mapp</emphasis> - pointer to the storage
                  for the new map to be returned.
                </para>
              </listitem>
            </itemizedlist>

            </para>
            <para>
              Free the memory allocated by
              <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

              <listitem>
                <para>
                  <emphasis>flags</emphasis> - theoretically, a bit map
                  of flags. But no flags are defined yet, so at present
                  it will be always 0.
                </para>
              </listitem>

          <para>
                Release a previously reserved DMA channel. No
                transfers must be in progress when the channel is
                released (in addition the device must not try to
                initiate transfer after the channel is released).
          </para>
        </listitem>

            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 something
            probably went wrong with that transfer.
          </para>
        </listitem>


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

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

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

          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 a reboot will be
          needed anyway, so the efforts spent on writing the detach
          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,
          the detach routine may be provided for the sake of
          completeness.
        </para>

          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 just call it.
        </para>
        <para><function>xxx_isa_shutdown(dev);</function></para>


          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 detail.
        </para>
     </sect1>


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

Return to bug 34916