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 24, 2014 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_get_max_read_req , 46.Nm pci_get_powerstate , 47.Nm pci_get_vpd_ident , 48.Nm pci_get_vpd_readonly , 49.Nm pci_iov_attach , 50.Nm pci_iov_detach , 51.Nm pci_msi_count , 52.Nm pci_msix_count , 53.Nm pci_pending_msix , 54.Nm pci_read_config , 55.Nm pci_release_msi , 56.Nm pci_remap_msix , 57.Nm pci_restore_state , 58.Nm pci_save_state , 59.Nm pci_set_max_read_req , 60.Nm pci_set_powerstate , 61.Nm pci_write_config 62.Nd PCI bus interface 63.Sh SYNOPSIS 64.In sys/bus.h 65.In dev/pci/pcireg.h 66.In dev/pci/pcivar.h 67.Ft int 68.Fn pci_alloc_msi "device_t dev" "int *count" 69.Ft int 70.Fn pci_alloc_msix "device_t dev" "int *count" 71.Ft int 72.Fn pci_disable_busmaster "device_t dev" 73.Ft int 74.Fn pci_disable_io "device_t dev" "int space" 75.Ft int 76.Fn pci_enable_busmaster "device_t dev" 77.Ft int 78.Fn pci_enable_io "device_t dev" "int space" 79.Ft device_t 80.Fn pci_find_bsf "uint8_t bus" "uint8_t slot" "uint8_t func" 81.Ft int 82.Fn pci_find_cap "device_t dev" "int capability" "int *capreg" 83.Ft device_t 84.Fn pci_find_dbsf "uint32_t domain" "uint8_t bus" "uint8_t slot" "uint8_t func" 85.Ft device_t 86.Fn pci_find_device "uint16_t vendor" "uint16_t device" 87.Ft int 88.Fn pci_find_extcap "device_t dev" "int capability" "int *capreg" 89.Ft int 90.Fn pci_find_htcap "device_t dev" "int capability" "int *capreg" 91.Ft int 92.Fn pci_get_max_read_req "device_t dev" 93.Ft int 94.Fn pci_get_powerstate "device_t dev" 95.Ft int 96.Fn pci_get_vpd_ident "device_t dev" "const char **identptr" 97.Ft int 98.Fn pci_get_vpd_readonly "device_t dev" "const char *kw" "const char **vptr" 99.Ft int 100.Fn pci_iov_attach "device_t dev" "nvlist_t *pf_schema" "nvlist_t *vf_schema" 101.Ft int 102.Fn pci_iov_detach "device_t dev" 103.Ft int 104.Fn pci_msi_count "device_t dev" 105.Ft int 106.Fn pci_msix_count "device_t dev" 107.Ft int 108.Fn pci_pending_msix "device_t dev" "u_int index" 109.Ft uint32_t 110.Fn pci_read_config "device_t dev" "int reg" "int width" 111.Ft int 112.Fn pci_release_msi "device_t dev" 113.Ft int 114.Fn pci_remap_msix "device_t dev" "int count" "const u_int *vectors" 115.Ft void 116.Fn pci_restore_state "device_t dev" 117.Ft void 118.Fn pci_save_state "device_t dev" 119.Ft int 120.Fn pci_set_max_read_req "device_t dev" "int size" 121.Ft int 122.Fn pci_set_powerstate "device_t dev" "int state" 123.Ft void 124.Fn pci_write_config "device_t dev" "int reg" "uint32_t val" "int width" 125.Sh DESCRIPTION 126The 127.Nm 128set of functions are used for managing PCI devices. 129The functions are split into several groups: 130raw configuration access, 131locating devices, 132device information, 133device configuration, 134and 135message signaled interrupts. 136.Ss Raw Configuration Access 137The 138.Fn pci_read_config 139function is used to read data from the PCI configuration 140space of the device 141.Fa dev , 142at offset 143.Fa reg , 144with 145.Fa width 146specifying the size of the access. 147.Pp 148The 149.Fn pci_write_config 150function is used to write the value 151.Fa val 152to the PCI configuration 153space of the device 154.Fa dev , 155at offset 156.Fa reg , 157with 158.Fa width 159specifying the size of the access. 160.Pp 161.Em NOTE : 162Device drivers should only use these functions for functionality that 163is not available via another 164.Fn pci 165function. 166.Ss Locating Devices 167The 168.Fn pci_find_bsf 169function looks up the 170.Vt device_t 171of a PCI device, given its 172.Fa bus , 173.Fa slot , 174and 175.Fa func . 176The 177.Fa slot 178number actually refers to the number of the device on the bus, 179which does not necessarily indicate its geographic location 180in terms of a physical slot. 181Note that in case the system has multiple PCI domains, 182the 183.Fn pci_find_bsf 184function only searches the first one. 185Actually, it is equivalent to: 186.Bd -literal -offset indent 187pci_find_dbsf(0, bus, slot, func); 188.Ed 189.Pp 190The 191.Fn pci_find_dbsf 192function looks up the 193.Vt device_t 194of a PCI device, given its 195.Fa domain , 196.Fa bus , 197.Fa slot , 198and 199.Fa func . 200The 201.Fa slot 202number actually refers to the number of the device on the bus, 203which does not necessarily indicate its geographic location 204in terms of a physical slot. 205.Pp 206The 207.Fn pci_find_device 208function looks up the 209.Vt device_t 210of a PCI device, given its 211.Fa vendor 212and 213.Fa device 214IDs. 215Note that there can be multiple matches for this search; this function 216only returns the first matching device. 217.Ss Device Information 218The 219.Fn pci_find_cap 220function is used to locate the first instance of a PCI capability 221register set for the device 222.Fa dev . 223The capability to locate is specified by ID via 224.Fa capability . 225Constant macros of the form 226.Dv PCIY_xxx 227for standard capability IDs are defined in 228.In dev/pci/pcireg.h . 229If the capability is found, then 230.Fa *capreg 231is set to the offset in configuration space of the capability register set, 232and 233.Fn pci_find_cap 234returns zero. 235If the capability is not found or the device does not support capabilities, 236.Fn pci_find_cap 237returns an error. 238.Pp 239The 240.Fn pci_find_extcap 241function is used to locate the first instance of a PCI-express 242extended capability register set for the device 243.Fa dev . 244The extended capability to locate is specified by ID via 245.Fa capability . 246Constant macros of the form 247.Dv PCIZ_xxx 248for standard extended capability IDs are defined in 249.In dev/pci/pcireg.h . 250If the extended capability is found, then 251.Fa *capreg 252is set to the offset in configuration space of the extended capability 253register set, and 254.Fn pci_find_extcap 255returns zero. 256If the extended capability is not found or the device is not a 257PCI-express device, 258.Fn pci_find_extcap 259returns an error. 260.Pp 261The 262.Fn pci_find_htcap 263function is used to locate the first instance of a HyperTransport capability 264register set for the device 265.Fa dev . 266The capability to locate is specified by type via 267.Fa capability . 268Constant macros of the form 269.Dv PCIM_HTCAP_xxx 270for standard HyperTransport capability types are defined in 271.In dev/pci/pcireg.h . 272If the capability is found, then 273.Fa *capreg 274is set to the offset in configuration space of the capability register set, 275and 276.Fn pci_find_htcap 277returns zero. 278If the capability is not found or the device is not a HyperTransport device, 279.Fn pci_find_htcap 280returns an error. 281.Pp 282The 283.Fn pci_get_vpd_ident 284function is used to fetch a device's Vital Product Data 285.Pq VPD 286identifier string. 287If the device 288.Fa dev 289supports VPD and provides an identifier string, 290then 291.Fa *identptr 292is set to point at a read-only, null-terminated copy of the identifier 293string, 294and 295.Fn pci_get_vpd_ident 296returns zero. 297If the device does not support VPD or does not provide an identifier 298string, 299then 300.Fn pci_get_vpd_ident 301returns an error. 302.Pp 303The 304.Fn pci_get_vpd_readonly 305function is used to fetch the value of a single VPD read-only keyword 306for the device 307.Fa dev . 308The keyword to fetch is identified by the two character string 309.Fa kw . 310If the device supports VPD and provides a read-only value for the 311requested keyword, 312then 313.Fa *vptr 314is set to point at a read-only, null-terminated copy of the value, 315and 316.Fn pci_get_vpd_readonly 317returns zero. 318If the device does not support VPD or does not provide the requested 319keyword, 320then 321.Fn pci_get_vpd_readonly 322returns an error. 323.Ss Device Configuration 324The 325.Fn pci_enable_busmaster 326function enables PCI bus mastering for the device 327.Fa dev , 328by setting the 329.Dv PCIM_CMD_BUSMASTEREN 330bit in the 331.Dv PCIR_COMMAND 332register. 333The 334.Fn pci_disable_busmaster 335function clears this bit. 336.Pp 337The 338.Fn pci_enable_io 339function enables memory or I/O port address decoding for the device 340.Fa dev , 341by setting the 342.Dv PCIM_CMD_MEMEN 343or 344.Dv PCIM_CMD_PORTEN 345bit in the 346.Dv PCIR_COMMAND 347register appropriately. 348The 349.Fn pci_disable_io 350function clears the appropriate bit. 351The 352.Fa space 353argument specifies which resource is affected; this can be either 354.Dv SYS_RES_MEMORY 355or 356.Dv SYS_RES_IOPORT 357as appropriate. 358Device drivers should generally not use these routines directly. 359The PCI bus will enable decoding automatically when a 360.Dv SYS_RES_MEMORY 361or 362.Dv SYS_RES_IOPORT 363resource is activated via 364.Xr bus_alloc_resource 9 365or 366.Xr bus_activate_resource 9 . 367.Pp 368The 369.Fn pci_get_max_read_req 370function returns the current maximum read request size in bytes for a 371PCI-express device. 372If the 373.Fa dev 374device is not a PCI-express device, 375.Fn pci_get_max_read_req 376returns zero. 377.Pp 378The 379.Fn pci_set_max_read_req 380sets the PCI-express maximum read request size for 381.Fa dev . 382The requested 383.Fa size 384may be adjusted, 385and 386.Fn pci_set_max_read_req 387returns the actual size set in bytes. 388If the 389.Fa dev 390device is not a PCI-express device, 391.Fn pci_set_max_read_req 392returns zero. 393.Pp 394The 395.Fn pci_get_powerstate 396function returns the current power state of the device 397.Fa dev . 398If the device does not support power management capabilities, then the default 399state of 400.Dv PCI_POWERSTATE_D0 401is returned. 402The following power states are defined by PCI: 403.Bl -hang -width ".Dv PCI_POWERSTATE_UNKNOWN" 404.It Dv PCI_POWERSTATE_D0 405State in which device is on and running. 406It is receiving full power from the system and delivering 407full functionality to the user. 408.It Dv PCI_POWERSTATE_D1 409Class-specific low-power state in which device context may or 410may not be lost. 411Busses in this state cannot do anything to the bus, to 412force devices to lose context. 413.It Dv PCI_POWERSTATE_D2 414Class-specific low-power state in which device context may or 415may not be lost. 416Attains greater power savings than 417.Dv PCI_POWERSTATE_D1 . 418Busses in this state can cause devices to lose some context. 419Devices 420.Em must 421be prepared for the bus to be in this state or higher. 422.It Dv PCI_POWERSTATE_D3 423State in which the device is off and not running. 424Device context is lost, and power from the device can 425be removed. 426.It Dv PCI_POWERSTATE_UNKNOWN 427State of the device is unknown. 428.El 429.Pp 430The 431.Fn pci_set_powerstate 432function is used to transition the device 433.Fa dev 434to the PCI power state 435.Fa state . 436If the device does not support power management capabilities or 437it does not support the specific power state 438.Fa state , 439then the function will fail with 440.Er EOPNOTSUPP . 441.Pp 442The 443.Fn pci_iov_attach 444function is used to advertise that the given device 445.Pq and associated device driver 446supports PCI Single-Root I/O Virtualization 447.Po SR-IOV Pc . 448A driver that supports SR-IOV must implement the 449.Xr PCI_INIT_IOV 9 , 450.Xr PCI_ADD_VF 9 451and 452.Xr PCI_UNIT_IOV 9 453methods. 454This function should be called during the 455.Xr DEVICE_ATTACH 9 456method. 457If this function returns an error, it is recommended that the device driver 458still successfully attaches, but runs with SR-IOV disabled. 459The 460.Fa pf_schema 461and 462.Fa vf_schema 463parameters are used to define what device-specific configuration parameters the 464device driver accepts when SR-IOV is enabled for the Physical Function 465.Pq PF 466and for individual Virtual Functions 467.Pq VFs 468respectively. 469See 470.Xr pci_iov_schema 9 471for details on how to construct the schema. 472If either the 473.Pa pf_schema 474or 475.Pa vf_schema 476is invalid or specifies parameter names that conflict with parameter names that 477are already in use, 478.Fn pci_iov_attach 479will return an error and SR-IOV will not be available on the PF device. 480If a driver does not accept configuration parameters for either the PF device 481or the VF devices, the driver must pass an empty schema for that device. 482The SR-IOV infrastructure takes ownership of the 483.Fa pf_schema 484and 485.Fa vf_schema 486and is responsible for freeing them. 487The driver must never free the schemas itself. 488.Pp 489The 490.Fn pci_iov_detach 491function is used to advise the SR-IOV infrastructure that the driver for the 492given device is attempting to detach and that all SR-IOV resources for the 493device must be released. 494This function must be called during the 495.Xr DEVICE_DETACH 9 496method if 497.Fn pci_iov_attach 498was successfully called on the device and 499.Fn pci_iov_detach 500has not subsequently been called on the device and returned no error. 501If this function returns an error, the 502.Xr DEVICE_DETACH 9 503method must fail and return an error, as detaching the PF driver while VF 504devices are active would cause system instability. 505This function is safe to call and will always succeed if 506.Fn pci_iov_attach 507previously failed with an error on the given device, or if 508.Fn pci_iov_attach 509was never called on the device. 510.Pp 511The 512.Fn pci_save_state 513and 514.Fn pci_restore_state 515functions can be used by a device driver to save and restore standard PCI 516config registers. 517The 518.Fn pci_save_state 519function must be invoked while the device has valid state before 520.Fn pci_restore_state 521can be used. 522If the device is not in the fully-powered state 523.Pq Dv PCI_POWERSTATE_D0 524when 525.Fn pci_restore_state 526is invoked, 527then the device will be transitioned to 528.Dv PCI_POWERSTATE_D0 529before any config registers are restored. 530.Ss Message Signaled Interrupts 531Message Signaled Interrupts 532.Pq MSI 533and 534Enhanced Message Signaled Interrupts 535.Pq MSI-X 536are PCI capabilities that provide an alternate method for PCI 537devices to signal interrupts. 538The legacy INTx interrupt is available to PCI devices as a 539.Dv SYS_RES_IRQ 540resource with a resource ID of zero. 541MSI and MSI-X interrupts are available to PCI devices as one or more 542.Dv SYS_RES_IRQ 543resources with resource IDs greater than zero. 544A driver must ask the PCI bus to allocate MSI or MSI-X interrupts 545using 546.Fn pci_alloc_msi 547or 548.Fn pci_alloc_msix 549before it can use MSI or MSI-X 550.Dv SYS_RES_IRQ 551resources. 552A driver is not allowed to use the legacy INTx 553.Dv SYS_RES_IRQ 554resource if MSI or MSI-X interrupts have been allocated, 555and attempts to allocate MSI or MSI-X interrupts will fail if the 556driver is currently using the legacy INTx 557.Dv SYS_RES_IRQ 558resource. 559A driver is only allowed to use either MSI or MSI-X, 560but not both. 561.Pp 562The 563.Fn pci_msi_count 564function returns the maximum number of MSI messages supported by the 565device 566.Fa dev . 567If the device does not support MSI, 568then 569.Fn pci_msi_count 570returns zero. 571.Pp 572The 573.Fn pci_alloc_msi 574function attempts to allocate 575.Fa *count 576MSI messages for the device 577.Fa dev . 578The 579.Fn pci_alloc_msi 580function may allocate fewer messages than requested for various 581reasons including requests for more messages than the device 582.Fa dev 583supports, 584or if the system has a shortage of available MSI messages. 585On success, 586.Fa *count 587is set to the number of messages allocated and 588.Fn pci_alloc_msi 589returns zero. 590The 591.Dv SYS_RES_IRQ 592resources for the allocated messages will be available at consecutive 593resource IDs beginning with one. 594If 595.Fn pci_alloc_msi 596is not able to allocate any messages, 597it returns an error. 598Note that MSI only supports message counts that are powers of two; 599requests to allocate a non-power of two count of messages will fail. 600.Pp 601The 602.Fn pci_release_msi 603function is used to release any allocated MSI or MSI-X messages back 604to the system. 605If any MSI or MSI-X 606.Dv SYS_RES_IRQ 607resources are allocated by the driver or have a configured interrupt 608handler, 609this function will fail with 610.Er EBUSY . 611The 612.Fn pci_release_msi 613function returns zero on success and an error on failure. 614.Pp 615The 616.Fn pci_msix_count 617function returns the maximum number of MSI-X messages supported by the 618device 619.Fa dev . 620If the device does not support MSI-X, 621then 622.Fn pci_msix_count 623returns zero. 624.Pp 625The 626.Fn pci_alloc_msix 627function attempts to allocate 628.Fa *count 629MSI-X messages for the device 630.Fa dev . 631The 632.Fn pci_alloc_msix 633function may allocate fewer messages than requested for various 634reasons including requests for more messages than the device 635.Fa dev 636supports, 637or if the system has a shortage of available MSI-X messages. 638On success, 639.Fa *count 640is set to the number of messages allocated and 641.Fn pci_alloc_msix 642returns zero. 643For MSI-X messages, 644the resource ID for each 645.Dv SYS_RES_IRQ 646resource identifies the index in the MSI-X table of the 647corresponding message. 648A resource ID of one maps to the first index of the MSI-X table; 649a resource ID two identifies the second index in the table, etc. 650The 651.Fn pci_alloc_msix 652function assigns the 653.Fa *count 654messages allocated to the first 655.Fa *count 656table indicies. 657If 658.Fn pci_alloc_msix 659is not able to allocate any messages, 660it returns an error. 661Unlike MSI, 662MSI-X does not require message counts that are powers of two. 663.Pp 664The 665.Fn pci_pending_msix 666function examines the 667.Fa dev 668device's Pending Bit Array 669.Pq PBA 670to determine the pending status of the MSI-X message at table index 671.Fa index . 672If the indicated message is pending, 673this function returns a non-zero value; 674otherwise, 675it returns zero. 676Passing an invalid 677.Fa index 678to this function will result in undefined behavior. 679.Pp 680As mentioned in the description of 681.Fn pci_alloc_msix , 682MSI-X messages are initially assigned to the first N table entries. 683A driver may use a different distribution of available messages to 684table entries via the 685.Fn pci_remap_msix 686function. 687Note that this function must be called after a successful call to 688.Fn pci_alloc_msix 689but before any of the 690.Dv SYS_RES_IRQ 691resources are allocated. 692The 693.Fn pci_remap_msix 694function returns zero on success, 695or an error on failure. 696.Pp 697The 698.Fa vectors 699array should contain 700.Fa count 701message vectors. 702The array maps directly to the MSI-X table in that the first entry in 703the array specifies the message used for the first entry in the MSI-X 704table, 705the second entry in the array corresponds to the second entry in the 706MSI-X table, 707etc. 708The vector value in each array index can either be zero to indicate 709that no message should be assigned to the corresponding MSI-X table entry, 710or it can be a number from one to N 711.Po 712where N is the count returned from the previous call to 713.Fn pci_alloc_msix 714.Pc 715to indicate which of the allocated messages should be assigned to the 716corresponding MSI-X table entry. 717.Pp 718If 719.Fn pci_remap_msix 720succeeds, 721each MSI-X table entry with a non-zero vector will have an associated 722.Dv SYS_RES_IRQ 723resource whose resource ID corresponds to the table index as described 724above for 725.Fn pci_alloc_msix . 726MSI-X table entries that with a vector of zero will not have an 727associated 728.Dv SYS_RES_IRQ 729resource. 730Additionally, 731if any of the original messages allocated by 732.Fn pci_alloc_msix 733are not used in the new distribution of messages in the MSI-X table, 734they will be released automatically. 735Note that if a driver wishes to use fewer messages than were allocated by 736.Fn pci_alloc_msix , 737the driver must use a single, contiguous range of messages beginning 738with one in the new distribution. 739The 740.Fn pci_remap_msix 741function will fail if this condition is not met. 742.Sh IMPLEMENTATION NOTES 743The 744.Vt pci_addr_t 745type varies according to the size of the PCI bus address 746space on the target architecture. 747.Sh SEE ALSO 748.Xr pci 4 , 749.Xr pciconf 8 , 750.Xr bus_alloc_resource 9 , 751.Xr bus_dma 9 , 752.Xr bus_release_resource 9 , 753.Xr bus_setup_intr 9 , 754.Xr bus_teardown_intr 9 , 755.Xr devclass 9 , 756.Xr device 9 , 757.Xr driver 9 , 758.Xr rman 9 759.Rs 760.%B FreeBSD Developers' Handbook 761.%T NewBus 762.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/ 763.Re 764.Rs 765.%A Shanley 766.%A Anderson 767.%B PCI System Architecture 768.%N 2nd Edition 769.%I Addison-Wesley 770.%O ISBN 0-201-30974-2 771.Re 772.Sh AUTHORS 773.An -nosplit 774This manual page was written by 775.An Bruce M Simpson Aq Mt bms@FreeBSD.org 776and 777.An John Baldwin Aq Mt jhb@FreeBSD.org . 778.Sh BUGS 779The kernel PCI code has a number of references to 780.Dq "slot numbers" . 781These do not refer to the geographic location of PCI devices, 782but to the device number assigned by the combination of the PCI IDSEL 783mechanism and the platform firmware. 784This should be taken note of when working with the kernel PCI code. 785