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