Re: [PATCH 1/4] cxl: docs/platform/cdat reference documentation

[Gregory Price <gourry@gourry.net>]

On Tue, May 13, 2025 at 05:31:30PM -0700, Dave Jiang wrote:
> Add documentation for CDAT sub-tables for CXL usages.
> 

Mostly wording nits, but i recommend putting allt he subtables in
cdat.rst directly and adding a terms list at the top so you can
reference them cleanly on the same page without redefining them
everywhere.  See below.

> Signed-off-by: Dave Jiang <dave.jiang@intel.com>
> ---
>  Documentation/driver-api/cxl/index.rst        |  1 +
>  .../driver-api/cxl/platform/cdat.rst          | 24 ++++++++++
>  .../driver-api/cxl/platform/cdat/dslbis.rst   | 33 ++++++++++++++
>  .../driver-api/cxl/platform/cdat/dsmas.rst    | 23 ++++++++++
>  .../driver-api/cxl/platform/cdat/sslbis.rst   | 45 +++++++++++++++++++
>  5 files changed, 126 insertions(+)
>  create mode 100644 Documentation/driver-api/cxl/platform/cdat.rst
>  create mode 100644 Documentation/driver-api/cxl/platform/cdat/dslbis.rst
>  create mode 100644 Documentation/driver-api/cxl/platform/cdat/dsmas.rst
>  create mode 100644 Documentation/driver-api/cxl/platform/cdat/sslbis.rst
> 
> diff --git a/Documentation/driver-api/cxl/index.rst b/Documentation/driver-api/cxl/index.rst
> index 366faf851fc7..9e1414ad3357 100644
> --- a/Documentation/driver-api/cxl/index.rst
> +++ b/Documentation/driver-api/cxl/index.rst
> @@ -27,6 +27,7 @@ that have impacts on each other.  The docs here break up configurations steps.
>  
>     platform/bios-and-efi
>     platform/acpi
> +   platform/cdat
>     platform/example-configs
>  
>  .. toctree::
> diff --git a/Documentation/driver-api/cxl/platform/cdat.rst b/Documentation/driver-api/cxl/platform/cdat.rst
> new file mode 100644
> index 000000000000..3e0ce7099db3
> --- /dev/null
> +++ b/Documentation/driver-api/cxl/platform/cdat.rst
> @@ -0,0 +1,24 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===========
> +CDAT Tables
> +===========

"Coherent Device Attribute Table Tables" :]

I would name this 

======================================
Coherent Device Attribute Table (CDAT)
======================================

> +
> +The Coherent Device Attribute Table (CDAT) is created to provide a standard way to
> +expose the properties of a device such as an CXL accelerator or switch. The table
> +formatting is similar to ACPI tables. The tables are created to provide performance
> +calculation of a hot-plugged device where ACPI HMAT+SRAT tables are not able to
> +enumerate the performance by the BIOS ahead of time.

I may suggest something like...

The CDAT provides functional and performance attributes of devices such
as CXL accelerators, switches, or endpoints.  The table formatting is
similar to ACPI tables. CDAT data may be parsed by BIOS at boot or may
be enumerated at runtime (after device hotplug, for example).

> +
> +The following CDAT tables contain *static* configuration and performance data about CXL devices.
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   cdat/dsmas.rst
> +   cdat/dslbis.rst
> +   cdat/sslbis.rst
> +
> +The Linux CXL driver uses these tables in addition to attributes of the CXL links and
                                                      ^^^^^^^^^^^^^
						      provided by what?
> +Generic Target performance data provided by HMAT+SRAT to create the whole path performance
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   The is provided by SRAT right?
> +for a CXL device.

Maybe simplified to:

The CXL driver uses a combination of CDAT, HMAT, SRAT and other data to
generate "whole path performance" data for a CXL device.

> diff --git a/Documentation/driver-api/cxl/platform/cdat/dslbis.rst b/Documentation/driver-api/cxl/platform/cdat/dslbis.rst
> new file mode 100644
> index 000000000000..91ae426b2e8b
> --- /dev/null
> +++ b/Documentation/driver-api/cxl/platform/cdat/dslbis.rst
> @@ -0,0 +1,33 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +==================================================================
> +DSLBIS - Device Scoped Latency and Bandwidth Information Structure
> +==================================================================
> +
> +The Device Scoped Latency and Bandwidth Information Structure contains latency
> +and bandwidth information based on DSMADHandle matching.
                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
			     What does a DSMADHandle represent?
> +
> +This table is used by Linux in conjunction with Device scoped Memory Affinity
> +Structure to determine the performance attributes of a CXL device.

swap the order of the last two paragraphs.  Add (DSMAS) after "Device
Scoped Memory Affinity Structure", introduce what a DSMADHandle is and
what it represents before you reference it.

