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