[PATCH] Documentation: cxl: fix typos and improve clarity in memory-devices.rst

[PATCH] Documentation: cxl: fix typos and improve clarity in memory-devices.rst

[Alok Tiwari]

This patch corrects several typographical issues and improves phrasing
in memory-devices.rst:

- Fixes duplicate word ("1 one") and adjusts phrasing for clarity.
- Adds missing hyphen in "on-device".
- Corrects "a give memory device" to "a given memory device".
- fix singular/plural "decoder resource" -> "decoder resources".
- Clarifies "spans to Host Bridges" -> "spans two Host Bridges".

These changes improve readability and accuracy of the documentation.

Signed-off-by: Alok Tiwari <alok.a.tiwari@oracle.com>
---
 Documentation/driver-api/cxl/memory-devices.rst | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/driver-api/cxl/memory-devices.rst b/Documentation/driver-api/cxl/memory-devices.rst
index d732c42526df..e9e2952a967d 100644
--- a/Documentation/driver-api/cxl/memory-devices.rst
+++ b/Documentation/driver-api/cxl/memory-devices.rst
@@ -29,8 +29,8 @@ Platform firmware enumerates a menu of interleave options at the "CXL root port"
 (Linux term for the top of the CXL decode topology). From there, PCIe topology
 dictates which endpoints can participate in which Host Bridge decode regimes.
 Each PCIe Switch in the path between the root and an endpoint introduces a point
-at which the interleave can be split. For example platform firmware may say at a
-given range only decodes to 1 one Host Bridge, but that Host Bridge may in turn
+at which the interleave can be split. For example, platform firmware may say at a
+given range only decodes to one Host Bridge, but that Host Bridge may in turn
 interleave cycles across multiple Root Ports. An intervening Switch between a
 port and an endpoint may interleave cycles across multiple Downstream Switch
 Ports, etc.
@@ -187,7 +187,7 @@ decodes them to "ports", "ports" decode to "endpoints", and "endpoints"
 represent the decode from SPA (System Physical Address) to DPA (Device Physical
 Address).
 
-Continuing the RAID analogy, disks have both topology metadata and on device
+Continuing the RAID analogy, disks have both topology metadata and on-device
 metadata that determine RAID set assembly. CXL Port topology and CXL Port link
 status is metadata for CXL.mem set assembly. The CXL Port topology is enumerated
 by the arrival of a CXL.mem device. I.e. unless and until the PCIe core attaches
@@ -197,7 +197,7 @@ the Linux PCI core to tear down switch-level CXL resources because the endpoint
 ->remove() event cleans up the port data that was established to support that
 Memory Expander.
 
-The port metadata and potential decode schemes that a give memory device may
+The port metadata and potential decode schemes that a given memory device may
 participate can be determined via a command like::
 
     # cxl list -BDMu -d root -m mem3
@@ -249,8 +249,8 @@ participate can be determined via a command like::
 ...which queries the CXL topology to ask "given CXL Memory Expander with a kernel
 device name of 'mem3' which platform level decode ranges may this device
 participate". A given expander can participate in multiple CXL.mem interleave
-sets simultaneously depending on how many decoder resource it has. In this
-example mem3 can participate in one or more of a PMEM interleave that spans to
+sets simultaneously depending on how many decoder resources it has. In this
+example mem3 can participate in one or more of a PMEM interleave that spans two
 Host Bridges, a PMEM interleave that targets a single Host Bridge, a Volatile
 memory interleave that spans 2 Host Bridges, and a Volatile memory interleave
 that only targets a single Host Bridge.
-- 
2.47.1

Re: [PATCH] Documentation: cxl: fix typos and improve clarity in memory-devices.rst

[Randy Dunlap]

On 5/31/25 12:51 AM, Alok Tiwari wrote:
> This patch corrects several typographical issues and improves phrasing
> in memory-devices.rst:
> 
> - Fixes duplicate word ("1 one") and adjusts phrasing for clarity.
> - Adds missing hyphen in "on-device".
> - Corrects "a give memory device" to "a given memory device".
> - fix singular/plural "decoder resource" -> "decoder resources".
> - Clarifies "spans to Host Bridges" -> "spans two Host Bridges".
> 
> These changes improve readability and accuracy of the documentation.
> 
> Signed-off-by: Alok Tiwari <alok.a.tiwari@oracle.com>

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

