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