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. 503 504 What: /sys/bus/pci/devices/.../leds/*:enclosure:*/brightness 505 What: /sys/class/leds/*:enclosure:*/brightness 506 Date: August 2024 507 KernelVersion: 6.12 508 Description: 509 LED indications on PCIe storage enclosures which are controlled 510 through the NPEM interface (Native PCIe Enclosure Management, 511 PCIe r6.1 sec 6.28) are accessible as led class devices, both 512 below /sys/class/leds and below NPEM-capable PCI devices. 513 514 Although these led class devices could be manipulated manually, 515 in practice they are typically manipulated automatically by an 516 application such as ledmon(8). 517 518 The name of a led class device is as follows: 519 <bdf>:enclosure:<indication> 520 where: 521 522 - <bdf> is the domain, bus, device and function number 523 (e.g. 10000:02:05.0) 524 - <indication> is a short description of the LED indication 525 526 Valid indications per PCIe r6.1 table 6-27 are: 527 528 - ok (drive is functioning normally) 529 - locate (drive is being identified by an admin) 530 - fail (drive is not functioning properly) 531 - rebuild (drive is part of an array that is rebuilding) 532 - pfa (drive is predicted to fail soon) 533 - hotspare (drive is marked to be used as a replacement) 534 - ica (drive is part of an array that is degraded) 535 - ifa (drive is part of an array that is failed) 536 - idt (drive is not the right type for the connector) 537 - disabled (drive is disabled, removal is safe) 538 - specific0 to specific7 (enclosure-specific indications) 539 540 Broadly, the indications fall into one of these categories: 541 542 - to signify drive state (ok, locate, fail, idt, disabled) 543 - to signify drive role or state in a software RAID array 544 (rebuild, pfa, hotspare, ica, ifa) 545 - to signify any other role or state (specific0 to specific7) 546 547 Mandatory indications per PCIe r6.1 sec 7.9.19.2 comprise: 548 ok, locate, fail, rebuild. All others are optional. 549 A led class device is only visible if the corresponding 550 indication is supported by the device. 551 552 To manipulate the indications, write 0 (LED_OFF) or 1 (LED_ON) 553 to the "brightness" file. Note that manipulating an indication 554 may implicitly manipulate other indications at the vendor's 555 discretion. E.g. when the user lights up the "ok" indication, 556 the vendor may choose to automatically turn off the "fail" 557 indication. The current state of an indication can be 558 retrieved by reading its "brightness" file. 559 560 The PCIe Base Specification allows vendors leeway to choose 561 different colors or blinking patterns for the indications, 562 but they typically follow the IBPI standard. E.g. the "locate" 563 indication is usually presented as one or two LEDs blinking at 564 4 Hz frequency: 565 https://en.wikipedia.org/wiki/International_Blinking_Pattern_Interpretation 566 567 PCI Firmware Specification r3.3 sec 4.7 defines a DSM interface 568 to facilitate shared access by operating system and platform 569 firmware to a device's NPEM registers. The kernel will use 570 this DSM interface where available, instead of accessing NPEM 571 registers directly. The DSM interface does not support the 572 enclosure-specific indications "specific0" to "specific7", 573 hence the corresponding led class devices are unavailable if 574 the DSM interface is used. 575