Re: [PATCH v3 01/17] cxl: update documentation structure in prep for new docs

Dave Jiang
2025-05-12T22:46:53Z

On 5/12/25 9:21 AM, Gregory Price wrote:
> Restructure the cxl folder to make adding docs per-page cleaner.
>
> Signed-off-by: Gregory Price <gourry@gourry.net>
Reviewed-by: Dave Jiang <dave.jiang@intel.com>

> ---
> Documentation/driver-api/cxl/index.rst | 16 +++++++++++++---
> .../cxl/{ => linux}/access-coordinates.rst | 0
> ...emory-devices.rst => theory-of-operation.rst} | 10 +++++-----
> 3 files changed, 18 insertions(+), 8 deletions(-)
> rename Documentation/driver-api/cxl/{ => linux}/access-coordinates.rst (100%)
> rename Documentation/driver-api/cxl/{memory-devices.rst => theory-of-operation.rst} (98%)
>
> diff --git a/Documentation/driver-api/cxl/index.rst b/Documentation/driver-api/cxl/index.rst
> index 965ba90e8fb7..fe1594dc6778 100644
> --- a/Documentation/driver-api/cxl/index.rst
> +++ b/Documentation/driver-api/cxl/index.rst
> @@ -4,12 +4,22 @@
> Compute Express Link
> ====================
>
> +CXL device configuration has a complex handoff between platform (Hardware,
> +BIOS, EFI), OS (early boot, core kernel, driver), and user policy decisions
> +that have impacts on each other. The docs here break up configurations steps.
> +
> +.. toctree::
> + :maxdepth: 2
> + :caption: Overview
> +
> + theory-of-operation
> + maturity-map
> +
> .. toctree::
> :maxdepth: 1
> + :caption: Linux Kernel Configuration
>
> - memory-devices
> - access-coordinates
> + linux/access-coordinates
>
> - maturity-map
>
> .. only:: subproject and html
> diff --git a/Documentation/driver-api/cxl/access-coordinates.rst b/Documentation/driver-api/cxl/linux/access-coordinates.rst
> similarity index 100%
> rename from Documentation/driver-api/cxl/access-coordinates.rst
> rename to Documentation/driver-api/cxl/linux/access-coordinates.rst
> diff --git a/Documentation/driver-api/cxl/memory-devices.rst b/Documentation/driver-api/cxl/theory-of-operation.rst
> similarity index 98%
> rename from Documentation/driver-api/cxl/memory-devices.rst
> rename to Documentation/driver-api/cxl/theory-of-operation.rst
> index d732c42526df..32739e253453 100644
> --- a/Documentation/driver-api/cxl/memory-devices.rst
> +++ b/Documentation/driver-api/cxl/theory-of-operation.rst
> @@ -1,9 +1,9 @@
> .. SPDX-License-Identifier: GPL-2.0
> .. include:: <isonum.txt>
>
> -===================================
> -Compute Express Link Memory Devices
> -===================================
> +===============================================
> +Compute Express Link Driver Theory of Operation
> +===============================================
>
> A Compute Express Link Memory Device is a CXL component that implements the
> CXL.mem protocol. It contains some amount of volatile memory, persistent memory,
> @@ -14,8 +14,8 @@ that optionally define a device's contribution to an interleaved address
> range across multiple devices underneath a host-bridge or interleaved
> across host-bridges.
>
> -CXL Bus: Theory of Operation
> -============================
> +The CXL Bus
> +===========
> Similar to how a RAID driver takes disk objects and assembles them into a new
> logical device, the CXL subsystem is tasked to take PCIe and ACPI objects and
> assemble them into a CXL.mem decode topology. The need for runtime configuration