[PATCH] media: v4l2-subdev: Clearly document that the crop API won't be extended

[Laurent Pinchart]

On Thu, Apr 04, 2024 at 11:59:12PM +0530, Umang Jain wrote:
> Hi Laurent,
> 
> It seems this is meant for linux-media instead ?

Oops :-S My fingers are too used to typing libcamera. Thanks for
noticing.

> On 04/04/24 8:26 pm, Laurent Pinchart wrote:
> > The V4L2 subdev crop API has been marked as obsolete, deprecated by the
> > selection API. Despite this, it has recently been extended with streams
> > support. In hindsight this was a mistake. Make sure it doesn't happen
> > again by clearly documenting that no new extensions will be accepted.
> >
> > Suggested-by: Hans Verkuil <hverkuil-cisco at xs4all.nl>
> > Signed-off-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
> > ---
> >   .../userspace-api/media/v4l/vidioc-subdev-g-crop.rst        | 6 +++---
> >   include/uapi/linux/v4l2-subdev.h                            | 4 ++++
> >   2 files changed, 7 insertions(+), 3 deletions(-)
> >
> > diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst
> > index 92d933631fda..88a748103a71 100644
> > --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst
> > +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst
> > @@ -37,9 +37,9 @@ Description
> >   
> >   .. note::
> >   
> > -    This is an :ref:`obsolete` interface and may be removed
> > -    in the future. It is superseded by
> > -    :ref:`the selection API <VIDIOC_SUBDEV_G_SELECTION>`.
> > +    This is an :ref:`obsolete` interface and may be removed in the future. It is
> > +    superseded by :ref:`the selection API <VIDIOC_SUBDEV_G_SELECTION>`. No new
> > +    extensions to the :c:type:`v4l2_subdev_crop` structure will be accepted.
> >   
> >   To retrieve the current crop rectangle applications set the ``pad``
> >   field of a struct :c:type:`v4l2_subdev_crop` to the
> > diff --git a/include/uapi/linux/v4l2-subdev.h b/include/uapi/linux/v4l2-subdev.h
> > index 7048c51581c6..81a24bd38003 100644
> > --- a/include/uapi/linux/v4l2-subdev.h
> > +++ b/include/uapi/linux/v4l2-subdev.h
> > @@ -50,6 +50,10 @@ struct v4l2_subdev_format {
> >    * @rect: pad crop rectangle boundaries
> >    * @stream: stream number, defined in subdev routing
> >    * @reserved: drivers and applications must zero this array
> > + *
> > + * The subdev crop API is an obsolete interface and may be removed in the
> > + * future. It is superseded by the selection API. No new extensions to this
> > + * structure will be accepted.
> >    */
> >   struct v4l2_subdev_crop {
> >   	__u32 which;

-- 
Regards,

Laurent Pinchart