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_HOT 668State in which the device is off and not running. 669Device context is lost, and power from the device can 670be (but is not necessarily) removed. 671.It Dv PCI_POWERSTATE_D3_COLD 672Same as 673.Dv PCI_POWERSTATE_D3_HOT , 674except power has been removed from the device. 675.It Dv PCI_POWERSTATE_UNKNOWN 676State of the device is unknown. 677.El 678.Pp 679The 680.Fn pci_set_powerstate 681function is used to transition the device 682.Fa dev 683to the PCI power state 684.Fa state . 685If the device does not support power management capabilities or 686it does not support the specific power state 687.Fa state , 688then the function will fail with 689.Er EOPNOTSUPP . 690.Pp 691The 692.Fn pci_clear_pme 693function is used to clear any pending PME# signal and disable generation 694of power management events. 695.Pp 696The 697.Fn pci_enable_pme 698function is used to enable generation of power management events before 699suspending a device. 700.Pp 701The 702.Fn pci_iov_attach 703function is used to advertise that the given device 704.Pq and associated device driver 705supports PCI Single-Root I/O Virtualization 706.Pq SR-IOV . 707A driver that supports SR-IOV must implement the 708.Xr PCI_IOV_INIT 9 , 709.Xr PCI_IOV_ADD_VF 9 710and 711.Xr PCI_IOV_UNINIT 9 712methods. 713This function should be called during the 714.Xr DEVICE_ATTACH 9 715method. 716If this function returns an error, it is recommended that the device driver 717still successfully attaches, but runs with SR-IOV disabled. 718The 719.Fa pf_schema 720and 721.Fa vf_schema 722parameters are used to define what device-specific configuration parameters the 723device driver accepts when SR-IOV is enabled for the Physical Function 724.Pq PF 725and for individual Virtual Functions 726.Pq VFs 727respectively. 728See 729.Xr pci_iov_schema 9 730for details on how to construct the schema. 731If either the 732.Pa pf_schema 733or 734.Pa vf_schema 735is invalid or specifies parameter names that conflict with parameter names that 736are already in use, 737.Fn pci_iov_attach 738will return an error and SR-IOV will not be available on the PF device. 739If a driver does not accept configuration parameters for either the PF device 740or the VF devices, the driver must pass an empty schema for that device. 741The SR-IOV infrastructure takes ownership of the 742.Fa pf_schema 743and 744.Fa vf_schema 745and is responsible for freeing them. 746The driver must never free the schemas itself. 747.Pp 748The 749.Fn pci_iov_attach_name 750function is a variant of 751.Fn pci_iov_attach 752that allows the name of the associated character device in 753.Pa /dev/iov 754to be specified by 755.Fa fmt . 756The 757.Fn pci_iov_attach 758function uses the name of 759.Fa dev 760as the device name. 761.Pp 762The 763.Fn pci_iov_detach 764function is used to advise the SR-IOV infrastructure that the driver for the 765given device is attempting to detach and that all SR-IOV resources for the 766device must be released. 767This function must be called during the 768.Xr DEVICE_DETACH 9 769method if 770.Fn pci_iov_attach 771was successfully called on the device and 772.Fn pci_iov_detach 773has not subsequently been called on the device and returned no error. 774If this function returns an error, the 775.Xr DEVICE_DETACH 9 776method must fail and return an error, as detaching the PF driver while VF 777devices are active would cause system instability. 778This function is safe to call and will always succeed if 779.Fn pci_iov_attach 780previously failed with an error on the given device, or if 781.Fn pci_iov_attach 782was never called on the device. 783.Pp 784The 785.Fn pci_save_state 786and 787.Fn pci_restore_state 788functions can be used by a device driver to save and restore standard PCI 789config registers. 790The 791.Fn pci_save_state 792function must be invoked while the device has valid state before 793.Fn pci_restore_state 794can be used. 795If the device is not in the fully-powered state 796.Pq Dv PCI_POWERSTATE_D0 797when 798.Fn pci_restore_state 799is invoked, 800then the device will be transitioned to 801.Dv PCI_POWERSTATE_D0 802before any config registers are restored. 803.Pp 804The 805.Fn pcie_flr 806function requests a Function Level Reset 807.Pq FLR 808of 809.Fa dev . 810If 811.Fa dev 812is not a PCI-express device or does not support Function Level Resets via 813the PCI-express device control register, 814.Dv false 815is returned. 816Pending transactions are drained by disabling busmastering and calling 817.Fn pcie_wait_for_pending_transactions 818before resetting the device. 819The 820.Fa max_delay 821argument specifies the maximum timeout to wait for pending transactions as 822described for 823.Fn pcie_wait_for_pending_transactions . 824If 825.Fn pcie_wait_for_pending_transactions 826fails with a timeout and 827.Fa force 828is 829.Dv false , 830busmastering is re-enabled and 831.Dv false 832is returned. 833If 834.Fn pcie_wait_for_pending_transactions 835fails with a timeout and 836.Fa force 837is 838.Dv true , 839the device is reset despite the timeout. 840After the reset has been requested, 841.Nm pcie_flr 842sleeps for at least 100 milliseconds before returning 843.Dv true . 844Note that 845.Nm pcie_flr 846does not save and restore any state around the reset. 847The caller should save and restore state as needed. 848.Ss Message Signaled Interrupts 849Message Signaled Interrupts 850.Pq MSI 851and 852Enhanced Message Signaled Interrupts 853.Pq MSI-X 854are PCI capabilities that provide an alternate method for PCI 855devices to signal interrupts. 856The legacy INTx interrupt is available to PCI devices as a 857.Dv SYS_RES_IRQ 858resource with a resource ID of zero. 859MSI and MSI-X interrupts are available to PCI devices as one or more 860.Dv SYS_RES_IRQ 861resources with resource IDs greater than zero. 862A driver must ask the PCI bus to allocate MSI or MSI-X interrupts 863using 864.Fn pci_alloc_msi 865or 866.Fn pci_alloc_msix 867before it can use MSI or MSI-X 868.Dv SYS_RES_IRQ 869resources. 870A driver is not allowed to use the legacy INTx 871.Dv SYS_RES_IRQ 872resource if MSI or MSI-X interrupts have been allocated, 873and attempts to allocate MSI or MSI-X interrupts will fail if the 874driver is currently using the legacy INTx 875.Dv SYS_RES_IRQ 876resource. 877A driver is only allowed to use either MSI or MSI-X, 878but not both. 879.Pp 880The 881.Fn pci_msi_count 882function returns the maximum number of MSI messages supported by the 883device 884.Fa dev . 885If the device does not support MSI, 886then 887.Fn pci_msi_count 888returns zero. 889.Pp 890The 891.Fn pci_alloc_msi 892function attempts to allocate 893.Fa *count 894MSI messages for the device 895.Fa dev . 896The 897.Fn pci_alloc_msi 898function may allocate fewer messages than requested for various 899reasons including requests for more messages than the device 900.Fa dev 901supports, 902or if the system has a shortage of available MSI messages. 903On success, 904.Fa *count 905is set to the number of messages allocated and 906.Fn pci_alloc_msi 907returns zero. 908The 909.Dv SYS_RES_IRQ 910resources for the allocated messages will be available at consecutive 911resource IDs beginning with one. 912If 913.Fn pci_alloc_msi 914is not able to allocate any messages, 915it returns an error. 916Note that MSI only supports message counts that are powers of two; 917requests to allocate a non-power of two count of messages will fail. 918.Pp 919The 920.Fn pci_release_msi 921function is used to release any allocated MSI or MSI-X messages back 922to the system. 923If any MSI or MSI-X 924.Dv SYS_RES_IRQ 925resources are allocated by the driver or have a configured interrupt 926handler, 927this function will fail with 928.Er EBUSY . 929The 930.Fn pci_release_msi 931function returns zero on success and an error on failure. 932.Pp 933The 934.Fn pci_msix_count 935function returns the maximum number of MSI-X messages supported by the 936device 937.Fa dev . 938If the device does not support MSI-X, 939then 940.Fn pci_msix_count 941returns zero. 942.Pp 943The 944.Fn pci_msix_pba_bar 945function returns the offset in configuration space of the Base Address Register 946.Pq BAR 947containing the MSI-X Pending Bit Array (PBA) for device 948.Fa dev . 949The returned value can be used as the resource ID with 950.Xr bus_alloc_resource 9 951and 952.Xr bus_release_resource 9 953to allocate the BAR. 954If the device does not support MSI-X, 955then 956.Fn pci_msix_pba_bar 957returns -1. 958.Pp 959The 960.Fn pci_msix_table_bar 961function returns the offset in configuration space of the BAR 962containing the MSI-X vector table for device 963.Fa dev . 964The returned value can be used as the resource ID with 965.Xr bus_alloc_resource 9 966and 967.Xr bus_release_resource 9 968to allocate the BAR. 969If the device does not support MSI-X, 970then 971.Fn pci_msix_table_bar 972returns -1. 973.Pp 974The 975.Fn pci_alloc_msix 976function attempts to allocate 977.Fa *count 978MSI-X messages for the device 979.Fa dev . 980The 981.Fn pci_alloc_msix 982function may allocate fewer messages than requested for various 983reasons including requests for more messages than the device 984.Fa dev 985supports, 986or if the system has a shortage of available MSI-X messages. 987On success, 988.Fa *count 989is set to the number of messages allocated and 990.Fn pci_alloc_msix 991returns zero. 992For MSI-X messages, 993the resource ID for each 994.Dv SYS_RES_IRQ 995resource identifies the index in the MSI-X table of the 996corresponding message. 997A resource ID of one maps to the first index of the MSI-X table; 998a resource ID two identifies the second index in the table, etc. 999The 1000.Fn pci_alloc_msix 1001function assigns the 1002.Fa *count 1003messages allocated to the first 1004.Fa *count 1005table indices. 1006If 1007.Fn pci_alloc_msix 1008is not able to allocate any messages, 1009it returns an error. 1010Unlike MSI, 1011MSI-X does not require message counts that are powers of two. 1012.Pp 1013The BARs containing the MSI-X vector table and PBA must be 1014allocated via 1015.Xr bus_alloc_resource 9 1016before calling 1017.Fn pci_alloc_msix 1018and must not be released until after calling 1019.Fn pci_release_msi . 1020Note that the vector table and PBA may be stored in the same BAR or in 1021different BARs. 1022.Pp 1023The 1024.Fn pci_pending_msix 1025function examines the 1026.Fa dev 1027device's PBA 1028to determine the pending status of the MSI-X message at table index 1029.Fa index . 1030If the indicated message is pending, 1031this function returns a non-zero value; 1032otherwise, 1033it returns zero. 1034Passing an invalid 1035.Fa index 1036to this function will result in undefined behavior. 1037.Pp 1038As mentioned in the description of 1039.Fn pci_alloc_msix , 1040MSI-X messages are initially assigned to the first N table entries. 1041A driver may use a different distribution of available messages to 1042table entries via the 1043.Fn pci_remap_msix 1044function. 1045Note that this function must be called after a successful call to 1046.Fn pci_alloc_msix 1047but before any of the 1048.Dv SYS_RES_IRQ 1049resources are allocated. 1050The 1051.Fn pci_remap_msix 1052function returns zero on success, 1053or an error on failure. 1054.Pp 1055The 1056.Fa vectors 1057array should contain 1058.Fa count 1059message vectors. 1060The array maps directly to the MSI-X table in that the first entry in 1061the array specifies the message used for the first entry in the MSI-X 1062table, 1063the second entry in the array corresponds to the second entry in the 1064MSI-X table, 1065etc. 1066The vector value in each array index can either be zero to indicate 1067that no message should be assigned to the corresponding MSI-X table entry, 1068or it can be a number from one to N 1069.Po 1070where N is the count returned from the previous call to 1071.Fn pci_alloc_msix 1072.Pc 1073to indicate which of the allocated messages should be assigned to the 1074corresponding MSI-X table entry. 1075.Pp 1076If 1077.Fn pci_remap_msix 1078succeeds, 1079each MSI-X table entry with a non-zero vector will have an associated 1080.Dv SYS_RES_IRQ 1081resource whose resource ID corresponds to the table index as described 1082above for 1083.Fn pci_alloc_msix . 1084MSI-X table entries that with a vector of zero will not have an 1085associated 1086.Dv SYS_RES_IRQ 1087resource. 1088Additionally, 1089if any of the original messages allocated by 1090.Fn pci_alloc_msix 1091are not used in the new distribution of messages in the MSI-X table, 1092they will be released automatically. 1093Note that if a driver wishes to use fewer messages than were allocated by 1094.Fn pci_alloc_msix , 1095the driver must use a single, contiguous range of messages beginning 1096with one in the new distribution. 1097The 1098.Fn pci_remap_msix 1099function will fail if this condition is not met. 1100.Ss Device Events 1101The 1102.Va pci_add_device 1103event handler is invoked every time a new PCI device is added to the system. 1104This includes the creation of Virtual Functions via SR-IOV. 1105.Pp 1106The 1107.Va pci_delete_device 1108event handler is invoked every time a PCI device is removed from the system. 1109.Pp 1110Both event handlers pass the 1111.Vt device_t 1112object of the relevant PCI device as 1113.Fa dev 1114to each callback function. 1115Both event handlers are invoked while 1116.Fa dev 1117is unattached but with valid instance variables. 1118.Sh SEE ALSO 1119.Xr pci 4 , 1120.Xr pciconf 8 , 1121.Xr bus_alloc_resource 9 , 1122.Xr bus_dma 9 , 1123.Xr bus_release_resource 9 , 1124.Xr bus_setup_intr 9 , 1125.Xr bus_teardown_intr 9 , 1126.Xr devclass 9 , 1127.Xr device 9 , 1128.Xr driver 9 , 1129.Xr eventhandler 9 , 1130.Xr rman 9 1131.Rs 1132.%B FreeBSD Developers' Handbook 1133.%T NewBus 1134.%U https://docs.freebsd.org/en/books/developers-handbook/ 1135.Re 1136.Rs 1137.%A Shanley 1138.%A Anderson 1139.%B PCI System Architecture 1140.%N 2nd Edition 1141.%I Addison-Wesley 1142.%O ISBN 0-201-30974-2 1143.Re 1144.Sh AUTHORS 1145.An -nosplit 1146This manual page was written by 1147.An Bruce M Simpson Aq Mt bms@FreeBSD.org 1148and 1149.An John Baldwin Aq Mt jhb@FreeBSD.org . 1150.Sh BUGS 1151The kernel PCI code has a number of references to 1152.Dq "slot numbers" . 1153These do not refer to the geographic location of PCI devices, 1154but to the device number assigned by the combination of the PCI IDSEL 1155mechanism and the platform firmware. 1156This should be taken note of when working with the kernel PCI code. 1157.Pp 1158The PCI bus driver should allocate the MSI-X vector table and PBA internally 1159as necessary rather than requiring the caller to do so. 1160