| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-ID: <aCBqWib0Cl2OdQgR@archie.me>
Date: Sun, 11 May 2025 16:14:02 +0700
From: Bagas Sanjaya <bagasdotme@...il.com>
To: Gregory Price <gourry@...rry.net>, linux-cxl@...r.kernel.org
Cc: linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
kernel-team@...a.com, dave@...olabs.net,
jonathan.cameron@...wei.com, dave.jiang@...el.com,
alison.schofield@...el.com, vishal.l.verma@...el.com,
ira.weiny@...el.com, dan.j.williams@...el.com, corbet@....net
Subject: Re: [RFC PATCH v2 18/18] cxl: docs - add self-referencing cross-links
On Wed, Apr 30, 2025 at 02:10:48PM -0400, Gregory Price wrote:
> diff --git a/Documentation/driver-api/cxl/devices/device-types.rst b/Documentation/driver-api/cxl/devices/device-types.rst
> index dfe8d4711987..f33a40d2284d 100644
> --- a/Documentation/driver-api/cxl/devices/device-types.rst
> +++ b/Documentation/driver-api/cxl/devices/device-types.rst
> @@ -115,7 +115,7 @@ A Multi-Headed Single-Logical Device (MHSLD) exposes a single logical
> device to multiple heads which may be connected to one or more discrete
> hosts. An example of this would be a simple memory-pool which may be
> statically configured (prior to boot) to expose portions of its memory
> -to Linux via the CEDT ACPI table.
> +to Linux via Documentation/driver-api/cxl/platform/acpi/cedt.rst
>
> MHMLD
> ~~~~~
> 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
> -via ACPI tables SRAT/HMAT. The min bandwidth are aggregated under the same
> -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/cxl-driver.rst b/Documentation/driver-api/cxl/linux/cxl-driver.rst
> index 1a354ea1cda4..b4cb1910adde 100644
> --- a/Documentation/driver-api/cxl/linux/cxl-driver.rst
> +++ b/Documentation/driver-api/cxl/linux/cxl-driver.rst
> @@ -77,11 +77,11 @@ Root Object` Device Class is found.
>
> The Root contains links to:
>
> -* `Host Bridge Ports` defined by ACPI CEDT CHBS.
> +* `Host Bridge Ports` defined by CHBS in Documentation/driver-api/cxl/platform/acpi/cedt.rst.
>
> * `Downstream Ports` typically connected to `Host Bridge Ports`
>
> -* `Root Decoders` defined by ACPI CEDT CFMWS.
> +* `Root Decoders` defined by CFMWS in Documentation/driver-api/cxl/platform/acpi/cedt.rst.
>
> ::
>
> @@ -150,9 +150,9 @@ An `endpoint` is a terminal port in the fabric. This is a `logical device`,
> and may be one of many `logical devices` presented by a memory device. It
> is still considered a type of `port` in the fabric.
>
> -An `endpoint` contains `endpoint decoders` available for use and the
> -*Coherent Device Attribute Table* (CDAT) used to describe the capabilities
> -of the device. ::
> +An `endpoint` contains `endpoint decoders` available for use and the CDAT in
> +Device's Documentation/driver-api/cxl/devices/uefi.rst used to describe the
> +capabilities of the device. ::
>
> # ls /sys/bus/cxl/devices/endpoint5
> CDAT decoders_committed modalias uevent
> @@ -247,17 +247,18 @@ parameter.
> Root Decoder
> ~~~~~~~~~~~~
> A `Root Decoder` is logical construct of the physical address and interleave
> -configurations present in the ACPI CEDT CFMWS. Linux presents this information
> -as a decoder present in the `CXL Root`. We consider this a `Root Decoder`,
> -though technically it exists on the boundary of the CXL specification and
> -platform-specific CXL root implementations.
> +configurations present in the CFMWS field of the
> +Documentation/driver-api/cxl/platform/acpi/cedt.rst.
> +Linux presents this information as a decoder present in the `CXL Root`. We
> +consider this a `Root Decoder`, though technically it exists on the boundary
> +of the CXL specification and platform-specific CXL root implementations.
>
> Linux considers these logical decoders a type of `Routing Decoder`, and is the
> first decoder in the CXL fabric to receive a memory access from the platform's
> memory controllers.
>
> `Root Decoders` are created during :code:`cxl_acpi_probe`. One root decoder
> -is created per CFMWS entry in the ACPI CEDT.
> +is created per CFMWS entry in the Documentation/driver-api/cxl/platform/acpi/cedt.rst.
>
> The :code:`target_list` parameter is filled by the CFMWS target fields. Targets
> of a root decoder are `Host Bridges`, which means interleave done at the root
> @@ -267,9 +268,11 @@ Only root decoders are capable of `Inter-Host-Bridge Interleave`.
>
> Such interleaves must be configured by the platform and described in the ACPI
> CEDT CFMWS, as the target CXL host bridge UIDs in the CFMWS must match the CXL
> -host bridge UIDs in the ACPI CEDT CHBS and ACPI DSDT.
> +host bridge UIDs in the CHBS field of the
> +Documentation/driver-api/cxl/platform/acpi/cedt.rst and the UID field of CXL
> +Host Bridges defined in the Documentation/driver-api/cxl/platform/acpi/dsdt.rst.
>
> -Interleave settings in a rootdecoder describe how to interleave accesses among
> +Interleave settings in a root decoder describe how to interleave accesses among
> the *immediate downstream targets*, not the entire interleave set.
>
> The memory range described in the root decoder is used to
> @@ -531,10 +534,11 @@ granularity configuration.
>
> At Root
> ~~~~~~~
> -Root decoder interleave is defined by the ACPI CEDT CFMWS. The CEDT
> -may actually define multiple CFMWS configurations to describe the same
> -physical capacity - with the intent to allow users to decide at runtime
> -whether to online memory as interleaved or non-interleaved. ::
> +Root decoder interleave is defined by CFMWS field of the
> +Documentation/driver-api/cxl/platform/acpi/cedt.rst. The CEDT may actually
> +define multiple CFMWS configurations to describe the same physical capacity,
> +with the intent to allow users to decide at runtime whether to online memory
> +as interleaved or non-interleaved. ::
>
> Subtable Type : 01 [CXL Fixed Memory Window Structure]
> Window base address : 0000000100000000
> 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
>
> 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/bios-and-efi.rst b/Documentation/driver-api/cxl/platform/bios-and-efi.rst
> index 552a83992bcc..cdbba6798079 100644
> --- a/Documentation/driver-api/cxl/platform/bios-and-efi.rst
> +++ b/Documentation/driver-api/cxl/platform/bios-and-efi.rst
> @@ -22,7 +22,7 @@ At a high level, this is what occurs during this phase of configuration.
>
> Much of what this section is concerned with is ACPI Table production and
> static memory map configuration. More detail on these tables can be found
> -under Platform Configuration -> ACPI Table Reference.
> +at Documentation/driver-api/cxl/platform/acpi.rst.
>
> .. note::
> Platform Vendors should read carefully, as this sections has recommendations
> @@ -175,9 +175,10 @@ to implement driver support for your platform.
>
> Interleave and Configuration Flexibility
> ----------------------------------------
> -If providing cross-host-bridge interleave, a CFMWS entry in the CEDT must be
> -presented with target host-bridges for the interleaved device sets (there may
> -be multiple behind each host bridge).
> +If providing cross-host-bridge interleave, a CFMWS entry in the
> +Documentation/driver-api/cxl/platform/acpi/cedt.rst
> +must be presented with target host-bridges for the interleaved device sets
> +(there may be multiple behind each host bridge).
>
> If providing intra-host-bridge interleaving, only 1 CFMWS entry in the CEDT is
> required for that host bridge - if it covers the entire capacity of the devices
> @@ -193,8 +194,8 @@ different purposes. For example, you may want to consider adding:
>
> A platform may choose to add all of these, or change the mode based on a BIOS
> setting. For each CFMWS entry, Linux expects descriptions of the described
> -memory regions in the SRAT to determine the number of NUMA nodes it should
> -reserve during early boot / init.
> +memory regions in the Documentation/driver-api/cxl/platform/acpi/srat.rst to
> +determine the number of NUMA nodes it should reserve during early boot / init.
>
> As of v6.14, Linux will create a NUMA node for each CEDT CFMWS entry, even if
> a matching SRAT entry does not exist; however, this is not guaranteed in the
> 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.
> * 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.
> * 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
> * 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)
> {
You may want to add explicit anchor text (using relative :doc: links to
lessen typing):
---- >8 ----
diff --git a/Documentation/driver-api/cxl/devices/device-types.rst b/Documentation/driver-api/cxl/devices/device-types.rst
index f33a40d2284d19..b784aa85abf019 100644
--- a/Documentation/driver-api/cxl/devices/device-types.rst
+++ b/Documentation/driver-api/cxl/devices/device-types.rst
@@ -115,7 +115,7 @@ A Multi-Headed Single-Logical Device (MHSLD) exposes a single logical
device to multiple heads which may be connected to one or more discrete
hosts. An example of this would be a simple memory-pool which may be
statically configured (prior to boot) to expose portions of its memory
-to Linux via Documentation/driver-api/cxl/platform/acpi/cedt.rst
+to Linux via :doc:`CEDT ACPI table <../platform/acpi/cedt>`.
MHMLD
~~~~~
diff --git a/Documentation/driver-api/cxl/linux/access-coordinates.rst b/Documentation/driver-api/cxl/linux/access-coordinates.rst
index cd6d66cdf9e691..610970874aefdb 100644
--- a/Documentation/driver-api/cxl/linux/access-coordinates.rst
+++ b/Documentation/driver-api/cxl/linux/access-coordinates.rst
@@ -84,9 +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
-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.
+via ACPI tables :doc:`SRAT <../platform/acpi/srat>` and
+:doc:`HMAT <../platform/acpi/hmat>`. 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/cxl-driver.rst b/Documentation/driver-api/cxl/linux/cxl-driver.rst
index b4cb1910added6..c7e0ef80237df8 100644
--- a/Documentation/driver-api/cxl/linux/cxl-driver.rst
+++ b/Documentation/driver-api/cxl/linux/cxl-driver.rst
@@ -77,11 +77,13 @@ Root Object` Device Class is found.
The Root contains links to:
-* `Host Bridge Ports` defined by CHBS in Documentation/driver-api/cxl/platform/acpi/cedt.rst.
+* `Host Bridge Ports` defined by CHBS in :doc:`CEDT table
+ <../platform/acpi/cedt>`.
* `Downstream Ports` typically connected to `Host Bridge Ports`
-* `Root Decoders` defined by CFMWS in Documentation/driver-api/cxl/platform/acpi/cedt.rst.
+* `Root Decoders` defined by CFMWS in :doc:`CEDT table
+ <../platform/acpi/cedt>`.
::
@@ -151,8 +153,8 @@ and may be one of many `logical devices` presented by a memory device. It
is still considered a type of `port` in the fabric.
An `endpoint` contains `endpoint decoders` available for use and the CDAT in
-Device's Documentation/driver-api/cxl/devices/uefi.rst used to describe the
-capabilities of the device. ::
+Device's :doc:`UEFI data <../devices/uefi>` used to describe the capabilities
+of the device. ::
# ls /sys/bus/cxl/devices/endpoint5
CDAT decoders_committed modalias uevent
@@ -247,18 +249,18 @@ parameter.
Root Decoder
~~~~~~~~~~~~
A `Root Decoder` is logical construct of the physical address and interleave
-configurations present in the CFMWS field of the
-Documentation/driver-api/cxl/platform/acpi/cedt.rst.
-Linux presents this information as a decoder present in the `CXL Root`. We
-consider this a `Root Decoder`, though technically it exists on the boundary
-of the CXL specification and platform-specific CXL root implementations.
+configurations present in the CFMWS field of the :doc:`CEDT table
+<../platform/acpi/cedt>`. Linux presents this information as a decoder present
+in the `CXL Root`. We consider this a `Root Decoder`, though technically it
+exists on the boundary of the CXL specification and platform-specific CXL root
+implementations.
Linux considers these logical decoders a type of `Routing Decoder`, and is the
first decoder in the CXL fabric to receive a memory access from the platform's
memory controllers.
`Root Decoders` are created during :code:`cxl_acpi_probe`. One root decoder
-is created per CFMWS entry in the Documentation/driver-api/cxl/platform/acpi/cedt.rst.
+is created per CFMWS entry in the :doc:`CEDT table <../platform/acpi/cedt>`.
The :code:`target_list` parameter is filled by the CFMWS target fields. Targets
of a root decoder are `Host Bridges`, which means interleave done at the root
@@ -269,8 +271,8 @@ Only root decoders are capable of `Inter-Host-Bridge Interleave`.
Such interleaves must be configured by the platform and described in the ACPI
CEDT CFMWS, as the target CXL host bridge UIDs in the CFMWS must match the CXL
host bridge UIDs in the CHBS field of the
-Documentation/driver-api/cxl/platform/acpi/cedt.rst and the UID field of CXL
-Host Bridges defined in the Documentation/driver-api/cxl/platform/acpi/dsdt.rst.
+:doc:`CEDT table <../platform/acpi/cedt>` and the UID field of CXL
+Host Bridges defined in the :doc:`DSDT table <../platform/acpi/dsdt>`.
Interleave settings in a root decoder describe how to interleave accesses among
the *immediate downstream targets*, not the entire interleave set.
@@ -534,11 +536,11 @@ granularity configuration.
At Root
~~~~~~~
-Root decoder interleave is defined by CFMWS field of the
-Documentation/driver-api/cxl/platform/acpi/cedt.rst. The CEDT may actually
-define multiple CFMWS configurations to describe the same physical capacity,
-with the intent to allow users to decide at runtime whether to online memory
-as interleaved or non-interleaved. ::
+Root decoder interleave is defined by CFMWS field of the :doc:`CEDT table
+<../platform/acpi/cedt>`. The CEDT may actually define multiple CFMWS
+configurations to describe the same physical capacity, with the intent to allow
+users to decide at runtime whether to online memory as interleaved or
+non-interleaved. ::
Subtable Type : 01 [CXL Fixed Memory Window Structure]
Window base address : 0000000100000000
diff --git a/Documentation/driver-api/cxl/linux/early-boot.rst b/Documentation/driver-api/cxl/linux/early-boot.rst
index 309cc6999c6bce..cdd485579e6422 100644
--- a/Documentation/driver-api/cxl/linux/early-boot.rst
+++ b/Documentation/driver-api/cxl/linux/early-boot.rst
@@ -13,8 +13,8 @@ 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
-(Documentation/driver-api/cxl/platform/acpi.rst)
-and turns them into resources that the kernel can consume.
+(:doc:`ACPI tables <../platform/acpi>`) and turns them into resources that the
+kernel can consume.
BIOS, Build and Boot Options
@@ -71,14 +71,14 @@ NUMA Node Reservation
=====================
Linux refers to the proximity domains (:code:`PXM`) defined in the
-Documentation/driver-api/cxl/platform/acpi/srat.rst to create NUMA nodes in
+:doc:`SRAT table <../platform/acpi/srat>` to create NUMA nodes in
:code:`acpi_numa_init`. Typically, there is a 1:1 relation between
:code:`PXM` and NUMA node IDs.
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
+:doc:`CEDT <../platform/acpi/cedt>` adds a description of SPA ranges which
+Linux may map to one or more NUMA nodes
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
@@ -91,7 +91,8 @@ data for Linux to identify NUMA nodes their associated memory regions.
The relevant code exists in: :code:`linux/drivers/acpi/numa/srat.c`.
-See Documentation/driver-api/cxl/platform/example-configs.rst for more info.
+See :doc:`Example Platform Configurations section <../platform/example-configs>`
+for more info.
Memory Tiers Creation
=====================
@@ -111,12 +112,13 @@ Tier membership can be inspected in ::
0-1
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`.
+:doc:`HMAT <../platform/acpi/hmat>` and :doc:`CDAT <../devices/uefi>`
+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.
+For more, see :doc:`CXL access coordinates documentation
+<../linux/access-coordinates>`.
Contiguous Memory Allocation
============================
diff --git a/Documentation/driver-api/cxl/platform/bios-and-efi.rst b/Documentation/driver-api/cxl/platform/bios-and-efi.rst
index 3c46941b948e4f..f95efacc36de8b 100644
--- a/Documentation/driver-api/cxl/platform/bios-and-efi.rst
+++ b/Documentation/driver-api/cxl/platform/bios-and-efi.rst
@@ -22,7 +22,7 @@ At a high level, this is what occurs during this phase of configuration.
Much of what this section is concerned with is ACPI Table production and
static memory map configuration. More detail on these tables can be found
-at Documentation/driver-api/cxl/platform/acpi.rst.
+at :doc:`ACPI tables reference <acpi>`.
.. note::
Platform Vendors should read carefully, as this sections has recommendations
@@ -176,9 +176,8 @@ to implement driver support for your platform.
Interleave and Configuration Flexibility
----------------------------------------
If providing cross-host-bridge interleave, a CFMWS entry in the
-Documentation/driver-api/cxl/platform/acpi/cedt.rst
-must be presented with target host-bridges for the interleaved device sets
-(there may be multiple behind each host bridge).
+:doc:`CEDT <acpi/cedt>` must be presented with target host-bridges for
+the interleaved device sets (there may be multiple behind each host bridge).
If providing intra-host-bridge interleaving, only 1 CFMWS entry in the CEDT is
required for that host bridge - if it covers the entire capacity of the devices
@@ -194,7 +193,7 @@ different purposes. For example, you may want to consider adding:
A platform may choose to add all of these, or change the mode based on a BIOS
setting. For each CFMWS entry, Linux expects descriptions of the described
-memory regions in the Documentation/driver-api/cxl/platform/acpi/srat.rst to
+memory regions in the :doc:`SRAT <acpi/srat>` to
determine the number of NUMA nodes it should reserve during early boot / init.
As of v6.14, Linux will create a NUMA node for each CEDT CFMWS entry, even if
diff --git a/Documentation/driver-api/cxl/platform/example-configurations/flexible.rst b/Documentation/driver-api/cxl/platform/example-configurations/flexible.rst
index b2559d2de2255b..03cfc8785702bc 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.
* The HMAT describes performance for each node in the SRAT.
-Documentation/driver-api/cxl/platform/acpi/cedt.rst ::
+:doc:`CEDT <../acpi/cedt>`::
Subtable Type : 00 [CXL Host Bridge Structure]
Reserved : 00
@@ -137,7 +137,7 @@ Documentation/driver-api/cxl/platform/acpi/cedt.rst ::
QtgId : 0001
First Target : 00000006
-Documentation/driver-api/cxl/platform/acpi/srat.rst ::
+:doc:`SRAT <../acpi/srat>`::
Subtable Type : 01 [Memory Affinity]
Length : 28
@@ -223,7 +223,7 @@ Documentation/driver-api/cxl/platform/acpi/srat.rst ::
Hot Pluggable : 1
Non-Volatile : 0
-Documentation/driver-api/cxl/platform/acpi/hmat.rst ::
+:doc:`HMAT <../acpi/hmat>`::
Structure Type : 0001 [SLLBI]
Data Type : 00 [Latency]
@@ -263,7 +263,7 @@ Documentation/driver-api/cxl/platform/acpi/hmat.rst ::
Entry : 0100
Entry : 0100
-Documentation/driver-api/cxl/platform/acpi/slit.rst ::
+:doc:`SLIT <../acpi/slit>`::
Signature : "SLIT" [System Locality Information Table]
Localities : 0000000000000003
@@ -276,7 +276,7 @@ Documentation/driver-api/cxl/platform/acpi/slit.rst ::
Locality 6 : FF FF FF FF FF FF 0A FF
Locality 7 : FF FF FF FF FF FF FF 0A
-Documentation/driver-api/cxl/platform/acpi/dsdt.rst ::
+:doc:`DSDT <../acpi/dsdt>`::
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 9cbf3dd44b0f62..d0c512b3c0ae99 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.
* The HMAT describes a single node's performance.
-Documentation/driver-api/cxl/platform/acpi/cedt.rst ::
+:doc:`CEDT <../acpi/cedt>`::
Subtable Type : 00 [CXL Host Bridge Structure]
Reserved : 00
@@ -48,7 +48,7 @@ Documentation/driver-api/cxl/platform/acpi/cedt.rst ::
First Target : 00000007
Second Target : 00000006
-Documentation/driver-api/cxl/platform/acpi/srat.rst ::
+:doc:`SRAT <../acpi/srat>`::
Subtable Type : 01 [Memory Affinity]
Length : 28
@@ -62,7 +62,7 @@ Documentation/driver-api/cxl/platform/acpi/srat.rst ::
Hot Pluggable : 1
Non-Volatile : 0
-Documentation/driver-api/cxl/platform/acpi/hmat.rst ::
+:doc:`HMAT <../acpi/hmat>`::
Structure Type : 0001 [SLLBI]
Data Type : 00 [Latency]
@@ -80,14 +80,14 @@ Documentation/driver-api/cxl/platform/acpi/hmat.rst ::
Entry : 1200
Entry : 0400
-Documentation/driver-api/cxl/platform/acpi/slit.rst ::
+:doc:`SLIT <../acpi/slit>`::
Signature : "SLIT" [System Locality Information Table]
Localities : 0000000000000003
Locality 0 : 10 20
Locality 1 : FF 0A
-Documentation/driver-api/cxl/platform/acpi/dsdt.rst ::
+:doc:`DSDT <../acpi/dsdt>`::
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 fa24243968ac9c..a7854a79dbbde9 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.
-Documentation/driver-api/cxl/platform/acpi/cedt.rst ::
+:doc:`CEDT <../acpi/cedt>`::
Subtable Type : 00 [CXL Host Bridge Structure]
Reserved : 00
@@ -39,7 +39,7 @@ Documentation/driver-api/cxl/platform/acpi/cedt.rst ::
QtgId : 0001
First Target : 00000007
-Documentation/driver-api/cxl/platform/acpi/srat.rst ::
+:doc:`SRAT <../acpi/srat>`::
Subtable Type : 01 [Memory Affinity]
Length : 28
@@ -53,7 +53,7 @@ Documentation/driver-api/cxl/platform/acpi/srat.rst ::
Hot Pluggable : 1
Non-Volatile : 0
-Documentation/driver-api/cxl/platform/acpi/hmat.rst ::
+:doc:`HMAT <../acpi/hmat>`::
Structure Type : 0001 [SLLBI]
Data Type : 00 [Latency]
@@ -69,14 +69,14 @@ Documentation/driver-api/cxl/platform/acpi/hmat.rst ::
Entry : 1200
Entry : 0200
-Documentation/driver-api/cxl/platform/acpi/slit.rst ::
+:doc:`SLIT <../acpi/slit>`::
Signature : "SLIT" [System Locality Information Table]
Localities : 0000000000000003
Locality 0 : 10 20
Locality 1 : FF 0A
-Documentation/driver-api/cxl/platform/acpi/dsdt.rst ::
+:doc:`DSDT <../acpi/dsdt>`::
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 ee65b3364c5bf6..b800713313451b 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
* The expanders have the same performance and will be in the same memory tier.
-Documentation/driver-api/cxl/platform/acpi/cedt.rst ::
+:doc:`CEDT <../acpi/cedt>`::
Subtable Type : 00 [CXL Host Bridge Structure]
Reserved : 00
@@ -62,7 +62,7 @@ Documentation/driver-api/cxl/platform/acpi/cedt.rst ::
QtgId : 0001
First Target : 00000006
-Documentation/driver-api/cxl/platform/acpi/srat.rst ::
+:doc:`SRAT <../acpi/srat>`::
Subtable Type : 01 [Memory Affinity]
Length : 28
@@ -88,7 +88,7 @@ Documentation/driver-api/cxl/platform/acpi/srat.rst ::
Hot Pluggable : 1
Non-Volatile : 0
-Documentation/driver-api/cxl/platform/acpi/hmat.rst ::
+:doc:`HMAT <../acpi/hmat>`::
Structure Type : 0001 [SLLBI]
Data Type : 00 [Latency]
@@ -108,7 +108,7 @@ Documentation/driver-api/cxl/platform/acpi/hmat.rst ::
Entry : 0200
Entry : 0200
-Documentation/driver-api/cxl/platform/acpi/slit.rst ::
+:doc:`SLIT <../acpi/slit>`::
Signature : "SLIT" [System Locality Information Table]
Localities : 0000000000000003
@@ -116,7 +116,7 @@ Documentation/driver-api/cxl/platform/acpi/slit.rst ::
Locality 1 : FF 0A FF
Locality 2 : FF FF 0A
-Documentation/driver-api/cxl/platform/acpi/dsdt.rst ::
+:doc:`DSDT <../acpi/dsdt>`::
Scope (_SB)
{
Thanks.
--
An old man doll... just what I always wanted! - Clara
Download attachment "signature.asc" of type "application/pgp-signature" (229 bytes)
Powered by blists - more mailing lists