driver-api/media/v4l2-controls.rst

9 The V4L2 control API seems simple enough, but quickly becomes very hard to
15 1) How do I add a control?
16 2) How do I set the control's value? (i.e. s_ctrl)
20 3) How do I get the control's value? (i.e. g_volatile_ctrl)
21 4) How do I validate the user's proposed control value? (i.e. try_ctrl)
25 The control framework was created in order to implement all the rules of the
29 Note that the control framework relies on the presence of a struct
39 The :c:type:`v4l2_ctrl` object describes the control properties and keeps
40 track of the control's value (both the current value and the proposed new
93 1.3) Hook the control handler into the driver:
202 the new control, but if you do not need to access the pointer outside the
203 control ops, then there is no need to store it.
206 the control ID except for the min, max, step and default values. These are
208 control attributes like type, name, flags are all global. The control's
217 integer menu control with driver-specific items in the menu. It differs
224 driver specific menu for an otherwise standard menu control. A good example
225 for this control is the test pattern control for capture/display/sensors
238 It is recommended to add controls in ascending control ID order: it will be
241 3) Optionally force initial control setup:
248 initializes the hardware to the default control values. It is recommended
279 The control ops are called with the v4l2_ctrl pointer as argument.
280 The new control value has already been validated, so all you need to do is
284 to do any validation of control values, or implement QUERYCTRL, QUERY_EXT_CTRL
302 skipped (so a V4L2 driver can always override a subdev control).
309 Accessing Control Values
312 The following union is used inside the control framework to access control
338 If the control has a simple s32 type, then:
348 Within the control ops you can freely use these. The val and cur.val speak for
352 Unless the control is marked volatile the p_cur field points to the
353 current cached control value. When you create a new control this value is made
377 are not, a V4L2_EVENT_CTRL_CH_VALUE will not be generated when the control
380 To mark a control as volatile you have to set V4L2_CTRL_FLAG_VOLATILE:
392 If s_ctrl returns 0 (OK), then the control framework will copy the new final
400 Outside of the control ops you have to go through to helper functions to get
401 or set a single control value safely in your driver:
408 These functions go through the control framework just as VIDIOC_G/S_CTRL ioctls
409 do. Don't use these inside the control ops g_volatile/s/try_ctrl, though, that
440 A good example is the MPEG Audio Layer II Bitrate menu control where the
447 control, or by calling v4l2_ctrl_new_std_menu().
475 control and will fill in the name, type and flags fields accordingly.
482 activate and deactivate controls. For example, if the Chroma AGC control is
483 on, then the Chroma Gain control is inactive. That is, you may set it, but
485 control is on. Typically user interfaces can disable such input fields.
492 The other flag is the 'grabbed' flag. A grabbed control means that you cannot
496 If a control is set to 'grabbed' using v4l2_ctrl_grab(), then the framework
497 will return -EBUSY if an attempt is made to set this control. The
502 Control Clusters
506 complex scenarios you can get dependencies from one control to another.
526 cluster is set (or 'gotten', or 'tried'), only the control ops of the first
527 control ('volume' in this example) is called. You effectively create a new
528 composite control. Similar to how a 'struct' works in C.
571 The anonymous struct is used to clearly 'cluster' these two control pointers,
573 array with two control pointers. So you can just do:
587 only restriction is that the first control of the cluster must always be
588 present, since that is the 'master' control of the cluster. The master
589 control is the one that identifies the cluster and that provides the
593 a valid control or to NULL.
597 each control. For example, in the case of a volume/mute cluster the 'is_new'
598 flag of the mute control would be set if the user called VIDIOC_S_CTRL for
608 A common type of control cluster is one that handles 'auto-foo/foo'-type
610 autowhitebalance/red balance/blue balance. In all cases you have one control
611 that determines whether another control is handled automatically by the hardware,
612 or whether it is under manual control from the user.
625 Finally the V4L2_CTRL_FLAG_UPDATE should be set for the auto control since
626 changing that control affects the control flags of the manual controls.
644 The first control of the cluster is assumed to be the 'auto' control.
663 Usually the V4L2 driver has just one control handler that is global for
664 all video nodes. But you can also specify different control handlers for
670 control handler. You do that by simply setting the ctrl_handler field in
675 manually to add the subdev's control handler (sd->ctrl_handler) to the desired
676 control handler. This control handler may be specific to the video_device or
678 audio controls, while the video and vbi device nodes share the same control
715 control. The rule is to have one control for each hardware 'knob' that you
725 But sometimes you need to find a control from another handler that you do
726 not own. For example, if you have to find a volume control from a subdev.
755 attempting to find another control from the same handler will deadlock.
757 It is recommended not to use this function from inside the control ops.
763 When one control handler is added to another using v4l2_ctrl_add_handler, then
768 setting the 'is_private' flag of the control to 1:
775 		.name = "Some Private Control",
790 Controls of this type can be used by GUIs to get the name of the control class.
792 containing the controls belonging to a particular control class. The name of
793 each tab can be found by querying a special control with ID <control class | 1>.
796 a control of this type whenever the first control belonging to a new control
803 Sometimes the platform or bridge driver needs to be notified when a control
812 Whenever the give control changes value the notify callback will be called
813 with a pointer to the control and the priv pointer that was passed with
814 v4l2_ctrl_notify. Note that the control's handler lock is held when the
817 There can be only one notify function per control handler. Any attempt