| blob | 5da6a14dc326bd651d8cabb795d769f221daa81e |
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::
13 # echo 0000:00:19.0 > /sys/bus/pci/drivers/foo/bind
15 (Note: kernels before 2.6.28 may require echo -n).
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::
29 # echo 0000:00:19.0 > /sys/bus/pci/drivers/foo/unbind
31 (Note: kernels before 2.6.28 may require echo -n).
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::
50 # echo "8086 10f5" > /sys/bus/pci/drivers/foo/new_id
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::
68 # echo "8086 10f5" > /sys/bus/pci/drivers/foo/remove_id
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.
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.
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.
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)
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.
111 "irq" being set to 0 indicates that the device isn't
112 capable of generating legacy INTx interrupts.
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.
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.
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.
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.
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.
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.
166 What: /sys/bus/pci/devices/.../reset_subordinate
167 Date: October 2024
168 Contact: linux-pci@vger.kernel.org
169 Description:
170 This is visible only for bridge devices. If you want to reset
171 all devices attached through the subordinate bus of a specific
172 bridge device, writing 1 to this will try to do it. This will
173 affect all devices attached to the system through this bridge
174 similiar to writing 1 to their individual "reset" file, so use
175 with caution.
177 What: /sys/bus/pci/devices/.../vpd
178 Date: February 2008
179 Contact: Ben Hutchings <bwh@kernel.org>
180 Description:
181 A file named vpd in a device directory will be a
182 binary file containing the Vital Product Data for the
183 device. It should follow the VPD format defined in
184 PCI Specification 2.1 or 2.2, but users should consider
185 that some devices may have incorrectly formatted data.
186 If the underlying VPD has a writable section then the
187 corresponding section of this file will be writable.
189 What: /sys/bus/pci/devices/.../virtfn<N>
190 Date: March 2009
191 Contact: Yu Zhao <yu.zhao@intel.com>
192 Description:
193 This symbolic link appears when hardware supports the SR-IOV
194 capability and the Physical Function driver has enabled it.
195 The symbolic link points to the PCI device sysfs entry of the
196 Virtual Function whose index is N (0...MaxVFs-1).
198 What: /sys/bus/pci/devices/.../dep_link
199 Date: March 2009
200 Contact: Yu Zhao <yu.zhao@intel.com>
201 Description:
202 This symbolic link appears when hardware supports the SR-IOV
203 capability and the Physical Function driver has enabled it,
204 and this device has vendor specific dependencies with others.
205 The symbolic link points to the PCI device sysfs entry of
206 Physical Function this device depends on.
208 What: /sys/bus/pci/devices/.../physfn
209 Date: March 2009
210 Contact: Yu Zhao <yu.zhao@intel.com>
211 Description:
212 This symbolic link appears when a device is a Virtual Function.
213 The symbolic link points to the PCI device sysfs entry of the
214 Physical Function this device associates with.
216 What: /sys/bus/pci/devices/.../modalias
217 Date: May 2005
218 Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
219 Description:
220 This attribute indicates the PCI ID of the device object.
222 That is in the format:
223 pci:vXXXXXXXXdXXXXXXXXsvXXXXXXXXsdXXXXXXXXbcXXscXXiXX,
224 where:
226 - vXXXXXXXX contains the vendor ID;
227 - dXXXXXXXX contains the device ID;
228 - svXXXXXXXX contains the sub-vendor ID;
229 - sdXXXXXXXX contains the subsystem device ID;
230 - bcXX contains the device class;
231 - scXX contains the device subclass;
232 - iXX contains the device class programming interface.
234 What: /sys/bus/pci/slots/.../module
235 Date: June 2009
236 Contact: linux-pci@vger.kernel.org
237 Description:
238 This symbolic link points to the PCI hotplug controller driver
239 module that manages the hotplug slot.
241 What: /sys/bus/pci/devices/.../label
242 Date: July 2010
243 Contact: Narendra K <narendra_k@dell.com>, linux-bugs@dell.com
244 Description:
245 Reading this attribute will provide the firmware
246 given name (SMBIOS type 41 string or ACPI _DSM string) of
247 the PCI device. The attribute will be created only
248 if the firmware has given a name to the PCI device.
249 ACPI _DSM string name will be given priority if the
250 system firmware provides SMBIOS type 41 string also.
251 Users:
252 Userspace applications interested in knowing the
253 firmware assigned name of the PCI device.
255 What: /sys/bus/pci/devices/.../index
256 Date: July 2010
257 Contact: Narendra K <narendra_k@dell.com>, linux-bugs@dell.com
258 Description:
259 Reading this attribute will provide the firmware given instance
260 number of the PCI device. Depending on the platform this can
261 be for example the SMBIOS type 41 device type instance or the
262 user-defined ID (UID) on s390. The attribute will be created
263 only if the firmware has given an instance number to the PCI
264 device and that number is guaranteed to uniquely identify the
265 device in the system.
266 Users:
267 Userspace applications interested in knowing the
268 firmware assigned device type instance of the PCI
269 device that can help in understanding the firmware
270 intended order of the PCI device.
272 What: /sys/bus/pci/devices/.../acpi_index
273 Date: July 2010
274 Contact: Narendra K <narendra_k@dell.com>, linux-bugs@dell.com
275 Description:
276 Reading this attribute will provide the firmware
277 given instance (ACPI _DSM instance number) of the PCI device.
278 The attribute will be created only if the firmware has given
279 an instance number to the PCI device. ACPI _DSM instance number
280 will be given priority if the system firmware provides SMBIOS
281 type 41 device type instance also.
282 Users:
283 Userspace applications interested in knowing the
284 firmware assigned instance number of the PCI
285 device that can help in understanding the firmware
286 intended order of the PCI device.
288 What: /sys/bus/pci/devices/.../d3cold_allowed
289 Date: July 2012
290 Contact: Huang Ying <ying.huang@intel.com>
291 Description:
292 d3cold_allowed is bit to control whether the corresponding PCI
293 device can be put into D3Cold state. If it is cleared, the
294 device will never be put into D3Cold state. If it is set, the
295 device may be put into D3Cold state if other requirements are
296 satisfied too. Reading this attribute will show the current
297 value of d3cold_allowed bit. Writing this attribute will set
298 the value of d3cold_allowed bit.
300 What: /sys/bus/pci/devices/.../sriov_totalvfs
301 Date: November 2012
302 Contact: Donald Dutile <ddutile@redhat.com>
303 Description:
304 This file appears when a physical PCIe device supports SR-IOV.
305 Userspace applications can read this file to determine the
306 maximum number of Virtual Functions (VFs) a PCIe physical
307 function (PF) can support. Typically, this is the value reported
308 in the PF's SR-IOV extended capability structure's TotalVFs
309 element. Drivers have the ability at probe time to reduce the
310 value read from this file via the pci_sriov_set_totalvfs()
311 function.
313 What: /sys/bus/pci/devices/.../sriov_numvfs
314 Date: November 2012
315 Contact: Donald Dutile <ddutile@redhat.com>
316 Description:
317 This file appears when a physical PCIe device supports SR-IOV.
318 Userspace applications can read and write to this file to
319 determine and control the enablement or disablement of Virtual
320 Functions (VFs) on the physical function (PF). A read of this
321 file will return the number of VFs that are enabled on this PF.
322 A number written to this file will enable the specified
323 number of VFs. A userspace application would typically read the
324 file and check that the value is zero, and then write the number
325 of VFs that should be enabled on the PF; the value written
326 should be less than or equal to the value in the sriov_totalvfs
327 file. A userspace application wanting to disable the VFs would
328 write a zero to this file. The core ensures that valid values
329 are written to this file, and returns errors when values are not
330 valid. For example, writing a 2 to this file when sriov_numvfs
331 is not 0 and not 2 already will return an error. Writing a 10
332 when the value of sriov_totalvfs is 8 will return an error.
334 What: /sys/bus/pci/devices/.../driver_override
335 Date: April 2014
336 Contact: Alex Williamson <alex.williamson@redhat.com>
337 Description:
338 This file allows the driver for a device to be specified which
339 will override standard static and dynamic ID matching. When
340 specified, only a driver with a name matching the value written
341 to driver_override will have an opportunity to bind to the
342 device. The override is specified by writing a string to the
343 driver_override file (echo pci-stub > driver_override) and
344 may be cleared with an empty string (echo > driver_override).
345 This returns the device to standard matching rules binding.
346 Writing to driver_override does not automatically unbind the
347 device from its current driver or make any attempt to
348 automatically load the specified driver. If no driver with a
349 matching name is currently loaded in the kernel, the device
350 will not bind to any driver. This also allows devices to
351 opt-out of driver binding using a driver_override name such as
352 "none". Only a single driver may be specified in the override,
353 there is no support for parsing delimiters.
355 What: /sys/bus/pci/devices/.../numa_node
356 Date: Oct 2014
357 Contact: Prarit Bhargava <prarit@redhat.com>
358 Description:
359 This file contains the NUMA node to which the PCI device is
360 attached, or -1 if the node is unknown. The initial value
361 comes from an ACPI _PXM method or a similar firmware
362 source. If that is missing or incorrect, this file can be
363 written to override the node. In that case, please report
364 a firmware bug to the system vendor. Writing to this file
365 taints the kernel with TAINT_FIRMWARE_WORKAROUND, which
366 reduces the supportability of your system.
368 What: /sys/bus/pci/devices/.../revision
369 Date: November 2016
370 Contact: Emil Velikov <emil.l.velikov@gmail.com>
371 Description:
372 This file contains the revision field of the PCI device.
373 The value comes from device config space. The file is read only.
375 What: /sys/bus/pci/devices/.../sriov_drivers_autoprobe
376 Date: April 2017
377 Contact: Bodong Wang<bodong@mellanox.com>
378 Description:
379 This file is associated with the PF of a device that
380 supports SR-IOV. It determines whether newly-enabled VFs
381 are immediately bound to a driver. It initially contains
382 1, which means the kernel automatically binds VFs to a
383 compatible driver immediately after they are enabled. If
384 an application writes 0 to the file before enabling VFs,
385 the kernel will not bind VFs to a driver.
387 A typical use case is to write 0 to this file, then enable
388 VFs, then assign the newly-created VFs to virtual machines.
389 Note that changing this file does not affect already-
390 enabled VFs. In this scenario, the user must first disable
391 the VFs, write 0 to sriov_drivers_autoprobe, then re-enable
392 the VFs.
394 This is similar to /sys/bus/pci/drivers_autoprobe, but
395 affects only the VFs associated with a specific PF.
397 What: /sys/bus/pci/devices/.../p2pmem/size
398 Date: November 2017
399 Contact: Logan Gunthorpe <logang@deltatee.com>
400 Description:
401 If the device has any Peer-to-Peer memory registered, this
402 file contains the total amount of memory that the device
403 provides (in decimal).
405 What: /sys/bus/pci/devices/.../p2pmem/available
406 Date: November 2017
407 Contact: Logan Gunthorpe <logang@deltatee.com>
408 Description:
409 If the device has any Peer-to-Peer memory registered, this
410 file contains the amount of memory that has not been
411 allocated (in decimal).
413 What: /sys/bus/pci/devices/.../p2pmem/published
414 Date: November 2017
415 Contact: Logan Gunthorpe <logang@deltatee.com>
416 Description:
417 If the device has any Peer-to-Peer memory registered, this
418 file contains a '1' if the memory has been published for
419 use outside the driver that owns the device.
421 What: /sys/bus/pci/devices/.../p2pmem/allocate
422 Date: August 2022
423 Contact: Logan Gunthorpe <logang@deltatee.com>
424 Description:
425 This file allows mapping p2pmem into userspace. For each
426 mmap() call on this file, the kernel will allocate a chunk
427 of Peer-to-Peer memory for use in Peer-to-Peer transactions.
428 This memory can be used in O_DIRECT calls to NVMe backed
429 files for Peer-to-Peer copies.
431 What: /sys/bus/pci/devices/.../link/clkpm
432 /sys/bus/pci/devices/.../link/l0s_aspm
433 /sys/bus/pci/devices/.../link/l1_aspm
434 /sys/bus/pci/devices/.../link/l1_1_aspm
435 /sys/bus/pci/devices/.../link/l1_2_aspm
436 /sys/bus/pci/devices/.../link/l1_1_pcipm
437 /sys/bus/pci/devices/.../link/l1_2_pcipm
438 Date: October 2019
439 Contact: Heiner Kallweit <hkallweit1@gmail.com>
440 Description: If ASPM is supported for an endpoint, these files can be
441 used to disable or enable the individual power management
442 states. Write y/1/on to enable, n/0/off to disable.
444 What: /sys/bus/pci/devices/.../power_state
445 Date: November 2020
446 Contact: Linux PCI developers <linux-pci@vger.kernel.org>
447 Description:
448 This file contains the current PCI power state of the device.
449 The value comes from the PCI kernel device state and can be one
450 of: "unknown", "error", "D0", D1", "D2", "D3hot", "D3cold".
451 The file is read only.
453 What: /sys/bus/pci/devices/.../sriov_vf_total_msix
454 Date: January 2021
455 Contact: Leon Romanovsky <leonro@nvidia.com>
456 Description:
457 This file is associated with a SR-IOV physical function (PF).
458 It contains the total number of MSI-X vectors available for
459 assignment to all virtual functions (VFs) associated with PF.
460 The value will be zero if the device doesn't support this
461 functionality. For supported devices, the value will be
462 constant and won't be changed after MSI-X vectors assignment.
464 What: /sys/bus/pci/devices/.../sriov_vf_msix_count
465 Date: January 2021
466 Contact: Leon Romanovsky <leonro@nvidia.com>
467 Description:
468 This file is associated with a SR-IOV virtual function (VF).
469 It allows configuration of the number of MSI-X vectors for
470 the VF. This allows devices that have a global pool of MSI-X
471 vectors to optimally divide them between VFs based on VF usage.
473 The values accepted are:
474 * > 0 - this number will be reported as the Table Size in the
475 VF's MSI-X capability
476 * < 0 - not valid
477 * = 0 - will reset to the device default value
479 The file is writable if the PF is bound to a driver that
480 implements ->sriov_set_msix_vec_count().
482 What: /sys/bus/pci/devices/.../resourceN_resize
483 Date: September 2022
484 Contact: Alex Williamson <alex.williamson@redhat.com>
485 Description:
486 These files provide an interface to PCIe Resizable BAR support.
487 A file is created for each BAR resource (N) supported by the
488 PCIe Resizable BAR extended capability of the device. Reading
489 each file exposes the bitmap of available resource sizes:
491 # cat resource1_resize
492 00000000000001c0
494 The bitmap represents supported resource sizes for the BAR,
495 where bit0 = 1MB, bit1 = 2MB, bit2 = 4MB, etc. In the above
496 example the device supports 64MB, 128MB, and 256MB BAR sizes.
498 When writing the file, the user provides the bit position of
499 the desired resource size, for example:
501 # echo 7 > resource1_resize
503 This indicates to set the size value corresponding to bit 7,
504 128MB. The resulting size is 2 ^ (bit# + 20). This definition
505 matches the PCIe specification of this capability.
507 In order to make use of resource resizing, all PCI drivers must
508 be unbound from the device and peer devices under the same
509 parent bridge may need to be soft removed. In the case of
510 VGA devices, writing a resize value will remove low level
511 console drivers from the device. Raw users of pci-sysfs
512 resourceN attributes must be terminated prior to resizing.
513 Success of the resizing operation is not guaranteed.
515 What: /sys/bus/pci/devices/.../leds/*:enclosure:*/brightness
516 What: /sys/class/leds/*:enclosure:*/brightness
517 Date: August 2024
518 KernelVersion: 6.12
519 Description:
520 LED indications on PCIe storage enclosures which are controlled
521 through the NPEM interface (Native PCIe Enclosure Management,
522 PCIe r6.1 sec 6.28) are accessible as led class devices, both
523 below /sys/class/leds and below NPEM-capable PCI devices.
525 Although these led class devices could be manipulated manually,
526 in practice they are typically manipulated automatically by an
527 application such as ledmon(8).
529 The name of a led class device is as follows:
530 <bdf>:enclosure:<indication>
531 where:
533 - <bdf> is the domain, bus, device and function number
534 (e.g. 10000:02:05.0)
535 - <indication> is a short description of the LED indication
537 Valid indications per PCIe r6.1 table 6-27 are:
539 - ok (drive is functioning normally)
540 - locate (drive is being identified by an admin)
541 - fail (drive is not functioning properly)
542 - rebuild (drive is part of an array that is rebuilding)
543 - pfa (drive is predicted to fail soon)
544 - hotspare (drive is marked to be used as a replacement)
545 - ica (drive is part of an array that is degraded)
546 - ifa (drive is part of an array that is failed)
547 - idt (drive is not the right type for the connector)
548 - disabled (drive is disabled, removal is safe)
549 - specific0 to specific7 (enclosure-specific indications)
551 Broadly, the indications fall into one of these categories:
553 - to signify drive state (ok, locate, fail, idt, disabled)
554 - to signify drive role or state in a software RAID array
555 (rebuild, pfa, hotspare, ica, ifa)
556 - to signify any other role or state (specific0 to specific7)
558 Mandatory indications per PCIe r6.1 sec 7.9.19.2 comprise:
559 ok, locate, fail, rebuild. All others are optional.
560 A led class device is only visible if the corresponding
561 indication is supported by the device.
563 To manipulate the indications, write 0 (LED_OFF) or 1 (LED_ON)
564 to the "brightness" file. Note that manipulating an indication
565 may implicitly manipulate other indications at the vendor's
566 discretion. E.g. when the user lights up the "ok" indication,
567 the vendor may choose to automatically turn off the "fail"
568 indication. The current state of an indication can be
569 retrieved by reading its "brightness" file.
571 The PCIe Base Specification allows vendors leeway to choose
572 different colors or blinking patterns for the indications,
573 but they typically follow the IBPI standard. E.g. the "locate"
574 indication is usually presented as one or two LEDs blinking at
575 4 Hz frequency:
576 https://en.wikipedia.org/wiki/International_Blinking_Pattern_Interpretation
578 PCI Firmware Specification r3.3 sec 4.7 defines a DSM interface
579 to facilitate shared access by operating system and platform
580 firmware to a device's NPEM registers. The kernel will use
581 this DSM interface where available, instead of accessing NPEM
582 registers directly. The DSM interface does not support the
583 enclosure-specific indications "specific0" to "specific7",
584 hence the corresponding led class devices are unavailable if
585 the DSM interface is used.