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 malformatted data.  If the
 143                 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
 199                 given instance (SMBIOS type 41 device type instance) of the
 200                 PCI device. The attribute will be created only if the firmware
 201                 has given an instance number to the PCI device.
 202 Users:
 203                 Userspace applications interested in knowing the
 204                 firmware assigned device type instance of the PCI
 205                 device that can help in understanding the firmware
 206                 intended order of the PCI device.
 207
 208 What:           /sys/bus/pci/devices/.../acpi_index
 209 Date:           July 2010
 210 Contact:        Narendra K <narendra_k@dell.com>, linux-bugs@dell.com
 211 Description:
 212                 Reading this attribute will provide the firmware
 213                 given instance (ACPI _DSM instance number) of the PCI device.
 214                 The attribute will be created only if the firmware has given
 215                 an instance number to the PCI device. ACPI _DSM instance number
 216                 will be given priority if the system firmware provides SMBIOS
 217                 type 41 device type instance also.
 218 Users:
 219                 Userspace applications interested in knowing the
 220                 firmware assigned instance number of the PCI
 221                 device that can help in understanding the firmware
 222                 intended order of the PCI device.
 223
 224 What:           /sys/bus/pci/devices/.../d3cold_allowed
 225 Date:           July 2012
 226 Contact:        Huang Ying <ying.huang@intel.com>
 227 Description:
 228                 d3cold_allowed is bit to control whether the corresponding PCI
 229                 device can be put into D3Cold state.  If it is cleared, the
 230                 device will never be put into D3Cold state.  If it is set, the
 231                 device may be put into D3Cold state if other requirements are
 232                 satisfied too.  Reading this attribute will show the current
 233                 value of d3cold_allowed bit.  Writing this attribute will set
 234                 the value of d3cold_allowed bit.
 235
 236 What:           /sys/bus/pci/devices/.../sriov_totalvfs
 237 Date:           November 2012
 238 Contact:        Donald Dutile <ddutile@redhat.com>
 239 Description:
 240                 This file appears when a physical PCIe device supports SR-IOV.
 241                 Userspace applications can read this file to determine the
 242                 maximum number of Virtual Functions (VFs) a PCIe physical
 243                 function (PF) can support. Typically, this is the value reported
 244                 in the PF's SR-IOV extended capability structure's TotalVFs
 245                 element.  Drivers have the ability at probe time to reduce the
 246                 value read from this file via the pci_sriov_set_totalvfs()
 247                 function.
 248
 249 What:           /sys/bus/pci/devices/.../sriov_numvfs
 250 Date:           November 2012
 251 Contact:        Donald Dutile <ddutile@redhat.com>
 252 Description:
 253                 This file appears when a physical PCIe device supports SR-IOV.
 254                 Userspace applications can read and write to this file to
 255                 determine and control the enablement or disablement of Virtual
 256                 Functions (VFs) on the physical function (PF). A read of this
 257                 file will return the number of VFs that are enabled on this PF.
 258                 A number written to this file will enable the specified
 259                 number of VFs. A userspace application would typically read the
 260                 file and check that the value is zero, and then write the number
 261                 of VFs that should be enabled on the PF; the value written
 262                 should be less than or equal to the value in the sriov_totalvfs
 263                 file. A userspace application wanting to disable the VFs would
 264                 write a zero to this file. The core ensures that valid values
 265                 are written to this file, and returns errors when values are not
 266                 valid.  For example, writing a 2 to this file when sriov_numvfs
 267                 is not 0 and not 2 already will return an error. Writing a 10
 268                 when the value of sriov_totalvfs is 8 will return an error.
 269
 270 What:           /sys/bus/pci/devices/.../driver_override
 271 Date:           April 2014
 272 Contact:        Alex Williamson <alex.williamson@redhat.com>
 273 Description:
 274                 This file allows the driver for a device to be specified which
 275                 will override standard static and dynamic ID matching.  When
 276                 specified, only a driver with a name matching the value written
 277                 to driver_override will have an opportunity to bind to the
 278                 device.  The override is specified by writing a string to the
 279                 driver_override file (echo pci-stub > driver_override) and
 280                 may be cleared with an empty string (echo > driver_override).
 281                 This returns the device to standard matching rules binding.
 282                 Writing to driver_override does not automatically unbind the
 283                 device from its current driver or make any attempt to
 284                 automatically load the specified driver.  If no driver with a
 285                 matching name is currently loaded in the kernel, the device
 286                 will not bind to any driver.  This also allows devices to
 287                 opt-out of driver binding using a driver_override name such as
 288                 "none".  Only a single driver may be specified in the override,
 289                 there is no support for parsing delimiters.
 290
 291 What:           /sys/bus/pci/devices/.../numa_node
 292 Date:           Oct 2014
 293 Contact:        Prarit Bhargava <prarit@redhat.com>
 294 Description:
 295                 This file contains the NUMA node to which the PCI device is
 296                 attached, or -1 if the node is unknown.  The initial value
 297                 comes from an ACPI _PXM method or a similar firmware
 298                 source.  If that is missing or incorrect, this file can be
 299                 written to override the node.  In that case, please report
 300                 a firmware bug to the system vendor.  Writing to this file
 301                 taints the kernel with TAINT_FIRMWARE_WORKAROUND, which
 302                 reduces the supportability of your system.
 303
 304 What:           /sys/bus/pci/devices/.../revision
 305 Date:           November 2016
 306 Contact:        Emil Velikov <emil.l.velikov@gmail.com>
 307 Description:
 308                 This file contains the revision field of the PCI device.
 309                 The value comes from device config space. The file is read only.
 310
 311 What:           /sys/bus/pci/devices/.../sriov_drivers_autoprobe
 312 Date:           April 2017
 313 Contact:        Bodong Wang<bodong@mellanox.com>
 314 Description:
 315                 This file is associated with the PF of a device that
 316                 supports SR-IOV.  It determines whether newly-enabled VFs
 317                 are immediately bound to a driver.  It initially contains
 318                 1, which means the kernel automatically binds VFs to a
 319                 compatible driver immediately after they are enabled.  If
 320                 an application writes 0 to the file before enabling VFs,
 321                 the kernel will not bind VFs to a driver.
 322
 323                 A typical use case is to write 0 to this file, then enable
 324                 VFs, then assign the newly-created VFs to virtual machines.
 325                 Note that changing this file does not affect already-
 326                 enabled VFs.  In this scenario, the user must first disable
 327                 the VFs, write 0 to sriov_drivers_autoprobe, then re-enable
 328                 the VFs.
 329
 330                 This is similar to /sys/bus/pci/drivers_autoprobe, but
 331                 affects only the VFs associated with a specific PF.
 332
 333 What:           /sys/bus/pci/devices/.../p2pmem/size
 334 Date:           November 2017
 335 Contact:        Logan Gunthorpe <logang@deltatee.com>
 336 Description:
 337                 If the device has any Peer-to-Peer memory registered, this
 338                 file contains the total amount of memory that the device
 339                 provides (in decimal).
 340
 341 What:           /sys/bus/pci/devices/.../p2pmem/available
 342 Date:           November 2017
 343 Contact:        Logan Gunthorpe <logang@deltatee.com>
 344 Description:
 345                 If the device has any Peer-to-Peer memory registered, this
 346                 file contains the amount of memory that has not been
 347                 allocated (in decimal).
 348
 349 What:           /sys/bus/pci/devices/.../p2pmem/published
 350 Date:           November 2017
 351 Contact:        Logan Gunthorpe <logang@deltatee.com>
 352 Description:
 353                 If the device has any Peer-to-Peer memory registered, this
 354                 file contains a '1' if the memory has been published for
 355                 use outside the driver that owns the device.
 356
 357 What:           /sys/bus/pci/devices/.../link/clkpm
 358                 /sys/bus/pci/devices/.../link/l0s_aspm
 359                 /sys/bus/pci/devices/.../link/l1_aspm
 360                 /sys/bus/pci/devices/.../link/l1_1_aspm
 361                 /sys/bus/pci/devices/.../link/l1_2_aspm
 362                 /sys/bus/pci/devices/.../link/l1_1_pcipm
 363                 /sys/bus/pci/devices/.../link/l1_2_pcipm
 364 Date:           October 2019
 365 Contact:        Heiner Kallweit <hkallweit1@gmail.com>
 366 Description:    If ASPM is supported for an endpoint, these files can be
 367                 used to disable or enable the individual power management
 368                 states. Write y/1/on to enable, n/0/off to disable.
 369
 370 What:           /sys/bus/pci/devices/.../power_state
 371 Date:           November 2020
 372 Contact:        Linux PCI developers <linux-pci@vger.kernel.org>
 373 Description:
 374                 This file contains the current PCI power state of the device.
 375                 The value comes from the PCI kernel device state and can be one
 376                 of: "unknown", "error", "D0", D1", "D2", "D3hot", "D3cold".
 377                 The file is read only.