From mboxrd@z Thu Jan 1 00:00:00 1970 Return-path: Received: from mailout4.w2.samsung.com ([211.189.100.14]:26595 "EHLO usmailout4.samsung.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753095AbaCLO1x (ORCPT ); Wed, 12 Mar 2014 10:27:53 -0400 Received: from uscpsbgm2.samsung.com (u115.gpu85.samsung.co.kr [203.254.195.115]) by usmailout4.samsung.com (Oracle Communications Messaging Server 7u4-24.01(7.0.4.24.0) 64bit (built Nov 17 2011)) with ESMTP id <0N2B00MNHUUGJS10@usmailout4.samsung.com> for linux-media@vger.kernel.org; Wed, 12 Mar 2014 10:27:52 -0400 (EDT) Date: Wed, 12 Mar 2014 11:27:45 -0300 From: Mauro Carvalho Chehab To: Hans Verkuil Cc: linux-media@vger.kernel.org, laurent.pinchart@ideasonboard.com, s.nawrocki@samsung.com, ismael.luceno@corp.bluecherry.net, pete@sensoray.com, sakari.ailus@iki.fi, Hans Verkuil Subject: Re: [REVIEWv3 PATCH 22/35] DocBook media: update control section. Message-id: <20140312112745.2d9d3205@samsung.com> In-reply-to: <1392631070-41868-23-git-send-email-hverkuil@xs4all.nl> References: <1392631070-41868-1-git-send-email-hverkuil@xs4all.nl> <1392631070-41868-23-git-send-email-hverkuil@xs4all.nl> MIME-version: 1.0 Content-type: text/plain; charset=US-ASCII Content-transfer-encoding: 7bit Sender: linux-media-owner@vger.kernel.org List-ID: Em Mon, 17 Feb 2014 10:57:37 +0100 Hans Verkuil escreveu: > From: Hans Verkuil > > Document the support for complex types in controls. > > Signed-off-by: Hans Verkuil > Reviewed-by: Sylwester Nawrocki > --- > Documentation/DocBook/media/v4l/controls.xml | 104 ++++++++++++++++++++------- > 1 file changed, 78 insertions(+), 26 deletions(-) > > diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml > index ef55c3e..85d78d4 100644 > --- a/Documentation/DocBook/media/v4l/controls.xml > +++ b/Documentation/DocBook/media/v4l/controls.xml > @@ -13,6 +13,19 @@ correctly with any device. > All controls are accessed using an ID value. V4L2 defines > several IDs for specific purposes. Drivers can also implement their > own custom controls using V4L2_CID_PRIVATE_BASE > +The use of V4L2_CID_PRIVATE_BASE > +is problematic because different drivers may use the same > +V4L2_CID_PRIVATE_BASE ID for different controls. > +This makes it hard to programatically set such controls since the meaning > +of the control with that ID is driver dependent. In order to resolve this > +drivers use unique IDs and the V4L2_CID_PRIVATE_BASE > +IDs are mapped to those unique IDs by the kernel. Consider these > +V4L2_CID_PRIVATE_BASE IDs as aliases to the real > +IDs. > +Many applications today still use the V4L2_CID_PRIVATE_BASE > +IDs instead of using &VIDIOC-QUERYCTRL; with the V4L2_CTRL_FLAG_NEXT_CTRL > +flag to enumerate all IDs, so support for V4L2_CID_PRIVATE_BASE > +is still around. > and higher values. The pre-defined control IDs have the prefix > V4L2_CID_, and are listed in linkend="control-id" />. The ID is used when querying the attributes of > @@ -31,25 +44,22 @@ the current video input or output, tuner or modulator, or audio input > or output. Different in the sense of other bounds, another default and > current value, step size or other menu items. A control with a certain > custom ID can also change name and > -type. > - It will be more convenient for applications if drivers > -make use of the V4L2_CTRL_FLAG_DISABLED flag, but > -that was never required. > - Control values are stored globally, they do not > +type. > + > + If a control is not applicable to the current configuration > +of the device (for example, it doesn't apply to the current video input) > +drivers set the V4L2_CTRL_FLAG_INACTIVE flag. > + > + Control values are stored globally, they do not > change when switching except to stay within the reported bounds. They > also do not change ⪚ when the device is opened or closed, when the Hmm... ⪚ above seems weird (ok, this is not part of your changes, but do you care take a look on the above line?) > tuner radio frequency is changed or generally never without > -application request. Since V4L2 specifies no event mechanism, panel > -applications intended to cooperate with other panel applications (be > -they built into a larger application, as a TV viewer) may need to > -regularly poll control values to update their user > -interface. > - Applications could call an ioctl to request events. > -After another process called &VIDIOC-S-CTRL; or another ioctl changing > -shared properties the &func-select; function would indicate > -readability until any ioctl (querying the properties) is > -called. > - > +application request. > + > + V4L2 specifies an event mechanism to notify applications > +when controls change value (see &VIDIOC-SUBSCRIBE-EVENT;, event > +V4L2_EVENT_CTRL), panel applications might want to make > +use of that in order to always reflect the correct control value. > > > All controls use machine endianness. > @@ -434,8 +444,8 @@ Drivers must implement VIDIOC_QUERYCTRL, > controls, VIDIOC_QUERYMENU when it has one or > more menu type controls. > > - > - Enumerating all controls > + > + Enumerating all user controls > > > &v4l2-queryctrl; queryctrl; > @@ -501,6 +511,32 @@ for (queryctrl.id = V4L2_CID_PRIVATE_BASE;; > > > > + Enumerating all user controls (alternative) > + > +memset(&queryctrl, 0, sizeof(queryctrl)); > + > +queryctrl.id = V4L2_CTRL_CLASS_USER | V4L2_CTRL_FLAG_NEXT_CTRL; > +while (0 == ioctl(fd, &VIDIOC-QUERYCTRL;, &queryctrl)) { > + if (V4L2_CTRL_ID2CLASS(queryctrl.id) != V4L2_CTRL_CLASS_USER) > + break; > + if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) > + continue; > + > + printf("Control %s\n", queryctrl.name); > + > + if (queryctrl.type == V4L2_CTRL_TYPE_MENU) > + enumerate_menu(); > + > + queryctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; > +} > +if (errno != EINVAL) { > + perror("VIDIOC_QUERYCTRL"); > + exit(EXIT_FAILURE); > +} > + > + > + > + > Changing controls > > > @@ -624,16 +660,32 @@ supported. > &v4l2-control;, except for the fact that it also allows for 64-bit > values and pointers to be passed. > > + Since the &v4l2-ext-control; supports pointers it is now > +also possible to have controls with complex types such as arrays/matrices s/complex/compound/g > +and/or structures. All such complex controls will have the > +V4L2_CTRL_FLAG_HIDDEN set since such controls cannot > +be displayed in control panel applications. Nor can they be used in the > +user class (for backwards compatibility reasons), and you need to specify > +the V4L2_CTRL_FLAG_NEXT_HIDDEN when enumerating controls > +to actually be able to see such hidden controls. In other words, these > +controls with complex types should only be used programmatically. > + > + Since such complex controls need to expose more information > +about themselves than is possible with &VIDIOC-QUERYCTRL; the > +&VIDIOC-QUERY-EXT-CTRL; ioctl was added. In particular, this ioctl gives > +the size of the matrix if this control consists of more than > +one element. > + > It is important to realize that due to the flexibility of > controls it is necessary to check whether the control you want to set > actually is supported in the driver and what the valid range of values > -is. So use the &VIDIOC-QUERYCTRL; and &VIDIOC-QUERYMENU; ioctls to > -check this. Also note that it is possible that some of the menu > -indices in a control of type V4L2_CTRL_TYPE_MENU > -may not be supported (VIDIOC_QUERYMENU will > -return an error). A good example is the list of supported MPEG audio > -bitrates. Some drivers only support one or two bitrates, others > -support a wider range. > +is. So use the &VIDIOC-QUERYCTRL; (or &VIDIOC-QUERY-EXT-CTRL;) and > +&VIDIOC-QUERYMENU; ioctls to check this. Also note that it is possible > +that some of the menu indices in a control of type > +V4L2_CTRL_TYPE_MENU may not be supported > +(VIDIOC_QUERYMENU will return an error). A good > +example is the list of supported MPEG audio bitrates. Some drivers only > +support one or two bitrates, others support a wider range. > > > All controls use machine endianness. > @@ -699,7 +751,7 @@ ID based on a control ID. > VIDIOC_QUERYCTRL will fail when used in > combination with V4L2_CTRL_FLAG_NEXT_CTRL. In > that case the old method of enumerating control should be used (see > -1.8). But if it is supported, then it is guaranteed to enumerate over > +). But if it is supported, then it is guaranteed to enumerate over > all controls, including driver-private controls. > > -- Regards, Mauro