1.\" 2.\" Copyright (c) 2005 Bruce M Simpson <bms@FreeBSD.org> 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd June 24, 2016 29.Dt PCI 9 30.Os 31.Sh NAME 32.Nm pci , 33.Nm pci_alloc_msi , 34.Nm pci_alloc_msix , 35.Nm pci_disable_busmaster , 36.Nm pci_disable_io , 37.Nm pci_enable_busmaster , 38.Nm pci_enable_io , 39.Nm pci_find_bsf , 40.Nm pci_find_cap , 41.Nm pci_find_dbsf , 42.Nm pci_find_device , 43.Nm pci_find_extcap , 44.Nm pci_find_htcap , 45.Nm pci_find_pcie_root_port , 46.Nm pci_get_id , 47.Nm pci_get_max_payload , 48.Nm pci_get_max_read_req , 49.Nm pci_get_powerstate , 50.Nm pci_get_vpd_ident , 51.Nm pci_get_vpd_readonly , 52.Nm pci_iov_attach , 53.Nm pci_iov_detach , 54.Nm pci_msi_count , 55.Nm pci_msix_count , 56.Nm pci_msix_pba_bar , 57.Nm pci_msix_table_bar , 58.Nm pci_pending_msix , 59.Nm pci_read_config , 60.Nm pci_release_msi , 61.Nm pci_remap_msix , 62.Nm pci_restore_state , 63.Nm pci_save_state , 64.Nm pci_set_max_read_req , 65.Nm pci_set_powerstate , 66.Nm pci_write_config , 67.Nm pcie_adjust_config , 68.Nm pcie_read_config , 69.Nm pcie_write_config 70.Nd PCI bus interface 71.Sh SYNOPSIS 72.In sys/bus.h 73.In dev/pci/pcireg.h 74.In dev/pci/pcivar.h 75.Ft int 76.Fn pci_alloc_msi "device_t dev" "int *count" 77.Ft int 78.Fn pci_alloc_msix "device_t dev" "int *count" 79.Ft int 80.Fn pci_disable_busmaster "device_t dev" 81.Ft int 82.Fn pci_disable_io "device_t dev" "int space" 83.Ft int 84.Fn pci_enable_busmaster "device_t dev" 85.Ft int 86.Fn pci_enable_io "device_t dev" "int space" 87.Ft device_t 88.Fn pci_find_bsf "uint8_t bus" "uint8_t slot" "uint8_t func" 89.Ft int 90.Fn pci_find_cap "device_t dev" "int capability" "int *capreg" 91.Ft device_t 92.Fn pci_find_dbsf "uint32_t domain" "uint8_t bus" "uint8_t slot" "uint8_t func" 93.Ft device_t 94.Fn pci_find_device "uint16_t vendor" "uint16_t device" 95.Ft int 96.Fn pci_find_extcap "device_t dev" "int capability" "int *capreg" 97.Ft int 98.Fn pci_find_htcap "device_t dev" "int capability" "int *capreg" 99.Ft device_t 100.Fn pci_find_pcie_root_port "device_t dev" 101.Ft int 102.Fn pci_get_id "device_t dev" "enum pci_id_type type" "uintptr_t *id" 103.Ft int 104.Fn pci_get_max_payload "device_t dev" 105.Ft int 106.Fn pci_get_max_read_req "device_t dev" 107.Ft int 108.Fn pci_get_powerstate "device_t dev" 109.Ft int 110.Fn pci_get_vpd_ident "device_t dev" "const char **identptr" 111.Ft int 112.Fn pci_get_vpd_readonly "device_t dev" "const char *kw" "const char **vptr" 113.Ft int 114.Fn pci_msi_count "device_t dev" 115.Ft int 116.Fn pci_msix_count "device_t dev" 117.Ft int 118.Fn pci_msix_pba_bar "device_t dev" 119.Ft int 120.Fn pci_msix_table_bar "device_t dev" 121.Ft int 122.Fn pci_pending_msix "device_t dev" "u_int index" 123.Ft uint32_t 124.Fn pci_read_config "device_t dev" "int reg" "int width" 125.Ft int 126.Fn pci_release_msi "device_t dev" 127.Ft int 128.Fn pci_remap_msix "device_t dev" "int count" "const u_int *vectors" 129.Ft void 130.Fn pci_restore_state "device_t dev" 131.Ft void 132.Fn pci_save_state "device_t dev" 133.Ft int 134.Fn pci_set_max_read_req "device_t dev" "int size" 135.Ft int 136.Fn pci_set_powerstate "device_t dev" "int state" 137.Ft void 138.Fn pci_write_config "device_t dev" "int reg" "uint32_t val" "int width" 139.Ft uint32_t 140.Fo pcie_adjust_config 141.Fa "device_t dev" 142.Fa "int reg" 143.Fa "uint32_t mask" 144.Fa "uint32_t val" 145.Fa "int width" 146.Fc 147.Ft uint32_t 148.Fn pcie_read_config "device_t dev" "int reg" "int width" 149.Ft void 150.Fn pcie_write_config "device_t dev" "int reg" "uint32_t val" "int width" 151.In dev/pci/pci_iov.h 152.Ft int 153.Fn pci_iov_attach "device_t dev" "nvlist_t *pf_schema" "nvlist_t *vf_schema" 154.Ft int 155.Fn pci_iov_detach "device_t dev" 156.Sh DESCRIPTION 157The 158.Nm 159set of functions are used for managing PCI devices. 160The functions are split into several groups: 161raw configuration access, 162locating devices, 163device information, 164device configuration, 165and 166message signaled interrupts. 167.Ss Raw Configuration Access 168The 169.Fn pci_read_config 170function is used to read data from the PCI configuration 171space of the device 172.Fa dev , 173at offset 174.Fa reg , 175with 176.Fa width 177specifying the size of the access. 178.Pp 179The 180.Fn pci_write_config 181function is used to write the value 182.Fa val 183to the PCI configuration 184space of the device 185.Fa dev , 186at offset 187.Fa reg , 188with 189.Fa width 190specifying the size of the access. 191.Pp 192The 193.Fn pcie_adjust_config 194function is used to modify the value of a register in the PCI-express 195capability register set of device 196.Fa dev . 197The offset 198.Fa reg 199specifies a relative offset in the register set with 200.Fa width 201specifying the size of the access. 202The new value of the register is computed by modifying bits set in 203.Fa mask 204to the value in 205.Fa val . 206Any bits not specified in 207.Fa mask 208are preserved. 209The previous value of the register is returned. 210.Pp 211The 212.Fn pcie_read_config 213function is used to read the value of a register in the PCI-express 214capability register set of device 215.Fa dev . 216The offset 217.Fa reg 218specifies a relative offset in the register set with 219.Fa width 220specifying the size of the access. 221.Pp 222The 223.Fn pcie_write_config 224function is used to write the value 225.Fa val 226to a register in the PCI-express capability register set of device 227.Fa dev . 228The offset 229.Fa reg 230specifies a relative offset in the register set with 231.Fa width 232specifying the size of the access. 233.Pp 234.Em NOTE : 235Device drivers should only use these functions for functionality that 236is not available via another 237.Fn pci 238function. 239.Ss Locating Devices 240The 241.Fn pci_find_bsf 242function looks up the 243.Vt device_t 244of a PCI device, given its 245.Fa bus , 246.Fa slot , 247and 248.Fa func . 249The 250.Fa slot 251number actually refers to the number of the device on the bus, 252which does not necessarily indicate its geographic location 253in terms of a physical slot. 254Note that in case the system has multiple PCI domains, 255the 256.Fn pci_find_bsf 257function only searches the first one. 258Actually, it is equivalent to: 259.Bd -literal -offset indent 260pci_find_dbsf(0, bus, slot, func); 261.Ed 262.Pp 263The 264.Fn pci_find_dbsf 265function looks up the 266.Vt device_t 267of a PCI device, given its 268.Fa domain , 269.Fa bus , 270.Fa slot , 271and 272.Fa func . 273The 274.Fa slot 275number actually refers to the number of the device on the bus, 276which does not necessarily indicate its geographic location 277in terms of a physical slot. 278.Pp 279The 280.Fn pci_find_device 281function looks up the 282.Vt device_t 283of a PCI device, given its 284.Fa vendor 285and 286.Fa device 287IDs. 288Note that there can be multiple matches for this search; this function 289only returns the first matching device. 290.Ss Device Information 291The 292.Fn pci_find_cap 293function is used to locate the first instance of a PCI capability 294register set for the device 295.Fa dev . 296The capability to locate is specified by ID via 297.Fa capability . 298Constant macros of the form 299.Dv PCIY_xxx 300for standard capability IDs are defined in 301.In dev/pci/pcireg.h . 302If the capability is found, then 303.Fa *capreg 304is set to the offset in configuration space of the capability register set, 305and 306.Fn pci_find_cap 307returns zero. 308If the capability is not found or the device does not support capabilities, 309.Fn pci_find_cap 310returns an error. 311.Pp 312The 313.Fn pci_find_extcap 314function is used to locate the first instance of a PCI-express 315extended capability register set for the device 316.Fa dev . 317The extended capability to locate is specified by ID via 318.Fa capability . 319Constant macros of the form 320.Dv PCIZ_xxx 321for standard extended capability IDs are defined in 322.In dev/pci/pcireg.h . 323If the extended capability is found, then 324.Fa *capreg 325is set to the offset in configuration space of the extended capability 326register set, and 327.Fn pci_find_extcap 328returns zero. 329If the extended capability is not found or the device is not a 330PCI-express device, 331.Fn pci_find_extcap 332returns an error. 333.Pp 334The 335.Fn pci_find_htcap 336function is used to locate the first instance of a HyperTransport capability 337register set for the device 338.Fa dev . 339The capability to locate is specified by type via 340.Fa capability . 341Constant macros of the form 342.Dv PCIM_HTCAP_xxx 343for standard HyperTransport capability types are defined in 344.In dev/pci/pcireg.h . 345If the capability is found, then 346.Fa *capreg 347is set to the offset in configuration space of the capability register set, 348and 349.Fn pci_find_htcap 350returns zero. 351If the capability is not found or the device is not a HyperTransport device, 352.Fn pci_find_htcap 353returns an error. 354.Pp 355The 356.Fn pci_find_pcie_root_port 357function walks up the PCI device hierarchy to locate the PCI-express root 358port upstream of 359.Fa dev . 360If a root port is not found, 361.Fn pci_find_pcie_root_port 362returns 363.Dv NULL . 364.Pp 365The 366.Fn pci_get_id 367function is used to read an identifier from a device. 368The 369.Fa type 370flag is used to specify which identifier to read. 371The following flags are supported: 372.Bl -hang -width ".Dv PCI_ID_RID" 373.It Dv PCI_ID_RID 374Read the routing identifier for the device. 375.It Dv PCI_ID_MSI 376Read the MSI routing ID. 377This is needed by some interrupt controllers to route MSI and MSI-X interrupts. 378.El 379.Pp 380The 381.Fn pci_get_vpd_ident 382function is used to fetch a device's Vital Product Data 383.Pq VPD 384identifier string. 385If the device 386.Fa dev 387supports VPD and provides an identifier string, 388then 389.Fa *identptr 390is set to point at a read-only, null-terminated copy of the identifier 391string, 392and 393.Fn pci_get_vpd_ident 394returns zero. 395If the device does not support VPD or does not provide an identifier 396string, 397then 398.Fn pci_get_vpd_ident 399returns an error. 400.Pp 401The 402.Fn pci_get_vpd_readonly 403function is used to fetch the value of a single VPD read-only keyword 404for the device 405.Fa dev . 406The keyword to fetch is identified by the two character string 407.Fa kw . 408If the device supports VPD and provides a read-only value for the 409requested keyword, 410then 411.Fa *vptr 412is set to point at a read-only, null-terminated copy of the value, 413and 414.Fn pci_get_vpd_readonly 415returns zero. 416If the device does not support VPD or does not provide the requested 417keyword, 418then 419.Fn pci_get_vpd_readonly 420returns an error. 421.Ss Device Configuration 422The 423.Fn pci_enable_busmaster 424function enables PCI bus mastering for the device 425.Fa dev , 426by setting the 427.Dv PCIM_CMD_BUSMASTEREN 428bit in the 429.Dv PCIR_COMMAND 430register. 431The 432.Fn pci_disable_busmaster 433function clears this bit. 434.Pp 435The 436.Fn pci_enable_io 437function enables memory or I/O port address decoding for the device 438.Fa dev , 439by setting the 440.Dv PCIM_CMD_MEMEN 441or 442.Dv PCIM_CMD_PORTEN 443bit in the 444.Dv PCIR_COMMAND 445register appropriately. 446The 447.Fn pci_disable_io 448function clears the appropriate bit. 449The 450.Fa space 451argument specifies which resource is affected; this can be either 452.Dv SYS_RES_MEMORY 453or 454.Dv SYS_RES_IOPORT 455as appropriate. 456Device drivers should generally not use these routines directly. 457The PCI bus will enable decoding automatically when a 458.Dv SYS_RES_MEMORY 459or 460.Dv SYS_RES_IOPORT 461resource is activated via 462.Xr bus_alloc_resource 9 463or 464.Xr bus_activate_resource 9 . 465.Pp 466The 467.Fn pci_get_max_payload 468function returns the current maximum TLP payload size in bytes for a 469PCI-express device. 470If the 471.Fa dev 472device is not a PCI-express device, 473.Fn pci_get_max_payload 474returns zero. 475.Pp 476The 477.Fn pci_get_max_read_req 478function returns the current maximum read request size in bytes for a 479PCI-express device. 480If the 481.Fa dev 482device is not a PCI-express device, 483.Fn pci_get_max_read_req 484returns zero. 485.Pp 486The 487.Fn pci_set_max_read_req 488sets the PCI-express maximum read request size for 489.Fa dev . 490The requested 491.Fa size 492may be adjusted, 493and 494.Fn pci_set_max_read_req 495returns the actual size set in bytes. 496If the 497.Fa dev 498device is not a PCI-express device, 499.Fn pci_set_max_read_req 500returns zero. 501.Pp 502The 503.Fn pci_get_powerstate 504function returns the current power state of the device 505.Fa dev . 506If the device does not support power management capabilities, then the default 507state of 508.Dv PCI_POWERSTATE_D0 509is returned. 510The following power states are defined by PCI: 511.Bl -hang -width ".Dv PCI_POWERSTATE_UNKNOWN" 512.It Dv PCI_POWERSTATE_D0 513State in which device is on and running. 514It is receiving full power from the system and delivering 515full functionality to the user. 516.It Dv PCI_POWERSTATE_D1 517Class-specific low-power state in which device context may or 518may not be lost. 519Busses in this state cannot do anything to the bus, to 520force devices to lose context. 521.It Dv PCI_POWERSTATE_D2 522Class-specific low-power state in which device context may or 523may not be lost. 524Attains greater power savings than 525.Dv PCI_POWERSTATE_D1 . 526Busses in this state can cause devices to lose some context. 527Devices 528.Em must 529be prepared for the bus to be in this state or higher. 530.It Dv PCI_POWERSTATE_D3 531State in which the device is off and not running. 532Device context is lost, and power from the device can 533be removed. 534.It Dv PCI_POWERSTATE_UNKNOWN 535State of the device is unknown. 536.El 537.Pp 538The 539.Fn pci_set_powerstate 540function is used to transition the device 541.Fa dev 542to the PCI power state 543.Fa state . 544If the device does not support power management capabilities or 545it does not support the specific power state 546.Fa state , 547then the function will fail with 548.Er EOPNOTSUPP . 549.Pp 550The 551.Fn pci_iov_attach 552function is used to advertise that the given device 553.Pq and associated device driver 554supports PCI Single-Root I/O Virtualization 555.Pq SR-IOV . 556A driver that supports SR-IOV must implement the 557.Xr PCI_IOV_INIT 9 , 558.Xr PCI_IOV_ADD_VF 9 559and 560.Xr PCI_IOV_UNINIT 9 561methods. 562This function should be called during the 563.Xr DEVICE_ATTACH 9 564method. 565If this function returns an error, it is recommended that the device driver 566still successfully attaches, but runs with SR-IOV disabled. 567The 568.Fa pf_schema 569and 570.Fa vf_schema 571parameters are used to define what device-specific configuration parameters the 572device driver accepts when SR-IOV is enabled for the Physical Function 573.Pq PF 574and for individual Virtual Functions 575.Pq VFs 576respectively. 577See 578.Xr pci_iov_schema 9 579for details on how to construct the schema. 580If either the 581.Pa pf_schema 582or 583.Pa vf_schema 584is invalid or specifies parameter names that conflict with parameter names that 585are already in use, 586.Fn pci_iov_attach 587will return an error and SR-IOV will not be available on the PF device. 588If a driver does not accept configuration parameters for either the PF device 589or the VF devices, the driver must pass an empty schema for that device. 590The SR-IOV infrastructure takes ownership of the 591.Fa pf_schema 592and 593.Fa vf_schema 594and is responsible for freeing them. 595The driver must never free the schemas itself. 596.Pp 597The 598.Fn pci_iov_detach 599function is used to advise the SR-IOV infrastructure that the driver for the 600given device is attempting to detach and that all SR-IOV resources for the 601device must be released. 602This function must be called during the 603.Xr DEVICE_DETACH 9 604method if 605.Fn pci_iov_attach 606was successfully called on the device and 607.Fn pci_iov_detach 608has not subsequently been called on the device and returned no error. 609If this function returns an error, the 610.Xr DEVICE_DETACH 9 611method must fail and return an error, as detaching the PF driver while VF 612devices are active would cause system instability. 613This function is safe to call and will always succeed if 614.Fn pci_iov_attach 615previously failed with an error on the given device, or if 616.Fn pci_iov_attach 617was never called on the device. 618.Pp 619The 620.Fn pci_save_state 621and 622.Fn pci_restore_state 623functions can be used by a device driver to save and restore standard PCI 624config registers. 625The 626.Fn pci_save_state 627function must be invoked while the device has valid state before 628.Fn pci_restore_state 629can be used. 630If the device is not in the fully-powered state 631.Pq Dv PCI_POWERSTATE_D0 632when 633.Fn pci_restore_state 634is invoked, 635then the device will be transitioned to 636.Dv PCI_POWERSTATE_D0 637before any config registers are restored. 638.Ss Message Signaled Interrupts 639Message Signaled Interrupts 640.Pq MSI 641and 642Enhanced Message Signaled Interrupts 643.Pq MSI-X 644are PCI capabilities that provide an alternate method for PCI 645devices to signal interrupts. 646The legacy INTx interrupt is available to PCI devices as a 647.Dv SYS_RES_IRQ 648resource with a resource ID of zero. 649MSI and MSI-X interrupts are available to PCI devices as one or more 650.Dv SYS_RES_IRQ 651resources with resource IDs greater than zero. 652A driver must ask the PCI bus to allocate MSI or MSI-X interrupts 653using 654.Fn pci_alloc_msi 655or 656.Fn pci_alloc_msix 657before it can use MSI or MSI-X 658.Dv SYS_RES_IRQ 659resources. 660A driver is not allowed to use the legacy INTx 661.Dv SYS_RES_IRQ 662resource if MSI or MSI-X interrupts have been allocated, 663and attempts to allocate MSI or MSI-X interrupts will fail if the 664driver is currently using the legacy INTx 665.Dv SYS_RES_IRQ 666resource. 667A driver is only allowed to use either MSI or MSI-X, 668but not both. 669.Pp 670The 671.Fn pci_msi_count 672function returns the maximum number of MSI messages supported by the 673device 674.Fa dev . 675If the device does not support MSI, 676then 677.Fn pci_msi_count 678returns zero. 679.Pp 680The 681.Fn pci_alloc_msi 682function attempts to allocate 683.Fa *count 684MSI messages for the device 685.Fa dev . 686The 687.Fn pci_alloc_msi 688function may allocate fewer messages than requested for various 689reasons including requests for more messages than the device 690.Fa dev 691supports, 692or if the system has a shortage of available MSI messages. 693On success, 694.Fa *count 695is set to the number of messages allocated and 696.Fn pci_alloc_msi 697returns zero. 698The 699.Dv SYS_RES_IRQ 700resources for the allocated messages will be available at consecutive 701resource IDs beginning with one. 702If 703.Fn pci_alloc_msi 704is not able to allocate any messages, 705it returns an error. 706Note that MSI only supports message counts that are powers of two; 707requests to allocate a non-power of two count of messages will fail. 708.Pp 709The 710.Fn pci_release_msi 711function is used to release any allocated MSI or MSI-X messages back 712to the system. 713If any MSI or MSI-X 714.Dv SYS_RES_IRQ 715resources are allocated by the driver or have a configured interrupt 716handler, 717this function will fail with 718.Er EBUSY . 719The 720.Fn pci_release_msi 721function returns zero on success and an error on failure. 722.Pp 723The 724.Fn pci_msix_count 725function returns the maximum number of MSI-X messages supported by the 726device 727.Fa dev . 728If the device does not support MSI-X, 729then 730.Fn pci_msix_count 731returns zero. 732.Pp 733The 734.Fn pci_msix_pba_bar 735function returns the offset in configuration space of the Base Address Register 736.Pq BAR 737containing the MSI-X Pending Bit Array (PBA) for device 738.Fa dev . 739The returned value can be used as the resource ID with 740.Xr bus_alloc_resource 9 741and 742.Xr bus_release_resource 9 743to allocate the BAR. 744If the device does not support MSI-X, 745then 746.Fn pci_msix_pba_bar 747returns -1. 748.Pp 749The 750.Fn pci_msix_table_bar 751function returns the offset in configuration space of the BAR 752containing the MSI-X vector table for device 753.Fa dev . 754The returned value can be used as the resource ID with 755.Xr bus_alloc_resource 9 756and 757.Xr bus_release_resource 9 758to allocate the BAR. 759If the device does not support MSI-X, 760then 761.Fn pci_msix_table_bar 762returns -1. 763.Pp 764The 765.Fn pci_alloc_msix 766function attempts to allocate 767.Fa *count 768MSI-X messages for the device 769.Fa dev . 770The 771.Fn pci_alloc_msix 772function may allocate fewer messages than requested for various 773reasons including requests for more messages than the device 774.Fa dev 775supports, 776or if the system has a shortage of available MSI-X messages. 777On success, 778.Fa *count 779is set to the number of messages allocated and 780.Fn pci_alloc_msix 781returns zero. 782For MSI-X messages, 783the resource ID for each 784.Dv SYS_RES_IRQ 785resource identifies the index in the MSI-X table of the 786corresponding message. 787A resource ID of one maps to the first index of the MSI-X table; 788a resource ID two identifies the second index in the table, etc. 789The 790.Fn pci_alloc_msix 791function assigns the 792.Fa *count 793messages allocated to the first 794.Fa *count 795table indices. 796If 797.Fn pci_alloc_msix 798is not able to allocate any messages, 799it returns an error. 800Unlike MSI, 801MSI-X does not require message counts that are powers of two. 802.Pp 803The BARs containing the MSI-X vector table and PBA must be 804allocated via 805.Xr bus_alloc_resource 9 806before calling 807.Fn pci_alloc_msix 808and must not be released until after calling 809.Fn pci_release_msi . 810Note that the vector table and PBA may be stored in the same BAR or in 811different BARs. 812.Pp 813The 814.Fn pci_pending_msix 815function examines the 816.Fa dev 817device's PBA 818to determine the pending status of the MSI-X message at table index 819.Fa index . 820If the indicated message is pending, 821this function returns a non-zero value; 822otherwise, 823it returns zero. 824Passing an invalid 825.Fa index 826to this function will result in undefined behavior. 827.Pp 828As mentioned in the description of 829.Fn pci_alloc_msix , 830MSI-X messages are initially assigned to the first N table entries. 831A driver may use a different distribution of available messages to 832table entries via the 833.Fn pci_remap_msix 834function. 835Note that this function must be called after a successful call to 836.Fn pci_alloc_msix 837but before any of the 838.Dv SYS_RES_IRQ 839resources are allocated. 840The 841.Fn pci_remap_msix 842function returns zero on success, 843or an error on failure. 844.Pp 845The 846.Fa vectors 847array should contain 848.Fa count 849message vectors. 850The array maps directly to the MSI-X table in that the first entry in 851the array specifies the message used for the first entry in the MSI-X 852table, 853the second entry in the array corresponds to the second entry in the 854MSI-X table, 855etc. 856The vector value in each array index can either be zero to indicate 857that no message should be assigned to the corresponding MSI-X table entry, 858or it can be a number from one to N 859.Po 860where N is the count returned from the previous call to 861.Fn pci_alloc_msix 862.Pc 863to indicate which of the allocated messages should be assigned to the 864corresponding MSI-X table entry. 865.Pp 866If 867.Fn pci_remap_msix 868succeeds, 869each MSI-X table entry with a non-zero vector will have an associated 870.Dv SYS_RES_IRQ 871resource whose resource ID corresponds to the table index as described 872above for 873.Fn pci_alloc_msix . 874MSI-X table entries that with a vector of zero will not have an 875associated 876.Dv SYS_RES_IRQ 877resource. 878Additionally, 879if any of the original messages allocated by 880.Fn pci_alloc_msix 881are not used in the new distribution of messages in the MSI-X table, 882they will be released automatically. 883Note that if a driver wishes to use fewer messages than were allocated by 884.Fn pci_alloc_msix , 885the driver must use a single, contiguous range of messages beginning 886with one in the new distribution. 887The 888.Fn pci_remap_msix 889function will fail if this condition is not met. 890.Sh IMPLEMENTATION NOTES 891The 892.Vt pci_addr_t 893type varies according to the size of the PCI bus address 894space on the target architecture. 895.Sh SEE ALSO 896.Xr pci 4 , 897.Xr pciconf 8 , 898.Xr bus_alloc_resource 9 , 899.Xr bus_dma 9 , 900.Xr bus_release_resource 9 , 901.Xr bus_setup_intr 9 , 902.Xr bus_teardown_intr 9 , 903.Xr devclass 9 , 904.Xr device 9 , 905.Xr driver 9 , 906.Xr rman 9 907.Rs 908.%B FreeBSD Developers' Handbook 909.%T NewBus 910.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/ 911.Re 912.Rs 913.%A Shanley 914.%A Anderson 915.%B PCI System Architecture 916.%N 2nd Edition 917.%I Addison-Wesley 918.%O ISBN 0-201-30974-2 919.Re 920.Sh AUTHORS 921.An -nosplit 922This manual page was written by 923.An Bruce M Simpson Aq Mt bms@FreeBSD.org 924and 925.An John Baldwin Aq Mt jhb@FreeBSD.org . 926.Sh BUGS 927The kernel PCI code has a number of references to 928.Dq "slot numbers" . 929These do not refer to the geographic location of PCI devices, 930but to the device number assigned by the combination of the PCI IDSEL 931mechanism and the platform firmware. 932This should be taken note of when working with the kernel PCI code. 933.Pp 934The PCI bus driver should allocate the MSI-X vector table and PBA internally 935as necessary rather than requiring the caller to do so. 936