1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 V4L2 Controls 3 V4L2 Controls
4 ============= 4 =============
5 5
6 Introduction 6 Introduction
7 ------------ 7 ------------
8 8
9 The V4L2 control API seems simple enough, but 9 The V4L2 control API seems simple enough, but quickly becomes very hard to
10 implement correctly in drivers. But much of th 10 implement correctly in drivers. But much of the code needed to handle controls
11 is actually not driver specific and can be mov 11 is actually not driver specific and can be moved to the V4L core framework.
12 12
13 After all, the only part that a driver develop 13 After all, the only part that a driver developer is interested in is:
14 14
15 1) How do I add a control? 15 1) How do I add a control?
16 2) How do I set the control's value? (i.e. s_c 16 2) How do I set the control's value? (i.e. s_ctrl)
17 17
18 And occasionally: 18 And occasionally:
19 19
20 3) How do I get the control's value? (i.e. g_v 20 3) How do I get the control's value? (i.e. g_volatile_ctrl)
21 4) How do I validate the user's proposed contr 21 4) How do I validate the user's proposed control value? (i.e. try_ctrl)
22 22
23 All the rest is something that can be done cen 23 All the rest is something that can be done centrally.
24 24
25 The control framework was created in order to 25 The control framework was created in order to implement all the rules of the
26 V4L2 specification with respect to controls in 26 V4L2 specification with respect to controls in a central place. And to make
27 life as easy as possible for the driver develo 27 life as easy as possible for the driver developer.
28 28
29 Note that the control framework relies on the 29 Note that the control framework relies on the presence of a struct
30 :c:type:`v4l2_device` for V4L2 drivers and str 30 :c:type:`v4l2_device` for V4L2 drivers and struct v4l2_subdev for
31 sub-device drivers. 31 sub-device drivers.
32 32
33 33
34 Objects in the framework 34 Objects in the framework
35 ------------------------ 35 ------------------------
36 36
37 There are two main objects: 37 There are two main objects:
38 38
39 The :c:type:`v4l2_ctrl` object describes the c 39 The :c:type:`v4l2_ctrl` object describes the control properties and keeps
40 track of the control's value (both the current 40 track of the control's value (both the current value and the proposed new
41 value). 41 value).
42 42
43 :c:type:`v4l2_ctrl_handler` is the object that 43 :c:type:`v4l2_ctrl_handler` is the object that keeps track of controls. It
44 maintains a list of v4l2_ctrl objects that it 44 maintains a list of v4l2_ctrl objects that it owns and another list of
45 references to controls, possibly to controls o 45 references to controls, possibly to controls owned by other handlers.
46 46
47 47
48 Basic usage for V4L2 and sub-device drivers 48 Basic usage for V4L2 and sub-device drivers
49 ------------------------------------------- 49 -------------------------------------------
50 50
51 1) Prepare the driver: 51 1) Prepare the driver:
52 52
53 .. code-block:: c 53 .. code-block:: c
54 54
55 #include <media/v4l2-ctrls.h> 55 #include <media/v4l2-ctrls.h>
56 56
57 1.1) Add the handler to your driver's top-leve 57 1.1) Add the handler to your driver's top-level struct:
58 58
59 For V4L2 drivers: 59 For V4L2 drivers:
60 60
61 .. code-block:: c 61 .. code-block:: c
62 62
63 struct foo_dev { 63 struct foo_dev {
64 ... 64 ...
65 struct v4l2_device v4l2_dev; 65 struct v4l2_device v4l2_dev;
66 ... 66 ...
67 struct v4l2_ctrl_handler ctrl_ 67 struct v4l2_ctrl_handler ctrl_handler;
68 ... 68 ...
69 }; 69 };
70 70
71 For sub-device drivers: 71 For sub-device drivers:
72 72
73 .. code-block:: c 73 .. code-block:: c
74 74
75 struct foo_dev { 75 struct foo_dev {
76 ... 76 ...
77 struct v4l2_subdev sd; 77 struct v4l2_subdev sd;
78 ... 78 ...
79 struct v4l2_ctrl_handler ctrl_ 79 struct v4l2_ctrl_handler ctrl_handler;
80 ... 80 ...
81 }; 81 };
82 82
83 1.2) Initialize the handler: 83 1.2) Initialize the handler:
84 84
85 .. code-block:: c 85 .. code-block:: c
86 86
87 v4l2_ctrl_handler_init(&foo->ctrl_hand 87 v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls);
88 88
89 The second argument is a hint telling the func 89 The second argument is a hint telling the function how many controls this
90 handler is expected to handle. It will allocat 90 handler is expected to handle. It will allocate a hashtable based on this
91 information. It is a hint only. 91 information. It is a hint only.
92 92
93 1.3) Hook the control handler into the driver: 93 1.3) Hook the control handler into the driver:
94 94
95 For V4L2 drivers: 95 For V4L2 drivers:
96 96
97 .. code-block:: c 97 .. code-block:: c
98 98
99 foo->v4l2_dev.ctrl_handler = &foo->ctr 99 foo->v4l2_dev.ctrl_handler = &foo->ctrl_handler;
100 100
101 For sub-device drivers: 101 For sub-device drivers:
102 102
103 .. code-block:: c 103 .. code-block:: c
104 104
105 foo->sd.ctrl_handler = &foo->ctrl_hand 105 foo->sd.ctrl_handler = &foo->ctrl_handler;
106 106
107 1.4) Clean up the handler at the end: 107 1.4) Clean up the handler at the end:
108 108
109 .. code-block:: c 109 .. code-block:: c
110 110
111 v4l2_ctrl_handler_free(&foo->ctrl_hand 111 v4l2_ctrl_handler_free(&foo->ctrl_handler);
112 112
113 113
114 2) Add controls: 114 2) Add controls:
115 115
116 You add non-menu controls by calling :c:func:` 116 You add non-menu controls by calling :c:func:`v4l2_ctrl_new_std`:
117 117
118 .. code-block:: c 118 .. code-block:: c
119 119
120 struct v4l2_ctrl *v4l2_ctrl_new_std(st 120 struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl,
121 const struct v4l2_ctrl 121 const struct v4l2_ctrl_ops *ops,
122 u32 id, s32 min, s32 m 122 u32 id, s32 min, s32 max, u32 step, s32 def);
123 123
124 Menu and integer menu controls are added by ca 124 Menu and integer menu controls are added by calling
125 :c:func:`v4l2_ctrl_new_std_menu`: 125 :c:func:`v4l2_ctrl_new_std_menu`:
126 126
127 .. code-block:: c 127 .. code-block:: c
128 128
129 struct v4l2_ctrl *v4l2_ctrl_new_std_me 129 struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl,
130 const struct v4l2_ctrl 130 const struct v4l2_ctrl_ops *ops,
131 u32 id, s32 max, s32 s 131 u32 id, s32 max, s32 skip_mask, s32 def);
132 132
133 Menu controls with a driver specific menu are 133 Menu controls with a driver specific menu are added by calling
134 :c:func:`v4l2_ctrl_new_std_menu_items`: 134 :c:func:`v4l2_ctrl_new_std_menu_items`:
135 135
136 .. code-block:: c 136 .. code-block:: c
137 137
138 struct v4l2_ctrl *v4l2_ctrl_new_std_men 138 struct v4l2_ctrl *v4l2_ctrl_new_std_menu_items(
139 struct v4l2_ctrl_handle 139 struct v4l2_ctrl_handler *hdl,
140 const struct v4l2_ctrl_ 140 const struct v4l2_ctrl_ops *ops, u32 id, s32 max,
141 s32 skip_mask, s32 def, 141 s32 skip_mask, s32 def, const char * const *qmenu);
142 142
143 Standard compound controls can be added by cal 143 Standard compound controls can be added by calling
144 :c:func:`v4l2_ctrl_new_std_compound`: 144 :c:func:`v4l2_ctrl_new_std_compound`:
145 145
146 .. code-block:: c 146 .. code-block:: c
147 147
148 struct v4l2_ctrl *v4l2_ctrl_new_std_com 148 struct v4l2_ctrl *v4l2_ctrl_new_std_compound(struct v4l2_ctrl_handler *hdl,
149 const struct v4l2_ctrl_ 149 const struct v4l2_ctrl_ops *ops, u32 id,
150 const union v4l2_ctrl_p 150 const union v4l2_ctrl_ptr p_def);
151 151
152 Integer menu controls with a driver specific m 152 Integer menu controls with a driver specific menu can be added by calling
153 :c:func:`v4l2_ctrl_new_int_menu`: 153 :c:func:`v4l2_ctrl_new_int_menu`:
154 154
155 .. code-block:: c 155 .. code-block:: c
156 156
157 struct v4l2_ctrl *v4l2_ctrl_new_int_me 157 struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl,
158 const struct v4l2_ctrl 158 const struct v4l2_ctrl_ops *ops,
159 u32 id, s32 max, s32 d 159 u32 id, s32 max, s32 def, const s64 *qmenu_int);
160 160
161 These functions are typically called right aft 161 These functions are typically called right after the
162 :c:func:`v4l2_ctrl_handler_init`: 162 :c:func:`v4l2_ctrl_handler_init`:
163 163
164 .. code-block:: c 164 .. code-block:: c
165 165
166 static const s64 exp_bias_qmenu[] = { 166 static const s64 exp_bias_qmenu[] = {
167 -2, -1, 0, 1, 2 167 -2, -1, 0, 1, 2
168 }; 168 };
169 static const char * const test_pattern 169 static const char * const test_pattern[] = {
170 "Disabled", 170 "Disabled",
171 "Vertical Bars", 171 "Vertical Bars",
172 "Solid Black", 172 "Solid Black",
173 "Solid White", 173 "Solid White",
174 }; 174 };
175 175
176 v4l2_ctrl_handler_init(&foo->ctrl_hand 176 v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls);
177 v4l2_ctrl_new_std(&foo->ctrl_handler, 177 v4l2_ctrl_new_std(&foo->ctrl_handler, &foo_ctrl_ops,
178 V4L2_CID_BRIGHTNESS, 0 178 V4L2_CID_BRIGHTNESS, 0, 255, 1, 128);
179 v4l2_ctrl_new_std(&foo->ctrl_handler, 179 v4l2_ctrl_new_std(&foo->ctrl_handler, &foo_ctrl_ops,
180 V4L2_CID_CONTRAST, 0, 180 V4L2_CID_CONTRAST, 0, 255, 1, 128);
181 v4l2_ctrl_new_std_menu(&foo->ctrl_hand 181 v4l2_ctrl_new_std_menu(&foo->ctrl_handler, &foo_ctrl_ops,
182 V4L2_CID_POWER_LINE_FR 182 V4L2_CID_POWER_LINE_FREQUENCY,
183 V4L2_CID_POWER_LINE_FR 183 V4L2_CID_POWER_LINE_FREQUENCY_60HZ, 0,
184 V4L2_CID_POWER_LINE_FR 184 V4L2_CID_POWER_LINE_FREQUENCY_DISABLED);
185 v4l2_ctrl_new_int_menu(&foo->ctrl_hand 185 v4l2_ctrl_new_int_menu(&foo->ctrl_handler, &foo_ctrl_ops,
186 V4L2_CID_EXPOSURE_BIAS 186 V4L2_CID_EXPOSURE_BIAS,
187 ARRAY_SIZE(exp_bias_qm 187 ARRAY_SIZE(exp_bias_qmenu) - 1,
188 ARRAY_SIZE(exp_bias_qm 188 ARRAY_SIZE(exp_bias_qmenu) / 2 - 1,
189 exp_bias_qmenu); 189 exp_bias_qmenu);
190 v4l2_ctrl_new_std_menu_items(&foo->ctr 190 v4l2_ctrl_new_std_menu_items(&foo->ctrl_handler, &foo_ctrl_ops,
191 V4L2_CID_TEST_PATTERN, 191 V4L2_CID_TEST_PATTERN, ARRAY_SIZE(test_pattern) - 1, 0,
192 0, test_pattern); 192 0, test_pattern);
193 ... 193 ...
194 if (foo->ctrl_handler.error) { 194 if (foo->ctrl_handler.error) {
195 int err = foo->ctrl_handler.er 195 int err = foo->ctrl_handler.error;
196 196
197 v4l2_ctrl_handler_free(&foo->c 197 v4l2_ctrl_handler_free(&foo->ctrl_handler);
198 return err; 198 return err;
199 } 199 }
200 200
201 The :c:func:`v4l2_ctrl_new_std` function retur 201 The :c:func:`v4l2_ctrl_new_std` function returns the v4l2_ctrl pointer to
202 the new control, but if you do not need to acc 202 the new control, but if you do not need to access the pointer outside the
203 control ops, then there is no need to store it 203 control ops, then there is no need to store it.
204 204
205 The :c:func:`v4l2_ctrl_new_std` function will 205 The :c:func:`v4l2_ctrl_new_std` function will fill in most fields based on
206 the control ID except for the min, max, step a 206 the control ID except for the min, max, step and default values. These are
207 passed in the last four arguments. These value 207 passed in the last four arguments. These values are driver specific while
208 control attributes like type, name, flags are 208 control attributes like type, name, flags are all global. The control's
209 current value will be set to the default value 209 current value will be set to the default value.
210 210
211 The :c:func:`v4l2_ctrl_new_std_menu` function 211 The :c:func:`v4l2_ctrl_new_std_menu` function is very similar but it is
212 used for menu controls. There is no min argume 212 used for menu controls. There is no min argument since that is always 0 for
213 menu controls, and instead of a step there is 213 menu controls, and instead of a step there is a skip_mask argument: if bit
214 X is 1, then menu item X is skipped. 214 X is 1, then menu item X is skipped.
215 215
216 The :c:func:`v4l2_ctrl_new_int_menu` function 216 The :c:func:`v4l2_ctrl_new_int_menu` function creates a new standard
217 integer menu control with driver-specific item 217 integer menu control with driver-specific items in the menu. It differs
218 from v4l2_ctrl_new_std_menu in that it doesn't 218 from v4l2_ctrl_new_std_menu in that it doesn't have the mask argument and
219 takes as the last argument an array of signed 219 takes as the last argument an array of signed 64-bit integers that form an
220 exact menu item list. 220 exact menu item list.
221 221
222 The :c:func:`v4l2_ctrl_new_std_menu_items` fun 222 The :c:func:`v4l2_ctrl_new_std_menu_items` function is very similar to
223 v4l2_ctrl_new_std_menu but takes an extra para 223 v4l2_ctrl_new_std_menu but takes an extra parameter qmenu, which is the
224 driver specific menu for an otherwise standard 224 driver specific menu for an otherwise standard menu control. A good example
225 for this control is the test pattern control f 225 for this control is the test pattern control for capture/display/sensors
226 devices that have the capability to generate t 226 devices that have the capability to generate test patterns. These test
227 patterns are hardware specific, so the content 227 patterns are hardware specific, so the contents of the menu will vary from
228 device to device. 228 device to device.
229 229
230 Note that if something fails, the function wil 230 Note that if something fails, the function will return NULL or an error and
231 set ctrl_handler->error to the error code. If 231 set ctrl_handler->error to the error code. If ctrl_handler->error was already
232 set, then it will just return and do nothing. 232 set, then it will just return and do nothing. This is also true for
233 v4l2_ctrl_handler_init if it cannot allocate t 233 v4l2_ctrl_handler_init if it cannot allocate the internal data structure.
234 234
235 This makes it easy to init the handler and jus 235 This makes it easy to init the handler and just add all controls and only check
236 the error code at the end. Saves a lot of repe 236 the error code at the end. Saves a lot of repetitive error checking.
237 237
238 It is recommended to add controls in ascending 238 It is recommended to add controls in ascending control ID order: it will be
239 a bit faster that way. 239 a bit faster that way.
240 240
241 3) Optionally force initial control setup: 241 3) Optionally force initial control setup:
242 242
243 .. code-block:: c 243 .. code-block:: c
244 244
245 v4l2_ctrl_handler_setup(&foo->ctrl_han 245 v4l2_ctrl_handler_setup(&foo->ctrl_handler);
246 246
247 This will call s_ctrl for all controls uncondi 247 This will call s_ctrl for all controls unconditionally. Effectively this
248 initializes the hardware to the default contro 248 initializes the hardware to the default control values. It is recommended
249 that you do this as this ensures that both the 249 that you do this as this ensures that both the internal data structures and
250 the hardware are in sync. 250 the hardware are in sync.
251 251
252 4) Finally: implement the :c:type:`v4l2_ctrl_o 252 4) Finally: implement the :c:type:`v4l2_ctrl_ops`
253 253
254 .. code-block:: c 254 .. code-block:: c
255 255
256 static const struct v4l2_ctrl_ops foo_ 256 static const struct v4l2_ctrl_ops foo_ctrl_ops = {
257 .s_ctrl = foo_s_ctrl, 257 .s_ctrl = foo_s_ctrl,
258 }; 258 };
259 259
260 Usually all you need is s_ctrl: 260 Usually all you need is s_ctrl:
261 261
262 .. code-block:: c 262 .. code-block:: c
263 263
264 static int foo_s_ctrl(struct v4l2_ctrl 264 static int foo_s_ctrl(struct v4l2_ctrl *ctrl)
265 { 265 {
266 struct foo *state = container_ 266 struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler);
267 267
268 switch (ctrl->id) { 268 switch (ctrl->id) {
269 case V4L2_CID_BRIGHTNESS: 269 case V4L2_CID_BRIGHTNESS:
270 write_reg(0x123, ctrl- 270 write_reg(0x123, ctrl->val);
271 break; 271 break;
272 case V4L2_CID_CONTRAST: 272 case V4L2_CID_CONTRAST:
273 write_reg(0x456, ctrl- 273 write_reg(0x456, ctrl->val);
274 break; 274 break;
275 } 275 }
276 return 0; 276 return 0;
277 } 277 }
278 278
279 The control ops are called with the v4l2_ctrl 279 The control ops are called with the v4l2_ctrl pointer as argument.
280 The new control value has already been validat 280 The new control value has already been validated, so all you need to do is
281 to actually update the hardware registers. 281 to actually update the hardware registers.
282 282
283 You're done! And this is sufficient for most o 283 You're done! And this is sufficient for most of the drivers we have. No need
284 to do any validation of control values, or imp 284 to do any validation of control values, or implement QUERYCTRL, QUERY_EXT_CTRL
285 and QUERYMENU. And G/S_CTRL as well as G/TRY/S 285 and QUERYMENU. And G/S_CTRL as well as G/TRY/S_EXT_CTRLS are automatically supported.
286 286
287 287
288 .. note:: 288 .. note::
289 289
290 The remainder sections deal with more advan 290 The remainder sections deal with more advanced controls topics and scenarios.
291 In practice the basic usage as described ab 291 In practice the basic usage as described above is sufficient for most drivers.
292 292
293 293
294 Inheriting Sub-device Controls 294 Inheriting Sub-device Controls
295 ------------------------------ 295 ------------------------------
296 296
297 When a sub-device is registered with a V4L2 dr 297 When a sub-device is registered with a V4L2 driver by calling
298 v4l2_device_register_subdev() and the ctrl_han 298 v4l2_device_register_subdev() and the ctrl_handler fields of both v4l2_subdev
299 and v4l2_device are set, then the controls of 299 and v4l2_device are set, then the controls of the subdev will become
300 automatically available in the V4L2 driver as 300 automatically available in the V4L2 driver as well. If the subdev driver
301 contains controls that already exist in the V4 301 contains controls that already exist in the V4L2 driver, then those will be
302 skipped (so a V4L2 driver can always override 302 skipped (so a V4L2 driver can always override a subdev control).
303 303
304 What happens here is that v4l2_device_register 304 What happens here is that v4l2_device_register_subdev() calls
305 v4l2_ctrl_add_handler() adding the controls of 305 v4l2_ctrl_add_handler() adding the controls of the subdev to the controls
306 of v4l2_device. 306 of v4l2_device.
307 307
308 308
309 Accessing Control Values 309 Accessing Control Values
310 ------------------------ 310 ------------------------
311 311
312 The following union is used inside the control 312 The following union is used inside the control framework to access control
313 values: 313 values:
314 314
315 .. code-block:: c 315 .. code-block:: c
316 316
317 union v4l2_ctrl_ptr { 317 union v4l2_ctrl_ptr {
318 s32 *p_s32; 318 s32 *p_s32;
319 s64 *p_s64; 319 s64 *p_s64;
320 char *p_char; 320 char *p_char;
321 void *p; 321 void *p;
322 }; 322 };
323 323
324 The v4l2_ctrl struct contains these fields tha 324 The v4l2_ctrl struct contains these fields that can be used to access both
325 current and new values: 325 current and new values:
326 326
327 .. code-block:: c 327 .. code-block:: c
328 328
329 s32 val; 329 s32 val;
330 struct { 330 struct {
331 s32 val; 331 s32 val;
332 } cur; 332 } cur;
333 333
334 334
335 union v4l2_ctrl_ptr p_new; 335 union v4l2_ctrl_ptr p_new;
336 union v4l2_ctrl_ptr p_cur; 336 union v4l2_ctrl_ptr p_cur;
337 337
338 If the control has a simple s32 type, then: 338 If the control has a simple s32 type, then:
339 339
340 .. code-block:: c 340 .. code-block:: c
341 341
342 &ctrl->val == ctrl->p_new.p_s32 342 &ctrl->val == ctrl->p_new.p_s32
343 &ctrl->cur.val == ctrl->p_cur.p_s32 343 &ctrl->cur.val == ctrl->p_cur.p_s32
344 344
345 For all other types use ctrl->p_cur.p<somethin 345 For all other types use ctrl->p_cur.p<something>. Basically the val
346 and cur.val fields can be considered an alias 346 and cur.val fields can be considered an alias since these are used so often.
347 347
348 Within the control ops you can freely use thes 348 Within the control ops you can freely use these. The val and cur.val speak for
349 themselves. The p_char pointers point to chara 349 themselves. The p_char pointers point to character buffers of length
350 ctrl->maximum + 1, and are always 0-terminated 350 ctrl->maximum + 1, and are always 0-terminated.
351 351
352 Unless the control is marked volatile the p_cu 352 Unless the control is marked volatile the p_cur field points to the
353 current cached control value. When you create 353 current cached control value. When you create a new control this value is made
354 identical to the default value. After calling 354 identical to the default value. After calling v4l2_ctrl_handler_setup() this
355 value is passed to the hardware. It is general 355 value is passed to the hardware. It is generally a good idea to call this
356 function. 356 function.
357 357
358 Whenever a new value is set that new value is 358 Whenever a new value is set that new value is automatically cached. This means
359 that most drivers do not need to implement the 359 that most drivers do not need to implement the g_volatile_ctrl() op. The
360 exception is for controls that return a volati 360 exception is for controls that return a volatile register such as a signal
361 strength read-out that changes continuously. I 361 strength read-out that changes continuously. In that case you will need to
362 implement g_volatile_ctrl like this: 362 implement g_volatile_ctrl like this:
363 363
364 .. code-block:: c 364 .. code-block:: c
365 365
366 static int foo_g_volatile_ctrl(struct 366 static int foo_g_volatile_ctrl(struct v4l2_ctrl *ctrl)
367 { 367 {
368 switch (ctrl->id) { 368 switch (ctrl->id) {
369 case V4L2_CID_BRIGHTNESS: 369 case V4L2_CID_BRIGHTNESS:
370 ctrl->val = read_reg(0 370 ctrl->val = read_reg(0x123);
371 break; 371 break;
372 } 372 }
373 } 373 }
374 374
375 Note that you use the 'new value' union as wel 375 Note that you use the 'new value' union as well in g_volatile_ctrl. In general
376 controls that need to implement g_volatile_ctr 376 controls that need to implement g_volatile_ctrl are read-only controls. If they
377 are not, a V4L2_EVENT_CTRL_CH_VALUE will not b 377 are not, a V4L2_EVENT_CTRL_CH_VALUE will not be generated when the control
378 changes. 378 changes.
379 379
380 To mark a control as volatile you have to set 380 To mark a control as volatile you have to set V4L2_CTRL_FLAG_VOLATILE:
381 381
382 .. code-block:: c 382 .. code-block:: c
383 383
384 ctrl = v4l2_ctrl_new_std(&sd->ctrl_han 384 ctrl = v4l2_ctrl_new_std(&sd->ctrl_handler, ...);
385 if (ctrl) 385 if (ctrl)
386 ctrl->flags |= V4L2_CTRL_FLAG_ 386 ctrl->flags |= V4L2_CTRL_FLAG_VOLATILE;
387 387
388 For try/s_ctrl the new values (i.e. as passed 388 For try/s_ctrl the new values (i.e. as passed by the user) are filled in and
389 you can modify them in try_ctrl or set them in 389 you can modify them in try_ctrl or set them in s_ctrl. The 'cur' union
390 contains the current value, which you can use 390 contains the current value, which you can use (but not change!) as well.
391 391
392 If s_ctrl returns 0 (OK), then the control fra 392 If s_ctrl returns 0 (OK), then the control framework will copy the new final
393 values to the 'cur' union. 393 values to the 'cur' union.
394 394
395 While in g_volatile/s/try_ctrl you can access 395 While in g_volatile/s/try_ctrl you can access the value of all controls owned
396 by the same handler since the handler's lock i 396 by the same handler since the handler's lock is held. If you need to access
397 the value of controls owned by other handlers, 397 the value of controls owned by other handlers, then you have to be very careful
398 not to introduce deadlocks. 398 not to introduce deadlocks.
399 399
400 Outside of the control ops you have to go thro 400 Outside of the control ops you have to go through to helper functions to get
401 or set a single control value safely in your d 401 or set a single control value safely in your driver:
402 402
403 .. code-block:: c 403 .. code-block:: c
404 404
405 s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl 405 s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl);
406 int v4l2_ctrl_s_ctrl(struct v4l2_ctrl 406 int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val);
407 407
408 These functions go through the control framewo 408 These functions go through the control framework just as VIDIOC_G/S_CTRL ioctls
409 do. Don't use these inside the control ops g_v 409 do. Don't use these inside the control ops g_volatile/s/try_ctrl, though, that
410 will result in a deadlock since these helpers 410 will result in a deadlock since these helpers lock the handler as well.
411 411
412 You can also take the handler lock yourself: 412 You can also take the handler lock yourself:
413 413
414 .. code-block:: c 414 .. code-block:: c
415 415
416 mutex_lock(&state->ctrl_handler.lock); 416 mutex_lock(&state->ctrl_handler.lock);
417 pr_info("String value is '%s'\n", ctrl 417 pr_info("String value is '%s'\n", ctrl1->p_cur.p_char);
418 pr_info("Integer value is '%s'\n", ctr 418 pr_info("Integer value is '%s'\n", ctrl2->cur.val);
419 mutex_unlock(&state->ctrl_handler.lock 419 mutex_unlock(&state->ctrl_handler.lock);
420 420
421 421
422 Menu Controls 422 Menu Controls
423 ------------- 423 -------------
424 424
425 The v4l2_ctrl struct contains this union: 425 The v4l2_ctrl struct contains this union:
426 426
427 .. code-block:: c 427 .. code-block:: c
428 428
429 union { 429 union {
430 u32 step; 430 u32 step;
431 u32 menu_skip_mask; 431 u32 menu_skip_mask;
432 }; 432 };
433 433
434 For menu controls menu_skip_mask is used. What 434 For menu controls menu_skip_mask is used. What it does is that it allows you
435 to easily exclude certain menu items. This is 435 to easily exclude certain menu items. This is used in the VIDIOC_QUERYMENU
436 implementation where you can return -EINVAL if 436 implementation where you can return -EINVAL if a certain menu item is not
437 present. Note that VIDIOC_QUERYCTRL always ret 437 present. Note that VIDIOC_QUERYCTRL always returns a step value of 1 for
438 menu controls. 438 menu controls.
439 439
440 A good example is the MPEG Audio Layer II Bitr 440 A good example is the MPEG Audio Layer II Bitrate menu control where the
441 menu is a list of standardized possible bitrat 441 menu is a list of standardized possible bitrates. But in practice hardware
442 implementations will only support a subset of 442 implementations will only support a subset of those. By setting the skip
443 mask you can tell the framework which menu ite 443 mask you can tell the framework which menu items should be skipped. Setting
444 it to 0 means that all menu items are supporte 444 it to 0 means that all menu items are supported.
445 445
446 You set this mask either through the v4l2_ctrl 446 You set this mask either through the v4l2_ctrl_config struct for a custom
447 control, or by calling v4l2_ctrl_new_std_menu( 447 control, or by calling v4l2_ctrl_new_std_menu().
448 448
449 449
450 Custom Controls 450 Custom Controls
451 --------------- 451 ---------------
452 452
453 Driver specific controls can be created using 453 Driver specific controls can be created using v4l2_ctrl_new_custom():
454 454
455 .. code-block:: c 455 .. code-block:: c
456 456
457 static const struct v4l2_ctrl_config c 457 static const struct v4l2_ctrl_config ctrl_filter = {
458 .ops = &ctrl_custom_ops, 458 .ops = &ctrl_custom_ops,
459 .id = V4L2_CID_MPEG_CX2341X_VI 459 .id = V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER,
460 .name = "Spatial Filter", 460 .name = "Spatial Filter",
461 .type = V4L2_CTRL_TYPE_INTEGER 461 .type = V4L2_CTRL_TYPE_INTEGER,
462 .flags = V4L2_CTRL_FLAG_SLIDER 462 .flags = V4L2_CTRL_FLAG_SLIDER,
463 .max = 15, 463 .max = 15,
464 .step = 1, 464 .step = 1,
465 }; 465 };
466 466
467 ctrl = v4l2_ctrl_new_custom(&foo->ctrl 467 ctrl = v4l2_ctrl_new_custom(&foo->ctrl_handler, &ctrl_filter, NULL);
468 468
469 The last argument is the priv pointer which ca 469 The last argument is the priv pointer which can be set to driver-specific
470 private data. 470 private data.
471 471
472 The v4l2_ctrl_config struct also has a field t 472 The v4l2_ctrl_config struct also has a field to set the is_private flag.
473 473
474 If the name field is not set, then the framewo 474 If the name field is not set, then the framework will assume this is a standard
475 control and will fill in the name, type and fl 475 control and will fill in the name, type and flags fields accordingly.
476 476
477 477
478 Active and Grabbed Controls 478 Active and Grabbed Controls
479 --------------------------- 479 ---------------------------
480 480
481 If you get more complex relationships between 481 If you get more complex relationships between controls, then you may have to
482 activate and deactivate controls. For example, 482 activate and deactivate controls. For example, if the Chroma AGC control is
483 on, then the Chroma Gain control is inactive. 483 on, then the Chroma Gain control is inactive. That is, you may set it, but
484 the value will not be used by the hardware as 484 the value will not be used by the hardware as long as the automatic gain
485 control is on. Typically user interfaces can d 485 control is on. Typically user interfaces can disable such input fields.
486 486
487 You can set the 'active' status using v4l2_ctr 487 You can set the 'active' status using v4l2_ctrl_activate(). By default all
488 controls are active. Note that the framework d 488 controls are active. Note that the framework does not check for this flag.
489 It is meant purely for GUIs. The function is t 489 It is meant purely for GUIs. The function is typically called from within
490 s_ctrl. 490 s_ctrl.
491 491
492 The other flag is the 'grabbed' flag. A grabbe 492 The other flag is the 'grabbed' flag. A grabbed control means that you cannot
493 change it because it is in use by some resourc 493 change it because it is in use by some resource. Typical examples are MPEG
494 bitrate controls that cannot be changed while 494 bitrate controls that cannot be changed while capturing is in progress.
495 495
496 If a control is set to 'grabbed' using v4l2_ct 496 If a control is set to 'grabbed' using v4l2_ctrl_grab(), then the framework
497 will return -EBUSY if an attempt is made to se 497 will return -EBUSY if an attempt is made to set this control. The
498 v4l2_ctrl_grab() function is typically called 498 v4l2_ctrl_grab() function is typically called from the driver when it
499 starts or stops streaming. 499 starts or stops streaming.
500 500
501 501
502 Control Clusters 502 Control Clusters
503 ---------------- 503 ----------------
504 504
505 By default all controls are independent from t 505 By default all controls are independent from the others. But in more
506 complex scenarios you can get dependencies fro 506 complex scenarios you can get dependencies from one control to another.
507 In that case you need to 'cluster' them: 507 In that case you need to 'cluster' them:
508 508
509 .. code-block:: c 509 .. code-block:: c
510 510
511 struct foo { 511 struct foo {
512 struct v4l2_ctrl_handler ctrl_ 512 struct v4l2_ctrl_handler ctrl_handler;
513 #define AUDIO_CL_VOLUME (0) 513 #define AUDIO_CL_VOLUME (0)
514 #define AUDIO_CL_MUTE (1) 514 #define AUDIO_CL_MUTE (1)
515 struct v4l2_ctrl *audio_cluste 515 struct v4l2_ctrl *audio_cluster[2];
516 ... 516 ...
517 }; 517 };
518 518
519 state->audio_cluster[AUDIO_CL_VOLUME] 519 state->audio_cluster[AUDIO_CL_VOLUME] =
520 v4l2_ctrl_new_std(&state->ctrl 520 v4l2_ctrl_new_std(&state->ctrl_handler, ...);
521 state->audio_cluster[AUDIO_CL_MUTE] = 521 state->audio_cluster[AUDIO_CL_MUTE] =
522 v4l2_ctrl_new_std(&state->ctrl 522 v4l2_ctrl_new_std(&state->ctrl_handler, ...);
523 v4l2_ctrl_cluster(ARRAY_SIZE(state->au 523 v4l2_ctrl_cluster(ARRAY_SIZE(state->audio_cluster), state->audio_cluster);
524 524
525 From now on whenever one or more of the contro 525 From now on whenever one or more of the controls belonging to the same
526 cluster is set (or 'gotten', or 'tried'), only 526 cluster is set (or 'gotten', or 'tried'), only the control ops of the first
527 control ('volume' in this example) is called. 527 control ('volume' in this example) is called. You effectively create a new
528 composite control. Similar to how a 'struct' w 528 composite control. Similar to how a 'struct' works in C.
529 529
530 So when s_ctrl is called with V4L2_CID_AUDIO_V 530 So when s_ctrl is called with V4L2_CID_AUDIO_VOLUME as argument, you should set
531 all two controls belonging to the audio_cluste 531 all two controls belonging to the audio_cluster:
532 532
533 .. code-block:: c 533 .. code-block:: c
534 534
535 static int foo_s_ctrl(struct v4l2_ctrl 535 static int foo_s_ctrl(struct v4l2_ctrl *ctrl)
536 { 536 {
537 struct foo *state = container_ 537 struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler);
538 538
539 switch (ctrl->id) { 539 switch (ctrl->id) {
540 case V4L2_CID_AUDIO_VOLUME: { 540 case V4L2_CID_AUDIO_VOLUME: {
541 struct v4l2_ctrl *mute 541 struct v4l2_ctrl *mute = ctrl->cluster[AUDIO_CL_MUTE];
542 542
543 write_reg(0x123, mute- 543 write_reg(0x123, mute->val ? 0 : ctrl->val);
544 break; 544 break;
545 } 545 }
546 case V4L2_CID_CONTRAST: 546 case V4L2_CID_CONTRAST:
547 write_reg(0x456, ctrl- 547 write_reg(0x456, ctrl->val);
548 break; 548 break;
549 } 549 }
550 return 0; 550 return 0;
551 } 551 }
552 552
553 In the example above the following are equival 553 In the example above the following are equivalent for the VOLUME case:
554 554
555 .. code-block:: c 555 .. code-block:: c
556 556
557 ctrl == ctrl->cluster[AUDIO_CL_VOLUME] 557 ctrl == ctrl->cluster[AUDIO_CL_VOLUME] == state->audio_cluster[AUDIO_CL_VOLUME]
558 ctrl->cluster[AUDIO_CL_MUTE] == state- 558 ctrl->cluster[AUDIO_CL_MUTE] == state->audio_cluster[AUDIO_CL_MUTE]
559 559
560 In practice using cluster arrays like this bec 560 In practice using cluster arrays like this becomes very tiresome. So instead
561 the following equivalent method is used: 561 the following equivalent method is used:
562 562
563 .. code-block:: c 563 .. code-block:: c
564 564
565 struct { 565 struct {
566 /* audio cluster */ 566 /* audio cluster */
567 struct v4l2_ctrl *volume; 567 struct v4l2_ctrl *volume;
568 struct v4l2_ctrl *mute; 568 struct v4l2_ctrl *mute;
569 }; 569 };
570 570
571 The anonymous struct is used to clearly 'clust 571 The anonymous struct is used to clearly 'cluster' these two control pointers,
572 but it serves no other purpose. The effect is 572 but it serves no other purpose. The effect is the same as creating an
573 array with two control pointers. So you can ju 573 array with two control pointers. So you can just do:
574 574
575 .. code-block:: c 575 .. code-block:: c
576 576
577 state->volume = v4l2_ctrl_new_std(&sta 577 state->volume = v4l2_ctrl_new_std(&state->ctrl_handler, ...);
578 state->mute = v4l2_ctrl_new_std(&state 578 state->mute = v4l2_ctrl_new_std(&state->ctrl_handler, ...);
579 v4l2_ctrl_cluster(2, &state->volume); 579 v4l2_ctrl_cluster(2, &state->volume);
580 580
581 And in foo_s_ctrl you can use these pointers d 581 And in foo_s_ctrl you can use these pointers directly: state->mute->val.
582 582
583 Note that controls in a cluster may be NULL. F 583 Note that controls in a cluster may be NULL. For example, if for some
584 reason mute was never added (because the hardw 584 reason mute was never added (because the hardware doesn't support that
585 particular feature), then mute will be NULL. S 585 particular feature), then mute will be NULL. So in that case we have a
586 cluster of 2 controls, of which only 1 is actu 586 cluster of 2 controls, of which only 1 is actually instantiated. The
587 only restriction is that the first control of 587 only restriction is that the first control of the cluster must always be
588 present, since that is the 'master' control of 588 present, since that is the 'master' control of the cluster. The master
589 control is the one that identifies the cluster 589 control is the one that identifies the cluster and that provides the
590 pointer to the v4l2_ctrl_ops struct that is us 590 pointer to the v4l2_ctrl_ops struct that is used for that cluster.
591 591
592 Obviously, all controls in the cluster array m 592 Obviously, all controls in the cluster array must be initialized to either
593 a valid control or to NULL. 593 a valid control or to NULL.
594 594
595 In rare cases you might want to know which con 595 In rare cases you might want to know which controls of a cluster actually
596 were set explicitly by the user. For this you 596 were set explicitly by the user. For this you can check the 'is_new' flag of
597 each control. For example, in the case of a vo 597 each control. For example, in the case of a volume/mute cluster the 'is_new'
598 flag of the mute control would be set if the u 598 flag of the mute control would be set if the user called VIDIOC_S_CTRL for
599 mute only. If the user would call VIDIOC_S_EXT 599 mute only. If the user would call VIDIOC_S_EXT_CTRLS for both mute and volume
600 controls, then the 'is_new' flag would be 1 fo 600 controls, then the 'is_new' flag would be 1 for both controls.
601 601
602 The 'is_new' flag is always 1 when called from 602 The 'is_new' flag is always 1 when called from v4l2_ctrl_handler_setup().
603 603
604 604
605 Handling autogain/gain-type Controls with Auto 605 Handling autogain/gain-type Controls with Auto Clusters
606 ---------------------------------------------- 606 -------------------------------------------------------
607 607
608 A common type of control cluster is one that h 608 A common type of control cluster is one that handles 'auto-foo/foo'-type
609 controls. Typical examples are autogain/gain, 609 controls. Typical examples are autogain/gain, autoexposure/exposure,
610 autowhitebalance/red balance/blue balance. In 610 autowhitebalance/red balance/blue balance. In all cases you have one control
611 that determines whether another control is han 611 that determines whether another control is handled automatically by the hardware,
612 or whether it is under manual control from the 612 or whether it is under manual control from the user.
613 613
614 If the cluster is in automatic mode, then the 614 If the cluster is in automatic mode, then the manual controls should be
615 marked inactive and volatile. When the volatil 615 marked inactive and volatile. When the volatile controls are read the
616 g_volatile_ctrl operation should return the va 616 g_volatile_ctrl operation should return the value that the hardware's automatic
617 mode set up automatically. 617 mode set up automatically.
618 618
619 If the cluster is put in manual mode, then the 619 If the cluster is put in manual mode, then the manual controls should become
620 active again and the volatile flag is cleared 620 active again and the volatile flag is cleared (so g_volatile_ctrl is no longer
621 called while in manual mode). In addition just 621 called while in manual mode). In addition just before switching to manual mode
622 the current values as determined by the auto m 622 the current values as determined by the auto mode are copied as the new manual
623 values. 623 values.
624 624
625 Finally the V4L2_CTRL_FLAG_UPDATE should be se 625 Finally the V4L2_CTRL_FLAG_UPDATE should be set for the auto control since
626 changing that control affects the control flag 626 changing that control affects the control flags of the manual controls.
627 627
628 In order to simplify this a special variation 628 In order to simplify this a special variation of v4l2_ctrl_cluster was
629 introduced: 629 introduced:
630 630
631 .. code-block:: c 631 .. code-block:: c
632 632
633 void v4l2_ctrl_auto_cluster(unsigned n 633 void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls,
634 u8 manual_ 634 u8 manual_val, bool set_volatile);
635 635
636 The first two arguments are identical to v4l2_ 636 The first two arguments are identical to v4l2_ctrl_cluster. The third argument
637 tells the framework which value switches the c 637 tells the framework which value switches the cluster into manual mode. The
638 last argument will optionally set V4L2_CTRL_FL 638 last argument will optionally set V4L2_CTRL_FLAG_VOLATILE for the non-auto controls.
639 If it is false, then the manual controls are n 639 If it is false, then the manual controls are never volatile. You would typically
640 use that if the hardware does not give you the 640 use that if the hardware does not give you the option to read back to values as
641 determined by the auto mode (e.g. if autogain 641 determined by the auto mode (e.g. if autogain is on, the hardware doesn't allow
642 you to obtain the current gain value). 642 you to obtain the current gain value).
643 643
644 The first control of the cluster is assumed to 644 The first control of the cluster is assumed to be the 'auto' control.
645 645
646 Using this function will ensure that you don't 646 Using this function will ensure that you don't need to handle all the complex
647 flag and volatile handling. 647 flag and volatile handling.
648 648
649 649
650 VIDIOC_LOG_STATUS Support 650 VIDIOC_LOG_STATUS Support
651 ------------------------- 651 -------------------------
652 652
653 This ioctl allow you to dump the current statu 653 This ioctl allow you to dump the current status of a driver to the kernel log.
654 The v4l2_ctrl_handler_log_status(ctrl_handler, 654 The v4l2_ctrl_handler_log_status(ctrl_handler, prefix) can be used to dump the
655 value of the controls owned by the given handl 655 value of the controls owned by the given handler to the log. You can supply a
656 prefix as well. If the prefix didn't end with 656 prefix as well. If the prefix didn't end with a space, then ': ' will be added
657 for you. 657 for you.
658 658
659 659
660 Different Handlers for Different Video Nodes 660 Different Handlers for Different Video Nodes
661 -------------------------------------------- 661 --------------------------------------------
662 662
663 Usually the V4L2 driver has just one control h 663 Usually the V4L2 driver has just one control handler that is global for
664 all video nodes. But you can also specify diff 664 all video nodes. But you can also specify different control handlers for
665 different video nodes. You can do that by manu 665 different video nodes. You can do that by manually setting the ctrl_handler
666 field of struct video_device. 666 field of struct video_device.
667 667
668 That is no problem if there are no subdevs inv 668 That is no problem if there are no subdevs involved but if there are, then
669 you need to block the automatic merging of sub 669 you need to block the automatic merging of subdev controls to the global
670 control handler. You do that by simply setting 670 control handler. You do that by simply setting the ctrl_handler field in
671 struct v4l2_device to NULL. Now v4l2_device_re 671 struct v4l2_device to NULL. Now v4l2_device_register_subdev() will no longer
672 merge subdev controls. 672 merge subdev controls.
673 673
674 After each subdev was added, you will then hav 674 After each subdev was added, you will then have to call v4l2_ctrl_add_handler
675 manually to add the subdev's control handler ( 675 manually to add the subdev's control handler (sd->ctrl_handler) to the desired
676 control handler. This control handler may be s 676 control handler. This control handler may be specific to the video_device or
677 for a subset of video_device's. For example: t 677 for a subset of video_device's. For example: the radio device nodes only have
678 audio controls, while the video and vbi device 678 audio controls, while the video and vbi device nodes share the same control
679 handler for the audio and video controls. 679 handler for the audio and video controls.
680 680
681 If you want to have one handler (e.g. for a ra 681 If you want to have one handler (e.g. for a radio device node) have a subset
682 of another handler (e.g. for a video device no 682 of another handler (e.g. for a video device node), then you should first add
683 the controls to the first handler, add the oth 683 the controls to the first handler, add the other controls to the second
684 handler and finally add the first handler to t 684 handler and finally add the first handler to the second. For example:
685 685
686 .. code-block:: c 686 .. code-block:: c
687 687
688 v4l2_ctrl_new_std(&radio_ctrl_handler, 688 v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_VOLUME, ...);
689 v4l2_ctrl_new_std(&radio_ctrl_handler, 689 v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...);
690 v4l2_ctrl_new_std(&video_ctrl_handler, 690 v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...);
691 v4l2_ctrl_new_std(&video_ctrl_handler, 691 v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_CONTRAST, ...);
692 v4l2_ctrl_add_handler(&video_ctrl_hand 692 v4l2_ctrl_add_handler(&video_ctrl_handler, &radio_ctrl_handler, NULL);
693 693
694 The last argument to v4l2_ctrl_add_handler() i 694 The last argument to v4l2_ctrl_add_handler() is a filter function that allows
695 you to filter which controls will be added. Se 695 you to filter which controls will be added. Set it to NULL if you want to add
696 all controls. 696 all controls.
697 697
698 Or you can add specific controls to a handler: 698 Or you can add specific controls to a handler:
699 699
700 .. code-block:: c 700 .. code-block:: c
701 701
702 volume = v4l2_ctrl_new_std(&video_ctrl 702 volume = v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_AUDIO_VOLUME, ...);
703 v4l2_ctrl_new_std(&video_ctrl_handler, 703 v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_BRIGHTNESS, ...);
704 v4l2_ctrl_new_std(&video_ctrl_handler, 704 v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_CONTRAST, ...);
705 705
706 What you should not do is make two identical c 706 What you should not do is make two identical controls for two handlers.
707 For example: 707 For example:
708 708
709 .. code-block:: c 709 .. code-block:: c
710 710
711 v4l2_ctrl_new_std(&radio_ctrl_handler, 711 v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...);
712 v4l2_ctrl_new_std(&video_ctrl_handler, 712 v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_AUDIO_MUTE, ...);
713 713
714 This would be bad since muting the radio would 714 This would be bad since muting the radio would not change the video mute
715 control. The rule is to have one control for e 715 control. The rule is to have one control for each hardware 'knob' that you
716 can twiddle. 716 can twiddle.
717 717
718 718
719 Finding Controls 719 Finding Controls
720 ---------------- 720 ----------------
721 721
722 Normally you have created the controls yoursel 722 Normally you have created the controls yourself and you can store the struct
723 v4l2_ctrl pointer into your own struct. 723 v4l2_ctrl pointer into your own struct.
724 724
725 But sometimes you need to find a control from 725 But sometimes you need to find a control from another handler that you do
726 not own. For example, if you have to find a vo 726 not own. For example, if you have to find a volume control from a subdev.
727 727
728 You can do that by calling v4l2_ctrl_find: 728 You can do that by calling v4l2_ctrl_find:
729 729
730 .. code-block:: c 730 .. code-block:: c
731 731
732 struct v4l2_ctrl *volume; 732 struct v4l2_ctrl *volume;
733 733
734 volume = v4l2_ctrl_find(sd->ctrl_handl 734 volume = v4l2_ctrl_find(sd->ctrl_handler, V4L2_CID_AUDIO_VOLUME);
735 735
736 Since v4l2_ctrl_find will lock the handler you 736 Since v4l2_ctrl_find will lock the handler you have to be careful where you
737 use it. For example, this is not a good idea: 737 use it. For example, this is not a good idea:
738 738
739 .. code-block:: c 739 .. code-block:: c
740 740
741 struct v4l2_ctrl_handler ctrl_handler; 741 struct v4l2_ctrl_handler ctrl_handler;
742 742
743 v4l2_ctrl_new_std(&ctrl_handler, &vide 743 v4l2_ctrl_new_std(&ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...);
744 v4l2_ctrl_new_std(&ctrl_handler, &vide 744 v4l2_ctrl_new_std(&ctrl_handler, &video_ops, V4L2_CID_CONTRAST, ...);
745 745
746 ...and in video_ops.s_ctrl: 746 ...and in video_ops.s_ctrl:
747 747
748 .. code-block:: c 748 .. code-block:: c
749 749
750 case V4L2_CID_BRIGHTNESS: 750 case V4L2_CID_BRIGHTNESS:
751 contrast = v4l2_find_ctrl(&ctr 751 contrast = v4l2_find_ctrl(&ctrl_handler, V4L2_CID_CONTRAST);
752 ... 752 ...
753 753
754 When s_ctrl is called by the framework the ctr 754 When s_ctrl is called by the framework the ctrl_handler.lock is already taken, so
755 attempting to find another control from the sa 755 attempting to find another control from the same handler will deadlock.
756 756
757 It is recommended not to use this function fro 757 It is recommended not to use this function from inside the control ops.
758 758
759 759
760 Preventing Controls inheritance 760 Preventing Controls inheritance
761 ------------------------------- 761 -------------------------------
762 762
763 When one control handler is added to another u 763 When one control handler is added to another using v4l2_ctrl_add_handler, then
764 by default all controls from one are merged to 764 by default all controls from one are merged to the other. But a subdev might
765 have low-level controls that make sense for so 765 have low-level controls that make sense for some advanced embedded system, but
766 not when it is used in consumer-level hardware 766 not when it is used in consumer-level hardware. In that case you want to keep
767 those low-level controls local to the subdev. 767 those low-level controls local to the subdev. You can do this by simply
768 setting the 'is_private' flag of the control t 768 setting the 'is_private' flag of the control to 1:
769 769
770 .. code-block:: c 770 .. code-block:: c
771 771
772 static const struct v4l2_ctrl_config c 772 static const struct v4l2_ctrl_config ctrl_private = {
773 .ops = &ctrl_custom_ops, 773 .ops = &ctrl_custom_ops,
774 .id = V4L2_CID_..., 774 .id = V4L2_CID_...,
775 .name = "Some Private Control" 775 .name = "Some Private Control",
776 .type = V4L2_CTRL_TYPE_INTEGER 776 .type = V4L2_CTRL_TYPE_INTEGER,
777 .max = 15, 777 .max = 15,
778 .step = 1, 778 .step = 1,
779 .is_private = 1, 779 .is_private = 1,
780 }; 780 };
781 781
782 ctrl = v4l2_ctrl_new_custom(&foo->ctrl 782 ctrl = v4l2_ctrl_new_custom(&foo->ctrl_handler, &ctrl_private, NULL);
783 783
784 These controls will now be skipped when v4l2_c 784 These controls will now be skipped when v4l2_ctrl_add_handler is called.
785 785
786 786
787 V4L2_CTRL_TYPE_CTRL_CLASS Controls 787 V4L2_CTRL_TYPE_CTRL_CLASS Controls
788 ---------------------------------- 788 ----------------------------------
789 789
790 Controls of this type can be used by GUIs to g 790 Controls of this type can be used by GUIs to get the name of the control class.
791 A fully featured GUI can make a dialog with mu 791 A fully featured GUI can make a dialog with multiple tabs with each tab
792 containing the controls belonging to a particu 792 containing the controls belonging to a particular control class. The name of
793 each tab can be found by querying a special co 793 each tab can be found by querying a special control with ID <control class | 1>.
794 794
795 Drivers do not have to care about this. The fr 795 Drivers do not have to care about this. The framework will automatically add
796 a control of this type whenever the first cont 796 a control of this type whenever the first control belonging to a new control
797 class is added. 797 class is added.
798 798
799 799
800 Adding Notify Callbacks 800 Adding Notify Callbacks
801 ----------------------- 801 -----------------------
802 802
803 Sometimes the platform or bridge driver needs 803 Sometimes the platform or bridge driver needs to be notified when a control
804 from a sub-device driver changes. You can set 804 from a sub-device driver changes. You can set a notify callback by calling
805 this function: 805 this function:
806 806
807 .. code-block:: c 807 .. code-block:: c
808 808
809 void v4l2_ctrl_notify(struct v4l2_ctrl 809 void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl,
810 void (*notify)(struct v4l2_ctr 810 void (*notify)(struct v4l2_ctrl *ctrl, void *priv), void *priv);
811 811
812 Whenever the give control changes value the no 812 Whenever the give control changes value the notify callback will be called
813 with a pointer to the control and the priv poi 813 with a pointer to the control and the priv pointer that was passed with
814 v4l2_ctrl_notify. Note that the control's hand 814 v4l2_ctrl_notify. Note that the control's handler lock is held when the
815 notify function is called. 815 notify function is called.
816 816
817 There can be only one notify function per cont 817 There can be only one notify function per control handler. Any attempt
818 to set another notify function will cause a WA 818 to set another notify function will cause a WARN_ON.
819 819
820 v4l2_ctrl functions and data structures 820 v4l2_ctrl functions and data structures
821 --------------------------------------- 821 ---------------------------------------
822 822
823 .. kernel-doc:: include/media/v4l2-ctrls.h 823 .. kernel-doc:: include/media/v4l2-ctrls.h
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.