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