[RFC] V4L2 Controls State Store/Restore File Format

[RFC] V4L2 Controls State Store/Restore File Format

[Paulo Assis]

Hi all,

Below is a proposal for the file format to use when storing/restoring
v4l2 controls state.

I've some doubts concerning atomically set controls and string
controls (see below)
that may be inducing me on error.
The format is intended to be generic enough to support any control
class so I hope
to receive comments for any special cases that I might have missed or
overlooked.
Don't worry about bashing on the proposal to hard I have a hard skin :-D

Regards,
Paulo

---------- Forwarded message ----------
From: Hans de Goede <hdegoede@redhat.com>
Date: 2010/5/20
Subject: Re: [RFC] V4L2 Controls State Store/Restore File Format
To: Paulo Assis <pj.assis@gmail.com>
Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>,
Martin_Rubli@logitech.com


Hi Paulo,

Clearly you've though quite a bit about this I had not realized
this would be this complex (with ordering issues etc.).

This looks like a good proposal to start with to me, I think it
would be good to further discuss this on the linux-media list,
where other v4l devs can read it and chime in.

Regards,

Hans


On 05/20/2010 03:11 PM, Paulo Assis wrote:
>
> Hans,
> Below is the RFC with my proposed control state file format for
> store/restore functionality.
> I have several doubts, mostly regarding controls that must be set
> atomically with the extended control API.
> The main question is:
> How does an application know that a group of controls must be set atomically ?
> Is this reported by the driver or is it something that the application
> must know.
>
> Also for string controls, I've only seen two implementations on RDS
> controls, so I've set these with low precedence/priority order
> compared with other control types.
>
> Awaiting comments, bash it all you want :-)
>
> Regards,
> Paulo
> ______________________
>
> [RFC] V4L2 Controls State Store/Restore File Format
>
> VERSION
>
> 0.0.1
>
> ABSTRACT
>
> This document proposes a standard for the file format used by v4l2
> applications to store/restore the controls state.
> This unified file format allows sharing control profiles between
> applications, making it much easier on both developers and users.
>
> INTRODUCTION
>
> V4l2 controls can be divided by classes and types.
> Controls in different classes are not dependent between themselves, on
> the other end if two controls belong to the same class they may or may
> not be dependent.
> A good example are automatic controls and their absolute counterparts,
> e.g.: V4L2_CID_AUTOGAIN and V4L2_CID_GAIN.
> Controls must be set following the dependency order, automatic
> controls must be set first or else setting the absolute value may
> fail, when that was not the intended behavior (auto disabled).
> After a quick analyses of the v4l2 controls, we are left to conclude
> that auto controls are in most cases of the
> boolean type, with some exceptions like V4L2_CID_EXPOSURE_AUTO, that
> is of the menu type.
> So ordering control priority by control type seems logical and it can
> be done in the following order:
>
> 1-V4L2_CTRL_TYPE_BOOLEAN
> 2-V4L2_CTRL_TYPE_MENU
> 3-V4L2_CTRL_TYPE_INTEGER
> 4-V4L2_CTRL_TYPE_INTEGER64
> 5-V4L2_CTRL_TYPE_STRING
>
> Button controls are stateless so they can't be stored and thus are out
> of the scope of this document.
> Relative controls are also in effect stateless, since they will always
> depend on their current state and thus can't be stored.
>
> There are also groups of controls that must be set atomically, so
> these need to be grouped together and properly identified when loading
> the controls state from a file.
>
> The proposed file format takes all of this into account and tries to
> make implementation of both store and restore functionality as easy as
> possible.
>
> FILE FORMAT
>
> The proposed file format is a regular text file with lines terminating
> with the newline character '\n'.
> Comments can be inserted by adding '#' at the beginning of the line,
> and can safely be ignored when parsing the file.
>
> FILE EXTENSION
>
> Although not much relevant, the file extension makes it easy to
> visually identify the file type and  also for applications to list
> relevant files, so we propose that v4l2 control state files be
> terminated by the suffix: ".v4l"
>
> FILE HEADER
>
> The file must always start with a commented line containing the file
> type identification and the version of this document on which it is
> based:
>
> #V4L2/CTRL/0.0.1
>
> Additionally it may contain extra information like the application
> name that generated the file and for usb devices the vid and pid of
> the device to whom the controls relate in hexadecimal notation:
>
> APP_NAME{"application name"}
> VID{0x00}
> PID{0x00}
>
> CONTROLS DATA
>
> The controls related data must be ordered by control type and for each
> type the ordering must be done by control ID. Ordering by control ID
> will also group the controls by class.
> The exception to the above rule are controls that need to be set
> atomically, these must be grouped together independent of their type.
>
> Each control must have is data set in a single line:
> ID{0x0000};CHK{min:max:step:def};EXT{[0|>0}=VAL{value}
>
> The ID key is the control v4l2 id in hex notation.
> The CHK key is used to match the control stored in file to the one we
> are trying to set on the device.
> Controls on different devices may have identical ID's but is unlikely
> that the correspondent values remain the same. All values are in
> decimal notation and correspond to the controls reported values.
> EXT indicates if the control must be set atomically, if it is set to a
> value higher than zero, then the next controls must be searched for
> identical EXT values,  all of them shall then be grouped and set using
> the extension control mechanism, VIDIOC_S_EXT_CTRLS.
> Controls with a EXT value of 0 can be set individually with a regular
> VIDIOC_S_CTRL.
> The VAL key contains the control state in decimal form.

Re: [RFC] V4L2 Controls State Store/Restore File Format

[Paulo Assis]

Martin Hi,

2010/5/21  <Martin_Rubli@logitech.com>:
> Hi Paulo,
>
> I haven't looked into the details, but why not use an XML format? It's less
> concise, yes, but it's standard, more extensible, and you don't have to
> worry about parsing it too much - after all, we already use libxml in
> libwebcam.
>

I've thought about this initially, xml would provide a standard format
without the strict rules of the one I'm proposing and yes it would be
very extensible and would also make it very simple to group controls,
however it as some drawbacks.
Mainly it is very hard to parse with standard c code and it would
almost certainly require an external lib (libxml).
This would be ok for libwebcam and probably some other apps, but the
idea was to create a format that requires only very simple code to
use.
When we finally decide on a format I'll right a small example that can
easily be integrated into any application, so I would rather not use
any external libs.
IMHO xml would be an overkill in this case, but if the general opinion
is that such format should be used instead I can easily change the
proposal to a xml format.

Regards,
Paulo


> Cheers,
> Martin
>
>
> Paulo Assis <pj.assis@gmail.com> wrote on 2010-05-20 21:11:36:
>
>> From: Paulo Assis <pj.assis@gmail.com>
>> To: Hans de Goede <hdegoede@redhat.com>
>
>> Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>,
>> Martin_Rubli@logitech.com
>> Date: 2010-05-20 21:11
>> Subject: [RFC] V4L2 Controls State Store/Restore File Format
>>
>> Hans,
>> Below is the RFC with my proposed control state file format for
>> store/restore functionality.
>> I have several doubts, mostly regarding controls that must be set
>> atomically with the extended control API.
>> The main question is:
>> How does an application know that a group of controls must be set
>> atomically ?
>> Is this reported by the driver or is it something that the application
>> must know.
>>
>> Also for string controls, I've only seen two implementations on RDS
>> controls, so I've set these with low precedence/priority order
>> compared with other control types.
>>
>> Awaiting comments, bash it all you want :-)
>>
>> Regards,
>> Paulo
>> ______________________
>>
>> [RFC] V4L2 Controls State Store/Restore File Format
>>
>> VERSION
>>
>> 0.0.1
>>
>> ABSTRACT
>>
>> This document proposes a standard for the file format used by v4l2
>> applications to store/restore the controls state.
>> This unified file format allows sharing control profiles between
>> applications, making it much easier on both developers and users.
>>
>> INTRODUCTION
>>
>> V4l2 controls can be divided by classes and types.
>> Controls in different classes are not dependent between themselves, on
>> the other end if two controls belong to the same class they may or may
>> not be dependent.
>> A good example are automatic controls and their absolute counterparts,
>> e.g.: V4L2_CID_AUTOGAIN and V4L2_CID_GAIN.
>> Controls must be set following the dependency order, automatic
>> controls must be set first or else setting the absolute value may
>> fail, when that was not the intended behavior (auto disabled).
>> After a quick analyses of the v4l2 controls, we are left to conclude
>> that auto controls are in most cases of the
>> boolean type, with some exceptions like V4L2_CID_EXPOSURE_AUTO, that
>> is of the menu type.
>> So ordering control priority by control type seems logical and it can
>> be done in the following order:
>>
>> 1-V4L2_CTRL_TYPE_BOOLEAN
>> 2-V4L2_CTRL_TYPE_MENU
>> 3-V4L2_CTRL_TYPE_INTEGER
>> 4-V4L2_CTRL_TYPE_INTEGER64
>> 5-V4L2_CTRL_TYPE_STRING
>>
>> Button controls are stateless so they can't be stored and thus are out
>> of the scope of this document.
>> Relative controls are also in effect stateless, since they will always
>> depend on their current state and thus can't be stored.
>>
>> There are also groups of controls that must be set atomically, so
>> these need to be grouped together and properly identified when loading
>> the controls state from a file.
>>
>> The proposed file format takes all of this into account and tries to
>> make implementation of both store and restore functionality as easy as
>> possible.
>>
>> FILE FORMAT
>>
>> The proposed file format is a regular text file with lines terminating
>> with the newline character '\n'.
>> Comments can be inserted by adding '#' at the beginning of the line,
>> and can safely be ignored when parsing the file.
>>
>> FILE EXTENSION
>>
>> Although not much relevant, the file extension makes it easy to
>> visually identify the file type and  also for applications to list
>> relevant files, so we propose that v4l2 control state files be
>> terminated by the suffix: ".v4l"
>>
>> FILE HEADER
>>
>> The file must always start with a commented line containing the file
>> type identification and the version of this document on which it is
>> based:
>>
>> #V4L2/CTRL/0.0.1
>>
>> Additionally it may contain extra information like the application
>> name that generated the file and for usb devices the vid and pid of
>> the device to whom the controls relate in hexadecimal notation:
>>
>> APP_NAME{"application name"}
>> VID{0x00}
>> PID{0x00}
>>
>> CONTROLS DATA
>>
>> The controls related data must be ordered by control type and for each
>> type the ordering must be done by control ID. Ordering by control ID
>> will also group the controls by class.
>> The exception to the above rule are controls that need to be set
>> atomically, these must be grouped together independent of their type.
>>
>> Each control must have is data set in a single line:
>> ID{0x0000};CHK{min:max:step:def};EXT{[0|>0}=VAL{value}
>>
>> The ID key is the control v4l2 id in hex notation.
>> The CHK key is used to match the control stored in file to the one we
>> are trying to set on the device.
>> Controls on different devices may have identical ID's but is unlikely
>> that the correspondent values remain the same. All values are in
>> decimal notation and correspond to the controls reported values.
>> EXT indicates if the control must be set atomically, if it is set to a
>> value higher than zero, then the next controls must be searched for
>> identical EXT values,  all of them shall then be grouped and set using
>> the extension control mechanism, VIDIOC_S_EXT_CTRLS.
>> Controls with a EXT value of 0 can be set individually with a regular
>> VIDIOC_S_CTRL.
>> The VAL key contains the control state in decimal form.
>

Re: [RFC] V4L2 Controls State Store/Restore File Format

[Hans Verkuil]

On Thursday 20 May 2010 16:42:01 Paulo Assis wrote:
> Hi all,
> 
> Below is a proposal for the file format to use when storing/restoring
> v4l2 controls state.
> 
> I've some doubts concerning atomically set controls and string
> controls (see below)
> that may be inducing me on error.
> The format is intended to be generic enough to support any control
> class so I hope
> to receive comments for any special cases that I might have missed or
> overlooked.
> Don't worry about bashing on the proposal to hard I have a hard skin :-D
> 
> Regards,
> Paulo
> 
> ---------- Forwarded message ----------
> From: Hans de Goede <hdegoede@redhat.com>
> Date: 2010/5/20
> Subject: Re: [RFC] V4L2 Controls State Store/Restore File Format
> To: Paulo Assis <pj.assis@gmail.com>
> Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>,
> Martin_Rubli@logitech.com
> 
> 
> Hi Paulo,
> 
> Clearly you've though quite a bit about this I had not realized
> this would be this complex (with ordering issues etc.).
> 
> This looks like a good proposal to start with to me, I think it
> would be good to further discuss this on the linux-media list,
> where other v4l devs can read it and chime in.
> 
> Regards,
> 
> Hans
> 
> 
> On 05/20/2010 03:11 PM, Paulo Assis wrote:
> >
> > Hans,
> > Below is the RFC with my proposed control state file format for
> > store/restore functionality.
> > I have several doubts, mostly regarding controls that must be set
> > atomically with the extended control API.
> > The main question is:
> > How does an application know that a group of controls must be set atomically ?
> > Is this reported by the driver or is it something that the application
> > must know.
> >
> > Also for string controls, I've only seen two implementations on RDS
> > controls, so I've set these with low precedence/priority order
> > compared with other control types.
> >
> > Awaiting comments, bash it all you want :-)
> >
> > Regards,
> > Paulo
> > ______________________
> >
> > [RFC] V4L2 Controls State Store/Restore File Format
> >
> > VERSION
> >
> > 0.0.1
> >
> > ABSTRACT
> >
> > This document proposes a standard for the file format used by v4l2
> > applications to store/restore the controls state.
> > This unified file format allows sharing control profiles between
> > applications, making it much easier on both developers and users.
> >
> > INTRODUCTION
> >
> > V4l2 controls can be divided by classes and types.
> > Controls in different classes are not dependent between themselves, on
> > the other end if two controls belong to the same class they may or may
> > not be dependent.
> > A good example are automatic controls and their absolute counterparts,
> > e.g.: V4L2_CID_AUTOGAIN and V4L2_CID_GAIN.
> > Controls must be set following the dependency order, automatic
> > controls must be set first or else setting the absolute value may
> > fail, when that was not the intended behavior (auto disabled).
> > After a quick analyses of the v4l2 controls, we are left to conclude
> > that auto controls are in most cases of the
> > boolean type, with some exceptions like V4L2_CID_EXPOSURE_AUTO, that
> > is of the menu type.
> > So ordering control priority by control type seems logical and it can
> > be done in the following order:
> >
> > 1-V4L2_CTRL_TYPE_BOOLEAN
> > 2-V4L2_CTRL_TYPE_MENU
> > 3-V4L2_CTRL_TYPE_INTEGER
> > 4-V4L2_CTRL_TYPE_INTEGER64
> > 5-V4L2_CTRL_TYPE_STRING

