diff options
Diffstat (limited to 'Documentation/ABI/testing/sysfs-bus-pci')
| -rw-r--r-- | Documentation/ABI/testing/sysfs-bus-pci | 282 |
1 files changed, 267 insertions, 15 deletions
diff --git a/Documentation/ABI/testing/sysfs-bus-pci b/Documentation/ABI/testing/sysfs-bus-pci index 450296cc7948..69f952fffec7 100644 --- a/Documentation/ABI/testing/sysfs-bus-pci +++ b/Documentation/ABI/testing/sysfs-bus-pci @@ -1,4 +1,5 @@ What: /sys/bus/pci/drivers/.../bind +What: /sys/devices/pciX/.../bind Date: December 2003 Contact: linux-pci@vger.kernel.org Description: @@ -7,11 +8,14 @@ Description: this location. This is useful for overriding default bindings. The format for the location is: DDDD:BB:DD.F. That is Domain:Bus:Device.Function and is the same as - found in /sys/bus/pci/devices/. For example: - # echo 0000:00:19.0 > /sys/bus/pci/drivers/foo/bind + found in /sys/bus/pci/devices/. For example:: + + # echo 0000:00:19.0 > /sys/bus/pci/drivers/foo/bind + (Note: kernels before 2.6.28 may require echo -n). What: /sys/bus/pci/drivers/.../unbind +What: /sys/devices/pciX/.../unbind Date: December 2003 Contact: linux-pci@vger.kernel.org Description: @@ -20,11 +24,14 @@ Description: this location. This may be useful when overriding default bindings. The format for the location is: DDDD:BB:DD.F. That is Domain:Bus:Device.Function and is the same as - found in /sys/bus/pci/devices/. For example: - # echo 0000:00:19.0 > /sys/bus/pci/drivers/foo/unbind + found in /sys/bus/pci/devices/. For example:: + + # echo 0000:00:19.0 > /sys/bus/pci/drivers/foo/unbind + (Note: kernels before 2.6.28 may require echo -n). What: /sys/bus/pci/drivers/.../new_id +What: /sys/devices/pciX/.../new_id Date: December 2003 Contact: linux-pci@vger.kernel.org Description: @@ -38,10 +45,12 @@ Description: Class, Class Mask, and Private Driver Data. The Vendor ID and Device ID fields are required, the rest are optional. Upon successfully adding an ID, the driver will probe - for the device and attempt to bind to it. For example: - # echo "8086 10f5" > /sys/bus/pci/drivers/foo/new_id + for the device and attempt to bind to it. For example:: + + # echo "8086 10f5" > /sys/bus/pci/drivers/foo/new_id What: /sys/bus/pci/drivers/.../remove_id +What: /sys/devices/pciX/.../remove_id Date: February 2009 Contact: Chris Wright <chrisw@sous-sol.org> Description: @@ -54,8 +63,9 @@ Description: required, the rest are optional. After successfully removing an ID, the driver will no longer support the device. This is useful to ensure auto probing won't - match the driver to the device. For example: - # echo "8086 10f5" > /sys/bus/pci/drivers/foo/remove_id + match the driver to the device. For example:: + + # echo "8086 10f5" > /sys/bus/pci/drivers/foo/remove_id What: /sys/bus/pci/rescan Date: January 2009 @@ -90,6 +100,17 @@ Description: This attribute indicates the mode that the irq vector named by the file is in (msi vs. msix) +What: /sys/bus/pci/devices/.../irq +Date: August 2021 +Contact: Linux PCI developers <linux-pci@vger.kernel.org> +Description: + If a driver has enabled MSI (not MSI-X), "irq" contains the + IRQ of the first MSI vector. Otherwise "irq" contains the + IRQ of the legacy INTx interrupt. + + "irq" being set to 0 indicates that the device isn't + capable of generating legacy INTx interrupts. + What: /sys/bus/pci/devices/.../remove Date: January 2009 Contact: Linux PCI developers <linux-pci@vger.kernel.org> @@ -115,6 +136,23 @@ Description: child buses, and re-discover devices removed earlier from this part of the device tree. +What: /sys/bus/pci/devices/.../reset_method +Date: August 2021 +Contact: Amey Narkhede <ameynarkhede03@gmail.com> +Description: + Some devices allow an individual function to be reset + without affecting other functions in the same slot. + + For devices that have this support, a file named + reset_method is present in sysfs. Reading this file + gives names of the supported and enabled reset methods and + their ordering. Writing a space-separated list of names of + reset methods sets the reset methods and ordering to be + used when resetting the device. Writing an empty string + disables the ability to reset the device. Writing + "default" enables all supported reset methods in the + default ordering. + What: /sys/bus/pci/devices/.../reset Date: July 2009 Contact: Michael S. Tsirkin <mst@redhat.com> @@ -125,6 +163,17 @@ Description: will be present in sysfs. Writing 1 to this file will perform reset. +What: /sys/bus/pci/devices/.../reset_subordinate +Date: October 2024 +Contact: linux-pci@vger.kernel.org +Description: + This is visible only for bridge devices. If you want to reset + all devices attached through the subordinate bus of a specific + bridge device, writing 1 to this will try to do it. This will + affect all devices attached to the system through this bridge + similiar to writing 1 to their individual "reset" file, so use + with caution. + What: /sys/bus/pci/devices/.../vpd Date: February 2008 Contact: Ben Hutchings <bwh@kernel.org> @@ -133,11 +182,11 @@ Description: binary file containing the Vital Product Data for the device. It should follow the VPD format defined in PCI Specification 2.1 or 2.2, but users should consider - that some devices may have malformatted data. If the - underlying VPD has a writable section then the + that some devices may have incorrectly formatted data. + If the underlying VPD has a writable section then the corresponding section of this file will be writable. -What: /sys/bus/pci/devices/.../virtfnN +What: /sys/bus/pci/devices/.../virtfn<N> Date: March 2009 Contact: Yu Zhao <yu.zhao@intel.com> Description: @@ -164,6 +213,24 @@ Description: The symbolic link points to the PCI device sysfs entry of the Physical Function this device associates with. +What: /sys/bus/pci/devices/.../modalias +Date: May 2005 +Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org> +Description: + This attribute indicates the PCI ID of the device object. + + That is in the format: + pci:vXXXXXXXXdXXXXXXXXsvXXXXXXXXsdXXXXXXXXbcXXscXXiXX, + where: + + - vXXXXXXXX contains the vendor ID; + - dXXXXXXXX contains the device ID; + - svXXXXXXXX contains the sub-vendor ID; + - sdXXXXXXXX contains the subsystem device ID; + - bcXX contains the device class; + - scXX contains the device subclass; + - iXX contains the device class programming interface. + What: /sys/bus/pci/slots/.../module Date: June 2009 Contact: linux-pci@vger.kernel.org @@ -189,10 +256,13 @@ What: /sys/bus/pci/devices/.../index Date: July 2010 Contact: Narendra K <narendra_k@dell.com>, linux-bugs@dell.com Description: - Reading this attribute will provide the firmware - given instance (SMBIOS type 41 device type instance) of the - PCI device. The attribute will be created only if the firmware - has given an instance number to the PCI device. + Reading this attribute will provide the firmware given instance + number of the PCI device. Depending on the platform this can + be for example the SMBIOS type 41 device type instance or the + user-defined ID (UID) on s390. The attribute will be created + only if the firmware has given an instance number to the PCI + device and that number is guaranteed to uniquely identify the + device in the system. Users: Userspace applications interested in knowing the firmware assigned device type instance of the PCI @@ -348,6 +418,16 @@ Description: file contains a '1' if the memory has been published for use outside the driver that owns the device. +What: /sys/bus/pci/devices/.../p2pmem/allocate +Date: August 2022 +Contact: Logan Gunthorpe <logang@deltatee.com> +Description: + This file allows mapping p2pmem into userspace. For each + mmap() call on this file, the kernel will allocate a chunk + of Peer-to-Peer memory for use in Peer-to-Peer transactions. + This memory can be used in O_DIRECT calls to NVMe backed + files for Peer-to-Peer copies. + What: /sys/bus/pci/devices/.../link/clkpm /sys/bus/pci/devices/.../link/l0s_aspm /sys/bus/pci/devices/.../link/l1_aspm @@ -360,3 +440,175 @@ Contact: Heiner Kallweit <hkallweit1@gmail.com> Description: If ASPM is supported for an endpoint, these files can be used to disable or enable the individual power management states. Write y/1/on to enable, n/0/off to disable. + +What: /sys/bus/pci/devices/.../power_state +Date: November 2020 +Contact: Linux PCI developers <linux-pci@vger.kernel.org> +Description: + This file contains the current PCI power state of the device. + The value comes from the PCI kernel device state and can be one + of: "unknown", "error", "D0", D1", "D2", "D3hot", "D3cold". + The file is read only. + +What: /sys/bus/pci/devices/.../sriov_vf_total_msix +Date: January 2021 +Contact: Leon Romanovsky <leonro@nvidia.com> +Description: + This file is associated with a SR-IOV physical function (PF). + It contains the total number of MSI-X vectors available for + assignment to all virtual functions (VFs) associated with PF. + The value will be zero if the device doesn't support this + functionality. For supported devices, the value will be + constant and won't be changed after MSI-X vectors assignment. + +What: /sys/bus/pci/devices/.../sriov_vf_msix_count +Date: January 2021 +Contact: Leon Romanovsky <leonro@nvidia.com> +Description: + This file is associated with a SR-IOV virtual function (VF). + It allows configuration of the number of MSI-X vectors for + the VF. This allows devices that have a global pool of MSI-X + vectors to optimally divide them between VFs based on VF usage. + + The values accepted are: + * > 0 - this number will be reported as the Table Size in the + VF's MSI-X capability + * < 0 - not valid + * = 0 - will reset to the device default value + + The file is writable if the PF is bound to a driver that + implements ->sriov_set_msix_vec_count(). + +What: /sys/bus/pci/devices/.../resourceN_resize +Date: September 2022 +Contact: Alex Williamson <alex.williamson@redhat.com> +Description: + These files provide an interface to PCIe Resizable BAR support. + A file is created for each BAR resource (N) supported by the + PCIe Resizable BAR extended capability of the device. Reading + each file exposes the bitmap of available resource sizes: + + # cat resource1_resize + 00000000000001c0 + + The bitmap represents supported resource sizes for the BAR, + where bit0 = 1MB, bit1 = 2MB, bit2 = 4MB, etc. In the above + example the device supports 64MB, 128MB, and 256MB BAR sizes. + + When writing the file, the user provides the bit position of + the desired resource size, for example: + + # echo 7 > resource1_resize + + This indicates to set the size value corresponding to bit 7, + 128MB. The resulting size is 2 ^ (bit# + 20). This definition + matches the PCIe specification of this capability. + + In order to make use of resource resizing, all PCI drivers must + be unbound from the device and peer devices under the same + parent bridge may need to be soft removed. In the case of + VGA devices, writing a resize value will remove low level + console drivers from the device. Raw users of pci-sysfs + resourceN attributes must be terminated prior to resizing. + Success of the resizing operation is not guaranteed. + +What: /sys/bus/pci/devices/.../leds/*:enclosure:*/brightness +What: /sys/class/leds/*:enclosure:*/brightness +Date: August 2024 +KernelVersion: 6.12 +Description: + LED indications on PCIe storage enclosures which are controlled + through the NPEM interface (Native PCIe Enclosure Management, + PCIe r6.1 sec 6.28) are accessible as led class devices, both + below /sys/class/leds and below NPEM-capable PCI devices. + + Although these led class devices could be manipulated manually, + in practice they are typically manipulated automatically by an + application such as ledmon(8). + + The name of a led class device is as follows: + <bdf>:enclosure:<indication> + where: + + - <bdf> is the domain, bus, device and function number + (e.g. 10000:02:05.0) + - <indication> is a short description of the LED indication + + Valid indications per PCIe r6.1 table 6-27 are: + + - ok (drive is functioning normally) + - locate (drive is being identified by an admin) + - fail (drive is not functioning properly) + - rebuild (drive is part of an array that is rebuilding) + - pfa (drive is predicted to fail soon) + - hotspare (drive is marked to be used as a replacement) + - ica (drive is part of an array that is degraded) + - ifa (drive is part of an array that is failed) + - idt (drive is not the right type for the connector) + - disabled (drive is disabled, removal is safe) + - specific0 to specific7 (enclosure-specific indications) + + Broadly, the indications fall into one of these categories: + + - to signify drive state (ok, locate, fail, idt, disabled) + - to signify drive role or state in a software RAID array + (rebuild, pfa, hotspare, ica, ifa) + - to signify any other role or state (specific0 to specific7) + + Mandatory indications per PCIe r6.1 sec 7.9.19.2 comprise: + ok, locate, fail, rebuild. All others are optional. + A led class device is only visible if the corresponding + indication is supported by the device. + + To manipulate the indications, write 0 (LED_OFF) or 1 (LED_ON) + to the "brightness" file. Note that manipulating an indication + may implicitly manipulate other indications at the vendor's + discretion. E.g. when the user lights up the "ok" indication, + the vendor may choose to automatically turn off the "fail" + indication. The current state of an indication can be + retrieved by reading its "brightness" file. + + The PCIe Base Specification allows vendors leeway to choose + different colors or blinking patterns for the indications, + but they typically follow the IBPI standard. E.g. the "locate" + indication is usually presented as one or two LEDs blinking at + 4 Hz frequency: + https://en.wikipedia.org/wiki/International_Blinking_Pattern_Interpretation + + PCI Firmware Specification r3.3 sec 4.7 defines a DSM interface + to facilitate shared access by operating system and platform + firmware to a device's NPEM registers. The kernel will use + this DSM interface where available, instead of accessing NPEM + registers directly. The DSM interface does not support the + enclosure-specific indications "specific0" to "specific7", + hence the corresponding led class devices are unavailable if + the DSM interface is used. + +What: /sys/bus/pci/devices/.../doe_features +Date: March 2025 +Contact: Linux PCI developers <linux-pci@vger.kernel.org> +Description: + This directory contains a list of the supported Data Object + Exchange (DOE) features. The features are the file name. + The contents of each file is the raw Vendor ID and data + object feature values. + + The value comes from the device and specifies the vendor and + data object type supported. The lower (RHS of the colon) is + the data object type in hex. The upper (LHS of the colon) + is the vendor ID. + + As all DOE devices must support the DOE discovery feature, + if DOE is supported you will at least see the doe_discovery + file, with this contents: + + # cat doe_features/doe_discovery + 0001:00 + + If the device supports other features you will see other + files as well. For example if CMA/SPDM and secure CMA/SPDM + are supported the doe_features directory will look like + this: + + # ls doe_features + 0001:01 0001:02 doe_discovery |