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