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