[PATCH] cxl: Sync up the driver-api/cxl documentation

[PATCH] cxl: Sync up the driver-api/cxl documentation

[alison.schofield]

From: Alison Schofield <alison.schofield@intel.com>

pmem.c regs.c mbox.c identifiers were missing. Add them to
memory-devices.rst following their respective DOC comment includes.

Two acpi.c identifiers were available, but not used in kernel-doc's:
1) Add add_cxl_resources to memory-devices.rst and fix up the Sphinx
complaint on the ascii art (escape and indent the pipes).
2) Add cxl_acpi_evaluate_qtg_dsm to access-coordinates.rst.

core/features.c is newish. Add a "DOC: cxl features" comment to the
source and the doc and identifiers to memory_devices.rst.

Signed-off-by: Alison Schofield <alison.schofield@intel.com>
---

DaveJ: the "DOC: cxl features" addition was simply a copy from the
Kconfig file. Please take a look and I can update.


 .../driver-api/cxl/access-coordinates.rst      |  3 +++
 .../driver-api/cxl/memory-devices.rst          | 18 ++++++++++++++++++
 drivers/cxl/acpi.c                             |  6 +++---
 drivers/cxl/core/features.c                    |  9 +++++++++
 4 files changed, 33 insertions(+), 3 deletions(-)

diff --git a/Documentation/driver-api/cxl/access-coordinates.rst b/Documentation/driver-api/cxl/access-coordinates.rst
index b07950ea30c9..5f2ad093fabe 100644
--- a/Documentation/driver-api/cxl/access-coordinates.rst
+++ b/Documentation/driver-api/cxl/access-coordinates.rst
@@ -89,3 +89,6 @@ ACPI0017 device to form a new xarray.
 Finally, the cxl_region_update_bandwidth() is called and the aggregated
 bandwidth from all the members of the last xarray is updated for the
 access coordinates residing in the cxl region (cxlr) context.
+
+.. kernel-doc:: drivers/cxl/acpi.c
+   :identifiers: cxl_acpi_evaluate_qtg_dsm
diff --git a/Documentation/driver-api/cxl/memory-devices.rst b/Documentation/driver-api/cxl/memory-devices.rst
index d732c42526df..f378a5d7ba40 100644
--- a/Documentation/driver-api/cxl/memory-devices.rst
+++ b/Documentation/driver-api/cxl/memory-devices.rst
@@ -347,6 +347,9 @@ CXL Core
 .. kernel-doc:: drivers/cxl/cxl.h
    :internal:
 
+.. kernel-doc:: drivers/cxl/acpi.c
+   :identifiers: add_cxl_resources
+
 .. kernel-doc:: drivers/cxl/core/hdm.c
    :doc: cxl core hdm
 
@@ -371,12 +374,27 @@ CXL Core
 .. kernel-doc:: drivers/cxl/core/pmem.c
    :doc: cxl pmem
 
+.. kernel-doc:: drivers/cxl/core/pmem.c
+   :identifiers:
+
 .. kernel-doc:: drivers/cxl/core/regs.c
    :doc: cxl registers
 
+.. kernel-doc:: drivers/cxl/core/regs.c
+   :identifiers:
+
 .. kernel-doc:: drivers/cxl/core/mbox.c
    :doc: cxl mbox
 
+.. kernel-doc:: drivers/cxl/core/mbox.c
+   :identifiers:
+
+.. kernel-doc:: drivers/cxl/core/features.c
+   :doc: cxl features
+
+.. kernel-doc:: drivers/cxl/core/features.c
+   :identifiers:
+
 CXL Regions
 -----------
 .. kernel-doc:: drivers/cxl/core/region.c
diff --git a/drivers/cxl/acpi.c b/drivers/cxl/acpi.c
index 587ad5289f7e..a1a99ec3f12c 100644
--- a/drivers/cxl/acpi.c
+++ b/drivers/cxl/acpi.c
@@ -749,10 +749,10 @@ static void remove_cxl_resources(void *data)
  * expanding its boundaries to ensure that any conflicting resources become
  * children. If a window is expanded it may then conflict with a another window
  * entry and require the window to be truncated or trimmed. Consider this
