On Thu, 23 Jun 2022 19:46:52 -0700 Dan Williams <dan.j.williams@xxxxxxxxx> wrote: > Clarify the access permission of CXL sysfs attributes in the > documentation to help development of userspace tooling. > > Reported-by: Alison Schofield <alison.schofield@xxxxxxxxx> > Signed-off-by: Dan Williams <dan.j.williams@xxxxxxxxx> Makes sense, though might be a good idea at somepoint to standardize this in some fashion for the automated docs build. e.g. https://www.kernel.org/doc/html/latest/admin-guide/abi-testing.html#abi-sys-bus-cxl-devices-devtype +CC Mauro in case he thinks it's worth looking at doing for purposes of his runtime verification scripts... Reviewed-by: Jonathan Cameron <Jonathan.Cameron@xxxxxxxxxx> > --- > Documentation/ABI/testing/sysfs-bus-cxl | 81 ++++++++++++++++--------------- > 1 file changed, 41 insertions(+), 40 deletions(-) > > diff --git a/Documentation/ABI/testing/sysfs-bus-cxl b/Documentation/ABI/testing/sysfs-bus-cxl > index 7c2b846521f3..1fd5984b6158 100644 > --- a/Documentation/ABI/testing/sysfs-bus-cxl > +++ b/Documentation/ABI/testing/sysfs-bus-cxl > @@ -57,28 +57,28 @@ Date: June, 2021 > KernelVersion: v5.14 > Contact: linux-cxl@xxxxxxxxxxxxxxx > Description: > - CXL device objects export the devtype attribute which mirrors > - the same value communicated in the DEVTYPE environment variable > - for uevents for devices on the "cxl" bus. > + (RO) CXL device objects export the devtype attribute which > + mirrors the same value communicated in the DEVTYPE environment > + variable for uevents for devices on the "cxl" bus. > > What: /sys/bus/cxl/devices/*/modalias > Date: December, 2021 > KernelVersion: v5.18 > Contact: linux-cxl@xxxxxxxxxxxxxxx > Description: > - CXL device objects export the modalias attribute which mirrors > - the same value communicated in the MODALIAS environment variable > - for uevents for devices on the "cxl" bus. > + (RO) CXL device objects export the modalias attribute which > + mirrors the same value communicated in the MODALIAS environment > + variable for uevents for devices on the "cxl" bus. > > What: /sys/bus/cxl/devices/portX/uport > Date: June, 2021 > KernelVersion: v5.14 > Contact: linux-cxl@xxxxxxxxxxxxxxx > Description: > - CXL port objects are enumerated from either a platform firmware > - device (ACPI0017 and ACPI0016) or PCIe switch upstream port with > - CXL component registers. The 'uport' symlink connects the CXL > - portX object to the device that published the CXL port > + (RO) CXL port objects are enumerated from either a platform > + firmware device (ACPI0017 and ACPI0016) or PCIe switch upstream > + port with CXL component registers. The 'uport' symlink connects > + the CXL portX object to the device that published the CXL port > capability. > > What: /sys/bus/cxl/devices/portX/dportY > @@ -86,20 +86,20 @@ Date: June, 2021 > KernelVersion: v5.14 > Contact: linux-cxl@xxxxxxxxxxxxxxx > Description: > - CXL port objects are enumerated from either a platform firmware > - device (ACPI0017 and ACPI0016) or PCIe switch upstream port with > - CXL component registers. The 'dportY' symlink identifies one or > - more downstream ports that the upstream port may target in its > - decode of CXL memory resources. The 'Y' integer reflects the > - hardware port unique-id used in the hardware decoder target > - list. > + (RO) CXL port objects are enumerated from either a platform > + firmware device (ACPI0017 and ACPI0016) or PCIe switch upstream > + port with CXL component registers. The 'dportY' symlink > + identifies one or more downstream ports that the upstream port > + may target in its decode of CXL memory resources. The 'Y' > + integer reflects the hardware port unique-id used in the > + hardware decoder target list. > > What: /sys/bus/cxl/devices/decoderX.Y > Date: June, 2021 > KernelVersion: v5.14 > Contact: linux-cxl@xxxxxxxxxxxxxxx > Description: > - CXL decoder objects are enumerated from either a platform > + (RO) CXL decoder objects are enumerated from either a platform > firmware description, or a CXL HDM decoder register set in a > PCIe device (see CXL 2.0 section 8.2.5.12 CXL HDM Decoder > Capability Structure). The 'X' in decoderX.Y represents the > @@ -111,42 +111,43 @@ Date: June, 2021 > KernelVersion: v5.14 > Contact: linux-cxl@xxxxxxxxxxxxxxx > Description: > - The 'start' and 'size' attributes together convey the physical > - address base and number of bytes mapped in the decoder's decode > - window. For decoders of devtype "cxl_decoder_root" the address > - range is fixed. For decoders of devtype "cxl_decoder_switch" the > - address is bounded by the decode range of the cxl_port ancestor > - of the decoder's cxl_port, and dynamically updates based on the > - active memory regions in that address space. > + (RO) The 'start' and 'size' attributes together convey the > + physical address base and number of bytes mapped in the > + decoder's decode window. For decoders of devtype > + "cxl_decoder_root" the address range is fixed. For decoders of > + devtype "cxl_decoder_switch" the address is bounded by the > + decode range of the cxl_port ancestor of the decoder's cxl_port, > + and dynamically updates based on the active memory regions in > + that address space. > > What: /sys/bus/cxl/devices/decoderX.Y/locked > Date: June, 2021 > KernelVersion: v5.14 > Contact: linux-cxl@xxxxxxxxxxxxxxx > Description: > - CXL HDM decoders have the capability to lock the configuration > - until the next device reset. For decoders of devtype > - "cxl_decoder_root" there is no standard facility to unlock them. > - For decoders of devtype "cxl_decoder_switch" a secondary bus > - reset, of the PCIe bridge that provides the bus for this > - decoders uport, unlocks / resets the decoder. > + (RO) CXL HDM decoders have the capability to lock the > + configuration until the next device reset. For decoders of > + devtype "cxl_decoder_root" there is no standard facility to > + unlock them. For decoders of devtype "cxl_decoder_switch" a > + secondary bus reset, of the PCIe bridge that provides the bus > + for this decoders uport, unlocks / resets the decoder. > > What: /sys/bus/cxl/devices/decoderX.Y/target_list > Date: June, 2021 > KernelVersion: v5.14 > Contact: linux-cxl@xxxxxxxxxxxxxxx > Description: > - Display a comma separated list of the current decoder target > - configuration. The list is ordered by the current configured > - interleave order of the decoder's dport instances. Each entry in > - the list is a dport id. > + (RO) Display a comma separated list of the current decoder > + target configuration. The list is ordered by the current > + configured interleave order of the decoder's dport instances. > + Each entry in the list is a dport id. > > What: /sys/bus/cxl/devices/decoderX.Y/cap_{pmem,ram,type2,type3} > Date: June, 2021 > KernelVersion: v5.14 > Contact: linux-cxl@xxxxxxxxxxxxxxx > Description: > - When a CXL decoder is of devtype "cxl_decoder_root", it > + (RO) When a CXL decoder is of devtype "cxl_decoder_root", it > represents a fixed memory window identified by platform > firmware. A fixed window may only support a subset of memory > types. The 'cap_*' attributes indicate whether persistent > @@ -158,8 +159,8 @@ Date: June, 2021 > KernelVersion: v5.14 > Contact: linux-cxl@xxxxxxxxxxxxxxx > Description: > - When a CXL decoder is of devtype "cxl_decoder_switch", it can > - optionally decode either accelerator memory (type-2) or expander > - memory (type-3). The 'target_type' attribute indicates the > - current setting which may dynamically change based on what > + (RO) When a CXL decoder is of devtype "cxl_decoder_switch", it > + can optionally decode either accelerator memory (type-2) or > + expander memory (type-3). The 'target_type' attribute indicates > + the current setting which may dynamically change based on what > memory regions are activated in this decode hierarchy. >
