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