Documentation/ABI/testing/sysfs-bus-pci

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