1.\" $NetBSD: pci.9,v 1.24 2006/06/18 09:27:41 wiz Exp $ 2.\" 3.\" Copyright (c) 2001, 2003 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 17, 2006 38.Dt PCI 9 39.Os 40.Sh NAME 41.Nm PCI , 42.Nm pci_activate , 43.Nm pci_conf_read , 44.Nm pci_conf_write , 45.Nm pci_conf_print , 46.Nm pci_conf_capture , 47.Nm pci_conf_restore , 48.Nm pci_find_device , 49.Nm pci_get_capability , 50.Nm pci_mapreg_type , 51.Nm pci_mapreg_map , 52.Nm pci_mapreg_info , 53.Nm pci_intr_map , 54.Nm pci_intr_string , 55.Nm pci_intr_evcnt , 56.Nm pci_intr_establish , 57.Nm pci_intr_disestablish , 58.Nm pci_get_powerstate , 59.Nm pci_set_powerstate , 60.Nm pci_vpd_read , 61.Nm pci_vpd_write , 62.Nm pci_make_tag , 63.Nm pci_decompose_tag , 64.Nm pci_findvendor , 65.Nm pci_devinfo , 66.Nm PCI_VENDOR , 67.Nm PCI_PRODUCT , 68.Nm PCI_REVISION 69.Nd Peripheral Component Interconnect 70.Sh SYNOPSIS 71.In machine/bus.h 72.In dev/pci/pcivar.h 73.In dev/pci/pcireg.h 74.In dev/pci/pcidevs.h 75.Ft int 76.Fn pci_activate "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" "void *sc" "int (*wakeup)(pci_chipset_tag_t pc, pcitag_t tag, void *sc, pcireg_t reg)" 77.Ft pcireg_t 78.Fn pci_conf_read "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" 79.Ft void 80.Fn pci_conf_write "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" \ 81"pcireg_t val" 82.Ft void 83.Fn pci_conf_print "pci_chipset_tag_t pc" "pcitag_t tag" \ 84"void (*func)(pci_chipset_tag_t, pcitag_t, const pcireg_t *)" 85.Ft void 86.Fn pci_conf_capture "pci_chipset_tag_t pc" "pcitag_t tag" \ 87"struct pci_conf_state *" 88.Ft void 89.Fn pci_conf_restore "pci_chipset_tag_t pc" "pcitag_t tag" \ 90"struct pci_conf_state *" 91.Ft int 92.Fn pci_find_device "struct pci_attach_args *pa" \ 93"int (*func)(struct pci_attach_args *)" 94.Ft int 95.Fn pci_get_capability "pci_chipset_tag_t pc" "pcitag_t tag" \ 96"int capid" "int *offsetp" "pcireg_t *valuep" 97.Ft pcireg_t 98.Fn pci_mapreg_type "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" 99.Ft int 100.Fn pci_mapreg_map "struct pci_attach_args *pa" "int reg" \ 101"pcireg_t type" "int busflags" "bus_space_tag_t *tagp" \ 102"bus_space_handle_t *handlep" "bus_addr_t *basep" "bus_size_t *sizep" 103.Ft int 104.Fn pci_mapreg_info "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" \ 105"pcireg_t type" "bus_addr_t *basep" "bus_size_t *sizep" "int *flagsp" 106.Ft int 107.Fn pci_find_rom "struct pci_attach_args *pa" \ 108"bus_space_tag_t bst" "bus_space_handle_t bsh" "int code" \ 109"bus_space_handle_t *handlep" "bus_space_size_t *sizep" 110.Ft int 111.Fn pci_intr_map "struct pci_attach_args *pa" "pci_intr_handle_t *ih" 112.Ft const char * 113.Fn pci_intr_string "pci_chipset_tag_t pc" "pci_intr_handle_t ih" 114.Ft const struct evcnt * 115.Fn pci_intr_evcnt "pci_chipset_tag_t pc" "pci_intr_handle_t ih" 116.Ft void * 117.Fn pci_intr_establish "pci_chipset_tag_t pc" "pci_intr_handle_t ih" \ 118"int level" "int (*handler)(void *)" "void *arg" 119.Ft void 120.Fn pci_intr_disestablish "pci_chipset_tag_t pc" "void *ih" 121.Ft int 122.Fn pci_set_powerstate "pci_chipset_tag_t pc" "pcitag_t tag" \ 123"pcireg_t newstate" 124.Ft int 125.Fn pci_get_powerstate "pci_chipset_tag_t pc" "pcitag_t tag" "pcireg_t *state" 126.Ft int 127.Fn pci_vpd_read "pci_chipset_tag_t pc" "pcitag_t tag" "int offset" \ 128"int count" "pcireg_t *data" 129.Ft int 130.Fn pci_vpd_write "pci_chipset_tag_t pc" "pcitag_t tag" "int offset" \ 131"int count" "pcireg_t *data" 132.Ft pcitag_t 133.Fn pci_make_tag "pci_chipset_tag_t pc" "int bus" "int device" \ 134"int function" 135.Ft void 136.Fn pci_decompose_tag "pci_chipset_tag_t pc" "pcitag_t tag" \ 137"int *busp" "int *devicep" "int *functionp" 138.Ft char * 139.Fn pci_findvendor "pcireg_t id" 140.Ft void 141.Fn pci_devinfo "pcireg_t id" "pcireg_t class" "int show" "char *cp" "size_t len" 142.Ft int 143.Fn PCI_VENDOR "pcireg_t id" 144.Ft int 145.Fn PCI_PRODUCT "pcireg_t id" 146.Ft int 147.Fn PCI_REVISION "pcireg_t id" 148.Sh DESCRIPTION 149The machine-independent 150.Nm 151subsystem provides support for PCI devices. 152.Pp 153The PCI bus was initially developed by Intel in the early 1990's to 154replace the ISA bus for interfacing with their Pentium processor. 155The PCI specification is widely regarded as well designed, and the 156PCI bus has found widespread acceptance in machines ranging from 157Apple's PowerPC-based systems to Sun's UltraSPARC-based machines. 158.Pp 159The PCI bus is a multiplexed bus, allowing addresses and data on the same 160pins for a reduced number of pins. 161Data transfers can be 8-bit, 16-bit or 32-bit. 162A 64-bit extended PCI bus is also defined. 163Multi-byte transfers are little-endian. 164The PCI bus operates up to 33MHz and any device on the bus can be 165the bus master. 166.Pp 167AGP is a version of PCI optimised for high-throughput data rates, 168particularly for accelerated frame buffers. 169.Pp 170The PCI bus is a "plug and play" bus, in the sense that devices can be 171configured dynamically by software. 172The PCI interface chip on a PCI device bus presents a small window 173of registers into the PCI configuration space. 174These registers contain information about the device such as the vendor 175and a product ID. 176The configuration registers can also be written to by software to alter 177how the device interfaces to the PCI bus. 178An important register in the configuration space is the Base Address 179Register (BAR). 180The BAR is written to by software to map the device registers into a 181window of processor address space. 182Once this mapping is done, the device registers can be accessed relative 183to the base address. 184.Sh DATA TYPES 185Drivers for devices attached to the 186.Nm 187will make use of the following data types: 188.Bl -tag -width compact 189.It Fa pcireg_t 190Configuration space register. 191.It Fa pci_chipset_tag_t 192Chipset tag for the PCI bus. 193.It Fa pcitag_t 194Configuration tag describing the location and function of the PCI 195device. 196It contains the tuple 197.Ao 198bus, device, function 199.Ac . 200.It Fa pci_intr_handle_t 201The opaque handle describing an established interrupt handler. 202.It Fa struct pci_attach_args 203Devices have their identity recorded in this structure. 204It contains the following members: 205.Bd -literal 206 bus_space_tag_t pa_iot; /* pci i/o space tag */ 207 bus_space_tag_t pa_memt; /* pci mem space tag */ 208 bus_dma_tag_t pa_dmat; /* DMA tag */ 209 pci_chipset_tag_t pa_pc; 210 int pa_flags; /* flags */ 211 pcitag_t pa_tag; 212 pcireg_t pa_id; 213 pcireg_t pa_class; 214.Ed 215.It Fa struct pci_conf_state 216Stores the PCI configuration state of a device. 217It contains the following member: 218.Bd -literal 219 pcireg_t reg[16]; /* pci conf register */ 220.Ed 221.El 222.Sh FUNCTIONS 223.Bl -tag -width compact 224.It Fn pci_activate "pc" "tag" "sc" "fun" 225Attempt to bring the device to state D0. 226If the device is not in the D0 state call 227.Fa fun 228to restore its state. 229If 230.Fa fun 231is 232.Dv NULL 233then restoring from state D3 is going to fail. 234.It Fn pci_conf_read "pc" "tag" "reg" 235Read from register 236.Fa reg 237in PCI configuration space. 238The argument 239.Fa tag 240is the PCI tag for the current device attached to PCI chipset 241.Fa pc . 242.It Fn pci_conf_write "pc" "tag" "reg" "val" 243Write to register 244.Fa reg 245in PCI configuration space. 246The argument 247.Fa tag 248is the PCI tag for the current device attached to PCI chipset 249.Fa pc . 250.It Fn pci_conf_print "pc" "tag" "func" 251Print out most of the registers in the PCI configuration for the 252device. 253The argument 254.Fa tag 255is the PCI tag for the current device attached to PCI chipset 256.Fa pc . 257The argument 258.Fa func 259is a function called by 260.Fn pci_conf_print 261to print the device-dependent registers. 262This function is only useful for driver development and is usually 263wrapped in pre-processor declarations. 264.It Fn pci_conf_capture "pc" "tag" "pcs" 265Capture PCI configuration space into structure 266.Fa pcs . 267The argument 268.Fa tag 269is the PCI tag for the current device attached to the PCI 270chipset 271.Fa pc . 272.It Fn pci_conf_restore "pc" "tag" "pcs" 273Restores PCI configuration space from structure 274.Fa pcs . 275The argument 276.Fa tag 277is the PCI tag for the current device attached to the PCI 278chipset 279.Fa pc . 280.It Fn pci_find_device "pa" "func" 281Find a device using a match function on all probed busses. 282The argument 283.Fa func 284is called by 285.Fn pci_find_device 286to match a device. 287The argument 288.Fa pa 289is filled in if the device is matched. 290.Fn pci_find_device 291returns 1 if the device is matched, and zero otherwise. 292This function is specifically for use by LKMs (see 293.Xr lkm 4 ) 294and its use otherwise is strongly discouraged. 295.It Fn pci_get_capability "pc" "tag" "capid" "offsetp" "valuep" 296Parse the device capability list in configuration space looking for 297capability 298.Fa capid . 299If 300.Fa offsetp 301is not NULL, the register offset in configuration space is returned in 302.Fa offsetp . 303If 304.Fa valuep 305is not NULL, the value of the capability is returned in 306.Fa valuep . 307The argument 308.Fa tag 309is the PCI tag for the current device attached to PCI chipset 310.Fa pc . 311This function returns 1 if the capability was found. 312If the capability was not found, it returns zero, and 313.Fa offsetp 314and 315.Fa valuep 316remain unchanged. 317.It Fn pci_mapreg_type "pc" "tag" "reg" 318Interrogates the Base Address Register (BAR) in configuration space 319specified by 320.Fa reg 321and returns the default (or current) mapping type. 322Valid returns values are: 323.Bl -tag -width compact 324.It Dv PCI_MAPREG_TYPE_IO 325The mapping is to I/O address space. 326.It Dv PCI_MAPREG_TYPE_MEM 327The mapping is to memory address space. 328.It Dv PCI_MAPREG_TYPE_MEM | PCI_MAPREG_MEM_TYPE_64BIT 329The mapping is to 64-bit memory address space. 330.It Dv PCI_MAPREG_TYPE_ROM 331The mapping is to ROM. 332Note that in the current implementation, 333.Dv PCI_MAPREG_TYPE_ROM 334has the same numeric value as 335.Dv PCI_MAPREG_TYPE_MEM . 336.El 337.Pp 338The argument 339.Fa tag 340is the PCI tag for the current device attached to PCI chipset 341.Fa pc . 342.It Fn pci_mapreg_map "pa" "reg" "type" "busflags" "tagp" "handlep" "basep" "sizep" 343Maps the register windows for the device into kernel virtual address 344space. 345This function is generally only called during the driver attach step 346and takes a pointer to the 347.Em struct pci_attach_args 348in 349.Fa pa . 350The physical address of the mapping is in the Base Address Register 351(BAR) in configuration space specified by 352.Fa reg . 353Valid values for the type of mapping 354.Fa type 355are: 356.Bl -tag -width compact 357.It Dv PCI_MAPREG_TYPE_IO 358The mapping should be to I/O address space. 359.It Dv PCI_MAPREG_TYPE_MEM 360The mapping should be to memory address space. 361.It Dv PCI_MAPREG_TYPE_ROM 362The mapping is to access ROM. 363This type of mapping is only permitted when the value for 364.Fa reg 365is 366.Dv PCI_MAPREG_ROM . 367.El 368.Pp 369The argument 370.Fa busflags 371are bus-space flags passed to 372.Fn bus_space_map 373to perform the mapping (see 374.Xr bus_space 9 ) . 375The bus-space tag and handle for the mapped register window are 376returned in 377.Fa tagp 378and 379.Fa handlep 380respectively. 381The bus-address and size of the mapping are returned in 382.Fa basep 383and 384.Fa sizep 385respectively. 386If any of 387.Fa tagp , 388.Fa handlep , 389.Fa basep , 390or 391.Fa sizep 392are NULL then 393.Fn pci_mapreg_map 394does not define their return value. 395This function returns zero on success and non-zero on error. 396.It Fn pci_mapreg_info "pc" "tag" "reg" "type" "basep" "sizep" "flagsp" 397Performs the same operations as 398.Fn pci_mapreg_map 399but doesn't actually map the register window into kernel virtual 400address space. 401Returns the bus-address, size and bus flags in 402.Fa basep , 403.Fa sizep 404and 405.Fa flagsp 406respectively. 407These return values can be used by 408.Fn bus_space_map 409to actually map the register window into kernel virtual address space. 410This function is useful for setting up the registers in configuration 411space and deferring the mapping to a later time, such as in a 412bus-independent attachment routine. 413.Fa pci_mapreg_info 414returns zero on success and non-zero on failure. 415.It Fn pci_find_rom "pa" "bst" "bsh" "code" "handlep" "sizep" 416Locates a suitable ROM image within a PCI expansion ROM previously mapped with 417.Fn pci_mapreg_map 418and creates a subregion for it with 419.Fn bus_space_subregion . 420The 421.Fa bst 422and 423.Fa bsh 424arguments are the bus tag and handle obtained with the prior call to 425.Fn pci_mapreg_map . 426Valid values for the image type 427.Fa code 428are: 429.Bl -tag -width compact 430.It Dv PCI_ROM_CODE_TYPE_X86 431Find a ROM image containing i386 executable code for use by PC BIOS. 432.It Dv PCI_ROM_CODE_TYPE_OFW 433Find a ROM image containing Forth code for use by Open Firmware. 434.It Dv PCI_ROM_CODE_TYPE_HPPA 435Find a ROM image containing HP PA/RISC executable code. 436.El 437.Pp 438The created subregion will cover the entire selected ROM image, including 439header data. 440The handle to this subregion is returned in 441.Fa handlep . 442The size of the image (and the corresponding subregion) is returned in 443.Fa sizep . 444This function can only be used with expansion ROMs located at the 445.Dv PCI_MAPREG_ROM 446base address register (BAR). 447.It Fn pci_intr_map "pa" "ih" 448See 449.Xr pci_intr 9 . 450.It Fn pci_intr_string "pc" "ih" 451See 452.Xr pci_intr 9 . 453.It Fn pci_intr_evcnt "pc" "ih" 454See 455.Xr pci_intr 9 . 456.It Fn pci_intr_establish "pc" "ih" "level" "handler" "arg" 457See 458.Xr pci_intr 9 . 459.It Fn pci_intr_disestablish "pc" "ih" 460See 461.Xr pci_intr 9 . 462.It Fn pci_set_powerstate "pc" "tag" "newstate" 463Set power state of the device to newstate. 464Valid values for 465.Fa newstate 466are: 467.Pp 468.Bl -tag -width PCI_PMCSR_STATE_D0 -compact 469.It Dv PCI_PMCSR_STATE_D0 470.It Dv PCI_PMCSR_STATE_D1 471.It Dv PCI_PMCSR_STATE_D2 472.It Dv PCI_PMCSR_STATE_D3 473.El 474.It Fn pci_get_powerstate "pc" "tag" "state" 475Get current power state of the device. 476.It Fn pci_vpd_read "pc" "tag" "offset" "count" "data" 477Read 478.Fa count 47932-bit words of Vital Product Data for the device starting at offset 480.Fa offset 481into the buffer pointed to by 482.Fa data . 483Returns 0 on success or non-zero if the device has no Vital Product Data 484capability or if reading the Vital Product Data fails. 485.It Fn pci_vpd_write "pc" "tag" "offset" "count" "data" 486Write 487.Fa count 48832-bit words of Vital Product Data for the device starting at offset 489.Fa offset 490from the buffer pointed to by 491.Fa data . 492Returns 0 on success or non-zero if the device has no Vital Product Data 493capability of if writing the Vital Product Data fails. 494.It Fn pci_make_tag "pc" "bus" "device" "function" 495Create a new PCI tag for the PCI device specified by the tuple 496.Ao 497bus, device, function 498.Ac . 499This function is not useful to the usual PCI device driver. 500It is generally used by drivers of multi-function devices when 501attaching other PCI device drivers to each function. 502.It Fn pci_decompose_tag "pc" "tag" "busp" "devicep" "fnp" 503Decompose the PCI tag 504.Fa tag 505generated by 506.Fn pci_make_tag 507into its 508.Ao 509bus, device, function 510.Ac 511tuple. 512.It Fn pci_findvendor "id" 513Return the string of the vendor name for the device specified by 514.Fa id . 515.It Fn pci_devinfo "id" "class" "show" "cp" "len" 516Returns the description string from the in-kernel PCI database for the 517device described by 518.Fa id 519and 520.Fa class . 521The description string is returned in 522.Fa cp ; 523the size of that storage is given in 524.Fa len . 525The argument 526.Fa show 527specifies whether the PCI subsystem should report the string to the 528console. 529.It Fn PCI_VENDOR "id" 530Return the PCI vendor id for device 531.Fa id . 532.It Fn PCI_PRODUCT "id" 533Return the PCI product id for device 534.Fa id . 535.It Fn PCI_REVISION "id" 536Return the PCI product revision for device 537.Fa id . 538.El 539.Sh AUTOCONFIGURATION 540During autoconfiguration, a 541.Nm 542driver will receive a pointer to 543.Fa struct pci_attach_args 544describing the device attaches to the PCI bus. 545Drivers match the device using the 546.Fa pa_id 547member using 548.Fn PCI_VENDOR . 549.Fn PCI_PRODUCT 550and 551.Fn PCI_REVISION . 552.Pp 553During the driver attach step, drivers can read the device 554configuration space using 555.Fn pci_conf_read . 556The meaning attached to registers in the PCI configuration space are 557device-dependent, but will usually contain physical addresses of the 558device register windows. 559Device options can also be stored into the PCI configuration space using 560.Fn pci_conf_write . 561For example, the driver can request support for bus-mastering DMA by 562writing the option to the PCI configuration space. 563.Pp 564Device capabilities can be queried using 565.Fn pci_get_capability , 566and returns device-specific information which can be found in the PCI 567configuration space to alter device operation. 568.Pp 569After reading the physical addresses of the device register windows 570from configuration space, these windows must be mapped into kernel 571virtual address space using 572.Fn pci_mapreg_map . 573Device registers can now be accessed using the standard bus-space API 574(see 575.Xr bus_space 9 ) . 576.Pp 577Details of using PCI interrupts is described in 578.Xr pci_intr 9 . 579.Sh DMA SUPPORT 580The PCI bus supports bus-mastering operations from any device on the bus. 581The DMA facilities are accessed through the standard 582.Xr bus_dma 9 583interface. 584To support DMA transfers from the device to the host, it is necessary 585to enable bus-mastering in the PCI configuration space for the device. 586.Pp 587During system shutdown, it is necessary to abort any DMA transfers in 588progress by registering a shutdown hook (see 589.Xr shutdownhook_establish 9 ) . 590.Sh CODE REFERENCES 591This section describes places within the 592.Nx 593source tree where actual code implementing or using the 594machine-independent PCI subsystem can be found. 595All pathnames are relative to 596.Pa /usr/src . 597.Pp 598The PCI subsystem itself is implemented within the files 599.Pa sys/dev/pci/pci.c , 600.Pa sys/dev/pci/pci_subr.c , 601.Pa sys/dev/pci/pci_map.c , 602.Pa sys/dev/pci/pci_quirks.c , 603and 604.Pa sys/dev/pci/pciconf.c . 605Machine-dependent portions are implemented within the file 606.Pa sys/arch/\*[Lt]arch\*[Gt]/pci/pci_machdep.c . 607.Pp 608The database of known devices exists within the file 609.Pa sys/dev/pci/pcidevs_data.h 610and is generated automatically from the file 611.Pa sys/dev/pci/pcidevs . 612New vendor and product identifiers should be added to this file. 613The database can be regenerated using the Makefile 614.Pa sys/dev/pci/Makefile.pcidevs . 615.Sh SEE ALSO 616.Xr pci 4 , 617.Xr autoconf 9 , 618.Xr bus_dma 9 , 619.Xr bus_space 9 , 620.Xr driver 9 , 621.Xr pci_configure_bus 9 , 622.Xr pci_intr 9 , 623.Xr shutdownhook_establish 9 624.Sh HISTORY 625The machine-independent PCI subsystem appeared in 626.Nx 1.2 . 627