Skip to contentSkip to conversation

cxl: documentation fixes

PATCH Applied Bagas Sanjaya 3 participants 8 messages Aug 4, 2022 – Aug 5, 2022

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

cover cxl: documentation fixes

Building htmldocs on next-20220803 (for which this series is based on), there are new warnings on cxl subsystem. The fixes below are self-explanatory.

Bagas Sanjaya (3):
cxl/regions: add padding for cxl_rr_ep_add nested lists cxl/region: describe targets and nr_targets members of
cxl_region_params
Documentation: cxl: remove dangling kernel-doc reference

 Documentation/driver-api/cxl/memory-devices.rst | 3 ---
 drivers/cxl/core/region.c                       | 3 +++
 drivers/cxl/cxl.h                               | 2 ++
 3 files changed, 5 insertions(+), 3 deletions(-)

base-commit: 861397378de91c64dec69a160595b891f443294f

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#1 lore raw

PATCH 1/3 cxl/regions: add padding for cxl_rr_ep_add nested lists

Sphinx reported indentation warnings:

Documentation/driver-api/cxl/memory-devices:457: ./drivers/cxl/core/region.c:732: WARNING: Unexpected indentation. Documentation/driver-api/cxl/memory-devices:457: ./drivers/cxl/core/region.c:733: WARNING: Block quote ends without a blank line; unexpected unindent. Documentation/driver-api/cxl/memory-devices:457: ./drivers/cxl/core/region.c:735: WARNING: Unexpected indentation.

These warnings above are due to missing blank line padding in the nested list in kernel-doc comment for cxl_rr_ep_add().

Add the paddings to fix the warnings.

Fixes 384e624bb211b4 ("cxl/region: Attach endpoint decoders")
---
 drivers/cxl/core/region.c | 3 +++
 1 file changed, 3 insertions(+)