I'm not sure whether the ordering is needed, it sounds more like a driver bug
that you are trying to work around.

When you retrieve the state of controls, then the value of the controls must be
valid. So you should be able to set it later. There are some dependencies,
for example selecting a particular MPEG video encoding might deactivate some
controls and activate others. But the INACTIVE flag should be used to mark that,
never the DISABLED flag. And you can still set inactive controls.

For controls not belonging to the user class I would store and restore them
all using G/S_EXT_CTRLS. So for each class just get all controls that are both
readable and writable and not disabled, then get or set them in one call.

For the user class controls you can do the same, but if that fails, then you
have to fallback to G/S_CTRL on a per-control basis.

The main problem at the moment is that control handling stinks. Which is why
I am working on a new control framework that will handle everything in the
v4l core greatly simplifying drivers and providing a unified and consistent
interface towards applications.

Regards,

	Hans

> >
> > Button controls are stateless so they can't be stored and thus are out
> > of the scope of this document.
> > Relative controls are also in effect stateless, since they will always
> > depend on their current state and thus can't be stored.
> >
> > There are also groups of controls that must be set atomically, so
> > these need to be grouped together and properly identified when loading
> > the controls state from a file.
> >
> > The proposed file format takes all of this into account and tries to
> > make implementation of both store and restore functionality as easy as
> > possible.
> >
> > FILE FORMAT
> >
> > The proposed file format is a regular text file with lines terminating
> > with the newline character '\n'.
> > Comments can be inserted by adding '#' at the beginning of the line,
> > and can safely be ignored when parsing the file.
> >
> > FILE EXTENSION
> >
> > Although not much relevant, the file extension makes it easy to
> > visually identify the file type and  also for applications to list
> > relevant files, so we propose that v4l2 control state files be
> > terminated by the suffix: ".v4l"
> >
> > FILE HEADER
> >
> > The file must always start with a commented line containing the file
> > type identification and the version of this document on which it is
> > based:
> >
> > #V4L2/CTRL/0.0.1
> >
> > Additionally it may contain extra information like the application
> > name that generated the file and for usb devices the vid and pid of
> > the device to whom the controls relate in hexadecimal notation:
> >
> > APP_NAME{"application name"}
> > VID{0x00}
> > PID{0x00}
> >
> > CONTROLS DATA
> >
> > The controls related data must be ordered by control type and for each
> > type the ordering must be done by control ID. Ordering by control ID
> > will also group the controls by class.
> > The exception to the above rule are controls that need to be set
> > atomically, these must be grouped together independent of their type.
> >
> > Each control must have is data set in a single line:
> > ID{0x0000};CHK{min:max:step:def};EXT{[0|>0}=VAL{value}
> >
> > The ID key is the control v4l2 id in hex notation.
> > The CHK key is used to match the control stored in file to the one we
> > are trying to set on the device.
> > Controls on different devices may have identical ID's but is unlikely
> > that the correspondent values remain the same. All values are in
> > decimal notation and correspond to the controls reported values.
> > EXT indicates if the control must be set atomically, if it is set to a
> > value higher than zero, then the next controls must be searched for
> > identical EXT values,  all of them shall then be grouped and set using
> > the extension control mechanism, VIDIOC_S_EXT_CTRLS.
> > Controls with a EXT value of 0 can be set individually with a regular
> > VIDIOC_S_CTRL.
> > The VAL key contains the control state in decimal form.
> --
> To unsubscribe from this list: send the line "unsubscribe linux-media" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 
> 

-- 
Hans Verkuil - video4linux developer - sponsored by TANDBERG, part of Cisco

Re: [RFC] V4L2 Controls State Store/Restore File Format

[Paulo Assis]

Hans,

2010/5/23 Hans Verkuil <hverkuil@xs4all.nl>:
> On Thursday 20 May 2010 16:42:01 Paulo Assis wrote:
>> Hi all,
>>
>> Below is a proposal for the file format to use when storing/restoring
>> v4l2 controls state.
>>
>> I've some doubts concerning atomically set controls and string
>> controls (see below)
>> that may be inducing me on error.
>> The format is intended to be generic enough to support any control
>> class so I hope
>> to receive comments for any special cases that I might have missed or
>> overlooked.
>> Don't worry about bashing on the proposal to hard I have a hard skin :-D
>>
>> Regards,
>> Paulo
>>
>> ---------- Forwarded message ----------
>> From: Hans de Goede <hdegoede@redhat.com>
>> Date: 2010/5/20
>> Subject: Re: [RFC] V4L2 Controls State Store/Restore File Format
>> To: Paulo Assis <pj.assis@gmail.com>
>> Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>,
>> Martin_Rubli@logitech.com
>>
>>
>> Hi Paulo,
>>
>> Clearly you've though quite a bit about this I had not realized
>> this would be this complex (with ordering issues etc.).
>>
>> This looks like a good proposal to start with to me, I think it
>> would be good to further discuss this on the linux-media list,
>> where other v4l devs can read it and chime in.
>>
>> Regards,
>>
>> Hans
>>
>>
>> On 05/20/2010 03:11 PM, Paulo Assis wrote:
>> >
>> > Hans,
>> > Below is the RFC with my proposed control state file format for
>> > store/restore functionality.
>> > I have several doubts, mostly regarding controls that must be set
>> > atomically with the extended control API.
>> > The main question is:
>> > How does an application know that a group of controls must be set atomically ?
>> > Is this reported by the driver or is it something that the application
>> > must know.
>> >
>> > Also for string controls, I've only seen two implementations on RDS
>> > controls, so I've set these with low precedence/priority order
>> > compared with other control types.
>> >
>> > Awaiting comments, bash it all you want :-)
>> >
>> > Regards,
>> > Paulo
>> > ______________________
>> >
>> > [RFC] V4L2 Controls State Store/Restore File Format
>> >
>> > VERSION
>> >
>> > 0.0.1
>> >
>> > ABSTRACT
>> >
>> > This document proposes a standard for the file format used by v4l2
>> > applications to store/restore the controls state.
>> > This unified file format allows sharing control profiles between
>> > applications, making it much easier on both developers and users.
>> >
>> > INTRODUCTION
>> >
>> > V4l2 controls can be divided by classes and types.
>> > Controls in different classes are not dependent between themselves, on
>> > the other end if two controls belong to the same class they may or may
>> > not be dependent.
>> > A good example are automatic controls and their absolute counterparts,
>> > e.g.: V4L2_CID_AUTOGAIN and V4L2_CID_GAIN.
>> > Controls must be set following the dependency order, automatic
>> > controls must be set first or else setting the absolute value may
>> > fail, when that was not the intended behavior (auto disabled).
>> > After a quick analyses of the v4l2 controls, we are left to conclude
>> > that auto controls are in most cases of the
>> > boolean type, with some exceptions like V4L2_CID_EXPOSURE_AUTO, that
>> > is of the menu type.
>> > So ordering control priority by control type seems logical and it can
>> > be done in the following order:
>> >
>> > 1-V4L2_CTRL_TYPE_BOOLEAN
>> > 2-V4L2_CTRL_TYPE_MENU
>> > 3-V4L2_CTRL_TYPE_INTEGER
>> > 4-V4L2_CTRL_TYPE_INTEGER64
>> > 5-V4L2_CTRL_TYPE_STRING
>
> I'm not sure whether the ordering is needed, it sounds more like a driver bug
> that you are trying to work around.
>
> When you retrieve the state of controls, then the value of the controls must be
> valid. So you should be able to set it later. There are some dependencies,
> for example selecting a particular MPEG video encoding might deactivate some
> controls and activate others. But the INACTIVE flag should be used to mark that,
> never the DISABLED flag. And you can still set inactive controls.
>

