Re: [PATCH v2 3/6] media: uvcvideo: Announce deprecation intentions for UVCIOC_CTRL_MAP

[Hans de Goede]

Hi Ricaro,

On 9-Dec-25 7:41 AM, Ricardo Ribalda wrote:
> Hi Hans
> 
> 
> On Mon, 8 Dec 2025 at 20:17, Hans de Goede <hansg@xxxxxxxxxx> wrote:
>>
>> Hi,
>>
>> On 19-Nov-25 8:37 PM, Ricardo Ribalda wrote:
>>> The UVCIOC_CTRL_MAP lets userspace create a mapping for a custom
>>> control.
>>>
>>> This mapping is usually created by the uvcdynctrl userspace utility. We
>>> would like to get the mappings into the driver instead.
>>>
>>> Reviewed-by: Laurent Pinchart <laurent.pinchart@xxxxxxxxxxxxxxxx>
>>> Signed-off-by: Ricardo Ribalda <ribalda@xxxxxxxxxxxx>
>>> ---
>>>  Documentation/userspace-api/media/drivers/uvcvideo.rst | 2 ++
>>>  drivers/media/usb/uvc/uvc_v4l2.c                       | 4 ++++
>>>  2 files changed, 6 insertions(+)
>>>
>>> diff --git a/Documentation/userspace-api/media/drivers/uvcvideo.rst b/Documentation/userspace-api/media/drivers/uvcvideo.rst
>>> index dbb30ad389ae4d53bc734b4269ebea20ecdd7535..b09d2f8ba66ecde67f1e35fd77858a505ad44eb1 100644
>>> --- a/Documentation/userspace-api/media/drivers/uvcvideo.rst
>>> +++ b/Documentation/userspace-api/media/drivers/uvcvideo.rst
>>> @@ -109,6 +109,8 @@ IOCTL reference
>>>  UVCIOC_CTRL_MAP - Map a UVC control to a V4L2 control
>>>  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>>>
>>> +**This IOCTL is deprecated and will be eventually removed**
>>> +
>>>  Argument: struct uvc_xu_control_mapping
>>>
>>>  **Description**:
>>> diff --git a/drivers/media/usb/uvc/uvc_v4l2.c b/drivers/media/usb/uvc/uvc_v4l2.c
>>> index 9e4a251eca88085a1b4e0e854370015855be92ee..03c64b5698bf4331fed8437fa6e9c726a07450bd 100644
>>> --- a/drivers/media/usb/uvc/uvc_v4l2.c
>>> +++ b/drivers/media/usb/uvc/uvc_v4l2.c
>>> @@ -1044,6 +1044,8 @@ static long uvc_ioctl_default(struct file *file, void *priv, bool valid_prio,
>>>       switch (cmd) {
>>>       /* Dynamic controls. */
>>>       case UVCIOC_CTRL_MAP:
>>> +             pr_warn_once("uvcvideo: " DEPRECATED
>>> +                          "UVCIOC_CTRL_MAP ioctl will be eventually removed.\n");
>>>               return uvc_ioctl_xu_ctrl_map(chain, arg);
>>>
>>>       case UVCIOC_CTRL_QUERY:
>>
>> Deprecating and then removing this is going to be a long slow process.
>>
>> I was thinking that rather then remove it we would keep accepting the ioctl but instead
>> of calling uvc_ioctl_xu_ctrl_map() we would simply return 0. E.g. change the above to:
>>
>>         case UVCIOC_CTRL_MAP:
>>                 pr_warn_once("uvcvideo: " DEPRECATED
>>                              "UVCIOC_CTRL_MAP ioctl will eventually be ignored.\n");
>>                 return uvc_ioctl_xu_ctrl_map(chain, arg);
>>
>> And then say in one year after a kernel with the above is released change it to:
>>
>>         case UVCIOC_CTRL_MAP:
>>                 pr_warn_once("uvcvideo: " DEPRECATED
>>                              "UVCIOC_CTRL_MAP ioctls are ignored.\n");
>>                 return 0;
>>
>>
>> I think removing it in 1 year is too soon, but ignoring it is ok. This does mean
>> that people will lose the custom v4l2-ctrls for which patch 2/6 is not adding
>> mappings into the driver in 1 year after a kernel with the warning is released...
>>
>> I'm not 100% sure about this plan, so please let me know what you think. For
>> outright deprecation warning + full removal I think we need to wait at least
>> 2 years after shipping a kernel with the deprecation warning.
> 
> Let me rephrase what you have written:
> 
> today:
> pr_warn_once("uvcvideo: " DEPRECATED "UVCIOC_CTRL_MAP ioctl will be
> eventually ignored.\n");
> return uvc_ioctl_xu_ctrl_map(chain, arg);

Ack for the above

What I was trying to say for the 1 year / 2 year thing is
not do "x after 1 year" and then "y after 2 years", but do 
either "x after 1 year" *or* "y after 2 years"

So:

> in 1 year:
> pr_warn_once("uvcvideo: " DEPRECATED "UVCIOC_CTRL_MAP ioctl is ignored.\n");
> return 0;

*or*

> in  2 years:
> return -ENOIOCTLCMD;

The idea being that when we start doing warn-once + return 0
we can already remove all the code and keeping just the case
label + pr_warn + return 0, which is not a lot of code to keep
around.

> Normally I would prefer not to lie to userspace (saying that the
> mapping was done, but not doing it).
> 
> But in this case, UVCIOC_CTRL_MAP does not seem to be very widely used
> (check previous email), so I do not think it really matters if we skip
> the "1 year step" and just return -ENOIOCTLCMD in 2 years.
> 
> I leave it up to you to decide the deprecation steps.

Laurent do you have any opinion on this ?

Regards,

Hans