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