Re: [PATCH v3 04/13] media: Rename stateful codec control macros

From: Hans Verkuil <hverkuil@xs4all.nl>
To: Ezequiel Garcia <ezequiel@collabora.com>,
	linux-media@vger.kernel.org, linux-kernel@vger.kernel.org
Cc: kernel@collabora.com, Jonas Karlman <jonas@kwiboo.se>,
	Nicolas Dufresne <nicolas.dufresne@collabora.com>,
	Philipp Zabel <p.zabel@pengutronix.de>,
	Maxime Ripard <mripard@kernel.org>,
	Paul Kocialkowski <paul.kocialkowski@bootlin.com>,
	Jernej Skrabec <jernej.skrabec@siol.net>
Subject: Re: [PATCH v3 04/13] media: Rename stateful codec control macros
Date: Fri, 20 Nov 2020 10:20:00 +0100	[thread overview]
Message-ID: <34641a16-73d1-3e7c-8dc6-dfb24e0a3a2d@xs4all.nl> (raw)
In-Reply-To: <20201118184700.331213-5-ezequiel@collabora.com>

On 18/11/2020 19:46, Ezequiel Garcia wrote:
> For historical reasons, stateful codec controls are named
> as {}_MPEG_{}. While we can't at this point sanely
> change all control IDs (such as V4L2_CID_MPEG_VIDEO_VP8_FRAME_HEADER),
> we can least change the more meaningful macros such as classes
> macros.
> 
> Signed-off-by: Ezequiel Garcia <ezequiel@collabora.com>
> ---
>  .../userspace-api/media/v4l/dev-mem2mem.rst   |   2 +-
>  .../media/v4l/ext-ctrls-codec.rst             |   4 +-
>  .../media/v4l/extended-controls.rst           |   8 +-
>  .../media/v4l/vidioc-g-ext-ctrls.rst          |   6 +-
>  drivers/media/common/cx2341x.c                |   4 +-
>  drivers/media/platform/s5p-mfc/s5p_mfc_dec.c  |   2 +-
>  drivers/media/platform/s5p-mfc/s5p_mfc_enc.c  |   2 +-
>  drivers/media/v4l2-core/v4l2-ctrls.c          |   4 +-
>  include/media/fwht-ctrls.h                    |   2 +-
>  include/media/h264-ctrls.h                    |  16 +-
>  include/media/hevc-ctrls.h                    |  10 +-
>  include/media/mpeg2-ctrls.h                   |   4 +-
>  include/media/vp8-ctrls.h                     |   2 +-
>  include/uapi/linux/v4l2-controls.h            | 409 +++++++++---------
>  14 files changed, 242 insertions(+), 233 deletions(-)
> 
> diff --git a/Documentation/userspace-api/media/v4l/dev-mem2mem.rst b/Documentation/userspace-api/media/v4l/dev-mem2mem.rst
> index d8db46886555..7041bb3d5b8d 100644
> --- a/Documentation/userspace-api/media/v4l/dev-mem2mem.rst
> +++ b/Documentation/userspace-api/media/v4l/dev-mem2mem.rst
> @@ -32,7 +32,7 @@ file handle is visible through another file handle).
>  One of the most common memory-to-memory device is the codec. Codecs
>  are more complicated than most and require additional setup for
>  their codec parameters. This is done through codec controls.
> -See :ref:`mpeg-controls`. More details on how to use codec memory-to-memory
> +See :ref:`codec-controls`. More details on how to use codec memory-to-memory
>  devices are given in the following sections.
>  
>  .. toctree::
> diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst
> index ce728c757eaf..b31c52d9b1da 100644
> --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst
> +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst
> @@ -1,6 +1,6 @@
>  .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
>  
> -.. _mpeg-controls:
> +.. _codec-controls:
>  
>  ***********************
>  Codec Control Reference
> @@ -26,7 +26,7 @@ Generic Codec Controls
>  Codec Control IDs
>  -----------------
>  
> -``V4L2_CID_MPEG_CLASS (class)``
> +``V4L2_CID_CODEC_CLASS (class)``
>      The Codec class descriptor. Calling
>      :ref:`VIDIOC_QUERYCTRL` for this control will
>      return a description of this control class. This description can be
> diff --git a/Documentation/userspace-api/media/v4l/extended-controls.rst b/Documentation/userspace-api/media/v4l/extended-controls.rst
> index 70301538d222..abec5ced748a 100644
> --- a/Documentation/userspace-api/media/v4l/extended-controls.rst
> +++ b/Documentation/userspace-api/media/v4l/extended-controls.rst
> @@ -55,8 +55,8 @@ controls in that array and a control class. Control classes are used to
>  group similar controls into a single class. For example, control class
>  ``V4L2_CTRL_CLASS_USER`` contains all user controls (i. e. all controls
>  that can also be set using the old :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>`
> -ioctl). Control class ``V4L2_CTRL_CLASS_MPEG`` contains all controls
> -relating to MPEG encoding, etc.
> +ioctl). Control class ``V4L2_CTRL_CLASS_CODEC`` contains all controls
> +relating to stateful codecs.

Not entirely true. Controls like V4L2_CID_MPEG_VIDEO_H264_PROFILE are valid
for both. Perhaps something like this would be better:

...contains controls relating to codecs. See :ref:... for controls specific
to stateless codecs.

>  
>  All controls in the control array must belong to the specified control
>  class. An error is returned if this is not the case.

Regards,

	Hans