1.\" $NetBSD: pci.9,v 1.41 2015/08/15 16:39:58 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.\" 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 August 14, 2015 31.Dt PCI 9 32.Os 33.Sh NAME 34.Nm PCI , 35.Nm pci_activate , 36.Nm pci_bus_devorder , 37.Nm pci_chipset_tag_create , 38.Nm pci_chipset_tag_destroy , 39.Nm pci_conf_read , 40.Nm pci_conf_write , 41.Nm pci_conf_print , 42.Nm pci_conf_capture , 43.Nm pci_conf_restore , 44.Nm pci_find_device , 45.Nm pci_get_capability , 46.Nm pci_get_ht_capability , 47.Nm pci_mapreg_type , 48.Nm pci_mapreg_map , 49.Nm pci_mapreg_info , 50.Nm pci_intr_map , 51.Nm pci_intr_string , 52.Nm pci_intr_evcnt , 53.Nm pci_intr_establish , 54.Nm pci_intr_disestablish , 55.Nm pci_get_powerstate , 56.Nm pci_set_powerstate , 57.Nm pci_vpd_read , 58.Nm pci_vpd_write , 59.Nm pci_make_tag , 60.Nm pci_decompose_tag , 61.Nm pci_findvendor , 62.Nm pci_devinfo , 63.Nm PCI_VENDOR , 64.Nm PCI_PRODUCT , 65.Nm PCI_REVISION 66.Nd Peripheral Component Interconnect 67.Sh SYNOPSIS 68.In sys/bus.h 69.In dev/pci/pcivar.h 70.In dev/pci/pcireg.h 71.In dev/pci/pcidevs.h 72.Ft int 73.Fn pci_bus_devorder "pci_chipset_tag_t pc" "int bus" "uint8_t *devs" \ 74"int maxdevs" 75.Ft int 76.Fn pci_activate "pci_chipset_tag_t pc" "pcitag_t tag" "device_t dev" \ 77"int (*wakeup)(pci_chipset_tag_t pc, pcitag_t tag, device_t dev, pcireg_t reg)" 78.Ft int 79.Fn pci_chipset_tag_create "pci_chipset_tag_t opc" "uint64_t present" \ 80"const struct pci_overrides *ov" "void *ctx" "pci_chipset_tag_t *pcp" 81.Ft void 82.Fn pci_chipset_tag_destroy "pci_chipset_tag_t pc" 83.Ft pcireg_t 84.Fn pci_conf_read "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" 85.Ft void 86.Fn pci_conf_write "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" \ 87"pcireg_t val" 88.Ft void 89.Fn pci_conf_print "pci_chipset_tag_t pc" "pcitag_t tag" \ 90"void (*func)(pci_chipset_tag_t, pcitag_t, const pcireg_t *)" 91.Ft void 92.Fn pci_conf_capture "pci_chipset_tag_t pc" "pcitag_t tag" \ 93"struct pci_conf_state *" 94.Ft void 95.Fn pci_conf_restore "pci_chipset_tag_t pc" "pcitag_t tag" \ 96"struct pci_conf_state *" 97.Ft int 98.Fn pci_find_device "struct pci_attach_args *pa" \ 99"int (*func)(const struct pci_attach_args *)" 100.Ft int 101.Fn pci_get_capability "pci_chipset_tag_t pc" "pcitag_t tag" \ 102"int capid" "int *offsetp" "pcireg_t *valuep" 103.Ft int 104.Fn pci_get_ht_capability "pci_chipset_tag_t pc" "pcitag_t tag" \ 105"int capid" "int *offsetp" "pcireg_t *valuep" 106.Ft pcireg_t 107.Fn pci_mapreg_type "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" 108.Ft int 109.Fn pci_mapreg_map "const struct pci_attach_args *pa" "int reg" \ 110"pcireg_t type" "int busflags" "bus_space_tag_t *tagp" \ 111"bus_space_handle_t *handlep" "bus_addr_t *basep" "bus_size_t *sizep" 112.Ft int 113.Fn pci_mapreg_info "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" \ 114"pcireg_t type" "bus_addr_t *basep" "bus_size_t *sizep" "int *flagsp" 115.Ft int 116.Fn pci_find_rom "const struct pci_attach_args *pa" \ 117"bus_space_tag_t bst" "bus_space_handle_t bsh" "int code" \ 118"bus_space_handle_t *handlep" "bus_space_size_t *sizep" 119.Ft int 120.Fn pci_intr_map "const struct pci_attach_args *pa" "pci_intr_handle_t *ih" 121.Ft const char * 122.Fn pci_intr_string "pci_chipset_tag_t pc" "pci_intr_handle_t ih" 123.Ft const struct evcnt * 124.Fn pci_intr_evcnt "pci_chipset_tag_t pc" "pci_intr_handle_t ih" 125.Ft void * 126.Fn pci_intr_establish "pci_chipset_tag_t pc" "pci_intr_handle_t ih" \ 127"int level" "int (*handler)(void *)" "void *arg" 128.Ft void 129.Fn pci_intr_disestablish "pci_chipset_tag_t pc" "void *ih" 130.Ft int 131.Fn pci_set_powerstate "pci_chipset_tag_t pc" "pcitag_t tag" \ 132"pcireg_t newstate" 133.Ft int 134.Fn pci_get_powerstate "pci_chipset_tag_t pc" "pcitag_t tag" "pcireg_t *state" 135.Ft int 136.Fn pci_vpd_read "pci_chipset_tag_t pc" "pcitag_t tag" "int offset" \ 137"int count" "pcireg_t *data" 138.Ft int 139.Fn pci_vpd_write "pci_chipset_tag_t pc" "pcitag_t tag" "int offset" \ 140"int count" "pcireg_t *data" 141.Ft pcitag_t 142.Fn pci_make_tag "pci_chipset_tag_t pc" "int bus" "int device" \ 143"int function" 144.Ft void 145.Fn pci_decompose_tag "pci_chipset_tag_t pc" "pcitag_t tag" \ 146"int *busp" "int *devicep" "int *functionp" 147.Ft char * 148.Fn pci_findvendor "pcireg_t id" 149.Ft void 150.Fn pci_devinfo "pcireg_t id" "pcireg_t class" "int show" "char *cp" "size_t len" 151.Ft void 152.Fn pci_aprint_devinfo "struct pci_attach_args *pa" "const char *naive" 153.Ft int 154.Fn PCI_VENDOR "pcireg_t id" 155.Ft int 156.Fn PCI_PRODUCT "pcireg_t id" 157.Ft int 158.Fn PCI_REVISION "pcireg_t id" 159.Sh DESCRIPTION 160The machine-independent 161.Nm 162subsystem provides support for PCI devices. 163.Pp 164The PCI bus was initially developed by Intel in the early 1990's to 165replace the ISA bus for interfacing with their Pentium processor. 166The PCI specification is widely regarded as well designed, and the 167PCI bus has found widespread acceptance in machines ranging from 168Apple's PowerPC-based systems to Sun's UltraSPARC-based machines. 169.Pp 170The PCI bus is a multiplexed bus, allowing addresses and data on the same 171pins for a reduced number of pins. 172Data transfers can be 8-bit, 16-bit or 32-bit. 173A 64-bit extended PCI bus is also defined. 174Multi-byte transfers are little-endian. 175The PCI bus operates up to 33MHz and any device on the bus can be 176the bus master. 177.Pp 178AGP is a version of PCI optimised for high-throughput data rates, 179particularly for accelerated frame buffers. 180.Pp 181The PCI bus is a "plug and play" bus, in the sense that devices can be 182configured dynamically by software. 183The PCI interface chip on a PCI device bus presents a small window 184of registers into the PCI configuration space. 185These registers contain information about the device such as the vendor 186and a product ID. 187The configuration registers can also be written to by software to alter 188how the device interfaces to the PCI bus. 189An important register in the configuration space is the Base Address 190Register (BAR). 191The BAR is written to by software to map the device registers into a 192window of processor address space. 193Once this mapping is done, the device registers can be accessed relative 194to the base address. 195.Sh DATA TYPES 196Drivers for devices attached to the 197.Nm 198will make use of the following data types: 199.Bl -tag -width compact 200.It Fa pcireg_t 201Configuration space register. 202.It Fa pci_chipset_tag_t 203Chipset tag for the PCI bus. 204.It Fa pcitag_t 205Configuration tag describing the location and function of the PCI 206device. 207It contains the tuple 208.Ao 209bus, device, function 210.Ac . 211.It Fa pci_intr_handle_t 212The opaque handle describing an established interrupt handler. 213.It Fa struct pci_attach_args 214Devices have their identity recorded in this structure. 215It contains the following members: 216.Bd -literal 217 bus_space_tag_t pa_iot; /* pci i/o space tag */ 218 bus_space_tag_t pa_memt; /* pci mem space tag */ 219 bus_dma_tag_t pa_dmat; /* DMA tag */ 220 pci_chipset_tag_t pa_pc; 221 int pa_flags; /* flags */ 222 pcitag_t pa_tag; 223 pcireg_t pa_id; 224 pcireg_t pa_class; 225.Ed 226.It Fa struct pci_conf_state 227Stores the PCI configuration state of a device. 228It contains the following member: 229.Bd -literal 230 pcireg_t reg[16]; /* pci conf register */ 231.Ed 232.It Fa struct pci_overrides 233Stores pointers to functions that override the architecture's 234default 235.Xr pci 9 236and 237.Xr pci_intr 9 238implementation. 239It contains the following members: 240.Bd -literal 241 pcireg_t (*ov_conf_read)(void *, 242 pci_chipset_tag_t, pcitag_t, int); 243 void (*ov_conf_write)(void *, 244 pci_chipset_tag_t, pcitag_t, int, pcireg_t); 245 int (*ov_intr_map)(void *, 246 const struct pci_attach_args *, pci_intr_handle_t *); 247 const char *(*ov_intr_string)(void *, 248 pci_chipset_tag_t, pci_intr_handle_t); 249 const struct evcnt *(*ov_intr_evcnt)(void *, 250 pci_chipset_tag_t, pci_intr_handle_t); 251 void *(*ov_intr_establish)(void *, 252 pci_chipset_tag_t, pci_intr_handle_t, 253 int, int (*)(void *), void *); 254 void (*ov_intr_disestablish)(void *, 255 pci_chipset_tag_t, void *); 256 pcitag_t (*ov_make_tag)(void *, 257 pci_chipset_tag_t, int, int, int); 258 void (*ov_decompose_tag)(void *, 259 pci_chipset_tag_t, pcitag_t, int *, int *, int *); 260.Ed 261.El 262.Sh FUNCTIONS 263.Bl -tag -width compact 264.It Fn pci_bus_devorder "pc" "bus" "devs" "maxdevs" 265Tell how many devices a PCI bus driver should probe 266and in what order. 267If 268.Fa maxdevs 269is less than or equal to zero, return 0 and 270do not modify 271.Fa devs . 272Otherwise, return 273.Fa maxdevs 274or the number of devices on 275.Fa bus 276to probe, whichever is less, and copy to 277.Fa devs 278each of the PCI device numbers to probe in the order that they 279should be probed. 280.Fn pci_bus_devorder 281will not copy more than 282.Fa maxdevs 283device numbers to 284.Fa devs . 285.It Fn pci_activate "pc" "tag" "dev" "fun" 286Attempt to bring the device to state D0. 287If the device is not in the D0 state call 288.Fa fun 289to restore its state. 290If 291.Fa fun 292is 293.Dv NULL 294then restoring from state D3 is going to fail. 295.It Fn pci_chipset_tag_create "opc" "present" "ov" "ctx" "pcp" 296Create a copy of the tag 297.Fa opc 298at 299.Fa *pcp . 300Except for the behavior 301overridden by 302.Fa ov , 303.Fa *pcp 304inherits the behavior of 305.Fa opc 306under 307.Nm 308calls. 309.Pp 310.Fa ov 311contains function pointers corresponding to 312.Nm 313routines. 314Each function pointer has a corresponding bit in 315.Fa present , 316and if that bit is 1, the function pointer overrides the corresponding 317.Nm 318call for the new tag. 319Any combination of these bits may be set in 320.Fa present : 321.Pp 322.Bl -tag -width PCI_OVERRIDE_INTR_DISESTABLISH -compact 323.It Dv PCI_OVERRIDE_CONF_READ 324.It Dv PCI_OVERRIDE_CONF_WRITE 325.It Dv PCI_OVERRIDE_INTR_MAP 326.It Dv PCI_OVERRIDE_INTR_STRING 327.It Dv PCI_OVERRIDE_INTR_EVCNT 328.It Dv PCI_OVERRIDE_INTR_ESTABLISH 329.It Dv PCI_OVERRIDE_INTR_DISESTABLISH 330.It Dv PCI_OVERRIDE_MAKE_TAG 331.It Dv PCI_OVERRIDE_DECOMPOSE_TAG 332.El 333.Pp 334.Fn pci_chipset_tag_create 335does not copy 336.Fa ov . 337After a new tag is created 338by 339.Fn pci_chipset_tag_create , 340.Fa ov 341must not be destroyed until after the 342tag is destroyed by 343.Fn pci_chipset_tag_destroy . 344.Pp 345The first argument of every override-function is a 346.Vt "void *" , 347and 348.Fa ctx 349is passed in that argument. 350.Pp 351Return 0 if the call succeeds. 352Return 353.Dv EOPNOTSUPP 354if the architecture does not support overrides. 355Return 356.Dv EINVAL 357if 358.Fa present 359is 0, if 360.Fa ov 361is 362.Dv NULL , 363or if 364.Fa present 365indicates that an override is present, but the corresponding override 366in 367.Fa ov 368is 369.Dv NULL . 370.Pp 371If the call does not succeed, 372.Fa *pcp 373is undefined. 374.It Fn pci_chipset_tag_destroy "pc" 375Destroy a tag, 376.Fa pc , 377created by a prior call to 378.Fn pci_chipset_tag_create . 379If 380.Fa pc 381was not created by 382.Fn pci_chipset_tag_create , 383results are undefined. 384If 385.Fa pc 386was already destroyed, results are undefined. 387.It Fn pci_conf_read "pc" "tag" "reg" 388Read from register 389.Fa reg 390in PCI configuration space. 391The argument 392.Fa tag 393is the PCI tag for the current device attached to PCI chipset 394.Fa pc . 395.It Fn pci_conf_write "pc" "tag" "reg" "val" 396Write to register 397.Fa reg 398in PCI configuration space. 399The argument 400.Fa tag 401is the PCI tag for the current device attached to PCI chipset 402.Fa pc . 403.It Fn pci_conf_print "pc" "tag" "func" 404Print out most of the registers in the PCI configuration for the 405device. 406The argument 407.Fa tag 408is the PCI tag for the current device attached to PCI chipset 409.Fa pc . 410The argument 411.Fa func 412is a function called by 413.Fn pci_conf_print 414to print the device-dependent registers. 415This function is only useful for driver development and is usually 416wrapped in pre-processor declarations. 417.It Fn pci_conf_capture "pc" "tag" "pcs" 418Capture PCI configuration space into structure 419.Fa pcs . 420The argument 421.Fa tag 422is the PCI tag for the current device attached to the PCI 423chipset 424.Fa pc . 425.It Fn pci_conf_restore "pc" "tag" "pcs" 426Restores PCI configuration space from structure 427.Fa pcs . 428The argument 429.Fa tag 430is the PCI tag for the current device attached to the PCI 431chipset 432.Fa pc . 433.It Fn pci_find_device "pa" "func" 434Find a device using a match function on all probed busses. 435The argument 436.Fa func 437is called by 438.Fn pci_find_device 439to match a device. 440The argument 441.Fa pa 442is filled in if the device is matched. 443.Fn pci_find_device 444returns 1 if the device is matched, and zero otherwise. 445This function is specifically for use by kernel modules 446and its use otherwise is strongly discouraged. 447.It Fn pci_get_capability "pc" "tag" "capid" "offsetp" "valuep" 448Parse the device capability list in configuration space looking for 449capability 450.Fa capid . 451If 452.Fa offsetp 453is not 454.Dv NULL , 455the register offset in configuration space is returned in 456.Fa offsetp . 457If 458.Fa valuep 459is not 460.Dv NULL , 461the value of the capability is returned in 462.Fa valuep . 463The argument 464.Fa tag 465is the PCI tag for the current device attached to PCI chipset 466.Fa pc . 467This function returns 1 if the capability was found. 468If the capability was not found, it returns zero, and 469.Fa offsetp 470and 471.Fa valuep 472remain unchanged. 473.It Fn pci_get_ht_capability "pc" "tag" "capid" "offsetp" "valuep" 474Parse the device capability list in HyperTransport configuration 475space looking for capability 476.Fa capid . 477If 478.Fa offsetp 479is not 480.Dv NULL , 481the register offset in configuration space is returned in 482.Fa offsetp . 483If 484.Fa valuep 485is not 486.Dv NULL , 487the value of the capability is returned in 488.Fa valuep . 489The argument 490.Fa tag 491is the PCI tag for the current device attached to PCI chipset 492.Fa pc . 493This function returns 1 if the capability was found. 494If the capability was not found, it returns zero, and 495.Fa offsetp 496and 497.Fa valuep 498remain unchanged. 499.It Fn pci_mapreg_type "pc" "tag" "reg" 500Interrogates the Base Address Register (BAR) in configuration space 501specified by 502.Fa reg 503and returns the default (or current) mapping type. 504Valid returns values are: 505.Bl -tag -width compact 506.It Dv PCI_MAPREG_TYPE_IO 507The mapping is to I/O address space. 508.It Dv PCI_MAPREG_TYPE_MEM 509The mapping is to memory address space. 510.It Dv PCI_MAPREG_TYPE_MEM | PCI_MAPREG_MEM_TYPE_64BIT 511The mapping is to 64-bit memory address space. 512.It Dv PCI_MAPREG_TYPE_ROM 513The mapping is to ROM. 514Note that in the current implementation, 515.Dv PCI_MAPREG_TYPE_ROM 516has the same numeric value as 517.Dv PCI_MAPREG_TYPE_MEM . 518.El 519.Pp 520The argument 521.Fa tag 522is the PCI tag for the current device attached to PCI chipset 523.Fa pc . 524.It Fn pci_mapreg_map "pa" "reg" "type" "busflags" "tagp" "handlep" "basep" "sizep" 525Maps the register windows for the device into kernel virtual address 526space. 527This function is generally only called during the driver attach step 528and takes a pointer to the 529.Em struct pci_attach_args 530in 531.Fa pa . 532The physical address of the mapping is in the Base Address Register 533(BAR) in configuration space specified by 534.Fa reg . 535Valid values for the type of mapping 536.Fa type 537are: 538.Bl -tag -width compact 539.It Dv PCI_MAPREG_TYPE_IO 540The mapping should be to I/O address space. 541.It Dv PCI_MAPREG_TYPE_MEM 542The mapping should be to memory address space. 543.It Dv PCI_MAPREG_TYPE_ROM 544The mapping is to access ROM. 545This type of mapping is only permitted when the value for 546.Fa reg 547is 548.Dv PCI_MAPREG_ROM . 549.El 550.Pp 551The argument 552.Fa busflags 553are bus-space flags passed to 554.Fn bus_space_map 555to perform the mapping (see 556.Xr bus_space 9 ) . 557The bus-space tag and handle for the mapped register window are 558returned in 559.Fa tagp 560and 561.Fa handlep 562respectively. 563The bus-address and size of the mapping are returned in 564.Fa basep 565and 566.Fa sizep 567respectively. 568If any of 569.Fa tagp , 570.Fa handlep , 571.Fa basep , 572or 573.Fa sizep 574are 575.Dv NULL 576then 577.Fn pci_mapreg_map 578does not define their return value. 579This function returns zero on success and non-zero on error. 580.It Fn pci_mapreg_info "pc" "tag" "reg" "type" "basep" "sizep" "flagsp" 581Performs the same operations as 582.Fn pci_mapreg_map 583but doesn't actually map the register window into kernel virtual 584address space. 585Returns the bus-address, size and bus flags in 586.Fa basep , 587.Fa sizep 588and 589.Fa flagsp 590respectively. 591These return values can be used by 592.Fn bus_space_map 593to actually map the register window into kernel virtual address space. 594This function is useful for setting up the registers in configuration 595space and deferring the mapping to a later time, such as in a 596bus-independent attachment routine. 597.Fa pci_mapreg_info 598returns zero on success and non-zero on failure. 599.It Fn pci_find_rom "pa" "bst" "bsh" "code" "handlep" "sizep" 600Locates a suitable ROM image within a PCI expansion ROM previously mapped with 601.Fn pci_mapreg_map 602and creates a subregion for it with 603.Fn bus_space_subregion . 604The 605.Fa bst 606and 607.Fa bsh 608arguments are the bus tag and handle obtained with the prior call to 609.Fn pci_mapreg_map . 610Valid values for the image type 611.Fa code 612are: 613.Bl -tag -width compact 614.It Dv PCI_ROM_CODE_TYPE_X86 615Find a ROM image containing i386 executable code for use by PC BIOS. 616.It Dv PCI_ROM_CODE_TYPE_OFW 617Find a ROM image containing Forth code for use by Open Firmware. 618.It Dv PCI_ROM_CODE_TYPE_HPPA 619Find a ROM image containing HP PA/RISC executable code. 620.El 621.Pp 622The created subregion will cover the entire selected ROM image, including 623header data. 624The handle to this subregion is returned in 625.Fa handlep . 626The size of the image (and the corresponding subregion) is returned in 627.Fa sizep . 628This function can only be used with expansion ROMs located at the 629.Dv PCI_MAPREG_ROM 630base address register (BAR). 631.It Fn pci_intr_map "pa" "ih" 632See 633.Xr pci_intr 9 . 634.It Fn pci_intr_string "pc" "ih" 635See 636.Xr pci_intr 9 . 637.It Fn pci_intr_evcnt "pc" "ih" 638See 639.Xr pci_intr 9 . 640.It Fn pci_intr_establish "pc" "ih" "level" "handler" "arg" 641See 642.Xr pci_intr 9 . 643.It Fn pci_intr_disestablish "pc" "ih" 644See 645.Xr pci_intr 9 . 646.It Fn pci_set_powerstate "pc" "tag" "newstate" 647Set power state of the device to newstate. 648Valid values for 649.Fa newstate 650are: 651.Pp 652.Bl -tag -width PCI_PMCSR_STATE_D0 -compact 653.It Dv PCI_PMCSR_STATE_D0 654.It Dv PCI_PMCSR_STATE_D1 655.It Dv PCI_PMCSR_STATE_D2 656.It Dv PCI_PMCSR_STATE_D3 657.El 658.It Fn pci_get_powerstate "pc" "tag" "state" 659Get current power state of the device. 660.It Fn pci_vpd_read "pc" "tag" "offset" "count" "data" 661Read 662.Fa count 66332-bit words of Vital Product Data for the device starting at offset 664.Fa offset 665into the buffer pointed to by 666.Fa data . 667Returns 0 on success or non-zero if the device has no Vital Product Data 668capability or if reading the Vital Product Data fails. 669.It Fn pci_vpd_write "pc" "tag" "offset" "count" "data" 670Write 671.Fa count 67232-bit words of Vital Product Data for the device starting at offset 673.Fa offset 674from the buffer pointed to by 675.Fa data . 676Returns 0 on success or non-zero if the device has no Vital Product Data 677capability of if writing the Vital Product Data fails. 678.It Fn pci_make_tag "pc" "bus" "device" "function" 679Create a new PCI tag for the PCI device specified by the tuple 680.Ao 681bus, device, function 682.Ac . 683This function is not useful to the usual PCI device driver. 684It is generally used by drivers of multi-function devices when 685attaching other PCI device drivers to each function. 686.It Fn pci_decompose_tag "pc" "tag" "busp" "devicep" "fnp" 687Decompose the PCI tag 688.Fa tag 689generated by 690.Fn pci_make_tag 691into its 692.Ao 693bus, device, function 694.Ac 695tuple. 696.It Fn pci_findvendor "id" 697Return the string of the vendor name for the device specified by 698.Fa id . 699.It Fn pci_devinfo "id" "class" "show" "cp" "len" 700Returns the description string from the in-kernel PCI database for the 701device described by 702.Fa id 703and 704.Fa class . 705The description string is returned in 706.Fa cp ; 707the size of that storage is given in 708.Fa len . 709The argument 710.Fa show 711specifies whether the PCI subsystem should report the string to the 712console. 713.It Fn pci_aprint_devinfo "pa" "naive" 714Print device information to the console and system log, using the 715.Xr aprint_normal 9 716and 717.Xr aprint_naive 9 718functions. 719For the device information, the 720.Dq pci_devinfo 721function above is used, or the 722.Ar naive 723argument in the 724.Dq AB_QUIET 725case. 726This function is intended to be used early in device attach. 727.It Fn PCI_VENDOR "id" 728Return the PCI vendor id for device 729.Fa id . 730.It Fn PCI_PRODUCT "id" 731Return the PCI product id for device 732.Fa id . 733.It Fn PCI_REVISION "id" 734Return the PCI product revision for device 735.Fa id . 736.El 737.Sh AUTOCONFIGURATION 738During autoconfiguration, a 739.Nm 740driver will receive a pointer to 741.Fa struct pci_attach_args 742describing the device attaches to the PCI bus. 743Drivers match the device using the 744.Fa pa_id 745member using 746.Fn PCI_VENDOR . 747.Fn PCI_PRODUCT 748and 749.Fn PCI_REVISION . 750.Pp 751During the driver attach step, drivers can read the device 752configuration space using 753.Fn pci_conf_read . 754The meaning attached to registers in the PCI configuration space are 755device-dependent, but will usually contain physical addresses of the 756device register windows. 757Device options can also be stored into the PCI configuration space using 758.Fn pci_conf_write . 759For example, the driver can request support for bus-mastering DMA by 760writing the option to the PCI configuration space. 761.Pp 762Device capabilities can be queried using 763.Fn pci_get_capability , 764and returns device-specific information which can be found in the PCI 765configuration space to alter device operation. 766.Pp 767After reading the physical addresses of the device register windows 768from configuration space, these windows must be mapped into kernel 769virtual address space using 770.Fn pci_mapreg_map . 771Device registers can now be accessed using the standard bus-space API 772(see 773.Xr bus_space 9 ) . 774.Pp 775Details of using PCI interrupts is described in 776.Xr pci_intr 9 . 777.Sh DMA SUPPORT 778The PCI bus supports bus-mastering operations from any device on the bus. 779The DMA facilities are accessed through the standard 780.Xr bus_dma 9 781interface. 782To support DMA transfers from the device to the host, it is necessary 783to enable bus-mastering in the PCI configuration space for the device. 784.Pp 785During system shutdown, it is necessary to abort any DMA transfers in 786progress by registering a shutdown hook (see 787.Xr pmf 9 ) . 788.Sh CODE REFERENCES 789The PCI subsystem itself is implemented within the files 790.Pa sys/dev/pci/pci.c , 791.Pa sys/dev/pci/pci_subr.c , 792.Pa sys/dev/pci/pci_map.c , 793.Pa sys/dev/pci/pci_quirks.c , 794and 795.Pa sys/dev/pci/pciconf.c . 796Machine-dependent portions are implemented within the file 797.Pa sys/arch/\*[Lt]arch\*[Gt]/pci/pci_machdep.c . 798.Pp 799The database of known devices exists within the file 800.Pa sys/dev/pci/pcidevs_data.h 801and is generated automatically from the file 802.Pa sys/dev/pci/pcidevs . 803New vendor and product identifiers should be added to this file. 804The database can be regenerated using the Makefile 805.Pa sys/dev/pci/Makefile.pcidevs . 806.Sh SEE ALSO 807.Xr pci 4 , 808.Xr autoconf 9 , 809.Xr bus_dma 9 , 810.Xr bus_space 9 , 811.Xr driver 9 , 812.Xr pci_configure_bus 9 , 813.Xr pci_intr 9 , 814.Xr pmf 9 815.Sh HISTORY 816The machine-independent PCI subsystem appeared in 817.Nx 1.2 . 818