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

Add indexterms and more descriptive markup (<literal>, <errorname>, etc..)

Browse source
This commit is contained in:
Murray Stokely 2005-05-04 23:21:38 +00:00
parent fcfbf156cd
commit c8495b0052
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=24450
2 changed files with 46 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -17,6 +17,9 @@
<sect1 id="isa-driver-synopsis">
<title>Synopsis</title>
<indexterm><primary>ISA</primary></indexterm>
<indexterm><primary>device driver</primary><secondary>ISA</secondary></indexterm>
<para>This chapter introduces the issues relevant to writing a
driver for an ISA device. The pseudo-code presented here is
rather detailed and reminiscent of the real code but is still
@ -44,10 +47,12 @@
<para>They describe the things specific to the ISA and generic
bus subsystem.</para>
<indexterm><primary>object-oriented</primary></indexterm>
<para>The bus subsystem is implemented in an object-oriented
fashion, its main structures are accessed by associated method
functions.</para>
<indexterm><primary>bus methods</primary></indexterm>
<para>The list of bus methods implemented by an ISA driver is like
one for any other bus. For a hypothetical driver named <quote>xxx</quote>
they would be:</para>
@ -137,12 +142,16 @@
DRIVER_MODULE(xxx, isa, xxx_isa_driver, xxx_devclass,
load_function, load_argument);</programlisting>
<indexterm><primary>softc</primary></indexterm>
<para>Here struct <structname>xxx_softc</structname> is a
device-specific structure that contains private driver data
and descriptors for the driver's resources. The bus code
automatically allocates one softc descriptor per device as
needed.</para>
<indexterm><primary>kernel module</primary></indexterm>
<para>If the driver is implemented as a loadable module then
<function>load_function()</function> is called to do
driver-specific initialization or clean-up when the driver is
@ -155,6 +164,8 @@
<programlisting> DRIVER_MODULE(xxx, isa, xxx_isa_driver,
xxx_devclass, 0, 0);</programlisting>
<indexterm><primary>PnP</primary></indexterm>
<para>If the driver is for a device which supports PnP then a
table of supported PnP IDs must be defined. The table
consists of a list of PnP IDs supported by this driver and
@ -250,12 +261,16 @@
<title>Configuration file and the order of identifying and probing
during auto-configuration</title>
<indexterm><primary>ISA</primary><secondary>probing</secondary></indexterm>
<para>The ISA devices are described in the kernel configuration file
like:</para>
<programlisting>device xxx0 at isa? port 0x300 irq 10 drq 5
iomem 0xd0000 flags 0x1 sensitive</programlisting>
<indexterm><primary>IRQ</primary></indexterm>
<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
@ -386,13 +401,16 @@
<sect1 id="isa-driver-resources">
<title>Resources</title>
<indexterm><primary>resources</primary></indexterm>
<indexterm><primary>device driver</primary><secondary>resources</secondary></indexterm>
<para>The information that a user enters into the kernel
configuration file is processed and passed to the kernel as
configuration resources. This information is parsed by the bus
configuration code and transformed into a value of structure
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
functions <function>resource_*</function> for more complex cases of
configuration. However, generally this is neither needed nor recommended,
so this issue is not discussed further here.</para>
@ -400,6 +418,8 @@
are identified by type and number within the type. For the ISA
bus the following types are defined:</para>
<indexterm><primary>DMA channel</primary></indexterm>
<itemizedlist>
<listitem>
<para><emphasis>SYS_RES_IRQ</emphasis> - interrupt
@ -425,7 +445,7 @@
<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
<literal>SYS_RES_MEMORY</literal> 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
@ -585,7 +605,7 @@
<listitem>
<para>Activate or deactivate resource. Return 0 on success,
error code otherwise. If the resource is time-shared and
currently activated by another driver then EBUSY is
currently activated by another driver then <literal>EBUSY</literal> is
returned.</para>
</listitem>
@ -704,7 +724,7 @@
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
memory must be defined as a SYS_RES_MEMORY resource. That
memory must be defined as a <literal>SYS_RES_MEMORY</literal> resource. That
resource can then be allocated and activated, and its virtual
address obtained using
<function>rman_get_virtual()</function>. The older drivers
@ -735,7 +755,7 @@
done by the drivers themselves.</para>
<para>Two structures are used for DMA memory allocation,
bus_dma_tag_t and bus_dmamap_t. Tag describes the properties
<varname>bus_dma_tag_t</varname> and <varname>bus_dmamap_t</varname>. Tag describes the properties
required for the DMA memory. Map represents a memory block
allocated according to these properties. Multiple maps may be
associated with the same tag.</para>
@ -870,17 +890,17 @@
memory (in bytes) that may be allocated through this
tag. In case it is difficult to estimate or could be
arbitrarily big, the value for ISA devices would be
BUS_SPACE_MAXSIZE_24BIT.</para>
<literal>BUS_SPACE_MAXSIZE_24BIT</literal>.</para>
</listitem>
<listitem>
<para><emphasis>nsegments</emphasis> - maximal number of
scatter-gather segments supported by the device. If
unrestricted then the value BUS_SPACE_UNRESTRICTED
unrestricted then the value <literal>BUS_SPACE_UNRESTRICTED</literal>
should be used. This value is recommended for the parent
tags, the actual restrictions would then be specified
for the descendant tags. Tags with nsegments equal to
BUS_SPACE_UNRESTRICTED may not be used to actually load
<literal>BUS_SPACE_UNRESTRICTED</literal> 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
@ -892,7 +912,7 @@
<para><emphasis>maxsegsz</emphasis> - maximal size of a
scatter-gather segment supported by the device. The
maximal value for ISA device would be
BUS_SPACE_MAXSIZE_24BIT.</para>
<literal>BUS_SPACE_MAXSIZE_24BIT</literal>.</para>
</listitem>
<listitem>
@ -948,8 +968,6 @@
<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 -->
<itemizedlist>
<listitem>
<para>
@ -1103,7 +1121,7 @@
needed but not immediately available the request will be
queued and the callback will be called when the bounce
buffers will become available. Returns 0 if the callback
was executed immediately or EINPROGRESS if the request
was executed immediately or <errorname>EINPROGRESS</errorname> if the request
was queued for future execution. In the latter case the
synchronization with queued callback routine is the
responsibility of the driver.
@ -1170,7 +1188,7 @@
<listitem>
<para>
<emphasis>error</emphasis> - indication of the
segment number overflow: if it is set to EFBIG then
segment number overflow: if it is set to <errorname>EFBIG</errorname> then
the buffer did not fit into the maximal number of
segments permitted by the tag. In this case only the
permitted number of descriptors will be in the
@ -1476,6 +1494,9 @@
<sect1 id="isa-driver-dma">
<title>DMA</title>
<!-- Section Marked up by Wylie -->
<indexterm><primary>Direct Memory Access (DMA)</primary></indexterm>
<para>
The Direct Memory Access (DMA) is implemented in the ISA bus
through the DMA controller (actually, two of them but that is
@ -1722,7 +1743,7 @@
As for any other bus, if the device cannot be detected or
is detected but failed the self-test or some other problem
happened then it returns a positive value of error. The
value ENXIO must be returned if the device is not
value <errorname>ENXIO</errorname> must be returned if the device is not
present. Other error values may mean other conditions. Zero
or negative values mean success. Most of the drivers return
zero as success.
@ -2431,6 +2452,8 @@
<sect1 id="isa-driver-intr">
<title>xxx_intr</title>
<indexterm><primary>interrupt handler</primary></indexterm>
<para>
The interrupt handler is called when an interrupt is
received which may be from this particular device. The ISA

12
en_US.ISO8859-1/books/arch-handbook/pci/chapter.sgml
View file

@ -7,6 +7,8 @@
<chapter id="pci">
<title>PCI Devices</title>
<indexterm><primary>PCI bus</primary></indexterm>
<para>This chapter will talk about the FreeBSD mechanisms for
writing a device driver for a device on a PCI bus.</para>
@ -212,6 +214,7 @@ DRIVER_MODULE(mypci, pci, mypci_driver, mypci_devclass, 0, 0);</programlisting>
<sect1 id="pci-bus">
<title>Bus Resources</title>
<indexterm><primary>PCI bus</primary><secondary>resources</secondary></indexterm>
<para>FreeBSD provides an object-oriented mechanism for requesting
resources from a parent bus. Almost all devices will be a child
member of some sort of bus (PCI, ISA, USB, SCSI, etc) and these
@ -221,6 +224,8 @@ DRIVER_MODULE(mypci, pci, mypci_driver, mypci_devclass, 0, 0);</programlisting>
<sect2>
<title>Base Address Registers</title>
<indexterm><primary>PCI bus</primary><secondary>Base Address Registers</secondary></indexterm>
<para>To do anything particularly useful with a PCI device you
will need to obtain the <emphasis>Base Address
Registers</emphasis> (BARs) from the PCI Configuration space.
@ -250,9 +255,7 @@ DRIVER_MODULE(mypci, pci, mypci_driver, mypci_devclass, 0, 0);</programlisting>
sc->bar0_bt = rman_get_bustag(sc->bar0res);
sc->bar0_bh = rman_get_bushandle(sc->bar0res);
sc->bar1_bt = rman_get_bustag(sc->bar1res);
sc->bar1_bh = rman_get_bushandle(sc->bar1res);
</programlisting>
sc->bar1_bh = rman_get_bushandle(sc->bar1res);</programlisting>
<para>Handles for each base address register are kept in the
<structname>softc</structname> structure so that they can be
@ -286,6 +289,7 @@ board_write(struct ni_softc *sc, uint16_t address, uint16_t value) {
<sect2>
<title>Interrupts</title>
<indexterm><primary>PCI bus</primary><secondary>interrupts</secondary></indexterm>
<para>Interrupts are allocated from the object-oriented bus code
in a way similar to the memory resources. First an IRQ
resource must be allocated from the parent bus, and then the
@ -332,6 +336,8 @@ board_write(struct ni_softc *sc, uint16_t address, uint16_t value) {
<sect2>
<title>DMA</title>
<indexterm><primary>PCI bus</primary><secondary>DMA</secondary></indexterm>
<para>This section is obsolete, and present only for historical
reasons. The proper methods for dealing with these issues is to
use the <function>bus_space_dma*()</function> functions instead.