From owner-svn-doc-all@freebsd.org Thu Sep 5 20:22:59 2019 Return-Path: Delivered-To: svn-doc-all@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id ABBB0D2704; Thu, 5 Sep 2019 20:22:59 +0000 (UTC) (envelope-from bcr@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) server-signature RSA-PSS (4096 bits) client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 46PXDz44z3z4KR4; Thu, 5 Sep 2019 20:22:59 +0000 (UTC) (envelope-from bcr@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 70A8E9B21; Thu, 5 Sep 2019 20:22:59 +0000 (UTC) (envelope-from bcr@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id x85KMxDf030299; Thu, 5 Sep 2019 20:22:59 GMT (envelope-from bcr@FreeBSD.org) Received: (from bcr@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id x85KMxKD030298; Thu, 5 Sep 2019 20:22:59 GMT (envelope-from bcr@FreeBSD.org) Message-Id: <201909052022.x85KMxKD030298@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: bcr set sender to bcr@FreeBSD.org using -f From: Benedict Reuschling Date: Thu, 5 Sep 2019 20:22:59 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r53377 - head/en_US.ISO8859-1/books/arch-handbook/pci X-SVN-Group: doc-head X-SVN-Commit-Author: bcr X-SVN-Commit-Paths: head/en_US.ISO8859-1/books/arch-handbook/pci X-SVN-Commit-Revision: 53377 X-SVN-Commit-Repository: doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 05 Sep 2019 20:22:59 -0000 Author: bcr Date: Thu Sep 5 20:22:58 2019 New Revision: 53377 URL: https://svnweb.freebsd.org/changeset/doc/53377 Log: 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 Modified: head/en_US.ISO8859-1/books/arch-handbook/pci/chapter.xml Modified: head/en_US.ISO8859-1/books/arch-handbook/pci/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/arch-handbook/pci/chapter.xml Thu Sep 5 19:40:43 2019 (r53376) +++ head/en_US.ISO8859-1/books/arch-handbook/pci/chapter.xml Thu Sep 5 20:22:58 2019 (r53377) @@ -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 <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, uin 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. -