Documentation/ABI/testing/sysfs-bus-pci

   1 What:           /sys/bus/pci/drivers/.../bind
   2 What:           /sys/devices/pciX/.../bind
   3 Date:           December 2003
   4 Contact:        linux-pci@vger.kernel.org
   5 Description:
   6                 Writing a device location to this file will cause
   7                 the driver to attempt to bind to the device found at
   8                 this location.  This is useful for overriding default
   9                 bindings.  The format for the location is: DDDD:BB:DD.F.
  10                 That is Domain:Bus:Device.Function and is the same as
  11                 found in /sys/bus/pci/devices/.  For example::
  12
  13                   # echo 0000:00:19.0 > /sys/bus/pci/drivers/foo/bind
  14
  15                 (Note: kernels before 2.6.28 may require echo -n).
  16
  17 What:           /sys/bus/pci/drivers/.../unbind
  18 What:           /sys/devices/pciX/.../unbind
  19 Date:           December 2003
  20 Contact:        linux-pci@vger.kernel.org
  21 Description:
  22                 Writing a device location to this file will cause the
  23                 driver to attempt to unbind from the device found at
  24                 this location.  This may be useful when overriding default
  25                 bindings.  The format for the location is: DDDD:BB:DD.F.
  26                 That is Domain:Bus:Device.Function and is the same as
  27                 found in /sys/bus/pci/devices/. For example::
  28
  29                   # echo 0000:00:19.0 > /sys/bus/pci/drivers/foo/unbind
  30
  31                 (Note: kernels before 2.6.28 may require echo -n).
  32
  33 What:           /sys/bus/pci/drivers/.../new_id
  34 What:           /sys/devices/pciX/.../new_id
  35 Date:           December 2003
  36 Contact:        linux-pci@vger.kernel.org
  37 Description:
  38                 Writing a device ID to this file will attempt to
  39                 dynamically add a new device ID to a PCI device driver.
  40                 This may allow the driver to support more hardware than
  41                 was included in the driver's static device ID support
  42                 table at compile time.  The format for the device ID is:
  43                 VVVV DDDD SVVV SDDD CCCC MMMM PPPP.  That is Vendor ID,
  44                 Device ID, Subsystem Vendor ID, Subsystem Device ID,
  45                 Class, Class Mask, and Private Driver Data.  The Vendor ID
  46                 and Device ID fields are required, the rest are optional.
  47                 Upon successfully adding an ID, the driver will probe
  48                 for the device and attempt to bind to it.  For example::
  49
  50                   # echo "8086 10f5" > /sys/bus/pci/drivers/foo/new_id
  51
  52 What:           /sys/bus/pci/drivers/.../remove_id
  53 What:           /sys/devices/pciX/.../remove_id
  54 Date:           February 2009
  55 Contact:        Chris Wright <chrisw@sous-sol.org>
  56 Description:
  57                 Writing a device ID to this file will remove an ID
  58                 that was dynamically added via the new_id sysfs entry.
  59                 The format for the device ID is:
  60                 VVVV DDDD SVVV SDDD CCCC MMMM.  That is Vendor ID, Device
  61                 ID, Subsystem Vendor ID, Subsystem Device ID, Class,
  62                 and Class Mask.  The Vendor ID and Device ID fields are
  63                 required, the rest are optional.  After successfully
  64                 removing an ID, the driver will no longer support the
  65                 device.  This is useful to ensure auto probing won't
  66                 match the driver to the device.  For example::
  67
  68                   # echo "8086 10f5" > /sys/bus/pci/drivers/foo/remove_id
  69
  70 What:           /sys/bus/pci/rescan
  71 Date:           January 2009
  72 Contact:        Linux PCI developers <linux-pci@vger.kernel.org>
  73 Description:
  74                 Writing a non-zero value to this attribute will
  75                 force a rescan of all PCI buses in the system, and
  76                 re-discover previously removed devices.
  77
  78 What:           /sys/bus/pci/devices/.../msi_bus
  79 Date:           September 2014
  80 Contact:        Linux PCI developers <linux-pci@vger.kernel.org>
  81 Description:
  82                 Writing a zero value to this attribute disallows MSI and
  83                 MSI-X for any future drivers of the device.  If the device
  84                 is a bridge, MSI and MSI-X will be disallowed for future
  85                 drivers of all child devices under the bridge.  Drivers
  86                 must be reloaded for the new setting to take effect.
  87
  88 What:           /sys/bus/pci/devices/.../msi_irqs/
  89 Date:           September, 2011
  90 Contact:        Neil Horman <nhorman@tuxdriver.com>
  91 Description:
  92                 The /sys/devices/.../msi_irqs directory contains a variable set
  93                 of files, with each file being named after a corresponding msi
  94                 irq vector allocated to that device.
  95
  96 What:           /sys/bus/pci/devices/.../msi_irqs/<N>
  97 Date:           September 2011
  98 Contact:        Neil Horman <nhorman@tuxdriver.com>
  99 Description:
 100                 This attribute indicates the mode that the irq vector named by
 101                 the file is in (msi vs. msix)
 102
 103 What:           /sys/bus/pci/devices/.../irq
 104 Date:           August 2021
 105 Contact:        Linux PCI developers <linux-pci@vger.kernel.org>
 106 Description:
 107                 If a driver has enabled MSI (not MSI-X), "irq" contains the
 108                 IRQ of the first MSI vector. Otherwise "irq" contains the
 109                 IRQ of the legacy INTx interrupt.
 110
 111                 "irq" being set to 0 indicates that the device isn't
 112                 capable of generating legacy INTx interrupts.
 113
 114 What:           /sys/bus/pci/devices/.../remove
 115 Date:           January 2009
 116 Contact:        Linux PCI developers <linux-pci@vger.kernel.org>
 117 Description:
 118                 Writing a non-zero value to this attribute will
 119                 hot-remove the PCI device and any of its children.
 120
 121 What:           /sys/bus/pci/devices/.../pci_bus/.../rescan
 122 Date:           May 2011
 123 Contact:        Linux PCI developers <linux-pci@vger.kernel.org>
 124 Description:
 125                 Writing a non-zero value to this attribute will
 126                 force a rescan of the bus and all child buses,
 127                 and re-discover devices removed earlier from this
 128                 part of the device tree.
 129
 130 What:           /sys/bus/pci/devices/.../rescan
 131 Date:           January 2009
 132 Contact:        Linux PCI developers <linux-pci@vger.kernel.org>
 133 Description:
 134                 Writing a non-zero value to this attribute will
 135                 force a rescan of the device's parent bus and all
 136                 child buses, and re-discover devices removed earlier
 137                 from this part of the device tree.
 138
 139 What:           /sys/bus/pci/devices/.../reset_method
 140 Date:           August 2021
 141 Contact:        Amey Narkhede <ameynarkhede03@gmail.com>
 142 Description:
 143                 Some devices allow an individual function to be reset
 144                 without affecting other functions in the same slot.
 145
 146                 For devices that have this support, a file named
 147                 reset_method is present in sysfs.  Reading this file
 148                 gives names of the supported and enabled reset methods and
 149                 their ordering.  Writing a space-separated list of names of
 150                 reset methods sets the reset methods and ordering to be
 151                 used when resetting the device.  Writing an empty string
 152                 disables the ability to reset the device.  Writing
 153                 "default" enables all supported reset methods in the
 154                 default ordering.
 155
 156 What:           /sys/bus/pci/devices/.../reset
 157 Date:           July 2009
 158 Contact:        Michael S. Tsirkin <mst@redhat.com>
 159 Description:
 160                 Some devices allow an individual function to be reset
 161                 without affecting other functions in the same device.
 162                 For devices that have this support, a file named reset
 163                 will be present in sysfs.  Writing 1 to this file
 164                 will perform reset.
 165
 166 What:           /sys/bus/pci/devices/.../vpd
 167 Date:           February 2008
 168 Contact:        Ben Hutchings <bwh@kernel.org>
 169 Description:
 170                 A file named vpd in a device directory will be a
 171                 binary file containing the Vital Product Data for the
 172                 device.  It should follow the VPD format defined in
 173                 PCI Specification 2.1 or 2.2, but users should consider
 174                 that some devices may have incorrectly formatted data.
 175                 If the underlying VPD has a writable section then the
 176                 corresponding section of this file will be writable.
 177
 178 What:           /sys/bus/pci/devices/.../virtfn<N>
 179 Date:           March 2009
 180 Contact:        Yu Zhao <yu.zhao@intel.com>
 181 Description:
 182                 This symbolic link appears when hardware supports the SR-IOV
 183                 capability and the Physical Function driver has enabled it.
 184                 The symbolic link points to the PCI device sysfs entry of the
 185                 Virtual Function whose index is N (0...MaxVFs-1).
 186
 187 What:           /sys/bus/pci/devices/.../dep_link
 188 Date:           March 2009
 189 Contact:        Yu Zhao <yu.zhao@intel.com>
 190 Description:
 191                 This symbolic link appears when hardware supports the SR-IOV
 192                 capability and the Physical Function driver has enabled it,
 193                 and this device has vendor specific dependencies with others.
 194                 The symbolic link points to the PCI device sysfs entry of
 195                 Physical Function this device depends on.
 196
 197 What:           /sys/bus/pci/devices/.../physfn
 198 Date:           March 2009
 199 Contact:        Yu Zhao <yu.zhao@intel.com>
 200 Description:
 201                 This symbolic link appears when a device is a Virtual Function.
 202                 The symbolic link points to the PCI device sysfs entry of the
 203                 Physical Function this device associates with.
 204
 205 What:           /sys/bus/pci/devices/.../modalias
 206 Date:           May 2005
 207 Contact:        Greg Kroah-Hartman <gregkh@linuxfoundation.org>
 208 Description:
 209                 This attribute indicates the PCI ID of the device object.
 210
 211                 That is in the format:
 212                 pci:vXXXXXXXXdXXXXXXXXsvXXXXXXXXsdXXXXXXXXbcXXscXXiXX,
 213                 where:
 214
 215                     - vXXXXXXXX contains the vendor ID;
 216                     - dXXXXXXXX contains the device ID;
 217                     - svXXXXXXXX contains the sub-vendor ID;
 218                     - sdXXXXXXXX contains the subsystem device ID;
 219                     - bcXX contains the device class;
 220                     - scXX contains the device subclass;
 221                     - iXX contains the device class programming interface.
 222
 223 What:           /sys/bus/pci/slots/.../module
 224 Date:           June 2009
 225 Contact:        linux-pci@vger.kernel.org
 226 Description:
 227                 This symbolic link points to the PCI hotplug controller driver
 228                 module that manages the hotplug slot.
 229
 230 What:           /sys/bus/pci/devices/.../label
 231 Date:           July 2010
 232 Contact:        Narendra K <narendra_k@dell.com>, linux-bugs@dell.com
 233 Description:
 234                 Reading this attribute will provide the firmware
 235                 given name (SMBIOS type 41 string or ACPI _DSM string) of
 236                 the PCI device. The attribute will be created only
 237                 if the firmware has given a name to the PCI device.
 238                 ACPI _DSM string name will be given priority if the
 239                 system firmware provides SMBIOS type 41 string also.
 240 Users:
 241                 Userspace applications interested in knowing the
 242                 firmware assigned name of the PCI device.
 243
 244 What:           /sys/bus/pci/devices/.../index
 245 Date:           July 2010
 246 Contact:        Narendra K <narendra_k@dell.com>, linux-bugs@dell.com
 247 Description:
 248                 Reading this attribute will provide the firmware given instance
 249                 number of the PCI device.  Depending on the platform this can
 250                 be for example the SMBIOS type 41 device type instance or the
 251                 user-defined ID (UID) on s390. The attribute will be created
 252                 only if the firmware has given an instance number to the PCI
 253                 device and that number is guaranteed to uniquely identify the
 254                 device in the system.
 255 Users:
 256                 Userspace applications interested in knowing the
 257                 firmware assigned device type instance of the PCI
 258                 device that can help in understanding the firmware
 259                 intended order of the PCI device.
 260
 261 What:           /sys/bus/pci/devices/.../acpi_index
 262 Date:           July 2010
 263 Contact:        Narendra K <narendra_k@dell.com>, linux-bugs@dell.com
 264 Description:
 265                 Reading this attribute will provide the firmware
 266                 given instance (ACPI _DSM instance number) of the PCI device.
 267                 The attribute will be created only if the firmware has given
 268                 an instance number to the PCI device. ACPI _DSM instance number
 269                 will be given priority if the system firmware provides SMBIOS
 270                 type 41 device type instance also.
 271 Users:
 272                 Userspace applications interested in knowing the
 273                 firmware assigned instance number of the PCI
 274                 device that can help in understanding the firmware
 275                 intended order of the PCI device.
 276
 277 What:           /sys/bus/pci/devices/.../d3cold_allowed
 278 Date:           July 2012
 279 Contact:        Huang Ying <ying.huang@intel.com>
 280 Description:
 281                 d3cold_allowed is bit to control whether the corresponding PCI
 282                 device can be put into D3Cold state.  If it is cleared, the
 283                 device will never be put into D3Cold state.  If it is set, the
 284                 device may be put into D3Cold state if other requirements are
 285                 satisfied too.  Reading this attribute will show the current
 286                 value of d3cold_allowed bit.  Writing this attribute will set
 287                 the value of d3cold_allowed bit.
 288
 289 What:           /sys/bus/pci/devices/.../sriov_totalvfs
 290 Date:           November 2012
 291 Contact:        Donald Dutile <ddutile@redhat.com>
 292 Description:
 293                 This file appears when a physical PCIe device supports SR-IOV.
 294                 Userspace applications can read this file to determine the
 295                 maximum number of Virtual Functions (VFs) a PCIe physical
 296                 function (PF) can support. Typically, this is the value reported
 297                 in the PF's SR-IOV extended capability structure's TotalVFs
 298                 element.  Drivers have the ability at probe time to reduce the
 299                 value read from this file via the pci_sriov_set_totalvfs()
 300                 function.
 301
 302 What:           /sys/bus/pci/devices/.../sriov_numvfs
 303 Date:           November 2012
 304 Contact:        Donald Dutile <ddutile@redhat.com>
 305 Description:
 306                 This file appears when a physical PCIe device supports SR-IOV.
 307                 Userspace applications can read and write to this file to
 308                 determine and control the enablement or disablement of Virtual
 309                 Functions (VFs) on the physical function (PF). A read of this
 310                 file will return the number of VFs that are enabled on this PF.
 311                 A number written to this file will enable the specified
 312                 number of VFs. A userspace application would typically read the
 313                 file and check that the value is zero, and then write the number
 314                 of VFs that should be enabled on the PF; the value written
 315                 should be less than or equal to the value in the sriov_totalvfs
 316                 file. A userspace application wanting to disable the VFs would
 317                 write a zero to this file. The core ensures that valid values
 318                 are written to this file, and returns errors when values are not
 319                 valid.  For example, writing a 2 to this file when sriov_numvfs
 320                 is not 0 and not 2 already will return an error. Writing a 10
 321                 when the value of sriov_totalvfs is 8 will return an error.
 322
 323 What:           /sys/bus/pci/devices/.../driver_override
 324 Date:           April 2014
 325 Contact:        Alex Williamson <alex.williamson@redhat.com>
 326 Description:
 327                 This file allows the driver for a device to be specified which
 328                 will override standard static and dynamic ID matching.  When
 329                 specified, only a driver with a name matching the value written
 330                 to driver_override will have an opportunity to bind to the
 331                 device.  The override is specified by writing a string to the
 332                 driver_override file (echo pci-stub > driver_override) and
 333                 may be cleared with an empty string (echo > driver_override).
 334                 This returns the device to standard matching rules binding.
 335                 Writing to driver_override does not automatically unbind the
 336                 device from its current driver or make any attempt to
 337                 automatically load the specified driver.  If no driver with a
 338                 matching name is currently loaded in the kernel, the device
 339                 will not bind to any driver.  This also allows devices to
 340                 opt-out of driver binding using a driver_override name such as
 341                 "none".  Only a single driver may be specified in the override,
 342                 there is no support for parsing delimiters.
 343
 344 What:           /sys/bus/pci/devices/.../numa_node
 345 Date:           Oct 2014
 346 Contact:        Prarit Bhargava <prarit@redhat.com>
 347 Description:
 348                 This file contains the NUMA node to which the PCI device is
 349                 attached, or -1 if the node is unknown.  The initial value
 350                 comes from an ACPI _PXM method or a similar firmware
 351                 source.  If that is missing or incorrect, this file can be
 352                 written to override the node.  In that case, please report
 353                 a firmware bug to the system vendor.  Writing to this file
 354                 taints the kernel with TAINT_FIRMWARE_WORKAROUND, which
 355                 reduces the supportability of your system.
 356
 357 What:           /sys/bus/pci/devices/.../revision
 358 Date:           November 2016
 359 Contact:        Emil Velikov <emil.l.velikov@gmail.com>
 360 Description:
 361                 This file contains the revision field of the PCI device.
 362                 The value comes from device config space. The file is read only.
 363
 364 What:           /sys/bus/pci/devices/.../sriov_drivers_autoprobe
 365 Date:           April 2017
 366 Contact:        Bodong Wang<bodong@mellanox.com>
 367 Description:
 368                 This file is associated with the PF of a device that
 369                 supports SR-IOV.  It determines whether newly-enabled VFs
 370                 are immediately bound to a driver.  It initially contains
 371                 1, which means the kernel automatically binds VFs to a
 372                 compatible driver immediately after they are enabled.  If
 373                 an application writes 0 to the file before enabling VFs,
 374                 the kernel will not bind VFs to a driver.
 375
 376                 A typical use case is to write 0 to this file, then enable
 377                 VFs, then assign the newly-created VFs to virtual machines.
 378                 Note that changing this file does not affect already-
 379                 enabled VFs.  In this scenario, the user must first disable
 380                 the VFs, write 0 to sriov_drivers_autoprobe, then re-enable
 381                 the VFs.
 382
 383                 This is similar to /sys/bus/pci/drivers_autoprobe, but
 384                 affects only the VFs associated with a specific PF.
 385
 386 What:           /sys/bus/pci/devices/.../p2pmem/size
 387 Date:           November 2017
 388 Contact:        Logan Gunthorpe <logang@deltatee.com>
 389 Description:
 390                 If the device has any Peer-to-Peer memory registered, this
 391                 file contains the total amount of memory that the device
 392                 provides (in decimal).
 393
 394 What:           /sys/bus/pci/devices/.../p2pmem/available
 395 Date:           November 2017
 396 Contact:        Logan Gunthorpe <logang@deltatee.com>
 397 Description:
 398                 If the device has any Peer-to-Peer memory registered, this
 399                 file contains the amount of memory that has not been
 400                 allocated (in decimal).
 401
 402 What:           /sys/bus/pci/devices/.../p2pmem/published
 403 Date:           November 2017
 404 Contact:        Logan Gunthorpe <logang@deltatee.com>
 405 Description:
 406                 If the device has any Peer-to-Peer memory registered, this
 407                 file contains a '1' if the memory has been published for
 408                 use outside the driver that owns the device.
 409
 410 What:           /sys/bus/pci/devices/.../p2pmem/allocate
 411 Date:           August 2022
 412 Contact:        Logan Gunthorpe <logang@deltatee.com>
 413 Description:
 414                 This file allows mapping p2pmem into userspace. For each
 415                 mmap() call on this file, the kernel will allocate a chunk
 416                 of Peer-to-Peer memory for use in Peer-to-Peer transactions.
 417                 This memory can be used in O_DIRECT calls to NVMe backed
 418                 files for Peer-to-Peer copies.
 419
 420 What:           /sys/bus/pci/devices/.../link/clkpm
 421                 /sys/bus/pci/devices/.../link/l0s_aspm
 422                 /sys/bus/pci/devices/.../link/l1_aspm
 423                 /sys/bus/pci/devices/.../link/l1_1_aspm
 424                 /sys/bus/pci/devices/.../link/l1_2_aspm
 425                 /sys/bus/pci/devices/.../link/l1_1_pcipm
 426                 /sys/bus/pci/devices/.../link/l1_2_pcipm
 427 Date:           October 2019
 428 Contact:        Heiner Kallweit <hkallweit1@gmail.com>
 429 Description:    If ASPM is supported for an endpoint, these files can be
 430                 used to disable or enable the individual power management
 431                 states. Write y/1/on to enable, n/0/off to disable.
 432
 433 What:           /sys/bus/pci/devices/.../power_state
 434 Date:           November 2020
 435 Contact:        Linux PCI developers <linux-pci@vger.kernel.org>
 436 Description:
 437                 This file contains the current PCI power state of the device.
 438                 The value comes from the PCI kernel device state and can be one
 439                 of: "unknown", "error", "D0", D1", "D2", "D3hot", "D3cold".
 440                 The file is read only.
 441
 442 What:           /sys/bus/pci/devices/.../sriov_vf_total_msix
 443 Date:           January 2021
 444 Contact:        Leon Romanovsky <leonro@nvidia.com>
 445 Description:
 446                 This file is associated with a SR-IOV physical function (PF).
 447                 It contains the total number of MSI-X vectors available for
 448                 assignment to all virtual functions (VFs) associated with PF.
 449                 The value will be zero if the device doesn't support this
 450                 functionality. For supported devices, the value will be
 451                 constant and won't be changed after MSI-X vectors assignment.
 452
 453 What:           /sys/bus/pci/devices/.../sriov_vf_msix_count
 454 Date:           January 2021
 455 Contact:        Leon Romanovsky <leonro@nvidia.com>
 456 Description:
 457                 This file is associated with a SR-IOV virtual function (VF).
 458                 It allows configuration of the number of MSI-X vectors for
 459                 the VF. This allows devices that have a global pool of MSI-X
 460                 vectors to optimally divide them between VFs based on VF usage.
 461
 462                 The values accepted are:
 463                  * > 0 - this number will be reported as the Table Size in the
 464                          VF's MSI-X capability
 465                  * < 0 - not valid
 466                  * = 0 - will reset to the device default value
 467
 468                 The file is writable if the PF is bound to a driver that
 469                 implements ->sriov_set_msix_vec_count().
 470
 471 What:           /sys/bus/pci/devices/.../resourceN_resize
 472 Date:           September 2022
 473 Contact:        Alex Williamson <alex.williamson@redhat.com>
 474 Description:
 475                 These files provide an interface to PCIe Resizable BAR support.
 476                 A file is created for each BAR resource (N) supported by the
 477                 PCIe Resizable BAR extended capability of the device.  Reading
 478                 each file exposes the bitmap of available resource sizes:
 479
 480                 # cat resource1_resize
 481                 00000000000001c0
 482
 483                 The bitmap represents supported resource sizes for the BAR,
 484                 where bit0 = 1MB, bit1 = 2MB, bit2 = 4MB, etc.  In the above
 485                 example the device supports 64MB, 128MB, and 256MB BAR sizes.
 486
 487                 When writing the file, the user provides the bit position of
 488                 the desired resource size, for example:
 489
 490                 # echo 7 > resource1_resize
 491
 492                 This indicates to set the size value corresponding to bit 7,
 493                 128MB.  The resulting size is 2 ^ (bit# + 20).  This definition
 494                 matches the PCIe specification of this capability.
 495
 496                 In order to make use of resource resizing, all PCI drivers must
 497                 be unbound from the device and peer devices under the same
 498                 parent bridge may need to be soft removed.  In the case of
 499                 VGA devices, writing a resize value will remove low level
 500                 console drivers from the device.  Raw users of pci-sysfs
 501                 resourceN attributes must be terminated prior to resizing.
 502                 Success of the resizing operation is not guaranteed.