1.\" $NetBSD: pci.9,v 1.16 2005/01/28 13:02:33 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 January 28, 2005 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_conf_capture , 46.Nm pci_conf_restore , 47.Nm pci_find_device , 48.Nm pci_get_capability , 49.Nm pci_mapreg_type , 50.Nm pci_mapreg_map , 51.Nm pci_mapreg_info , 52.Nm pci_intr_map , 53.Nm pci_intr_string , 54.Nm pci_intr_evcnt , 55.Nm pci_intr_establish , 56.Nm pci_intr_disestablish , 57.Nm pci_get_powerstate , 58.Nm pci_set_powerstate , 59.Nm pci_vpd_read , 60.Nm pci_vpd_write , 61.Nm pci_make_tag , 62.Nm pci_decompose_tag , 63.Nm pci_findvendor , 64.Nm pci_devinfo , 65.Nm PCI_VENDOR , 66.Nm PCI_PRODUCT , 67.Nm PCI_REVISION 68.Nd Peripheral Component Interconnect 69.Sh SYNOPSIS 70.In machine/bus.h 71.In dev/pci/pcivar.h 72.In dev/pci/pcireg.h 73.In dev/pci/pcidevs.h 74.Ft pcireg_t 75.Fn pci_conf_read "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" 76.Ft void 77.Fn pci_conf_write "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" \ 78"pcireg_t val" 79.Ft void 80.Fn pci_conf_print "pci_chipset_tag_t pc" "pcitag_t tag" \ 81"void (*func)(pci_chipset_tag_t, pcitag_t, const pcireg_t *)" 82.Ft void 83.Fn pci_conf_capture "pci_chipset_tag_t pc" "pcitag_t tag" \ 84"struct pci_conf_state *" 85.Ft void 86.Fn pci_conf_restore "pci_chipset_tag_t pc" "pcitag_t tag" \ 87"struct pci_conf_state *" 88.Ft int 89.Fn pci_find_device "struct pci_attach_args *pa" \ 90"int (*func)(struct pci_attach_args *)" 91.Ft int 92.Fn pci_get_capability "pci_chipset_tag_t pc" "pcitag_t tag" \ 93"int capid" "int *offsetp" "pcireg_t *valuep" 94.Ft pcireg_t 95.Fn pci_mapreg_type "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" 96.Ft int 97.Fn pci_mapreg_map "struct pci_attach_args *pa" "int reg" \ 98"pcireg_t type" "int busflags" "bus_space_tag_t *tagp" \ 99"bus_space_handle_t *handlep" "bus_addr_t *basep" "bus_size_t *sizep" 100.Ft int 101.Fn pci_mapreg_info "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" \ 102"pcireg_t type" "bus_addr_t *basep" "bus_size_t *sizep" "int *flagsp" 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"int newstate" 117.Ft int 118.Fn pci_get_powerstate "pci_chipset_tag_t pc" "pcitag_t tag" 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. It contains 210the 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_conf_read "pc" "tag" "reg" 218Read from register 219.Fa reg 220in PCI configuration space. 221The argument 222.Fa tag 223is the PCI tag for the current device attached to PCI chipset 224.Fa pc . 225.It Fn pci_conf_write "pc" "tag" "reg" "val" 226Write to register 227.Fa reg 228in PCI configuration space. 229The argument 230.Fa tag 231is the PCI tag for the current device attached to PCI chipset 232.Fa pc . 233.It Fn pci_conf_print "pc" "tag" "func" 234Print out most of the registers in the PCI configuration for the 235device. 236The argument 237.Fa tag 238is the PCI tag for the current device attached to PCI chipset 239.Fa pc . 240The argument 241.Fa func 242is a function called by 243.Fn pci_conf_print 244to print the device-dependent registers. 245This function is only useful for driver development and is usually 246wrapped in pre-processor declarations. 247.It Fn pci_conf_capture "pc" "tag" "pcs" 248Capture PCI configuration space into structure 249.Fa pcs . 250The argument 251.Fa tag 252is the PCI tag for the current device attached to the PCI 253chipset 254.Fa pc . 255.It Fn pci_conf_restore "pc" "tag" "pcs" 256Restores PCI configuration space from structure 257.Fa pcs . 258The argument 259.Fa tag 260is the PCI tag for the current device attached to the PCI 261chipset 262.Fa pc . 263.It Fn pci_find_device "pa" "func" 264Find a device using a match function on all probed busses. 265The argument 266.Fa func 267is called by 268.Fn pci_find_device 269to match a device. 270The argument 271.Fa pa 272is filled in if the device is matched. 273.Fn pci_find_device 274returns 1 if the device is matched, and zero otherwise. 275This function is specifically for use by LKMs (see 276.Xr lkm 4 ) 277and its use otherwise is strongly discouraged. 278.It Fn pci_get_capability "pc" "tag" "capid" "offsetp" "valuep" 279Parse the device capability list in configuration space looking for 280capability 281.Fa capid . 282If 283.Fa offsetp 284is not NULL, the register offset in configuration space is returned in 285.Fa offsetp . 286If 287.Fa valuep 288is not NULL, the value of the capability is returned in 289.Fa valuep . 290The argument 291.Fa tag 292is the PCI tag for the current device attached to PCI chipset 293.Fa pc . 294This function returns 1 if the capability was found. 295If the capability was not found, it returns zero, and 296.Fa offsetp 297and 298.Fa valuep 299remain unchanged. 300.It Fn pci_mapreg_type "pc" "tag" "reg" 301Interrogates the Base Address Register (BAR) in configuration space 302specified by 303.Fa reg 304and returns the default (or current) mapping type. 305Valid returns values are: 306.Bl -tag -width compact 307.It PCI_MAPREG_TYPE_IO 308The mapping is to I/O address space. 309.It PCI_MAPREG_TYPE_MEM 310The mapping is to memory address space. 311.It PCI_MAPREG_TYPE_MEM | PCI_MAPREG_MEM_TYPE_64BIT 312The mapping is to 64-bit memory address space. 313.It PCI_MAPREG_TYPE_ROM 314The mapping is to ROM. 315.El 316.sp 317The argument 318.Fa tag 319is the PCI tag for the current device attached to PCI chipset 320.Fa pc . 321.It Fn pci_mapreg_map "pa" "reg" "type" "busflags" "tagp" "handlep" "basep" "sizep" 322Maps the register windows for the device into kernel virtual address 323space. 324This function is generally only called during the driver attach step 325and takes a pointer to the 326.Em struct pci_attach_args 327in 328.Fa pa . 329The physical address of the mapping is in the Base Address Register 330(BAR) in configuration space specified by 331.Fa reg . 332Valid values for the type of mapping 333.Fa type 334are: 335.Bl -tag -width compact 336.It PCI_MAPREG_TYPE_IO 337The mapping should be to I/O address space. 338.It PCI_MAPREG_TYPE_MEM 339The mapping should be to memory address space. 340.It PCI_MAPREG_TYPE_ROM 341The mapping is to access ROM. 342.El 343.sp 344The argument 345.Fa busflags 346are bus-space flags passed to 347.Fn bus_space_map 348to perform the mapping (see 349.Xr bus_space 9 ) . 350The bus-space tag and handle for the mapped register window are 351returned in 352.Fa tagp 353and 354.Fa handlep 355respectively. 356The bus-address and size of the mapping are returned in 357.Fa basep 358and 359.Fa sizep 360respectively. 361If any of 362.Fa tagp , 363.Fa handlep , 364.Fa basep , 365or 366.Fa sizep 367are NULL then 368.Fn pci_mapreg_map 369does not define their return value. 370This function returns zero on success and non-zero on error. 371.It Fn pci_mapreg_info "pc" "tag" "reg" "type" "basep" "sizep" "flagsp" 372Performs the same operations as 373.Fn pci_mapreg_map 374but doesn't actually map the register window into kernel virtual 375address space. 376Returns the bus-address, size and bus flags in 377.Fa basep , 378.Fa sizep 379and 380.Fa flagsp 381respectively. 382These return values can be used by 383.Fn bus_space_map 384to actually map the register window into kernel virtual address space. 385This function is useful for setting up the registers in configuration 386space and deferring the mapping to a later time, such as in a 387bus-independent attachment routine. 388.Fa pci_mapreg_info 389returns zero on success and non-zero on failure. 390.It Fn pci_intr_map "pa" "ih" 391See 392.Xr pci_intr 9 . 393.It Fn pci_intr_string "pc" "ih" 394See 395.Xr pci_intr 9 . 396.It Fn pci_intr_evcnt "pc" "ih" 397See 398.Xr pci_intr 9 . 399.It Fn pci_intr_establish "pc" "ih" "level" "handler" "arg" 400See 401.Xr pci_intr 9 . 402.It Fn pci_intr_disestablish "pc" "ih" 403See 404.Xr pci_intr 9 . 405.It Fn pci_set_powerstate "pc" "tag" "newstate" 406Set power state of the device to newstate. 407Valid values for 408.Fa newstate 409are: 410.Pp 411.Bl -tag -width PCI_PWR_D0 -compact 412.It PCI_PWR_D0 413.It PCI_PWR_D1 414.It PCI_PWR_D2 415.It PCI_PWR_D3 416.El 417.It Fn pci_get_powerstate "pc" "tag" 418Get current power state of the device. 419.It Fn pci_vpd_read "pc" "tag" "offset" "count" "data" 420Read 421.Fa count 42232-bit words of Vital Product Data for the device starting at offset 423.Fa offset 424into the buffer pointed to by 425.Fa data . 426Returns 0 on success or non-zero if the device has no Vital Product Data 427capability or if reading the Vital Product Data fails. 428.It Fn pci_vpd_write "pc" "tag" "offset" "count" "data" 429Write 430.Fa count 43132-bit words of Vital Product Data for the device starting at offset 432.Fa offset 433from the buffer pointed to by 434.Fa data . 435Returns 0 on success or non-zero if the device has no Vital Product Data 436capability of if writing the Vital Product Data fails. 437.It Fn pci_make_tag "pc" "bus" "device" "function" 438Create a new PCI tag for the PCI device specified by the tuple 439.Ao 440bus, device, function 441.Ac . 442This function is not useful to the usual PCI device driver. 443It is generally used by drivers of multi-function devices when 444attaching other PCI device drivers to each function. 445.It Fn pci_decompose_tag "pc" "tag" "busp" "devicep" "fnp" 446Decompose the PCI tag 447.Fa tag 448generated by 449.Fn pci_make_tag 450into its 451.Ao 452bus, device, function 453.Ac 454tuple. 455.It Fn pci_findvendor "id" 456Return the string of the vendor name for the device specified by 457.Fa id . 458.It Fn pci_devinfo "id" "class" "show" "cp" "len" 459Returns the description string from the in-kernel PCI database for the 460device described by 461.Fa id 462and 463.Fa class . 464The description string is returned in 465.Fa cp ; 466the size of that storage is given in 467.Fa len . 468The argument 469.Fa show 470specifies whether the PCI subsystem should report the string to the 471console. 472.It Fn PCI_VENDOR "id" 473Return the PCI vendor id for device 474.Fa id . 475.It Fn PCI_PRODUCT "id" 476Return the PCI product id for device 477.Fa id . 478.It Fn PCI_REVISION "id" 479Return the PCI product revision for device 480.Fa id . 481.El 482.Sh AUTOCONFIGURATION 483During autoconfiguration, a 484.Nm 485driver will receive a pointer to 486.Fa struct pci_attach_args 487describing the device attaches to the PCI bus. 488Drivers match the device using the 489.Fa pa_id 490member using 491.Fn PCI_VENDOR . 492.Fn PCI_PRODUCT 493and 494.Fn PCI_REVISION . 495.Pp 496During the driver attach step, drivers can read the device 497configuration space using 498.Fn pci_conf_read . 499The meaning attached to registers in the PCI configuration space are 500device-dependent, but will usually contain physical addresses of the 501device register windows. 502Device options can also be stored into the PCI configuration space using 503.Fn pci_conf_write . 504For example, the driver can request support for bus-mastering DMA by 505writing the option to the PCI configuration space. 506.Pp 507Device capabilities can be queried using 508.Fn pci_get_capability , 509and returns device-specific information which can be found in the PCI 510configuration space to alter device operation. 511.Pp 512After reading the physical addresses of the device register windows 513from configuration space, these windows must be mapped into kernel 514virtual address space using 515.Fn pci_mapreg_map . 516Device registers can now be accessed using the standard bus-space API 517(see 518.Xr bus_space 9 ) . 519.Pp 520Details of using PCI interrupts is described in 521.Xr pci_intr 9 . 522.Sh DMA SUPPORT 523The PCI bus supports bus-mastering operations from any device on the bus. 524The DMA facilities are accessed through the standard 525.Xr bus_dma 9 526interface. 527To support DMA transfers from the device to the host, it is necessary 528to enable bus-mastering in the PCI configuration space for the device. 529.Pp 530During system shutdown, it is necessary to abort any DMA transfers in 531progress by registering a shutdown hook (see 532.Xr shutdownhook_establish 9 ) . 533.Sh CODE REFERENCES 534This section describes places within the 535.Nx 536source tree where actual code implementing or using the 537machine-independent PCI subsystem can be found. 538All pathnames are relative to 539.Pa /usr/src . 540.Pp 541The PCI subsystem itself is implemented within the files 542.Pa sys/dev/pci/pci.c , 543.Pa sys/dev/pci/pci_subr.c , 544.Pa sys/dev/pci/pci_map.c , 545.Pa sys/dev/pci/pci_quirks.c , 546and 547.Pa sys/dev/pci/pciconf.c . 548Machine-dependent portions are implemented within the file 549.Pa sys/arch/\*[Lt]arch\*[Gt]/pci/pci_machdep.c . 550.Pp 551The database of known devices exists within the file 552.Pa sys/dev/pci/pcidevs_data.h 553and is generated automatically from the file 554.Pa sys/dev/pci/pcidevs . 555New vendor and product identifiers should be added to this file. 556The database can be regenerated using the Makefile 557.Pa sys/dev/pci/Makefile.pcidevs . 558.Sh SEE ALSO 559.Xr pci 4 , 560.Xr autoconf 9 , 561.Xr bus_dma 9 , 562.Xr bus_space 9 , 563.Xr driver 9 , 564.Xr pci_configure_bus 9 , 565.Xr pci_intr 9 , 566.Xr shutdownhook_establish 9 567.Sh HISTORY 568The machine-independent PCI subsystem appeared in 569.Nx 1.2 . 570