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