Re: [PATCHv3 08/13] Documentation: media: document HPD_PRESENT cap and flag.

[sashiko-bot@kernel.org]

Thank you for your contribution! Sashiko AI review found 2 potential issue(s) to consider:
- [Medium] media: cec: docs: CEC_CAP_HAS_HPD_PRESENT and flag missing from uAPI header
- [Low] media: cec: docs: malformed rST indentation in CEC_LOG_ADDRS_FL_HPD_PRESENT
--

commit 53c76b7e379d8741e299203dcf5382f4b9c83f39
Author: Hans Verkuil <hverkuil+cisco@kernel.org>

Documentation: media: document HPD_PRESENT cap and flag.

This commit documents the CEC_CAP_HAS_HPD_PRESENT capability and the
CEC_LOG_ADDRS_FL_HPD_PRESENT logical address flag in the CEC userspace API
documentation.

> diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst
> index 1d5248979a6da..bf734cbee0dda 100644
> --- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst
> +++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst
> @@ -143,6 +143,16 @@ returns the information to the application. The ioctl never fails.
>        - 0x00000200
>        - If this capability is set, then
>          :ref:`CEC_MSG_FL_REPLY_VENDOR_ID <cec-msg-flags>` can be used.
> +    * .. _`CEC-CAP-HAS-HPD-PRESENT`:
> +
> +      - ``CEC_CAP_HAS_HPD_PRESENT``
> +      - 0x00000400
> +      - If this capability is set, then
> +        :ref:`CEC_LOG_ADDRS_FL_HPD_PRESENT <cec-log-addrs-flags>` is valid.
> +	This makes it possible to tell apart the case where the Physical Address
> +	is f.f.f.f because no HPD (Hotplug Detect) is present, and the case
> +	where it is f.f.f.f because the EDID does not provide a valid Physical
> +	Address.

[Severity: Medium]
Are CEC_CAP_HAS_HPD_PRESENT and CEC_LOG_ADDRS_FL_HPD_PRESENT missing from
include/uapi/linux/cec.h?

In include/uapi/linux/cec.h, the capability definitions currently end at
CEC_CAP_REPLY_VENDOR_ID:

    /* CEC_MSG_FL_REPLY_VENDOR_ID is available */
    #define CEC_CAP_REPLY_VENDOR_ID	(1 << 9)

and the logical address flags end at CEC_LOG_ADDRS_FL_CONFIG_FAILED:

    /* Configuration failed */
    #define CEC_LOG_ADDRS_FL_CONFIG_FAILED		(1 << 3)

Neither constant appears to be defined in include/uapi/linux/cec.h or used in
drivers/media/cec/, so userspace applications consulting this documentation
cannot compile with these flags.

> diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst
> index 8397bf5737988..e37898750ab5d 100644
> --- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst
> +++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst
> @@ -192,6 +192,16 @@ logical address types are already defined will return with error ``EBUSY``.
>        - If this flag is set, then the CEC device failed to claim a free logical
>          address and is in the unconfigured state. This can never happen if
>  	``CEC_LOG_ADDRS_FL_ALLOW_UNREG_FALLBACK`` was set as well.
> +    * .. _`CEC-LOG-ADDRS-FL-HPD-PRESENT`:
> +
> +      - ``CEC_LOG_ADDRS_FL_HPD_PRESENT``
> +      - 16
> +      - If this flag is set, then the HPD (Hotplug Detect) is present. This
> +	 helps tell apart the case where the Physical Address is f.f.f.f
> +	 because no HPD is present, and the case where it is f.f.f.f because the
> +	 EDID does not provide a valid Physical Address. This flag can only be
> +	 used if ``CEC_CAP_HAS_HPD_PRESENT`` is set in the adapter
> +	 capabilities.

[Severity: Low]
Will Sphinx misparse the CEC_LOG_ADDRS_FL_HPD_PRESENT description as a
definition list when building htmldocs?

The first line of the bullet item starts at column 8 (six spaces, a hyphen,
and a space), whereas the continuation lines are indented with a tab plus an
extra space, placing them at column 9. In reStructuredText, indenting
continuation lines relative to the first line without a blank line causes
the first line to be rendered as a bold definition term and the remaining
lines as an indented definition block instead of a single paragraph.

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/e98308c0db382c09ce698b34ca54f798ab0e3557.1793863347.git.hverkuil+cisco@kernel.org?part=1