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