- * situation:
+ * situation::
  *
- * |-- "CXL Window 0" --||----- "CXL Window 1" -----|
- * |--------------- "System RAM" -------------|
+ *	|-- "CXL Window 0" --||----- "CXL Window 1" -----|
+ *	|--------------- "System RAM" -------------|
  *
  * ...where platform firmware has established as System RAM resource across 2
  * windows, but has left some portion of window 1 for dynamic CXL region
diff --git a/drivers/cxl/core/features.c b/drivers/cxl/core/features.c
index bdc2c492bdff..5461cf07e65c 100644
--- a/drivers/cxl/core/features.c
+++ b/drivers/cxl/core/features.c
@@ -9,6 +9,15 @@
 #include "core.h"
 #include "cxlmem.h"
 
+/**
+ * DOC: cxl features
+ *
+ * A CXL device that includes a mailbox supports commands that allows
+ * listing, getting, and setting of optionally defined features such
+ * as memory sparing or post package sparing. Vendors may define custom
+ * features for the device.
+ */
+
 /* All the features below are exclusive to the kernel */
 static const uuid_t cxl_exclusive_feats[] = {
 	CXL_FEAT_PATROL_SCRUB_UUID,
-- 
2.37.3

Re: [PATCH] cxl: Sync up the driver-api/cxl documentation

[Dave Jiang]

On 5/12/25 4:58 PM, alison.schofield@intel.com wrote:
> From: Alison Schofield <alison.schofield@intel.com>
> 
> pmem.c regs.c mbox.c identifiers were missing. Add them to
> memory-devices.rst following their respective DOC comment includes.
> 
> Two acpi.c identifiers were available, but not used in kernel-doc's:
> 1) Add add_cxl_resources to memory-devices.rst and fix up the Sphinx
> complaint on the ascii art (escape and indent the pipes).
> 2) Add cxl_acpi_evaluate_qtg_dsm to access-coordinates.rst.
> 
> core/features.c is newish. Add a "DOC: cxl features" comment to the
> source and the doc and identifiers to memory_devices.rst.
> 
> Signed-off-by: Alison Schofield <alison.schofield@intel.com>
> ---
> 
> DaveJ: the "DOC: cxl features" addition was simply a copy from the
> Kconfig file. Please take a look and I can update.
> 
> 
>  .../driver-api/cxl/access-coordinates.rst      |  3 +++
>  .../driver-api/cxl/memory-devices.rst          | 18 ++++++++++++++++++
>  drivers/cxl/acpi.c                             |  6 +++---
>  drivers/cxl/core/features.c                    |  9 +++++++++
>  4 files changed, 33 insertions(+), 3 deletions(-)

Looks good to me. Although I wonder if you will want to coordinate with Gregory as he's moving some stuff around in his doc series.


