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                 # echo 0000:00:19.0 > /sys/bus/pci/drivers/foo/bind
  12                 (Note: kernels before 2.6.28 may require echo -n).
  13
  14 What:           /sys/bus/pci/drivers/.../unbind
  15 Date:           December 2003
  16 Contact:        linux-pci@vger.kernel.org
  17 Description:
  18                 Writing a device location to this file will cause the
  19                 driver to attempt to unbind from the device found at
  20                 this location.  This may be useful when overriding default
  21                 bindings.  The format for the location is: DDDD:BB:DD.F.
  22                 That is Domain:Bus:Device.Function and is the same as
  23                 found in /sys/bus/pci/devices/. For example:
  24                 # echo 0000:00:19.0 > /sys/bus/pci/drivers/foo/unbind
  25                 (Note: kernels before 2.6.28 may require echo -n).
  26
  27 What:           /sys/bus/pci/drivers/.../new_id
  28 Date:           December 2003
  29 Contact:        linux-pci@vger.kernel.org
  30 Description:
  31                 Writing a device ID to this file will attempt to
  32                 dynamically add a new device ID to a PCI device driver.
  33                 This may allow the driver to support more hardware than
  34                 was included in the driver's static device ID support
  35                 table at compile time.  The format for the device ID is:
  36                 VVVV DDDD SVVV SDDD CCCC MMMM PPPP.  That is Vendor ID,
  37                 Device ID, Subsystem Vendor ID, Subsystem Device ID,
  38                 Class, Class Mask, and Private Driver Data.  The Vendor ID
  39                 and Device ID fields are required, the rest are optional.
  40                 Upon successfully adding an ID, the driver will probe
  41                 for the device and attempt to bind to it.  For example:
  42                 # echo "8086 10f5" > /sys/bus/pci/drivers/foo/new_id
  43
  44 What:           /sys/bus/pci/drivers/.../remove_id
  45 Date:           February 2009
  46 Contact:        Chris Wright <chrisw@sous-sol.org>
  47 Description:
  48                 Writing a device ID to this file will remove an ID
  49                 that was dynamically added via the new_id sysfs entry.
  50                 The format for the device ID is:
  51                 VVVV DDDD SVVV SDDD CCCC MMMM.  That is Vendor ID, Device
  52                 ID, Subsystem Vendor ID, Subsystem Device ID, Class,
  53                 and Class Mask.  The Vendor ID and Device ID fields are
  54                 required, the rest are optional.  After successfully
  55                 removing an ID, the driver will no longer support the
  56                 device.  This is useful to ensure auto probing won't
  57                 match the driver to the device.  For example:
  58                 # echo "8086 10f5" > /sys/bus/pci/drivers/foo/remove_id
  59
  60 What:           /sys/bus/pci/rescan
  61 Date:           January 2009
  62 Contact:        Linux PCI developers <linux-pci@vger.kernel.org>
  63 Description:
  64                 Writing a non-zero value to this attribute will
  65                 force a rescan of all PCI buses in the system, and
  66                 re-discover previously removed devices.
  67
  68 What:           /sys/bus/pci/devices/.../msi_bus
  69 Date:           September 2014
  70 Contact:        Linux PCI developers <linux-pci@vger.kernel.org>
  71 Description:
  72                 Writing a zero value to this attribute disallows MSI and
  73                 MSI-X for any future drivers of the device.  If the device
  74                 is a bridge, MSI and MSI-X will be disallowed for future
  75                 drivers of all child devices under the bridge.  Drivers
  76                 must be reloaded for the new setting to take effect.
  77
  78 What:           /sys/bus/pci/devices/.../msi_irqs/
  79 Date:           September, 2011
  80 Contact:        Neil Horman <nhorman@tuxdriver.com>
  81 Description:
  82                 The /sys/devices/.../msi_irqs directory contains a variable set
  83                 of files, with each file being named after a corresponding msi
  84                 irq vector allocated to that device.
  85
  86 What:           /sys/bus/pci/devices/.../msi_irqs/<N>
  87 Date:           September 2011
  88 Contact:        Neil Horman <nhorman@tuxdriver.com>
  89 Description:
  90                 This attribute indicates the mode that the irq vector named by
  91                 the file is in (msi vs. msix)
  92
  93 What:           /sys/bus/pci/devices/.../remove
  94 Date:           January 2009
  95 Contact:        Linux PCI developers <linux-pci@vger.kernel.org>
  96 Description:
  97                 Writing a non-zero value to this attribute will
  98                 hot-remove the PCI device and any of its children.
  99
 100 What:           /sys/bus/pci/devices/.../pci_bus/.../rescan
 101 Date:           May 2011
 102 Contact:        Linux PCI developers <linux-pci@vger.kernel.org>
 103 Description:
 104                 Writing a non-zero value to this attribute will
 105                 force a rescan of the bus and all child buses,
 106                 and re-discover devices removed earlier from this
 107                 part of the device tree.
 108
 109 What:           /sys/bus/pci/devices/.../rescan
 110 Date:           January 2009
 111 Contact:        Linux PCI developers <linux-pci@vger.kernel.org>
 112 Description:
 113                 Writing a non-zero value to this attribute will
 114                 force a rescan of the device's parent bus and all
 115                 child buses, and re-discover devices removed earlier
 116                 from this part of the device tree.
 117
 118 What:           /sys/bus/pci/devices/.../reset
 119 Date:           July 2009
 120 Contact:        Michael S. Tsirkin <mst@redhat.com>
 121 Description:
 122                 Some devices allow an individual function to be reset
 123                 without affecting other functions in the same device.
 124                 For devices that have this support, a file named reset
 125                 will be present in sysfs.  Writing 1 to this file
 126                 will perform reset.
 127
 128 What:           /sys/bus/pci/devices/.../vpd
 129 Date:           February 2008
 130 Contact:        Ben Hutchings <bwh@kernel.org>
 131 Description:
 132                 A file named vpd in a device directory will be a
 133                 binary file containing the Vital Product Data for the
 134                 device.  It should follow the VPD format defined in
 135                 PCI Specification 2.1 or 2.2, but users should consider
 136                 that some devices may have malformatted data.  If the
 137                 underlying VPD has a writable section then the
 138                 corresponding section of this file will be writable.
 139
 140 What:           /sys/bus/pci/devices/.../virtfnN
 141 Date:           March 2009
 142 Contact:        Yu Zhao <yu.zhao@intel.com>
 143 Description:
 144                 This symbolic link appears when hardware supports the SR-IOV
 145                 capability and the Physical Function driver has enabled it.
 146                 The symbolic link points to the PCI device sysfs entry of the
 147                 Virtual Function whose index is N (0...MaxVFs-1).
 148
 149 What:           /sys/bus/pci/devices/.../dep_link
 150 Date:           March 2009
 151 Contact:        Yu Zhao <yu.zhao@intel.com>
 152 Description:
 153                 This symbolic link appears when hardware supports the SR-IOV
 154                 capability and the Physical Function driver has enabled it,
 155                 and this device has vendor specific dependencies with others.
 156                 The symbolic link points to the PCI device sysfs entry of
 157                 Physical Function this device depends on.
 158
 159 What:           /sys/bus/pci/devices/.../physfn
 160 Date:           March 2009
 161 Contact:        Yu Zhao <yu.zhao@intel.com>
 162 Description:
 163                 This symbolic link appears when a device is a Virtual Function.
 164                 The symbolic link points to the PCI device sysfs entry of the
 165                 Physical Function this device associates with.
 166
 167 What:           /sys/bus/pci/slots/.../module
 168 Date:           June 2009
 169 Contact:        linux-pci@vger.kernel.org
 170 Description:
 171                 This symbolic link points to the PCI hotplug controller driver
 172                 module that manages the hotplug slot.
 173
 174 What:           /sys/bus/pci/devices/.../label
 175 Date:           July 2010
 176 Contact:        Narendra K <narendra_k@dell.com>, linux-bugs@dell.com
 177 Description:
 178                 Reading this attribute will provide the firmware
 179                 given name (SMBIOS type 41 string or ACPI _DSM string) of
 180                 the PCI device. The attribute will be created only
 181                 if the firmware has given a name to the PCI device.
 182                 ACPI _DSM string name will be given priority if the
 183                 system firmware provides SMBIOS type 41 string also.
 184 Users:
 185                 Userspace applications interested in knowing the
 186                 firmware assigned name of the PCI device.
 187
 188 What:           /sys/bus/pci/devices/.../index
 189 Date:           July 2010
 190 Contact:        Narendra K <narendra_k@dell.com>, linux-bugs@dell.com
 191 Description:
 192                 Reading this attribute will provide the firmware
 193                 given instance (SMBIOS type 41 device type instance) of the
 194                 PCI device. The attribute will be created only if the firmware
 195                 has given an instance number to the PCI device.
 196 Users:
 197                 Userspace applications interested in knowing the
 198                 firmware assigned device type instance of the PCI
 199                 device that can help in understanding the firmware
 200                 intended order of the PCI device.
 201
 202 What:           /sys/bus/pci/devices/.../acpi_index
 203 Date:           July 2010
 204 Contact:        Narendra K <narendra_k@dell.com>, linux-bugs@dell.com
 205 Description:
 206                 Reading this attribute will provide the firmware
 207                 given instance (ACPI _DSM instance number) of the PCI device.
 208                 The attribute will be created only if the firmware has given
 209                 an instance number to the PCI device. ACPI _DSM instance number
 210                 will be given priority if the system firmware provides SMBIOS
 211                 type 41 device type instance also.
 212 Users:
 213                 Userspace applications interested in knowing the
 214                 firmware assigned instance number of the PCI
 215                 device that can help in understanding the firmware
 216                 intended order of the PCI device.
 217
 218 What:           /sys/bus/pci/devices/.../d3cold_allowed
 219 Date:           July 2012
 220 Contact:        Huang Ying <ying.huang@intel.com>
 221 Description:
 222                 d3cold_allowed is bit to control whether the corresponding PCI
 223                 device can be put into D3Cold state.  If it is cleared, the
 224                 device will never be put into D3Cold state.  If it is set, the
 225                 device may be put into D3Cold state if other requirements are
 226                 satisfied too.  Reading this attribute will show the current
 227                 value of d3cold_allowed bit.  Writing this attribute will set
 228                 the value of d3cold_allowed bit.
 229
 230 What:           /sys/bus/pci/devices/.../sriov_totalvfs
 231 Date:           November 2012
 232 Contact:        Donald Dutile <ddutile@redhat.com>
 233 Description:
 234                 This file appears when a physical PCIe device supports SR-IOV.
 235                 Userspace applications can read this file to determine the
 236                 maximum number of Virtual Functions (VFs) a PCIe physical
 237                 function (PF) can support. Typically, this is the value reported
 238                 in the PF's SR-IOV extended capability structure's TotalVFs
 239                 element.  Drivers have the ability at probe time to reduce the
 240                 value read from this file via the pci_sriov_set_totalvfs()
 241                 function.
 242
 243 What:           /sys/bus/pci/devices/.../sriov_numvfs
 244 Date:           November 2012
 245 Contact:        Donald Dutile <ddutile@redhat.com>
 246 Description:
 247                 This file appears when a physical PCIe device supports SR-IOV.
 248                 Userspace applications can read and write to this file to
 249                 determine and control the enablement or disablement of Virtual
 250                 Functions (VFs) on the physical function (PF). A read of this
 251                 file will return the number of VFs that are enabled on this PF.
 252                 A number written to this file will enable the specified
 253                 number of VFs. A userspace application would typically read the
 254                 file and check that the value is zero, and then write the number
 255                 of VFs that should be enabled on the PF; the value written
 256                 should be less than or equal to the value in the sriov_totalvfs
 257                 file. A userspace application wanting to disable the VFs would
 258                 write a zero to this file. The core ensures that valid values
 259                 are written to this file, and returns errors when values are not
 260                 valid.  For example, writing a 2 to this file when sriov_numvfs
 261                 is not 0 and not 2 already will return an error. Writing a 10
 262                 when the value of sriov_totalvfs is 8 will return an error.
 263
 264 What:           /sys/bus/pci/devices/.../driver_override
 265 Date:           April 2014
 266 Contact:        Alex Williamson <alex.williamson@redhat.com>
 267 Description:
 268                 This file allows the driver for a device to be specified which
 269                 will override standard static and dynamic ID matching.  When
 270                 specified, only a driver with a name matching the value written
 271                 to driver_override will have an opportunity to bind to the
 272                 device.  The override is specified by writing a string to the
 273                 driver_override file (echo pci-stub > driver_override) and
 274                 may be cleared with an empty string (echo > driver_override).
 275                 This returns the device to standard matching rules binding.
 276                 Writing to driver_override does not automatically unbind the
 277                 device from its current driver or make any attempt to
 278                 automatically load the specified driver.  If no driver with a
 279                 matching name is currently loaded in the kernel, the device
 280                 will not bind to any driver.  This also allows devices to
 281                 opt-out of driver binding using a driver_override name such as
 282                 "none".  Only a single driver may be specified in the override,
 283                 there is no support for parsing delimiters.
 284
 285 What:           /sys/bus/pci/devices/.../numa_node
 286 Date:           Oct 2014
 287 Contact:        Prarit Bhargava <prarit@redhat.com>
 288 Description:
 289                 This file contains the NUMA node to which the PCI device is
 290                 attached, or -1 if the node is unknown.  The initial value
 291                 comes from an ACPI _PXM method or a similar firmware
 292                 source.  If that is missing or incorrect, this file can be
 293                 written to override the node.  In that case, please report
 294                 a firmware bug to the system vendor.  Writing to this file
 295                 taints the kernel with TAINT_FIRMWARE_WORKAROUND, which
 296                 reduces the supportability of your system.
 297
 298 What:           /sys/bus/pci/devices/.../revision
 299 Date:           November 2016
 300 Contact:        Emil Velikov <emil.l.velikov@gmail.com>
 301 Description:
 302                 This file contains the revision field of the PCI device.
 303                 The value comes from device config space. The file is read only.
 304
 305 What:           /sys/bus/pci/devices/.../sriov_drivers_autoprobe
 306 Date:           April 2017
 307 Contact:        Bodong Wang<bodong@mellanox.com>
 308 Description:
 309                 This file is associated with the PF of a device that
 310                 supports SR-IOV.  It determines whether newly-enabled VFs
 311                 are immediately bound to a driver.  It initially contains
 312                 1, which means the kernel automatically binds VFs to a
 313                 compatible driver immediately after they are enabled.  If
 314                 an application writes 0 to the file before enabling VFs,
 315                 the kernel will not bind VFs to a driver.
 316
 317                 A typical use case is to write 0 to this file, then enable
 318                 VFs, then assign the newly-created VFs to virtual machines.
 319                 Note that changing this file does not affect already-
 320                 enabled VFs.  In this scenario, the user must first disable
 321                 the VFs, write 0 to sriov_drivers_autoprobe, then re-enable
 322                 the VFs.
 323
 324                 This is similar to /sys/bus/pci/drivers_autoprobe, but
 325                 affects only the VFs associated with a specific PF.