How would this work for controls like "Exposure, Auto" ?
In the cameras I've tested if we don't set it to manual first, changing
"Exposure (Absolute)" fails. Maybe it's a uvcvideo a bug, I'm not sure.
The same for "White Balance Temperature, Auto" and
"White Balance Temperature".  They all return a EIO error.

> For controls not belonging to the user class I would store and restore them
> all using G/S_EXT_CTRLS. So for each class just get all controls that are both
> readable and writable and not disabled, then get or set them in one call.
>
I'll have to test at least camera class controls and see if this works.

> For the user class controls you can do the same, but if that fails, then you
> have to fallback to G/S_CTRL on a per-control basis.
>
I'll test this to!


> The main problem at the moment is that control handling stinks. Which is why
> I am working on a new control framework that will handle everything in the
> v4l core greatly simplifying drivers and providing a unified and consistent
> interface towards applications.
>

Will this bring any changes to the API, or is just at the core level ?


Best Regards,
Paulo

> Regards,
>
>        Hans
>
>> >
>> > Button controls are stateless so they can't be stored and thus are out
>> > of the scope of this document.
>> > Relative controls are also in effect stateless, since they will always
>> > depend on their current state and thus can't be stored.
>> >
>> > There are also groups of controls that must be set atomically, so
>> > these need to be grouped together and properly identified when loading
>> > the controls state from a file.
>> >
>> > The proposed file format takes all of this into account and tries to
>> > make implementation of both store and restore functionality as easy as
>> > possible.
>> >
>> > FILE FORMAT
>> >
>> > The proposed file format is a regular text file with lines terminating
>> > with the newline character '\n'.
>> > Comments can be inserted by adding '#' at the beginning of the line,
>> > and can safely be ignored when parsing the file.
>> >
>> > FILE EXTENSION
>> >
>> > Although not much relevant, the file extension makes it easy to
>> > visually identify the file type and  also for applications to list
>> > relevant files, so we propose that v4l2 control state files be
>> > terminated by the suffix: ".v4l"
>> >
>> > FILE HEADER
>> >
>> > The file must always start with a commented line containing the file
>> > type identification and the version of this document on which it is
>> > based:
>> >
>> > #V4L2/CTRL/0.0.1
>> >
>> > Additionally it may contain extra information like the application
>> > name that generated the file and for usb devices the vid and pid of
>> > the device to whom the controls relate in hexadecimal notation:
>> >
>> > APP_NAME{"application name"}
>> > VID{0x00}
>> > PID{0x00}
>> >
>> > CONTROLS DATA
>> >
>> > The controls related data must be ordered by control type and for each
>> > type the ordering must be done by control ID. Ordering by control ID
>> > will also group the controls by class.
>> > The exception to the above rule are controls that need to be set
>> > atomically, these must be grouped together independent of their type.
>> >
>> > Each control must have is data set in a single line:
>> > ID{0x0000};CHK{min:max:step:def};EXT{[0|>0}=VAL{value}
>> >
>> > The ID key is the control v4l2 id in hex notation.
>> > The CHK key is used to match the control stored in file to the one we
>> > are trying to set on the device.
>> > Controls on different devices may have identical ID's but is unlikely
>> > that the correspondent values remain the same. All values are in
>> > decimal notation and correspond to the controls reported values.
>> > EXT indicates if the control must be set atomically, if it is set to a
>> > value higher than zero, then the next controls must be searched for
>> > identical EXT values,  all of them shall then be grouped and set using
>> > the extension control mechanism, VIDIOC_S_EXT_CTRLS.
>> > Controls with a EXT value of 0 can be set individually with a regular
>> > VIDIOC_S_CTRL.
>> > The VAL key contains the control state in decimal form.
>> --
>> To unsubscribe from this list: send the line "unsubscribe linux-media" in
>> the body of a message to majordomo@vger.kernel.org
>> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>>
>>
>
> --
> Hans Verkuil - video4linux developer - sponsored by TANDBERG, part of Cisco
>

Re: [RFC] V4L2 Controls State Store/Restore File Format

[Hans Verkuil]

On Sunday 23 May 2010 15:40:26 Paulo Assis wrote:
> Hans,
> 
> 2010/5/23 Hans Verkuil <hverkuil@xs4all.nl>:
> > On Thursday 20 May 2010 16:42:01 Paulo Assis wrote:
> >> Hi all,
> >>
> >> Below is a proposal for the file format to use when storing/restoring
> >> v4l2 controls state.
> >>
> >> I've some doubts concerning atomically set controls and string
> >> controls (see below)
> >> that may be inducing me on error.
> >> The format is intended to be generic enough to support any control
> >> class so I hope
> >> to receive comments for any special cases that I might have missed or
> >> overlooked.
> >> Don't worry about bashing on the proposal to hard I have a hard skin :-D
> >>
> >> Regards,
> >> Paulo
> >>
> >> ---------- Forwarded message ----------
> >> From: Hans de Goede <hdegoede@redhat.com>
> >> Date: 2010/5/20
> >> Subject: Re: [RFC] V4L2 Controls State Store/Restore File Format
> >> To: Paulo Assis <pj.assis@gmail.com>
> >> Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>,
> >> Martin_Rubli@logitech.com
> >>
> >>
> >> Hi Paulo,
> >>
> >> Clearly you've though quite a bit about this I had not realized
> >> this would be this complex (with ordering issues etc.).
> >>
> >> This looks like a good proposal to start with to me, I think it
> >> would be good to further discuss this on the linux-media list,
> >> where other v4l devs can read it and chime in.
> >>
> >> Regards,
> >>
> >> Hans
> >>
> >>
> >> On 05/20/2010 03:11 PM, Paulo Assis wrote:
> >> >
> >> > Hans,
> >> > Below is the RFC with my proposed control state file format for
> >> > store/restore functionality.
> >> > I have several doubts, mostly regarding controls that must be set
> >> > atomically with the extended control API.
> >> > The main question is:
> >> > How does an application know that a group of controls must be set atomically ?
> >> > Is this reported by the driver or is it something that the application
> >> > must know.
> >> >
> >> > Also for string controls, I've only seen two implementations on RDS
> >> > controls, so I've set these with low precedence/priority order
> >> > compared with other control types.
> >> >
> >> > Awaiting comments, bash it all you want :-)
> >> >
> >> > Regards,
> >> > Paulo
> >> > ______________________
> >> >
> >> > [RFC] V4L2 Controls State Store/Restore File Format
> >> >
> >> > VERSION
> >> >
> >> > 0.0.1
> >> >
> >> > ABSTRACT
> >> >
> >> > This document proposes a standard for the file format used by v4l2
> >> > applications to store/restore the controls state.
> >> > This unified file format allows sharing control profiles between
> >> > applications, making it much easier on both developers and users.
> >> >
> >> > INTRODUCTION
> >> >
> >> > V4l2 controls can be divided by classes and types.
> >> > Controls in different classes are not dependent between themselves, on
> >> > the other end if two controls belong to the same class they may or may
> >> > not be dependent.
> >> > A good example are automatic controls and their absolute counterparts,
> >> > e.g.: V4L2_CID_AUTOGAIN and V4L2_CID_GAIN.
> >> > Controls must be set following the dependency order, automatic
> >> > controls must be set first or else setting the absolute value may
> >> > fail, when that was not the intended behavior (auto disabled).
> >> > After a quick analyses of the v4l2 controls, we are left to conclude
> >> > that auto controls are in most cases of the
> >> > boolean type, with some exceptions like V4L2_CID_EXPOSURE_AUTO, that
> >> > is of the menu type.
> >> > So ordering control priority by control type seems logical and it can
> >> > be done in the following order:
> >> >
> >> > 1-V4L2_CTRL_TYPE_BOOLEAN
> >> > 2-V4L2_CTRL_TYPE_MENU
> >> > 3-V4L2_CTRL_TYPE_INTEGER
> >> > 4-V4L2_CTRL_TYPE_INTEGER64
> >> > 5-V4L2_CTRL_TYPE_STRING
> >
> > I'm not sure whether the ordering is needed, it sounds more like a driver bug
> > that you are trying to work around.
> >
> > When you retrieve the state of controls, then the value of the controls must be
> > valid. So you should be able to set it later. There are some dependencies,
> > for example selecting a particular MPEG video encoding might deactivate some
> > controls and activate others. But the INACTIVE flag should be used to mark that,
> > never the DISABLED flag. And you can still set inactive controls.
> >
> 
> How would this work for controls like "Exposure, Auto" ?
> In the cameras I've tested if we don't set it to manual first, changing
> "Exposure (Absolute)" fails. Maybe it's a uvcvideo a bug, I'm not sure.
> The same for "White Balance Temperature, Auto" and
> "White Balance Temperature".  They all return a EIO error.

