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
 125 Date:           July 2009
 126 Contact:        Michael S. Tsirkin <mst@redhat.com>
 127 Description:
 128                 Some devices allow an individual function to be reset
 129                 without affecting other functions in the same device.
 130                 For devices that have this support, a file named reset
 131                 will be present in sysfs.  Writing 1 to this file
 132                 will perform reset.
 133
 134 What:           /sys/bus/pci/devices/.../vpd
 135 Date:           February 2008
 136 Contact:        Ben Hutchings <bwh@kernel.org>
 137 Description:
 138                 A file named vpd in a device directory will be a
 139                 binary file containing the Vital Product Data for the
 140                 device.  It should follow the VPD format defined in
 141                 PCI Specification 2.1 or 2.2, but users should consider
 142                 that some devices may have incorrectly formatted data.
 143                 If the underlying VPD has a writable section then the
 144                 corresponding section of this file will be writable.
 145
 146 What:           /sys/bus/pci/devices/.../virtfnN
 147 Date:           March 2009
 148 Contact:        Yu Zhao <yu.zhao@intel.com>
 149 Description:
 150                 This symbolic link appears when hardware supports the SR-IOV
 151                 capability and the Physical Function driver has enabled it.
 152                 The symbolic link points to the PCI device sysfs entry of the
 153                 Virtual Function whose index is N (0...MaxVFs-1).
 154
 155 What:           /sys/bus/pci/devices/.../dep_link
 156 Date:           March 2009
 157 Contact:        Yu Zhao <yu.zhao@intel.com>
 158 Description:
 159                 This symbolic link appears when hardware supports the SR-IOV
 160                 capability and the Physical Function driver has enabled it,
 161                 and this device has vendor specific dependencies with others.
 162                 The symbolic link points to the PCI device sysfs entry of
 163                 Physical Function this device depends on.
 164
 165 What:           /sys/bus/pci/devices/.../physfn
 166 Date:           March 2009
 167 Contact:        Yu Zhao <yu.zhao@intel.com>
 168 Description:
 169                 This symbolic link appears when a device is a Virtual Function.
 170                 The symbolic link points to the PCI device sysfs entry of the
 171                 Physical Function this device associates with.
 172
 173 What:           /sys/bus/pci/slots/.../module
 174 Date:           June 2009
 175 Contact:        linux-pci@vger.kernel.org
 176 Description:
 177                 This symbolic link points to the PCI hotplug controller driver
 178                 module that manages the hotplug slot.
 179
 180 What:           /sys/bus/pci/devices/.../label
 181 Date:           July 2010
 182 Contact:        Narendra K <narendra_k@dell.com>, linux-bugs@dell.com
 183 Description:
 184                 Reading this attribute will provide the firmware
 185                 given name (SMBIOS type 41 string or ACPI _DSM string) of
 186                 the PCI device. The attribute will be created only
 187                 if the firmware has given a name to the PCI device.
 188                 ACPI _DSM string name will be given priority if the
 189                 system firmware provides SMBIOS type 41 string also.
 190 Users:
 191                 Userspace applications interested in knowing the
 192                 firmware assigned name of the PCI device.
 193
 194 What:           /sys/bus/pci/devices/.../index
 195 Date:           July 2010
 196 Contact:        Narendra K <narendra_k@dell.com>, linux-bugs@dell.com
 197 Description:
 198                 Reading this attribute will provide the firmware given instance
 199                 number of the PCI device.  Depending on the platform this can
 200                 be for example the SMBIOS type 41 device type instance or the
 201                 user-defined ID (UID) on s390. The attribute will be created
 202                 only if the firmware has given an instance number to the PCI
 203                 device and that number is guaranteed to uniquely identify the
 204                 device in the system.
 205 Users:
 206                 Userspace applications interested in knowing the
 207                 firmware assigned device type instance of the PCI
 208                 device that can help in understanding the firmware
 209                 intended order of the PCI device.
 210
 211 What:           /sys/bus/pci/devices/.../acpi_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
 216                 given instance (ACPI _DSM instance number) of the PCI device.
 217                 The attribute will be created only if the firmware has given
 218                 an instance number to the PCI device. ACPI _DSM instance number
 219                 will be given priority if the system firmware provides SMBIOS
 220                 type 41 device type instance also.
 221 Users:
 222                 Userspace applications interested in knowing the
 223                 firmware assigned instance number of the PCI
 224                 device that can help in understanding the firmware
 225                 intended order of the PCI device.
 226
 227 What:           /sys/bus/pci/devices/.../d3cold_allowed
 228 Date:           July 2012
 229 Contact:        Huang Ying <ying.huang@intel.com>
 230 Description:
 231                 d3cold_allowed is bit to control whether the corresponding PCI
 232                 device can be put into D3Cold state.  If it is cleared, the
 233                 device will never be put into D3Cold state.  If it is set, the
 234                 device may be put into D3Cold state if other requirements are
 235                 satisfied too.  Reading this attribute will show the current
 236                 value of d3cold_allowed bit.  Writing this attribute will set
 237                 the value of d3cold_allowed bit.
 238
 239 What:           /sys/bus/pci/devices/.../sriov_totalvfs
 240 Date:           November 2012
 241 Contact:        Donald Dutile <ddutile@redhat.com>
 242 Description:
 243                 This file appears when a physical PCIe device supports SR-IOV.
 244                 Userspace applications can read this file to determine the
 245                 maximum number of Virtual Functions (VFs) a PCIe physical
 246                 function (PF) can support. Typically, this is the value reported
 247                 in the PF's SR-IOV extended capability structure's TotalVFs
 248                 element.  Drivers have the ability at probe time to reduce the
 249                 value read from this file via the pci_sriov_set_totalvfs()
 250                 function.
 251
 252 What:           /sys/bus/pci/devices/.../sriov_numvfs
 253 Date:           November 2012
 254 Contact:        Donald Dutile <ddutile@redhat.com>
 255 Description:
 256                 This file appears when a physical PCIe device supports SR-IOV.
 257                 Userspace applications can read and write to this file to
 258                 determine and control the enablement or disablement of Virtual
 259                 Functions (VFs) on the physical function (PF). A read of this
 260                 file will return the number of VFs that are enabled on this PF.
 261                 A number written to this file will enable the specified
 262                 number of VFs. A userspace application would typically read the
 263                 file and check that the value is zero, and then write the number
 264                 of VFs that should be enabled on the PF; the value written
 265                 should be less than or equal to the value in the sriov_totalvfs
 266                 file. A userspace application wanting to disable the VFs would
 267                 write a zero to this file. The core ensures that valid values
 268                 are written to this file, and returns errors when values are not
 269                 valid.  For example, writing a 2 to this file when sriov_numvfs
 270                 is not 0 and not 2 already will return an error. Writing a 10
 271                 when the value of sriov_totalvfs is 8 will return an error.
 272
 273 What:           /sys/bus/pci/devices/.../driver_override
 274 Date:           April 2014
 275 Contact:        Alex Williamson <alex.williamson@redhat.com>
 276 Description:
 277                 This file allows the driver for a device to be specified which
 278                 will override standard static and dynamic ID matching.  When
 279                 specified, only a driver with a name matching the value written
 280                 to driver_override will have an opportunity to bind to the
 281                 device.  The override is specified by writing a string to the
 282                 driver_override file (echo pci-stub > driver_override) and
 283                 may be cleared with an empty string (echo > driver_override).
 284                 This returns the device to standard matching rules binding.
 285                 Writing to driver_override does not automatically unbind the
 286                 device from its current driver or make any attempt to
 287                 automatically load the specified driver.  If no driver with a
 288                 matching name is currently loaded in the kernel, the device
 289                 will not bind to any driver.  This also allows devices to
 290                 opt-out of driver binding using a driver_override name such as
 291                 "none".  Only a single driver may be specified in the override,
 292                 there is no support for parsing delimiters.
 293
 294 What:           /sys/bus/pci/devices/.../numa_node
 295 Date:           Oct 2014
 296 Contact:        Prarit Bhargava <prarit@redhat.com>
 297 Description:
 298                 This file contains the NUMA node to which the PCI device is
 299                 attached, or -1 if the node is unknown.  The initial value
 300                 comes from an ACPI _PXM method or a similar firmware
 301                 source.  If that is missing or incorrect, this file can be
 302                 written to override the node.  In that case, please report
 303                 a firmware bug to the system vendor.  Writing to this file
 304                 taints the kernel with TAINT_FIRMWARE_WORKAROUND, which
 305                 reduces the supportability of your system.
 306
 307 What:           /sys/bus/pci/devices/.../revision
 308 Date:           November 2016
 309 Contact:        Emil Velikov <emil.l.velikov@gmail.com>
 310 Description:
 311                 This file contains the revision field of the PCI device.
 312                 The value comes from device config space. The file is read only.
 313
 314 What:           /sys/bus/pci/devices/.../sriov_drivers_autoprobe
 315 Date:           April 2017
 316 Contact:        Bodong Wang<bodong@mellanox.com>
 317 Description:
 318                 This file is associated with the PF of a device that
 319                 supports SR-IOV.  It determines whether newly-enabled VFs
 320                 are immediately bound to a driver.  It initially contains
 321                 1, which means the kernel automatically binds VFs to a
 322                 compatible driver immediately after they are enabled.  If
 323                 an application writes 0 to the file before enabling VFs,
 324                 the kernel will not bind VFs to a driver.
 325
 326                 A typical use case is to write 0 to this file, then enable
 327                 VFs, then assign the newly-created VFs to virtual machines.
 328                 Note that changing this file does not affect already-
 329                 enabled VFs.  In this scenario, the user must first disable
 330                 the VFs, write 0 to sriov_drivers_autoprobe, then re-enable
 331                 the VFs.
 332
 333                 This is similar to /sys/bus/pci/drivers_autoprobe, but
 334                 affects only the VFs associated with a specific PF.
 335
 336 What:           /sys/bus/pci/devices/.../p2pmem/size
 337 Date:           November 2017
 338 Contact:        Logan Gunthorpe <logang@deltatee.com>
 339 Description:
 340                 If the device has any Peer-to-Peer memory registered, this
 341                 file contains the total amount of memory that the device
 342                 provides (in decimal).
 343
 344 What:           /sys/bus/pci/devices/.../p2pmem/available
 345 Date:           November 2017
 346 Contact:        Logan Gunthorpe <logang@deltatee.com>
 347 Description:
 348                 If the device has any Peer-to-Peer memory registered, this
 349                 file contains the amount of memory that has not been
 350                 allocated (in decimal).
 351
 352 What:           /sys/bus/pci/devices/.../p2pmem/published
 353 Date:           November 2017
 354 Contact:        Logan Gunthorpe <logang@deltatee.com>
 355 Description:
 356                 If the device has any Peer-to-Peer memory registered, this
 357                 file contains a '1' if the memory has been published for
 358                 use outside the driver that owns the device.
 359
 360 What:           /sys/bus/pci/devices/.../link/clkpm
 361                 /sys/bus/pci/devices/.../link/l0s_aspm
 362                 /sys/bus/pci/devices/.../link/l1_aspm
 363                 /sys/bus/pci/devices/.../link/l1_1_aspm
 364                 /sys/bus/pci/devices/.../link/l1_2_aspm
 365                 /sys/bus/pci/devices/.../link/l1_1_pcipm
 366                 /sys/bus/pci/devices/.../link/l1_2_pcipm
 367 Date:           October 2019
 368 Contact:        Heiner Kallweit <hkallweit1@gmail.com>
 369 Description:    If ASPM is supported for an endpoint, these files can be
 370                 used to disable or enable the individual power management
 371                 states. Write y/1/on to enable, n/0/off to disable.
 372
 373 What:           /sys/bus/pci/devices/.../power_state
 374 Date:           November 2020
 375 Contact:        Linux PCI developers <linux-pci@vger.kernel.org>
 376 Description:
 377                 This file contains the current PCI power state of the device.
 378                 The value comes from the PCI kernel device state and can be one
 379                 of: "unknown", "error", "D0", D1", "D2", "D3hot", "D3cold".
 380                 The file is read only.
 381
 382 What:           /sys/bus/pci/devices/.../sriov_vf_total_msix
 383 Date:           January 2021
 384 Contact:        Leon Romanovsky <leonro@nvidia.com>
 385 Description:
 386                 This file is associated with a SR-IOV physical function (PF).
 387                 It contains the total number of MSI-X vectors available for
 388                 assignment to all virtual functions (VFs) associated with PF.
 389                 The value will be zero if the device doesn't support this
 390                 functionality. For supported devices, the value will be
 391                 constant and won't be changed after MSI-X vectors assignment.
 392
 393 What:           /sys/bus/pci/devices/.../sriov_vf_msix_count
 394 Date:           January 2021
 395 Contact:        Leon Romanovsky <leonro@nvidia.com>
 396 Description:
 397                 This file is associated with a SR-IOV virtual function (VF).
 398                 It allows configuration of the number of MSI-X vectors for
 399                 the VF. This allows devices that have a global pool of MSI-X
 400                 vectors to optimally divide them between VFs based on VF usage.
 401
 402                 The values accepted are:
 403                  * > 0 - this number will be reported as the Table Size in the
 404                          VF's MSI-X capability
 405                  * < 0 - not valid
 406                  * = 0 - will reset to the device default value
 407
 408                 The file is writable if the PF is bound to a driver that
 409                 implements ->sriov_set_msix_vec_count().