include/media/v4l2-ctrls.h

1 /* SPDX-License-Identifier: GPL-2.0-or-later */
14 #include <media/media-request.h>
29  * union v4l2_ctrl_ptr - A pointer to a control value.
30  * @p_s32:			Pointer to a 32-bit signed value.
31  * @p_s64:			Pointer to a 64-bit signed value.
32  * @p_u8:			Pointer to a 8-bit unsigned value.
33  * @p_u16:			Pointer to a 16-bit unsigned value.
34  * @p_u32:			Pointer to a 32-bit unsigned value.
97  * v4l2_ctrl_ptr_create() - Helper function to return a v4l2_ctrl_ptr from a
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
119  *		ctrl->handler->lock is held when these ops are called, so no
129  * struct v4l2_ctrl_type_ops - The control type operations that the driver
132  * @equal: return true if all ctrl->elems array elements are equal.
133  * @init: initialize the value for array elements from from_idx to ctrl->elems.
135  * @validate: validate the value for ctrl->new_elems array elements.
148  * typedef v4l2_ctrl_notify_fnc - typedef for a notify argument with a function
149  *	that should be called when a control value has changed.
152  * @priv: control private data
160  * struct v4l2_ctrl - The control structure.
163  * @ev_subs:	The list of control event subscriptions.
164  * @handler:	The handler that owns the control.
167  * @done:	Internal flag: set for each processed control.
168  * @is_new:	Set when the user specified a new value for this control. It
173  * @is_private: If set, then this control is private to its handler and it
176  * @is_auto:   If set, then this control selects whether the other cluster
180  * @is_int:    If set, then this control has a simple integer value (i.e. it
181  *		uses ctrl->val).
182  * @is_string: If set, then this control has type %V4L2_CTRL_TYPE_STRING.
183  * @is_ptr:	If set, then this control is an array and/or has type >=
187  * @is_array: If set, then this control contains an N-dimensional array.
188  * @is_dyn_array: If set, then this control contains a dynamically sized 1-dimensional array.
193  *		control's value changes.
195  *		of the auto control that determines if that control is in
196  *		manual mode. So if the value of the auto control equals this
199  * @ops:	The control ops.
200  * @type_ops:	The control type ops.
201  * @id:	The control ID.
202  * @name:	The control name.
203  * @type:	The control type.
204  * @minimum:	The control's minimum value.
205  * @maximum:	The control's maximum value.
206  * @default_value: The control's default value.
207  * @step:	The control's step value for non-menu controls.
208  * @elems:	The number of elements in the N-dimensional array.
209  * @elem_size:	The size in bytes of the control.
215  * @menu_skip_mask: The control's skip mask for menu controls. This makes it
222  *		empty strings ("") correspond to non-existing menu items (this
226  * @qmenu_int:	A 64-bit integer array for with integer menu items.
228  *		:math:`ceil(\frac{maximum - minimum}{step}) + 1`.
230  * @flags:	The control's flags.
231  * @priv:	The control's private pointer. For use by the driver. It is
232  *		untouched by the control framework. Note that this pointer is
233  *		not freed when the control is deleted. Should this be needed
242  * @cur.val:	The control's current value, if the @type is represented via
244  * @val:	The control's new s32 value.
245  * @p_def:	The control's default value represented via a union which
246  *		provides a standard way of accessing control types
248  * @p_cur:	The control's current value represented via a union which
249  *		provides a standard way of accessing control types
251  * @p_new:	The control's new value represented via a union which provides
252  *		a standard way of accessing control types
312  * struct v4l2_ctrl_ref - The control reference.
315  * @next:	Single-link list node for the hash.
316  * @ctrl:	The actual control information.
318  *		``prepare_ext_ctrls`` function at ``v4l2-ctrl.c``.
321  * @req_done:	Internal flag: if the control handler containing this control
323  *		the control has been applied. This prevents applying controls
325  *		control of a cluster is applied, they all are).
326  * @p_req_valid: If set, then p_req contains the control value for the request.
329  *		result in ENOMEM. Only valid if ctrl->is_array is true.
331  *		array. Only valid if @p_req_valid and ctrl->is_array are
334  *		ctrl->elems, except for dynamic arrays. In that case it is in
337  * @p_req:	If the control handler containing this control reference
339  *		value of the control that must be applied when the request
340  *		is executed, or to the value of the control at the time
342  *		then this control was never set for this request and the
343  *		control will not be updated when this request is applied.
345  * Each control handler has a list of these refs. The list_head is used to
346  * keep a sorted-by-control-ID list of all controls, while the next pointer
347  * is used to link the control in the hash's bucket.
364  * struct v4l2_ctrl_handler - The control handler keeps track of all the
369  * @lock:	Lock to control access to this handler and its controls.
372  * @ctrl_refs:	The list of control references.
373  * @cached:	The last found control reference. It is common that the same
374  *		control is needed multiple times, so this is a simple
376  * @buckets:	Buckets for the hashing. Allows for quick control lookup.
377  * @notify:	A notify callback that is called whenever the control changes
383  * @error:	The error code of the first failed control addition.
385  * @requests:	List to keep track of open control handler request objects.
386  *		For the parent control handler (@req_obj.ops == NULL) this
387  *		is the list header. When the parent control handler is
414  * struct v4l2_ctrl_config - Control configuration structure.
416  * @ops:	The control ops.
417  * @type_ops:	The control type ops. Only needed for compound controls.
418  * @id:	The control ID.
419  * @name:	The control name.
420  * @type:	The control type.
421  * @min:	The control's minimum value.
422  * @max:	The control's maximum value.
423  * @step:	The control's step value for non-menu controls.
424  * @def:	The control's default value.
425  * @p_def:	The control's default value for compound controls.
427  * @elem_size:	The size in bytes of the control.
428  * @flags:	The control's flags.
429  * @menu_skip_mask: The control's skip mask for menu controls. This makes it
436  *		empty strings ("") correspond to non-existing menu items (this
441  * @is_private: If set, then this control is private to its handler and it
465  * v4l2_ctrl_fill - Fill in the control fields based on the control ID.
467  * @id: ID of the control
468  * @name: pointer to be filled with a string with the name of the control
469  * @type: pointer for storing the type of the control
470  * @min: pointer for storing the minimum value for the control
471  * @max: pointer for storing the maximum value for the control
472  * @step: pointer for storing the control step
473  * @def: pointer for storing the default value for the control
474  * @flags: pointer for storing the flags to be used on the control
477  * For non-standard controls it will only fill in the given arguments
487  *    control handling only. Once all drivers are converted to use the new
488  *    control framework this function will no longer be exported.
495  * v4l2_ctrl_handler_init_class() - Initialize the control handler.
496  * @hdl:	The control handler.
501  *		are allocated) or the control lookup becomes slower (not enough
513  * error will also be stored in @hdl->error.
522  * v4l2_ctrl_handler_init - helper function to create a static struct
525  * @hdl:	The control handler.
530  *		are allocated) or the control lookup becomes slower (not enough
538  * Use this helper function to initialize a control handler.
548 					"(" #hdl ")->_lock");		\
557  * v4l2_ctrl_handler_free() - Free all controls owned by the handler and free
558  * the control list.
559  * @hdl:	The control handler.
566  * v4l2_ctrl_lock() - Helper function to lock the handler
567  * associated with the control.
568  * @ctrl:	The control to lock.
572 	mutex_lock(ctrl->handler->lock);  in v4l2_ctrl_lock()
576  * v4l2_ctrl_unlock() - Helper function to unlock the handler
577  * associated with the control.
578  * @ctrl:	The control to unlock.
582 	mutex_unlock(ctrl->handler->lock);  in v4l2_ctrl_unlock()
586  * __v4l2_ctrl_handler_setup() - Call the s_ctrl op for all controls belonging
587  * to the handler to initialize the hardware to the current control values. The
588  * caller is responsible for acquiring the control handler mutex on behalf of
590  * @hdl:	The control handler.
592  * Button controls will be skipped, as are read-only controls.
599  * v4l2_ctrl_handler_setup() - Call the s_ctrl op for all controls belonging
600  * to the handler to initialize the hardware to the current control values.
601  * @hdl:	The control handler.
603  * Button controls will be skipped, as are read-only controls.
610  * v4l2_ctrl_handler_log_status() - Log all controls owned by the handler.
611  * @hdl:	The control handler.
612  * @prefix:	The prefix to use when logging the control values. If the
625  * v4l2_ctrl_new_custom() - Allocate and initialize a new custom V4L2
626  *	control.
628  * @hdl:	The control handler.
629  * @cfg:	The control's configuration data.
630  * @priv:	The control's driver-specific private data.
633  * and @hdl->error is set to the error code (if it wasn't set already).
640  * v4l2_ctrl_new_std() - Allocate and initialize a new standard V4L2 non-menu
641  *	control.
643  * @hdl:	The control handler.
644  * @ops:	The control ops.
645  * @id:		The control ID.
646  * @min:	The control's minimum value.
647  * @max:	The control's maximum value.
648  * @step:	The control's step value
649  * @def:	The control's default value.
651  * If the &v4l2_ctrl struct could not be allocated, or the control
652  * ID is not known, then NULL is returned and @hdl->error is set to the
655  * If @id refers to a menu control, then this function will return NULL.
665  * v4l2_ctrl_new_std_menu() - Allocate and initialize a new standard V4L2
666  *	menu control.
668  * @hdl:	The control handler.
669  * @ops:	The control ops.
670  * @id:		The control ID.
671  * @max:	The control's maximum value.
672  * @mask:	The control's skip mask for menu controls. This makes it
678  * @def:	The control's default value.
683  * If @id refers to a non-menu control, then this function will return NULL.
690  * v4l2_ctrl_new_std_menu_items() - Create a new standard V4L2 menu control
693  * @hdl:	The control handler.
694  * @ops:	The control ops.
695  * @id:	The control ID.
696  * @max:	The control's maximum value.
697  * @mask:	The control's skip mask for menu controls. This makes it
703  * @def:	The control's default value.
707  * menu of this control.
717  * v4l2_ctrl_new_std_compound() - Allocate and initialize a new standard V4L2
718  *      compound control.
720  * @hdl:       The control handler.
721  * @ops:       The control ops.
722  * @id:        The control ID.
723  * @p_def:     The control's default value.
728  * compound control should be all zeroes.
737  * v4l2_ctrl_new_int_menu() - Create a new standard V4L2 integer menu control.
739  * @hdl:	The control handler.
740  * @ops:	The control ops.
741  * @id:	The control ID.
742  * @max:	The control's maximum value.
743  * @def:	The control's default value.
744  * @qmenu_int:	The control's menu entries.
749  * If @id refers to a non-integer-menu control, then this function will
758  * typedef v4l2_ctrl_filter - Typedef to define the filter function to be
759  *	used when adding a control handler.
767  * v4l2_ctrl_add_handler() - Add all controls from handler @add to
770  * @hdl:	The control handler.
771  * @add:	The control handler whose controls you want to add to
772  *		the @hdl control handler.
780  * In case of an error @hdl->error will be set to the error code (if it
789  * v4l2_ctrl_radio_filter() - Standard filter for radio controls.
791  * @ctrl:	The control that is filtered.
802  * v4l2_ctrl_cluster() - Mark all controls in the cluster as belonging
806  * @controls:	The cluster control array of size @ncontrols.
812  * v4l2_ctrl_auto_cluster() - Mark all controls in the cluster as belonging
813  *	to that cluster and set it up for autofoo/foo-type handling.
816  * @controls:	The cluster control array of size @ncontrols. The first control
817  *		must be the 'auto' control (e.g. autogain, autoexposure, etc.)
818  * @manual_val: The value for the first control in the cluster that equals the
820  * @set_volatile: If true, then all controls except the first auto control will
823  * Use for control groups where one control selects some automatic feature and
825  * off (manual mode). Typical examples: autogain vs gain, auto-whitebalance vs
830  * When the autofoo control is set to automatic, then any manual controls
831  * are set to inactive and any reads will call g_volatile_ctrl (if the control
834  * When the autofoo control is set to manual, then any manual controls will
839  * on the autofoo control and %V4L2_CTRL_FLAG_INACTIVE on the foo control(s)
848  * v4l2_ctrl_find() - Find a control with the given ID.
850  * @hdl:	The control handler.
851  * @id:	The control ID to find.
859  * v4l2_ctrl_activate() - Make the control active or inactive.
860  * @ctrl:	The control to (de)activate.
861  * @active:	True if the control should become active.
868  * This function assumes that the control handler is locked.
873  * __v4l2_ctrl_grab() - Unlocked variant of v4l2_ctrl_grab.
875  * @ctrl:	The control to (de)activate.
876  * @grabbed:	True if the control should become grabbed.
884  * This function assumes that the control handler is locked by the caller.
889  * v4l2_ctrl_grab() - Mark the control as grabbed or not grabbed.
891  * @ctrl:	The control to (de)activate.
892  * @grabbed:	True if the control should become grabbed.
900  * This function assumes that the control handler is not locked and will
914  *__v4l2_ctrl_modify_range() - Unlocked variant of v4l2_ctrl_modify_range()
916  * @ctrl:	The control to update.
917  * @min:	The control's minimum value.
918  * @max:	The control's maximum value.
919  * @step:	The control's step value
920  * @def:	The control's default value.
922  * Update the range of a control on the fly. This works for control types
927  * control type.
929  * The caller is responsible for acquiring the control handler mutex on behalf
936  * v4l2_ctrl_modify_range() - Update the range of a control.
938  * @ctrl:	The control to update.
939  * @min:	The control's minimum value.
940  * @max:	The control's maximum value.
941  * @step:	The control's step value
942  * @def:	The control's default value.
944  * Update the range of a control on the fly. This works for control types
949  * control type.
951  * This function assumes that the control handler is not locked and will
967  *__v4l2_ctrl_modify_dimensions() - Unlocked variant of v4l2_ctrl_modify_dimensions()
969  * @ctrl:	The control to update.
970  * @dims:	The control's new dimensions.
972  * Update the dimensions of an array control on the fly. The elements of the
976  * An error is returned if @dims is invalid for this control.
978  * The caller is responsible for acquiring the control handler mutex on behalf
981  * Note: calling this function when the same control is used in pending requests
982  * is untested. It should work (a request with the wrong size of the control
983  * will drop that control silently), but it will be very confusing.
989  * v4l2_ctrl_modify_dimensions() - Update the dimensions of an array control.
991  * @ctrl:	The control to update.
992  * @dims:	The control's new dimensions.
994  * Update the dimensions of an array control on the fly. The elements of the
998  * An error is returned if @dims is invalid for this control type.
1000  * This function assumes that the control handler is not locked and will
1003  * Note: calling this function when the same control is used in pending requests
1004  * is untested. It should work (a request with the wrong size of the control
1005  * will drop that control silently), but it will be very confusing.
1020  * v4l2_ctrl_notify() - Function to set a notify callback for a control.
1022  * @ctrl:	The control.
1026  * This function sets a callback function for the control. If @ctrl is NULL,
1037  * v4l2_ctrl_get_name() - Get the name of the control
1039  * @id:		The control ID.
1041  * This function returns the name of the given control ID or NULL if it isn't
1042  * a known control.
1047  * v4l2_ctrl_get_menu() - Get the menu string array of the control
1049  * @id:		The control ID.
1051  * This function returns the NULL-terminated menu string array name of the
1052  * given control ID or NULL if it isn't a known menu control.
1057  * v4l2_ctrl_get_int_menu() - Get the integer menu array of the control
1059  * @id:		The control ID.
1062  * This function returns the integer array of the given control ID or NULL if it
1063  * if it isn't a known integer menu control.
1068  * v4l2_ctrl_g_ctrl() - Helper function to get the control's value from
1071  * @ctrl:	The control.
1073  * This returns the control's value safely by going through the control
1074  * framework. This function will lock the control's handler, so it cannot be
1082  * __v4l2_ctrl_s_ctrl() - Unlocked variant of v4l2_ctrl_s_ctrl().
1084  * @ctrl:	The control.
1087  * This sets the control's new value safely by going through the control
1088  * framework. This function assumes the control's handler is already locked,
1096  * v4l2_ctrl_s_ctrl() - Helper function to set the control's value from
1098  * @ctrl:	The control.
1101  * This sets the control's new value safely by going through the control
1102  * framework. This function will lock the control's handler, so it cannot be
1119  * v4l2_ctrl_g_ctrl_int64() - Helper function to get a 64-bit control's value
1122  * @ctrl:	The control.
1124  * This returns the control's value safely by going through the control
1125  * framework. This function will lock the control's handler, so it cannot be
1128  * This function is for 64-bit integer type controls only.
1133  * __v4l2_ctrl_s_ctrl_int64() - Unlocked variant of v4l2_ctrl_s_ctrl_int64().
1135  * @ctrl:	The control.
1138  * This sets the control's new value safely by going through the control
1139  * framework. This function assumes the control's handler is already locked,
1142  * This function is for 64-bit integer type controls only.
1147  * v4l2_ctrl_s_ctrl_int64() - Helper function to set a 64-bit control's value
1150  * @ctrl:	The control.
1153  * This sets the control's new value safely by going through the control
1154  * framework. This function will lock the control's handler, so it cannot be
1157  * This function is for 64-bit integer type controls only.
1171  * __v4l2_ctrl_s_ctrl_string() - Unlocked variant of v4l2_ctrl_s_ctrl_string().
1173  * @ctrl:	The control.
1176  * This sets the control's new string safely by going through the control
1177  * framework. This function assumes the control's handler is already locked,
1185  * v4l2_ctrl_s_ctrl_string() - Helper function to set a control's string value
1188  * @ctrl:	The control.
1191  * This sets the control's new string safely by going through the control
1192  * framework. This function will lock the control's handler, so it cannot be
1209  * __v4l2_ctrl_s_ctrl_compound() - Unlocked variant to set a compound control
1211  * @ctrl: The control.
1215  * This sets the control's new compound payload safely by going through the
1216  * control framework. This function assumes the control's handler is already
1225  * v4l2_ctrl_s_ctrl_compound() - Helper function to set a compound control
1228  * @ctrl: The control.
1232  * This sets the control's new compound payload safely by going through the
1233  * control framework. This function will lock the control's handler, so it
1257 /* Internal helper functions that deal with control events. */
1261  * v4l2_ctrl_replace - Function to be used as a callback to
1272  * v4l2_ctrl_merge - Function to be used as a callback to
1283  * v4l2_ctrl_log_status - helper function to implement %VIDIOC_LOG_STATUS ioctl
1295  * v4l2_ctrl_subscribe_event - Subscribes to an event
1302  * control events.
1308  * v4l2_ctrl_poll - function to be used as a callback to the poll()
1309  *	That just polls for control events.
1317  * v4l2_ctrl_request_setup - helper function to apply control values in a request
1320  * @parent: The parent control handler ('priv' in media_request_object_find())
1322  * This is a helper function to call the control handler's s_ctrl callback with
1323  * the control values contained in the request. Do note that this approach of
1324  * applying control values in a request is only applicable to memory-to-memory
1331  * v4l2_ctrl_request_complete - Complete a control handler request object
1334  * @parent: The parent control handler ('priv' in media_request_object_find())
1336  * This function is to be called on each control handler that may have had a
1337  * request object associated with it, i.e. control handlers of a driver that
1340  * The function first obtains the values of any volatile controls in the control
1348  * v4l2_ctrl_request_hdl_find - Find the control handler in the request
1351  * @parent: The parent control handler ('priv' in media_request_object_find())
1353  * This function finds the control handler in the request. It may return
1369  * v4l2_ctrl_request_hdl_put - Put the control handler
1371  * @hdl: Put this control handler
1373  * This function released the control handler previously obtained from'
1379 		media_request_object_put(&hdl->req_obj);  in v4l2_ctrl_request_hdl_put()
1383  * v4l2_ctrl_request_hdl_ctrl_find() - Find a control with the given ID.
1385  * @hdl: The control handler from the request.
1386  * @id: The ID of the control to find.
1388  * This function returns a pointer to the control if this control is
1397  * v4l2_queryctrl - Helper function to implement
1403  * If hdl == NULL then they will all return -EINVAL.
1408  * v4l2_query_ext_ctrl - Helper function to implement
1414  * If hdl == NULL then they will all return -EINVAL.
1420  * v4l2_querymenu - Helper function to implement
1426  * If hdl == NULL then they will all return -EINVAL.
1431  * v4l2_g_ctrl - Helper function to implement
1437  * If hdl == NULL then they will all return -EINVAL.
1442  * v4l2_s_ctrl - Helper function to implement
1450  * If hdl == NULL then they will all return -EINVAL.
1456  * v4l2_g_ext_ctrls - Helper function to implement
1464  * If hdl == NULL then they will all return -EINVAL.
1470  * v4l2_try_ext_ctrls - Helper function to implement
1478  * If hdl == NULL then they will all return -EINVAL.
1486  * v4l2_s_ext_ctrls - Helper function to implement
1495  * If hdl == NULL then they will all return -EINVAL.
1503  * v4l2_ctrl_subdev_subscribe_event - Helper function to implement
1505  *	that just subscribes control events.
1515  * v4l2_ctrl_subdev_log_status - Log all controls owned by subdev's control
1523  * v4l2_ctrl_new_fwnode_properties() - Register controls for the device
1535  * - V4L2_CID_CAMERA_ORIENTATION
1536  * - V4L2_CID_CAMERA_SENSOR_ROTATION;
1538  * Controls already registered by the caller with the @hdl control handler are
1549  * v4l2_ctrl_type_op_equal - Default v4l2_ctrl_type_ops equal callback.
1552  * @ptr1: A v4l2 control value.
1553  * @ptr2: A v4l2 control value.
1561  * v4l2_ctrl_type_op_init - Default v4l2_ctrl_type_ops init callback.
1565  * @ptr: The v4l2 control value.
1573  * v4l2_ctrl_type_op_log - Default v4l2_ctrl_type_ops log callback.
1582  * v4l2_ctrl_type_op_validate - Default v4l2_ctrl_type_ops validate callback.
1585  * @ptr: The v4l2 control value.