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