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