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.
35  * @p_char:			Pointer to a string.
36  * @p_mpeg2_sequence:		Pointer to a MPEG2 sequence structure.
37  * @p_mpeg2_picture:		Pointer to a MPEG2 picture structure.
38  * @p_mpeg2_quantisation:	Pointer to a MPEG2 quantisation data structure.
39  * @p_fwht_params:		Pointer to a FWHT stateless parameters structure.
40  * @p_h264_sps:			Pointer to a struct v4l2_ctrl_h264_sps.
41  * @p_h264_pps:			Pointer to a struct v4l2_ctrl_h264_pps.
42  * @p_h264_scaling_matrix:	Pointer to a struct v4l2_ctrl_h264_scaling_matrix.
43  * @p_h264_slice_params:	Pointer to a struct v4l2_ctrl_h264_slice_params.
44  * @p_h264_decode_params:	Pointer to a struct v4l2_ctrl_h264_decode_params.
45  * @p_h264_pred_weights:	Pointer to a struct v4l2_ctrl_h264_pred_weights.
46  * @p_vp8_frame:		Pointer to a VP8 frame params structure.
47  * @p_vp9_compressed_hdr_probs:	Pointer to a VP9 frame compressed header probs structure.
48  * @p_vp9_frame:		Pointer to a VP9 frame params structure.
59  * @p:				Pointer to a compound value.
60  * @p_const:			Pointer to a constant compound 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
119  *		ctrl->handler->lock is held when these ops are called, so no
123 	int (*g_volatile_ctrl)(struct v4l2_ctrl *ctrl);
124 	int (*try_ctrl)(struct v4l2_ctrl *ctrl);
125 	int (*s_ctrl)(struct v4l2_ctrl *ctrl);
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.
136  *	Return 0 on success and a negative value otherwise.
139 	bool (*equal)(const struct v4l2_ctrl *ctrl,
141 	void (*init)(const struct v4l2_ctrl *ctrl, u32 from_idx,
143 	void (*log)(const struct v4l2_ctrl *ctrl);
144 	int (*validate)(const struct v4l2_ctrl *ctrl, union v4l2_ctrl_ptr ptr);
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.
151  * @ctrl: pointer to struct &v4l2_ctrl
157 typedef void (*v4l2_ctrl_notify_fnc)(struct v4l2_ctrl *ctrl, void *priv);
160  * struct v4l2_ctrl - The control structure.
168  * @is_new:	Set when the user specified a new value for this control. It
180  * @is_int:    If set, then this control has a simple integer value (i.e. it
181  *		uses ctrl->val).
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.
207  * @step:	The control's step value for non-menu controls.
208  * @elems:	The number of elements in the N-dimensional array.
220  *		then this will have to be extended to a u64 or a bit array.
221  * @qmenu:	A const char * array for all menu items. Array entries that are
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`.
234  *		then a new internal bitfield can be added to tell the framework
243  *		a u32 integer (see &enum v4l2_ctrl_type).
245  * @p_def:	The control's default value represented via a union which
246  *		provides a standard way of accessing control types
247  *		through a pointer (for compound controls only).
248  * @p_cur:	The control's current value represented via a union which
249  *		provides a standard way of accessing control types
250  *		through a pointer.
251  * @p_new:	The control's new value represented via a union which provides
252  *		a standard way of accessing control types
253  *		through a pointer.
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``.
319  * @from_other_dev: If true, then @ctrl was defined in another
322  *		reference is bound to a media request, then this is set when
324  *		from a cluster with multiple controls twice (when the first
325  *		control of a cluster is applied, they all are).
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
338  *		is bound to a media request, then this points to the
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
352 	struct v4l2_ctrl *ctrl;  member
364  * struct v4l2_ctrl_handler - The control handler keeps track of all the
374  *		control is needed multiple times, so this is a simple
377  * @notify:	A notify callback that is called whenever the control changes
393  * @req_obj:	The &struct media_request_object, used to link into a
394  *		&struct media_request. This request object has a refcount.
414  * struct v4l2_ctrl_config - Control configuration structure.
423  * @step:	The control's step value for non-menu controls.
434  *		then this will have to be extended to a bit array.
435  * @qmenu:	A const char * array for all menu items. Array entries that are
436  *		empty strings ("") correspond to non-existing menu items (this
439  * @qmenu_int:	A const s64 integer array for all menu items of the type
465  * v4l2_ctrl_fill - Fill in the control fields based on the control ID.
468  * @name: pointer to be filled with a string with the name of the control
477  * For non-standard controls it will only fill in the given arguments
495  * v4l2_ctrl_handler_init_class() - Initialize the control handler.
497  * @nr_of_controls_hint: A hint of how many controls this handler is
513  * error will also be stored in @hdl->error.
522  * v4l2_ctrl_handler_init - helper function to create a static struct
526  * @nr_of_controls_hint: A hint of how many controls this handler is
534  * This helper function creates a static struct &lock_class_key and
535  * calls v4l2_ctrl_handler_init_class(), providing a proper name for the lock
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
566  * v4l2_ctrl_lock() - Helper function to lock the handler
568  * @ctrl:	The control to lock.
570 static inline void v4l2_ctrl_lock(struct v4l2_ctrl *ctrl)  in v4l2_ctrl_lock()  argument
572 	mutex_lock(ctrl->handler->lock);  in v4l2_ctrl_lock()
576  * v4l2_ctrl_unlock() - Helper function to unlock the handler
578  * @ctrl:	The control to unlock.
580 static inline void v4l2_ctrl_unlock(struct v4l2_ctrl *ctrl)  in v4l2_ctrl_unlock()  argument
582 	mutex_unlock(ctrl->handler->lock);  in v4l2_ctrl_unlock()
586  * __v4l2_ctrl_handler_setup() - Call the s_ctrl op for all controls belonging
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
603  * Button controls will be skipped, as are read-only controls.
610  * v4l2_ctrl_handler_log_status() - Log all controls owned by the handler.
613  *		prefix does not end with a space, then ": " will be added
625  * v4l2_ctrl_new_custom() - Allocate and initialize a new custom V4L2
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
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
677  *		then this will have to be extended to a bit array.
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
702  *		then this will have to be extended to a bit array.
717  * v4l2_ctrl_new_std_compound() - Allocate and initialize a new standard V4L2
726  * to the @p_def field. Use v4l2_ctrl_ptr_create() to create @p_def from a
737  * v4l2_ctrl_new_int_menu() - Create a new standard V4L2 integer menu control.
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.
761  * @ctrl: pointer to struct &v4l2_ctrl.
764 typedef bool (*v4l2_ctrl_filter)(const struct v4l2_ctrl *ctrl);
767  * v4l2_ctrl_add_handler() - Add all controls from handler @add to
777  * Does nothing if either of the two handlers is a NULL pointer.
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.
799 bool v4l2_ctrl_radio_filter(const struct v4l2_ctrl *ctrl);
802  * v4l2_ctrl_cluster() - Mark all controls in the cluster as belonging
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.
825  * off (manual mode). Typical examples: autogain vs gain, auto-whitebalance vs
848  * v4l2_ctrl_find() - Find a control with the given ID.
859  * v4l2_ctrl_activate() - Make the control active or inactive.
860  * @ctrl:	The control to (de)activate.
864  * Does nothing if @ctrl == NULL.
870 void v4l2_ctrl_activate(struct v4l2_ctrl *ctrl, bool active);
873  * __v4l2_ctrl_grab() - Unlocked variant of v4l2_ctrl_grab.
875  * @ctrl:	The control to (de)activate.
879  * Does nothing if @ctrl == NULL.
886 void __v4l2_ctrl_grab(struct v4l2_ctrl *ctrl, bool grabbed);
889  * v4l2_ctrl_grab() - Mark the control as grabbed or not grabbed.
891  * @ctrl:	The control to (de)activate.
895  * Does nothing if @ctrl == NULL.
903 static inline void v4l2_ctrl_grab(struct v4l2_ctrl *ctrl, bool grabbed)  in v4l2_ctrl_grab()  argument
905 	if (!ctrl)  in v4l2_ctrl_grab()
908 	v4l2_ctrl_lock(ctrl);  in v4l2_ctrl_grab()
909 	__v4l2_ctrl_grab(ctrl, grabbed);  in v4l2_ctrl_grab()
910 	v4l2_ctrl_unlock(ctrl);  in v4l2_ctrl_grab()
914  *__v4l2_ctrl_modify_range() - Unlocked variant of v4l2_ctrl_modify_range()
916  * @ctrl:	The control to update.
922  * Update the range of a control on the fly. This works for control types
924  * @step value is interpreted as a menu_skip_mask.
932 int __v4l2_ctrl_modify_range(struct v4l2_ctrl *ctrl,
936  * v4l2_ctrl_modify_range() - Update the range of a control.
938  * @ctrl:	The control to update.
944  * Update the range of a control on the fly. This works for control types
946  * @step value is interpreted as a menu_skip_mask.
954 static inline int v4l2_ctrl_modify_range(struct v4l2_ctrl *ctrl,  in v4l2_ctrl_modify_range()  argument
959 	v4l2_ctrl_lock(ctrl);  in v4l2_ctrl_modify_range()
960 	rval = __v4l2_ctrl_modify_range(ctrl, min, max, step, def);  in v4l2_ctrl_modify_range()
961 	v4l2_ctrl_unlock(ctrl);  in v4l2_ctrl_modify_range()
967  *__v4l2_ctrl_modify_dimensions() - Unlocked variant of v4l2_ctrl_modify_dimensions()
969  * @ctrl:	The control to update.
982  * is untested. It should work (a request with the wrong size of the control
985 int __v4l2_ctrl_modify_dimensions(struct v4l2_ctrl *ctrl,
989  * v4l2_ctrl_modify_dimensions() - Update the dimensions of an array control.
991  * @ctrl:	The control to update.
1004  * is untested. It should work (a request with the wrong size of the control
1007 static inline int v4l2_ctrl_modify_dimensions(struct v4l2_ctrl *ctrl,  in v4l2_ctrl_modify_dimensions()  argument
1012 	v4l2_ctrl_lock(ctrl);  in v4l2_ctrl_modify_dimensions()
1013 	rval = __v4l2_ctrl_modify_dimensions(ctrl, dims);  in v4l2_ctrl_modify_dimensions()
1014 	v4l2_ctrl_unlock(ctrl);  in v4l2_ctrl_modify_dimensions()
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,
1030  * There can be only one notify. If another already exists, then a WARN_ON
1033 void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl, v4l2_ctrl_notify_fnc notify,
1037  * v4l2_ctrl_get_name() - Get the name of the control
1042  * a known control.
1047  * v4l2_ctrl_get_menu() - Get the menu string array of the control
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
1063  * if it isn't a known integer menu control.
1068  * v4l2_ctrl_g_ctrl() - Helper function to get the control's value from
1069  *	within a driver.
1071  * @ctrl:	The control.
1079 s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl);
1082  * __v4l2_ctrl_s_ctrl() - Unlocked variant of v4l2_ctrl_s_ctrl().
1084  * @ctrl:	The control.
1093 int __v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val);
1096  * v4l2_ctrl_s_ctrl() - Helper function to set the control's value from
1097  *	within a driver.
1098  * @ctrl:	The control.
1107 static inline int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val)  in v4l2_ctrl_s_ctrl()  argument
1111 	v4l2_ctrl_lock(ctrl);  in v4l2_ctrl_s_ctrl()
1112 	rval = __v4l2_ctrl_s_ctrl(ctrl, val);  in v4l2_ctrl_s_ctrl()
1113 	v4l2_ctrl_unlock(ctrl);  in v4l2_ctrl_s_ctrl()
1119  * v4l2_ctrl_g_ctrl_int64() - Helper function to get a 64-bit control's value
1120  *	from within a driver.
1122  * @ctrl:	The control.
1128  * This function is for 64-bit integer type controls only.
1130 s64 v4l2_ctrl_g_ctrl_int64(struct v4l2_ctrl *ctrl);
1133  * __v4l2_ctrl_s_ctrl_int64() - Unlocked variant of v4l2_ctrl_s_ctrl_int64().
1135  * @ctrl:	The control.
1142  * This function is for 64-bit integer type controls only.
1144 int __v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val);
1147  * v4l2_ctrl_s_ctrl_int64() - Helper function to set a 64-bit control's value
1148  *	from within a driver.
1150  * @ctrl:	The control.
1157  * This function is for 64-bit integer type controls only.
1159 static inline int v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val)  in v4l2_ctrl_s_ctrl_int64()  argument
1163 	v4l2_ctrl_lock(ctrl);  in v4l2_ctrl_s_ctrl_int64()
1164 	rval = __v4l2_ctrl_s_ctrl_int64(ctrl, val);  in v4l2_ctrl_s_ctrl_int64()
1165 	v4l2_ctrl_unlock(ctrl);  in v4l2_ctrl_s_ctrl_int64()
1171  * __v4l2_ctrl_s_ctrl_string() - Unlocked variant of v4l2_ctrl_s_ctrl_string().
1173  * @ctrl:	The control.
1182 int __v4l2_ctrl_s_ctrl_string(struct v4l2_ctrl *ctrl, const char *s);
1185  * v4l2_ctrl_s_ctrl_string() - Helper function to set a control's string value
1186  *	 from within a driver.
1188  * @ctrl:	The control.
1197 static inline int v4l2_ctrl_s_ctrl_string(struct v4l2_ctrl *ctrl, const char *s)  in v4l2_ctrl_s_ctrl_string()  argument
1201 	v4l2_ctrl_lock(ctrl);  in v4l2_ctrl_s_ctrl_string()
1202 	rval = __v4l2_ctrl_s_ctrl_string(ctrl, s);  in v4l2_ctrl_s_ctrl_string()
1203 	v4l2_ctrl_unlock(ctrl);  in v4l2_ctrl_s_ctrl_string()
1209  * __v4l2_ctrl_s_ctrl_compound() - Unlocked variant to set a compound control
1211  * @ctrl: The control.
1221 int __v4l2_ctrl_s_ctrl_compound(struct v4l2_ctrl *ctrl,
1225  * v4l2_ctrl_s_ctrl_compound() - Helper function to set a compound control
1226  *	from within a driver.
1228  * @ctrl: The control.
1238 static inline int v4l2_ctrl_s_ctrl_compound(struct v4l2_ctrl *ctrl,  in v4l2_ctrl_s_ctrl_compound()  argument
1244 	v4l2_ctrl_lock(ctrl);  in v4l2_ctrl_s_ctrl_compound()
1245 	rval = __v4l2_ctrl_s_ctrl_compound(ctrl, type, p);  in v4l2_ctrl_s_ctrl_compound()
1246 	v4l2_ctrl_unlock(ctrl);  in v4l2_ctrl_s_ctrl_compound()
1252 #define __v4l2_ctrl_s_ctrl_area(ctrl, area) \  argument
1253 	__v4l2_ctrl_s_ctrl_compound((ctrl), V4L2_CTRL_TYPE_AREA, (area))
1254 #define v4l2_ctrl_s_ctrl_area(ctrl, area) \  argument
1255 	v4l2_ctrl_s_ctrl_compound((ctrl), V4L2_CTRL_TYPE_AREA, (area))
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
1289  * Can be used as a vidioc_log_status function that just dumps all controls
1295  * v4l2_ctrl_subscribe_event - Subscribes to an event
1301  * Can be used as a vidioc_subscribe_event function that just subscribes
1308  * v4l2_ctrl_poll - function to be used as a callback to the poll()
1317  * v4l2_ctrl_request_setup - helper function to apply control values in a request
1322  * This is a helper function to call the control handler's s_ctrl callback with
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
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
1348  * v4l2_ctrl_request_hdl_find - Find the control handler in the request
1369  * v4l2_ctrl_request_hdl_put - Put the control handler
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.
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
1435  * @ctrl: pointer to &struct v4l2_control
1437  * If hdl == NULL then they will all return -EINVAL.
1439 int v4l2_g_ctrl(struct v4l2_ctrl_handler *hdl, struct v4l2_control *ctrl);
1442  * v4l2_s_ctrl - Helper function to implement
1448  * @ctrl: pointer to &struct v4l2_control
1450  * If hdl == NULL then they will all return -EINVAL.
1453 		struct v4l2_control *ctrl);
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
1504  *	as a &struct v4l2_subdev_core_ops subscribe_event function
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
1532  * a value.
1535  * - V4L2_CID_CAMERA_ORIENTATION
1536  * - V4L2_CID_CAMERA_SENSOR_ROTATION;
1542  * Return: 0 on success, a negative error code on failure.
1549  * v4l2_ctrl_type_op_equal - Default v4l2_ctrl_type_ops equal callback.
1551  * @ctrl: The v4l2_ctrl pointer.
1552  * @ptr1: A v4l2 control value.
1553  * @ptr2: A v4l2 control value.
1557 bool v4l2_ctrl_type_op_equal(const struct v4l2_ctrl *ctrl,
1561  * v4l2_ctrl_type_op_init - Default v4l2_ctrl_type_ops init callback.
1563  * @ctrl: The v4l2_ctrl pointer.
1569 void v4l2_ctrl_type_op_init(const struct v4l2_ctrl *ctrl, u32 from_idx,
1573  * v4l2_ctrl_type_op_log - Default v4l2_ctrl_type_ops log callback.
1575  * @ctrl: The v4l2_ctrl pointer.
1579 void v4l2_ctrl_type_op_log(const struct v4l2_ctrl *ctrl);
1582  * v4l2_ctrl_type_op_validate - Default v4l2_ctrl_type_ops validate callback.
1584  * @ctrl: The v4l2_ctrl pointer.
1587  * Return: 0 on success, a negative error code on failure.
1589 int v4l2_ctrl_type_op_validate(const struct v4l2_ctrl *ctrl, union v4l2_ctrl_ptr ptr);