That's definitely wrong. Either they should set the INACTIVE flag and just
accept the new value (possibly storing it internally), or they should set
the READONLY flag and return -EACCES or -EINVAL. The spec says -EINVAL but we
want to change that to -EACCES. -EIO should only be used for failing hardware.
I.e. i2c errors or something like that.

But as I said there is a wild variety of ways in which drivers handle controls.
It's why I'm working on the control framework and why I want to get that in
asap.

> 
> > For controls not belonging to the user class I would store and restore them
> > all using G/S_EXT_CTRLS. So for each class just get all controls that are both
> > readable and writable and not disabled, then get or set them in one call.
> >
> I'll have to test at least camera class controls and see if this works.
> 
> > For the user class controls you can do the same, but if that fails, then you
> > have to fallback to G/S_CTRL on a per-control basis.
> >
> I'll test this to!

Note that all or almost all drivers will currently fail when you try to use
G/S_EXT_CTRLS with user class controls. But the new framework will handle this
just fine.

> 
> 
> > The main problem at the moment is that control handling stinks. Which is why
> > I am working on a new control framework that will handle everything in the
> > v4l core greatly simplifying drivers and providing a unified and consistent
> > interface towards applications.
> >
> 
> Will this bring any changes to the API, or is just at the core level ?

There will be a few small changes to the API with respect to error codes.

