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