cxl: documentation fixes
Subsystems (3)
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
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.
--- drivers/cxl/core/region.c | 3 +++ 1 file changed, 3 insertions(+)
drivers/cxl/core/region.c +3 -0
@@ -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
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")Signed-off-by Bagas Sanjaya <[email protected]>
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@@ -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
In reply to Bagas SanjayaSphinx 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.
--- drivers/cxl/cxl.h | 2 ++ 1 file changed, 2 insertions(+)
drivers/cxl/cxl.h +2 -0
@@ -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
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_paramsstruct:
./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
Signed-off-by Bagas Sanjaya <[email protected]>--- drivers/cxl/cxl.h | 2 ++ 1 file changed, 2 insertions(+)drivers/cxl/cxl.h +2
-0@@ -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
In reply to Bagas SanjayaSphinx 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.
--- Documentation/driver-api/cxl/memory-devices.rst | 3 --- 1 file changed, 3 deletions(-)
Documentation/driver-api/cxl/memory-devices.rst +0 -3
@@ -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
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 1Above 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 <[email protected]>
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@@ -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
Dan Williams
AppliedQuoted 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 forcxl_rr_ep_addnested lists cxl/region: describe targets andnr_targetsmembers 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.