The latest patch series is here:

http://thread.gmane.org/gmane.linux.drivers.video-input-infrastructure/19318

Look at patch 3/15, section 'Differences from the Spec' (almost at the end
of the patch).

But most drivers that switch to this framework will probably behave differently
since most drivers behave inconsistently when it comes to corner cases. Such
as the EIO error code in your example.

Regards,

	Hans

-- 
Hans Verkuil - video4linux developer - sponsored by TANDBERG, part of Cisco

Re: [RFC] V4L2 Controls State Store/Restore File Format

[Paulo Assis]

Hi,

2010/5/23 Hans Verkuil <hverkuil@xs4all.nl>:
> On Sunday 23 May 2010 15:40:26 Paulo Assis wrote:
>> Hans,
>>
>> 2010/5/23 Hans Verkuil <hverkuil@xs4all.nl>:
>> > On Thursday 20 May 2010 16:42:01 Paulo Assis wrote:
>> >> Hi all,
>> >>
>> >> Below is a proposal for the file format to use when storing/restoring
>> >> v4l2 controls state.
>> >>
>> >> I've some doubts concerning atomically set controls and string
>> >> controls (see below)
>> >> that may be inducing me on error.
>> >> The format is intended to be generic enough to support any control
>> >> class so I hope
>> >> to receive comments for any special cases that I might have missed or
>> >> overlooked.
>> >> Don't worry about bashing on the proposal to hard I have a hard skin :-D
>> >>
>> >> Regards,
>> >> Paulo
>> >>
>> >> ---------- Forwarded message ----------
>> >> From: Hans de Goede <hdegoede@redhat.com>
>> >> Date: 2010/5/20
>> >> Subject: Re: [RFC] V4L2 Controls State Store/Restore File Format
>> >> To: Paulo Assis <pj.assis@gmail.com>
>> >> Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>,
>> >> Martin_Rubli@logitech.com
>> >>
>> >>
>> >> Hi Paulo,
>> >>
>> >> Clearly you've though quite a bit about this I had not realized
>> >> this would be this complex (with ordering issues etc.).
>> >>
>> >> This looks like a good proposal to start with to me, I think it
>> >> would be good to further discuss this on the linux-media list,
>> >> where other v4l devs can read it and chime in.
>> >>
>> >> Regards,
>> >>
>> >> Hans
>> >>
>> >>
>> >> On 05/20/2010 03:11 PM, Paulo Assis wrote:
>> >> >
>> >> > Hans,
>> >> > Below is the RFC with my proposed control state file format for
>> >> > store/restore functionality.
>> >> > I have several doubts, mostly regarding controls that must be set
>> >> > atomically with the extended control API.
>> >> > The main question is:
>> >> > How does an application know that a group of controls must be set atomically ?
>> >> > Is this reported by the driver or is it something that the application
>> >> > must know.
>> >> >
>> >> > Also for string controls, I've only seen two implementations on RDS
>> >> > controls, so I've set these with low precedence/priority order
>> >> > compared with other control types.
>> >> >
>> >> > Awaiting comments, bash it all you want :-)
>> >> >
>> >> > Regards,
>> >> > Paulo
>> >> > ______________________
>> >> >
>> >> > [RFC] V4L2 Controls State Store/Restore File Format
>> >> >
>> >> > VERSION
>> >> >
>> >> > 0.0.1
>> >> >
>> >> > ABSTRACT
>> >> >
>> >> > This document proposes a standard for the file format used by v4l2
>> >> > applications to store/restore the controls state.
>> >> > This unified file format allows sharing control profiles between
>> >> > applications, making it much easier on both developers and users.
>> >> >
>> >> > INTRODUCTION
>> >> >
>> >> > V4l2 controls can be divided by classes and types.
>> >> > Controls in different classes are not dependent between themselves, on
>> >> > the other end if two controls belong to the same class they may or may
>> >> > not be dependent.
>> >> > A good example are automatic controls and their absolute counterparts,
>> >> > e.g.: V4L2_CID_AUTOGAIN and V4L2_CID_GAIN.
>> >> > Controls must be set following the dependency order, automatic
>> >> > controls must be set first or else setting the absolute value may
>> >> > fail, when that was not the intended behavior (auto disabled).
>> >> > After a quick analyses of the v4l2 controls, we are left to conclude
>> >> > that auto controls are in most cases of the
>> >> > boolean type, with some exceptions like V4L2_CID_EXPOSURE_AUTO, that
>> >> > is of the menu type.
>> >> > So ordering control priority by control type seems logical and it can
>> >> > be done in the following order:
>> >> >
>> >> > 1-V4L2_CTRL_TYPE_BOOLEAN
>> >> > 2-V4L2_CTRL_TYPE_MENU
>> >> > 3-V4L2_CTRL_TYPE_INTEGER
>> >> > 4-V4L2_CTRL_TYPE_INTEGER64
>> >> > 5-V4L2_CTRL_TYPE_STRING
>> >
>> > I'm not sure whether the ordering is needed, it sounds more like a driver bug
>> > that you are trying to work around.
>> >
>> > When you retrieve the state of controls, then the value of the controls must be
>> > valid. So you should be able to set it later. There are some dependencies,
>> > for example selecting a particular MPEG video encoding might deactivate some
>> > controls and activate others. But the INACTIVE flag should be used to mark that,
>> > never the DISABLED flag. And you can still set inactive controls.
>> >
>>
>> How would this work for controls like "Exposure, Auto" ?
>> In the cameras I've tested if we don't set it to manual first, changing
>> "Exposure (Absolute)" fails. Maybe it's a uvcvideo a bug, I'm not sure.
>> The same for "White Balance Temperature, Auto" and
>> "White Balance Temperature".  They all return a EIO error.
>
> That's definitely wrong. Either they should set the INACTIVE flag and just
> accept the new value (possibly storing it internally), or they should set
> the READONLY flag and return -EACCES or -EINVAL. The spec says -EINVAL but we
> want to change that to -EACCES. -EIO should only be used for failing hardware.
> I.e. i2c errors or something like that.
>
> But as I said there is a wild variety of ways in which drivers handle controls.
> It's why I'm working on the control framework and why I want to get that in
> asap.
>

