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

[PATCH v2] 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 by escaping it.
2) Add cxl_acpi_evaluate_qtg_dsm to access-coordinates.rst.

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

Signed-off-by: Alison Schofield <alison.schofield@intel.com>
Reviewed-by: Ira Weiny <ira.weiny@intel.com>
---

Change in v2:
- rebased on cxl/next with Gregory's Boot to Bash


 .../cxl/linux/access-coordinates.rst           |  3 +++
 .../driver-api/cxl/theory-of-operation.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/linux/access-coordinates.rst b/Documentation/driver-api/cxl/linux/access-coordinates.rst
index 71024fa0f561..7f949cc4ece5 100644
--- a/Documentation/driver-api/cxl/linux/access-coordinates.rst
+++ b/Documentation/driver-api/cxl/linux/access-coordinates.rst
@@ -90,3 +90,6 @@ under the same 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/theory-of-operation.rst b/Documentation/driver-api/cxl/theory-of-operation.rst
index 32739e253453..1b854b11f575 100644
--- a/Documentation/driver-api/cxl/theory-of-operation.rst
+++ b/Documentation/driver-api/cxl/theory-of-operation.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 v2] cxl: Sync up the driver-api/cxl documentation

[Dave Jiang]

On 5/13/25 2: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 by escaping it.
> 2) Add cxl_acpi_evaluate_qtg_dsm to access-coordinates.rst.
> 
> core/features.c is new. Add a "DOC: cxl features" comment to the
> source and identifiers to memory_devices.rst.
> 
> Signed-off-by: Alison Schofield <alison.schofield@intel.com>
> Reviewed-by: Ira Weiny <ira.weiny@intel.com>

Applied to cxl/next

> ---
> 
> Change in v2:
> - rebased on cxl/next with Gregory's Boot to Bash
> 
> 
>  .../cxl/linux/access-coordinates.rst           |  3 +++
>  .../driver-api/cxl/theory-of-operation.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/linux/access-coordinates.rst b/Documentation/driver-api/cxl/linux/access-coordinates.rst
> index 71024fa0f561..7f949cc4ece5 100644
> --- a/Documentation/driver-api/cxl/linux/access-coordinates.rst
> +++ b/Documentation/driver-api/cxl/linux/access-coordinates.rst
> @@ -90,3 +90,6 @@ under the same 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/theory-of-operation.rst b/Documentation/driver-api/cxl/theory-of-operation.rst
> index 32739e253453..1b854b11f575 100644
> --- a/Documentation/driver-api/cxl/theory-of-operation.rst
> +++ b/Documentation/driver-api/cxl/theory-of-operation.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,