(This time not in html.)


> ---
>  Documentation/driver-api/cxl/memory-devices.rst | 12 ++++++------
>  1 file changed, 6 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/driver-api/cxl/memory-devices.rst b/Documentation/driver-api/cxl/memory-devices.rst
> index d732c42526df..e9e2952a967d 100644
> --- a/Documentation/driver-api/cxl/memory-devices.rst
> +++ b/Documentation/driver-api/cxl/memory-devices.rst
> @@ -29,8 +29,8 @@ Platform firmware enumerates a menu of interleave options at the "CXL root port"
>  (Linux term for the top of the CXL decode topology). From there, PCIe topology
>  dictates which endpoints can participate in which Host Bridge decode regimes.
>  Each PCIe Switch in the path between the root and an endpoint introduces a point
> -at which the interleave can be split. For example platform firmware may say at a
> -given range only decodes to 1 one Host Bridge, but that Host Bridge may in turn
> +at which the interleave can be split. For example, platform firmware may say at a
> +given range only decodes to one Host Bridge, but that Host Bridge may in turn
>  interleave cycles across multiple Root Ports. An intervening Switch between a
>  port and an endpoint may interleave cycles across multiple Downstream Switch
>  Ports, etc.
> @@ -187,7 +187,7 @@ decodes them to "ports", "ports" decode to "endpoints", and "endpoints"
>  represent the decode from SPA (System Physical Address) to DPA (Device Physical
>  Address).
>  
> -Continuing the RAID analogy, disks have both topology metadata and on device
> +Continuing the RAID analogy, disks have both topology metadata and on-device
>  metadata that determine RAID set assembly. CXL Port topology and CXL Port link
>  status is metadata for CXL.mem set assembly. The CXL Port topology is enumerated
>  by the arrival of a CXL.mem device. I.e. unless and until the PCIe core attaches
> @@ -197,7 +197,7 @@ the Linux PCI core to tear down switch-level CXL resources because the endpoint
>  ->remove() event cleans up the port data that was established to support that
>  Memory Expander.
>  
> -The port metadata and potential decode schemes that a give memory device may
> +The port metadata and potential decode schemes that a given memory device may
>  participate can be determined via a command like::
>  
>      # cxl list -BDMu -d root -m mem3
> @@ -249,8 +249,8 @@ participate can be determined via a command like::
>  ...which queries the CXL topology to ask "given CXL Memory Expander with a kernel
>  device name of 'mem3' which platform level decode ranges may this device
>  participate". A given expander can participate in multiple CXL.mem interleave
> -sets simultaneously depending on how many decoder resource it has. In this
> -example mem3 can participate in one or more of a PMEM interleave that spans to
> +sets simultaneously depending on how many decoder resources it has. In this
> +example mem3 can participate in one or more of a PMEM interleave that spans two
>  Host Bridges, a PMEM interleave that targets a single Host Bridge, a Volatile
>  memory interleave that spans 2 Host Bridges, and a Volatile memory interleave
>  that only targets a single Host Bridge.

-- 
~Randy

Re: [PATCH] Documentation: cxl: fix typos and improve clarity in memory-devices.rst

[Gregory Price]

On Sat, May 31, 2025 at 12:51:58AM -0700, Alok Tiwari wrote:
> This patch corrects several typographical issues and improves phrasing
> in memory-devices.rst:
> 
> - Fixes duplicate word ("1 one") and adjusts phrasing for clarity.
> - Adds missing hyphen in "on-device".
> - Corrects "a give memory device" to "a given memory device".
> - fix singular/plural "decoder resource" -> "decoder resources".
> - Clarifies "spans to Host Bridges" -> "spans two Host Bridges".
> 
> These changes improve readability and accuracy of the documentation.
> 
> Signed-off-by: Alok Tiwari <alok.a.tiwari@oracle.com>
> ---
>  Documentation/driver-api/cxl/memory-devices.rst | 12 ++++++------
>  1 file changed, 6 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/driver-api/cxl/memory-devices.rst b/Documentation/driver-api/cxl/memory-devices.rst
> index d732c42526df..e9e2952a967d 100644
> --- a/Documentation/driver-api/cxl/memory-devices.rst
> +++ b/Documentation/driver-api/cxl/memory-devices.rst
> @@ -29,8 +29,8 @@ Platform firmware enumerates a menu of interleave options at the "CXL root port"
>  (Linux term for the top of the CXL decode topology). From there, PCIe topology
>  dictates which endpoints can participate in which Host Bridge decode regimes.
>  Each PCIe Switch in the path between the root and an endpoint introduces a point
> -at which the interleave can be split. For example platform firmware may say at a
> -given range only decodes to 1 one Host Bridge, but that Host Bridge may in turn
> +at which the interleave can be split. For example, platform firmware may say at a
                                                                                ^^^^
