1.\" $NetBSD: pci.9,v 1.29 2009/04/17 19:02:03 cegger 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 April 17, 2009 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" "device_t dev" \ 70"int (*wakeup)(pci_chipset_tag_t pc, pcitag_t tag" \ 71"\t\tdevice_t dev, 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" "dev" "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 kernel modules 288and its use otherwise is strongly discouraged. 289.It Fn pci_get_capability "pc" "tag" "capid" "offsetp" "valuep" 290Parse the device capability list in configuration space looking for 291capability 292.Fa capid . 293If 294.Fa offsetp 295is not NULL, the register offset in configuration space is returned in 296.Fa offsetp . 297If 298.Fa valuep 299is not NULL, the value of the capability is returned in 300.Fa valuep . 301The argument 302.Fa tag 303is the PCI tag for the current device attached to PCI chipset 304.Fa pc . 305This function returns 1 if the capability was found. 306If the capability was not found, it returns zero, and 307.Fa offsetp 308and 309.Fa valuep 310remain unchanged. 311.It Fn pci_mapreg_type "pc" "tag" "reg" 312Interrogates the Base Address Register (BAR) in configuration space 313specified by 314.Fa reg 315and returns the default (or current) mapping type. 316Valid returns values are: 317.Bl -tag -width compact 318.It Dv PCI_MAPREG_TYPE_IO 319The mapping is to I/O address space. 320.It Dv PCI_MAPREG_TYPE_MEM 321The mapping is to memory address space. 322.It Dv PCI_MAPREG_TYPE_MEM | PCI_MAPREG_MEM_TYPE_64BIT 323The mapping is to 64-bit memory address space. 324.It Dv PCI_MAPREG_TYPE_ROM 325The mapping is to ROM. 326Note that in the current implementation, 327.Dv PCI_MAPREG_TYPE_ROM 328has the same numeric value as 329.Dv PCI_MAPREG_TYPE_MEM . 330.El 331.Pp 332The argument 333.Fa tag 334is the PCI tag for the current device attached to PCI chipset 335.Fa pc . 336.It Fn pci_mapreg_map "pa" "reg" "type" "busflags" "tagp" "handlep" "basep" "sizep" 337Maps the register windows for the device into kernel virtual address 338space. 339This function is generally only called during the driver attach step 340and takes a pointer to the 341.Em struct pci_attach_args 342in 343.Fa pa . 344The physical address of the mapping is in the Base Address Register 345(BAR) in configuration space specified by 346.Fa reg . 347Valid values for the type of mapping 348.Fa type 349are: 350.Bl -tag -width compact 351.It Dv PCI_MAPREG_TYPE_IO 352The mapping should be to I/O address space. 353.It Dv PCI_MAPREG_TYPE_MEM 354The mapping should be to memory address space. 355.It Dv PCI_MAPREG_TYPE_ROM 356The mapping is to access ROM. 357This type of mapping is only permitted when the value for 358.Fa reg 359is 360.Dv PCI_MAPREG_ROM . 361.El 362.Pp 363The argument 364.Fa busflags 365are bus-space flags passed to 366.Fn bus_space_map 367to perform the mapping (see 368.Xr bus_space 9 ) . 369The bus-space tag and handle for the mapped register window are 370returned in 371.Fa tagp 372and 373.Fa handlep 374respectively. 375The bus-address and size of the mapping are returned in 376.Fa basep 377and 378.Fa sizep 379respectively. 380If any of 381.Fa tagp , 382.Fa handlep , 383.Fa basep , 384or 385.Fa sizep 386are NULL then 387.Fn pci_mapreg_map 388does not define their return value. 389This function returns zero on success and non-zero on error. 390.It Fn pci_mapreg_info "pc" "tag" "reg" "type" "basep" "sizep" "flagsp" 391Performs the same operations as 392.Fn pci_mapreg_map 393but doesn't actually map the register window into kernel virtual 394address space. 395Returns the bus-address, size and bus flags in 396.Fa basep , 397.Fa sizep 398and 399.Fa flagsp 400respectively. 401These return values can be used by 402.Fn bus_space_map 403to actually map the register window into kernel virtual address space. 404This function is useful for setting up the registers in configuration 405space and deferring the mapping to a later time, such as in a 406bus-independent attachment routine. 407.Fa pci_mapreg_info 408returns zero on success and non-zero on failure. 409.It Fn pci_find_rom "pa" "bst" "bsh" "code" "handlep" "sizep" 410Locates a suitable ROM image within a PCI expansion ROM previously mapped with 411.Fn pci_mapreg_map 412and creates a subregion for it with 413.Fn bus_space_subregion . 414The 415.Fa bst 416and 417.Fa bsh 418arguments are the bus tag and handle obtained with the prior call to 419.Fn pci_mapreg_map . 420Valid values for the image type 421.Fa code 422are: 423.Bl -tag -width compact 424.It Dv PCI_ROM_CODE_TYPE_X86 425Find a ROM image containing i386 executable code for use by PC BIOS. 426.It Dv PCI_ROM_CODE_TYPE_OFW 427Find a ROM image containing Forth code for use by Open Firmware. 428.It Dv PCI_ROM_CODE_TYPE_HPPA 429Find a ROM image containing HP PA/RISC executable code. 430.El 431.Pp 432The created subregion will cover the entire selected ROM image, including 433header data. 434The handle to this subregion is returned in 435.Fa handlep . 436The size of the image (and the corresponding subregion) is returned in 437.Fa sizep . 438This function can only be used with expansion ROMs located at the 439.Dv PCI_MAPREG_ROM 440base address register (BAR). 441.It Fn pci_intr_map "pa" "ih" 442See 443.Xr pci_intr 9 . 444.It Fn pci_intr_string "pc" "ih" 445See 446.Xr pci_intr 9 . 447.It Fn pci_intr_evcnt "pc" "ih" 448See 449.Xr pci_intr 9 . 450.It Fn pci_intr_establish "pc" "ih" "level" "handler" "arg" 451See 452.Xr pci_intr 9 . 453.It Fn pci_intr_disestablish "pc" "ih" 454See 455.Xr pci_intr 9 . 456.It Fn pci_set_powerstate "pc" "tag" "newstate" 457Set power state of the device to newstate. 458Valid values for 459.Fa newstate 460are: 461.Pp 462.Bl -tag -width PCI_PMCSR_STATE_D0 -compact 463.It Dv PCI_PMCSR_STATE_D0 464.It Dv PCI_PMCSR_STATE_D1 465.It Dv PCI_PMCSR_STATE_D2 466.It Dv PCI_PMCSR_STATE_D3 467.El 468.It Fn pci_get_powerstate "pc" "tag" "state" 469Get current power state of the device. 470.It Fn pci_vpd_read "pc" "tag" "offset" "count" "data" 471Read 472.Fa count 47332-bit words of Vital Product Data for the device starting at offset 474.Fa offset 475into the buffer pointed to by 476.Fa data . 477Returns 0 on success or non-zero if the device has no Vital Product Data 478capability or if reading the Vital Product Data fails. 479.It Fn pci_vpd_write "pc" "tag" "offset" "count" "data" 480Write 481.Fa count 48232-bit words of Vital Product Data for the device starting at offset 483.Fa offset 484from the buffer pointed to by 485.Fa data . 486Returns 0 on success or non-zero if the device has no Vital Product Data 487capability of if writing the Vital Product Data fails. 488.It Fn pci_make_tag "pc" "bus" "device" "function" 489Create a new PCI tag for the PCI device specified by the tuple 490.Ao 491bus, device, function 492.Ac . 493This function is not useful to the usual PCI device driver. 494It is generally used by drivers of multi-function devices when 495attaching other PCI device drivers to each function. 496.It Fn pci_decompose_tag "pc" "tag" "busp" "devicep" "fnp" 497Decompose the PCI tag 498.Fa tag 499generated by 500.Fn pci_make_tag 501into its 502.Ao 503bus, device, function 504.Ac 505tuple. 506.It Fn pci_findvendor "id" 507Return the string of the vendor name for the device specified by 508.Fa id . 509.It Fn pci_devinfo "id" "class" "show" "cp" "len" 510Returns the description string from the in-kernel PCI database for the 511device described by 512.Fa id 513and 514.Fa class . 515The description string is returned in 516.Fa cp ; 517the size of that storage is given in 518.Fa len . 519The argument 520.Fa show 521specifies whether the PCI subsystem should report the string to the 522console. 523.It Fn PCI_VENDOR "id" 524Return the PCI vendor id for device 525.Fa id . 526.It Fn PCI_PRODUCT "id" 527Return the PCI product id for device 528.Fa id . 529.It Fn PCI_REVISION "id" 530Return the PCI product revision for device 531.Fa id . 532.El 533.Sh AUTOCONFIGURATION 534During autoconfiguration, a 535.Nm 536driver will receive a pointer to 537.Fa struct pci_attach_args 538describing the device attaches to the PCI bus. 539Drivers match the device using the 540.Fa pa_id 541member using 542.Fn PCI_VENDOR . 543.Fn PCI_PRODUCT 544and 545.Fn PCI_REVISION . 546.Pp 547During the driver attach step, drivers can read the device 548configuration space using 549.Fn pci_conf_read . 550The meaning attached to registers in the PCI configuration space are 551device-dependent, but will usually contain physical addresses of the 552device register windows. 553Device options can also be stored into the PCI configuration space using 554.Fn pci_conf_write . 555For example, the driver can request support for bus-mastering DMA by 556writing the option to the PCI configuration space. 557.Pp 558Device capabilities can be queried using 559.Fn pci_get_capability , 560and returns device-specific information which can be found in the PCI 561configuration space to alter device operation. 562.Pp 563After reading the physical addresses of the device register windows 564from configuration space, these windows must be mapped into kernel 565virtual address space using 566.Fn pci_mapreg_map . 567Device registers can now be accessed using the standard bus-space API 568(see 569.Xr bus_space 9 ) . 570.Pp 571Details of using PCI interrupts is described in 572.Xr pci_intr 9 . 573.Sh DMA SUPPORT 574The PCI bus supports bus-mastering operations from any device on the bus. 575The DMA facilities are accessed through the standard 576.Xr bus_dma 9 577interface. 578To support DMA transfers from the device to the host, it is necessary 579to enable bus-mastering in the PCI configuration space for the device. 580.Pp 581During system shutdown, it is necessary to abort any DMA transfers in 582progress by registering a shutdown hook (see 583.Xr shutdownhook_establish 9 ) . 584.Sh CODE REFERENCES 585This section describes places within the 586.Nx 587source tree where actual code implementing or using the 588machine-independent PCI subsystem can be found. 589All pathnames are relative to 590.Pa /usr/src . 591.Pp 592The PCI subsystem itself is implemented within the files 593.Pa sys/dev/pci/pci.c , 594.Pa sys/dev/pci/pci_subr.c , 595.Pa sys/dev/pci/pci_map.c , 596.Pa sys/dev/pci/pci_quirks.c , 597and 598.Pa sys/dev/pci/pciconf.c . 599Machine-dependent portions are implemented within the file 600.Pa sys/arch/\*[Lt]arch\*[Gt]/pci/pci_machdep.c . 601.Pp 602The database of known devices exists within the file 603.Pa sys/dev/pci/pcidevs_data.h 604and is generated automatically from the file 605.Pa sys/dev/pci/pcidevs . 606New vendor and product identifiers should be added to this file. 607The database can be regenerated using the Makefile 608.Pa sys/dev/pci/Makefile.pcidevs . 609.Sh SEE ALSO 610.Xr pci 4 , 611.Xr autoconf 9 , 612.Xr bus_dma 9 , 613.Xr bus_space 9 , 614.Xr driver 9 , 615.Xr pci_configure_bus 9 , 616.Xr pci_intr 9 , 617.Xr shutdownhook_establish 9 618.Sh HISTORY 619The machine-independent PCI subsystem appeared in 620.Nx 1.2 . 621