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