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