If you wouldn't mind, can you also change:                           "at a"  - >  "a"

Otherwise

Reviewed-by: Gregory Price <gourry@gourry.net>

Re: [PATCH] Documentation: cxl: fix typos and improve clarity in memory-devices.rst

[ALOK TIWARI]

Thanks Gregory,

On 02-06-2025 05:00, Gregory Price wrote:
> On Sat, May 31, 2025 at 12:51:58AM -0700, Alok Tiwari wrote:
>> This patch corrects several typographical issues and improves phrasing
>> in memory-devices.rst:
>>
>> - Fixes duplicate word ("1 one") and adjusts phrasing for clarity.
>> - Adds missing hyphen in "on-device".
>> - Corrects "a give memory device" to "a given memory device".
>> - fix singular/plural "decoder resource" -> "decoder resources".
>> - Clarifies "spans to Host Bridges" -> "spans two Host Bridges".
>>
>> These changes improve readability and accuracy of the documentation.
>>
>> Signed-off-by: Alok Tiwari <alok.a.tiwari@oracle.com>
>> ---
>>   Documentation/driver-api/cxl/memory-devices.rst | 12 ++++++------
>>   1 file changed, 6 insertions(+), 6 deletions(-)
>>
>> diff --git a/Documentation/driver-api/cxl/memory-devices.rst b/Documentation/driver-api/cxl/memory-devices.rst
>> index d732c42526df..e9e2952a967d 100644
>> --- a/Documentation/driver-api/cxl/memory-devices.rst
>> +++ b/Documentation/driver-api/cxl/memory-devices.rst
>> @@ -29,8 +29,8 @@ Platform firmware enumerates a menu of interleave options at the "CXL root port"
>>   (Linux term for the top of the CXL decode topology). From there, PCIe topology
>>   dictates which endpoints can participate in which Host Bridge decode regimes.
>>   Each PCIe Switch in the path between the root and an endpoint introduces a point
>> -at which the interleave can be split. For example platform firmware may say at a
>> -given range only decodes to 1 one Host Bridge, but that Host Bridge may in turn
>> +at which the interleave can be split. For example, platform firmware may say at a
>                                                                                  ^^^^
> If you wouldn't mind, can you also change:                           "at a"  - >  "a"

I will replace "at a" with "a"

> 
> Otherwise
> 
> Reviewed-by: Gregory Price <gourry@gourry.net>


Thanks,
Alok

Re: [PATCH] Documentation: cxl: fix typos and improve clarity in memory-devices.rst

[Jonathan Cameron]

On Sat, 31 May 2025 00:51:58 -0700
Alok Tiwari <alok.a.tiwari@oracle.com> wrote:

> This patch corrects several typographical issues and improves phrasing
> in memory-devices.rst:
> 
> - Fixes duplicate word ("1 one") and adjusts phrasing for clarity.
> - Adds missing hyphen in "on-device".
> - Corrects "a give memory device" to "a given memory device".
> - fix singular/plural "decoder resource" -> "decoder resources".
> - Clarifies "spans to Host Bridges" -> "spans two Host Bridges".
> 
> These changes improve readability and accuracy of the documentation.
> 
> Signed-off-by: Alok Tiwari <alok.a.tiwari@oracle.com>
One additional comment given you are touching this text.

Reviewed-by: Jonathan Cameron <jonathan.cameron@huawei.com>
> ---
>  Documentation/driver-api/cxl/memory-devices.rst | 12 ++++++------
>  1 file changed, 6 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/driver-api/cxl/memory-devices.rst b/Documentation/driver-api/cxl/memory-devices.rst
> index d732c42526df..e9e2952a967d 100644
> --- a/Documentation/driver-api/cxl/memory-devices.rst
> +++ b/Documentation/driver-api/cxl/memory-devices.rst
> @@ -29,8 +29,8 @@ Platform firmware enumerates a menu of interleave options at the "CXL root port"
>  (Linux term for the top of the CXL decode topology). From there, PCIe topology
>  dictates which endpoints can participate in which Host Bridge decode regimes.
>  Each PCIe Switch in the path between the root and an endpoint introduces a point
> -at which the interleave can be split. For example platform firmware may say at a
> -given range only decodes to 1 one Host Bridge, but that Host Bridge may in turn
> +at which the interleave can be split. For example, platform firmware may say at a

