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