1/* SPDX-License-Identifier: GPL-2.0-or-later */
   2/*
   3 *  V4L2 controls support header.
   4 *
   5 *  Copyright (C) 2010  Hans Verkuil <hverkuil@xs4all.nl>
   6 */
   7
   8#ifndef _V4L2_CTRLS_H
   9#define _V4L2_CTRLS_H
  10
  11#include <linux/list.h>
  12#include <linux/mutex.h>
  13#include <linux/videodev2.h>
  14#include <media/media-request.h>
  15
  16/*
  17 * Include the stateless codec compound control definitions.
  18 * This will move to the public headers once this API is fully stable.
  19 */
  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>
  25
  26/* forward references */
  27struct file;
  28struct poll_table_struct;
  29struct v4l2_ctrl;
  30struct v4l2_ctrl_handler;
  31struct v4l2_ctrl_helper;
  32struct v4l2_fh;
  33struct v4l2_fwnode_device_properties;
  34struct v4l2_subdev;
  35struct v4l2_subscribed_event;
  36struct video_device;
  37
  38/**
  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.
  45 * @p_char:			Pointer to a string.
  46 * @p_mpeg2_slice_params:	Pointer to a MPEG2 slice parameters structure.
  47 * @p_mpeg2_quantization:	Pointer to a MPEG2 quantization data structure.
 
  48 * @p_fwht_params:		Pointer to a FWHT stateless parameters structure.
  49 * @p_h264_sps:			Pointer to a struct v4l2_ctrl_h264_sps.
  50 * @p_h264_pps:			Pointer to a struct v4l2_ctrl_h264_pps.
  51 * @p_h264_scaling_matrix:	Pointer to a struct v4l2_ctrl_h264_scaling_matrix.
  52 * @p_h264_slice_params:	Pointer to a struct v4l2_ctrl_h264_slice_params.
  53 * @p_h264_decode_params:	Pointer to a struct v4l2_ctrl_h264_decode_params.
  54 * @p_vp8_frame_header:		Pointer to a VP8 frame header structure.
 
  55 * @p_hevc_sps:			Pointer to an HEVC sequence parameter set structure.
  56 * @p_hevc_pps:			Pointer to an HEVC picture parameter set structure.
  57 * @p_hevc_slice_params:	Pointer to an HEVC slice parameters structure.
 
 
  58 * @p_area:			Pointer to an area.
  59 * @p:				Pointer to a compound value.
  60 * @p_const:			Pointer to a constant compound value.
  61 */
  62union v4l2_ctrl_ptr {
  63	s32 *p_s32;
  64	s64 *p_s64;
  65	u8 *p_u8;
  66	u16 *p_u16;
  67	u32 *p_u32;
  68	char *p_char;
  69	struct v4l2_ctrl_mpeg2_slice_params *p_mpeg2_slice_params;
  70	struct v4l2_ctrl_mpeg2_quantization *p_mpeg2_quantization;
 
  71	struct v4l2_ctrl_fwht_params *p_fwht_params;
  72	struct v4l2_ctrl_h264_sps *p_h264_sps;
  73	struct v4l2_ctrl_h264_pps *p_h264_pps;
  74	struct v4l2_ctrl_h264_scaling_matrix *p_h264_scaling_matrix;
  75	struct v4l2_ctrl_h264_slice_params *p_h264_slice_params;
  76	struct v4l2_ctrl_h264_decode_params *p_h264_decode_params;
  77	struct v4l2_ctrl_vp8_frame_header *p_vp8_frame_header;
 
  78	struct v4l2_ctrl_hevc_sps *p_hevc_sps;
  79	struct v4l2_ctrl_hevc_pps *p_hevc_pps;
  80	struct v4l2_ctrl_hevc_slice_params *p_hevc_slice_params;
 
 
  81	struct v4l2_area *p_area;
  82	void *p;
  83	const void *p_const;
  84};
  85
  86/**
  87 * v4l2_ctrl_ptr_create() - Helper function to return a v4l2_ctrl_ptr from a
  88 * void pointer
  89 * @ptr:	The void pointer
  90 */
  91static inline union v4l2_ctrl_ptr v4l2_ctrl_ptr_create(void *ptr)
  92{
  93	union v4l2_ctrl_ptr p = { .p = ptr };
  94
  95	return p;
  96}
  97
  98/**
  99 * struct v4l2_ctrl_ops - The control operations that the driver has to provide.
 100 *
 101 * @g_volatile_ctrl: Get a new value for this control. Generally only relevant
 102 *		for volatile (and usually read-only) controls such as a control
 103 *		that returns the current signal strength which changes
 104 *		continuously.
 105 *		If not set, then the currently cached value will be returned.
 106 * @try_ctrl:	Test whether the control's value is valid. Only relevant when
 107 *		the usual min/max/step checks are not sufficient.
 108 * @s_ctrl:	Actually set the new control value. s_ctrl is compulsory. The
 109 *		ctrl->handler->lock is held when these ops are called, so no
 110 *		one else can access controls owned by that handler.
 111 */
 112struct v4l2_ctrl_ops {
 113	int (*g_volatile_ctrl)(struct v4l2_ctrl *ctrl);
 114	int (*try_ctrl)(struct v4l2_ctrl *ctrl);
 115	int (*s_ctrl)(struct v4l2_ctrl *ctrl);
 116};
 117
 118/**
 119 * struct v4l2_ctrl_type_ops - The control type operations that the driver
 120 *			       has to provide.
 121 *
 122 * @equal: return true if both values are equal.
 123 * @init: initialize the value.
 124 * @log: log the value.
 125 * @validate: validate the value. Return 0 on success and a negative value
 126 *	otherwise.
 127 */
 128struct v4l2_ctrl_type_ops {
 129	bool (*equal)(const struct v4l2_ctrl *ctrl, u32 idx,
 130		      union v4l2_ctrl_ptr ptr1,
 131		      union v4l2_ctrl_ptr ptr2);
 132	void (*init)(const struct v4l2_ctrl *ctrl, u32 idx,
 133		     union v4l2_ctrl_ptr ptr);
 134	void (*log)(const struct v4l2_ctrl *ctrl);
 135	int (*validate)(const struct v4l2_ctrl *ctrl, u32 idx,
 136			union v4l2_ctrl_ptr ptr);
 137};
 138
 139/**
 140 * typedef v4l2_ctrl_notify_fnc - typedef for a notify argument with a function
 141 *	that should be called when a control value has changed.
 142 *
 143 * @ctrl: pointer to struct &v4l2_ctrl
 144 * @priv: control private data
 145 *
 146 * This typedef definition is used as an argument to v4l2_ctrl_notify()
 147 * and as an argument at struct &v4l2_ctrl_handler.
 148 */
 149typedef void (*v4l2_ctrl_notify_fnc)(struct v4l2_ctrl *ctrl, void *priv);
 150
 151/**
 152 * struct v4l2_ctrl - The control structure.
 153 *
 154 * @node:	The list node.
 155 * @ev_subs:	The list of control event subscriptions.
 156 * @handler:	The handler that owns the control.
 157 * @cluster:	Point to start of cluster array.
 158 * @ncontrols:	Number of controls in cluster array.
 159 * @done:	Internal flag: set for each processed control.
 160 * @is_new:	Set when the user specified a new value for this control. It
 161 *		is also set when called from v4l2_ctrl_handler_setup(). Drivers
 162 *		should never set this flag.
 163 * @has_changed: Set when the current value differs from the new value. Drivers
 164 *		should never use this flag.
 165 * @is_private: If set, then this control is private to its handler and it
 166 *		will not be added to any other handlers. Drivers can set
 167 *		this flag.
 168 * @is_auto:   If set, then this control selects whether the other cluster
 169 *		members are in 'automatic' mode or 'manual' mode. This is
 170 *		used for autogain/gain type clusters. Drivers should never
 171 *		set this flag directly.
 172 * @is_int:    If set, then this control has a simple integer value (i.e. it
 173 *		uses ctrl->val).
 174 * @is_string: If set, then this control has type %V4L2_CTRL_TYPE_STRING.
 175 * @is_ptr:	If set, then this control is an array and/or has type >=
 176 *		%V4L2_CTRL_COMPOUND_TYPES
 177 *		and/or has type %V4L2_CTRL_TYPE_STRING. In other words, &struct
 178 *		v4l2_ext_control uses field p to point to the data.
 179 * @is_array: If set, then this control contains an N-dimensional array.
 180 * @has_volatiles: If set, then one or more members of the cluster are volatile.
 181 *		Drivers should never touch this flag.
 182 * @call_notify: If set, then call the handler's notify function whenever the
 183 *		control's value changes.
 184 * @manual_mode_value: If the is_auto flag is set, then this is the value
 185 *		of the auto control that determines if that control is in
 186 *		manual mode. So if the value of the auto control equals this
 187 *		value, then the whole cluster is in manual mode. Drivers should
 188 *		never set this flag directly.
 189 * @ops:	The control ops.
 190 * @type_ops:	The control type ops.
 191 * @id:	The control ID.
 192 * @name:	The control name.
 193 * @type:	The control type.
 194 * @minimum:	The control's minimum value.
 195 * @maximum:	The control's maximum value.
 196 * @default_value: The control's default value.
 197 * @step:	The control's step value for non-menu controls.
 198 * @elems:	The number of elements in the N-dimensional array.
 199 * @elem_size:	The size in bytes of the control.
 200 * @dims:	The size of each dimension.
 201 * @nr_of_dims:The number of dimensions in @dims.
 202 * @menu_skip_mask: The control's skip mask for menu controls. This makes it
 203 *		easy to skip menu items that are not valid. If bit X is set,
 204 *		then menu item X is skipped. Of course, this only works for
 205 *		menus with <= 32 menu items. There are no menus that come
 206 *		close to that number, so this is OK. Should we ever need more,
 207 *		then this will have to be extended to a u64 or a bit array.
 208 * @qmenu:	A const char * array for all menu items. Array entries that are
 209 *		empty strings ("") correspond to non-existing menu items (this
 210 *		is in addition to the menu_skip_mask above). The last entry
 211 *		must be NULL.
 212 *		Used only if the @type is %V4L2_CTRL_TYPE_MENU.
 213 * @qmenu_int:	A 64-bit integer array for with integer menu items.
 214 *		The size of array must be equal to the menu size, e. g.:
 215 *		:math:`ceil(\frac{maximum - minimum}{step}) + 1`.
 216 *		Used only if the @type is %V4L2_CTRL_TYPE_INTEGER_MENU.
 217 * @flags:	The control's flags.
 218 * @cur:	Structure to store the current value.
 219 * @cur.val:	The control's current value, if the @type is represented via
 220 *		a u32 integer (see &enum v4l2_ctrl_type).
 221 * @val:	The control's new s32 value.
 222 * @priv:	The control's private pointer. For use by the driver. It is
 223 *		untouched by the control framework. Note that this pointer is
 224 *		not freed when the control is deleted. Should this be needed
 225 *		then a new internal bitfield can be added to tell the framework
 226 *		to free this pointer.
 227 * @p_def:	The control's default value represented via a union which
 228 *		provides a standard way of accessing control types
 229 *		through a pointer (for compound controls only).
 230 * @p_cur:	The control's current value represented via a union which
 231 *		provides a standard way of accessing control types
 232 *		through a pointer.
 233 * @p_new:	The control's new value represented via a union which provides
 234 *		a standard way of accessing control types
 235 *		through a pointer.
 236 */
 237struct v4l2_ctrl {
 238	/* Administrative fields */
 239	struct list_head node;
 240	struct list_head ev_subs;
 241	struct v4l2_ctrl_handler *handler;
 242	struct v4l2_ctrl **cluster;
 243	unsigned int ncontrols;
 244
 245	unsigned int done:1;
 246
 247	unsigned int is_new:1;
 248	unsigned int has_changed:1;
 249	unsigned int is_private:1;
 250	unsigned int is_auto:1;
 251	unsigned int is_int:1;
 252	unsigned int is_string:1;
 253	unsigned int is_ptr:1;
 254	unsigned int is_array:1;
 255	unsigned int has_volatiles:1;
 256	unsigned int call_notify:1;
 257	unsigned int manual_mode_value:8;
 258
 259	const struct v4l2_ctrl_ops *ops;
 260	const struct v4l2_ctrl_type_ops *type_ops;
 261	u32 id;
 262	const char *name;
 263	enum v4l2_ctrl_type type;
 264	s64 minimum, maximum, default_value;
 265	u32 elems;
 266	u32 elem_size;
 267	u32 dims[V4L2_CTRL_MAX_DIMS];
 268	u32 nr_of_dims;
 269	union {
 270		u64 step;
 271		u64 menu_skip_mask;
 272	};
 273	union {
 274		const char * const *qmenu;
 275		const s64 *qmenu_int;
 276	};
 277	unsigned long flags;
 278	void *priv;
 279	s32 val;
 280	struct {
 281		s32 val;
 282	} cur;
 283
 284	union v4l2_ctrl_ptr p_def;
 285	union v4l2_ctrl_ptr p_new;
 286	union v4l2_ctrl_ptr p_cur;
 287};
 288
 289/**
 290 * struct v4l2_ctrl_ref - The control reference.
 291 *
 292 * @node:	List node for the sorted list.
 293 * @next:	Single-link list node for the hash.
 294 * @ctrl:	The actual control information.
 295 * @helper:	Pointer to helper struct. Used internally in
 296 *		``prepare_ext_ctrls`` function at ``v4l2-ctrl.c``.
 297 * @from_other_dev: If true, then @ctrl was defined in another
 298 *		device than the &struct v4l2_ctrl_handler.
 299 * @req_done:	Internal flag: if the control handler containing this control
 300 *		reference is bound to a media request, then this is set when
 301 *		the control has been applied. This prevents applying controls
 302 *		from a cluster with multiple controls twice (when the first
 303 *		control of a cluster is applied, they all are).
 304 * @req:	If set, this refers to another request that sets this control.
 305 * @p_req:	If the control handler containing this control reference
 306 *		is bound to a media request, then this points to the
 307 *		value of the control that should be applied when the request
 308 *		is executed, or to the value of the control at the time
 309 *		that the request was completed.
 
 
 310 *
 311 * Each control handler has a list of these refs. The list_head is used to
 312 * keep a sorted-by-control-ID list of all controls, while the next pointer
 313 * is used to link the control in the hash's bucket.
 314 */
 315struct v4l2_ctrl_ref {
 316	struct list_head node;
 317	struct v4l2_ctrl_ref *next;
 318	struct v4l2_ctrl *ctrl;
 319	struct v4l2_ctrl_helper *helper;
 320	bool from_other_dev;
 321	bool req_done;
 322	struct v4l2_ctrl_ref *req;
 323	union v4l2_ctrl_ptr p_req;
 324};
 325
 326/**
 327 * struct v4l2_ctrl_handler - The control handler keeps track of all the
 328 *	controls: both the controls owned by the handler and those inherited
 329 *	from other handlers.
 330 *
 331 * @_lock:	Default for "lock".
 332 * @lock:	Lock to control access to this handler and its controls.
 333 *		May be replaced by the user right after init.
 334 * @ctrls:	The list of controls owned by this handler.
 335 * @ctrl_refs:	The list of control references.
 336 * @cached:	The last found control reference. It is common that the same
 337 *		control is needed multiple times, so this is a simple
 338 *		optimization.
 339 * @buckets:	Buckets for the hashing. Allows for quick control lookup.
 340 * @notify:	A notify callback that is called whenever the control changes
 341 *		value.
 342 *		Note that the handler's lock is held when the notify function
 343 *		is called!
 344 * @notify_priv: Passed as argument to the v4l2_ctrl notify callback.
 345 * @nr_of_buckets: Total number of buckets in the array.
 346 * @error:	The error code of the first failed control addition.
 347 * @request_is_queued: True if the request was queued.
 348 * @requests:	List to keep track of open control handler request objects.
 349 *		For the parent control handler (@req_obj.req == NULL) this
 350 *		is the list header. When the parent control handler is
 351 *		removed, it has to unbind and put all these requests since
 352 *		they refer to the parent.
 353 * @requests_queued: List of the queued requests. This determines the order
 354 *		in which these controls are applied. Once the request is
 355 *		completed it is removed from this list.
 356 * @req_obj:	The &struct media_request_object, used to link into a
 357 *		&struct media_request. This request object has a refcount.
 358 */
 359struct v4l2_ctrl_handler {
 360	struct mutex _lock;
 361	struct mutex *lock;
 362	struct list_head ctrls;
 363	struct list_head ctrl_refs;
 364	struct v4l2_ctrl_ref *cached;
 365	struct v4l2_ctrl_ref **buckets;
 366	v4l2_ctrl_notify_fnc notify;
 367	void *notify_priv;
 368	u16 nr_of_buckets;
 369	int error;
 370	bool request_is_queued;
 371	struct list_head requests;
 372	struct list_head requests_queued;
 373	struct media_request_object req_obj;
 374};
 375
 376/**
 377 * struct v4l2_ctrl_config - Control configuration structure.
 378 *
 379 * @ops:	The control ops.
 380 * @type_ops:	The control type ops. Only needed for compound controls.
 381 * @id:	The control ID.
 382 * @name:	The control name.
 383 * @type:	The control type.
 384 * @min:	The control's minimum value.
 385 * @max:	The control's maximum value.
 386 * @step:	The control's step value for non-menu controls.
 387 * @def:	The control's default value.
 388 * @p_def:	The control's default value for compound controls.
 389 * @dims:	The size of each dimension.
 390 * @elem_size:	The size in bytes of the control.
 391 * @flags:	The control's flags.
 392 * @menu_skip_mask: The control's skip mask for menu controls. This makes it
 393 *		easy to skip menu items that are not valid. If bit X is set,
 394 *		then menu item X is skipped. Of course, this only works for
 395 *		menus with <= 64 menu items. There are no menus that come
 396 *		close to that number, so this is OK. Should we ever need more,
 397 *		then this will have to be extended to a bit array.
 398 * @qmenu:	A const char * array for all menu items. Array entries that are
 399 *		empty strings ("") correspond to non-existing menu items (this
 400 *		is in addition to the menu_skip_mask above). The last entry
 401 *		must be NULL.
 402 * @qmenu_int:	A const s64 integer array for all menu items of the type
 403 *		V4L2_CTRL_TYPE_INTEGER_MENU.
 404 * @is_private: If set, then this control is private to its handler and it
 405 *		will not be added to any other handlers.
 406 */
 407struct v4l2_ctrl_config {
 408	const struct v4l2_ctrl_ops *ops;
 409	const struct v4l2_ctrl_type_ops *type_ops;
 410	u32 id;
 411	const char *name;
 412	enum v4l2_ctrl_type type;
 413	s64 min;
 414	s64 max;
 415	u64 step;
 416	s64 def;
 417	union v4l2_ctrl_ptr p_def;
 418	u32 dims[V4L2_CTRL_MAX_DIMS];
 419	u32 elem_size;
 420	u32 flags;
 421	u64 menu_skip_mask;
 422	const char * const *qmenu;
 423	const s64 *qmenu_int;
 424	unsigned int is_private:1;
 425};
 426
 427/**
 428 * v4l2_ctrl_fill - Fill in the control fields based on the control ID.
 429 *
 430 * @id: ID of the control
 431 * @name: pointer to be filled with a string with the name of the control
 432 * @type: pointer for storing the type of the control
 433 * @min: pointer for storing the minimum value for the control
 434 * @max: pointer for storing the maximum value for the control
 435 * @step: pointer for storing the control step
 436 * @def: pointer for storing the default value for the control
 437 * @flags: pointer for storing the flags to be used on the control
 438 *
 439 * This works for all standard V4L2 controls.
 440 * For non-standard controls it will only fill in the given arguments
 441 * and @name content will be set to %NULL.
 442 *
 443 * This function will overwrite the contents of @name, @type and @flags.
 444 * The contents of @min, @max, @step and @def may be modified depending on
 445 * the type.
 446 *
 447 * .. note::
 448 *
 449 *    Do not use in drivers! It is used internally for backwards compatibility
 450 *    control handling only. Once all drivers are converted to use the new
 451 *    control framework this function will no longer be exported.
 452 */
 453void v4l2_ctrl_fill(u32 id, const char **name, enum v4l2_ctrl_type *type,
 454		    s64 *min, s64 *max, u64 *step, s64 *def, u32 *flags);
 455
 456
 457/**
 458 * v4l2_ctrl_handler_init_class() - Initialize the control handler.
 459 * @hdl:	The control handler.
 460 * @nr_of_controls_hint: A hint of how many controls this handler is
 461 *		expected to refer to. This is the total number, so including
 462 *		any inherited controls. It doesn't have to be precise, but if
 463 *		it is way off, then you either waste memory (too many buckets
 464 *		are allocated) or the control lookup becomes slower (not enough
 465 *		buckets are allocated, so there are more slow list lookups).
 466 *		It will always work, though.
 467 * @key:	Used by the lock validator if CONFIG_LOCKDEP is set.
 468 * @name:	Used by the lock validator if CONFIG_LOCKDEP is set.
 469 *
 470 * .. attention::
 471 *
 472 *    Never use this call directly, always use the v4l2_ctrl_handler_init()
 473 *    macro that hides the @key and @name arguments.
 474 *
 475 * Return: returns an error if the buckets could not be allocated. This
 476 * error will also be stored in @hdl->error.
 477 */
 478int v4l2_ctrl_handler_init_class(struct v4l2_ctrl_handler *hdl,
 479				 unsigned int nr_of_controls_hint,
 480				 struct lock_class_key *key, const char *name);
 481
 482#ifdef CONFIG_LOCKDEP
 483
 484/**
 485 * v4l2_ctrl_handler_init - helper function to create a static struct
 486 *	 &lock_class_key and calls v4l2_ctrl_handler_init_class()
 487 *
 488 * @hdl:	The control handler.
 489 * @nr_of_controls_hint: A hint of how many controls this handler is
 490 *		expected to refer to. This is the total number, so including
 491 *		any inherited controls. It doesn't have to be precise, but if
 492 *		it is way off, then you either waste memory (too many buckets
 493 *		are allocated) or the control lookup becomes slower (not enough
 494 *		buckets are allocated, so there are more slow list lookups).
 495 *		It will always work, though.
 496 *
 497 * This helper function creates a static struct &lock_class_key and
 498 * calls v4l2_ctrl_handler_init_class(), providing a proper name for the lock
 499 * validador.
 500 *
 501 * Use this helper function to initialize a control handler.
 502 */
 503#define v4l2_ctrl_handler_init(hdl, nr_of_controls_hint)		\
 504(									\
 505	({								\
 506		static struct lock_class_key _key;			\
 507		v4l2_ctrl_handler_init_class(hdl, nr_of_controls_hint,	\
 508					&_key,				\
 509					KBUILD_BASENAME ":"		\
 510					__stringify(__LINE__) ":"	\
 511					"(" #hdl ")->_lock");		\
 512	})								\
 513)
 514#else
 515#define v4l2_ctrl_handler_init(hdl, nr_of_controls_hint)		\
 516	v4l2_ctrl_handler_init_class(hdl, nr_of_controls_hint, NULL, NULL)
 517#endif
 518
 519/**
 520 * v4l2_ctrl_handler_free() - Free all controls owned by the handler and free
 521 * the control list.
 522 * @hdl:	The control handler.
 523 *
 524 * Does nothing if @hdl == NULL.
 525 */
 526void v4l2_ctrl_handler_free(struct v4l2_ctrl_handler *hdl);
 527
 528/**
 529 * v4l2_ctrl_lock() - Helper function to lock the handler
 530 * associated with the control.
 531 * @ctrl:	The control to lock.
 532 */
 533static inline void v4l2_ctrl_lock(struct v4l2_ctrl *ctrl)
 534{
 535	mutex_lock(ctrl->handler->lock);
 536}
 537
 538/**
 539 * v4l2_ctrl_unlock() - Helper function to unlock the handler
 540 * associated with the control.
 541 * @ctrl:	The control to unlock.
 542 */
 543static inline void v4l2_ctrl_unlock(struct v4l2_ctrl *ctrl)
 544{
 545	mutex_unlock(ctrl->handler->lock);
 546}
 547
 548/**
 549 * __v4l2_ctrl_handler_setup() - Call the s_ctrl op for all controls belonging
 550 * to the handler to initialize the hardware to the current control values. The
 551 * caller is responsible for acquiring the control handler mutex on behalf of
 552 * __v4l2_ctrl_handler_setup().
 553 * @hdl:	The control handler.
 554 *
 555 * Button controls will be skipped, as are read-only controls.
 556 *
 557 * If @hdl == NULL, then this just returns 0.
 558 */
 559int __v4l2_ctrl_handler_setup(struct v4l2_ctrl_handler *hdl);
 560
 561/**
 562 * v4l2_ctrl_handler_setup() - Call the s_ctrl op for all controls belonging
 563 * to the handler to initialize the hardware to the current control values.
 564 * @hdl:	The control handler.
 565 *
 566 * Button controls will be skipped, as are read-only controls.
 567 *
 568 * If @hdl == NULL, then this just returns 0.
 569 */
 570int v4l2_ctrl_handler_setup(struct v4l2_ctrl_handler *hdl);
 571
 572/**
 573 * v4l2_ctrl_handler_log_status() - Log all controls owned by the handler.
 574 * @hdl:	The control handler.
 575 * @prefix:	The prefix to use when logging the control values. If the
 576 *		prefix does not end with a space, then ": " will be added
 577 *		after the prefix. If @prefix == NULL, then no prefix will be
 578 *		used.
 579 *
 580 * For use with VIDIOC_LOG_STATUS.
 581 *
 582 * Does nothing if @hdl == NULL.
 583 */
 584void v4l2_ctrl_handler_log_status(struct v4l2_ctrl_handler *hdl,
 585				  const char *prefix);
 586
 587/**
 588 * v4l2_ctrl_new_custom() - Allocate and initialize a new custom V4L2
 589 *	control.
 590 *
 591 * @hdl:	The control handler.
 592 * @cfg:	The control's configuration data.
 593 * @priv:	The control's driver-specific private data.
 594 *
 595 * If the &v4l2_ctrl struct could not be allocated then NULL is returned
 596 * and @hdl->error is set to the error code (if it wasn't set already).
 597 */
 598struct v4l2_ctrl *v4l2_ctrl_new_custom(struct v4l2_ctrl_handler *hdl,
 599				       const struct v4l2_ctrl_config *cfg,
 600				       void *priv);
 601
 602/**
 603 * v4l2_ctrl_new_std() - Allocate and initialize a new standard V4L2 non-menu
 604 *	control.
 605 *
 606 * @hdl:	The control handler.
 607 * @ops:	The control ops.
 608 * @id:		The control ID.
 609 * @min:	The control's minimum value.
 610 * @max:	The control's maximum value.
 611 * @step:	The control's step value
 612 * @def:	The control's default value.
 613 *
 614 * If the &v4l2_ctrl struct could not be allocated, or the control
 615 * ID is not known, then NULL is returned and @hdl->error is set to the
 616 * appropriate error code (if it wasn't set already).
 617 *
 618 * If @id refers to a menu control, then this function will return NULL.
 619 *
 620 * Use v4l2_ctrl_new_std_menu() when adding menu controls.
 621 */
 622struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl,
 623				    const struct v4l2_ctrl_ops *ops,
 624				    u32 id, s64 min, s64 max, u64 step,
 625				    s64 def);
 626
 627/**
 628 * v4l2_ctrl_new_std_menu() - Allocate and initialize a new standard V4L2
 629 *	menu control.
 630 *
 631 * @hdl:	The control handler.
 632 * @ops:	The control ops.
 633 * @id:		The control ID.
 634 * @max:	The control's maximum value.
 635 * @mask:	The control's skip mask for menu controls. This makes it
 636 *		easy to skip menu items that are not valid. If bit X is set,
 637 *		then menu item X is skipped. Of course, this only works for
 638 *		menus with <= 64 menu items. There are no menus that come
 639 *		close to that number, so this is OK. Should we ever need more,
 640 *		then this will have to be extended to a bit array.
 641 * @def:	The control's default value.
 642 *
 643 * Same as v4l2_ctrl_new_std(), but @min is set to 0 and the @mask value
 644 * determines which menu items are to be skipped.
 645 *
 646 * If @id refers to a non-menu control, then this function will return NULL.
 647 */
 648struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl,
 649					 const struct v4l2_ctrl_ops *ops,
 650					 u32 id, u8 max, u64 mask, u8 def);
 651
 652/**
 653 * v4l2_ctrl_new_std_menu_items() - Create a new standard V4L2 menu control
 654 *	with driver specific menu.
 655 *
 656 * @hdl:	The control handler.
 657 * @ops:	The control ops.
 658 * @id:	The control ID.
 659 * @max:	The control's maximum value.
 660 * @mask:	The control's skip mask for menu controls. This makes it
 661 *		easy to skip menu items that are not valid. If bit X is set,
 662 *		then menu item X is skipped. Of course, this only works for
 663 *		menus with <= 64 menu items. There are no menus that come
 664 *		close to that number, so this is OK. Should we ever need more,
 665 *		then this will have to be extended to a bit array.
 666 * @def:	The control's default value.
 667 * @qmenu:	The new menu.
 668 *
 669 * Same as v4l2_ctrl_new_std_menu(), but @qmenu will be the driver specific
 670 * menu of this control.
 671 *
 672 */
 673struct v4l2_ctrl *v4l2_ctrl_new_std_menu_items(struct v4l2_ctrl_handler *hdl,
 674					       const struct v4l2_ctrl_ops *ops,
 675					       u32 id, u8 max,
 676					       u64 mask, u8 def,
 677					       const char * const *qmenu);
 678
 679/**
 680 * v4l2_ctrl_new_std_compound() - Allocate and initialize a new standard V4L2
 681 *      compound control.
 682 *
 683 * @hdl:       The control handler.
 684 * @ops:       The control ops.
 685 * @id:        The control ID.
 686 * @p_def:     The control's default value.
 687 *
 688 * Sames as v4l2_ctrl_new_std(), but with support to compound controls, thanks
 689 * to the @p_def field. Use v4l2_ctrl_ptr_create() to create @p_def from a
 690 * pointer. Use v4l2_ctrl_ptr_create(NULL) if the default value of the
 691 * compound control should be all zeroes.
 692 *
 693 */
 694struct v4l2_ctrl *v4l2_ctrl_new_std_compound(struct v4l2_ctrl_handler *hdl,
 695					     const struct v4l2_ctrl_ops *ops,
 696					     u32 id,
 697					     const union v4l2_ctrl_ptr p_def);
 698
 699/**
 700 * v4l2_ctrl_new_int_menu() - Create a new standard V4L2 integer menu control.
 701 *
 702 * @hdl:	The control handler.
 703 * @ops:	The control ops.
 704 * @id:	The control ID.
 705 * @max:	The control's maximum value.
 706 * @def:	The control's default value.
 707 * @qmenu_int:	The control's menu entries.
 708 *
 709 * Same as v4l2_ctrl_new_std_menu(), but @mask is set to 0 and it additionally
 710 * takes as an argument an array of integers determining the menu items.
 711 *
 712 * If @id refers to a non-integer-menu control, then this function will
 713 * return %NULL.
 714 */
 715struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl,
 716					 const struct v4l2_ctrl_ops *ops,
 717					 u32 id, u8 max, u8 def,
 718					 const s64 *qmenu_int);
 719
 720/**
 721 * typedef v4l2_ctrl_filter - Typedef to define the filter function to be
 722 *	used when adding a control handler.
 723 *
 724 * @ctrl: pointer to struct &v4l2_ctrl.
 725 */
 726
 727typedef bool (*v4l2_ctrl_filter)(const struct v4l2_ctrl *ctrl);
 728
 729/**
 730 * v4l2_ctrl_add_handler() - Add all controls from handler @add to
 731 *	handler @hdl.
 732 *
 733 * @hdl:	The control handler.
 734 * @add:	The control handler whose controls you want to add to
 735 *		the @hdl control handler.
 736 * @filter:	This function will filter which controls should be added.
 737 * @from_other_dev: If true, then the controls in @add were defined in another
 738 *		device than @hdl.
 739 *
 740 * Does nothing if either of the two handlers is a NULL pointer.
 741 * If @filter is NULL, then all controls are added. Otherwise only those
 742 * controls for which @filter returns true will be added.
 743 * In case of an error @hdl->error will be set to the error code (if it
 744 * wasn't set already).
 745 */
 746int v4l2_ctrl_add_handler(struct v4l2_ctrl_handler *hdl,
 747			  struct v4l2_ctrl_handler *add,
 748			  v4l2_ctrl_filter filter,
 749			  bool from_other_dev);
 750
 751/**
 752 * v4l2_ctrl_radio_filter() - Standard filter for radio controls.
 753 *
 754 * @ctrl:	The control that is filtered.
 755 *
 756 * This will return true for any controls that are valid for radio device
 757 * nodes. Those are all of the V4L2_CID_AUDIO_* user controls and all FM
 758 * transmitter class controls.
 759 *
 760 * This function is to be used with v4l2_ctrl_add_handler().
 761 */
 762bool v4l2_ctrl_radio_filter(const struct v4l2_ctrl *ctrl);
 763
 764/**
 765 * v4l2_ctrl_cluster() - Mark all controls in the cluster as belonging
 766 *	to that cluster.
 767 *
 768 * @ncontrols:	The number of controls in this cluster.
 769 * @controls:	The cluster control array of size @ncontrols.
 770 */
 771void v4l2_ctrl_cluster(unsigned int ncontrols, struct v4l2_ctrl **controls);
 772
 773
 774/**
 775 * v4l2_ctrl_auto_cluster() - Mark all controls in the cluster as belonging
 776 *	to that cluster and set it up for autofoo/foo-type handling.
 777 *
 778 * @ncontrols:	The number of controls in this cluster.
 779 * @controls:	The cluster control array of size @ncontrols. The first control
 780 *		must be the 'auto' control (e.g. autogain, autoexposure, etc.)
 781 * @manual_val: The value for the first control in the cluster that equals the
 782 *		manual setting.
 783 * @set_volatile: If true, then all controls except the first auto control will
 784 *		be volatile.
 785 *
 786 * Use for control groups where one control selects some automatic feature and
 787 * the other controls are only active whenever the automatic feature is turned
 788 * off (manual mode). Typical examples: autogain vs gain, auto-whitebalance vs
 789 * red and blue balance, etc.
 790 *
 791 * The behavior of such controls is as follows:
 792 *
 793 * When the autofoo control is set to automatic, then any manual controls
 794 * are set to inactive and any reads will call g_volatile_ctrl (if the control
 795 * was marked volatile).
 796 *
 797 * When the autofoo control is set to manual, then any manual controls will
 798 * be marked active, and any reads will just return the current value without
 799 * going through g_volatile_ctrl.
 800 *
 801 * In addition, this function will set the %V4L2_CTRL_FLAG_UPDATE flag
 802 * on the autofoo control and %V4L2_CTRL_FLAG_INACTIVE on the foo control(s)
 803 * if autofoo is in auto mode.
 804 */
 805void v4l2_ctrl_auto_cluster(unsigned int ncontrols,
 806			    struct v4l2_ctrl **controls,
 807			    u8 manual_val, bool set_volatile);
 808
 809
 810/**
 811 * v4l2_ctrl_find() - Find a control with the given ID.
 812 *
 813 * @hdl:	The control handler.
 814 * @id:	The control ID to find.
 815 *
 816 * If @hdl == NULL this will return NULL as well. Will lock the handler so
 817 * do not use from inside &v4l2_ctrl_ops.
 818 */
 819struct v4l2_ctrl *v4l2_ctrl_find(struct v4l2_ctrl_handler *hdl, u32 id);
 820
 821/**
 822 * v4l2_ctrl_activate() - Make the control active or inactive.
 823 * @ctrl:	The control to (de)activate.
 824 * @active:	True if the control should become active.
 825 *
 826 * This sets or clears the V4L2_CTRL_FLAG_INACTIVE flag atomically.
 827 * Does nothing if @ctrl == NULL.
 828 * This will usually be called from within the s_ctrl op.
 829 * The V4L2_EVENT_CTRL event will be generated afterwards.
 830 *
 831 * This function assumes that the control handler is locked.
 832 */
 833void v4l2_ctrl_activate(struct v4l2_ctrl *ctrl, bool active);
 834
 835/**
 836 * __v4l2_ctrl_grab() - Unlocked variant of v4l2_ctrl_grab.
 837 *
 838 * @ctrl:	The control to (de)activate.
 839 * @grabbed:	True if the control should become grabbed.
 840 *
 841 * This sets or clears the V4L2_CTRL_FLAG_GRABBED flag atomically.
 842 * Does nothing if @ctrl == NULL.
 843 * The V4L2_EVENT_CTRL event will be generated afterwards.
 844 * This will usually be called when starting or stopping streaming in the
 845 * driver.
 846 *
 847 * This function assumes that the control handler is locked by the caller.
 848 */
 849void __v4l2_ctrl_grab(struct v4l2_ctrl *ctrl, bool grabbed);
 850
 851/**
 852 * v4l2_ctrl_grab() - Mark the control as grabbed or not grabbed.
 853 *
 854 * @ctrl:	The control to (de)activate.
 855 * @grabbed:	True if the control should become grabbed.
 856 *
 857 * This sets or clears the V4L2_CTRL_FLAG_GRABBED flag atomically.
 858 * Does nothing if @ctrl == NULL.
 859 * The V4L2_EVENT_CTRL event will be generated afterwards.
 860 * This will usually be called when starting or stopping streaming in the
 861 * driver.
 862 *
 863 * This function assumes that the control handler is not locked and will
 864 * take the lock itself.
 865 */
 866static inline void v4l2_ctrl_grab(struct v4l2_ctrl *ctrl, bool grabbed)
 867{
 868	if (!ctrl)
 869		return;
 870
 871	v4l2_ctrl_lock(ctrl);
 872	__v4l2_ctrl_grab(ctrl, grabbed);
 873	v4l2_ctrl_unlock(ctrl);
 874}
 875
 876/**
 877 *__v4l2_ctrl_modify_range() - Unlocked variant of v4l2_ctrl_modify_range()
 878 *
 879 * @ctrl:	The control to update.
 880 * @min:	The control's minimum value.
 881 * @max:	The control's maximum value.
 882 * @step:	The control's step value
 883 * @def:	The control's default value.
 884 *
 885 * Update the range of a control on the fly. This works for control types
 886 * INTEGER, BOOLEAN, MENU, INTEGER MENU and BITMASK. For menu controls the
 887 * @step value is interpreted as a menu_skip_mask.
 888 *
 889 * An error is returned if one of the range arguments is invalid for this
 890 * control type.
 891 *
 892 * The caller is responsible for acquiring the control handler mutex on behalf
 893 * of __v4l2_ctrl_modify_range().
 894 */
 895int __v4l2_ctrl_modify_range(struct v4l2_ctrl *ctrl,
 896			     s64 min, s64 max, u64 step, s64 def);
 897
 898/**
 899 * v4l2_ctrl_modify_range() - Update the range of a control.
 900 *
 901 * @ctrl:	The control to update.
 902 * @min:	The control's minimum value.
 903 * @max:	The control's maximum value.
 904 * @step:	The control's step value
 905 * @def:	The control's default value.
 906 *
 907 * Update the range of a control on the fly. This works for control types
 908 * INTEGER, BOOLEAN, MENU, INTEGER MENU and BITMASK. For menu controls the
 909 * @step value is interpreted as a menu_skip_mask.
 910 *
 911 * An error is returned if one of the range arguments is invalid for this
 912 * control type.
 913 *
 914 * This function assumes that the control handler is not locked and will
 915 * take the lock itself.
 916 */
 917static inline int v4l2_ctrl_modify_range(struct v4l2_ctrl *ctrl,
 918					 s64 min, s64 max, u64 step, s64 def)
 919{
 920	int rval;
 921
 922	v4l2_ctrl_lock(ctrl);
 923	rval = __v4l2_ctrl_modify_range(ctrl, min, max, step, def);
 924	v4l2_ctrl_unlock(ctrl);
 925
 926	return rval;
 927}
 928
 929/**
 930 * v4l2_ctrl_notify() - Function to set a notify callback for a control.
 931 *
 932 * @ctrl:	The control.
 933 * @notify:	The callback function.
 934 * @priv:	The callback private handle, passed as argument to the callback.
 935 *
 936 * This function sets a callback function for the control. If @ctrl is NULL,
 937 * then it will do nothing. If @notify is NULL, then the notify callback will
 938 * be removed.
 939 *
 940 * There can be only one notify. If another already exists, then a WARN_ON
 941 * will be issued and the function will do nothing.
 942 */
 943void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl, v4l2_ctrl_notify_fnc notify,
 944		      void *priv);
 945
 946/**
 947 * v4l2_ctrl_get_name() - Get the name of the control
 948 *
 949 * @id:		The control ID.
 950 *
 951 * This function returns the name of the given control ID or NULL if it isn't
 952 * a known control.
 953 */
 954const char *v4l2_ctrl_get_name(u32 id);
 955
 956/**
 957 * v4l2_ctrl_get_menu() - Get the menu string array of the control
 958 *
 959 * @id:		The control ID.
 960 *
 961 * This function returns the NULL-terminated menu string array name of the
 962 * given control ID or NULL if it isn't a known menu control.
 963 */
 964const char * const *v4l2_ctrl_get_menu(u32 id);
 965
 966/**
 967 * v4l2_ctrl_get_int_menu() - Get the integer menu array of the control
 968 *
 969 * @id:		The control ID.
 970 * @len:	The size of the integer array.
 971 *
 972 * This function returns the integer array of the given control ID or NULL if it
 973 * if it isn't a known integer menu control.
 974 */
 975const s64 *v4l2_ctrl_get_int_menu(u32 id, u32 *len);
 976
 977/**
 978 * v4l2_ctrl_g_ctrl() - Helper function to get the control's value from
 979 *	within a driver.
 980 *
 981 * @ctrl:	The control.
 982 *
 983 * This returns the control's value safely by going through the control
 984 * framework. This function will lock the control's handler, so it cannot be
 985 * used from within the &v4l2_ctrl_ops functions.
 986 *
 987 * This function is for integer type controls only.
 988 */
 989s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl);
 990
 991/**
 992 * __v4l2_ctrl_s_ctrl() - Unlocked variant of v4l2_ctrl_s_ctrl().
 993 *
 994 * @ctrl:	The control.
 995 * @val:	The new value.
 996 *
 997 * This sets the control's new value safely by going through the control
 998 * framework. This function assumes the control's handler is already locked,
 999 * allowing it to be used from within the &v4l2_ctrl_ops functions.
1000 *
1001 * This function is for integer type controls only.
1002 */
1003int __v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val);
1004
1005/**
1006 * v4l2_ctrl_s_ctrl() - Helper function to set the control's value from
1007 *	within a driver.
1008 * @ctrl:	The control.
1009 * @val:	The new value.
1010 *
1011 * This sets the control's new value safely by going through the control
1012 * framework. This function will lock the control's handler, so it cannot be
1013 * used from within the &v4l2_ctrl_ops functions.
1014 *
1015 * This function is for integer type controls only.
1016 */
1017static inline int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val)
1018{
1019	int rval;
1020
1021	v4l2_ctrl_lock(ctrl);
1022	rval = __v4l2_ctrl_s_ctrl(ctrl, val);
1023	v4l2_ctrl_unlock(ctrl);
1024
1025	return rval;
1026}
1027
1028/**
1029 * v4l2_ctrl_g_ctrl_int64() - Helper function to get a 64-bit control's value
1030 *	from within a driver.
1031 *
1032 * @ctrl:	The control.
1033 *
1034 * This returns the control's value safely by going through the control
1035 * framework. This function will lock the control's handler, so it cannot be
1036 * used from within the &v4l2_ctrl_ops functions.
1037 *
1038 * This function is for 64-bit integer type controls only.
1039 */
1040s64 v4l2_ctrl_g_ctrl_int64(struct v4l2_ctrl *ctrl);
1041
1042/**
1043 * __v4l2_ctrl_s_ctrl_int64() - Unlocked variant of v4l2_ctrl_s_ctrl_int64().
1044 *
1045 * @ctrl:	The control.
1046 * @val:	The new value.
1047 *
1048 * This sets the control's new value safely by going through the control
1049 * framework. This function assumes the control's handler is already locked,
1050 * allowing it to be used from within the &v4l2_ctrl_ops functions.
1051 *
1052 * This function is for 64-bit integer type controls only.
1053 */
1054int __v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val);
1055
1056/**
1057 * v4l2_ctrl_s_ctrl_int64() - Helper function to set a 64-bit control's value
1058 *	from within a driver.
1059 *
1060 * @ctrl:	The control.
1061 * @val:	The new value.
1062 *
1063 * This sets the control's new value safely by going through the control
1064 * framework. This function will lock the control's handler, so it cannot be
1065 * used from within the &v4l2_ctrl_ops functions.
1066 *
1067 * This function is for 64-bit integer type controls only.
1068 */
1069static inline int v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val)
1070{
1071	int rval;
1072
1073	v4l2_ctrl_lock(ctrl);
1074	rval = __v4l2_ctrl_s_ctrl_int64(ctrl, val);
1075	v4l2_ctrl_unlock(ctrl);
1076
1077	return rval;
1078}
1079
1080/**
1081 * __v4l2_ctrl_s_ctrl_string() - Unlocked variant of v4l2_ctrl_s_ctrl_string().
1082 *
1083 * @ctrl:	The control.
1084 * @s:		The new string.
1085 *
1086 * This sets the control's new string safely by going through the control
1087 * framework. This function assumes the control's handler is already locked,
1088 * allowing it to be used from within the &v4l2_ctrl_ops functions.
1089 *
1090 * This function is for string type controls only.
1091 */
1092int __v4l2_ctrl_s_ctrl_string(struct v4l2_ctrl *ctrl, const char *s);
1093
1094/**
1095 * v4l2_ctrl_s_ctrl_string() - Helper function to set a control's string value
1096 *	 from within a driver.
1097 *
1098 * @ctrl:	The control.
1099 * @s:		The new string.
1100 *
1101 * This sets the control's new string safely by going through the control
1102 * framework. This function will lock the control's handler, so it cannot be
1103 * used from within the &v4l2_ctrl_ops functions.
1104 *
1105 * This function is for string type controls only.
1106 */
1107static inline int v4l2_ctrl_s_ctrl_string(struct v4l2_ctrl *ctrl, const char *s)
1108{
1109	int rval;
1110
1111	v4l2_ctrl_lock(ctrl);
1112	rval = __v4l2_ctrl_s_ctrl_string(ctrl, s);
1113	v4l2_ctrl_unlock(ctrl);
1114
1115	return rval;
1116}
1117
1118/**
1119 * __v4l2_ctrl_s_ctrl_compound() - Unlocked variant to set a compound control
1120 *
1121 * @ctrl: The control.
1122 * @type: The type of the data.
1123 * @p:    The new compound payload.
1124 *
1125 * This sets the control's new compound payload safely by going through the
1126 * control framework. This function assumes the control's handler is already
1127 * locked, allowing it to be used from within the &v4l2_ctrl_ops functions.
1128 *
1129 * This function is for compound type controls only.
1130 */
1131int __v4l2_ctrl_s_ctrl_compound(struct v4l2_ctrl *ctrl,
1132				enum v4l2_ctrl_type type, const void *p);
1133
1134/**
1135 * v4l2_ctrl_s_ctrl_compound() - Helper function to set a compound control
1136 *	from within a driver.
1137 *
1138 * @ctrl: The control.
1139 * @type: The type of the data.
1140 * @p:    The new compound payload.
1141 *
1142 * This sets the control's new compound payload safely by going through the
1143 * control framework. This function will lock the control's handler, so it
1144 * cannot be used from within the &v4l2_ctrl_ops functions.
1145 *
1146 * This function is for compound type controls only.
1147 */
1148static inline int v4l2_ctrl_s_ctrl_compound(struct v4l2_ctrl *ctrl,
1149					    enum v4l2_ctrl_type type,
1150					    const void *p)
1151{
1152	int rval;
1153
1154	v4l2_ctrl_lock(ctrl);
1155	rval = __v4l2_ctrl_s_ctrl_compound(ctrl, type, p);
1156	v4l2_ctrl_unlock(ctrl);
1157
1158	return rval;
1159}
1160
1161/* Helper defines for area type controls */
1162#define __v4l2_ctrl_s_ctrl_area(ctrl, area) \
1163	__v4l2_ctrl_s_ctrl_compound((ctrl), V4L2_CTRL_TYPE_AREA, (area))
1164#define v4l2_ctrl_s_ctrl_area(ctrl, area) \
1165	v4l2_ctrl_s_ctrl_compound((ctrl), V4L2_CTRL_TYPE_AREA, (area))
1166
1167/* Internal helper functions that deal with control events. */
1168extern const struct v4l2_subscribed_event_ops v4l2_ctrl_sub_ev_ops;
1169
1170/**
1171 * v4l2_ctrl_replace - Function to be used as a callback to
1172 *	&struct v4l2_subscribed_event_ops replace\(\)
1173 *
1174 * @old: pointer to struct &v4l2_event with the reported
1175 *	 event;
1176 * @new: pointer to struct &v4l2_event with the modified
1177 *	 event;
1178 */
1179void v4l2_ctrl_replace(struct v4l2_event *old, const struct v4l2_event *new);
1180
1181/**
1182 * v4l2_ctrl_merge - Function to be used as a callback to
1183 *	&struct v4l2_subscribed_event_ops merge(\)
1184 *
1185 * @old: pointer to struct &v4l2_event with the reported
1186 *	 event;
1187 * @new: pointer to struct &v4l2_event with the merged
1188 *	 event;
1189 */
1190void v4l2_ctrl_merge(const struct v4l2_event *old, struct v4l2_event *new);
1191
1192/**
1193 * v4l2_ctrl_log_status - helper function to implement %VIDIOC_LOG_STATUS ioctl
1194 *
1195 * @file: pointer to struct file
1196 * @fh: unused. Kept just to be compatible to the arguments expected by
1197 *	&struct v4l2_ioctl_ops.vidioc_log_status.
1198 *
1199 * Can be used as a vidioc_log_status function that just dumps all controls
1200 * associated with the filehandle.
1201 */
1202int v4l2_ctrl_log_status(struct file *file, void *fh);
1203
1204/**
1205 * v4l2_ctrl_subscribe_event - Subscribes to an event
1206 *
1207 *
1208 * @fh: pointer to struct v4l2_fh
1209 * @sub: pointer to &struct v4l2_event_subscription
1210 *
1211 * Can be used as a vidioc_subscribe_event function that just subscribes
1212 * control events.
1213 */
1214int v4l2_ctrl_subscribe_event(struct v4l2_fh *fh,
1215				const struct v4l2_event_subscription *sub);
1216
1217/**
1218 * v4l2_ctrl_poll - function to be used as a callback to the poll()
1219 *	That just polls for control events.
1220 *
1221 * @file: pointer to struct file
1222 * @wait: pointer to struct poll_table_struct
1223 */
1224__poll_t v4l2_ctrl_poll(struct file *file, struct poll_table_struct *wait);
1225
1226/**
1227 * v4l2_ctrl_request_setup - helper function to apply control values in a request
1228 *
1229 * @req: The request
1230 * @parent: The parent control handler ('priv' in media_request_object_find())
1231 *
1232 * This is a helper function to call the control handler's s_ctrl callback with
1233 * the control values contained in the request. Do note that this approach of
1234 * applying control values in a request is only applicable to memory-to-memory
1235 * devices.
1236 */
1237int v4l2_ctrl_request_setup(struct media_request *req,
1238			     struct v4l2_ctrl_handler *parent);
1239
1240/**
1241 * v4l2_ctrl_request_complete - Complete a control handler request object
1242 *
1243 * @req: The request
1244 * @parent: The parent control handler ('priv' in media_request_object_find())
1245 *
1246 * This function is to be called on each control handler that may have had a
1247 * request object associated with it, i.e. control handlers of a driver that
1248 * supports requests.
1249 *
1250 * The function first obtains the values of any volatile controls in the control
1251 * handler and attach them to the request. Then, the function completes the
1252 * request object.
1253 */
1254void v4l2_ctrl_request_complete(struct media_request *req,
1255				struct v4l2_ctrl_handler *parent);
1256
1257/**
1258 * v4l2_ctrl_request_hdl_find - Find the control handler in the request
1259 *
1260 * @req: The request
1261 * @parent: The parent control handler ('priv' in media_request_object_find())
1262 *
1263 * This function finds the control handler in the request. It may return
1264 * NULL if not found. When done, you must call v4l2_ctrl_request_put_hdl()
1265 * with the returned handler pointer.
1266 *
1267 * If the request is not in state VALIDATING or QUEUED, then this function
1268 * will always return NULL.
1269 *
1270 * Note that in state VALIDATING the req_queue_mutex is held, so
1271 * no objects can be added or deleted from the request.
1272 *
1273 * In state QUEUED it is the driver that will have to ensure this.
1274 */
1275struct v4l2_ctrl_handler *v4l2_ctrl_request_hdl_find(struct media_request *req,
1276					struct v4l2_ctrl_handler *parent);
1277
1278/**
1279 * v4l2_ctrl_request_hdl_put - Put the control handler
1280 *
1281 * @hdl: Put this control handler
1282 *
1283 * This function released the control handler previously obtained from'
1284 * v4l2_ctrl_request_hdl_find().
1285 */
1286static inline void v4l2_ctrl_request_hdl_put(struct v4l2_ctrl_handler *hdl)
1287{
1288	if (hdl)
1289		media_request_object_put(&hdl->req_obj);
1290}
1291
1292/**
1293 * v4l2_ctrl_request_ctrl_find() - Find a control with the given ID.
1294 *
1295 * @hdl: The control handler from the request.
1296 * @id: The ID of the control to find.
1297 *
1298 * This function returns a pointer to the control if this control is
1299 * part of the request or NULL otherwise.
1300 */
1301struct v4l2_ctrl *
1302v4l2_ctrl_request_hdl_ctrl_find(struct v4l2_ctrl_handler *hdl, u32 id);
1303
1304/* Helpers for ioctl_ops */
1305
1306/**
1307 * v4l2_queryctrl - Helper function to implement
1308 *	:ref:`VIDIOC_QUERYCTRL <vidioc_queryctrl>` ioctl
1309 *
1310 * @hdl: pointer to &struct v4l2_ctrl_handler
1311 * @qc: pointer to &struct v4l2_queryctrl
1312 *
1313 * If hdl == NULL then they will all return -EINVAL.
1314 */
1315int v4l2_queryctrl(struct v4l2_ctrl_handler *hdl, struct v4l2_queryctrl *qc);
1316
1317/**
1318 * v4l2_query_ext_ctrl - Helper function to implement
1319 *	 :ref:`VIDIOC_QUERY_EXT_CTRL <vidioc_queryctrl>` ioctl
1320 *
1321 * @hdl: pointer to &struct v4l2_ctrl_handler
1322 * @qc: pointer to &struct v4l2_query_ext_ctrl
1323 *
1324 * If hdl == NULL then they will all return -EINVAL.
1325 */
1326int v4l2_query_ext_ctrl(struct v4l2_ctrl_handler *hdl,
1327			struct v4l2_query_ext_ctrl *qc);
1328
1329/**
1330 * v4l2_querymenu - Helper function to implement
1331 *	:ref:`VIDIOC_QUERYMENU <vidioc_queryctrl>` ioctl
1332 *
1333 * @hdl: pointer to &struct v4l2_ctrl_handler
1334 * @qm: pointer to &struct v4l2_querymenu
1335 *
1336 * If hdl == NULL then they will all return -EINVAL.
1337 */
1338int v4l2_querymenu(struct v4l2_ctrl_handler *hdl, struct v4l2_querymenu *qm);
1339
1340/**
1341 * v4l2_g_ctrl - Helper function to implement
1342 *	:ref:`VIDIOC_G_CTRL <vidioc_g_ctrl>` ioctl
1343 *
1344 * @hdl: pointer to &struct v4l2_ctrl_handler
1345 * @ctrl: pointer to &struct v4l2_control
1346 *
1347 * If hdl == NULL then they will all return -EINVAL.
1348 */
1349int v4l2_g_ctrl(struct v4l2_ctrl_handler *hdl, struct v4l2_control *ctrl);
1350
1351/**
1352 * v4l2_s_ctrl - Helper function to implement
1353 *	:ref:`VIDIOC_S_CTRL <vidioc_g_ctrl>` ioctl
1354 *
1355 * @fh: pointer to &struct v4l2_fh
1356 * @hdl: pointer to &struct v4l2_ctrl_handler
1357 *
1358 * @ctrl: pointer to &struct v4l2_control
1359 *
1360 * If hdl == NULL then they will all return -EINVAL.
1361 */
1362int v4l2_s_ctrl(struct v4l2_fh *fh, struct v4l2_ctrl_handler *hdl,
1363		struct v4l2_control *ctrl);
1364
1365/**
1366 * v4l2_g_ext_ctrls - Helper function to implement
1367 *	:ref:`VIDIOC_G_EXT_CTRLS <vidioc_g_ext_ctrls>` ioctl
1368 *
1369 * @hdl: pointer to &struct v4l2_ctrl_handler
1370 * @vdev: pointer to &struct video_device
1371 * @mdev: pointer to &struct media_device
1372 * @c: pointer to &struct v4l2_ext_controls
1373 *
1374 * If hdl == NULL then they will all return -EINVAL.
1375 */
1376int v4l2_g_ext_ctrls(struct v4l2_ctrl_handler *hdl, struct video_device *vdev,
1377		     struct media_device *mdev, struct v4l2_ext_controls *c);
1378
1379/**
1380 * v4l2_try_ext_ctrls - Helper function to implement
1381 *	:ref:`VIDIOC_TRY_EXT_CTRLS <vidioc_g_ext_ctrls>` ioctl
1382 *
1383 * @hdl: pointer to &struct v4l2_ctrl_handler
1384 * @vdev: pointer to &struct video_device
1385 * @mdev: pointer to &struct media_device
1386 * @c: pointer to &struct v4l2_ext_controls
1387 *
1388 * If hdl == NULL then they will all return -EINVAL.
1389 */
1390int v4l2_try_ext_ctrls(struct v4l2_ctrl_handler *hdl,
1391		       struct video_device *vdev,
1392		       struct media_device *mdev,
1393		       struct v4l2_ext_controls *c);
1394
1395/**
1396 * v4l2_s_ext_ctrls - Helper function to implement
1397 *	:ref:`VIDIOC_S_EXT_CTRLS <vidioc_g_ext_ctrls>` ioctl
1398 *
1399 * @fh: pointer to &struct v4l2_fh
1400 * @hdl: pointer to &struct v4l2_ctrl_handler
1401 * @vdev: pointer to &struct video_device
1402 * @mdev: pointer to &struct media_device
1403 * @c: pointer to &struct v4l2_ext_controls
1404 *
1405 * If hdl == NULL then they will all return -EINVAL.
1406 */
1407int v4l2_s_ext_ctrls(struct v4l2_fh *fh, struct v4l2_ctrl_handler *hdl,
1408		     struct video_device *vdev,
1409		     struct media_device *mdev,
1410		     struct v4l2_ext_controls *c);
1411
1412/**
1413 * v4l2_ctrl_subdev_subscribe_event - Helper function to implement
1414 *	as a &struct v4l2_subdev_core_ops subscribe_event function
1415 *	that just subscribes control events.
1416 *
1417 * @sd: pointer to &struct v4l2_subdev
1418 * @fh: pointer to &struct v4l2_fh
1419 * @sub: pointer to &struct v4l2_event_subscription
1420 */
1421int v4l2_ctrl_subdev_subscribe_event(struct v4l2_subdev *sd, struct v4l2_fh *fh,
1422				     struct v4l2_event_subscription *sub);
1423
1424/**
1425 * v4l2_ctrl_subdev_log_status - Log all controls owned by subdev's control
1426 *	 handler.
1427 *
1428 * @sd: pointer to &struct v4l2_subdev
1429 */
1430int v4l2_ctrl_subdev_log_status(struct v4l2_subdev *sd);
1431
1432/**
1433 * v4l2_ctrl_new_fwnode_properties() - Register controls for the device
1434 *				       properties
1435 *
1436 * @hdl: pointer to &struct v4l2_ctrl_handler to register controls on
1437 * @ctrl_ops: pointer to &struct v4l2_ctrl_ops to register controls with
1438 * @p: pointer to &struct v4l2_fwnode_device_properties
1439 *
1440 * This function registers controls associated to device properties, using the
1441 * property values contained in @p parameter, if the property has been set to
1442 * a value.
1443 *
1444 * Currently the following v4l2 controls are parsed and registered:
1445 * - V4L2_CID_CAMERA_ORIENTATION
1446 * - V4L2_CID_CAMERA_SENSOR_ROTATION;
1447 *
1448 * Controls already registered by the caller with the @hdl control handler are
1449 * not overwritten. Callers should register the controls they want to handle
1450 * themselves before calling this function.
1451 *
1452 * Return: 0 on success, a negative error code on failure.
1453 */
1454int v4l2_ctrl_new_fwnode_properties(struct v4l2_ctrl_handler *hdl,
1455				    const struct v4l2_ctrl_ops *ctrl_ops,
1456				    const struct v4l2_fwnode_device_properties *p);
1457#endif