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/vp8-ctrls.h> 22 #include <media/hevc-ctrls.h> 23 24 /* forward references */ 25 struct file; 26 struct poll_table_struct; 27 struct v4l2_ctrl; 28 struct v4l2_ctrl_handler; 29 struct v4l2_ctrl_helper; 30 struct v4l2_fh; 31 struct v4l2_fwnode_device_properties; 32 struct v4l2_subdev; 33 struct v4l2_subscribed_event; 34 struct video_device; 35 36 /** 37 * union v4l2_ctrl_ptr - A pointer to a control value. 38 * @p_s32: Pointer to a 32-bit signed value. 39 * @p_s64: Pointer to a 64-bit signed value. 40 * @p_u8: Pointer to a 8-bit unsigned value. 41 * @p_u16: Pointer to a 16-bit unsigned value. 42 * @p_u32: Pointer to a 32-bit unsigned value. 43 * @p_char: Pointer to a string. 44 * @p_mpeg2_slice_params: Pointer to a MPEG2 slice parameters structure. 45 * @p_mpeg2_quantization: Pointer to a MPEG2 quantization data structure. 46 * @p_fwht_params: Pointer to a FWHT stateless parameters structure. 47 * @p_h264_sps: Pointer to a struct v4l2_ctrl_h264_sps. 48 * @p_h264_pps: Pointer to a struct v4l2_ctrl_h264_pps. 49 * @p_h264_scaling_matrix: Pointer to a struct v4l2_ctrl_h264_scaling_matrix. 50 * @p_h264_slice_params: Pointer to a struct v4l2_ctrl_h264_slice_params. 51 * @p_h264_decode_params: Pointer to a struct v4l2_ctrl_h264_decode_params. 52 * @p_h264_pred_weights: Pointer to a struct v4l2_ctrl_h264_pred_weights. 53 * @p_vp8_frame_header: Pointer to a VP8 frame header structure. 54 * @p_hevc_sps: Pointer to an HEVC sequence parameter set structure. 55 * @p_hevc_pps: Pointer to an HEVC picture parameter set structure. 56 * @p_hevc_slice_params: Pointer to an HEVC slice parameters structure. 57 * @p_area: Pointer to an area. 58 * @p: Pointer to a compound value. 59 * @p_const: Pointer to a constant compound value. 60 */ 61 union v4l2_ctrl_ptr { 62 s32 *p_s32; 63 s64 *p_s64; 64 u8 *p_u8; 65 u16 *p_u16; 66 u32 *p_u32; 67 char *p_char; 68 struct v4l2_ctrl_mpeg2_slice_params *p_mpeg2_slice_params; 69 struct v4l2_ctrl_mpeg2_quantization *p_mpeg2_quantization; 70 struct v4l2_ctrl_fwht_params *p_fwht_params; 71 struct v4l2_ctrl_h264_sps *p_h264_sps; 72 struct v4l2_ctrl_h264_pps *p_h264_pps; 73 struct v4l2_ctrl_h264_scaling_matrix *p_h264_scaling_matrix; 74 struct v4l2_ctrl_h264_slice_params *p_h264_slice_params; 75 struct v4l2_ctrl_h264_decode_params *p_h264_decode_params; 76 struct v4l2_ctrl_h264_pred_weights *p_h264_pred_weights; 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 */ 91 static 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 */ 112 struct 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 */ 128 struct 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 */ 149 typedef 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 */ 237 struct 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 */ 315 struct 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 */ 359 struct 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 */ 407 struct 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 */ 453 void 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 */ 478 int 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 */ 526 void 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 */ 533 static 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 */ 543 static 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 */ 559 int __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 */ 570 int 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 */ 584 void 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 */ 598 struct 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 */ 622 struct 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 */ 648 struct 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 */ 673 struct 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 */ 694 struct 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 */ 715 struct 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 727 typedef 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 */ 746 int 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 */ 762 bool 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 */ 771 void 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 */ 805 void 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 */ 819 struct 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 */ 833 void 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 */ 849 void __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 */ 866 static 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 */ 895 int __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 */ 917 static 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 */ 943 void 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 */ 954 const 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 */ 964 const 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 */ 975 const 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 */ 989 s32 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 */ 1003 int __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 */ 1017 static 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 */ 1040 s64 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 */ 1054 int __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 */ 1069 static 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 */ 1092 int __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 */ 1107 static 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 */ 1131 int __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 */ 1148 static 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. */ 1168 extern 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 */ 1179 void 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 */ 1190 void 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 */ 1202 int 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 */ 1214 int 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 */ 1237 int 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 */ 1254 void 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 */ 1275 struct 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 */ 1286 static 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_hdl_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 */ 1301 struct v4l2_ctrl * 1302 v4l2_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 */ 1315 int 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 */ 1326 int 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 */ 1338 int 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 */ 1349 int 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 */ 1362 int 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 */ 1376 int 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 */ 1390 int 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 */ 1407 int 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 */ 1421 int 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 */ 1430 int 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 */ 1454 int 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 1458