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

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 <[email protected]>

Seems reasonable. One comment below.

Reviewed-by: Dave Jiang <[email protected]>

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

Stray blank line?

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