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