[PATCH] Documentation/driver-api/cxl: Introduce conventions.rst

[PATCH] Documentation/driver-api/cxl: Introduce conventions.rst

[Dan Williams]

There exists shipping platforms that bend, break, or otherwise lean on
ambiguities in the CXL specification. Without driver changes to accommodate
these deviations, end users are left without CXL subsystem RAS features.
Specifically, provisioning, error translation, and other flows require the
CXL subsystem to understand the platforms CXL topology beyond undecorated
memory address ranges.

Those isolated compatibility problems risk growing into deeper upstream
maintenance burden if different platform vendors arrive at diverging
solutions. For example, there are multiple options for resolving
low-memory-mmio intersecting large-interleave-ways CXL windows. Linux
should only entertain one solution to that problem.

Now, with the ACPI Specification Working Group, situations like this would
be resolved with the "Code First ECN" process to codify Linux expectations
in a specification. In the absence of such a process for the CXL
specification, create a file in Linux documentation to detail the
motivations, assumptions, tradeoffs, and proposals for amending
specification language.

The goal is to capture the issues such that platform vendors arrive at
compatible solutions for these problems and serve as a repository for
potential specification updates. The expectation is to update
conventions.rst along with CXL subsystem code changes to accommodate the
platform topology.

Signed-off-by: Dan Williams <dan.j.williams@intel.com>
---
 Documentation/driver-api/cxl/conventions.rst | 48 ++++++++++++++++++++
 Documentation/driver-api/cxl/index.rst       |  2 +
 2 files changed, 50 insertions(+)
 create mode 100644 Documentation/driver-api/cxl/conventions.rst

diff --git a/Documentation/driver-api/cxl/conventions.rst b/Documentation/driver-api/cxl/conventions.rst
new file mode 100644
index 000000000000..662dbaf1f045
--- /dev/null
+++ b/Documentation/driver-api/cxl/conventions.rst
@@ -0,0 +1,48 @@
+.. 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.
+
+<(template) Title>
+==================
+
+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.>
+
+
+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.>
+
diff --git a/Documentation/driver-api/cxl/index.rst b/Documentation/driver-api/cxl/index.rst
index 965ba90e8fb7..721a2dacf8fc 100644
--- a/Documentation/driver-api/cxl/index.rst
+++ b/Documentation/driver-api/cxl/index.rst
@@ -12,4 +12,6 @@ Compute Express Link
 
    maturity-map
 
+   conventions
+
 .. only::  subproject and html

base-commit: a5806cd506af5a7c19bcd596e4708b5c464bfd21
-- 
2.49.0

Re: [PATCH] Documentation/driver-api/cxl: Introduce conventions.rst

[Dave Jiang]

On 6/3/25 11:52 AM, Dan Williams wrote:
> There exists shipping platforms that bend, break, or otherwise lean on
> ambiguities in the CXL specification. Without driver changes to accommodate
> these deviations, end users are left without CXL subsystem RAS features.
> Specifically, provisioning, error translation, and other flows require the
> CXL subsystem to understand the platforms CXL topology beyond undecorated
> memory address ranges.
> 
> Those isolated compatibility problems risk growing into deeper upstream
> maintenance burden if different platform vendors arrive at diverging
> solutions. For example, there are multiple options for resolving
> low-memory-mmio intersecting large-interleave-ways CXL windows. Linux
> should only entertain one solution to that problem.
> 
> Now, with the ACPI Specification Working Group, situations like this would
> be resolved with the "Code First ECN" process to codify Linux expectations
> in a specification. In the absence of such a process for the CXL
> specification, create a file in Linux documentation to detail the
> motivations, assumptions, tradeoffs, and proposals for amending
> specification language.
> 
> The goal is to capture the issues such that platform vendors arrive at
> compatible solutions for these problems and serve as a repository for
> potential specification updates. The expectation is to update
> conventions.rst along with CXL subsystem code changes to accommodate the
> platform topology.
> 
> Signed-off-by: Dan Williams <dan.j.williams@intel.com>

Reviewed-by: Dave Jiang <dave.jiang@intel.com>
> ---
>  Documentation/driver-api/cxl/conventions.rst | 48 ++++++++++++++++++++
>  Documentation/driver-api/cxl/index.rst       |  2 +
>  2 files changed, 50 insertions(+)
>  create mode 100644 Documentation/driver-api/cxl/conventions.rst
> 
> diff --git a/Documentation/driver-api/cxl/conventions.rst b/Documentation/driver-api/cxl/conventions.rst
> new file mode 100644
> index 000000000000..662dbaf1f045
> --- /dev/null
> +++ b/Documentation/driver-api/cxl/conventions.rst
> @@ -0,0 +1,48 @@
> +.. 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.
> +
> +<(template) Title>
> +==================
> +
> +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.>
> +
> +
> +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.>
> +
> diff --git a/Documentation/driver-api/cxl/index.rst b/Documentation/driver-api/cxl/index.rst
> index 965ba90e8fb7..721a2dacf8fc 100644
> --- a/Documentation/driver-api/cxl/index.rst
> +++ b/Documentation/driver-api/cxl/index.rst
> @@ -12,4 +12,6 @@ Compute Express Link
>  
>     maturity-map
>  
> +   conventions
> +
>  .. only::  subproject and html
> 
> base-commit: a5806cd506af5a7c19bcd596e4708b5c464bfd21