Should probably be "platform firmware may say that a given range"

> +given range only decodes to one Host Bridge, but that Host Bridge may in turn
>  interleave cycles across multiple Root Ports. An intervening Switch between a
>  port and an endpoint may interleave cycles across multiple Downstream Switch
>  Ports, etc.
> @@ -187,7 +187,7 @@ decodes them to "ports", "ports" decode to "endpoints", and "endpoints"
>  represent the decode from SPA (System Physical Address) to DPA (Device Physical
>  Address).
>  
> -Continuing the RAID analogy, disks have both topology metadata and on device
> +Continuing the RAID analogy, disks have both topology metadata and on-device
>  metadata that determine RAID set assembly. CXL Port topology and CXL Port link
>  status is metadata for CXL.mem set assembly. The CXL Port topology is enumerated
>  by the arrival of a CXL.mem device. I.e. unless and until the PCIe core attaches
> @@ -197,7 +197,7 @@ the Linux PCI core to tear down switch-level CXL resources because the endpoint
>  ->remove() event cleans up the port data that was established to support that  
>  Memory Expander.
>  
> -The port metadata and potential decode schemes that a give memory device may
> +The port metadata and potential decode schemes that a given memory device may
>  participate can be determined via a command like::
>  
>      # cxl list -BDMu -d root -m mem3
> @@ -249,8 +249,8 @@ participate can be determined via a command like::
>  ...which queries the CXL topology to ask "given CXL Memory Expander with a kernel
>  device name of 'mem3' which platform level decode ranges may this device
>  participate". A given expander can participate in multiple CXL.mem interleave
> -sets simultaneously depending on how many decoder resource it has. In this
> -example mem3 can participate in one or more of a PMEM interleave that spans to
> +sets simultaneously depending on how many decoder resources it has. In this
> +example mem3 can participate in one or more of a PMEM interleave that spans two
>  Host Bridges, a PMEM interleave that targets a single Host Bridge, a Volatile
>  memory interleave that spans 2 Host Bridges, and a Volatile memory interleave
>  that only targets a single Host Bridge.

Re: [PATCH] Documentation: cxl: fix typos and improve clarity in memory-devices.rst

[ALOK TIWARI]

I really appreciate your review, thanks a lot!

On 09-06-2025 16:28, Jonathan Cameron wrote:
>> These changes improve readability and accuracy of the documentation.
>>
>> Signed-off-by: Alok Tiwari<alok.a.tiwari@oracle.com>
> One additional comment given you are touching this text.
> 
> Reviewed-by: Jonathan Cameron<jonathan.cameron@huawei.com>
>> ---
>>   Documentation/driver-api/cxl/memory-devices.rst | 12 ++++++------
>>   1 file changed, 6 insertions(+), 6 deletions(-)
>>
>> diff --git a/Documentation/driver-api/cxl/memory-devices.rst b/Documentation/driver-api/cxl/memory-devices.rst
>> index d732c42526df..e9e2952a967d 100644
>> --- a/Documentation/driver-api/cxl/memory-devices.rst
>> +++ b/Documentation/driver-api/cxl/memory-devices.rst
>> @@ -29,8 +29,8 @@ Platform firmware enumerates a menu of interleave options at the "CXL root port"
>>   (Linux term for the top of the CXL decode topology). From there, PCIe topology
>>   dictates which endpoints can participate in which Host Bridge decode regimes.
>>   Each PCIe Switch in the path between the root and an endpoint introduces a point
>> -at which the interleave can be split. For example platform firmware may say at a
>> -given range only decodes to 1 one Host Bridge, but that Host Bridge may in turn
>> +at which the interleave can be split. For example, platform firmware may say at a
> Should probably be "platform firmware may say that a given range"

"We addressed these parts based on Gregory Price's comments and 
submitted version 2 of the patch."
use phrase -> "platform firmware may say a given range only"

