include/media/v4l2-ctrls.h

18  * Include the stateless codec compound control definitions.
40  * union v4l2_ctrl_ptr - A pointer to a control value.
109  * struct v4l2_ctrl_ops - The control operations that the driver has to provide.
111  * @g_volatile_ctrl: Get a new value for this control. Generally only relevant
112  *		for volatile (and usually read-only) controls such as a control
116  * @try_ctrl:	Test whether the control's value is valid. Only relevant when
118  * @s_ctrl:	Actually set the new control value. s_ctrl is compulsory. The
131  * struct v4l2_ctrl_type_ops - The control type operations that the driver
155  *	that should be called when a control value has changed.
158  * @priv: control private data
166  * struct v4l2_ctrl - The control structure.
169  * @ev_subs:	The list of control event subscriptions.
170  * @handler:	The handler that owns the control.
173  * @done:	Internal flag: set for each processed control.
174  * @is_new:	Set when the user specified a new value for this control. It
179  * @is_private: If set, then this control is private to its handler and it
182  * @is_auto:   If set, then this control selects whether the other cluster
186  * @is_int:    If set, then this control has a simple integer value (i.e. it
188  * @is_string: If set, then this control has type %V4L2_CTRL_TYPE_STRING.
189  * @is_ptr:	If set, then this control is an array and/or has type >=
193  * @is_array: If set, then this control contains an N-dimensional array.
197  *		control's value changes.
199  *		of the auto control that determines if that control is in
200  *		manual mode. So if the value of the auto control equals this
203  * @ops:	The control ops.
204  * @type_ops:	The control type ops.
205  * @id:	The control ID.
206  * @name:	The control name.
207  * @type:	The control type.
208  * @minimum:	The control's minimum value.
209  * @maximum:	The control's maximum value.
210  * @default_value: The control's default value.
211  * @step:	The control's step value for non-menu controls.
213  * @elem_size:	The size in bytes of the control.
216  * @menu_skip_mask: The control's skip mask for menu controls. This makes it
231  * @flags:	The control's flags.
233  * @cur.val:	The control's current value, if the @type is represented via
235  * @val:	The control's new s32 value.
236  * @priv:	The control's private pointer. For use by the driver. It is
237  *		untouched by the control framework. Note that this pointer is
238  *		not freed when the control is deleted. Should this be needed
241  * @p_def:	The control's default value represented via a union which
242  *		provides a standard way of accessing control types
244  * @p_cur:	The control's current value represented via a union which
245  *		provides a standard way of accessing control types
247  * @p_new:	The control's new value represented via a union which provides
248  *		a standard way of accessing control types
306  * struct v4l2_ctrl_ref - The control reference.
310  * @ctrl:	The actual control information.
315  * @req_done:	Internal flag: if the control handler containing this control
317  *		the control has been applied. This prevents applying controls
319  *		control of a cluster is applied, they all are).
320  * @valid_p_req: If set, then p_req contains the control value for the request.
321  * @p_req:	If the control handler containing this control reference
323  *		value of the control that must be applied when the request
324  *		is executed, or to the value of the control at the time
326  *		then this control was never set for this request and the
327  *		control will not be updated when this request is applied.
329  * Each control handler has a list of these refs. The list_head is used to
330  * keep a sorted-by-control-ID list of all controls, while the next pointer
331  * is used to link the control in the hash's bucket.
347  * struct v4l2_ctrl_handler - The control handler keeps track of all the
352  * @lock:	Lock to control access to this handler and its controls.
355  * @ctrl_refs:	The list of control references.
356  * @cached:	The last found control reference. It is common that the same
357  *		control is needed multiple times, so this is a simple
359  * @buckets:	Buckets for the hashing. Allows for quick control lookup.
360  * @notify:	A notify callback that is called whenever the control changes
366  * @error:	The error code of the first failed control addition.
368  * @requests:	List to keep track of open control handler request objects.
369  *		For the parent control handler (@req_obj.ops == NULL) this
370  *		is the list header. When the parent control handler is
399  * struct v4l2_ctrl_config - Control configuration structure.
401  * @ops:	The control ops.
402  * @type_ops:	The control type ops. Only needed for compound controls.
403  * @id:	The control ID.
404  * @name:	The control name.
405  * @type:	The control type.
406  * @min:	The control's minimum value.
407  * @max:	The control's maximum value.
408  * @step:	The control's step value for non-menu controls.
409  * @def:	The control's default value.
410  * @p_def:	The control's default value for compound controls.
412  * @elem_size:	The size in bytes of the control.
413  * @flags:	The control's flags.
414  * @menu_skip_mask: The control's skip mask for menu controls. This makes it
426  * @is_private: If set, then this control is private to its handler and it
452  * v4l2_ctrl_fill - Fill in the control fields based on the control ID.
454  * @id: ID of the control
455  * @name: pointer to be filled with a string with the name of the control
456  * @type: pointer for storing the type of the control
457  * @min: pointer for storing the minimum value for the control
458  * @max: pointer for storing the maximum value for the control
459  * @step: pointer for storing the control step
460  * @def: pointer for storing the default value for the control
461  * @flags: pointer for storing the flags to be used on the control
474  *    control handling only. Once all drivers are converted to use the new
475  *    control framework this function will no longer be exported.
482  * v4l2_ctrl_handler_init_class() - Initialize the control handler.
483  * @hdl:	The control handler.
488  *		are allocated) or the control lookup becomes slower (not enough
512  * @hdl:	The control handler.
517  *		are allocated) or the control lookup becomes slower (not enough
525  * Use this helper function to initialize a control handler.
545  * the control list.
546  * @hdl:	The control handler.
554  * associated with the control.
555  * @ctrl:	The control to lock.
564  * associated with the control.
565  * @ctrl:	The control to unlock.
574  * to the handler to initialize the hardware to the current control values. The
575  * caller is responsible for acquiring the control handler mutex on behalf of
577  * @hdl:	The control handler.
587  * to the handler to initialize the hardware to the current control values.
588  * @hdl:	The control handler.
598  * @hdl:	The control handler.
599  * @prefix:	The prefix to use when logging the control values. If the
613  *	control.
615  * @hdl:	The control handler.
616  * @cfg:	The control's configuration data.
617  * @priv:	The control's driver-specific private data.
628  *	control.
630  * @hdl:	The control handler.
631  * @ops:	The control ops.
632  * @id:		The control ID.
633  * @min:	The control's minimum value.
634  * @max:	The control's maximum value.
635  * @step:	The control's step value
636  * @def:	The control's default value.
638  * If the &v4l2_ctrl struct could not be allocated, or the control
642  * If @id refers to a menu control, then this function will return NULL.
653  *	menu control.
655  * @hdl:	The control handler.
656  * @ops:	The control ops.
657  * @id:		The control ID.
658  * @max:	The control's maximum value.
659  * @mask:	The control's skip mask for menu controls. This makes it
665  * @def:	The control's default value.
670  * If @id refers to a non-menu control, then this function will return NULL.
677  * v4l2_ctrl_new_std_menu_items() - Create a new standard V4L2 menu control
680  * @hdl:	The control handler.
681  * @ops:	The control ops.
682  * @id:	The control ID.
683  * @max:	The control's maximum value.
684  * @mask:	The control's skip mask for menu controls. This makes it
690  * @def:	The control's default value.
694  * menu of this control.
705  *      compound control.
707  * @hdl:       The control handler.
708  * @ops:       The control ops.
709  * @id:        The control ID.
710  * @p_def:     The control's default value.
715  * compound control should be all zeroes.
724  * v4l2_ctrl_new_int_menu() - Create a new standard V4L2 integer menu control.
726  * @hdl:	The control handler.
727  * @ops:	The control ops.
728  * @id:	The control ID.
729  * @max:	The control's maximum value.
730  * @def:	The control's default value.
731  * @qmenu_int:	The control's menu entries.
736  * If @id refers to a non-integer-menu control, then this function will
746  *	used when adding a control handler.
757  * @hdl:	The control handler.
758  * @add:	The control handler whose controls you want to add to
759  *		the @hdl control handler.
778  * @ctrl:	The control that is filtered.
793  * @controls:	The cluster control array of size @ncontrols.
803  * @controls:	The cluster control array of size @ncontrols. The first control
804  *		must be the 'auto' control (e.g. autogain, autoexposure, etc.)
805  * @manual_val: The value for the first control in the cluster that equals the
807  * @set_volatile: If true, then all controls except the first auto control will
810  * Use for control groups where one control selects some automatic feature and
817  * When the autofoo control is set to automatic, then any manual controls
818  * are set to inactive and any reads will call g_volatile_ctrl (if the control
821  * When the autofoo control is set to manual, then any manual controls will
826  * on the autofoo control and %V4L2_CTRL_FLAG_INACTIVE on the foo control(s)
835  * v4l2_ctrl_find() - Find a control with the given ID.
837  * @hdl:	The control handler.
838  * @id:	The control ID to find.
846  * v4l2_ctrl_activate() - Make the control active or inactive.
847  * @ctrl:	The control to (de)activate.
848  * @active:	True if the control should become active.
855  * This function assumes that the control handler is locked.
862  * @ctrl:	The control to (de)activate.
863  * @grabbed:	True if the control should become grabbed.
871  * This function assumes that the control handler is locked by the caller.
876  * v4l2_ctrl_grab() - Mark the control as grabbed or not grabbed.
878  * @ctrl:	The control to (de)activate.
879  * @grabbed:	True if the control should become grabbed.
887  * This function assumes that the control handler is not locked and will
903  * @ctrl:	The control to update.
904  * @min:	The control's minimum value.
905  * @max:	The control's maximum value.
906  * @step:	The control's step value
907  * @def:	The control's default value.
909  * Update the range of a control on the fly. This works for control types
914  * control type.
916  * The caller is responsible for acquiring the control handler mutex on behalf
923  * v4l2_ctrl_modify_range() - Update the range of a control.
925  * @ctrl:	The control to update.
926  * @min:	The control's minimum value.
927  * @max:	The control's maximum value.
928  * @step:	The control's step value
929  * @def:	The control's default value.
931  * Update the range of a control on the fly. This works for control types
936  * control type.
938  * This function assumes that the control handler is not locked and will
954  * v4l2_ctrl_notify() - Function to set a notify callback for a control.
956  * @ctrl:	The control.
960  * This function sets a callback function for the control. If @ctrl is NULL,
971  * v4l2_ctrl_get_name() - Get the name of the control
973  * @id:		The control ID.
975  * This function returns the name of the given control ID or NULL if it isn't
976  * a known control.
981  * v4l2_ctrl_get_menu() - Get the menu string array of the control
983  * @id:		The control ID.
986  * given control ID or NULL if it isn't a known menu control.
991  * v4l2_ctrl_get_int_menu() - Get the integer menu array of the control
993  * @id:		The control ID.
996  * This function returns the integer array of the given control ID or NULL if it
997  * if it isn't a known integer menu control.
1002  * v4l2_ctrl_g_ctrl() - Helper function to get the control's value from
1005  * @ctrl:	The control.
1007  * This returns the control's value safely by going through the control
1008  * framework. This function will lock the control's handler, so it cannot be
1018  * @ctrl:	The control.
1021  * This sets the control's new value safely by going through the control
1022  * framework. This function assumes the control's handler is already locked,
1030  * v4l2_ctrl_s_ctrl() - Helper function to set the control's value from
1032  * @ctrl:	The control.
1035  * This sets the control's new value safely by going through the control
1036  * framework. This function will lock the control's handler, so it cannot be
1053  * v4l2_ctrl_g_ctrl_int64() - Helper function to get a 64-bit control's value
1056  * @ctrl:	The control.
1058  * This returns the control's value safely by going through the control
1059  * framework. This function will lock the control's handler, so it cannot be
1069  * @ctrl:	The control.
1072  * This sets the control's new value safely by going through the control
1073  * framework. This function assumes the control's handler is already locked,
1081  * v4l2_ctrl_s_ctrl_int64() - Helper function to set a 64-bit control's value
1084  * @ctrl:	The control.
1087  * This sets the control's new value safely by going through the control
1088  * framework. This function will lock the control's handler, so it cannot be
1107  * @ctrl:	The control.
1110  * This sets the control's new string safely by going through the control
1111  * framework. This function assumes the control's handler is already locked,
1119  * v4l2_ctrl_s_ctrl_string() - Helper function to set a control's string value
1122  * @ctrl:	The control.
1125  * This sets the control's new string safely by going through the control
1126  * framework. This function will lock the control's handler, so it cannot be
1143  * __v4l2_ctrl_s_ctrl_compound() - Unlocked variant to set a compound control
1145  * @ctrl: The control.
1149  * This sets the control's new compound payload safely by going through the
1150  * control framework. This function assumes the control's handler is already
1159  * v4l2_ctrl_s_ctrl_compound() - Helper function to set a compound control
1162  * @ctrl: The control.
1166  * This sets the control's new compound payload safely by going through the
1167  * control framework. This function will lock the control's handler, so it
1191 /* Internal helper functions that deal with control events. */
1236  * control events.
1243  *	That just polls for control events.
1251  * v4l2_ctrl_request_setup - helper function to apply control values in a request
1254  * @parent: The parent control handler ('priv' in media_request_object_find())
1256  * This is a helper function to call the control handler's s_ctrl callback with
1257  * the control values contained in the request. Do note that this approach of
1258  * applying control values in a request is only applicable to memory-to-memory
1265  * v4l2_ctrl_request_complete - Complete a control handler request object
1268  * @parent: The parent control handler ('priv' in media_request_object_find())
1270  * This function is to be called on each control handler that may have had a
1271  * request object associated with it, i.e. control handlers of a driver that
1274  * The function first obtains the values of any volatile controls in the control
1282  * v4l2_ctrl_request_hdl_find - Find the control handler in the request
1285  * @parent: The parent control handler ('priv' in media_request_object_find())
1287  * This function finds the control handler in the request. It may return
1303  * v4l2_ctrl_request_hdl_put - Put the control handler
1305  * @hdl: Put this control handler
1307  * This function released the control handler previously obtained from'
1317  * v4l2_ctrl_request_ctrl_find() - Find a control with the given ID.
1319  * @hdl: The control handler from the request.
1320  * @id: The ID of the control to find.
1322  * This function returns a pointer to the control if this control is
1439  *	that just subscribes control events.
1449  * v4l2_ctrl_subdev_log_status - Log all controls owned by subdev's control
1472  * Controls already registered by the caller with the @hdl control handler are