From 6c190c76c3775288838604c9a9fa1f1567f814ee Mon Sep 17 00:00:00 2001 From: Benedict Reuschling Date: Thu, 5 Sep 2019 20:22:58 +0000 Subject: [PATCH] Clean up the following igor warnings: - wrap long line - add blank line after previous line - use tabs instead of spaces - straggling Event: vBSDcon FreeBSD Hackathon --- .../books/arch-handbook/pci/chapter.xml | 161 +++++++++--------- 1 file changed, 83 insertions(+), 78 deletions(-) diff --git a/en_US.ISO8859-1/books/arch-handbook/pci/chapter.xml b/en_US.ISO8859-1/books/arch-handbook/pci/chapter.xml index 851e32ce5b..a80de475a4 100644 --- a/en_US.ISO8859-1/books/arch-handbook/pci/chapter.xml +++ b/en_US.ISO8859-1/books/arch-handbook/pci/chapter.xml @@ -4,7 +4,9 @@ $FreeBSD$ --> - + PCI Devices PCI bus @@ -20,9 +22,10 @@ to any of them. - Sample Driver Source (<filename>mypci.c</filename>) + Sample Driver Source + (<filename>mypci.c</filename>) -/* + /* * Simple KLD to play with the PCI functions. * * Murray Stokely @@ -232,7 +235,7 @@ DRIVER_MODULE(mypci, pci, mypci_driver, mypci_devclass, 0, 0); <filename>Makefile</filename> for Sample Driver -# Makefile for mypci driver + # Makefile for mypci driver KMOD= mypci SRCS= mypci.c @@ -251,13 +254,16 @@ SRCS+= device_if.h bus_if.h pci_if.h Additional Resources + - PCI - Special Interest Group + + PCI + Special Interest Group + PCI System Architecture, Fourth Edition by - Tom Shanley, et al. - + Tom Shanley, et al. + @@ -265,7 +271,8 @@ SRCS+= device_if.h bus_if.h pci_if.h Bus Resources - PCI busresources + 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 @@ -275,18 +282,20 @@ SRCS+= device_if.h bus_if.h pci_if.h Base Address Registers - PCI busBase 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. - The PCI-specific details of obtaining the BAR are abstracted in - the bus_alloc_resource() function. + will need to obtain the Base Address + Registers (BARs) from the PCI Configuration + space. The PCI-specific details of obtaining the BAR are + abstracted in the bus_alloc_resource() + function. For example, a typical driver might have something similar - to this in the attach() function: + to this in the attach() function: - sc->bar0id = PCIR_BAR(0); + sc->bar0id = PCIR_BAR(0); sc->bar0res = bus_alloc_resource(dev, SYS_RES_MEMORY, &sc->bar0id, 0, ~0, 1, RF_ACTIVE); if (sc->bar0res == NULL) { @@ -309,34 +318,33 @@ SRCS+= device_if.h bus_if.h pci_if.h 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 - used to write to the device later. + softc structure so that + they can be used to write to the device later. These handles can then be used to read or write from the - device registers with the bus_space_* - functions. For example, a driver might contain a shorthand - function to read from a board specific register like this: + device registers with the bus_space_* + functions. For example, a driver might contain a shorthand + function to read from a board specific register like + this: -uint16_t + uint16_t board_read(struct ni_softc *sc, uint16_t address) { return bus_space_read_2(sc->bar1_bt, sc->bar1_bh, address); -} - +} Similarly, one could write to the registers with: -void + void board_write(struct ni_softc *sc, uint16_t address, uint16_t value) { bus_space_write_2(sc->bar1_bt, sc->bar1_bh, address, value); -} - +} These functions exist in 8bit, 16bit, and 32bit versions - and you should use - bus_space_{read|write}_{1|2|4} - accordingly. + and you should use + bus_space_{read|write}_{1|2|4} + accordingly. In FreeBSD 7.0 and later, you can use the @@ -345,31 +353,33 @@ board_write(struct ni_softc *sc, uint16_t address, uint16_t value) bus_* functions take a struct resource * pointer instead of a bus tag and handle. Thus, you could drop the bus tag and bus handle members from - the softc and rewrite the - board_read() function as: + the softc and rewrite + the board_read() function as: -uint16_t + uint16_t board_read(struct ni_softc *sc, uint16_t address) { return (bus_read(sc->bar1res, address)); -} - +} + Interrupts - PCI businterrupts + 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 - interrupt handler must be set up to deal with this IRQ. + in a way similar to the memory resources. First an IRQ + resource must be allocated from the parent bus, and then the + interrupt handler must be set up to deal with this IRQ. Again, a sample from a device - attach() function says more than - words. + attach() function says more than + words. -/* Get the IRQ resource */ + /* Get the IRQ resource */ sc->irqid = 0x0; sc->irqres = bus_alloc_resource(dev, SYS_RES_IRQ, &(sc->irqid), @@ -387,67 +397,62 @@ board_read(struct ni_softc *sc, uint16_t address) if (error) { printf("Couldn't set up irq\n"); goto fail4; - } - + } Some care must be taken in the detach routine of the - driver. You must quiesce the device's interrupt stream, and - remove the interrupt handler. Once - bus_teardown_intr() has returned, you - know that your interrupt handler will no longer be called and - that all threads that might have been executing this interrupt handler - have returned. Since this function can sleep, you must not hold - any mutexes when calling this function. - + driver. You must quiesce the device's interrupt stream, and + remove the interrupt handler. Once + bus_teardown_intr() has returned, you + know that your interrupt handler will no longer be called and + that all threads that might have been executing this interrupt + handler have returned. Since this function can sleep, you + must not hold any mutexes when calling this function. DMA - PCI busDMA + 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. - This paragraph can be removed when this section is updated to reflect - that usage. However, at the moment, the API is in a bit of - flux, so once that settles down, it would be good to update this - section to reflect that. + reasons. The proper methods for dealing with these issues is + to use the bus_space_dma*() functions + instead. This paragraph can be removed when this section is + updated to reflect that usage. However, at the moment, the + API is in a bit of flux, so once that settles down, it would + be good to update this section to reflect that. On the PC, peripherals that want to do bus-mastering DMA - must deal with physical addresses. This is a problem since - FreeBSD uses virtual memory and deals almost exclusively with - virtual addresses. Fortunately, there is a function, - vtophys() to help. + must deal with physical addresses. This is a problem since + FreeBSD uses virtual memory and deals almost exclusively with + virtual addresses. Fortunately, there is a function, + vtophys() to help. -#include <vm/vm.h> + #include <vm/vm.h> #include <vm/pmap.h> -#define vtophys(virtual_address) (...) - +#define vtophys(virtual_address) (...) The solution is a bit different on the alpha however, and - what we really want is a function called - vtobus(). + what we really want is a function called + vtobus(). -#if defined(__alpha__) + #if defined(__alpha__) #define vtobus(va) alpha_XXX_dmamap((vm_offset_t)va) #else #define vtobus(va) vtophys(va) -#endif - - +#endif Deallocating Resources It is very important to deallocate all of the resources - that were allocated during attach(). - Care must be taken to deallocate the correct stuff even on a - failure condition so that the system will remain usable while - your driver dies. - + that were allocated during attach(). + Care must be taken to deallocate the correct stuff even on a + failure condition so that the system will remain usable while + your driver dies. -