drivers/cxl/core/region.c +3 -0
index dc71ec457608d2..616db51c4e78cf 100644
@@ -728,11 +728,14 @@ static int cxl_rr_ep_add(struct cxl_region_ref *cxl_rr,
  * in particular decoder target lists.
  *
  * The steps are:
+ *
  * - validate that there are no other regions with a higher HPA already
  *   associated with @port
  * - establish a region reference if one is not already present
+ *
  *   - additionally allocate a decoder instance that will host @cxlr on
  *     @port
+ *
  * - pin the region reference by the endpoint
  * - account for how many entries in @port's target list are needed to
  *   cover all of the added endpoints.
Signature · 1 line
An old man doll... just what I always wanted! - Clara
Reviewed-by on v1 1/3
#2 lore raw

Re: [PATCH 1/3] cxl/regions: add padding for cxl_rr_ep_add nested lists

Quoted 6 lines · On Thu, 4 Aug 2022 14:54:46 +0700 Bagas Sanjaya <[email protected]> wrote:

Sphinx reported indentation warnings:

Documentation/driver-api/cxl/memory-devices:457: ./drivers/cxl/core/region.c:732: WARNING: Unexpected indentation. Documentation/driver-api/cxl/memory-devices:457: ./drivers/cxl/core/region.c:733: WARNING: Block quote ends without a blank line; unexpected unindent. Documentation/driver-api/cxl/memory-devices:457: ./drivers/cxl/core/region.c:735: WARNING: Unexpected indentation.

Quoted 7 lines

These warnings above are due to missing blank line padding in the nested list in kernel-doc comment for cxl_rr_ep_add().

Add the paddings to fix the warnings.

Fixes 384e624bb211b4 ("cxl/region: Attach endpoint decoders")

Looks right to me. Sphinx white space around lists is annoyingly fiddly but such is life.

Quoted 23 lines
---
 drivers/cxl/core/region.c | 3 +++
 1 file changed, 3 insertions(+)
drivers/cxl/core/region.c +3 -0
index dc71ec457608d2..616db51c4e78cf 100644
@@ -728,11 +728,14 @@ static int cxl_rr_ep_add(struct cxl_region_ref *cxl_rr,
  * in particular decoder target lists.
  *
  * The steps are:
+ *
  * - validate that there are no other regions with a higher HPA already
  *   associated with @port
  * - establish a region reference if one is not already present
+ *
  *   - additionally allocate a decoder instance that will host @cxlr on
  *     @port
+ *
  * - pin the region reference by the endpoint
  * - account for how many entries in @port's target list are needed to
  *   cover all of the added endpoints.
#3 lore raw

PATCH 2/3 cxl/region: describe targets and nr_targets members of cxl_region_params

In reply to Bagas Sanjaya

Sphinx reported undescribed parameters in cxl_region_params struct:

./drivers/cxl/cxl.h:376: warning: Function parameter or member 'targets' not described in 'cxl_region_params' ./drivers/cxl/cxl.h:376: warning: Function parameter or member 'nr_targets' not described in 'cxl_region_params'

Describe these members.

Fixes dd5ba0ebbdc414 ("cxl/region: Add a 'uuid' attribute")
---
 drivers/cxl/cxl.h | 2 ++
 1 file changed, 2 insertions(+)
drivers/cxl/cxl.h +2 -0
index 75674400cc8d41..65aaf15aa17e29 100644
@@ -362,6 +362,8 @@ enum cxl_config_state {
  * @interleave_ways: number of endpoints in the region
  * @interleave_granularity: capacity each endpoint contributes to a stripe
  * @res: allocated iomem capacity for this region
+ * @targets: active ordered targets in current decoder configuration
+ * @nr_targets: number of targets
  *
  * State transitions are protected by the cxl_region_rwsem
  */
Signature · 1 line
An old man doll... just what I always wanted! - Clara
Reviewed-by on v1 2/3
#4 lore raw

Re: [PATCH 2/3] cxl/region: describe targets and nr_targets members of cxl_region_params

Quoted 8 lines · On Thu, 4 Aug 2022 14:54:47 +0700 Bagas Sanjaya <[email protected]> wrote:

Sphinx reported undescribed parameters in cxl_region_params struct:

./drivers/cxl/cxl.h:376: warning: Function parameter or member 'targets' not described in 'cxl_region_params' ./drivers/cxl/cxl.h:376: warning: Function parameter or member 'nr_targets' not described in 'cxl_region_params'

Describe these members.

Fixes dd5ba0ebbdc414 ("cxl/region: Add a 'uuid' attribute")

That seems unlikely to be right tag. Probably b9686e8c8e39

With that tidied up.

Quoted 18 lines
---
 drivers/cxl/cxl.h | 2 ++
 1 file changed, 2 insertions(+)
drivers/cxl/cxl.h +2 -0
index 75674400cc8d41..65aaf15aa17e29 100644
@@ -362,6 +362,8 @@ enum cxl_config_state {
  * @interleave_ways: number of endpoints in the region
  * @interleave_granularity: capacity each endpoint contributes to a stripe
  * @res: allocated iomem capacity for this region
+ * @targets: active ordered targets in current decoder configuration
+ * @nr_targets: number of targets
  *
  * State transitions are protected by the cxl_region_rwsem
  */
#5 lore raw

PATCH 3/3 Documentation: cxl: remove dangling kernel-doc reference

In reply to Bagas Sanjaya

Sphinx reported kernel-doc failure warning, pointing to non-existent drivers/cxl/region.h (which doesn't also exist throughout repo history):

WARNING: kernel-doc './scripts/kernel-doc -rst -enable-lineno -sphinx-version 2.4.4 -no-doc-sections ./drivers/cxl/region.h' failed with return code 1

Above cause error message to be displayed on htmldocs output.

Delete the reference.

Fixes 779dd20cfb56c5 ("cxl/region: Add region creation support")
---
 Documentation/driver-api/cxl/memory-devices.rst | 3 ---
 1 file changed, 3 deletions(-)
Documentation/driver-api/cxl/memory-devices.rst +0 -3
index 66ddc58a21b159..5149ecdc53c796 100644
@@ -364,9 +364,6 @@ CXL Core
 
 CXL Regions
 -----------
-.. kernel-doc:: drivers/cxl/region.h
-   :identifiers:
-
 .. kernel-doc:: drivers/cxl/core/region.c
    :doc: cxl core region
 
Signature · 1 line
An old man doll... just what I always wanted! - Clara
Reviewed-by on v1 3/3
#6 lore raw

Re: [PATCH 3/3] Documentation: cxl: remove dangling kernel-doc reference

Quoted 11 lines · On Thu, 4 Aug 2022 14:54:48 +0700 Bagas Sanjaya <[email protected]> wrote:

Sphinx reported kernel-doc failure warning, pointing to non-existent drivers/cxl/region.h (which doesn't also exist throughout repo history):

WARNING: kernel-doc './scripts/kernel-doc -rst -enable-lineno -sphinx-version 2.4.4 -no-doc-sections ./drivers/cxl/region.h' failed with return code 1

Above cause error message to be displayed on htmldocs output.

Delete the reference.

Fixes 779dd20cfb56c5 ("cxl/region: Add region creation support")

Ah. That went in some refactoring along the way.

Quoted 18 lines
---
 Documentation/driver-api/cxl/memory-devices.rst | 3 ---
 1 file changed, 3 deletions(-)
Documentation/driver-api/cxl/memory-devices.rst +0 -3
index 66ddc58a21b159..5149ecdc53c796 100644
@@ -364,9 +364,6 @@ CXL Core
 
 CXL Regions
 -----------
-.. kernel-doc:: drivers/cxl/region.h
-   :identifiers:
-
 .. kernel-doc:: drivers/cxl/core/region.c
    :doc: cxl core region
 
Applied
#7 lore raw
In reply to Bagas Sanjaya
Quoted 10 lines · Bagas Sanjaya

Building htmldocs on next-20220803 (for which this series is based on), there are new warnings on cxl subsystem. The fixes below are self-explanatory.

Bagas Sanjaya (3):
cxl/regions: add padding for cxl_rr_ep_add nested lists cxl/region: describe targets and nr_targets members of
cxl_region_params
Documentation: cxl: remove dangling kernel-doc reference

Quoted 4 lines
 Documentation/driver-api/cxl/memory-devices.rst | 3 ---
 drivers/cxl/core/region.c                       | 3 +++
 drivers/cxl/cxl.h                               | 2 ++
 3 files changed, 5 insertions(+), 3 deletions(-)

Thanks, applied, and with Jonathan's Fixes: tag fixup.