From c8495b0052959a7ac10ec4902893a972fd8dfee1 Mon Sep 17 00:00:00 2001 From: Murray Stokely Date: Wed, 4 May 2005 23:21:38 +0000 Subject: [PATCH] Add indexterms and more descriptive markup (, , etc..) --- .../books/arch-handbook/isa/chapter.sgml | 51 ++++++++++++++----- .../books/arch-handbook/pci/chapter.sgml | 12 +++-- 2 files changed, 46 insertions(+), 17 deletions(-) diff --git a/en_US.ISO8859-1/books/arch-handbook/isa/chapter.sgml b/en_US.ISO8859-1/books/arch-handbook/isa/chapter.sgml index 55469129ff..ff9697ad5a 100644 --- a/en_US.ISO8859-1/books/arch-handbook/isa/chapter.sgml +++ b/en_US.ISO8859-1/books/arch-handbook/isa/chapter.sgml @@ -17,6 +17,9 @@ Synopsis + ISA + device driverISA + 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 @@ They describe the things specific to the ISA and generic bus subsystem. + object-oriented The bus subsystem is implemented in an object-oriented fashion, its main structures are accessed by associated method functions. + bus methods The list of bus methods implemented by an ISA driver is like one for any other bus. For a hypothetical driver named xxx they would be: @@ -137,12 +142,16 @@ DRIVER_MODULE(xxx, isa, xxx_isa_driver, xxx_devclass, load_function, load_argument); + softc + Here struct xxx_softc 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. + kernel module + If the driver is implemented as a loadable module then load_function() is called to do driver-specific initialization or clean-up when the driver is @@ -155,6 +164,8 @@ DRIVER_MODULE(xxx, isa, xxx_isa_driver, xxx_devclass, 0, 0); + PnP + 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 @@ Configuration file and the order of identifying and probing during auto-configuration + ISAprobing + The ISA devices are described in the kernel configuration file like: device xxx0 at isa? port 0x300 irq 10 drq 5 iomem 0xd0000 flags 0x1 sensitive + IRQ + 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 @@ Resources + resources + device driverresources + 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 resource_* for more complex cases of configuration. However, generally this is neither needed nor recommended, so this issue is not discussed further here. @@ -400,6 +418,8 @@ are identified by type and number within the type. For the ISA bus the following types are defined: + DMA channel + SYS_RES_IRQ - interrupt @@ -425,7 +445,7 @@ 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 + 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 @@ -585,7 +605,7 @@ 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 EBUSY is returned. @@ -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 SYS_RES_MEMORY resource. That resource can then be allocated and activated, and its virtual address obtained using rman_get_virtual(). The older drivers @@ -735,7 +755,7 @@ done by the drivers themselves. Two structures are used for DMA memory allocation, - bus_dma_tag_t and bus_dmamap_t. Tag describes the properties + bus_dma_tag_t and bus_dmamap_t. 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. @@ -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. + BUS_SPACE_MAXSIZE_24BIT. nsegments - maximal number of scatter-gather segments supported by the device. If - unrestricted then the value BUS_SPACE_UNRESTRICTED + unrestricted then the value BUS_SPACE_UNRESTRICTED 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 + 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 @@ -892,7 +912,7 @@ maxsegsz - maximal size of a scatter-gather segment supported by the device. The maximal value for ISA device would be - BUS_SPACE_MAXSIZE_24BIT. + BUS_SPACE_MAXSIZE_24BIT. @@ -948,8 +968,6 @@ bus_dmamap_load() before being used to get the physical address of the memory. - - @@ -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 EINPROGRESS 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 @@ error - indication of the - segment number overflow: if it is set to EFBIG then + segment number overflow: if it is set to EFBIG 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 @@ DMA + + Direct Memory Access (DMA) + 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 ENXIO 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 @@ xxx_intr + interrupt handler + The interrupt handler is called when an interrupt is received which may be from this particular device. The ISA diff --git a/en_US.ISO8859-1/books/arch-handbook/pci/chapter.sgml b/en_US.ISO8859-1/books/arch-handbook/pci/chapter.sgml index 5e7c795622..2123ec5861 100644 --- a/en_US.ISO8859-1/books/arch-handbook/pci/chapter.sgml +++ b/en_US.ISO8859-1/books/arch-handbook/pci/chapter.sgml @@ -7,6 +7,8 @@ PCI Devices + PCI bus + This chapter will talk about the FreeBSD mechanisms for writing a device driver for a device on a PCI bus. @@ -212,6 +214,7 @@ DRIVER_MODULE(mypci, pci, mypci_driver, mypci_devclass, 0, 0); Bus Resources + PCI busresources 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); Base Address Registers + PCI busBase Address Registers + To do anything particularly useful with a PCI device you will need to obtain the Base Address Registers (BARs) from the PCI Configuration space. @@ -250,9 +255,7 @@ DRIVER_MODULE(mypci, pci, mypci_driver, mypci_devclass, 0, 0); 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); - - + sc->bar1_bh = rman_get_bushandle(sc->bar1res); Handles for each base address register are kept in the softc structure so that they can be @@ -286,6 +289,7 @@ board_write(struct ni_softc *sc, uint16_t address, uint16_t value) { Interrupts + PCI businterrupts 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) { DMA + + PCI busDMA This section is obsolete, and present only for historical reasons. The proper methods for dealing with these issues is to use the bus_space_dma*() functions instead.