Re: [PATCH v5 09/18] drm/xe/vsec: Add DOC text for VSEC

[sashiko-bot@kernel.org]

Thank you for your contribution! Sashiko AI review found 2 potential issue(s) to consider:
- [Low] Incorrect kernel-doc tag for return value in `xe_pmt_telem_read`.
- [Low] The newly added documentation file `xe_vsec.rst` is not included in any Sphinx `toctree`.
--

commit 011373dcf20ed7018b1279370ae8b1af346ffff5
Author: Michael J. Ruhl <michael.j.ruhl@intel.com>

drm/xe/vsec: Add DOC text for VSEC

This commit adds the necessary files and documentation text to use the DOC
system for the VSEC component.

> diff --git a/Documentation/gpu/xe/xe_vsec.rst b/Documentation/gpu/xe/xe_vsec.rst
> new file mode 100644
> index 0000000000000..1a87548489ea9
> --- /dev/null
> +++ b/Documentation/gpu/xe/xe_vsec.rst
> @@ -0,0 +1,14 @@
> +.. SPDX-License-Identifier: (GPL-2.0+ OR MIT)
> +
> +=====
> +VSEC
> +=====

[Severity: Low]
This isn't a bug, but should this newly added documentation file be included
in a Sphinx toctree, such as the one in Documentation/gpu/xe/index.rst? 

Without a toctree entry, the document remains orphaned. This triggers a Sphinx
build warning stating that the document isn't included in any toctree, and 
makes the text unreachable from the main generated documentation tree.

[ ... ]
> diff --git a/drivers/gpu/drm/xe/xe_vsec.c b/drivers/gpu/drm/xe/xe_vsec.c
> index 468a221378faf..5223bfe50ede6 100644
> --- a/drivers/gpu/drm/xe/xe_vsec.c
> +++ b/drivers/gpu/drm/xe/xe_vsec.c
[ ... ]
> @@ -140,6 +151,17 @@ static int xe_guid_decode(u32 guid, int *index, u32 *offset)
>  	return 0;
>  }
>  
> +/**
> + * xe_pmt_telem_read - Given a device and a PMT GUID, read data into a buffer
> + * @dev: valid Xe device
> + * @guid: PMT GUID (from the PMT discovery struct)
> + * @data: buffer to place data in
> + * @user_offset: a user offset relative to the beginning of the data to read
> + * @count: bytes to read
> + *
> + * Returns -EINVAL for VF and PMT WATCHER requests
> + *         count   number of bytes read on success
> + */

[Severity: Low]
This isn't a bug, but does this return value description violate the 
kernel-doc format? 

The scripts/kernel-doc tool expects return values to be formatted using the 
"Return:" section header. Not formatting this correctly causes the tool to fail 
to parse the return value, which can trigger a warning and render incorrectly 
in the generated HTML documentation.

>  int xe_pmt_telem_read(struct device *dev, u32 guid, u64 *data, loff_t user_offset,
>  		      u32 count)
>  {

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20260903201002.1064889-20-michael.j.ruhl@intel.com?part=9