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