Still I'm guessing this won't be fully available in drivers before 2.6.36/37.
And applications would still need to support older kernel versions, so
in the end
ordering the controls would work for both the new control framework and older
kernels (with "buggy" drivers).


>>
>> > For controls not belonging to the user class I would store and restore them
>> > all using G/S_EXT_CTRLS. So for each class just get all controls that are both
>> > readable and writable and not disabled, then get or set them in one call.
>> >
>> I'll have to test at least camera class controls and see if this works.
>>
>> > For the user class controls you can do the same, but if that fails, then you
>> > have to fallback to G/S_CTRL on a per-control basis.
>> >
>> I'll test this to!
>
> Note that all or almost all drivers will currently fail when you try to use
> G/S_EXT_CTRLS with user class controls. But the new framework will handle this
> just fine.
>

Like I said before ordering the controls would still work for both cases.
But probably ordering first by control class and then by type is a better idea,
As it allows the use of TRY/S_EXT_CTRLS first, although from what I could
read from the framework proposal, the requirement that all controls belong to
the same Class will no longer apply.

Regards,
Paulo

>>
>>
>> > The main problem at the moment is that control handling stinks. Which is why
>> > I am working on a new control framework that will handle everything in the
>> > v4l core greatly simplifying drivers and providing a unified and consistent
>> > interface towards applications.
>> >
>>
>> Will this bring any changes to the API, or is just at the core level ?
>
> There will be a few small changes to the API with respect to error codes.
>
> The latest patch series is here:
>
> http://thread.gmane.org/gmane.linux.drivers.video-input-infrastructure/19318
>
> Look at patch 3/15, section 'Differences from the Spec' (almost at the end
> of the patch).
>
> But most drivers that switch to this framework will probably behave differently
> since most drivers behave inconsistently when it comes to corner cases. Such
> as the EIO error code in your example.
>
> Regards,
>
>        Hans
>
> --
> Hans Verkuil - video4linux developer - sponsored by TANDBERG, part of Cisco
>