cxl/Documentation: Spell out globbed sysfs attribute names
PATCH 1/1 cxl/Documentation: Spell out globbed sysfs attribute names
Four entries in sysfs-bus-cxl use braced globs to document groups of attributes. Where the glob factors out a common prefix, as in cap_{pmem,ram,type2,type3}, no individual attribute name appears in the file at all and none can be found by grep or get_abi.py search. In every case the glob also keys get_abi.py validate on the glob string, so duplicates against separately documented attributes go undetected.
Replace the globs with consecutive What: lines for each attribute. These lines continue to share the existing metadata and description and follow the format used in sysfs-driver-ufs and sysfs-bus-iio.
Also restore one missing blank line between entries.
Verify with:
python3 tools/docs/get_abi.py -D Documentation/ABI/testing validate python3 tools/docs/get_abi.py search cap_pmem
python3 tools/docs/get_abi.py search create_ram_region
validate reports no sysfs-bus-cxl warning, and both searches now return the stanza where they returned nothing before.
---
This caught my eye when reading DavidLohr's Back-Invalidate series that adds cap_bi to the cap_{pmem,ram,type2,type3} glob and then references it. I couldn't find it, not w grep and not w 'get_abi.py search'. None of the existing cap_* names can be found. This patch is independent of that series and happy to spin this to include cap_bi if needed.
This intentionally does not address get_abi.py undefined, which still fails to match decoderX.Y attributes due to a bug in the ABI tooling. That will be fixed separately in linux-doc.
Documentation/ABI/testing/sysfs-bus-cxl | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-)
Documentation/ABI/testing/sysfs-bus-cxl +11 -4
@@ -201,7 +201,8 @@ Description: capability. -What: /sys/bus/cxl/devices/{port,endpoint}X/parent_dport +What: /sys/bus/cxl/devices/portX/parent_dport +What: /sys/bus/cxl/devices/endpointX/parent_dport Date: January, 2023 KernelVersion: v6.3 Contact: [email protected]
@@ -258,7 +259,8 @@ Description: instance id of a given decoder resource. -What: /sys/bus/cxl/devices/decoderX.Y/{start,size} +What: /sys/bus/cxl/devices/decoderX.Y/start +What: /sys/bus/cxl/devices/decoderX.Y/size Date: June, 2021 KernelVersion: v5.14 Contact: [email protected]
@@ -297,7 +299,10 @@ Description: Each entry in the list is a dport id. -What: /sys/bus/cxl/devices/decoderX.Y/cap_{pmem,ram,type2,type3} +What: /sys/bus/cxl/devices/decoderX.Y/cap_pmem +What: /sys/bus/cxl/devices/decoderX.Y/cap_ram +What: /sys/bus/cxl/devices/decoderX.Y/cap_type2 +What: /sys/bus/cxl/devices/decoderX.Y/cap_type3 Date: June, 2021 KernelVersion: v5.14 Contact: [email protected]
@@ -410,7 +415,8 @@ Description: interleave_granularity). -What: /sys/bus/cxl/devices/decoderX.Y/create_{pmem,ram}_region +What: /sys/bus/cxl/devices/decoderX.Y/create_pmem_region +What: /sys/bus/cxl/devices/decoderX.Y/create_ram_region Date: May, 2022, January, 2023 KernelVersion: v6.0 (pmem), v6.3 (ram) Contact: [email protected]
@@ -500,6 +506,7 @@ Description: cache is present, the size indicates extended linear cache size plus the CXL region size. + What: /sys/bus/cxl/devices/regionZ/extended_linear_cache_size Date: October, 2025 KernelVersion: v6.19
Signature · 1 line
2.37.3
Quoted 18 lines · Alison Schofield
Four entries in sysfs-bus-cxl use braced globs to document groups of attributes. Where the glob factors out a common prefix, as in cap_{pmem,ram,type2,type3}, no individual attribute name appears in the file at all and none can be found by grep or
get_abi.pysearch. In every case the glob also keysget_abi.pyvalidate on the glob string, so duplicates against separately documented attributes go undetected.Replace the globs with consecutive What: lines for each attribute. These lines continue to share the existing metadata and description and follow the format used in sysfs-driver-ufs and sysfs-bus-iio.
Also restore one missing blank line between entries.
Verify with:
python3tools/docs/get_abi.py-DDocumentation/ABI/testingvalidate python3tools/docs/get_abi.pysearchcap_pmem
python3tools/docs/get_abi.pysearchcreate_ram_region
Quoted 4 lines
validate reports no sysfs-bus-cxl warning, and both searches now return the stanza where they returned nothing before.
Signed-off-by Alison Schofield <[email protected]>
Seems reasonable. One comment below.
Quoted 63 lines
---
This caught my eye when reading DavidLohr's Back-Invalidate series that adds
cap_bito the cap_{pmem,ram,type2,type3} glob and then references it. I couldn't find it, not w grep and not w 'get_abi.pysearch'. None of the existing cap_* names can be found. This patch is independent of that series and happy to spin this to includecap_biif needed.This intentionally does not address
get_abi.py undefined, which still fails to match decoderX.Y attributes due to a bug in the ABI tooling. That will be fixed separately in linux-doc.Documentation/ABI/testing/sysfs-bus-cxl | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-)Documentation/ABI/testing/sysfs-bus-cxl +10
-4@@ -201,7 +201,8 @@ Description: capability. -What: /sys/bus/cxl/devices/{port,endpoint}X/parent_dport +What: /sys/bus/cxl/devices/portX/parent_dport +What: /sys/bus/cxl/devices/endpointX/parent_dport Date: January, 2023 KernelVersion: v6.3 Contact: [email protected]@@ -258,7 +259,8 @@ Description: instance id of a given decoder resource. -What: /sys/bus/cxl/devices/decoderX.Y/{start,size} +What: /sys/bus/cxl/devices/decoderX.Y/start +What: /sys/bus/cxl/devices/decoderX.Y/size Date: June, 2021 KernelVersion: v5.14 Contact: [email protected]@@ -297,7 +299,10 @@ Description: Each entry in the list is a dport id. -What: /sys/bus/cxl/devices/decoderX.Y/cap_{pmem,ram,type2,type3} +What: /sys/bus/cxl/devices/decoderX.Y/cap_pmem +What: /sys/bus/cxl/devices/decoderX.Y/cap_ram +What: /sys/bus/cxl/devices/decoderX.Y/cap_type2 +What: /sys/bus/cxl/devices/decoderX.Y/cap_type3 Date: June, 2021 KernelVersion: v5.14 Contact: [email protected]@@ -410,7 +415,8 @@ Description: interleave_granularity). -What: /sys/bus/cxl/devices/decoderX.Y/create_{pmem,ram}_region +What: /sys/bus/cxl/devices/decoderX.Y/create_pmem_region +What: /sys/bus/cxl/devices/decoderX.Y/create_ram_region Date: May, 2022, January, 2023 KernelVersion: v6.0 (pmem), v6.3 (ram) Contact: [email protected]
Documentation/ABI/testing/sysfs-bus-cxl Description: · line 509
Quoted 4 lines
Documentation/ABI/testing/sysfs-bus-cxl +1
-0@@ -500,6 +506,7 @@ Description: cache is present, the size indicates extended linear cache size plus the CXL region size. +
Stray blank line?
Quoted 4 lines
Documentation/ABI/testing/sysfs-bus-cxl +0
-0What: /sys/bus/cxl/devices/regionZ/extended_linear_cache_size Date: October, 2025 KernelVersion: v6.19
Quoted 21 lines · Dave Jiang
Quoted 18 lines · Alison Schofield
Four entries in sysfs-bus-cxl use braced globs to document groups of attributes. Where the glob factors out a common prefix, as in cap_{pmem,ram,type2,type3}, no individual attribute name appears in the file at all and none can be found by grep or
get_abi.pysearch. In every case the glob also keysget_abi.pyvalidate on the glob string, so duplicates against separately documented attributes go undetected.Replace the globs with consecutive What: lines for each attribute. These lines continue to share the existing metadata and description and follow the format used in sysfs-driver-ufs and sysfs-bus-iio.
Also restore one missing blank line between entries.
Verify with:
python3tools/docs/get_abi.py-DDocumentation/ABI/testingvalidate python3tools/docs/get_abi.pysearchcap_pmem
python3tools/docs/get_abi.pysearchcreate_ram_region
Quoted 9 lines
Quoted 4 lines
validate reports no sysfs-bus-cxl warning, and both searches now return the stanza where they returned nothing before.
Signed-off-by Alison Schofield <[email protected]>Seems reasonable. One comment below.
Reviewed-by Dave Jiang <[email protected]>
You're faster than Sashiko ;)
snip
Quoted 3 lines
Quoted 1 line
+
Stray blank line?
It's mentioned in the commit log.
"Also restore one missing blank line between entries." Pattern is 2 blank lines btw entries.
Quoted 6 lines
Quoted 5 lines
What:
/sys/bus/cxl/devices/regionZ/extended_linear_cache_size
Date: October, 2025
KernelVersion: v6.19
Dave Jiang
AppliedQuoted 18 lines · Alison Schofield
Four entries in sysfs-bus-cxl use braced globs to document groups of attributes. Where the glob factors out a common prefix, as in cap_{pmem,ram,type2,type3}, no individual attribute name appears in the file at all and none can be found by grep or
get_abi.pysearch. In every case the glob also keysget_abi.pyvalidate on the glob string, so duplicates against separately documented attributes go undetected.Replace the globs with consecutive What: lines for each attribute. These lines continue to share the existing metadata and description and follow the format used in sysfs-driver-ufs and sysfs-bus-iio.
Also restore one missing blank line between entries.
Verify with:
python3tools/docs/get_abi.py-DDocumentation/ABI/testingvalidate python3tools/docs/get_abi.pysearchcap_pmem
python3tools/docs/get_abi.pysearchcreate_ram_region
Quoted 4 lines
validate reports no sysfs-bus-cxl warning, and both searches now return the stanza where they returned nothing before.
Signed-off-by Alison Schofield <[email protected]>
Applied to cxl/nextd7066cfc4187
Quoted 71 lines
---
This caught my eye when reading DavidLohr's Back-Invalidate series that adds
cap_bito the cap_{pmem,ram,type2,type3} glob and then references it. I couldn't find it, not w grep and not w 'get_abi.pysearch'. None of the existing cap_* names can be found. This patch is independent of that series and happy to spin this to includecap_biif needed.This intentionally does not address
get_abi.py undefined, which still fails to match decoderX.Y attributes due to a bug in the ABI tooling. That will be fixed separately in linux-doc.Documentation/ABI/testing/sysfs-bus-cxl | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-)Documentation/ABI/testing/sysfs-bus-cxl +11
-4@@ -201,7 +201,8 @@ Description: capability. -What: /sys/bus/cxl/devices/{port,endpoint}X/parent_dport +What: /sys/bus/cxl/devices/portX/parent_dport +What: /sys/bus/cxl/devices/endpointX/parent_dport Date: January, 2023 KernelVersion: v6.3 Contact: [email protected]@@ -258,7 +259,8 @@ Description: instance id of a given decoder resource. -What: /sys/bus/cxl/devices/decoderX.Y/{start,size} +What: /sys/bus/cxl/devices/decoderX.Y/start +What: /sys/bus/cxl/devices/decoderX.Y/size Date: June, 2021 KernelVersion: v5.14 Contact: [email protected]@@ -297,7 +299,10 @@ Description: Each entry in the list is a dport id. -What: /sys/bus/cxl/devices/decoderX.Y/cap_{pmem,ram,type2,type3} +What: /sys/bus/cxl/devices/decoderX.Y/cap_pmem +What: /sys/bus/cxl/devices/decoderX.Y/cap_ram +What: /sys/bus/cxl/devices/decoderX.Y/cap_type2 +What: /sys/bus/cxl/devices/decoderX.Y/cap_type3 Date: June, 2021 KernelVersion: v5.14 Contact: [email protected]@@ -410,7 +415,8 @@ Description: interleave_granularity). -What: /sys/bus/cxl/devices/decoderX.Y/create_{pmem,ram}_region +What: /sys/bus/cxl/devices/decoderX.Y/create_pmem_region +What: /sys/bus/cxl/devices/decoderX.Y/create_ram_region Date: May, 2022, January, 2023 KernelVersion: v6.0 (pmem), v6.3 (ram) Contact: [email protected]@@ -500,6 +506,7 @@ Description: cache is present, the size indicates extended linear cache size plus the CXL region size. + What: /sys/bus/cxl/devices/regionZ/extended_linear_cache_size Date: October, 2025 KernelVersion: v6.19