1.\" $NetBSD: pci.9,v 1.1 2001/07/01 04:11:14 gmcgarry Exp $ 2.\" 3.\" Copyright (c) 2001 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Gregory McGarry. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd June 19, 2001 38.Dt PCI 9 39.Os 40.Sh NAME 41.Nm PCI , 42.Nm pci_conf_read , 43.Nm pci_conf_write , 44.Nm pci_conf_print , 45.Nm pci_get_capability , 46.Nm pci_mapreg_type , 47.Nm pci_mapreg_map , 48.Nm pci_mapreg_info , 49.Nm pci_intr_map , 50.Nm pci_intr_string , 51.Nm pci_intr_evcnt , 52.Nm pci_intr_establish , 53.Nm pci_intr_disestablish , 54.Nm pci_make_tag , 55.Nm pci_decompose_tag , 56.Nm pci_findvendor , 57.Nm pci_devinfo , 58.Nm PCI_VENDOR , 59.Nm PCI_PRODUCT , 60.Nm PCI_REVISION 61.Nd Peripheral Component Interconnect 62.Sh SYNOPSIS 63.Fd #include <machine/bus.h> 64.Fd #include <dev/pci/pcivar.h> 65.Fd #include <dev/pci/pcireg.h> 66.Fd #include <dev/pci/pcidevs.h> 67.Ft pcireg_t 68.Fn pci_conf_read "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" 69.Ft void 70.Fn pci_conf_write "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" \ 71"pcireg_t val" 72.Ft void 73.Fn pci_conf_print "pci_chipset_tag_t pc" "pcitag_t tag" \ 74"void (*func)(pci_chipset_tag_t, pcitag_t, const pcireg_t *)" 75.Ft int 76.Fn pci_get_capability "pci_chipset_tag_t pc" "pcitag_t tag" \ 77"int capid" "int *offsetp" "pcireg_t *valuep" 78.Ft pcireg_t 79.Fn pci_mapreg_type "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" 80.Ft int 81.Fn pci_mapreg_map "struct pci_attach_args *pa" "int reg" \ 82"pcireg_t type" "int busflags" "bus_space_tag_t *tagp" \ 83"bus_space_handle_t *handlep" "bus_addr_t *basep" "bus_size_t *sizep" 84.Ft int 85.Fn pci_mapreg_info "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" \ 86"pcireg_t type" "bus_addr_t *basep" "bus_size_t *sizep" "int *flagsp" 87.Ft int 88.Fn pci_intr_map "struct pci_attach_args *pa" "pci_intr_handle_t *ih" 89.Ft const char * 90.Fn pci_intr_string "pci_chipset_tag_t pc" "pci_intr_handle_t ih" 91.Ft const struct evcnt * 92.Fn pci_intr_evcnt "pci_chipset_tag_t pc" "pci_intr_handle_t ih" 93.Ft void * 94.Fn pci_intr_establish "pci_chipset_tag_t pc" "pci_intr_handle_t ih" \ 95"int level" "int (*handler)(void *)" "void *arg" 96.Ft void 97.Fn pci_intr_disestablish "pci_chipset_tag_t pc" "void *ih" 98.Ft pcitag_t 99.Fn pci_make_tag "pci_chipset_tag_t pc" "int bus" "int device" \ 100"int function" 101.Ft void 102.Fn pci_decompose_tag "pci_chipset_tag_t pc" "pcitag_t tag" \ 103"int *busp" "int *devicep" "int *functionp" 104.Ft char * 105.Fn pci_findvendor "pcireg_t id" 106.Ft void 107.Fn pci_devinfo "pcireg_t id" "pcireg_t class" "int show" "char *cp" 108.Ft int 109.Fn PCI_VENDOR "pcireg_t id" 110.Ft int 111.Fn PCI_PRODUCT "pcireg_t id" 112.Ft int 113.Fn PCI_REVISION "pcireg_t id" 114.Sh DESCRIPTION 115The machine-independent 116.Nm 117subsystem provides support for PCI devices. 118.Pp 119The PCI bus was initially developed by Intel in the early 1990's to 120replace the ISA bus for interfacing to their Pentium processor. The 121PCI specification is widely regarded as well designed, and the PCI bus 122has found widespread acceptable in machines ranging from Apple's 123PowerPC-based machines to Sun's UltraSPARC-based machines. 124.Pp 125The PCI bus a multiplexed bus, allowing addresses and data on the same 126pins for a reduced number of pins. Data transfers can be 8-bit, 12716-bit or 32-bit. A 64-bit extended PCI bus is also defined. 128Multi-byte transfers are little-endian. The PCI bus operates up to 12933MHz and any device on the bus can be the bus master. 130.Pp 131AGP is a version of PCI optimised for high-throughput data rates, 132particularly for accelerated frame buffers. 133.Pp 134The PCI bus is a "plug and play" bus, in the sense that devices can be 135configured dynamically by software. The PCI interface chip on a PCI 136device bus presents a small window of registers into the PCI 137configuration space. These registers contain information about the 138device such as the vendor and a product ID. The configuration 139registers can also be written to by software to alter how the device 140interfaces to the PCI bus. An important register in the configuration 141space is the Base Address Register (BAR). The BAR is written by 142software to map the device registers into a window of processor 143address space. Once this mapping is done, the device registers can be 144accessed relative to the base address. 145.Sh DATA TYPES 146Drivers for devices attached to the 147.Nm 148will make use of the following data types: 149.Bl -tag -width compact 150.It Fa pcireg_t 151Configuration space register. 152.It Fa pci_chipset_tag_t 153Chipset tag for the PCI bus. 154.It Fa pcitag_t 155Configuration tag describing the location and function of the PCI 156device. It contains the tuple 157.Ao 158bus, device, function 159.Ac . 160.It Fa pci_intr_handle_t 161The opaque handle describing an established interrupt handler. 162.It Fa struct pci_attach_args 163Devices have their identity recorded in this structure. it contains 164the following members: 165.Bd -literal 166 bus_space_tag_t pa_iot; /* pci i/o space tag */ 167 bus_space_tag_t pa_memt; /* pci mem space tag */ 168 bus_dma_tag_t pa_dmat; /* DMA tag */ 169 pci_chipset_tag_t pa_pc; 170 int pa_flags; /* flags */ 171 pcitag_t pa_tag; 172 pcireg_t pa_id; 173 pcireg_t pa_class; 174.Ed 175.El 176.Sh FUNCTIONS 177.Bl -tag -width compact 178.It Fn pci_conf_read "pc" "tag" "reg" 179Read from register 180.Fa reg 181in PCI configuration space. The argument 182.Fa tag 183is the PCI tag for the current device attached to PCI chipset 184.Fa pc . 185.It Fn pci_conf_write "pc" "tag" "reg" "val" 186Write to register 187.Fa reg 188in PCI configuration space. The argument 189.Fa tag 190is the PCI tag for the current device attached to PCI chipset 191.Fa pc . 192.It Fn pci_conf_print "pc" "tag" "func" 193Print out most of the registers in the PCI configuration for the 194device. The argument 195.Fa tag 196is the PCI tag for the current device attached to PCI chipset 197.Fa pc . 198The argument 199.Fa func 200is a function called by 201.Fn pci_conf_print 202to print the device-dependent registers. This function is only useful 203for driver development and is usually wrapped in pre-processor 204declarations. 205.It Fn pci_get_capability "pc" "tag" "capid" "offsetp" "valuep" 206Parse the device capability list in configuration space looking for 207capability 208.Fa capid . 209If 210.Fa offsetp 211is not NULL, the register offset in configuration space is returned in 212.Fa offsetp. 213If 214.Fa valuep 215is not NULL, the value of the capability is returned in 216.Fa valuep . 217The argument 218.Fa tag 219is the PCI tag for the current device attached to PCI chipset 220.Fa pc . 221This function returns 1 if the capability was found. If the 222capability was not found, it returns zero, and 223.Fa offsetp 224and 225.Fa valuep 226remain unchanged. 227.It Fn pci_mapreg_type "pc" "tag" "reg" 228Interrogates the Base Address Register (BAR) in configuration space 229specified by 230.Fa reg 231and returns the default (or current) mapping type. Valid returns 232values are: 233.Bl -tag -width compact 234.It PCI_MAPREG_TYPE_IO 235The mapping is to I/O address space. 236.It PCI_MAPREG_TYPE_MEM 237The mapping is to memory address space. 238.It PCI_MAPREG_TYPE_MEM | PCI_MAPREG_MEM_TYPE_64BIT 239The mapping is to 64-bit memory address space. 240.It PCI_MAPREG_TYPE_ROM 241The mapping is to ROM. 242.El 243.sp 244The argument 245.Fa tag 246is the PCI tag for the current device attached to PCI chipset 247.Fa pc . 248.It Fo pci_mapreg_map 249.Fa "pa" "reg" "type" "busflags" "tagp" "handlep" 250.Fa "basep" "sizep" 251.Fc 252Maps the register windows for the device into kernel virtual address 253space. This function is generally only called during the driver 254attach step and takes a pointer to the 255.Em struct pci_attach_args 256in 257.Fa pa . 258The physical address of the mapping is in the Base Address Register 259(BAR) in configuration space specified by 260.Fa reg . 261Valid values for the type of mapping 262.Fa type 263are: 264.Bl -tag -width compact 265.It PCI_MAPREG_TYPE_IO 266The mapping should be to I/O address space. 267.It PCI_MAPREG_TYPE_MEM 268The mapping should be to memory address space. 269.It PCI_MAPREG_TYPE_ROM 270The mapping is to access ROM. 271.El 272.sp 273The argument 274.Fa busflags 275are bus-space flags passed to 276.Fn bus_space_map 277to perform the mapping (see 278.Xr bus_space 9 ). 279The bus-space tag and handle for the mapped register window are 280returned in 281.Fa tagp 282and 283.Fa handlep 284respectively. The bus-address and size of the mapping are returned in 285.Fa basep 286and 287.Fa sizep 288respectively. If any of 289.Fa tagp , 290.Fa handlep , 291.Fa basep , 292or 293.Fa sizep 294are NULL then 295.Fn pci_mapreg_map 296does not define their return value. This function returns zero on 297success and non-zero on error. 298.It Fn pci_mapreg_info "pc" "tag" "reg" "type" "basep" "sizep" "flagsp" 299Performs the same operations as 300.Fn pci_mapreg_map 301but doesn't actually map the register window into kernel virtual 302address space. Returns the bus-address, size and bus flags in 303.Fa basep , 304.Fa sizep 305and 306.Fa flagsp 307respectively. These return values can be used by 308.Fn bus_space_map 309to actually map the register window into kernel virtual address space. 310This function is useful for setting up the registers in configuration 311space and deferring the mapping to a later time, such as in a 312bus-independent attachment routine. 313.Fa pci_mapreg_info 314returns zero on success and non-zero on failure. 315.It Fn pci_intr_map "pa" "ih" 316See 317.Xr pci_intr 9 . 318.It Fn pci_intr_string "pc" "ih" 319See 320.Xr pci_intr 9 . 321.It Fn pci_intr_evcnt "pc" "ih" 322See 323.Xr pci_intr 9 . 324.It Fn pci_intr_establish "pc" "ih" "level" "handler" "arg" 325See 326.Xr pci_intr 9 . 327.It Fn pci_intr_disestablish "pc" "ih" 328See 329.Xr pci_intr 9 . 330.It Fn pci_make_tag "pc" "bus" "device" "function" 331Create a new PCI tag for the PCI device specified by the tuple 332.Ao 333bus, device, function 334.Ac . 335This function is not useful to the usual PCI device driver. It is 336generally used by drivers of multi-function devices when attaching 337other PCI device drivers to each function. 338.It Fn pci_decompose_tag "pc" "tag" "busp" "devicep" "fnp" 339Decompose the PCI tag 340.Fa tag 341generated by 342.Fn pci_make_tag 343into its 344.Ao 345bus, device, function 346.Ac 347tuple. 348.It Fn pci_findvendor "id" 349Return the string of the vendor name for the device specified by 350.Fa id . 351.It Fn pci_devinfo "id" "class" "show" "cp" 352Returns the description string from the in-kernel PCI database for the 353device described by 354.Fa id 355and 356.Fa class . 357The description string is returned in 358.Fa cp . 359The argument 360.Fa show 361specifies whether the PCI subsystem should report the string to the 362console. 363.It Fn PCI_VENDOR "id" 364Return the PCI vendor id for device 365.Fa id . 366.It Fn PCI_PRODUCT "id" 367Return the PCI product id for device 368.Fa id . 369.It Fn PCI_REVISION "id" 370Return the PCI product revision for device 371.Fa id . 372.El 373.Sh AUTOCONFIGURATION 374During autoconfiguration, a 375.Nm 376driver will receive a pointer to 377.Fa struct pci_attach_args 378describing the device attaches to the PCI bus. Drivers match the 379device using the 380.Fa pa_id 381member using 382.Fn PCI_VENDOR . 383.Fn PCI_PRODUCT 384and 385.Fn PCI_REVISION . 386.Pp 387During the driver attach step, drivers can read the device 388configuration space using 389.Fn pci_conf_read . 390The meaning attached to registers in the PCI configuration space are 391device-dependent, but will usually contain physical addresses of the 392device register windows. Device options can also be stored into the 393PCI configuration space using 394.Fn pci_conf_write . 395For example, the driver can request support for bus-mastering DMA by 396writing the option to the PCI configuration space. 397.Pp 398Device capabilities can be queried using 399.Fn pci_get_capability , 400and returns device-specific information which can be found in the PCI 401configuration space to alter device operation. 402.Pp 403After reading the physical addresses of the device register windows 404from configuration space, these windows must be mapped into kernel 405virtual address space using 406.Fn pci_mapreg_map . 407Device registers can now be accessed using the standard bus-space API 408(see 409.Xr bus_space 9 ). 410.Pp 411Details of using PCI interrupts is described in 412.Xr pci_intr 9 . 413.Sh DMA SUPPORT 414The PCI bus supports bus-mastering operations from any device on the 415bus. The DMA facilities are accessed through the standard 416.Xr bus_dma 9 417interface. To support DMA transfers from the device to the host, it 418is necessary to enable bus-mastering in the PCI configuration space 419for the device. 420.Pp 421During system shutdown, it is necessary to abort any DMA transfers in 422progress by registering a shutdown hook (see 423.Xr shutdownhook_establish 9 ). 424.Sh CODE REFERENCES 425This section describes places within the 426.Nx 427source tree where actual code implementing or utilising the 428machine-independent PCI subsystem can be found. All pathnames are 429relative to 430.Pa /usr/src. 431.Pp 432The PCI subsystem itself is implemented within the files 433.Pa sys/dev/pci/pci.c , 434.Pa sys/dev/pci/pci_subr.c , 435.Pa sys/dev/pci/pci_map.c , 436.Pa sys/dev/pci/pci_quirks.c , 437and 438.Pa sys/dev/pci/pciconf.c . 439Machine-dependent portions are implemented within the file 440.Pa sys/arch/<arch>/pci/pci_machdep.c . 441.Pp 442The database of known devices exists within the file 443.Pa sys/dev/pci/pcidevs_data.h 444and is generated automatically from the file 445.Pa sys/dev/pci/pcidevs . 446New vendor and product identifiers should be added to this 447file. The database can be regenerated using the Makefile 448.Pa sys/dev/pci/Makefile.pcidevs . 449.Sh SEE ALSO 450.Xr pci 4 , 451.Xr autoconf 9 , 452.Xr bus_dma 9 , 453.Xr bus_space 9 , 454.Xr driver 9 , 455.Xr pci_configure_bus 9 , 456.Xr pci_intr 9 , 457.Xr shutdownhook_establish 9 . 458.Sh HISTORY 459The machine-independent PCI subsystem appeared in 460.Nx 1.2 . 461