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