2 V4L2 controls framework implementation.
4 Copyright (C) 2010 Hans Verkuil <hverkuil@xs4all.nl>
6 This program is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2 of the License, or
9 (at your option) any later version.
11 This program is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 GNU General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with this program; if not, write to the Free Software
18 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
21 #include <linux/ctype.h>
22 #include <media/v4l2-ioctl.h>
23 #include <media/v4l2-device.h>
24 #include <media/v4l2-ctrls.h>
25 #include <media/v4l2-dev.h>
27 /* Internal temporary helper struct, one for each v4l2_ext_control */
29 /* The control corresponding to the v4l2_ext_control ID field. */
30 struct v4l2_ctrl *ctrl;
31 /* Used internally to mark whether this control was already
36 /* Returns NULL or a character pointer array containing the menu for
37 the given control ID. The pointer array ends with a NULL pointer.
38 An empty string signifies a menu entry that is invalid. This allows
39 drivers to disable certain options if it is not supported. */
40 const char **v4l2_ctrl_get_menu(u32 id)
42 static const char *mpeg_audio_sampling_freq[] = {
48 static const char *mpeg_audio_encoding[] = {
56 static const char *mpeg_audio_l1_bitrate[] = {
73 static const char *mpeg_audio_l2_bitrate[] = {
90 static const char *mpeg_audio_l3_bitrate[] = {
107 static const char *mpeg_audio_ac3_bitrate[] = {
129 static const char *mpeg_audio_mode[] = {
136 static const char *mpeg_audio_mode_extension[] = {
143 static const char *mpeg_audio_emphasis[] = {
149 static const char *mpeg_audio_crc[] = {
154 static const char *mpeg_video_encoding[] = {
160 static const char *mpeg_video_aspect[] = {
167 static const char *mpeg_video_bitrate_mode[] = {
172 static const char *mpeg_stream_type[] = {
173 "MPEG-2 Program Stream",
174 "MPEG-2 Transport Stream",
175 "MPEG-1 System Stream",
176 "MPEG-2 DVD-compatible Stream",
177 "MPEG-1 VCD-compatible Stream",
178 "MPEG-2 SVCD-compatible Stream",
181 static const char *mpeg_stream_vbi_fmt[] = {
183 "Private packet, IVTV format",
186 static const char *camera_power_line_frequency[] = {
192 static const char *camera_exposure_auto[] = {
195 "Shutter Priority Mode",
196 "Aperture Priority Mode",
199 static const char *colorfx[] = {
212 static const char *tune_preemphasis[] = {
220 case V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ:
221 return mpeg_audio_sampling_freq;
222 case V4L2_CID_MPEG_AUDIO_ENCODING:
223 return mpeg_audio_encoding;
224 case V4L2_CID_MPEG_AUDIO_L1_BITRATE:
225 return mpeg_audio_l1_bitrate;
226 case V4L2_CID_MPEG_AUDIO_L2_BITRATE:
227 return mpeg_audio_l2_bitrate;
228 case V4L2_CID_MPEG_AUDIO_L3_BITRATE:
229 return mpeg_audio_l3_bitrate;
230 case V4L2_CID_MPEG_AUDIO_AC3_BITRATE:
231 return mpeg_audio_ac3_bitrate;
232 case V4L2_CID_MPEG_AUDIO_MODE:
233 return mpeg_audio_mode;
234 case V4L2_CID_MPEG_AUDIO_MODE_EXTENSION:
235 return mpeg_audio_mode_extension;
236 case V4L2_CID_MPEG_AUDIO_EMPHASIS:
237 return mpeg_audio_emphasis;
238 case V4L2_CID_MPEG_AUDIO_CRC:
239 return mpeg_audio_crc;
240 case V4L2_CID_MPEG_VIDEO_ENCODING:
241 return mpeg_video_encoding;
242 case V4L2_CID_MPEG_VIDEO_ASPECT:
243 return mpeg_video_aspect;
244 case V4L2_CID_MPEG_VIDEO_BITRATE_MODE:
245 return mpeg_video_bitrate_mode;
246 case V4L2_CID_MPEG_STREAM_TYPE:
247 return mpeg_stream_type;
248 case V4L2_CID_MPEG_STREAM_VBI_FMT:
249 return mpeg_stream_vbi_fmt;
250 case V4L2_CID_POWER_LINE_FREQUENCY:
251 return camera_power_line_frequency;
252 case V4L2_CID_EXPOSURE_AUTO:
253 return camera_exposure_auto;
254 case V4L2_CID_COLORFX:
256 case V4L2_CID_TUNE_PREEMPHASIS:
257 return tune_preemphasis;
262 EXPORT_SYMBOL(v4l2_ctrl_get_menu);
264 /* Return the control name. */
265 const char *v4l2_ctrl_get_name(u32 id)
269 /* Keep the order of the 'case's the same as in videodev2.h! */
270 case V4L2_CID_USER_CLASS: return "User Controls";
271 case V4L2_CID_BRIGHTNESS: return "Brightness";
272 case V4L2_CID_CONTRAST: return "Contrast";
273 case V4L2_CID_SATURATION: return "Saturation";
274 case V4L2_CID_HUE: return "Hue";
275 case V4L2_CID_AUDIO_VOLUME: return "Volume";
276 case V4L2_CID_AUDIO_BALANCE: return "Balance";
277 case V4L2_CID_AUDIO_BASS: return "Bass";
278 case V4L2_CID_AUDIO_TREBLE: return "Treble";
279 case V4L2_CID_AUDIO_MUTE: return "Mute";
280 case V4L2_CID_AUDIO_LOUDNESS: return "Loudness";
281 case V4L2_CID_BLACK_LEVEL: return "Black Level";
282 case V4L2_CID_AUTO_WHITE_BALANCE: return "White Balance, Automatic";
283 case V4L2_CID_DO_WHITE_BALANCE: return "Do White Balance";
284 case V4L2_CID_RED_BALANCE: return "Red Balance";
285 case V4L2_CID_BLUE_BALANCE: return "Blue Balance";
286 case V4L2_CID_GAMMA: return "Gamma";
287 case V4L2_CID_EXPOSURE: return "Exposure";
288 case V4L2_CID_AUTOGAIN: return "Gain, Automatic";
289 case V4L2_CID_GAIN: return "Gain";
290 case V4L2_CID_HFLIP: return "Horizontal Flip";
291 case V4L2_CID_VFLIP: return "Vertical Flip";
292 case V4L2_CID_HCENTER: return "Horizontal Center";
293 case V4L2_CID_VCENTER: return "Vertical Center";
294 case V4L2_CID_POWER_LINE_FREQUENCY: return "Power Line Frequency";
295 case V4L2_CID_HUE_AUTO: return "Hue, Automatic";
296 case V4L2_CID_WHITE_BALANCE_TEMPERATURE: return "White Balance Temperature";
297 case V4L2_CID_SHARPNESS: return "Sharpness";
298 case V4L2_CID_BACKLIGHT_COMPENSATION: return "Backlight Compensation";
299 case V4L2_CID_CHROMA_AGC: return "Chroma AGC";
300 case V4L2_CID_COLOR_KILLER: return "Color Killer";
301 case V4L2_CID_COLORFX: return "Color Effects";
302 case V4L2_CID_AUTOBRIGHTNESS: return "Brightness, Automatic";
303 case V4L2_CID_BAND_STOP_FILTER: return "Band-Stop Filter";
304 case V4L2_CID_ROTATE: return "Rotate";
305 case V4L2_CID_BG_COLOR: return "Background Color";
306 case V4L2_CID_CHROMA_GAIN: return "Chroma Gain";
309 /* Keep the order of the 'case's the same as in videodev2.h! */
310 case V4L2_CID_MPEG_CLASS: return "MPEG Encoder Controls";
311 case V4L2_CID_MPEG_STREAM_TYPE: return "Stream Type";
312 case V4L2_CID_MPEG_STREAM_PID_PMT: return "Stream PMT Program ID";
313 case V4L2_CID_MPEG_STREAM_PID_AUDIO: return "Stream Audio Program ID";
314 case V4L2_CID_MPEG_STREAM_PID_VIDEO: return "Stream Video Program ID";
315 case V4L2_CID_MPEG_STREAM_PID_PCR: return "Stream PCR Program ID";
316 case V4L2_CID_MPEG_STREAM_PES_ID_AUDIO: return "Stream PES Audio ID";
317 case V4L2_CID_MPEG_STREAM_PES_ID_VIDEO: return "Stream PES Video ID";
318 case V4L2_CID_MPEG_STREAM_VBI_FMT: return "Stream VBI Format";
319 case V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ: return "Audio Sampling Frequency";
320 case V4L2_CID_MPEG_AUDIO_ENCODING: return "Audio Encoding";
321 case V4L2_CID_MPEG_AUDIO_L1_BITRATE: return "Audio Layer I Bitrate";
322 case V4L2_CID_MPEG_AUDIO_L2_BITRATE: return "Audio Layer II Bitrate";
323 case V4L2_CID_MPEG_AUDIO_L3_BITRATE: return "Audio Layer III Bitrate";
324 case V4L2_CID_MPEG_AUDIO_MODE: return "Audio Stereo Mode";
325 case V4L2_CID_MPEG_AUDIO_MODE_EXTENSION: return "Audio Stereo Mode Extension";
326 case V4L2_CID_MPEG_AUDIO_EMPHASIS: return "Audio Emphasis";
327 case V4L2_CID_MPEG_AUDIO_CRC: return "Audio CRC";
328 case V4L2_CID_MPEG_AUDIO_MUTE: return "Audio Mute";
329 case V4L2_CID_MPEG_AUDIO_AAC_BITRATE: return "Audio AAC Bitrate";
330 case V4L2_CID_MPEG_AUDIO_AC3_BITRATE: return "Audio AC-3 Bitrate";
331 case V4L2_CID_MPEG_VIDEO_ENCODING: return "Video Encoding";
332 case V4L2_CID_MPEG_VIDEO_ASPECT: return "Video Aspect";
333 case V4L2_CID_MPEG_VIDEO_B_FRAMES: return "Video B Frames";
334 case V4L2_CID_MPEG_VIDEO_GOP_SIZE: return "Video GOP Size";
335 case V4L2_CID_MPEG_VIDEO_GOP_CLOSURE: return "Video GOP Closure";
336 case V4L2_CID_MPEG_VIDEO_PULLDOWN: return "Video Pulldown";
337 case V4L2_CID_MPEG_VIDEO_BITRATE_MODE: return "Video Bitrate Mode";
338 case V4L2_CID_MPEG_VIDEO_BITRATE: return "Video Bitrate";
339 case V4L2_CID_MPEG_VIDEO_BITRATE_PEAK: return "Video Peak Bitrate";
340 case V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION: return "Video Temporal Decimation";
341 case V4L2_CID_MPEG_VIDEO_MUTE: return "Video Mute";
342 case V4L2_CID_MPEG_VIDEO_MUTE_YUV: return "Video Mute YUV";
344 /* CAMERA controls */
345 /* Keep the order of the 'case's the same as in videodev2.h! */
346 case V4L2_CID_CAMERA_CLASS: return "Camera Controls";
347 case V4L2_CID_EXPOSURE_AUTO: return "Auto Exposure";
348 case V4L2_CID_EXPOSURE_ABSOLUTE: return "Exposure Time, Absolute";
349 case V4L2_CID_EXPOSURE_AUTO_PRIORITY: return "Exposure, Dynamic Framerate";
350 case V4L2_CID_PAN_RELATIVE: return "Pan, Relative";
351 case V4L2_CID_TILT_RELATIVE: return "Tilt, Relative";
352 case V4L2_CID_PAN_RESET: return "Pan, Reset";
353 case V4L2_CID_TILT_RESET: return "Tilt, Reset";
354 case V4L2_CID_PAN_ABSOLUTE: return "Pan, Absolute";
355 case V4L2_CID_TILT_ABSOLUTE: return "Tilt, Absolute";
356 case V4L2_CID_FOCUS_ABSOLUTE: return "Focus, Absolute";
357 case V4L2_CID_FOCUS_RELATIVE: return "Focus, Relative";
358 case V4L2_CID_FOCUS_AUTO: return "Focus, Automatic";
359 case V4L2_CID_ZOOM_ABSOLUTE: return "Zoom, Absolute";
360 case V4L2_CID_ZOOM_RELATIVE: return "Zoom, Relative";
361 case V4L2_CID_ZOOM_CONTINUOUS: return "Zoom, Continuous";
362 case V4L2_CID_PRIVACY: return "Privacy";
363 case V4L2_CID_IRIS_ABSOLUTE: return "Iris, Absolute";
364 case V4L2_CID_IRIS_RELATIVE: return "Iris, Relative";
366 /* FM Radio Modulator control */
367 /* Keep the order of the 'case's the same as in videodev2.h! */
368 case V4L2_CID_FM_TX_CLASS: return "FM Radio Modulator Controls";
369 case V4L2_CID_RDS_TX_DEVIATION: return "RDS Signal Deviation";
370 case V4L2_CID_RDS_TX_PI: return "RDS Program ID";
371 case V4L2_CID_RDS_TX_PTY: return "RDS Program Type";
372 case V4L2_CID_RDS_TX_PS_NAME: return "RDS PS Name";
373 case V4L2_CID_RDS_TX_RADIO_TEXT: return "RDS Radio Text";
374 case V4L2_CID_AUDIO_LIMITER_ENABLED: return "Audio Limiter Feature Enabled";
375 case V4L2_CID_AUDIO_LIMITER_RELEASE_TIME: return "Audio Limiter Release Time";
376 case V4L2_CID_AUDIO_LIMITER_DEVIATION: return "Audio Limiter Deviation";
377 case V4L2_CID_AUDIO_COMPRESSION_ENABLED: return "Audio Compression Feature Enabled";
378 case V4L2_CID_AUDIO_COMPRESSION_GAIN: return "Audio Compression Gain";
379 case V4L2_CID_AUDIO_COMPRESSION_THRESHOLD: return "Audio Compression Threshold";
380 case V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME: return "Audio Compression Attack Time";
381 case V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME: return "Audio Compression Release Time";
382 case V4L2_CID_PILOT_TONE_ENABLED: return "Pilot Tone Feature Enabled";
383 case V4L2_CID_PILOT_TONE_DEVIATION: return "Pilot Tone Deviation";
384 case V4L2_CID_PILOT_TONE_FREQUENCY: return "Pilot Tone Frequency";
385 case V4L2_CID_TUNE_PREEMPHASIS: return "Pre-emphasis settings";
386 case V4L2_CID_TUNE_POWER_LEVEL: return "Tune Power Level";
387 case V4L2_CID_TUNE_ANTENNA_CAPACITOR: return "Tune Antenna Capacitor";
393 EXPORT_SYMBOL(v4l2_ctrl_get_name);
395 void v4l2_ctrl_fill(u32 id, const char **name, enum v4l2_ctrl_type *type,
396 s32 *min, s32 *max, s32 *step, s32 *def, u32 *flags)
398 *name = v4l2_ctrl_get_name(id);
402 case V4L2_CID_AUDIO_MUTE:
403 case V4L2_CID_AUDIO_LOUDNESS:
404 case V4L2_CID_AUTO_WHITE_BALANCE:
405 case V4L2_CID_AUTOGAIN:
408 case V4L2_CID_HUE_AUTO:
409 case V4L2_CID_CHROMA_AGC:
410 case V4L2_CID_COLOR_KILLER:
411 case V4L2_CID_MPEG_AUDIO_MUTE:
412 case V4L2_CID_MPEG_VIDEO_MUTE:
413 case V4L2_CID_MPEG_VIDEO_GOP_CLOSURE:
414 case V4L2_CID_MPEG_VIDEO_PULLDOWN:
415 case V4L2_CID_EXPOSURE_AUTO_PRIORITY:
416 case V4L2_CID_FOCUS_AUTO:
417 case V4L2_CID_PRIVACY:
418 case V4L2_CID_AUDIO_LIMITER_ENABLED:
419 case V4L2_CID_AUDIO_COMPRESSION_ENABLED:
420 case V4L2_CID_PILOT_TONE_ENABLED:
421 *type = V4L2_CTRL_TYPE_BOOLEAN;
425 case V4L2_CID_PAN_RESET:
426 case V4L2_CID_TILT_RESET:
427 *type = V4L2_CTRL_TYPE_BUTTON;
428 *flags |= V4L2_CTRL_FLAG_WRITE_ONLY;
429 *min = *max = *step = *def = 0;
431 case V4L2_CID_POWER_LINE_FREQUENCY:
432 case V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ:
433 case V4L2_CID_MPEG_AUDIO_ENCODING:
434 case V4L2_CID_MPEG_AUDIO_L1_BITRATE:
435 case V4L2_CID_MPEG_AUDIO_L2_BITRATE:
436 case V4L2_CID_MPEG_AUDIO_L3_BITRATE:
437 case V4L2_CID_MPEG_AUDIO_AC3_BITRATE:
438 case V4L2_CID_MPEG_AUDIO_MODE:
439 case V4L2_CID_MPEG_AUDIO_MODE_EXTENSION:
440 case V4L2_CID_MPEG_AUDIO_EMPHASIS:
441 case V4L2_CID_MPEG_AUDIO_CRC:
442 case V4L2_CID_MPEG_VIDEO_ENCODING:
443 case V4L2_CID_MPEG_VIDEO_ASPECT:
444 case V4L2_CID_MPEG_VIDEO_BITRATE_MODE:
445 case V4L2_CID_MPEG_STREAM_TYPE:
446 case V4L2_CID_MPEG_STREAM_VBI_FMT:
447 case V4L2_CID_EXPOSURE_AUTO:
448 case V4L2_CID_COLORFX:
449 case V4L2_CID_TUNE_PREEMPHASIS:
450 *type = V4L2_CTRL_TYPE_MENU;
452 case V4L2_CID_RDS_TX_PS_NAME:
453 case V4L2_CID_RDS_TX_RADIO_TEXT:
454 *type = V4L2_CTRL_TYPE_STRING;
456 case V4L2_CID_USER_CLASS:
457 case V4L2_CID_CAMERA_CLASS:
458 case V4L2_CID_MPEG_CLASS:
459 case V4L2_CID_FM_TX_CLASS:
460 *type = V4L2_CTRL_TYPE_CTRL_CLASS;
461 /* You can neither read not write these */
462 *flags |= V4L2_CTRL_FLAG_READ_ONLY | V4L2_CTRL_FLAG_WRITE_ONLY;
463 *min = *max = *step = *def = 0;
465 case V4L2_CID_BG_COLOR:
466 *type = V4L2_CTRL_TYPE_INTEGER;
469 /* Max is calculated as RGB888 that is 2^24 */
473 *type = V4L2_CTRL_TYPE_INTEGER;
477 case V4L2_CID_MPEG_AUDIO_ENCODING:
478 case V4L2_CID_MPEG_AUDIO_MODE:
479 case V4L2_CID_MPEG_VIDEO_BITRATE_MODE:
480 case V4L2_CID_MPEG_VIDEO_B_FRAMES:
481 case V4L2_CID_MPEG_STREAM_TYPE:
482 *flags |= V4L2_CTRL_FLAG_UPDATE;
484 case V4L2_CID_AUDIO_VOLUME:
485 case V4L2_CID_AUDIO_BALANCE:
486 case V4L2_CID_AUDIO_BASS:
487 case V4L2_CID_AUDIO_TREBLE:
488 case V4L2_CID_BRIGHTNESS:
489 case V4L2_CID_CONTRAST:
490 case V4L2_CID_SATURATION:
492 case V4L2_CID_RED_BALANCE:
493 case V4L2_CID_BLUE_BALANCE:
495 case V4L2_CID_SHARPNESS:
496 case V4L2_CID_CHROMA_GAIN:
497 case V4L2_CID_RDS_TX_DEVIATION:
498 case V4L2_CID_AUDIO_LIMITER_RELEASE_TIME:
499 case V4L2_CID_AUDIO_LIMITER_DEVIATION:
500 case V4L2_CID_AUDIO_COMPRESSION_GAIN:
501 case V4L2_CID_AUDIO_COMPRESSION_THRESHOLD:
502 case V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME:
503 case V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME:
504 case V4L2_CID_PILOT_TONE_DEVIATION:
505 case V4L2_CID_PILOT_TONE_FREQUENCY:
506 case V4L2_CID_TUNE_POWER_LEVEL:
507 case V4L2_CID_TUNE_ANTENNA_CAPACITOR:
508 *flags |= V4L2_CTRL_FLAG_SLIDER;
510 case V4L2_CID_PAN_RELATIVE:
511 case V4L2_CID_TILT_RELATIVE:
512 case V4L2_CID_FOCUS_RELATIVE:
513 case V4L2_CID_IRIS_RELATIVE:
514 case V4L2_CID_ZOOM_RELATIVE:
515 *flags |= V4L2_CTRL_FLAG_WRITE_ONLY;
519 EXPORT_SYMBOL(v4l2_ctrl_fill);
521 /* Helper function to determine whether the control type is compatible with
523 static bool type_is_int(const struct v4l2_ctrl *ctrl)
525 switch (ctrl->type) {
526 case V4L2_CTRL_TYPE_INTEGER64:
527 case V4L2_CTRL_TYPE_STRING:
528 /* Nope, these need v4l2_ext_control */
535 /* Helper function: copy the current control value back to the caller */
536 static int cur_to_user(struct v4l2_ext_control *c,
537 struct v4l2_ctrl *ctrl)
541 switch (ctrl->type) {
542 case V4L2_CTRL_TYPE_STRING:
543 len = strlen(ctrl->cur.string);
544 if (c->size < len + 1) {
548 return copy_to_user(c->string, ctrl->cur.string,
549 len + 1) ? -EFAULT : 0;
550 case V4L2_CTRL_TYPE_INTEGER64:
551 c->value64 = ctrl->cur.val64;
554 c->value = ctrl->cur.val;
560 /* Helper function: copy the caller-provider value as the new control value */
561 static int user_to_new(struct v4l2_ext_control *c,
562 struct v4l2_ctrl *ctrl)
568 switch (ctrl->type) {
569 case V4L2_CTRL_TYPE_INTEGER64:
570 ctrl->val64 = c->value64;
572 case V4L2_CTRL_TYPE_STRING:
576 if (size > ctrl->maximum + 1)
577 size = ctrl->maximum + 1;
578 ret = copy_from_user(ctrl->string, c->string, size);
580 char last = ctrl->string[size - 1];
582 ctrl->string[size - 1] = 0;
583 /* If the string was longer than ctrl->maximum,
584 then return an error. */
585 if (strlen(ctrl->string) == ctrl->maximum && last)
588 return ret ? -EFAULT : 0;
590 ctrl->val = c->value;
596 /* Helper function: copy the new control value back to the caller */
597 static int new_to_user(struct v4l2_ext_control *c,
598 struct v4l2_ctrl *ctrl)
602 switch (ctrl->type) {
603 case V4L2_CTRL_TYPE_STRING:
604 len = strlen(ctrl->string);
605 if (c->size < len + 1) {
606 c->size = ctrl->maximum + 1;
609 return copy_to_user(c->string, ctrl->string,
610 len + 1) ? -EFAULT : 0;
611 case V4L2_CTRL_TYPE_INTEGER64:
612 c->value64 = ctrl->val64;
615 c->value = ctrl->val;
621 /* Copy the new value to the current value. */
622 static void new_to_cur(struct v4l2_ctrl *ctrl)
626 switch (ctrl->type) {
627 case V4L2_CTRL_TYPE_STRING:
628 /* strings are always 0-terminated */
629 strcpy(ctrl->cur.string, ctrl->string);
631 case V4L2_CTRL_TYPE_INTEGER64:
632 ctrl->cur.val64 = ctrl->val64;
635 ctrl->cur.val = ctrl->val;
640 /* Copy the current value to the new value */
641 static void cur_to_new(struct v4l2_ctrl *ctrl)
645 switch (ctrl->type) {
646 case V4L2_CTRL_TYPE_STRING:
647 /* strings are always 0-terminated */
648 strcpy(ctrl->string, ctrl->cur.string);
650 case V4L2_CTRL_TYPE_INTEGER64:
651 ctrl->val64 = ctrl->cur.val64;
654 ctrl->val = ctrl->cur.val;
659 /* Return non-zero if one or more of the controls in the cluster has a new
660 value that differs from the current value. */
661 static int cluster_changed(struct v4l2_ctrl *master)
666 for (i = 0; !diff && i < master->ncontrols; i++) {
667 struct v4l2_ctrl *ctrl = master->cluster[i];
671 switch (ctrl->type) {
672 case V4L2_CTRL_TYPE_BUTTON:
673 /* Button controls are always 'different' */
675 case V4L2_CTRL_TYPE_STRING:
676 /* strings are always 0-terminated */
677 diff = strcmp(ctrl->string, ctrl->cur.string);
679 case V4L2_CTRL_TYPE_INTEGER64:
680 diff = ctrl->val64 != ctrl->cur.val64;
683 diff = ctrl->val != ctrl->cur.val;
690 /* Validate a new control */
691 static int validate_new(struct v4l2_ctrl *ctrl)
694 char *s = ctrl->string;
698 switch (ctrl->type) {
699 case V4L2_CTRL_TYPE_INTEGER:
700 /* Round towards the closest legal value */
701 val += ctrl->step / 2;
702 if (val < ctrl->minimum)
704 if (val > ctrl->maximum)
706 offset = val - ctrl->minimum;
707 offset = ctrl->step * (offset / ctrl->step);
708 val = ctrl->minimum + offset;
712 case V4L2_CTRL_TYPE_BOOLEAN:
713 ctrl->val = !!ctrl->val;
716 case V4L2_CTRL_TYPE_MENU:
717 if (val < ctrl->minimum || val > ctrl->maximum)
719 if (ctrl->qmenu[val][0] == '\0' ||
720 (ctrl->menu_skip_mask & (1 << val)))
724 case V4L2_CTRL_TYPE_BUTTON:
725 case V4L2_CTRL_TYPE_CTRL_CLASS:
729 case V4L2_CTRL_TYPE_INTEGER64:
732 case V4L2_CTRL_TYPE_STRING:
734 if (len < ctrl->minimum)
736 if ((len - ctrl->minimum) % ctrl->step)
745 static inline u32 node2id(struct list_head *node)
747 return list_entry(node, struct v4l2_ctrl_ref, node)->ctrl->id;
750 /* Set the handler's error code if it wasn't set earlier already */
751 static inline int handler_set_err(struct v4l2_ctrl_handler *hdl, int err)
758 /* Initialize the handler */
759 int v4l2_ctrl_handler_init(struct v4l2_ctrl_handler *hdl,
760 unsigned nr_of_controls_hint)
762 mutex_init(&hdl->lock);
763 INIT_LIST_HEAD(&hdl->ctrls);
764 INIT_LIST_HEAD(&hdl->ctrl_refs);
765 hdl->nr_of_buckets = 1 + nr_of_controls_hint / 8;
766 hdl->buckets = kzalloc(sizeof(hdl->buckets[0]) * hdl->nr_of_buckets,
768 hdl->error = hdl->buckets ? 0 : -ENOMEM;
771 EXPORT_SYMBOL(v4l2_ctrl_handler_init);
773 /* Free all controls and control refs */
774 void v4l2_ctrl_handler_free(struct v4l2_ctrl_handler *hdl)
776 struct v4l2_ctrl_ref *ref, *next_ref;
777 struct v4l2_ctrl *ctrl, *next_ctrl;
779 if (hdl == NULL || hdl->buckets == NULL)
782 mutex_lock(&hdl->lock);
784 list_for_each_entry_safe(ref, next_ref, &hdl->ctrl_refs, node) {
785 list_del(&ref->node);
788 /* Free all controls owned by the handler */
789 list_for_each_entry_safe(ctrl, next_ctrl, &hdl->ctrls, node) {
790 list_del(&ctrl->node);
797 mutex_unlock(&hdl->lock);
799 EXPORT_SYMBOL(v4l2_ctrl_handler_free);
801 /* For backwards compatibility: V4L2_CID_PRIVATE_BASE should no longer
802 be used except in G_CTRL, S_CTRL, QUERYCTRL and QUERYMENU when dealing
803 with applications that do not use the NEXT_CTRL flag.
805 We just find the n-th private user control. It's O(N), but that should not
806 be an issue in this particular case. */
807 static struct v4l2_ctrl_ref *find_private_ref(
808 struct v4l2_ctrl_handler *hdl, u32 id)
810 struct v4l2_ctrl_ref *ref;
812 id -= V4L2_CID_PRIVATE_BASE;
813 list_for_each_entry(ref, &hdl->ctrl_refs, node) {
814 /* Search for private user controls that are compatible with
816 if (V4L2_CTRL_ID2CLASS(ref->ctrl->id) == V4L2_CTRL_CLASS_USER &&
817 V4L2_CTRL_DRIVER_PRIV(ref->ctrl->id)) {
818 if (!type_is_int(ref->ctrl))
828 /* Find a control with the given ID. */
829 static struct v4l2_ctrl_ref *find_ref(struct v4l2_ctrl_handler *hdl, u32 id)
831 struct v4l2_ctrl_ref *ref;
834 id &= V4L2_CTRL_ID_MASK;
836 /* Old-style private controls need special handling */
837 if (id >= V4L2_CID_PRIVATE_BASE)
838 return find_private_ref(hdl, id);
839 bucket = id % hdl->nr_of_buckets;
841 /* Simple optimization: cache the last control found */
842 if (hdl->cached && hdl->cached->ctrl->id == id)
845 /* Not in cache, search the hash */
846 ref = hdl->buckets ? hdl->buckets[bucket] : NULL;
847 while (ref && ref->ctrl->id != id)
851 hdl->cached = ref; /* cache it! */
855 /* Find a control with the given ID. Take the handler's lock first. */
856 static struct v4l2_ctrl_ref *find_ref_lock(
857 struct v4l2_ctrl_handler *hdl, u32 id)
859 struct v4l2_ctrl_ref *ref = NULL;
862 mutex_lock(&hdl->lock);
863 ref = find_ref(hdl, id);
864 mutex_unlock(&hdl->lock);
869 /* Find a control with the given ID. */
870 struct v4l2_ctrl *v4l2_ctrl_find(struct v4l2_ctrl_handler *hdl, u32 id)
872 struct v4l2_ctrl_ref *ref = find_ref_lock(hdl, id);
874 return ref ? ref->ctrl : NULL;
876 EXPORT_SYMBOL(v4l2_ctrl_find);
878 /* Allocate a new v4l2_ctrl_ref and hook it into the handler. */
879 static int handler_new_ref(struct v4l2_ctrl_handler *hdl,
880 struct v4l2_ctrl *ctrl)
882 struct v4l2_ctrl_ref *ref;
883 struct v4l2_ctrl_ref *new_ref;
885 u32 class_ctrl = V4L2_CTRL_ID2CLASS(id) | 1;
886 int bucket = id % hdl->nr_of_buckets; /* which bucket to use */
888 /* Automatically add the control class if it is not yet present. */
889 if (id != class_ctrl && find_ref_lock(hdl, class_ctrl) == NULL)
890 if (!v4l2_ctrl_new_std(hdl, NULL, class_ctrl, 0, 0, 0, 0))
896 new_ref = kzalloc(sizeof(*new_ref), GFP_KERNEL);
898 return handler_set_err(hdl, -ENOMEM);
899 new_ref->ctrl = ctrl;
900 if (ctrl->handler == hdl) {
901 /* By default each control starts in a cluster of its own.
902 new_ref->ctrl is basically a cluster array with one
903 element, so that's perfect to use as the cluster pointer.
904 But only do this for the handler that owns the control. */
905 ctrl->cluster = &new_ref->ctrl;
909 INIT_LIST_HEAD(&new_ref->node);
911 mutex_lock(&hdl->lock);
913 /* Add immediately at the end of the list if the list is empty, or if
914 the last element in the list has a lower ID.
915 This ensures that when elements are added in ascending order the
916 insertion is an O(1) operation. */
917 if (list_empty(&hdl->ctrl_refs) || id > node2id(hdl->ctrl_refs.prev)) {
918 list_add_tail(&new_ref->node, &hdl->ctrl_refs);
922 /* Find insert position in sorted list */
923 list_for_each_entry(ref, &hdl->ctrl_refs, node) {
924 if (ref->ctrl->id < id)
926 /* Don't add duplicates */
927 if (ref->ctrl->id == id) {
931 list_add(&new_ref->node, ref->node.prev);
936 /* Insert the control node in the hash */
937 new_ref->next = hdl->buckets[bucket];
938 hdl->buckets[bucket] = new_ref;
941 mutex_unlock(&hdl->lock);
945 /* Add a new control */
946 static struct v4l2_ctrl *v4l2_ctrl_new(struct v4l2_ctrl_handler *hdl,
947 const struct v4l2_ctrl_ops *ops,
948 u32 id, const char *name, enum v4l2_ctrl_type type,
949 s32 min, s32 max, u32 step, s32 def,
950 u32 flags, const char **qmenu, void *priv)
952 struct v4l2_ctrl *ctrl;
953 unsigned sz_extra = 0;
959 if (id == 0 || name == NULL || id >= V4L2_CID_PRIVATE_BASE ||
960 def < min || def > max || max < min ||
961 (type == V4L2_CTRL_TYPE_INTEGER && step == 0) ||
962 (type == V4L2_CTRL_TYPE_MENU && qmenu == NULL) ||
963 (type == V4L2_CTRL_TYPE_STRING && max == 0)) {
964 handler_set_err(hdl, -ERANGE);
968 if (type == V4L2_CTRL_TYPE_BUTTON)
969 flags |= V4L2_CTRL_FLAG_WRITE_ONLY;
970 else if (type == V4L2_CTRL_TYPE_CTRL_CLASS)
971 flags |= V4L2_CTRL_FLAG_READ_ONLY;
972 else if (type == V4L2_CTRL_TYPE_STRING)
973 sz_extra += 2 * (max + 1);
975 ctrl = kzalloc(sizeof(*ctrl) + sz_extra, GFP_KERNEL);
977 handler_set_err(hdl, -ENOMEM);
981 INIT_LIST_HEAD(&ctrl->node);
993 ctrl->cur.val = ctrl->val = ctrl->default_value = def;
995 if (ctrl->type == V4L2_CTRL_TYPE_STRING) {
996 ctrl->cur.string = (char *)&ctrl[1] + sz_extra - (max + 1);
997 ctrl->string = (char *)&ctrl[1] + sz_extra - 2 * (max + 1);
999 memset(ctrl->cur.string, ' ', ctrl->minimum);
1001 if (handler_new_ref(hdl, ctrl)) {
1005 mutex_lock(&hdl->lock);
1006 list_add_tail(&ctrl->node, &hdl->ctrls);
1007 mutex_unlock(&hdl->lock);
1011 struct v4l2_ctrl *v4l2_ctrl_new_custom(struct v4l2_ctrl_handler *hdl,
1012 const struct v4l2_ctrl_config *cfg, void *priv)
1015 struct v4l2_ctrl *ctrl;
1016 const char *name = cfg->name;
1017 const char **qmenu = cfg->qmenu;
1018 enum v4l2_ctrl_type type = cfg->type;
1019 u32 flags = cfg->flags;
1022 u32 step = cfg->step;
1026 v4l2_ctrl_fill(cfg->id, &name, &type, &min, &max, &step,
1029 is_menu = (cfg->type == V4L2_CTRL_TYPE_MENU);
1033 WARN_ON(cfg->menu_skip_mask);
1034 if (is_menu && qmenu == NULL)
1035 qmenu = v4l2_ctrl_get_menu(cfg->id);
1037 ctrl = v4l2_ctrl_new(hdl, cfg->ops, cfg->id, name,
1039 is_menu ? cfg->menu_skip_mask : step,
1040 def, flags, qmenu, priv);
1042 ctrl->is_private = cfg->is_private;
1043 ctrl->is_volatile = cfg->is_volatile;
1047 EXPORT_SYMBOL(v4l2_ctrl_new_custom);
1049 /* Helper function for standard non-menu controls */
1050 struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl,
1051 const struct v4l2_ctrl_ops *ops,
1052 u32 id, s32 min, s32 max, u32 step, s32 def)
1055 enum v4l2_ctrl_type type;
1058 v4l2_ctrl_fill(id, &name, &type, &min, &max, &step, &def, &flags);
1059 if (type == V4L2_CTRL_TYPE_MENU) {
1060 handler_set_err(hdl, -EINVAL);
1063 return v4l2_ctrl_new(hdl, ops, id, name, type,
1064 min, max, step, def, flags, NULL, NULL);
1066 EXPORT_SYMBOL(v4l2_ctrl_new_std);
1068 /* Helper function for standard menu controls */
1069 struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl,
1070 const struct v4l2_ctrl_ops *ops,
1071 u32 id, s32 max, s32 mask, s32 def)
1073 const char **qmenu = v4l2_ctrl_get_menu(id);
1075 enum v4l2_ctrl_type type;
1080 v4l2_ctrl_fill(id, &name, &type, &min, &max, &step, &def, &flags);
1081 if (type != V4L2_CTRL_TYPE_MENU) {
1082 handler_set_err(hdl, -EINVAL);
1085 return v4l2_ctrl_new(hdl, ops, id, name, type,
1086 0, max, mask, def, flags, qmenu, NULL);
1088 EXPORT_SYMBOL(v4l2_ctrl_new_std_menu);
1090 /* Add a control from another handler to this handler */
1091 struct v4l2_ctrl *v4l2_ctrl_add_ctrl(struct v4l2_ctrl_handler *hdl,
1092 struct v4l2_ctrl *ctrl)
1094 if (hdl == NULL || hdl->error)
1097 handler_set_err(hdl, -EINVAL);
1100 if (ctrl->handler == hdl)
1102 return handler_new_ref(hdl, ctrl) ? NULL : ctrl;
1104 EXPORT_SYMBOL(v4l2_ctrl_add_ctrl);
1106 /* Add the controls from another handler to our own. */
1107 int v4l2_ctrl_add_handler(struct v4l2_ctrl_handler *hdl,
1108 struct v4l2_ctrl_handler *add)
1110 struct v4l2_ctrl *ctrl;
1113 /* Do nothing if either handler is NULL or if they are the same */
1114 if (!hdl || !add || hdl == add)
1118 mutex_lock(&add->lock);
1119 list_for_each_entry(ctrl, &add->ctrls, node) {
1120 /* Skip handler-private controls. */
1121 if (ctrl->is_private)
1123 ret = handler_new_ref(hdl, ctrl);
1127 mutex_unlock(&add->lock);
1130 EXPORT_SYMBOL(v4l2_ctrl_add_handler);
1132 /* Cluster controls */
1133 void v4l2_ctrl_cluster(unsigned ncontrols, struct v4l2_ctrl **controls)
1137 /* The first control is the master control and it must not be NULL */
1138 BUG_ON(controls[0] == NULL);
1140 for (i = 0; i < ncontrols; i++) {
1142 controls[i]->cluster = controls;
1143 controls[i]->ncontrols = ncontrols;
1147 EXPORT_SYMBOL(v4l2_ctrl_cluster);
1149 /* Activate/deactivate a control. */
1150 void v4l2_ctrl_activate(struct v4l2_ctrl *ctrl, bool active)
1156 /* set V4L2_CTRL_FLAG_INACTIVE */
1157 set_bit(4, &ctrl->flags);
1159 /* clear V4L2_CTRL_FLAG_INACTIVE */
1160 clear_bit(4, &ctrl->flags);
1162 EXPORT_SYMBOL(v4l2_ctrl_activate);
1164 /* Grab/ungrab a control.
1165 Typically used when streaming starts and you want to grab controls,
1166 preventing the user from changing them.
1168 Just call this and the framework will block any attempts to change
1170 void v4l2_ctrl_grab(struct v4l2_ctrl *ctrl, bool grabbed)
1176 /* set V4L2_CTRL_FLAG_GRABBED */
1177 set_bit(1, &ctrl->flags);
1179 /* clear V4L2_CTRL_FLAG_GRABBED */
1180 clear_bit(1, &ctrl->flags);
1182 EXPORT_SYMBOL(v4l2_ctrl_grab);
1184 /* Log the control name and value */
1185 static void log_ctrl(const struct v4l2_ctrl *ctrl,
1186 const char *prefix, const char *colon)
1188 int fl_inact = ctrl->flags & V4L2_CTRL_FLAG_INACTIVE;
1189 int fl_grabbed = ctrl->flags & V4L2_CTRL_FLAG_GRABBED;
1191 if (ctrl->flags & (V4L2_CTRL_FLAG_DISABLED | V4L2_CTRL_FLAG_WRITE_ONLY))
1193 if (ctrl->type == V4L2_CTRL_TYPE_CTRL_CLASS)
1196 printk(KERN_INFO "%s%s%s: ", prefix, colon, ctrl->name);
1198 switch (ctrl->type) {
1199 case V4L2_CTRL_TYPE_INTEGER:
1200 printk(KERN_CONT "%d", ctrl->cur.val);
1202 case V4L2_CTRL_TYPE_BOOLEAN:
1203 printk(KERN_CONT "%s", ctrl->cur.val ? "true" : "false");
1205 case V4L2_CTRL_TYPE_MENU:
1206 printk(KERN_CONT "%s", ctrl->qmenu[ctrl->cur.val]);
1208 case V4L2_CTRL_TYPE_INTEGER64:
1209 printk(KERN_CONT "%lld", ctrl->cur.val64);
1211 case V4L2_CTRL_TYPE_STRING:
1212 printk(KERN_CONT "%s", ctrl->cur.string);
1215 printk(KERN_CONT "unknown type %d", ctrl->type);
1218 if (fl_inact && fl_grabbed)
1219 printk(KERN_CONT " (inactive, grabbed)\n");
1221 printk(KERN_CONT " (inactive)\n");
1222 else if (fl_grabbed)
1223 printk(KERN_CONT " (grabbed)\n");
1225 printk(KERN_CONT "\n");
1228 /* Log all controls owned by the handler */
1229 void v4l2_ctrl_handler_log_status(struct v4l2_ctrl_handler *hdl,
1232 struct v4l2_ctrl *ctrl;
1233 const char *colon = "";
1240 len = strlen(prefix);
1241 if (len && prefix[len - 1] != ' ')
1243 mutex_lock(&hdl->lock);
1244 list_for_each_entry(ctrl, &hdl->ctrls, node)
1245 if (!(ctrl->flags & V4L2_CTRL_FLAG_DISABLED))
1246 log_ctrl(ctrl, prefix, colon);
1247 mutex_unlock(&hdl->lock);
1249 EXPORT_SYMBOL(v4l2_ctrl_handler_log_status);
1251 /* Call s_ctrl for all controls owned by the handler */
1252 int v4l2_ctrl_handler_setup(struct v4l2_ctrl_handler *hdl)
1254 struct v4l2_ctrl *ctrl;
1259 mutex_lock(&hdl->lock);
1260 list_for_each_entry(ctrl, &hdl->ctrls, node)
1263 list_for_each_entry(ctrl, &hdl->ctrls, node) {
1264 struct v4l2_ctrl *master = ctrl->cluster[0];
1267 /* Skip if this control was already handled by a cluster. */
1271 for (i = 0; i < master->ncontrols; i++)
1272 cur_to_new(master->cluster[i]);
1274 /* Skip button controls and read-only controls. */
1275 if (ctrl->type == V4L2_CTRL_TYPE_BUTTON ||
1276 (ctrl->flags & V4L2_CTRL_FLAG_READ_ONLY))
1278 ret = master->ops->s_ctrl(master);
1281 for (i = 0; i < master->ncontrols; i++)
1282 if (master->cluster[i])
1283 master->cluster[i]->done = true;
1285 mutex_unlock(&hdl->lock);
1288 EXPORT_SYMBOL(v4l2_ctrl_handler_setup);
1290 /* Implement VIDIOC_QUERYCTRL */
1291 int v4l2_queryctrl(struct v4l2_ctrl_handler *hdl, struct v4l2_queryctrl *qc)
1293 u32 id = qc->id & V4L2_CTRL_ID_MASK;
1294 struct v4l2_ctrl_ref *ref;
1295 struct v4l2_ctrl *ctrl;
1300 mutex_lock(&hdl->lock);
1302 /* Try to find it */
1303 ref = find_ref(hdl, id);
1305 if ((qc->id & V4L2_CTRL_FLAG_NEXT_CTRL) && !list_empty(&hdl->ctrl_refs)) {
1306 /* Find the next control with ID > qc->id */
1308 /* Did we reach the end of the control list? */
1309 if (id >= node2id(hdl->ctrl_refs.prev)) {
1310 ref = NULL; /* Yes, so there is no next control */
1312 /* We found a control with the given ID, so just get
1313 the next one in the list. */
1314 ref = list_entry(ref->node.next, typeof(*ref), node);
1316 /* No control with the given ID exists, so start
1317 searching for the next largest ID. We know there
1318 is one, otherwise the first 'if' above would have
1320 list_for_each_entry(ref, &hdl->ctrl_refs, node)
1321 if (id < ref->ctrl->id)
1325 mutex_unlock(&hdl->lock);
1330 memset(qc, 0, sizeof(*qc));
1332 strlcpy(qc->name, ctrl->name, sizeof(qc->name));
1333 qc->minimum = ctrl->minimum;
1334 qc->maximum = ctrl->maximum;
1335 qc->default_value = ctrl->default_value;
1336 if (qc->type == V4L2_CTRL_TYPE_MENU)
1339 qc->step = ctrl->step;
1340 qc->flags = ctrl->flags;
1341 qc->type = ctrl->type;
1344 EXPORT_SYMBOL(v4l2_queryctrl);
1346 int v4l2_subdev_queryctrl(struct v4l2_subdev *sd, struct v4l2_queryctrl *qc)
1348 return v4l2_queryctrl(sd->ctrl_handler, qc);
1350 EXPORT_SYMBOL(v4l2_subdev_queryctrl);
1352 /* Implement VIDIOC_QUERYMENU */
1353 int v4l2_querymenu(struct v4l2_ctrl_handler *hdl, struct v4l2_querymenu *qm)
1355 struct v4l2_ctrl *ctrl;
1358 ctrl = v4l2_ctrl_find(hdl, qm->id);
1364 if (ctrl->qmenu == NULL ||
1365 i < ctrl->minimum || i > ctrl->maximum)
1367 /* Use mask to see if this menu item should be skipped */
1368 if (ctrl->menu_skip_mask & (1 << i))
1370 /* Empty menu items should also be skipped */
1371 if (ctrl->qmenu[i] == NULL || ctrl->qmenu[i][0] == '\0')
1373 strlcpy(qm->name, ctrl->qmenu[i], sizeof(qm->name));
1376 EXPORT_SYMBOL(v4l2_querymenu);
1378 int v4l2_subdev_querymenu(struct v4l2_subdev *sd, struct v4l2_querymenu *qm)
1380 return v4l2_querymenu(sd->ctrl_handler, qm);
1382 EXPORT_SYMBOL(v4l2_subdev_querymenu);
1386 /* Some general notes on the atomic requirements of VIDIOC_G/TRY/S_EXT_CTRLS:
1388 It is not a fully atomic operation, just best-effort only. After all, if
1389 multiple controls have to be set through multiple i2c writes (for example)
1390 then some initial writes may succeed while others fail. Thus leaving the
1391 system in an inconsistent state. The question is how much effort you are
1392 willing to spend on trying to make something atomic that really isn't.
1394 From the point of view of an application the main requirement is that
1395 when you call VIDIOC_S_EXT_CTRLS and some values are invalid then an
1396 error should be returned without actually affecting any controls.
1398 If all the values are correct, then it is acceptable to just give up
1399 in case of low-level errors.
1401 It is important though that the application can tell when only a partial
1402 configuration was done. The way we do that is through the error_idx field
1403 of struct v4l2_ext_controls: if that is equal to the count field then no
1404 controls were affected. Otherwise all controls before that index were
1405 successful in performing their 'get' or 'set' operation, the control at
1406 the given index failed, and you don't know what happened with the controls
1407 after the failed one. Since if they were part of a control cluster they
1408 could have been successfully processed (if a cluster member was encountered
1409 at index < error_idx), they could have failed (if a cluster member was at
1410 error_idx), or they may not have been processed yet (if the first cluster
1411 member appeared after error_idx).
1413 It is all fairly theoretical, though. In practice all you can do is to
1414 bail out. If error_idx == count, then it is an application bug. If
1415 error_idx < count then it is only an application bug if the error code was
1416 EBUSY. That usually means that something started streaming just when you
1417 tried to set the controls. In all other cases it is a driver/hardware
1418 problem and all you can do is to retry or bail out.
1420 Note that these rules do not apply to VIDIOC_TRY_EXT_CTRLS: since that
1421 never modifies controls the error_idx is just set to whatever control
1422 has an invalid value.
1425 /* Prepare for the extended g/s/try functions.
1426 Find the controls in the control array and do some basic checks. */
1427 static int prepare_ext_ctrls(struct v4l2_ctrl_handler *hdl,
1428 struct v4l2_ext_controls *cs,
1429 struct ctrl_helper *helpers,
1434 for (i = 0; i < cs->count; i++) {
1435 struct v4l2_ext_control *c = &cs->controls[i];
1436 struct v4l2_ctrl *ctrl;
1437 u32 id = c->id & V4L2_CTRL_ID_MASK;
1442 if (cs->ctrl_class && V4L2_CTRL_ID2CLASS(id) != cs->ctrl_class)
1445 /* Old-style private controls are not allowed for
1446 extended controls */
1447 if (id >= V4L2_CID_PRIVATE_BASE)
1449 ctrl = v4l2_ctrl_find(hdl, id);
1452 if (ctrl->flags & V4L2_CTRL_FLAG_DISABLED)
1455 helpers[i].ctrl = ctrl;
1456 helpers[i].handled = false;
1461 typedef int (*cluster_func)(struct v4l2_ext_control *c,
1462 struct v4l2_ctrl *ctrl);
1464 /* Walk over all controls in v4l2_ext_controls belonging to the same cluster
1465 and call the provided function. */
1466 static int cluster_walk(unsigned from,
1467 struct v4l2_ext_controls *cs,
1468 struct ctrl_helper *helpers,
1471 struct v4l2_ctrl **cluster = helpers[from].ctrl->cluster;
1475 /* Find any controls from the same cluster and call the function */
1476 for (i = from; !ret && i < cs->count; i++) {
1477 struct v4l2_ctrl *ctrl = helpers[i].ctrl;
1479 if (!helpers[i].handled && ctrl->cluster == cluster)
1480 ret = f(&cs->controls[i], ctrl);
1485 static void cluster_done(unsigned from,
1486 struct v4l2_ext_controls *cs,
1487 struct ctrl_helper *helpers)
1489 struct v4l2_ctrl **cluster = helpers[from].ctrl->cluster;
1492 /* Find any controls from the same cluster and mark them as handled */
1493 for (i = from; i < cs->count; i++)
1494 if (helpers[i].ctrl->cluster == cluster)
1495 helpers[i].handled = true;
1498 /* Handles the corner case where cs->count == 0. It checks whether the
1499 specified control class exists. If that class ID is 0, then it checks
1500 whether there are any controls at all. */
1501 static int class_check(struct v4l2_ctrl_handler *hdl, u32 ctrl_class)
1503 if (ctrl_class == 0)
1504 return list_empty(&hdl->ctrl_refs) ? -EINVAL : 0;
1505 return find_ref_lock(hdl, ctrl_class | 1) ? 0 : -EINVAL;
1510 /* Get extended controls. Allocates the helpers array if needed. */
1511 int v4l2_g_ext_ctrls(struct v4l2_ctrl_handler *hdl, struct v4l2_ext_controls *cs)
1513 struct ctrl_helper helper[4];
1514 struct ctrl_helper *helpers = helper;
1518 cs->error_idx = cs->count;
1519 cs->ctrl_class = V4L2_CTRL_ID2CLASS(cs->ctrl_class);
1525 return class_check(hdl, cs->ctrl_class);
1527 if (cs->count > ARRAY_SIZE(helper)) {
1528 helpers = kmalloc(sizeof(helper[0]) * cs->count, GFP_KERNEL);
1529 if (helpers == NULL)
1533 ret = prepare_ext_ctrls(hdl, cs, helpers, false);
1535 for (i = 0; !ret && i < cs->count; i++)
1536 if (helpers[i].ctrl->flags & V4L2_CTRL_FLAG_WRITE_ONLY)
1539 for (i = 0; !ret && i < cs->count; i++) {
1540 struct v4l2_ctrl *ctrl = helpers[i].ctrl;
1541 struct v4l2_ctrl *master = ctrl->cluster[0];
1543 if (helpers[i].handled)
1548 v4l2_ctrl_lock(master);
1549 /* g_volatile_ctrl will update the current control values */
1550 if (ctrl->is_volatile && master->ops->g_volatile_ctrl)
1551 ret = master->ops->g_volatile_ctrl(master);
1552 /* If OK, then copy the current control values to the caller */
1554 ret = cluster_walk(i, cs, helpers, cur_to_user);
1555 v4l2_ctrl_unlock(master);
1556 cluster_done(i, cs, helpers);
1559 if (cs->count > ARRAY_SIZE(helper))
1563 EXPORT_SYMBOL(v4l2_g_ext_ctrls);
1565 int v4l2_subdev_g_ext_ctrls(struct v4l2_subdev *sd, struct v4l2_ext_controls *cs)
1567 return v4l2_g_ext_ctrls(sd->ctrl_handler, cs);
1569 EXPORT_SYMBOL(v4l2_subdev_g_ext_ctrls);
1571 /* Helper function to get a single control */
1572 static int get_ctrl(struct v4l2_ctrl *ctrl, s32 *val)
1574 struct v4l2_ctrl *master = ctrl->cluster[0];
1577 if (ctrl->flags & V4L2_CTRL_FLAG_WRITE_ONLY)
1580 v4l2_ctrl_lock(master);
1581 /* g_volatile_ctrl will update the current control values */
1582 if (ctrl->is_volatile && master->ops->g_volatile_ctrl)
1583 ret = master->ops->g_volatile_ctrl(master);
1584 *val = ctrl->cur.val;
1585 v4l2_ctrl_unlock(master);
1589 int v4l2_g_ctrl(struct v4l2_ctrl_handler *hdl, struct v4l2_control *control)
1591 struct v4l2_ctrl *ctrl = v4l2_ctrl_find(hdl, control->id);
1593 if (ctrl == NULL || !type_is_int(ctrl))
1595 return get_ctrl(ctrl, &control->value);
1597 EXPORT_SYMBOL(v4l2_g_ctrl);
1599 int v4l2_subdev_g_ctrl(struct v4l2_subdev *sd, struct v4l2_control *control)
1601 return v4l2_g_ctrl(sd->ctrl_handler, control);
1603 EXPORT_SYMBOL(v4l2_subdev_g_ctrl);
1605 s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl)
1609 /* It's a driver bug if this happens. */
1610 WARN_ON(!type_is_int(ctrl));
1611 get_ctrl(ctrl, &val);
1614 EXPORT_SYMBOL(v4l2_ctrl_g_ctrl);
1617 /* Core function that calls try/s_ctrl and ensures that the new value is
1618 copied to the current value on a set.
1619 Must be called with ctrl->handler->lock held. */
1620 static int try_or_set_control_cluster(struct v4l2_ctrl *master, bool set)
1626 /* Go through the cluster and either validate the new value or
1627 (if no new value was set), copy the current value to the new
1628 value, ensuring a consistent view for the control ops when
1630 for (i = 0; !ret && i < master->ncontrols; i++) {
1631 struct v4l2_ctrl *ctrl = master->cluster[i];
1636 if (ctrl->has_new) {
1637 /* Double check this: it may have changed since the
1638 last check in try_or_set_ext_ctrls(). */
1639 if (set && (ctrl->flags & V4L2_CTRL_FLAG_GRABBED))
1642 /* Validate if required */
1644 ret = validate_new(ctrl);
1647 /* No new value was set, so copy the current and force
1648 a call to try_ctrl later, since the values for the cluster
1649 may now have changed and the end result might be invalid. */
1654 /* For larger clusters you have to call try_ctrl again to
1655 verify that the controls are still valid after the
1656 'cur_to_new' above. */
1657 if (!ret && master->ops->try_ctrl && try)
1658 ret = master->ops->try_ctrl(master);
1660 /* Don't set if there is no change */
1661 if (!ret && set && cluster_changed(master)) {
1662 ret = master->ops->s_ctrl(master);
1663 /* If OK, then make the new values permanent. */
1665 for (i = 0; i < master->ncontrols; i++)
1666 new_to_cur(master->cluster[i]);
1671 /* Try or set controls. */
1672 static int try_or_set_ext_ctrls(struct v4l2_ctrl_handler *hdl,
1673 struct v4l2_ext_controls *cs,
1674 struct ctrl_helper *helpers,
1680 cs->error_idx = cs->count;
1681 for (i = 0; i < cs->count; i++) {
1682 struct v4l2_ctrl *ctrl = helpers[i].ctrl;
1687 if (ctrl->flags & V4L2_CTRL_FLAG_READ_ONLY)
1689 /* This test is also done in try_set_control_cluster() which
1690 is called in atomic context, so that has the final say,
1691 but it makes sense to do an up-front check as well. Once
1692 an error occurs in try_set_control_cluster() some other
1693 controls may have been set already and we want to do a
1694 best-effort to avoid that. */
1695 if (set && (ctrl->flags & V4L2_CTRL_FLAG_GRABBED))
1699 for (i = 0; !ret && i < cs->count; i++) {
1700 struct v4l2_ctrl *ctrl = helpers[i].ctrl;
1701 struct v4l2_ctrl *master = ctrl->cluster[0];
1705 if (helpers[i].handled)
1708 v4l2_ctrl_lock(ctrl);
1710 /* Reset the 'has_new' flags of the cluster */
1711 for (j = 0; j < master->ncontrols; j++)
1712 if (master->cluster[j])
1713 master->cluster[j]->has_new = 0;
1715 /* Copy the new caller-supplied control values.
1716 user_to_new() sets 'has_new' to 1. */
1717 ret = cluster_walk(i, cs, helpers, user_to_new);
1720 ret = try_or_set_control_cluster(master, set);
1722 /* Copy the new values back to userspace. */
1724 ret = cluster_walk(i, cs, helpers, new_to_user);
1726 v4l2_ctrl_unlock(ctrl);
1727 cluster_done(i, cs, helpers);
1732 /* Try or try-and-set controls */
1733 static int try_set_ext_ctrls(struct v4l2_ctrl_handler *hdl,
1734 struct v4l2_ext_controls *cs,
1737 struct ctrl_helper helper[4];
1738 struct ctrl_helper *helpers = helper;
1742 cs->error_idx = cs->count;
1743 cs->ctrl_class = V4L2_CTRL_ID2CLASS(cs->ctrl_class);
1749 return class_check(hdl, cs->ctrl_class);
1751 if (cs->count > ARRAY_SIZE(helper)) {
1752 helpers = kmalloc(sizeof(helper[0]) * cs->count, GFP_KERNEL);
1756 ret = prepare_ext_ctrls(hdl, cs, helpers, !set);
1760 /* First 'try' all controls and abort on error */
1761 ret = try_or_set_ext_ctrls(hdl, cs, helpers, false);
1762 /* If this is a 'set' operation and the initial 'try' failed,
1763 then set error_idx to count to tell the application that no
1764 controls changed value yet. */
1766 cs->error_idx = cs->count;
1768 /* Reset 'handled' state */
1769 for (i = 0; i < cs->count; i++)
1770 helpers[i].handled = false;
1771 ret = try_or_set_ext_ctrls(hdl, cs, helpers, true);
1775 if (cs->count > ARRAY_SIZE(helper))
1780 int v4l2_try_ext_ctrls(struct v4l2_ctrl_handler *hdl, struct v4l2_ext_controls *cs)
1782 return try_set_ext_ctrls(hdl, cs, false);
1784 EXPORT_SYMBOL(v4l2_try_ext_ctrls);
1786 int v4l2_s_ext_ctrls(struct v4l2_ctrl_handler *hdl, struct v4l2_ext_controls *cs)
1788 return try_set_ext_ctrls(hdl, cs, true);
1790 EXPORT_SYMBOL(v4l2_s_ext_ctrls);
1792 int v4l2_subdev_try_ext_ctrls(struct v4l2_subdev *sd, struct v4l2_ext_controls *cs)
1794 return try_set_ext_ctrls(sd->ctrl_handler, cs, false);
1796 EXPORT_SYMBOL(v4l2_subdev_try_ext_ctrls);
1798 int v4l2_subdev_s_ext_ctrls(struct v4l2_subdev *sd, struct v4l2_ext_controls *cs)
1800 return try_set_ext_ctrls(sd->ctrl_handler, cs, true);
1802 EXPORT_SYMBOL(v4l2_subdev_s_ext_ctrls);
1804 /* Helper function for VIDIOC_S_CTRL compatibility */
1805 static int set_ctrl(struct v4l2_ctrl *ctrl, s32 *val)
1807 struct v4l2_ctrl *master = ctrl->cluster[0];
1811 v4l2_ctrl_lock(ctrl);
1813 /* Reset the 'has_new' flags of the cluster */
1814 for (i = 0; i < master->ncontrols; i++)
1815 if (master->cluster[i])
1816 master->cluster[i]->has_new = 0;
1820 ret = try_or_set_control_cluster(master, false);
1822 ret = try_or_set_control_cluster(master, true);
1823 *val = ctrl->cur.val;
1824 v4l2_ctrl_unlock(ctrl);
1828 int v4l2_s_ctrl(struct v4l2_ctrl_handler *hdl, struct v4l2_control *control)
1830 struct v4l2_ctrl *ctrl = v4l2_ctrl_find(hdl, control->id);
1832 if (ctrl == NULL || !type_is_int(ctrl))
1835 return set_ctrl(ctrl, &control->value);
1837 EXPORT_SYMBOL(v4l2_s_ctrl);
1839 int v4l2_subdev_s_ctrl(struct v4l2_subdev *sd, struct v4l2_control *control)
1841 return v4l2_s_ctrl(sd->ctrl_handler, control);
1843 EXPORT_SYMBOL(v4l2_subdev_s_ctrl);
1845 int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val)
1847 /* It's a driver bug if this happens. */
1848 WARN_ON(!type_is_int(ctrl));
1849 return set_ctrl(ctrl, &val);
1851 EXPORT_SYMBOL(v4l2_ctrl_s_ctrl);