> 
>> +given range only decodes to one Host Bridge, but that Host Bridge may in turn
>>   interleave cycles across multiple Root Ports. An intervening Switch between a
>>   port and an endpoint may interleave cycles across multiple Downstream Switch
>>   Ports, etc.
>> @@ -187,7 +187,7 @@ decodes them to "ports", "ports" decode to "endpoints", and "endpoints"
>>   represent the decode from SPA (System Physical Address) to DPA (Device Physical
>>   Address).


Thanks,
Alok

Re: [PATCH] Documentation: cxl: fix typos and improve clarity in memory-devices.rst

[Dave Jiang]

On 5/31/25 12:51 AM, Alok Tiwari wrote:
> This patch corrects several typographical issues and improves phrasing
> in memory-devices.rst:
> 
> - Fixes duplicate word ("1 one") and adjusts phrasing for clarity.
> - Adds missing hyphen in "on-device".
> - Corrects "a give memory device" to "a given memory device".
> - fix singular/plural "decoder resource" -> "decoder resources".
> - Clarifies "spans to Host Bridges" -> "spans two Host Bridges".
> 
> These changes improve readability and accuracy of the documentation.
> 
> Signed-off-by: Alok Tiwari <alok.a.tiwari@oracle.com>

Can you please rebase the changes against v6.16-rc1? memory-devices.rst no longer exists.


> ---
>  Documentation/driver-api/cxl/memory-devices.rst | 12 ++++++------
>  1 file changed, 6 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/driver-api/cxl/memory-devices.rst b/Documentation/driver-api/cxl/memory-devices.rst
> index d732c42526df..e9e2952a967d 100644
> --- a/Documentation/driver-api/cxl/memory-devices.rst
> +++ b/Documentation/driver-api/cxl/memory-devices.rst
> @@ -29,8 +29,8 @@ Platform firmware enumerates a menu of interleave options at the "CXL root port"
>  (Linux term for the top of the CXL decode topology). From there, PCIe topology
>  dictates which endpoints can participate in which Host Bridge decode regimes.
>  Each PCIe Switch in the path between the root and an endpoint introduces a point
> -at which the interleave can be split. For example platform firmware may say at a
> -given range only decodes to 1 one Host Bridge, but that Host Bridge may in turn
> +at which the interleave can be split. For example, platform firmware may say at a
> +given range only decodes to one Host Bridge, but that Host Bridge may in turn
>  interleave cycles across multiple Root Ports. An intervening Switch between a
>  port and an endpoint may interleave cycles across multiple Downstream Switch
>  Ports, etc.
> @@ -187,7 +187,7 @@ decodes them to "ports", "ports" decode to "endpoints", and "endpoints"
>  represent the decode from SPA (System Physical Address) to DPA (Device Physical
>  Address).
>  
> -Continuing the RAID analogy, disks have both topology metadata and on device
> +Continuing the RAID analogy, disks have both topology metadata and on-device
>  metadata that determine RAID set assembly. CXL Port topology and CXL Port link
>  status is metadata for CXL.mem set assembly. The CXL Port topology is enumerated
>  by the arrival of a CXL.mem device. I.e. unless and until the PCIe core attaches
> @@ -197,7 +197,7 @@ the Linux PCI core to tear down switch-level CXL resources because the endpoint
>  ->remove() event cleans up the port data that was established to support that
>  Memory Expander.
>  
> -The port metadata and potential decode schemes that a give memory device may
> +The port metadata and potential decode schemes that a given memory device may
>  participate can be determined via a command like::
>  
>      # cxl list -BDMu -d root -m mem3
> @@ -249,8 +249,8 @@ participate can be determined via a command like::
>  ...which queries the CXL topology to ask "given CXL Memory Expander with a kernel
>  device name of 'mem3' which platform level decode ranges may this device
>  participate". A given expander can participate in multiple CXL.mem interleave
> -sets simultaneously depending on how many decoder resource it has. In this
> -example mem3 can participate in one or more of a PMEM interleave that spans to
> +sets simultaneously depending on how many decoder resources it has. In this
> +example mem3 can participate in one or more of a PMEM interleave that spans two
>  Host Bridges, a PMEM interleave that targets a single Host Bridge, a Volatile
>  memory interleave that spans 2 Host Bridges, and a Volatile memory interleave
>  that only targets a single Host Bridge.