Re: [PATCH v3 06/17] cxl: docs/platform/example-configs documentation

Dave Jiang
2025-05-13T00:06:58Z

On 5/12/25 9:21 AM, Gregory Price wrote:
> Add example ACPI Table configurations for different sample platforms.
>
> Signed-off-by: Gregory Price <gourry@gourry.net>

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

> ---
> Documentation/driver-api/cxl/index.rst | 1 +
> .../cxl/platform/example-configs.rst | 13 +
> .../example-configurations/flexible.rst | 296 ++++++++++++++++++
> .../example-configurations/hb-interleave.rst | 107 +++++++
> .../multi-dev-per-hb.rst | 90 ++++++
> .../example-configurations/one-dev-per-hb.rst | 136 ++++++++
> 6 files changed, 643 insertions(+)
> create mode 100644 Documentation/driver-api/cxl/platform/example-configs.rst
> create mode 100644 Documentation/driver-api/cxl/platform/example-configurations/flexible.rst
> create mode 100644 Documentation/driver-api/cxl/platform/example-configurations/hb-interleave.rst
> create mode 100644 Documentation/driver-api/cxl/platform/example-configurations/multi-dev-per-hb.rst
> create mode 100644 Documentation/driver-api/cxl/platform/example-configurations/one-dev-per-hb.rst
>
> diff --git a/Documentation/driver-api/cxl/index.rst b/Documentation/driver-api/cxl/index.rst
> index 336322dc35a0..6a5fb7e00c52 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/example-configs
>
> .. toctree::
> :maxdepth: 1
> diff --git a/Documentation/driver-api/cxl/platform/example-configs.rst b/Documentation/driver-api/cxl/platform/example-configs.rst
> new file mode 100644
> index 000000000000..90a10d7473c6
> --- /dev/null
> +++ b/Documentation/driver-api/cxl/platform/example-configs.rst
> @@ -0,0 +1,13 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +Example Platform Configurations
> +###############################
> +
> +.. toctree::
> + :maxdepth: 1
> + :caption: Contents
> +
> + example-configurations/one-dev-per-hb.rst
> + example-configurations/multi-dev-per-hb.rst
> + example-configurations/hb-interleave.rst
> + example-configurations/flexible.rst
> diff --git a/Documentation/driver-api/cxl/platform/example-configurations/flexible.rst b/Documentation/driver-api/cxl/platform/example-configurations/flexible.rst
> new file mode 100644
> index 000000000000..e39daba65fa0
> --- /dev/null
> +++ b/Documentation/driver-api/cxl/platform/example-configurations/flexible.rst
> @@ -0,0 +1,296 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=====================
> +Flexible Presentation
> +=====================
> +This system has a single socket with two CXL host bridges. Each host bridge
> +has two CXL memory expanders with a 4GB of memory (32GB total).
> +
> +On this system, the platform designer wanted to provide the user flexibility
> +to configure the memory devices in various interleave or NUMA node
> +configurations. So they provided every combination.
> +
> +Things to note:
> +
> +* Cross-Bridge interleave is described in one CFMWS that covers all capacity.
> +* One CFMWS is also described per-host bridge.
> +* One CFMWS is also described per-device.
> +* This SRAT describes one node for each of the above CFMWS.
> +* The HMAT describes performance for each node in the SRAT.
> +
> +CEDT ::
> +
> + Subtable Type : 00 [CXL Host Bridge Structure]
> + Reserved : 00
> + Length : 0020
> + Associated host bridge : 00000007
> + Specification version : 00000001
> + Reserved : 00000000
> + Register base : 0000010370400000
> + Register length : 0000000000010000
> +
> + Subtable Type : 00 [CXL Host Bridge Structure]
> + Reserved : 00
> + Length : 0020
> + Associated host bridge : 00000006
> + Specification version : 00000001
> + Reserved : 00000000
> + Register base : 0000010380800000
> + Register length : 0000000000010000
> +
> + Subtable Type : 01 [CXL Fixed Memory Window Structure]
> + Reserved : 00
> + Length : 002C
> + Reserved : 00000000
> + Window base address : 0000001000000000
> + Window size : 0000000400000000
> + Interleave Members (2^n) : 01
> + Interleave Arithmetic : 00
> + Reserved : 0000
> + Granularity : 00000000
> + Restrictions : 0006
> + QtgId : 0001
> + First Target : 00000007
> + Second Target : 00000006
> +
> + Subtable Type : 01 [CXL Fixed Memory Window Structure]
> + Reserved : 00
> + Length : 002C
> + Reserved : 00000000
> + Window base address : 0000002000000000
> + Window size : 0000000200000000
> + Interleave Members (2^n) : 00
> + Interleave Arithmetic : 00
> + Reserved : 0000
> + Granularity : 00000000
> + Restrictions : 0006
> + QtgId : 0001
> + First Target : 00000007
> +
> + Subtable Type : 01 [CXL Fixed Memory Window Structure]
> + Reserved : 00
> + Length : 002C
> + Reserved : 00000000
> + Window base address : 0000002200000000
> + Window size : 0000000200000000
> + Interleave Members (2^n) : 00
> + Interleave Arithmetic : 00
> + Reserved : 0000
> + Granularity : 00000000
> + Restrictions : 0006
> + QtgId : 0001
> + First Target : 00000006
> +
> + Subtable Type : 01 [CXL Fixed Memory Window Structure]
> + Reserved : 00
> + Length : 002C
> + Reserved : 00000000
> + Window base address : 0000003000000000
> + Window size : 0000000100000000
> + Interleave Members (2^n) : 00
> + Interleave Arithmetic : 00
> + Reserved : 0000
> + Granularity : 00000000
> + Restrictions : 0006
> + QtgId : 0001
> + First Target : 00000007
> +
> + Subtable Type : 01 [CXL Fixed Memory Window Structure]
> + Reserved : 00
> + Length : 002C
> + Reserved : 00000000
> + Window base address : 0000003100000000
> + Window size : 0000000100000000
> + Interleave Members (2^n) : 00
> + Interleave Arithmetic : 00
> + Reserved : 0000
> + Granularity : 00000000
> + Restrictions : 0006
> + QtgId : 0001
> + First Target : 00000007
> +
> + Subtable Type : 01 [CXL Fixed Memory Window Structure]
> + Reserved : 00
> + Length : 002C
> + Reserved : 00000000
> + Window base address : 0000003200000000
> + Window size : 0000000100000000
> + Interleave Members (2^n) : 00
> + Interleave Arithmetic : 00
> + Reserved : 0000
> + Granularity : 00000000
> + Restrictions : 0006
> + QtgId : 0001
> + First Target : 00000006
> +
> + Subtable Type : 01 [CXL Fixed Memory Window Structure]
> + Reserved : 00
> + Length : 002C
> + Reserved : 00000000
> + Window base address : 0000003300000000
> + Window size : 0000000100000000
> + Interleave Members (2^n) : 00
> + Interleave Arithmetic : 00
> + Reserved : 0000
> + Granularity : 00000000
> + Restrictions : 0006
> + QtgId : 0001
> + First Target : 00000006
> +
> +SRAT ::
> +
> + Subtable Type : 01 [Memory Affinity]
> + Length : 28
> + Proximity Domain : 00000001
> + Reserved1 : 0000
> + Base Address : 0000001000000000
> + Address Length : 0000000400000000
> + Reserved2 : 00000000
> + Flags (decoded below) : 0000000B
> + Enabled : 1
> + Hot Pluggable : 1
> + Non-Volatile : 0
> +
> + Subtable Type : 01 [Memory Affinity]
> + Length : 28
> + Proximity Domain : 00000002
> + Reserved1 : 0000
> + Base Address : 0000002000000000
> + Address Length : 0000000200000000
> + Reserved2 : 00000000
> + Flags (decoded below) : 0000000B
> + Enabled : 1
> + Hot Pluggable : 1
> + Non-Volatile : 0
> +
> + Subtable Type : 01 [Memory Affinity]
> + Length : 28
> + Proximity Domain : 00000003
> + Reserved1 : 0000
> + Base Address : 0000002200000000
> + Address Length : 0000000200000000
> + Reserved2 : 00000000
> + Flags (decoded below) : 0000000B
> + Enabled : 1
> + Hot Pluggable : 1
> + Non-Volatile : 0
> +
> + Subtable Type : 01 [Memory Affinity]
> + Length : 28
> + Proximity Domain : 00000004
> + Reserved1 : 0000
> + Base Address : 0000003000000000
> + Address Length : 0000000100000000
> + Reserved2 : 00000000
> + Flags (decoded below) : 0000000B
> + Enabled : 1
> + Hot Pluggable : 1
> + Non-Volatile : 0
> +
> + Subtable Type : 01 [Memory Affinity]
> + Length : 28
> + Proximity Domain : 00000005
> + Reserved1 : 0000
> + Base Address : 0000003100000000
> + Address Length : 0000000100000000
> + Reserved2 : 00000000
> + Flags (decoded below) : 0000000B
> + Enabled : 1
> + Hot Pluggable : 1
> + Non-Volatile : 0
> +
> + Subtable Type : 01 [Memory Affinity]
> + Length : 28
> + Proximity Domain : 00000006
> + Reserved1 : 0000
> + Base Address : 0000003200000000
> + Address Length : 0000000100000000
> + Reserved2 : 00000000
> + Flags (decoded below) : 0000000B
> + Enabled : 1
> + Hot Pluggable : 1
> + Non-Volatile : 0
> +
> + Subtable Type : 01 [Memory Affinity]
> + Length : 28
> + Proximity Domain : 00000007
> + Reserved1 : 0000
> + Base Address : 0000003300000000
> + Address Length : 0000000100000000
> + Reserved2 : 00000000
> + Flags (decoded below) : 0000000B
> + Enabled : 1
> + Hot Pluggable : 1
> + Non-Volatile : 0
> +
> +HMAT ::
> +
> + Structure Type : 0001 [SLLBI]
> + Data Type : 00 [Latency]
> + Target Proximity Domain List : 00000000
> + Target Proximity Domain List : 00000001
> + Target Proximity Domain List : 00000002
> + Target Proximity Domain List : 00000003
> + Target Proximity Domain List : 00000004
> + Target Proximity Domain List : 00000005
> + Target Proximity Domain List : 00000006
> + Target Proximity Domain List : 00000007
> + Entry : 0080
> + Entry : 0100
> + Entry : 0100
> + Entry : 0100
> + Entry : 0100
> + Entry : 0100
> + Entry : 0100
> + Entry : 0100
> +
> + Structure Type : 0001 [SLLBI]
> + Data Type : 03 [Bandwidth]
> + Target Proximity Domain List : 00000000
> + Target Proximity Domain List : 00000001
> + Target Proximity Domain List : 00000002
> + Target Proximity Domain List : 00000003
> + Target Proximity Domain List : 00000004
> + Target Proximity Domain List : 00000005
> + Target Proximity Domain List : 00000006
> + Target Proximity Domain List : 00000007
> + Entry : 1200
> + Entry : 0400
> + Entry : 0200
> + Entry : 0200
> + Entry : 0100
> + Entry : 0100
> + Entry : 0100
> + Entry : 0100
> +
> +SLIT ::
> +
> + Signature : "SLIT" [System Locality Information Table]
> + Localities : 0000000000000003
> + Locality 0 : 10 20 20 20 20 20 20 20
> + Locality 1 : FF 0A FF FF FF FF FF FF
> + Locality 2 : FF FF 0A FF FF FF FF FF
> + Locality 3 : FF FF FF 0A FF FF FF FF
> + Locality 4 : FF FF FF FF 0A FF FF FF
> + Locality 5 : FF FF FF FF FF 0A FF FF
> + Locality 6 : FF FF FF FF FF FF 0A FF
> + Locality 7 : FF FF FF FF FF FF FF 0A
> +
> +DSDT ::
> +
> + Scope (_SB)
> + {
> + Device (S0D0)
> + {
> + Name (_HID, "ACPI0016" /* Compute Express Link Host Bridge */) // _HID: Hardware ID
> + ...
> + Name (_UID, 0x07) // _UID: Unique ID
> + }
> + ...
> + Device (S0D5)
> + {
> + Name (_HID, "ACPI0016" /* Compute Express Link Host Bridge */) // _HID: Hardware ID
> + ...
> + Name (_UID, 0x06) // _UID: Unique ID
> + }
> + }
> diff --git a/Documentation/driver-api/cxl/platform/example-configurations/hb-interleave.rst b/Documentation/driver-api/cxl/platform/example-configurations/hb-interleave.rst
> new file mode 100644
> index 000000000000..ce07e6162f26
> --- /dev/null
> +++ b/Documentation/driver-api/cxl/platform/example-configurations/hb-interleave.rst
> @@ -0,0 +1,107 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +============================
> +Cross-Host-Bridge Interleave
> +============================
> +This system has a single socket with two CXL host bridges. Each host bridge
> +has a single CXL memory expander with a 4GB of memory.
> +
> +Things to note:
> +
> +* Cross-Bridge interleave is described.
> +* The expanders are described by a single CFMWS.
> +* This SRAT describes one node for both host bridges.
> +* The HMAT describes a single node's performance.
> +
> +CEDT ::
> +
> + Subtable Type : 00 [CXL Host Bridge Structure]
> + Reserved : 00
> + Length : 0020
> + Associated host bridge : 00000007
> + Specification version : 00000001
> + Reserved : 00000000
> + Register base : 0000010370400000
> + Register length : 0000000000010000
> +
> + Subtable Type : 00 [CXL Host Bridge Structure]
> + Reserved : 00
> + Length : 0020
> + Associated host bridge : 00000006
> + Specification version : 00000001
> + Reserved : 00000000
> + Register base : 0000010380800000
> + Register length : 0000000000010000
> +
> + Subtable Type : 01 [CXL Fixed Memory Window Structure]
> + Reserved : 00
> + Length : 002C
> + Reserved : 00000000
> + Window base address : 0000001000000000
> + Window size : 0000000200000000
> + Interleave Members (2^n) : 01
> + Interleave Arithmetic : 00
> + Reserved : 0000
> + Granularity : 00000000
> + Restrictions : 0006
> + QtgId : 0001
> + First Target : 00000007
> + Second Target : 00000006
> +
> +SRAT ::
> +
> + Subtable Type : 01 [Memory Affinity]
> + Length : 28
> + Proximity Domain : 00000001
> + Reserved1 : 0000
> + Base Address : 0000001000000000
> + Address Length : 0000000200000000
> + Reserved2 : 00000000
> + Flags (decoded below) : 0000000B
> + Enabled : 1
> + Hot Pluggable : 1
> + Non-Volatile : 0
> +
> +HMAT ::
> +
> + Structure Type : 0001 [SLLBI]
> + Data Type : 00 [Latency]
> + Target Proximity Domain List : 00000000
> + Target Proximity Domain List : 00000001
> + Target Proximity Domain List : 00000002
> + Entry : 0080
> + Entry : 0100
> +
> + Structure Type : 0001 [SLLBI]
> + Data Type : 03 [Bandwidth]
> + Target Proximity Domain List : 00000000
> + Target Proximity Domain List : 00000001
> + Target Proximity Domain List : 00000002
> + Entry : 1200
> + Entry : 0400
> +
> +SLIT ::
> +
> + Signature : "SLIT" [System Locality Information Table]
> + Localities : 0000000000000003
> + Locality 0 : 10 20
> + Locality 1 : FF 0A
> +
> +DSDT ::
> +
> + Scope (_SB)
> + {
> + Device (S0D0)
> + {
> + Name (_HID, "ACPI0016" /* Compute Express Link Host Bridge */) // _HID: Hardware ID
> + ...
> + Name (_UID, 0x07) // _UID: Unique ID
> + }
> + ...
> + Device (S0D5)
> + {
> + Name (_HID, "ACPI0016" /* Compute Express Link Host Bridge */) // _HID: Hardware ID
> + ...
> + Name (_UID, 0x06) // _UID: Unique ID
> + }
> + }
> diff --git a/Documentation/driver-api/cxl/platform/example-configurations/multi-dev-per-hb.rst b/Documentation/driver-api/cxl/platform/example-configurations/multi-dev-per-hb.rst
> new file mode 100644
> index 000000000000..6adf7c639490
> --- /dev/null
> +++ b/Documentation/driver-api/cxl/platform/example-configurations/multi-dev-per-hb.rst
> @@ -0,0 +1,90 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +================================
> +Multiple Devices per Host Bridge
> +================================
> +
> +In this example system we will have a single socket and one CXL host bridge.
> +There are two CXL memory expanders with 4GB attached to the host bridge.
> +
> +Things to note:
> +
> +* Intra-Bridge interleave is not described here.
> +* The expanders are described by a single CEDT/CFMWS.
> +* This CEDT/SRAT describes one node for both devices.
> +* There is only one proximity domain the HMAT for both devices.
> +
> +CEDT ::
> +
> + Subtable Type : 00 [CXL Host Bridge Structure]
> + Reserved : 00
> + Length : 0020
> + Associated host bridge : 00000007
> + Specification version : 00000001
> + Reserved : 00000000
> + Register base : 0000010370400000
> + Register length : 0000000000010000
> +
> + Subtable Type : 01 [CXL Fixed Memory Window Structure]
> + Reserved : 00
> + Length : 002C
> + Reserved : 00000000
> + Window base address : 0000001000000000
> + Window size : 0000000200000000
> + Interleave Members (2^n) : 00
> + Interleave Arithmetic : 00
> + Reserved : 0000
> + Granularity : 00000000
> + Restrictions : 0006
> + QtgId : 0001
> + First Target : 00000007
> +
> +SRAT ::
> +
> + Subtable Type : 01 [Memory Affinity]
> + Length : 28
> + Proximity Domain : 00000001
> + Reserved1 : 0000
> + Base Address : 0000001000000000
> + Address Length : 0000000200000000
> + Reserved2 : 00000000
> + Flags (decoded below) : 0000000B
> + Enabled : 1
> + Hot Pluggable : 1
> + Non-Volatile : 0
> +
> +HMAT ::
> +
> + Structure Type : 0001 [SLLBI]
> + Data Type : 00 [Latency]
> + Target Proximity Domain List : 00000000
> + Target Proximity Domain List : 00000001
> + Entry : 0080
> + Entry : 0100
> +
> + Structure Type : 0001 [SLLBI]
> + Data Type : 03 [Bandwidth]
> + Target Proximity Domain List : 00000000
> + Target Proximity Domain List : 00000001
> + Entry : 1200
> + Entry : 0200
> +
> +SLIT ::
> +
> + Signature : "SLIT" [System Locality Information Table]
> + Localities : 0000000000000003
> + Locality 0 : 10 20
> + Locality 1 : FF 0A
> +
> +DSDT ::
> +
> + Scope (_SB)
> + {
> + Device (S0D0)
> + {
> + Name (_HID, "ACPI0016" /* Compute Express Link Host Bridge */) // _HID: Hardware ID
> + ...
> + Name (_UID, 0x07) // _UID: Unique ID
> + }
> + ...
> + }
> diff --git a/Documentation/driver-api/cxl/platform/example-configurations/one-dev-per-hb.rst b/Documentation/driver-api/cxl/platform/example-configurations/one-dev-per-hb.rst
> new file mode 100644
> index 000000000000..b89ba3cab98f
> --- /dev/null
> +++ b/Documentation/driver-api/cxl/platform/example-configurations/one-dev-per-hb.rst
> @@ -0,0 +1,136 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +==========================
> +One Device per Host Bridge
> +==========================
> +
> +This system has a single socket with two CXL host bridges. Each host bridge
> +has a single CXL memory expander with a 4GB of memory.
> +
> +Things to note:
> +
> +* Cross-Bridge interleave is not being used.
> +* The expanders are in two separate but adjascent memory regions.
> +* This CEDT/SRAT describes one node per device
> +* The expanders have the same performance and will be in the same memory tier.
> +
> +CEDT ::
> +
> + Subtable Type : 00 [CXL Host Bridge Structure]
> + Reserved : 00
> + Length : 0020
> + Associated host bridge : 00000007
> + Specification version : 00000001
> + Reserved : 00000000
> + Register base : 0000010370400000
> + Register length : 0000000000010000
> +
> + Subtable Type : 00 [CXL Host Bridge Structure]
> + Reserved : 00
> + Length : 0020
> + Associated host bridge : 00000006
> + Specification version : 00000001
> + Reserved : 00000000
> + Register base : 0000010380800000
> + Register length : 0000000000010000
> +
> + Subtable Type : 01 [CXL Fixed Memory Window Structure]
> + Reserved : 00
> + Length : 002C
> + Reserved : 00000000
> + Window base address : 0000001000000000
> + Window size : 0000000100000000
> + Interleave Members (2^n) : 00
> + Interleave Arithmetic : 00
> + Reserved : 0000
> + Granularity : 00000000
> + Restrictions : 0006
> + QtgId : 0001
> + First Target : 00000007
> +
> + Subtable Type : 01 [CXL Fixed Memory Window Structure]
> + Reserved : 00
> + Length : 002C
> + Reserved : 00000000
> + Window base address : 0000001100000000
> + Window size : 0000000100000000
> + Interleave Members (2^n) : 00
> + Interleave Arithmetic : 00
> + Reserved : 0000
> + Granularity : 00000000
> + Restrictions : 0006
> + QtgId : 0001
> + First Target : 00000006
> +
> +SRAT ::
> +
> + Subtable Type : 01 [Memory Affinity]
> + Length : 28
> + Proximity Domain : 00000001
> + Reserved1 : 0000
> + Base Address : 0000001000000000
> + Address Length : 0000000100000000
> + Reserved2 : 00000000
> + Flags (decoded below) : 0000000B
> + Enabled : 1
> + Hot Pluggable : 1
> + Non-Volatile : 0
> +
> + Subtable Type : 01 [Memory Affinity]
> + Length : 28
> + Proximity Domain : 00000002
> + Reserved1 : 0000
> + Base Address : 0000001100000000
> + Address Length : 0000000100000000
> + Reserved2 : 00000000
> + Flags (decoded below) : 0000000B
> + Enabled : 1
> + Hot Pluggable : 1
> + Non-Volatile : 0
> +
> +HMAT ::
> +
> + Structure Type : 0001 [SLLBI]
> + Data Type : 00 [Latency]
> + Target Proximity Domain List : 00000000
> + Target Proximity Domain List : 00000001
> + Target Proximity Domain List : 00000002
> + Entry : 0080
> + Entry : 0100
> + Entry : 0100
> +
> + Structure Type : 0001 [SLLBI]
> + Data Type : 03 [Bandwidth]
> + Target Proximity Domain List : 00000000
> + Target Proximity Domain List : 00000001
> + Target Proximity Domain List : 00000002
> + Entry : 1200
> + Entry : 0200
> + Entry : 0200
> +
> +SLIT ::
> +
> + Signature : "SLIT" [System Locality Information Table]
> + Localities : 0000000000000003
> + Locality 0 : 10 20 20
> + Locality 1 : FF 0A FF
> + Locality 2 : FF FF 0A
> +
> +DSDT ::
> +
> + Scope (_SB)
> + {
> + Device (S0D0)
> + {
> + Name (_HID, "ACPI0016" /* Compute Express Link Host Bridge */) // _HID: Hardware ID
> + ...
> + Name (_UID, 0x07) // _UID: Unique ID
> + }
> + ...
> + Device (S0D5)
> + {
> + Name (_HID, "ACPI0016" /* Compute Express Link Host Bridge */) // _HID: Hardware ID
> + ...
> + Name (_UID, 0x06) // _UID: Unique ID
> + }
> + }