> +
> +Example ::
> +
> +   Structure Type : 01 [DSLBIS]
> +         Reserved : 00
> +           Length : 18                     <- 24d, size of structure
> +           Handle : 0001                   <- DSMAS handle
> +            Flags : 00                     <- Matches flag field for HMAT SLLBIS
> +        Data Type : 00                     <- Latency
> + Entry Basee Unit : 0000000000001000       <- Entry Base Unit field in HMAT SSLBIS
> +            Entry : 010000000000           <- First byte used here, CXL LTC
> +         Reserved : 0000
> +
> +   Structure Type : 01 [DSLBIS]
> +         Reserved : 00
> +           Length : 18                     <- 24d, size of structure
> +           Handle : 0001                   <- DSMAS handle
> +            Flags : 00                     <- Matches flag field for HMAT SLLBIS
> +        Data Type : 03                     <- Bandwidth
> + Entry Basee Unit : 0000000000001000       <- Entry Base Unit field in HMAT SSLBIS
> +            Entry : 020000000000           <- First byte used here, CXL BW
> +         Reserved : 0000
> diff --git a/Documentation/driver-api/cxl/platform/cdat/dsmas.rst b/Documentation/driver-api/cxl/platform/cdat/dsmas.rst
> new file mode 100644
> index 000000000000..8c32ddb3381c
> --- /dev/null
> +++ b/Documentation/driver-api/cxl/platform/cdat/dsmas.rst
> @@ -0,0 +1,23 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===============================================
> +DSMAS - Device Scoped Memory Affinity Structure
> +===============================================

Device Scoped Memory Affinity Structure (DSMAS)

> +
> +The Device Scoped Memory Affinity Structure contains information such as
       ^^^^^^        DSMAS               ^^^^^
       Since you define it in the header, you can use the abbreviation
 
> +DSMADHandle, the DPA Base, and DPA Length.
> +

It's probably better to put all these subtables in a single document
(cdat.rst) and add a terms list at the top (such as DSMADHandle)

> +This table is used by Linux in conjunction with the Device Scoped Latency and
> +Bandwidth Information Structure (DSLBIS) to determine the performance
> +attributes of the CXL device itself.
> +
> +Example ::
> +
> + Structure Type : 00 [DSMAS]
> +       Reserved : 00
> +         Length : 0018              <- 24d, size of structure
> +    DSMADHandle : 01
> +          Flags : 00
> +       Reserved : 0000
> +       DPA Base : 0000000040000000  <- 1GiB base
> +     DPA Length : 0000000080000000  <- 2GiB size
> diff --git a/Documentation/driver-api/cxl/platform/cdat/sslbis.rst b/Documentation/driver-api/cxl/platform/cdat/sslbis.rst
> new file mode 100644
> index 000000000000..e299575493fa
> --- /dev/null
> +++ b/Documentation/driver-api/cxl/platform/cdat/sslbis.rst
> @@ -0,0 +1,45 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +==================================================================
> +SSLBIS - Switch Scoped Latency and Bandwidth Information Structure
> +==================================================================

Switch Scoped Latency and Bandwidth Information Structure (SSLBIS)

> +
> +The Switch Scoped Latency Bandwidth Information Structure contains information
       ^^^^^^^^^^^^^^^^ SSLBIS ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +about the latency and bandwidth of a switch.
> +
> +The table is used by Linux to compute the performance coordinates of a CXL path
> +from the device to the root port where a switch is part of the path.
> +
> +Example ::
> +
> +  Structure Type : 05 [SSLBIS]
> +        Reserved : 00
> +          Length : 20                           <- 32d, length of record, including SSLB entries
> +       Data Type : 00                           <- Latency
> +        Reserved : 000000
> + Entry Base Unit : 00000000000000001000         <- Matches Entry Base Unit in HMAT SSLBIS
> +
> +                                                <- SSLB Entry 0
> +       Port X ID : 0100                         <- First port, 0100h represents an upstream port
> +       Port Y ID : 0000                         <- Second port, downstream port 0
> +         Latency : 0100                         <- Port latency
> +        Reserved : 0000
> +                                                <- SSLB Entry 1
> +       Port X ID : 0100
> +       Port Y ID : 0001
> +         Latency : 0100
> +        Reserved : 0000
> +
> +
> +  Structure Type : 05 [SSLBIS]
> +        Reserved : 00
> +          Length : 18                           <- 24d, length of record, including SSLB entry
> +       Data Type : 03                           <- Bandwidth
> +        Reserved : 000000
> + Entry Base Unit : 00000000000000001000         <- Matches Entry Base Unit in HMAT SSLBIS
> +
> +                                                <- SSLB Entry 0
> +       Port X ID : 0100                         <- First port, 0100h represents an upstream port
> +       Port Y ID : FFFF                         <- Second port, FFFFh indicates any port
> +       Bandwidth : 1200                         <- Port bandwidth
> +        Reserved : 0000
> -- 
> 2.49.0
>