include/media/v4l2-ctrls.h

1 /* SPDX-License-Identifier: GPL-2.0-or-later */
14 #include <media/media-request.h>
20 #include <media/mpeg2-ctrls.h>
21 #include <media/fwht-ctrls.h>
22 #include <media/h264-ctrls.h>
23 #include <media/vp8-ctrls.h>
24 #include <media/hevc-ctrls.h>
39  * union v4l2_ctrl_ptr - A pointer to a control value.
40  * @p_s32:			Pointer to a 32-bit signed value.
41  * @p_s64:			Pointer to a 64-bit signed value.
42  * @p_u8:			Pointer to a 8-bit unsigned value.
43  * @p_u16:			Pointer to a 16-bit unsigned value.
44  * @p_u32:			Pointer to a 32-bit unsigned value.
89  * v4l2_ctrl_ptr_create() - Helper function to return a v4l2_ctrl_ptr from a
101  * struct v4l2_ctrl_ops - The control operations that the driver has to provide.
104  *		for volatile (and usually read-only) controls such as a control
109  *		the usual min/max/step checks are not sufficient.
111  *		ctrl->handler->lock is held when these ops are called, so no
121  * struct v4l2_ctrl_type_ops - The control type operations that the driver
142  * typedef v4l2_ctrl_notify_fnc - typedef for a notify argument with a function
154  * struct v4l2_ctrl - The control structure.
175  *		uses ctrl->val).
181  * @is_array: If set, then this control contains an N-dimensional array.
199  * @step:	The control's step value for non-menu controls.
200  * @elems:	The number of elements in the N-dimensional array.
211  *		empty strings ("") correspond to non-existing menu items (this
215  * @qmenu_int:	A 64-bit integer array for with integer menu items.
217  *		:math:`ceil(\frac{maximum - minimum}{step}) + 1`.
292  * struct v4l2_ctrl_ref - The control reference.
295  * @next:	Single-link list node for the hash.
298  *		``prepare_ext_ctrls`` function at ``v4l2-ctrl.c``.
314  * keep a sorted-by-control-ID list of all controls, while the next pointer
329  * struct v4l2_ctrl_handler - The control handler keeps track of all the
379  * struct v4l2_ctrl_config - Control configuration structure.
387  * @max:	The control's maximum value.
388  * @step:	The control's step value for non-menu controls.
401  *		empty strings ("") correspond to non-existing menu items (this
416 	s64 max;  member
430  * v4l2_ctrl_fill - Fill in the control fields based on the control ID.
436  * @max: pointer for storing the maximum value for the control
442  * For non-standard controls it will only fill in the given arguments
446  * The contents of @min, @max, @step and @def may be modified depending on
456 		    s64 *min, s64 *max, u64 *step, s64 *def, u32 *flags);
460  * v4l2_ctrl_handler_init_class() - Initialize the control handler.
478  * error will also be stored in @hdl->error.
487  * v4l2_ctrl_handler_init - helper function to create a static struct
513 					"(" #hdl ")->_lock");		\
522  * v4l2_ctrl_handler_free() - Free all controls owned by the handler and free
531  * v4l2_ctrl_lock() - Helper function to lock the handler
537 	mutex_lock(ctrl->handler->lock);  in v4l2_ctrl_lock()
541  * v4l2_ctrl_unlock() - Helper function to unlock the handler
547 	mutex_unlock(ctrl->handler->lock);  in v4l2_ctrl_unlock()
551  * __v4l2_ctrl_handler_setup() - Call the s_ctrl op for all controls belonging
557  * Button controls will be skipped, as are read-only controls.
564  * v4l2_ctrl_handler_setup() - Call the s_ctrl op for all controls belonging
568  * Button controls will be skipped, as are read-only controls.
575  * v4l2_ctrl_handler_log_status() - Log all controls owned by the handler.
590  * v4l2_ctrl_new_custom() - Allocate and initialize a new custom V4L2
595  * @priv:	The control's driver-specific private data.
598  * and @hdl->error is set to the error code (if it wasn't set already).
605  * v4l2_ctrl_new_std() - Allocate and initialize a new standard V4L2 non-menu
612  * @max:	The control's maximum value.
617  * ID is not known, then NULL is returned and @hdl->error is set to the
626 				    u32 id, s64 min, s64 max, u64 step,
630  * v4l2_ctrl_new_std_menu() - Allocate and initialize a new standard V4L2
636  * @max:	The control's maximum value.
648  * If @id refers to a non-menu control, then this function will return NULL.
652 					 u32 id, u8 max, u64 mask, u8 def);
655  * v4l2_ctrl_new_std_menu_items() - Create a new standard V4L2 menu control
661  * @max:	The control's maximum value.
677 					       u32 id, u8 max,
682  * v4l2_ctrl_new_std_compound() - Allocate and initialize a new standard V4L2
702  * v4l2_ctrl_new_int_menu() - Create a new standard V4L2 integer menu control.
707  * @max:	The control's maximum value.
714  * If @id refers to a non-integer-menu control, then this function will
719 					 u32 id, u8 max, u8 def,
723  * typedef v4l2_ctrl_filter - Typedef to define the filter function to be
732  * v4l2_ctrl_add_handler() - Add all controls from handler @add to
745  * In case of an error @hdl->error will be set to the error code (if it
754  * v4l2_ctrl_radio_filter() - Standard filter for radio controls.
767  * v4l2_ctrl_cluster() - Mark all controls in the cluster as belonging
777  * v4l2_ctrl_auto_cluster() - Mark all controls in the cluster as belonging
778  *	to that cluster and set it up for autofoo/foo-type handling.
790  * off (manual mode). Typical examples: autogain vs gain, auto-whitebalance vs
813  * v4l2_ctrl_find() - Find a control with the given ID.
824  * v4l2_ctrl_activate() - Make the control active or inactive.
838  * __v4l2_ctrl_grab() - Unlocked variant of v4l2_ctrl_grab.
854  * v4l2_ctrl_grab() - Mark the control as grabbed or not grabbed.
879  *__v4l2_ctrl_modify_range() - Unlocked variant of v4l2_ctrl_modify_range()
883  * @max:	The control's maximum value.
898 			     s64 min, s64 max, u64 step, s64 def);
901  * v4l2_ctrl_modify_range() - Update the range of a control.
905  * @max:	The control's maximum value.
920 					 s64 min, s64 max, u64 step, s64 def)  in v4l2_ctrl_modify_range()  argument
925 	rval = __v4l2_ctrl_modify_range(ctrl, min, max, step, def);  in v4l2_ctrl_modify_range()
932  * v4l2_ctrl_notify() - Function to set a notify callback for a control.
949  * v4l2_ctrl_get_name() - Get the name of the control
959  * v4l2_ctrl_get_menu() - Get the menu string array of the control
963  * This function returns the NULL-terminated menu string array name of the
969  * v4l2_ctrl_get_int_menu() - Get the integer menu array of the control
980  * v4l2_ctrl_g_ctrl() - Helper function to get the control's value from
987  * used from within the &v4l2_ctrl_ops functions.
994  * __v4l2_ctrl_s_ctrl() - Unlocked variant of v4l2_ctrl_s_ctrl().
1001  * allowing it to be used from within the &v4l2_ctrl_ops functions.
1008  * v4l2_ctrl_s_ctrl() - Helper function to set the control's value from
1015  * used from within the &v4l2_ctrl_ops functions.
1031  * v4l2_ctrl_g_ctrl_int64() - Helper function to get a 64-bit control's value
1038  * used from within the &v4l2_ctrl_ops functions.
1040  * This function is for 64-bit integer type controls only.
1045  * __v4l2_ctrl_s_ctrl_int64() - Unlocked variant of v4l2_ctrl_s_ctrl_int64().
1052  * allowing it to be used from within the &v4l2_ctrl_ops functions.
1054  * This function is for 64-bit integer type controls only.
1059  * v4l2_ctrl_s_ctrl_int64() - Helper function to set a 64-bit control's value
1067  * used from within the &v4l2_ctrl_ops functions.
1069  * This function is for 64-bit integer type controls only.
1083  * __v4l2_ctrl_s_ctrl_string() - Unlocked variant of v4l2_ctrl_s_ctrl_string().
1090  * allowing it to be used from within the &v4l2_ctrl_ops functions.
1097  * v4l2_ctrl_s_ctrl_string() - Helper function to set a control's string value
1105  * used from within the &v4l2_ctrl_ops functions.
1121  * __v4l2_ctrl_s_ctrl_compound() - Unlocked variant to set a compound control
1129  * locked, allowing it to be used from within the &v4l2_ctrl_ops functions.
1137  * v4l2_ctrl_s_ctrl_compound() - Helper function to set a compound control
1146  * cannot be used from within the &v4l2_ctrl_ops functions.
1169 /* Internal helper functions that deal with control events. */
1173  * v4l2_ctrl_replace - Function to be used as a callback to
1184  * v4l2_ctrl_merge - Function to be used as a callback to
1195  * v4l2_ctrl_log_status - helper function to implement %VIDIOC_LOG_STATUS ioctl
1207  * v4l2_ctrl_subscribe_event - Subscribes to an event
1220  * v4l2_ctrl_poll - function to be used as a callback to the poll()
1229  * v4l2_ctrl_request_setup - helper function to apply control values in a request
1236  * applying control values in a request is only applicable to memory-to-memory
1243  * v4l2_ctrl_request_complete - Complete a control handler request object
1260  * v4l2_ctrl_request_hdl_find - Find the control handler in the request
1281  * v4l2_ctrl_request_hdl_put - Put the control handler
1291 		media_request_object_put(&hdl->req_obj);  in v4l2_ctrl_request_hdl_put()
1295  * v4l2_ctrl_request_ctrl_find() - Find a control with the given ID.
1309  * v4l2_queryctrl - Helper function to implement
1315  * If hdl == NULL then they will all return -EINVAL.
1320  * v4l2_query_ext_ctrl - Helper function to implement
1326  * If hdl == NULL then they will all return -EINVAL.
1332  * v4l2_querymenu - Helper function to implement
1338  * If hdl == NULL then they will all return -EINVAL.
1343  * v4l2_g_ctrl - Helper function to implement
1349  * If hdl == NULL then they will all return -EINVAL.
1354  * v4l2_s_ctrl - Helper function to implement
1362  * If hdl == NULL then they will all return -EINVAL.
1368  * v4l2_g_ext_ctrls - Helper function to implement
1376  * If hdl == NULL then they will all return -EINVAL.
1382  * v4l2_try_ext_ctrls - Helper function to implement
1390  * If hdl == NULL then they will all return -EINVAL.
1398  * v4l2_s_ext_ctrls - Helper function to implement
1407  * If hdl == NULL then they will all return -EINVAL.
1415  * v4l2_ctrl_subdev_subscribe_event - Helper function to implement
1427  * v4l2_ctrl_subdev_log_status - Log all controls owned by subdev's control
1435  * v4l2_ctrl_new_fwnode_properties() - Register controls for the device
1447  * - V4L2_CID_CAMERA_ORIENTATION
1448  * - V4L2_CID_CAMERA_SENSOR_ROTATION;