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