> 
> diff --git a/Documentation/driver-api/cxl/access-coordinates.rst b/Documentation/driver-api/cxl/access-coordinates.rst
> index b07950ea30c9..5f2ad093fabe 100644
> --- a/Documentation/driver-api/cxl/access-coordinates.rst
> +++ b/Documentation/driver-api/cxl/access-coordinates.rst
> @@ -89,3 +89,6 @@ ACPI0017 device to form a new xarray.
>  Finally, the cxl_region_update_bandwidth() is called and the aggregated
>  bandwidth from all the members of the last xarray is updated for the
>  access coordinates residing in the cxl region (cxlr) context.
> +
> +.. kernel-doc:: drivers/cxl/acpi.c
> +   :identifiers: cxl_acpi_evaluate_qtg_dsm
> diff --git a/Documentation/driver-api/cxl/memory-devices.rst b/Documentation/driver-api/cxl/memory-devices.rst
> index d732c42526df..f378a5d7ba40 100644
> --- a/Documentation/driver-api/cxl/memory-devices.rst
> +++ b/Documentation/driver-api/cxl/memory-devices.rst
> @@ -347,6 +347,9 @@ CXL Core
>  .. kernel-doc:: drivers/cxl/cxl.h
>     :internal:
>  
> +.. kernel-doc:: drivers/cxl/acpi.c
> +   :identifiers: add_cxl_resources
> +
>  .. kernel-doc:: drivers/cxl/core/hdm.c
>     :doc: cxl core hdm
>  
> @@ -371,12 +374,27 @@ CXL Core
>  .. kernel-doc:: drivers/cxl/core/pmem.c
>     :doc: cxl pmem
>  
> +.. kernel-doc:: drivers/cxl/core/pmem.c
> +   :identifiers:
> +
>  .. kernel-doc:: drivers/cxl/core/regs.c
>     :doc: cxl registers
>  
> +.. kernel-doc:: drivers/cxl/core/regs.c
> +   :identifiers:
> +
>  .. kernel-doc:: drivers/cxl/core/mbox.c
>     :doc: cxl mbox
>  
> +.. kernel-doc:: drivers/cxl/core/mbox.c
> +   :identifiers:
> +
> +.. kernel-doc:: drivers/cxl/core/features.c
> +   :doc: cxl features
> +
> +.. kernel-doc:: drivers/cxl/core/features.c
> +   :identifiers:
> +
>  CXL Regions
>  -----------
>  .. kernel-doc:: drivers/cxl/core/region.c
> diff --git a/drivers/cxl/acpi.c b/drivers/cxl/acpi.c
> index 587ad5289f7e..a1a99ec3f12c 100644
> --- a/drivers/cxl/acpi.c
> +++ b/drivers/cxl/acpi.c
> @@ -749,10 +749,10 @@ static void remove_cxl_resources(void *data)
>   * expanding its boundaries to ensure that any conflicting resources become
>   * children. If a window is expanded it may then conflict with a another window
>   * entry and require the window to be truncated or trimmed. Consider this
> - * situation:
> + * situation::
>   *
> - * |-- "CXL Window 0" --||----- "CXL Window 1" -----|
> - * |--------------- "System RAM" -------------|
> + *	|-- "CXL Window 0" --||----- "CXL Window 1" -----|
> + *	|--------------- "System RAM" -------------|
>   *
>   * ...where platform firmware has established as System RAM resource across 2
>   * windows, but has left some portion of window 1 for dynamic CXL region
> diff --git a/drivers/cxl/core/features.c b/drivers/cxl/core/features.c
> index bdc2c492bdff..5461cf07e65c 100644
> --- a/drivers/cxl/core/features.c
> +++ b/drivers/cxl/core/features.c
> @@ -9,6 +9,15 @@
>  #include "core.h"
>  #include "cxlmem.h"
>  
> +/**
> + * DOC: cxl features
> + *
> + * A CXL device that includes a mailbox supports commands that allows
> + * listing, getting, and setting of optionally defined features such
> + * as memory sparing or post package sparing. Vendors may define custom
> + * features for the device.
> + */
> +
>  /* All the features below are exclusive to the kernel */
>  static const uuid_t cxl_exclusive_feats[] = {
>  	CXL_FEAT_PATROL_SCRUB_UUID,

Re: [PATCH] cxl: Sync up the driver-api/cxl documentation

[Ira Weiny]

alison.schofield@ wrote:
> From: Alison Schofield <alison.schofield@intel.com>
> 
> pmem.c regs.c mbox.c identifiers were missing. Add them to
> memory-devices.rst following their respective DOC comment includes.
> 
> Two acpi.c identifiers were available, but not used in kernel-doc's:
> 1) Add add_cxl_resources to memory-devices.rst and fix up the Sphinx
> complaint on the ascii art (escape and indent the pipes).
> 2) Add cxl_acpi_evaluate_qtg_dsm to access-coordinates.rst.
> 
> core/features.c is newish. Add a "DOC: cxl features" comment to the
> source and the doc and identifiers to memory_devices.rst.
> 
> Signed-off-by: Alison Schofield <alison.schofield@intel.com>

With coordination with Gregory.

Reviewed-by: Ira Weiny <ira.weiny@intel.com>

[snip]