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

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

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <a962493d-0b68-4b37-88e4-57c3a199c1f8@intel.com>
Date: Mon, 12 May 2025 15:46:52 -0700
From: Dave Jiang <dave.jiang@...el.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,
 alison.schofield@...el.com, vishal.l.verma@...el.com, ira.weiny@...el.com,
 dan.j.williams@...el.com, corbet@....net
Subject: Re: [PATCH v3 01/17] cxl: update documentation structure in prep for
 new docs



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@...rry.net>
Reviewed-by: Dave Jiang <dave.jiang@...el.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