Re: v4l regression: V4L2_CID_[VH]CENTER disappeared without notice.

[Mauro Carvalho Chehab <mchehab@infradead.org>]

On Mon, 02 Jun 2008 20:59:38 +0100
David Woodhouse <dwmw2@infradead.org> wrote:

> On Mon, 2008-06-02 at 20:19 +0100, Alan Cox wrote:
> > > Don't forget to document how people are _supposed_ to use the v4l api
> > > from userspace, though.
> > 
> > Correct but those methods are not part of the V4L2 API and have not been
> > for some considerable time. 
> 
> It seems that message hadn't got through. Any suggestions as to how we
> could make sure it does in future?
> 
> The usual answers are (in order of preference):
>  1) don't remove userspace APIs
>  2) don't remove userspace APIs
>  3) Documentation/feature-removal-schedule.txt
>  4) don't remove userspace APIs
> 
> It would be good if we could combine #3 with some form of
> __deprecated... can we make that work for ioctls in userspace?

David, 

V4L2_CID_[VH]CENTER are not ioctls.

They are just magic id's, to uniquely identify a parameter that needs to be
controlled by userspace. There are magic numbers for volume, hue, contrast, etc.

The V4L API has two ioctl's that lists what magic numbers exist at a given driver
and helps the userspace app to build an input entry for that parameter. 

On a very few cases, the userspace app might need to use the symbol aliases.
That's why those symbols are at videodev2.h. For example, the volume ID is
somewhat interesting for an userspace app to know, since it can associate the IR
volume UP/Down keys to control the board volume.

On most cases, userspace will just call VIDIOC_QUERYCTRL ioctl, passing an index,
starting on 0, until it receives an -EINVAL. If the ioctl returns 0, the
userspace will have the magic number, a string with the control name,
its minimum/maximum value, its type (integer/boolean), and its default value
and step, and will dynamically construct a table of controls.

In the case of V4L2_CID_[VH]CENTER those magic numbers were intended to control
X and Y positions, but were never used, in fact.

So, it was a complete surprise to me that an userspace API wants to do a
special treatment to an id that weren't used (since no kernel driver will
enumerate  V4L2_CID_[VH]CENTER).

So, I don't think that a __deprecated macro for ioctls should deal with those
stuff.

Cheers,
Mauro