Re: [PATCH] Documentation/driver-api/cxl: Introduce conventions.rst

[Jonathan Cameron]

On Tue, 3 Jun 2025 11:52:54 -0700
Dan Williams <dan.j.williams@intel.com> wrote:

> There exists shipping platforms that bend, break, or otherwise lean on
> ambiguities in the CXL specification. Without driver changes to accommodate
> these deviations, end users are left without CXL subsystem RAS features.
> Specifically, provisioning, error translation, and other flows require the
> CXL subsystem to understand the platforms CXL topology beyond undecorated
> memory address ranges.
> 
> Those isolated compatibility problems risk growing into deeper upstream
> maintenance burden if different platform vendors arrive at diverging
> solutions. For example, there are multiple options for resolving
> low-memory-mmio intersecting large-interleave-ways CXL windows. Linux
> should only entertain one solution to that problem.
> 
> Now, with the ACPI Specification Working Group, situations like this would
> be resolved with the "Code First ECN" process to codify Linux expectations
> in a specification. In the absence of such a process for the CXL
> specification, create a file in Linux documentation to detail the
> motivations, assumptions, tradeoffs, and proposals for amending
> specification language.
> 
> The goal is to capture the issues such that platform vendors arrive at
> compatible solutions for these problems and serve as a repository for
> potential specification updates. The expectation is to update
> conventions.rst along with CXL subsystem code changes to accommodate the
> platform topology.
> 
> Signed-off-by: Dan Williams <dan.j.williams@intel.com>
Seems like a good way to get things going.
Reviewed-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>

Re: [PATCH] Documentation/driver-api/cxl: Introduce conventions.rst

[Dave Jiang]

On 6/3/25 11:52 AM, Dan Williams wrote:
> There exists shipping platforms that bend, break, or otherwise lean on
> ambiguities in the CXL specification. Without driver changes to accommodate
> these deviations, end users are left without CXL subsystem RAS features.
> Specifically, provisioning, error translation, and other flows require the
> CXL subsystem to understand the platforms CXL topology beyond undecorated
> memory address ranges.
> 
> Those isolated compatibility problems risk growing into deeper upstream
> maintenance burden if different platform vendors arrive at diverging
> solutions. For example, there are multiple options for resolving
> low-memory-mmio intersecting large-interleave-ways CXL windows. Linux
> should only entertain one solution to that problem.
> 
> Now, with the ACPI Specification Working Group, situations like this would
> be resolved with the "Code First ECN" process to codify Linux expectations
> in a specification. In the absence of such a process for the CXL
> specification, create a file in Linux documentation to detail the
> motivations, assumptions, tradeoffs, and proposals for amending
> specification language.
> 
> The goal is to capture the issues such that platform vendors arrive at
> compatible solutions for these problems and serve as a repository for
> potential specification updates. The expectation is to update
> conventions.rst along with CXL subsystem code changes to accommodate the
> platform topology.
> 
> Signed-off-by: Dan Williams <dan.j.williams@intel.com>

Applied to cxl/next

Rebased against v6.16-rc1

> ---
>  Documentation/driver-api/cxl/conventions.rst | 48 ++++++++++++++++++++
>  Documentation/driver-api/cxl/index.rst       |  2 +
>  2 files changed, 50 insertions(+)
>  create mode 100644 Documentation/driver-api/cxl/conventions.rst
> 
> diff --git a/Documentation/driver-api/cxl/conventions.rst b/Documentation/driver-api/cxl/conventions.rst
> new file mode 100644
> index 000000000000..662dbaf1f045
> --- /dev/null
> +++ b/Documentation/driver-api/cxl/conventions.rst
> @@ -0,0 +1,48 @@
> +.. 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.
> +
> +<(template) Title>
> +==================
> +
> +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.>
> +
> +
> +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.>
> +
> diff --git a/Documentation/driver-api/cxl/index.rst b/Documentation/driver-api/cxl/index.rst
> index 965ba90e8fb7..721a2dacf8fc 100644
> --- a/Documentation/driver-api/cxl/index.rst
> +++ b/Documentation/driver-api/cxl/index.rst
> @@ -12,4 +12,6 @@ Compute Express Link
>  
>     maturity-map
>  
> +   conventions
> +
>  .. only::  subproject and html
> 
> base-commit: a5806cd506af5a7c19bcd596e4708b5c464bfd21

Re: [PATCH] Documentation/driver-api/cxl: Introduce conventions.rst

