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