Skip to contentSkip to conversation

cxl/Documentation: Spell out globbed sysfs attribute names

PATCH Applied Alison Schofield 2 participants 4 messages Aug 4 – Aug 6

lore
Share & tools
lore
#0 lore raw

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
index 16a9b3d2e2c0..7352dbd70bc7 100644
@@ -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
Reviewed-by on v1 1/1
#1 lore raw
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.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

Quoted 4 lines

validate reports no sysfs-bus-cxl warning, and both searches now return the stanza where they returned nothing before.

Seems reasonable. One comment below.

Quoted 63 lines

---

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 +10 -4
index 16a9b3d2e2c0..7352dbd70bc7 100644
@@ -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 -0
 What:		/sys/bus/cxl/devices/regionZ/extended_linear_cache_size
 Date:		October, 2025
 KernelVersion:	v6.19
#2 lore raw
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.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

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.

Seems reasonable. One comment below.

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

Applied
#3 lore raw
In reply to Alison Schofield
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.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

Quoted 4 lines

validate reports no sysfs-bus-cxl warning, and both searches now return the stanza where they returned nothing before.

Applied to cxl/next
d7066cfc4187

Quoted 71 lines

---

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
index 16a9b3d2e2c0..7352dbd70bc7 100644
@@ -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