On 4/30/25 11:10 AM, Gregory Price wrote:
> Add some crosslinks between pages in the CXL docs - mostly to the
> ACPI tables.
>
> Signed-off-by: Gregory Price <gourry@xxxxxxxxxx>
> ---
> .../driver-api/cxl/devices/device-types.rst | 2 +-
> .../cxl/linux/access-coordinates.rst | 8 +++--
> .../driver-api/cxl/linux/cxl-driver.rst | 36 ++++++++++---------
> .../driver-api/cxl/linux/early-boot.rst | 30 +++++++++-------
> .../driver-api/cxl/platform/bios-and-efi.rst | 13 +++----
> .../example-configurations/flexible.rst | 10 +++---
> .../example-configurations/hb-interleave.rst | 10 +++---
> .../multi-dev-per-hb.rst | 10 +++---
> .../example-configurations/one-dev-per-hb.rst | 10 +++---
> 9 files changed, 71 insertions(+), 58 deletions(-)
>
> diff --git a/Documentation/driver-api/cxl/linux/access-coordinates.rst b/Documentation/driver-api/cxl/linux/access-coordinates.rst
> index b07950ea30c9..24db5b41716a 100644
> --- a/Documentation/driver-api/cxl/linux/access-coordinates.rst
> +++ b/Documentation/driver-api/cxl/linux/access-coordinates.rst
> @@ -24,7 +24,8 @@ asymmetry in properties does not happen and all paths to EPs are equal.
>
> There can be multiple switches under an RP. There can be multiple RPs under
> a CXL Host Bridge (HB). There can be multiple HBs under a CXL Fixed Memory
> -Window Structure (CFMWS).
> +Window Structure (CFMWS) in the
> +Documentation/driver-api/cxl/platform/acpi/acpi/cedt.rst.
>
> An example hierarchy:
>
> @@ -83,8 +84,9 @@ also the index for the resulting xarray.
>
> The next step is to take the min() of the per host bridge bandwidth and the
> bandwidth from the Generic Port (GP). The bandwidths for the GP is retrieved
are
> -via ACPI tables SRAT/HMAT. The min bandwidth are aggregated under the same
s/min/minimum/ preferably.
> -ACPI0017 device to form a new xarray.
> +via ACPI tables Documentation/driver-api/cxl/platform/acpi/srat.rst and
> +Documentation/driver-api/cxl/platform/acpi/hmat.rst. The min bandwidth are
> +aggregated under the same ACPI0017 device to form a new xarray.
>
> Finally, the cxl_region_update_bandwidth() is called and the aggregated
> bandwidth from all the members of the last xarray is updated for the
> diff --git a/Documentation/driver-api/cxl/linux/early-boot.rst b/Documentation/driver-api/cxl/linux/early-boot.rst
> index 275174d5b0bb..309cc6999c6b 100644
> --- a/Documentation/driver-api/cxl/linux/early-boot.rst
> +++ b/Documentation/driver-api/cxl/linux/early-boot.rst
> @@ -12,7 +12,8 @@ read EFI and ACPI information throughout this process to configure logical
> representations of the devices.
>
> During Linux Early Boot stage (functions in the kernel that have the __init
> -decorator), the system takes the resources created by EFI/BIOS (ACPI tables)
> +decorator), the system takes the resources created by EFI/BIOS
> +(Documentation/driver-api/cxl/platform/acpi.rst)
> and turns them into resources that the kernel can consume.
>
>
> @@ -69,13 +70,15 @@ significant impact performance depending on the memory capacity of the system.
> NUMA Node Reservation
> =====================
>
> -Linux refers to the proximity domains (:code:`PXM`) defined in the SRAT to
> -create NUMA nodes in :code:`acpi_numa_init`. Typically, there is a 1:1 relation
> -between :code:`PXM` and NUMA node IDs.
> +Linux refers to the proximity domains (:code:`PXM`) defined in the
> +Documentation/driver-api/cxl/platform/acpi/srat.rst to create NUMA nodes in
> +:code:`acpi_numa_init`. Typically, there is a 1:1 relation between
> +:code:`PXM` and NUMA node IDs.
>
> -SRAT is the only ACPI defined way of defining Proximity Domains. Linux chooses
> -to, at most, map those 1:1 with NUMA nodes. CEDT adds a description of SPA
> -ranges which Linux may wish to map to one or more NUMA nodes
> +The SRAT is the only ACPI defined way of defining Proximity Domains. Linux
> +chooses to, at most, map those 1:1 with NUMA nodes.
> +Documentation/driver-api/cxl/platform/acpi/cedt.rst
> +adds a description of SPA ranges which Linux may map to one or more NUMA nodes
Add ending period ('.') above.
>
> If there are CXL ranges in the CFMWS but not in SRAT, then a fake :code:`PXM`
> is created (as of v6.15). In the future, Linux may reject CFMWS not described
> @@ -88,7 +91,7 @@ data for Linux to identify NUMA nodes their associated memory regions.
>
> The relevant code exists in: :code:`linux/drivers/acpi/numa/srat.c`.
>
> -See the Example Platform Configurations section for more information.
> +See Documentation/driver-api/cxl/platform/example-configs.rst for more info.
>
> Memory Tiers Creation
> =====================
> @@ -107,10 +110,13 @@ Tier membership can be inspected in ::
> /sys/devices/virtual/memory_tiering/memory_tierN/nodelist
> 0-1
>
> -If nodes are grouped which have clear difference in performance, check the HMAT
> -and CDAT information for the CXL nodes. All nodes default to the DRAM tier,
> -unless HMAT/CDAT information is reported to the memory_tier component via
> -`access_coordinates`.
> +If nodes are grouped which have clear difference in performance, check the
> +Documentation/driver-api/cxl/platform/acpi/hmat.rst and CDAT
> +(Documentation/driver-api/cxl/devices/uefi.rst) information for the CXL nodes.
> +All nodes default to the DRAM tier, unless HMAT/CDAT information is reported
> +to the memory_tier component via `access_coordinates`.
> +
> +For more, see Documentation/driver-api/cxl/linux/access-coordinates.rst.
>
> Contiguous Memory Allocation
> ============================
> diff --git a/Documentation/driver-api/cxl/platform/example-configurations/flexible.rst b/Documentation/driver-api/cxl/platform/example-configurations/flexible.rst
> index 13a97c03e25a..b2559d2de225 100644
> --- a/Documentation/driver-api/cxl/platform/example-configurations/flexible.rst
> +++ b/Documentation/driver-api/cxl/platform/example-configurations/flexible.rst
> @@ -18,7 +18,7 @@ Things to note:
> * This SRAT describes one-node for each of the above CFMWS.
one node
> * The HMAT describes performance for each node in the SRAT.
>
> -CEDT ::
> +Documentation/driver-api/cxl/platform/acpi/cedt.rst ::
>
> Subtable Type : 00 [CXL Host Bridge Structure]
> Reserved : 00
> @@ -137,7 +137,7 @@ CEDT ::
> QtgId : 0001
> First Target : 00000006
>
> -SRAT ::
> +Documentation/driver-api/cxl/platform/acpi/srat.rst ::
>
> Subtable Type : 01 [Memory Affinity]
> Length : 28
> @@ -223,7 +223,7 @@ SRAT ::
> Hot Pluggable : 1
> Non-Volatile : 0
>
> -HMAT ::
> +Documentation/driver-api/cxl/platform/acpi/hmat.rst ::
>
> Structure Type : 0001 [SLLBI]
> Data Type : 00 [Latency]
> @@ -263,7 +263,7 @@ HMAT ::
> Entry : 0100
> Entry : 0100
>
> -SLIT ::
> +Documentation/driver-api/cxl/platform/acpi/slit.rst ::
>
> Signature : "SLIT" [System Locality Information Table]
> Localities : 0000000000000003
> @@ -276,7 +276,7 @@ SLIT ::
> Locality 6 : FF FF FF FF FF FF 0A FF
> Locality 7 : FF FF FF FF FF FF FF 0A
>
> -DSDT ::
> +Documentation/driver-api/cxl/platform/acpi/dsdt.rst ::
>
> Scope (_SB)
> {
> diff --git a/Documentation/driver-api/cxl/platform/example-configurations/hb-interleave.rst b/Documentation/driver-api/cxl/platform/example-configurations/hb-interleave.rst
> index fa0885d82deb..9cbf3dd44b0f 100644
> --- a/Documentation/driver-api/cxl/platform/example-configurations/hb-interleave.rst
> +++ b/Documentation/driver-api/cxl/platform/example-configurations/hb-interleave.rst
> @@ -13,7 +13,7 @@ Things to note:
> * This SRAT describes one-node for both host bridges.
one node
> * The HMAT describes a single node's performance.
>
> -CEDT ::
> +Documentation/driver-api/cxl/platform/acpi/cedt.rst ::
>
> Subtable Type : 00 [CXL Host Bridge Structure]
> Reserved : 00
> @@ -48,7 +48,7 @@ CEDT ::
> First Target : 00000007
> Second Target : 00000006
>
> -SRAT ::
> +Documentation/driver-api/cxl/platform/acpi/srat.rst ::
>
> Subtable Type : 01 [Memory Affinity]
> Length : 28
> @@ -62,7 +62,7 @@ SRAT ::
> Hot Pluggable : 1
> Non-Volatile : 0
>
> -HMAT ::
> +Documentation/driver-api/cxl/platform/acpi/hmat.rst ::
>
> Structure Type : 0001 [SLLBI]
> Data Type : 00 [Latency]
> @@ -80,14 +80,14 @@ HMAT ::
> Entry : 1200
> Entry : 0400
>
> -SLIT ::
> +Documentation/driver-api/cxl/platform/acpi/slit.rst ::
>
> Signature : "SLIT" [System Locality Information Table]
> Localities : 0000000000000003
> Locality 0 : 10 20
> Locality 1 : FF 0A
>
> -DSDT ::
> +Documentation/driver-api/cxl/platform/acpi/dsdt.rst ::
>
> Scope (_SB)
> {
> 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
> index 6adf7c639490..fa24243968ac 100644
> --- 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
> @@ -14,7 +14,7 @@ Things to note:
> * This CEDT/SRAT describes one node for both devices.
> * There is only one proximity domain the HMAT for both devices.
>
> -CEDT ::
> +Documentation/driver-api/cxl/platform/acpi/cedt.rst ::
>
> Subtable Type : 00 [CXL Host Bridge Structure]
> Reserved : 00
> @@ -39,7 +39,7 @@ CEDT ::
> QtgId : 0001
> First Target : 00000007
>
> -SRAT ::
> +Documentation/driver-api/cxl/platform/acpi/srat.rst ::
>
> Subtable Type : 01 [Memory Affinity]
> Length : 28
> @@ -53,7 +53,7 @@ SRAT ::
> Hot Pluggable : 1
> Non-Volatile : 0
>
> -HMAT ::
> +Documentation/driver-api/cxl/platform/acpi/hmat.rst ::
>
> Structure Type : 0001 [SLLBI]
> Data Type : 00 [Latency]
> @@ -69,14 +69,14 @@ HMAT ::
> Entry : 1200
> Entry : 0200
>
> -SLIT ::
> +Documentation/driver-api/cxl/platform/acpi/slit.rst ::
>
> Signature : "SLIT" [System Locality Information Table]
> Localities : 0000000000000003
> Locality 0 : 10 20
> Locality 1 : FF 0A
>
> -DSDT ::
> +Documentation/driver-api/cxl/platform/acpi/dsdt.rst ::
>
> Scope (_SB)
> {
> 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
> index 8b732dc8c5b6..ee65b3364c5b 100644
> --- 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
> @@ -14,7 +14,7 @@ Things to note:
> * This CEDT/SRAT describes one-node per device
one node
> * The expanders have the same performance and will be in the same memory tier.
>
> -CEDT ::
> +Documentation/driver-api/cxl/platform/acpi/cedt.rst ::
>
> Subtable Type : 00 [CXL Host Bridge Structure]
> Reserved : 00
> @@ -62,7 +62,7 @@ CEDT ::
> QtgId : 0001
> First Target : 00000006
>
> -SRAT ::
> +Documentation/driver-api/cxl/platform/acpi/srat.rst ::
>
> Subtable Type : 01 [Memory Affinity]
> Length : 28
> @@ -88,7 +88,7 @@ SRAT ::
> Hot Pluggable : 1
> Non-Volatile : 0
>
> -HMAT ::
> +Documentation/driver-api/cxl/platform/acpi/hmat.rst ::
>
> Structure Type : 0001 [SLLBI]
> Data Type : 00 [Latency]
> @@ -108,7 +108,7 @@ HMAT ::
> Entry : 0200
> Entry : 0200
>
> -SLIT ::
> +Documentation/driver-api/cxl/platform/acpi/slit.rst ::
>
> Signature : "SLIT" [System Locality Information Table]
> Localities : 0000000000000003
> @@ -116,7 +116,7 @@ SLIT ::
> Locality 1 : FF 0A FF
> Locality 2 : FF FF 0A
>
> -DSDT ::
> +Documentation/driver-api/cxl/platform/acpi/dsdt.rst ::
>
> Scope (_SB)
> {
--
~Randy
