linux-kernel - Re: [PATCH v2 1/2] cxl, doc: Moving conventions in separate files

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: <20251215111453.000072a2@huawei.com>
Date: Mon, 15 Dec 2025 11:14:53 +0000
From: Jonathan Cameron <jonathan.cameron@...wei.com>
To: Robert Richter <rrichter@....com>
CC: Alison Schofield <alison.schofield@...el.com>, Vishal Verma
	<vishal.l.verma@...el.com>, Ira Weiny <ira.weiny@...el.com>, Dan Williams
	<dan.j.williams@...el.com>, Dave Jiang <dave.jiang@...el.com>, "Davidlohr
 Bueso" <dave@...olabs.net>, Jonathan Corbet <corbet@....net>,
	<linux-cxl@...r.kernel.org>, <linux-kernel@...r.kernel.org>, Gregory Price
	<gourry@...rry.net>, "Fabio M. De Francesco"
	<fabio.m.de.francesco@...ux.intel.com>, Terry Bowman <terry.bowman@....com>,
	Joshua Hahn <joshua.hahnjy@...il.com>, Randy Dunlap <rdunlap@...radead.org>,
	<linux-doc@...r.kernel.org>
Subject: Re: [PATCH v2 1/2] cxl, doc: Moving conventions in separate files

On Tue, 9 Dec 2025 19:19:55 +0100
Robert Richter <rrichter@....com> wrote:

> Moving conventions in separate files.
> 
> Note this patch removes the line to include:: <isonum.txt>. From Jon:
> 
> "This include has been cargo-culted around the docs...the only real
> use of it is to write |copy| rather than ©, but these docs don't even
> do that. It can be taken out."

Hi Robert,

Whilst I don't really care that much for docs, this is an unrelated
change so I'd have done that as a precursor patch.

Other than that, looks like sensible path to better scalability of
these docs.  However, questions inline as this is doing a little
more than simply moving stuff around. The intro text on what the whole
thing is about disappears.

> 
> Cc: Jonathan Corbet <corbet@....net>
> Signed-off-by: Robert Richter <rrichter@....com>
> ---
> v2:
>  * Removed include:: <isonum.txt> line (Jon).
> ---
> ---
>  Documentation/driver-api/cxl/conventions.rst  | 183 +-----------------
>  .../driver-api/cxl/conventions/cxl-lmh.rst    | 135 +++++++++++++
>  .../driver-api/cxl/conventions/template.rst   |  38 ++++
>  3 files changed, 179 insertions(+), 177 deletions(-)
>  create mode 100644 Documentation/driver-api/cxl/conventions/cxl-lmh.rst
>  create mode 100644 Documentation/driver-api/cxl/conventions/template.rst
> 
> diff --git a/Documentation/driver-api/cxl/conventions.rst b/Documentation/driver-api/cxl/conventions.rst
> index e37336d7b116..53f31a229c8d 100644
> --- a/Documentation/driver-api/cxl/conventions.rst
> +++ b/Documentation/driver-api/cxl/conventions.rst
> @@ -1,182 +1,11 @@
>  .. SPDX-License-Identifier: GPL-2.0
> -.. include:: <isonum.txt>
>  
> -=======================================
>  Compute Express Link: Linux Conventions
> -=======================================
> +#######################################
>  
> -There exists shipping platforms that bend or break CXL specification
> -expectations. Record the details and the rationale for those deviations.
> -Borrow the ACPI Code First template format to capture the assumptions
> -and tradeoffs such that multiple platform implementations can follow the
> -same convention.

This block around the format choice etc to me has some value, so why not keep
it about the ToC?  I'd rather we didn't end up with conventions that are
about something completely different in here just because the title first
(code style maybe?)



> +.. toctree::
> +   :maxdepth: 1
> +   :caption: Contents

> +   conventions/cxl-lmh.rst
> +   conventions/template.rst

...

> diff --git a/Documentation/driver-api/cxl/conventions/template.rst b/Documentation/driver-api/cxl/conventions/template.rst
> new file mode 100644
> index 000000000000..39a9ca87cf92
> --- /dev/null
> +++ b/Documentation/driver-api/cxl/conventions/template.rst
> @@ -0,0 +1,38 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. :: Template Title here:
> +
> +Template File
> +=============
> +
> +Document
> +--------
> +CXL Revision <rev>, Version <ver>
> +
> +License
> +-------
> +SPDX-License Identifier: CC-BY-4.0
> +
> +Creator/Contributors
> +--------------------
> +
> +Summary of the Change
> +---------------------
> +
> +<Detail the conflict with the specification and where available the
> +assumptions and tradeoffs taken by the hardware platform.>
> +

Obviously unrelated change but maybe drop a blank line here anyway
just for consistency with the rest where 1 is 

> +
> +Benefits of the Change
> +----------------------
> +
> +<Detail what happens if platforms and Linux do not adopt this
> +convention.>  
> +
> +References
> +----------
> +
> +Detailed Description of the Change
> +----------------------------------
> +
> +<Propose spec language that corrects the conflict.>
> 
> base-commit: 9d887fa9036f64331038b48199ae07da89777160