[PATCH] cxl/Documentation: Spell out globbed sysfs attribute names

[PATCH] cxl/Documentation: Spell out globbed sysfs attribute names

[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

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

Signed-off-by: Alison Schofield <alison.schofield@intel.com>
---

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(-)

diff --git a/Documentation/ABI/testing/sysfs-bus-cxl b/Documentation/ABI/testing/sysfs-bus-cxl
index 16a9b3d2e2c0..7352dbd70bc7 100644
--- a/Documentation/ABI/testing/sysfs-bus-cxl
+++ b/Documentation/ABI/testing/sysfs-bus-cxl
@@ -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:	linux-cxl@vger.kernel.org
@@ -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:	linux-cxl@vger.kernel.org
@@ -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:	linux-cxl@vger.kernel.org
@@ -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:	linux-cxl@vger.kernel.org
@@ -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

-- 
2.37.3

Re: [PATCH] cxl/Documentation: Spell out globbed sysfs attribute names

[Dave Jiang]

On 8/4/26 4:20 PM, Alison Schofield wrote:
> 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.
> 
> Signed-off-by: Alison Schofield <alison.schofield@intel.com>

Seems reasonable. One comment below.

Reviewed-by: Dave Jiang <dave.jiang@intel.com>

> ---
> 
> 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(-)
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-cxl b/Documentation/ABI/testing/sysfs-bus-cxl
> index 16a9b3d2e2c0..7352dbd70bc7 100644
> --- a/Documentation/ABI/testing/sysfs-bus-cxl
> +++ b/Documentation/ABI/testing/sysfs-bus-cxl
> @@ -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:	linux-cxl@vger.kernel.org
> @@ -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:	linux-cxl@vger.kernel.org
> @@ -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:	linux-cxl@vger.kernel.org
> @@ -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:	linux-cxl@vger.kernel.org
> @@ -500,6 +506,7 @@ Description:
>  		cache is present, the size indicates extended linear cache size
>  		plus the CXL region size.
>  
> +

Stray blank line?

>  What:		/sys/bus/cxl/devices/regionZ/extended_linear_cache_size
>  Date:		October, 2025
>  KernelVersion:	v6.19
> 

Re: [PATCH] cxl/Documentation: Spell out globbed sysfs attribute names

[Alison Schofield]

On Tue, Aug 04, 2026 at 04:24:17PM -0700, Dave Jiang wrote:
> 
> 
> On 8/4/26 4:20 PM, Alison Schofield wrote:
> > 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.
> > 
> > Signed-off-by: Alison Schofield <alison.schofield@intel.com>
> 
> Seems reasonable. One comment below.
> 
> Reviewed-by: Dave Jiang <dave.jiang@intel.com>
> 

You're faster than Sashiko ;)
snip

> > +
> 
> 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.

> 
> >  What:		/sys/bus/cxl/devices/regionZ/extended_linear_cache_size
> >  Date:		October, 2025
> >  KernelVersion:	v6.19
> > 
> 

Re: [PATCH] cxl/Documentation: Spell out globbed sysfs attribute names

[Dave Jiang]

On 8/4/26 4:20 PM, Alison Schofield wrote:
> 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.
> 
> Signed-off-by: Alison Schofield <alison.schofield@intel.com>

Applied to cxl/next
d7066cfc4187

> ---
> 
> 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(-)
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-cxl b/Documentation/ABI/testing/sysfs-bus-cxl
> index 16a9b3d2e2c0..7352dbd70bc7 100644
> --- a/Documentation/ABI/testing/sysfs-bus-cxl
> +++ b/Documentation/ABI/testing/sysfs-bus-cxl
> @@ -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:	linux-cxl@vger.kernel.org
> @@ -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:	linux-cxl@vger.kernel.org
> @@ -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:	linux-cxl@vger.kernel.org
> @@ -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:	linux-cxl@vger.kernel.org
> @@ -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
>