[PATCH 0/3] cxl: documentation fixes

[PATCH 0/3] cxl: documentation fixes

[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

 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
-- 
An old man doll... just what I always wanted! - Clara

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

[Bagas Sanjaya]

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")
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 drivers/cxl/core/region.c | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/drivers/cxl/core/region.c b/drivers/cxl/core/region.c
index dc71ec457608d2..616db51c4e78cf 100644
--- a/drivers/cxl/core/region.c
+++ b/drivers/cxl/core/region.c
@@ -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.
-- 
An old man doll... just what I always wanted! - Clara

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

[Jonathan Cameron]

On Thu,  4 Aug 2022 14:54:46 +0700
Bagas Sanjaya <bagasdotme@gmail.com> 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.
> 
> 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")
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
Looks right to me.  Sphinx white space around lists is annoyingly fiddly but
such is life.

Reviewed-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>

> ---
>  drivers/cxl/core/region.c | 3 +++
>  1 file changed, 3 insertions(+)
> 
> diff --git a/drivers/cxl/core/region.c b/drivers/cxl/core/region.c
> index dc71ec457608d2..616db51c4e78cf 100644
> --- a/drivers/cxl/core/region.c
> +++ b/drivers/cxl/core/region.c
> @@ -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.

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

[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")
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 drivers/cxl/cxl.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/drivers/cxl/cxl.h b/drivers/cxl/cxl.h
index 75674400cc8d41..65aaf15aa17e29 100644
--- a/drivers/cxl/cxl.h
+++ b/drivers/cxl/cxl.h
@@ -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
  */
-- 
An old man doll... just what I always wanted! - Clara

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

[Jonathan Cameron]

On Thu,  4 Aug 2022 14:54:47 +0700
Bagas Sanjaya <bagasdotme@gmail.com> 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.

Reviewed-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>

> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  drivers/cxl/cxl.h | 2 ++
>  1 file changed, 2 insertions(+)
> 
> diff --git a/drivers/cxl/cxl.h b/drivers/cxl/cxl.h
> index 75674400cc8d41..65aaf15aa17e29 100644
> --- a/drivers/cxl/cxl.h
> +++ b/drivers/cxl/cxl.h
> @@ -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
>   */

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

[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")
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/driver-api/cxl/memory-devices.rst | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/Documentation/driver-api/cxl/memory-devices.rst b/Documentation/driver-api/cxl/memory-devices.rst
index 66ddc58a21b159..5149ecdc53c796 100644
--- a/Documentation/driver-api/cxl/memory-devices.rst
+++ b/Documentation/driver-api/cxl/memory-devices.rst
@@ -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
 
-- 
An old man doll... just what I always wanted! - Clara

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

[Jonathan Cameron]

On Thu,  4 Aug 2022 14:54:48 +0700
Bagas Sanjaya <bagasdotme@gmail.com> 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")
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
Ah. That went in some refactoring along the way.

Reviewed-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>

> ---
>  Documentation/driver-api/cxl/memory-devices.rst | 3 ---
>  1 file changed, 3 deletions(-)
> 
> diff --git a/Documentation/driver-api/cxl/memory-devices.rst b/Documentation/driver-api/cxl/memory-devices.rst
> index 66ddc58a21b159..5149ecdc53c796 100644
> --- a/Documentation/driver-api/cxl/memory-devices.rst
> +++ b/Documentation/driver-api/cxl/memory-devices.rst
> @@ -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
>  

RE: [PATCH 0/3] cxl: documentation fixes

[Dan Williams]

Bagas Sanjaya wrote:
> 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(-)

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