Re: [PATCH RFC 04/13] drm/powervr_sgx: Add the uAPI header and its documentation

[sashiko-bot@kernel.org]

Thank you for your contribution! Sashiko AI review found 2 potential
issues to consider:
- [Low] drm/powervr_sgx: missing macro identifiers in uapi.rst
  kernel-doc
- [Low] drm/powervr_sgx: broken ReST role after caret in
  powervr_sgx_drm.h
--

commit f06a880dd06227c9b6234d3a185b5b25ba657094
Author: Joseph Telaak <joseph@telaak.dev>

drm/powervr_sgx: Add the uAPI header and its documentation

This commit adds the powervr_sgx DRM driver's uAPI header, Sphinx
documentation, and MAINTAINERS entry.

> diff --git a/Documentation/gpu/powervr_sgx/uapi.rst b/Documentation/gpu/powervr_sgx/uapi.rst
> new file mode 100644
> index 0000000000000..8dd7908970b92
> --- /dev/null
> +++ b/Documentation/gpu/powervr_sgx/uapi.rst

[ ... ]

> +DEV_QUERY
> +---------
> +.. kernel-doc:: include/uapi/drm/powervr_sgx_drm.h
> +   :doc: PowerVR SGX IOCTL DEV_QUERY interface
> +
> +.. kernel-doc:: include/uapi/drm/powervr_sgx_drm.h
> +   :identifiers: drm_powervr_sgx_dev_query
> +                 drm_powervr_sgx_ioctl_dev_query_args
> +                 drm_powervr_sgx_dev_query_gpu_info
> +                 drm_powervr_sgx_dev_query_limits
> +                 drm_powervr_sgx_dev_query_commands
> +                 drm_powervr_sgx_dev_query_quirks
> +                 drm_powervr_sgx_heap_id
> +                 drm_powervr_sgx_heap
> +                 drm_powervr_sgx_dev_query_heap_info
> +
> +CREATE_BO
> +---------
> +.. kernel-doc:: include/uapi/drm/powervr_sgx_drm.h
> +   :doc: PowerVR SGX IOCTL CREATE_BO interface
> +
> +.. kernel-doc:: include/uapi/drm/powervr_sgx_drm.h
> +   :identifiers: drm_powervr_sgx_ioctl_create_bo_args
> +                 drm_powervr_sgx_ioctl_get_bo_mmap_offset_args

[Severity: Low]
Should these :identifiers: lists also include
DRM_POWERVR_SGX_CAP_BACKWARD_BLITS under DEV_QUERY, and
DRM_POWERVR_SGX_BO_ALLOW_CPU_ACCESS and DRM_POWERVR_SGX_BO_CODE under
CREATE_BO?

Those three macros have standalone kernel-doc comments in
powervr_sgx_drm.h rather than being part of a DOC: section, and every
kernel-doc directive in uapi.rst filters by :doc: or :identifiers:, so
their documentation (including the rules on code objects and reserved flag
bits) is omitted from the rendered Sphinx output.

> diff --git a/include/uapi/drm/powervr_sgx_drm.h b/include/uapi/drm/powervr_sgx_drm.h
> new file mode 100644
> index 0000000000000..12381809503a1
> --- /dev/null
> +++ b/include/uapi/drm/powervr_sgx_drm.h
> @@ -0,0 +1,1175 @@

[ ... ]

> + *  - User pointers and device-virtual addresses are __u64. A device-virtual
> + *    address at or above 2^&drm_powervr_sgx_dev_query_limits.va_bits is
> + *    rejected.

[Severity: Low]
Does 2^&drm_powervr_sgx_dev_query_limits.va_bits render raw :c:type:
markup in the generated documentation?

kernel-doc expands &drm_powervr_sgx_dev_query_limits.va_bits into a
:c:type: role right after the caret, and ReStructuredText only recognizes
an inline role when it is preceded by whitespace, a backslash-escaped
space, or punctuation such as ( or -.  Escaping the space as 2\^&\ ... or
adding parentheses as 2^(&drm_powervr_sgx_dev_query_limits.va_bits) lets
Docutils parse the cross-reference.

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20261112-powervr-sgx-v1-0-c69b84bac011@telaak.dev?part=4