[Robert Richter]

Dan,

On 03.06.25 11:52:54, Dan Williams wrote:
> There exists shipping platforms that bend, break, or otherwise lean on
> ambiguities in the CXL specification. Without driver changes to accommodate
> these deviations, end users are left without CXL subsystem RAS features.
> Specifically, provisioning, error translation, and other flows require the
> CXL subsystem to understand the platforms CXL topology beyond undecorated
> memory address ranges.

thank you for addressing and documenting this. That helps following a
process to generalize platform specifics and add them to the spec and
Linux driver.

> 
> Those isolated compatibility problems risk growing into deeper upstream
> maintenance burden if different platform vendors arrive at diverging
> solutions. For example, there are multiple options for resolving
> low-memory-mmio intersecting large-interleave-ways CXL windows. Linux
> should only entertain one solution to that problem.
> 
> Now, with the ACPI Specification Working Group, situations like this would
> be resolved with the "Code First ECN" process to codify Linux expectations
> in a specification. In the absence of such a process for the CXL
> specification, create a file in Linux documentation to detail the
> motivations, assumptions, tradeoffs, and proposals for amending
> specification language.

I have found a collection of ACPI ECNs here:

 https://github.com/pmem/acpi-spec-ecr
 https://github.com/pmem/acpi-spec-ecr/blob/main/cxl-hmat-ext-linear.md

Is there the plan to have a repo like this for CXL? Or just use
Documentation/driver-api/cxl/ for this?

> 
> The goal is to capture the issues such that platform vendors arrive at
> compatible solutions for these problems and serve as a repository for
> potential specification updates. The expectation is to update
> conventions.rst along with CXL subsystem code changes to accommodate the
> platform topology.

Ah, so it will be part of conventions.rst for each ECN, right?

> 
> Signed-off-by: Dan Williams <dan.j.williams@intel.com>

Though it is already applied:

Reviewed-by: Robert Richter <rrichter@amd.com>

> ---
>  Documentation/driver-api/cxl/conventions.rst | 48 ++++++++++++++++++++
>  Documentation/driver-api/cxl/index.rst       |  2 +
>  2 files changed, 50 insertions(+)
>  create mode 100644 Documentation/driver-api/cxl/conventions.rst

Re: [PATCH] Documentation/driver-api/cxl: Introduce conventions.rst

[Dave Jiang]

On 6/10/25 5:54 AM, Robert Richter wrote:
> Dan,
> 
> On 03.06.25 11:52:54, Dan Williams wrote:
>> There exists shipping platforms that bend, break, or otherwise lean on
>> ambiguities in the CXL specification. Without driver changes to accommodate
>> these deviations, end users are left without CXL subsystem RAS features.
>> Specifically, provisioning, error translation, and other flows require the
>> CXL subsystem to understand the platforms CXL topology beyond undecorated
>> memory address ranges.
> 
> thank you for addressing and documenting this. That helps following a
> process to generalize platform specifics and add them to the spec and
> Linux driver.
> 
>>
>> Those isolated compatibility problems risk growing into deeper upstream
>> maintenance burden if different platform vendors arrive at diverging
>> solutions. For example, there are multiple options for resolving
>> low-memory-mmio intersecting large-interleave-ways CXL windows. Linux
>> should only entertain one solution to that problem.
>>
>> Now, with the ACPI Specification Working Group, situations like this would
>> be resolved with the "Code First ECN" process to codify Linux expectations
>> in a specification. In the absence of such a process for the CXL
>> specification, create a file in Linux documentation to detail the
>> motivations, assumptions, tradeoffs, and proposals for amending
>> specification language.
> 
> I have found a collection of ACPI ECNs here:
> 
>  https://github.com/pmem/acpi-spec-ecr
>  https://github.com/pmem/acpi-spec-ecr/blob/main/cxl-hmat-ext-linear.md
> 
> Is there the plan to have a repo like this for CXL? Or just use
> Documentation/driver-api/cxl/ for this?
> 
>>
>> The goal is to capture the issues such that platform vendors arrive at
>> compatible solutions for these problems and serve as a repository for
>> potential specification updates. The expectation is to update
>> conventions.rst along with CXL subsystem code changes to accommodate the
>> platform topology.
> 
> Ah, so it will be part of conventions.rst for each ECN, right?
> 
>>
>> Signed-off-by: Dan Williams <dan.j.williams@intel.com>
> 
> Though it is already applied:
> 
> Reviewed-by: Robert Richter <rrichter@amd.com>

I had to fix something for linux-next, so I applied your review tag.

DJ

> 
>> ---
>>  Documentation/driver-api/cxl/conventions.rst | 48 ++++++++++++++++++++
>>  Documentation/driver-api/cxl/index.rst       |  2 +
>>  2 files changed, 50 insertions(+)
>>  create mode 100644 Documentation/driver-api/cxl/conventions.rst