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