projects / linux-2.6-block.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
[media] radio-si470x-usb: remove autosuspend, implement suspend/resume
[linux-2.6-block.git] / drivers / media / video / v4l2-ctrls.c
CommitLineData
0996517c
HV		 1/*
2 V4L2 controls framework implementation.
3
4 Copyright (C) 2010 Hans Verkuil <hverkuil@xs4all.nl>
5
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.
10
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.
15
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
19 */
20
21#include <linux/ctype.h>
2b80163c 22#include <linux/slab.h>
35a24636 23#include <linux/export.h>
0996517c
HV		 24#include <media/v4l2-ioctl.h>
25#include <media/v4l2-device.h>
26#include <media/v4l2-ctrls.h>
6e239399 27#include <media/v4l2-event.h>
0996517c
HV		 28#include <media/v4l2-dev.h>
29
ddac5c10
HV		 30#define has_op(master, op) \
31 (master->ops && master->ops->op)
54c911eb 32#define call_op(master, op) \
ddac5c10 33 (has_op(master, op) ? master->ops->op(master) : 0)
54c911eb 34
0996517c 35/* Internal temporary helper struct, one for each v4l2_ext_control */
eb5b16ef
HV		 36struct v4l2_ctrl_helper {
37 /* Pointer to the control reference of the master control */
38 struct v4l2_ctrl_ref *mref;
0996517c
HV		 39 /* The control corresponding to the v4l2_ext_control ID field. */
40 struct v4l2_ctrl *ctrl;
eb5b16ef
HV		 41 /* v4l2_ext_control index of the next control belonging to the
42 same cluster, or 0 if there isn't any. */
43 u32 next;
0996517c
HV		 44};
45
72d877ca 46/* Small helper function to determine if the autocluster is set to manual
88365105 47 mode. */
72d877ca
HV		 48static bool is_cur_manual(const struct v4l2_ctrl *master)
49{
50 return master->is_auto && master->cur.val == master->manual_mode_value;
51}
52
53/* Same as above, but this checks the against the new value instead of the
54 current value. */
55static bool is_new_manual(const struct v4l2_ctrl *master)
56{
57 return master->is_auto && master->val == master->manual_mode_value;
58}
59
0996517c
HV		 60/* Returns NULL or a character pointer array containing the menu for
61 the given control ID. The pointer array ends with a NULL pointer.
62 An empty string signifies a menu entry that is invalid. This allows
63 drivers to disable certain options if it is not supported. */
513521ea 64const char * const *v4l2_ctrl_get_menu(u32 id)
0996517c 65{
513521ea 66 static const char * const mpeg_audio_sampling_freq[] = {
0996517c
HV		 67 "44.1 kHz",
68 "48 kHz",
69 "32 kHz",
70 NULL
71 };
513521ea 72 static const char * const mpeg_audio_encoding[] = {
0996517c
HV		 73 "MPEG-1/2 Layer I",
74 "MPEG-1/2 Layer II",
75 "MPEG-1/2 Layer III",
76 "MPEG-2/4 AAC",
77 "AC-3",
78 NULL
79 };
513521ea 80 static const char * const mpeg_audio_l1_bitrate[] = {
0996517c
HV		 81 "32 kbps",
82 "64 kbps",
83 "96 kbps",
84 "128 kbps",
85 "160 kbps",
86 "192 kbps",
87 "224 kbps",
88 "256 kbps",
89 "288 kbps",
90 "320 kbps",
91 "352 kbps",
92 "384 kbps",
93 "416 kbps",
94 "448 kbps",
95 NULL
96 };
513521ea 97 static const char * const mpeg_audio_l2_bitrate[] = {
0996517c
HV		 98 "32 kbps",
99 "48 kbps",
100 "56 kbps",
101 "64 kbps",
102 "80 kbps",
103 "96 kbps",
104 "112 kbps",
105 "128 kbps",
106 "160 kbps",
107 "192 kbps",
108 "224 kbps",
109 "256 kbps",
110 "320 kbps",
111 "384 kbps",
112 NULL
113 };
513521ea 114 static const char * const mpeg_audio_l3_bitrate[] = {
0996517c
HV		 115 "32 kbps",
116 "40 kbps",
117 "48 kbps",
118 "56 kbps",
119 "64 kbps",
120 "80 kbps",
121 "96 kbps",
122 "112 kbps",
123 "128 kbps",
124 "160 kbps",
125 "192 kbps",
126 "224 kbps",
127 "256 kbps",
128 "320 kbps",
129 NULL
130 };
513521ea 131 static const char * const mpeg_audio_ac3_bitrate[] = {
0996517c
HV		 132 "32 kbps",
133 "40 kbps",
134 "48 kbps",
135 "56 kbps",
136 "64 kbps",
137 "80 kbps",
138 "96 kbps",
139 "112 kbps",
140 "128 kbps",
141 "160 kbps",
142 "192 kbps",
143 "224 kbps",
144 "256 kbps",
145 "320 kbps",
146 "384 kbps",
147 "448 kbps",
148 "512 kbps",
149 "576 kbps",
150 "640 kbps",
151 NULL
152 };
513521ea 153 static const char * const mpeg_audio_mode[] = {
0996517c
HV		 154 "Stereo",
155 "Joint Stereo",
156 "Dual",
157 "Mono",
158 NULL
159 };
513521ea 160 static const char * const mpeg_audio_mode_extension[] = {
0996517c
HV		 161 "Bound 4",
162 "Bound 8",
163 "Bound 12",
164 "Bound 16",
165 NULL
166 };
513521ea 167 static const char * const mpeg_audio_emphasis[] = {
0996517c
HV		 168 "No Emphasis",
169 "50/15 us",
170 "CCITT J17",
171 NULL
172 };
513521ea 173 static const char * const mpeg_audio_crc[] = {
0996517c
HV		 174 "No CRC",
175 "16-bit CRC",
176 NULL
177 };
24c19a21
HV		 178 static const char * const mpeg_audio_dec_playback[] = {
179 "Auto",
180 "Stereo",
181 "Left",
182 "Right",
183 "Mono",
184 "Swapped Stereo",
185 NULL
186 };
513521ea 187 static const char * const mpeg_video_encoding[] = {
0996517c
HV		 188 "MPEG-1",
189 "MPEG-2",
190 "MPEG-4 AVC",
191 NULL
192 };
513521ea 193 static const char * const mpeg_video_aspect[] = {
0996517c
HV		 194 "1x1",
195 "4x3",
196 "16x9",
197 "2.21x1",
198 NULL
199 };
513521ea 200 static const char * const mpeg_video_bitrate_mode[] = {
0996517c
HV		 201 "Variable Bitrate",
202 "Constant Bitrate",
203 NULL
204 };
513521ea 205 static const char * const mpeg_stream_type[] = {
0996517c
HV		 206 "MPEG-2 Program Stream",
207 "MPEG-2 Transport Stream",
208 "MPEG-1 System Stream",
209 "MPEG-2 DVD-compatible Stream",
210 "MPEG-1 VCD-compatible Stream",
211 "MPEG-2 SVCD-compatible Stream",
212 NULL
213 };
513521ea 214 static const char * const mpeg_stream_vbi_fmt[] = {
0996517c 215 "No VBI",
064f5096 216 "Private Packet, IVTV Format",
0996517c
HV		 217 NULL
218 };
513521ea 219 static const char * const camera_power_line_frequency[] = {
0996517c
HV		 220 "Disabled",
221 "50 Hz",
222 "60 Hz",
d26a6635 223 "Auto",
0996517c
HV		 224 NULL
225 };
513521ea 226 static const char * const camera_exposure_auto[] = {
0996517c
HV		 227 "Auto Mode",
228 "Manual Mode",
229 "Shutter Priority Mode",
230 "Aperture Priority Mode",
231 NULL
232 };
513521ea 233 static const char * const colorfx[] = {
0996517c
HV		 234 "None",
235 "Black & White",
236 "Sepia",
237 "Negative",
238 "Emboss",
239 "Sketch",
064f5096
KD		 240 "Sky Blue",
241 "Grass Green",
242 "Skin Whiten",
0996517c
HV		 243 "Vivid",
244 NULL
245 };
513521ea 246 static const char * const tune_preemphasis[] = {
064f5096 247 "No Preemphasis",
f769c260
HV		 248 "50 Microseconds",
249 "75 Microseconds",
0996517c
HV		 250 NULL,
251 };
064f5096
KD		 252 static const char * const header_mode[] = {
253 "Separate Buffer",
254 "Joined With 1st Frame",
255 NULL,
256 };
257 static const char * const multi_slice[] = {
258 "Single",
259 "Max Macroblocks",
260 "Max Bytes",
261 NULL,
262 };
263 static const char * const entropy_mode[] = {
264 "CAVLC",
265 "CABAC",
266 NULL,
267 };
268 static const char * const mpeg_h264_level[] = {
269 "1",
270 "1b",
271 "1.1",
272 "1.2",
273 "1.3",
274 "2",
275 "2.1",
276 "2.2",
277 "3",
278 "3.1",
279 "3.2",
280 "4",
281 "4.1",
282 "4.2",
283 "5",
284 "5.1",
285 NULL,
286 };
287 static const char * const h264_loop_filter[] = {
288 "Enabled",
289 "Disabled",
290 "Disabled at Slice Boundary",
291 NULL,
292 };
293 static const char * const h264_profile[] = {
294 "Baseline",
295 "Constrained Baseline",
296 "Main",
297 "Extended",
298 "High",
299 "High 10",
300 "High 422",
301 "High 444 Predictive",
302 "High 10 Intra",
303 "High 422 Intra",
304 "High 444 Intra",
305 "CAVLC 444 Intra",
306 "Scalable Baseline",
307 "Scalable High",
308 "Scalable High Intra",
309 "Multiview High",
310 NULL,
311 };
312 static const char * const vui_sar_idc[] = {
313 "Unspecified",
314 "1:1",
315 "12:11",
316 "10:11",
317 "16:11",
318 "40:33",
319 "24:11",
320 "20:11",
321 "32:11",
322 "80:33",
323 "18:11",
324 "15:11",
325 "64:33",
326 "160:99",
327 "4:3",
328 "3:2",
329 "2:1",
330 "Extended SAR",
331 NULL,
332 };
333 static const char * const mpeg_mpeg4_level[] = {
334 "0",
335 "0b",
336 "1",
337 "2",
338 "3",
339 "3b",
340 "4",
341 "5",
342 NULL,
343 };
344 static const char * const mpeg4_profile[] = {
345 "Simple",
f769c260 346 "Advanced Simple",
064f5096
KD		 347 "Core",
348 "Simple Scalable",
349 "Advanced Coding Efficency",
350 NULL,
351 };
352
0b159acd
SA		 353 static const char * const flash_led_mode[] = {
354 "Off",
355 "Flash",
356 "Torch",
357 NULL,
358 };
359 static const char * const flash_strobe_source[] = {
360 "Software",
361 "External",
362 NULL,
363 };
0996517c 364
c7361ae1
SN		 365 static const char * const jpeg_chroma_subsampling[] = {
366 "4:4:4",
367 "4:2:2",
368 "4:2:0",
369 "4:1:1",
370 "4:1:0",
371 "Gray",
372 NULL,
373 };
374
0996517c
HV		 375 switch (id) {
376 case V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ:
377 return mpeg_audio_sampling_freq;
378 case V4L2_CID_MPEG_AUDIO_ENCODING:
379 return mpeg_audio_encoding;
380 case V4L2_CID_MPEG_AUDIO_L1_BITRATE:
381 return mpeg_audio_l1_bitrate;
382 case V4L2_CID_MPEG_AUDIO_L2_BITRATE:
383 return mpeg_audio_l2_bitrate;
384 case V4L2_CID_MPEG_AUDIO_L3_BITRATE:
385 return mpeg_audio_l3_bitrate;
386 case V4L2_CID_MPEG_AUDIO_AC3_BITRATE:
387 return mpeg_audio_ac3_bitrate;
388 case V4L2_CID_MPEG_AUDIO_MODE:
389 return mpeg_audio_mode;
390 case V4L2_CID_MPEG_AUDIO_MODE_EXTENSION:
391 return mpeg_audio_mode_extension;
392 case V4L2_CID_MPEG_AUDIO_EMPHASIS:
393 return mpeg_audio_emphasis;
394 case V4L2_CID_MPEG_AUDIO_CRC:
395 return mpeg_audio_crc;
24c19a21
HV		 396 case V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK:
397 case V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK:
398 return mpeg_audio_dec_playback;
0996517c
HV		 399 case V4L2_CID_MPEG_VIDEO_ENCODING:
400 return mpeg_video_encoding;
401 case V4L2_CID_MPEG_VIDEO_ASPECT:
402 return mpeg_video_aspect;
403 case V4L2_CID_MPEG_VIDEO_BITRATE_MODE:
404 return mpeg_video_bitrate_mode;
405 case V4L2_CID_MPEG_STREAM_TYPE:
406 return mpeg_stream_type;
407 case V4L2_CID_MPEG_STREAM_VBI_FMT:
408 return mpeg_stream_vbi_fmt;
409 case V4L2_CID_POWER_LINE_FREQUENCY:
410 return camera_power_line_frequency;
411 case V4L2_CID_EXPOSURE_AUTO:
412 return camera_exposure_auto;
413 case V4L2_CID_COLORFX:
414 return colorfx;
415 case V4L2_CID_TUNE_PREEMPHASIS:
416 return tune_preemphasis;
0b159acd
SA		 417 case V4L2_CID_FLASH_LED_MODE:
418 return flash_led_mode;
419 case V4L2_CID_FLASH_STROBE_SOURCE:
420 return flash_strobe_source;
064f5096
KD		 421 case V4L2_CID_MPEG_VIDEO_HEADER_MODE:
422 return header_mode;
423 case V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE:
424 return multi_slice;
425 case V4L2_CID_MPEG_VIDEO_H264_ENTROPY_MODE:
426 return entropy_mode;
427 case V4L2_CID_MPEG_VIDEO_H264_LEVEL:
428 return mpeg_h264_level;
429 case V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_MODE:
430 return h264_loop_filter;
431 case V4L2_CID_MPEG_VIDEO_H264_PROFILE:
432 return h264_profile;
433 case V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_IDC:
434 return vui_sar_idc;
435 case V4L2_CID_MPEG_VIDEO_MPEG4_LEVEL:
436 return mpeg_mpeg4_level;
437 case V4L2_CID_MPEG_VIDEO_MPEG4_PROFILE:
438 return mpeg4_profile;
c7361ae1
SN		 439 case V4L2_CID_JPEG_CHROMA_SUBSAMPLING:
440 return jpeg_chroma_subsampling;
441
0996517c
HV		 442 default:
443 return NULL;
444 }
445}
446EXPORT_SYMBOL(v4l2_ctrl_get_menu);
447
448/* Return the control name. */
449const char *v4l2_ctrl_get_name(u32 id)
450{
451 switch (id) {
452 /* USER controls */
6c8d6111 453 /* Keep the order of the 'case's the same as in videodev2.h! */
6dd5aff3
MCC		 454 case V4L2_CID_USER_CLASS: return "User Controls";
455 case V4L2_CID_BRIGHTNESS: return "Brightness";
456 case V4L2_CID_CONTRAST: return "Contrast";
457 case V4L2_CID_SATURATION: return "Saturation";
458 case V4L2_CID_HUE: return "Hue";
459 case V4L2_CID_AUDIO_VOLUME: return "Volume";
460 case V4L2_CID_AUDIO_BALANCE: return "Balance";
461 case V4L2_CID_AUDIO_BASS: return "Bass";
462 case V4L2_CID_AUDIO_TREBLE: return "Treble";
463 case V4L2_CID_AUDIO_MUTE: return "Mute";
464 case V4L2_CID_AUDIO_LOUDNESS: return "Loudness";
0996517c
HV		 465 case V4L2_CID_BLACK_LEVEL: return "Black Level";
466 case V4L2_CID_AUTO_WHITE_BALANCE: return "White Balance, Automatic";
467 case V4L2_CID_DO_WHITE_BALANCE: return "Do White Balance";
468 case V4L2_CID_RED_BALANCE: return "Red Balance";
469 case V4L2_CID_BLUE_BALANCE: return "Blue Balance";
470 case V4L2_CID_GAMMA: return "Gamma";
471 case V4L2_CID_EXPOSURE: return "Exposure";
472 case V4L2_CID_AUTOGAIN: return "Gain, Automatic";
473 case V4L2_CID_GAIN: return "Gain";
474 case V4L2_CID_HFLIP: return "Horizontal Flip";
475 case V4L2_CID_VFLIP: return "Vertical Flip";
476 case V4L2_CID_HCENTER: return "Horizontal Center";
477 case V4L2_CID_VCENTER: return "Vertical Center";
478 case V4L2_CID_POWER_LINE_FREQUENCY: return "Power Line Frequency";
479 case V4L2_CID_HUE_AUTO: return "Hue, Automatic";
480 case V4L2_CID_WHITE_BALANCE_TEMPERATURE: return "White Balance Temperature";
481 case V4L2_CID_SHARPNESS: return "Sharpness";
482 case V4L2_CID_BACKLIGHT_COMPENSATION: return "Backlight Compensation";
483 case V4L2_CID_CHROMA_AGC: return "Chroma AGC";
0996517c
HV		 484 case V4L2_CID_COLOR_KILLER: return "Color Killer";
485 case V4L2_CID_COLORFX: return "Color Effects";
486 case V4L2_CID_AUTOBRIGHTNESS: return "Brightness, Automatic";
487 case V4L2_CID_BAND_STOP_FILTER: return "Band-Stop Filter";
488 case V4L2_CID_ROTATE: return "Rotate";
489 case V4L2_CID_BG_COLOR: return "Background Color";
6c8d6111 490 case V4L2_CID_CHROMA_GAIN: return "Chroma Gain";
008d35f2
JFM		 491 case V4L2_CID_ILLUMINATORS_1: return "Illuminator 1";
492 case V4L2_CID_ILLUMINATORS_2: return "Illuminator 2";
f08aacf8
HV		 493 case V4L2_CID_MIN_BUFFERS_FOR_CAPTURE: return "Min Number of Capture Buffers";
494 case V4L2_CID_MIN_BUFFERS_FOR_OUTPUT: return "Min Number of Output Buffers";
cc1d3272 495 case V4L2_CID_ALPHA_COMPONENT: return "Alpha Component";
0996517c
HV		 496
497 /* MPEG controls */
6c8d6111 498 /* Keep the order of the 'case's the same as in videodev2.h! */
6dd5aff3
MCC		 499 case V4L2_CID_MPEG_CLASS: return "MPEG Encoder Controls";
500 case V4L2_CID_MPEG_STREAM_TYPE: return "Stream Type";
501 case V4L2_CID_MPEG_STREAM_PID_PMT: return "Stream PMT Program ID";
502 case V4L2_CID_MPEG_STREAM_PID_AUDIO: return "Stream Audio Program ID";
503 case V4L2_CID_MPEG_STREAM_PID_VIDEO: return "Stream Video Program ID";
504 case V4L2_CID_MPEG_STREAM_PID_PCR: return "Stream PCR Program ID";
6c8d6111
HV		 505 case V4L2_CID_MPEG_STREAM_PES_ID_AUDIO: return "Stream PES Audio ID";
506 case V4L2_CID_MPEG_STREAM_PES_ID_VIDEO: return "Stream PES Video ID";
507 case V4L2_CID_MPEG_STREAM_VBI_FMT: return "Stream VBI Format";
0996517c 508 case V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ: return "Audio Sampling Frequency";
6dd5aff3
MCC		 509 case V4L2_CID_MPEG_AUDIO_ENCODING: return "Audio Encoding";
510 case V4L2_CID_MPEG_AUDIO_L1_BITRATE: return "Audio Layer I Bitrate";
511 case V4L2_CID_MPEG_AUDIO_L2_BITRATE: return "Audio Layer II Bitrate";
512 case V4L2_CID_MPEG_AUDIO_L3_BITRATE: return "Audio Layer III Bitrate";
513 case V4L2_CID_MPEG_AUDIO_MODE: return "Audio Stereo Mode";
0996517c 514 case V4L2_CID_MPEG_AUDIO_MODE_EXTENSION: return "Audio Stereo Mode Extension";
6dd5aff3
MCC		 515 case V4L2_CID_MPEG_AUDIO_EMPHASIS: return "Audio Emphasis";
516 case V4L2_CID_MPEG_AUDIO_CRC: return "Audio CRC";
517 case V4L2_CID_MPEG_AUDIO_MUTE: return "Audio Mute";
518 case V4L2_CID_MPEG_AUDIO_AAC_BITRATE: return "Audio AAC Bitrate";
519 case V4L2_CID_MPEG_AUDIO_AC3_BITRATE: return "Audio AC-3 Bitrate";
24c19a21
HV		 520 case V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK: return "Audio Playback";
521 case V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK: return "Audio Multilingual Playback";
6dd5aff3
MCC		 522 case V4L2_CID_MPEG_VIDEO_ENCODING: return "Video Encoding";
523 case V4L2_CID_MPEG_VIDEO_ASPECT: return "Video Aspect";
524 case V4L2_CID_MPEG_VIDEO_B_FRAMES: return "Video B Frames";
525 case V4L2_CID_MPEG_VIDEO_GOP_SIZE: return "Video GOP Size";
526 case V4L2_CID_MPEG_VIDEO_GOP_CLOSURE: return "Video GOP Closure";
527 case V4L2_CID_MPEG_VIDEO_PULLDOWN: return "Video Pulldown";
528 case V4L2_CID_MPEG_VIDEO_BITRATE_MODE: return "Video Bitrate Mode";
529 case V4L2_CID_MPEG_VIDEO_BITRATE: return "Video Bitrate";
530 case V4L2_CID_MPEG_VIDEO_BITRATE_PEAK: return "Video Peak Bitrate";
0996517c 531 case V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION: return "Video Temporal Decimation";
6dd5aff3 532 case V4L2_CID_MPEG_VIDEO_MUTE: return "Video Mute";
0996517c 533 case V4L2_CID_MPEG_VIDEO_MUTE_YUV: return "Video Mute YUV";
064f5096
KD		 534 case V4L2_CID_MPEG_VIDEO_DECODER_SLICE_INTERFACE: return "Decoder Slice Interface";
535 case V4L2_CID_MPEG_VIDEO_DECODER_MPEG4_DEBLOCK_FILTER: return "MPEG4 Loop Filter Enable";
f08aacf8 536 case V4L2_CID_MPEG_VIDEO_CYCLIC_INTRA_REFRESH_MB: return "Number of Intra Refresh MBs";
064f5096
KD		 537 case V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE: return "Frame Level Rate Control Enable";
538 case V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE: return "H264 MB Level Rate Control";
539 case V4L2_CID_MPEG_VIDEO_HEADER_MODE: return "Sequence Header Mode";
f08aacf8 540 case V4L2_CID_MPEG_VIDEO_MAX_REF_PIC: return "Max Number of Reference Pics";
064f5096 541 case V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP: return "H263 I-Frame QP Value";
f08aacf8
HV		 542 case V4L2_CID_MPEG_VIDEO_H263_P_FRAME_QP: return "H263 P-Frame QP Value";
543 case V4L2_CID_MPEG_VIDEO_H263_B_FRAME_QP: return "H263 B-Frame QP Value";
064f5096
KD		 544 case V4L2_CID_MPEG_VIDEO_H263_MIN_QP: return "H263 Minimum QP Value";
545 case V4L2_CID_MPEG_VIDEO_H263_MAX_QP: return "H263 Maximum QP Value";
546 case V4L2_CID_MPEG_VIDEO_H264_I_FRAME_QP: return "H264 I-Frame QP Value";
f08aacf8
HV		 547 case V4L2_CID_MPEG_VIDEO_H264_P_FRAME_QP: return "H264 P-Frame QP Value";
548 case V4L2_CID_MPEG_VIDEO_H264_B_FRAME_QP: return "H264 B-Frame QP Value";
064f5096
KD		 549 case V4L2_CID_MPEG_VIDEO_H264_MAX_QP: return "H264 Maximum QP Value";
550 case V4L2_CID_MPEG_VIDEO_H264_MIN_QP: return "H264 Minimum QP Value";
551 case V4L2_CID_MPEG_VIDEO_H264_8X8_TRANSFORM: return "H264 8x8 Transform Enable";
552 case V4L2_CID_MPEG_VIDEO_H264_CPB_SIZE: return "H264 CPB Buffer Size";
f08aacf8
HV		 553 case V4L2_CID_MPEG_VIDEO_H264_ENTROPY_MODE: return "H264 Entropy Mode";
554 case V4L2_CID_MPEG_VIDEO_H264_I_PERIOD: return "H264 I-Frame Period";
064f5096
KD		 555 case V4L2_CID_MPEG_VIDEO_H264_LEVEL: return "H264 Level";
556 case V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_ALPHA: return "H264 Loop Filter Alpha Offset";
557 case V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_BETA: return "H264 Loop Filter Beta Offset";
558 case V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_MODE: return "H264 Loop Filter Mode";
559 case V4L2_CID_MPEG_VIDEO_H264_PROFILE: return "H264 Profile";
560 case V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_HEIGHT: return "Vertical Size of SAR";
561 case V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_WIDTH: return "Horizontal Size of SAR";
562 case V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_ENABLE: return "Aspect Ratio VUI Enable";
563 case V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_IDC: return "VUI Aspect Ratio IDC";
564 case V4L2_CID_MPEG_VIDEO_MPEG4_I_FRAME_QP: return "MPEG4 I-Frame QP Value";
f08aacf8
HV		 565 case V4L2_CID_MPEG_VIDEO_MPEG4_P_FRAME_QP: return "MPEG4 P-Frame QP Value";
566 case V4L2_CID_MPEG_VIDEO_MPEG4_B_FRAME_QP: return "MPEG4 B-Frame QP Value";
064f5096
KD		 567 case V4L2_CID_MPEG_VIDEO_MPEG4_MIN_QP: return "MPEG4 Minimum QP Value";
568 case V4L2_CID_MPEG_VIDEO_MPEG4_MAX_QP: return "MPEG4 Maximum QP Value";
569 case V4L2_CID_MPEG_VIDEO_MPEG4_LEVEL: return "MPEG4 Level";
570 case V4L2_CID_MPEG_VIDEO_MPEG4_PROFILE: return "MPEG4 Profile";
571 case V4L2_CID_MPEG_VIDEO_MPEG4_QPEL: return "Quarter Pixel Search Enable";
f08aacf8
HV		 572 case V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_BYTES: return "Maximum Bytes in a Slice";
573 case V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_MB: return "Number of MBs in a Slice";
574 case V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE: return "Slice Partitioning Method";
064f5096 575 case V4L2_CID_MPEG_VIDEO_VBV_SIZE: return "VBV Buffer Size";
24c19a21
HV		 576 case V4L2_CID_MPEG_VIDEO_DEC_PTS: return "Video Decoder PTS";
577 case V4L2_CID_MPEG_VIDEO_DEC_FRAME: return "Video Decoder Frame Count";
0996517c
HV		 578
579 /* CAMERA controls */
6c8d6111 580 /* Keep the order of the 'case's the same as in videodev2.h! */
0996517c
HV		 581 case V4L2_CID_CAMERA_CLASS: return "Camera Controls";
582 case V4L2_CID_EXPOSURE_AUTO: return "Auto Exposure";
583 case V4L2_CID_EXPOSURE_ABSOLUTE: return "Exposure Time, Absolute";
584 case V4L2_CID_EXPOSURE_AUTO_PRIORITY: return "Exposure, Dynamic Framerate";
585 case V4L2_CID_PAN_RELATIVE: return "Pan, Relative";
586 case V4L2_CID_TILT_RELATIVE: return "Tilt, Relative";
587 case V4L2_CID_PAN_RESET: return "Pan, Reset";
588 case V4L2_CID_TILT_RESET: return "Tilt, Reset";
589 case V4L2_CID_PAN_ABSOLUTE: return "Pan, Absolute";
590 case V4L2_CID_TILT_ABSOLUTE: return "Tilt, Absolute";
591 case V4L2_CID_FOCUS_ABSOLUTE: return "Focus, Absolute";
592 case V4L2_CID_FOCUS_RELATIVE: return "Focus, Relative";
593 case V4L2_CID_FOCUS_AUTO: return "Focus, Automatic";
0996517c
HV		 594 case V4L2_CID_ZOOM_ABSOLUTE: return "Zoom, Absolute";
595 case V4L2_CID_ZOOM_RELATIVE: return "Zoom, Relative";
596 case V4L2_CID_ZOOM_CONTINUOUS: return "Zoom, Continuous";
597 case V4L2_CID_PRIVACY: return "Privacy";
6c8d6111
HV		 598 case V4L2_CID_IRIS_ABSOLUTE: return "Iris, Absolute";
599 case V4L2_CID_IRIS_RELATIVE: return "Iris, Relative";
0996517c
HV		 600
601 /* FM Radio Modulator control */
6c8d6111 602 /* Keep the order of the 'case's the same as in videodev2.h! */
0996517c
HV		 603 case V4L2_CID_FM_TX_CLASS: return "FM Radio Modulator Controls";
604 case V4L2_CID_RDS_TX_DEVIATION: return "RDS Signal Deviation";
605 case V4L2_CID_RDS_TX_PI: return "RDS Program ID";
606 case V4L2_CID_RDS_TX_PTY: return "RDS Program Type";
607 case V4L2_CID_RDS_TX_PS_NAME: return "RDS PS Name";
608 case V4L2_CID_RDS_TX_RADIO_TEXT: return "RDS Radio Text";
609 case V4L2_CID_AUDIO_LIMITER_ENABLED: return "Audio Limiter Feature Enabled";
610 case V4L2_CID_AUDIO_LIMITER_RELEASE_TIME: return "Audio Limiter Release Time";
611 case V4L2_CID_AUDIO_LIMITER_DEVIATION: return "Audio Limiter Deviation";
f08aacf8 612 case V4L2_CID_AUDIO_COMPRESSION_ENABLED: return "Audio Compression Enabled";
0996517c
HV		 613 case V4L2_CID_AUDIO_COMPRESSION_GAIN: return "Audio Compression Gain";
614 case V4L2_CID_AUDIO_COMPRESSION_THRESHOLD: return "Audio Compression Threshold";
615 case V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME: return "Audio Compression Attack Time";
616 case V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME: return "Audio Compression Release Time";
617 case V4L2_CID_PILOT_TONE_ENABLED: return "Pilot Tone Feature Enabled";
618 case V4L2_CID_PILOT_TONE_DEVIATION: return "Pilot Tone Deviation";
619 case V4L2_CID_PILOT_TONE_FREQUENCY: return "Pilot Tone Frequency";
f08aacf8 620 case V4L2_CID_TUNE_PREEMPHASIS: return "Pre-Emphasis";
0996517c
HV		 621 case V4L2_CID_TUNE_POWER_LEVEL: return "Tune Power Level";
622 case V4L2_CID_TUNE_ANTENNA_CAPACITOR: return "Tune Antenna Capacitor";
623
0b159acd 624 /* Flash controls */
f08aacf8
HV		 625 case V4L2_CID_FLASH_CLASS: return "Flash Controls";
626 case V4L2_CID_FLASH_LED_MODE: return "LED Mode";
627 case V4L2_CID_FLASH_STROBE_SOURCE: return "Strobe Source";
0b159acd 628 case V4L2_CID_FLASH_STROBE: return "Strobe";
f08aacf8
HV		 629 case V4L2_CID_FLASH_STROBE_STOP: return "Stop Strobe";
630 case V4L2_CID_FLASH_STROBE_STATUS: return "Strobe Status";
631 case V4L2_CID_FLASH_TIMEOUT: return "Strobe Timeout";
632 case V4L2_CID_FLASH_INTENSITY: return "Intensity, Flash Mode";
633 case V4L2_CID_FLASH_TORCH_INTENSITY: return "Intensity, Torch Mode";
634 case V4L2_CID_FLASH_INDICATOR_INTENSITY: return "Intensity, Indicator";
0b159acd
SA		 635 case V4L2_CID_FLASH_FAULT: return "Faults";
636 case V4L2_CID_FLASH_CHARGE: return "Charge";
f08aacf8 637 case V4L2_CID_FLASH_READY: return "Ready to Strobe";
0b159acd 638
c7361ae1
SN		 639 /* JPEG encoder controls */
640 /* Keep the order of the 'case's the same as in videodev2.h! */
641 case V4L2_CID_JPEG_CLASS: return "JPEG Compression Controls";
642 case V4L2_CID_JPEG_CHROMA_SUBSAMPLING: return "Chroma Subsampling";
643 case V4L2_CID_JPEG_RESTART_INTERVAL: return "Restart Interval";
644 case V4L2_CID_JPEG_COMPRESSION_QUALITY: return "Compression Quality";
645 case V4L2_CID_JPEG_ACTIVE_MARKER: return "Active Markers";
646
8c9d236e
SA		 647 /* Image source controls */
648 case V4L2_CID_IMAGE_SOURCE_CLASS: return "Image Source Controls";
649 case V4L2_CID_VBLANK: return "Vertical Blanking";
650 case V4L2_CID_HBLANK: return "Horizontal Blanking";
651 case V4L2_CID_ANALOGUE_GAIN: return "Analogue Gain";
652
c643ee13
SA		 653 /* Image processing controls */
654 case V4L2_CID_IMAGE_PROC_CLASS: return "Image Processing Controls";
655 case V4L2_CID_LINK_FREQ: return "Link Frequency";
656 case V4L2_CID_PIXEL_RATE: return "Pixel Rate";
657
0996517c
HV		 658 default:
659 return NULL;
660 }
661}
662EXPORT_SYMBOL(v4l2_ctrl_get_name);
663
664void v4l2_ctrl_fill(u32 id, const char **name, enum v4l2_ctrl_type *type,
665 s32 *min, s32 *max, s32 *step, s32 *def, u32 *flags)
666{
667 *name = v4l2_ctrl_get_name(id);
668 *flags = 0;
669
670 switch (id) {
671 case V4L2_CID_AUDIO_MUTE:
672 case V4L2_CID_AUDIO_LOUDNESS:
673 case V4L2_CID_AUTO_WHITE_BALANCE:
674 case V4L2_CID_AUTOGAIN:
675 case V4L2_CID_HFLIP:
676 case V4L2_CID_VFLIP:
677 case V4L2_CID_HUE_AUTO:
678 case V4L2_CID_CHROMA_AGC:
679 case V4L2_CID_COLOR_KILLER:
680 case V4L2_CID_MPEG_AUDIO_MUTE:
681 case V4L2_CID_MPEG_VIDEO_MUTE:
682 case V4L2_CID_MPEG_VIDEO_GOP_CLOSURE:
683 case V4L2_CID_MPEG_VIDEO_PULLDOWN:
684 case V4L2_CID_EXPOSURE_AUTO_PRIORITY:
685 case V4L2_CID_FOCUS_AUTO:
686 case V4L2_CID_PRIVACY:
687 case V4L2_CID_AUDIO_LIMITER_ENABLED:
688 case V4L2_CID_AUDIO_COMPRESSION_ENABLED:
689 case V4L2_CID_PILOT_TONE_ENABLED:
008d35f2
JFM		 690 case V4L2_CID_ILLUMINATORS_1:
691 case V4L2_CID_ILLUMINATORS_2:
0b159acd
SA		 692 case V4L2_CID_FLASH_STROBE_STATUS:
693 case V4L2_CID_FLASH_CHARGE:
694 case V4L2_CID_FLASH_READY:
064f5096
KD		 695 case V4L2_CID_MPEG_VIDEO_DECODER_MPEG4_DEBLOCK_FILTER:
696 case V4L2_CID_MPEG_VIDEO_DECODER_SLICE_INTERFACE:
697 case V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE:
698 case V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE:
699 case V4L2_CID_MPEG_VIDEO_H264_8X8_TRANSFORM:
700 case V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_ENABLE:
701 case V4L2_CID_MPEG_VIDEO_MPEG4_QPEL:
0996517c
HV		 702 *type = V4L2_CTRL_TYPE_BOOLEAN;
703 *min = 0;
704 *max = *step = 1;
705 break;
706 case V4L2_CID_PAN_RESET:
707 case V4L2_CID_TILT_RESET:
0b159acd
SA		 708 case V4L2_CID_FLASH_STROBE:
709 case V4L2_CID_FLASH_STROBE_STOP:
0996517c
HV		 710 *type = V4L2_CTRL_TYPE_BUTTON;
711 *flags |= V4L2_CTRL_FLAG_WRITE_ONLY;
712 *min = *max = *step = *def = 0;
713 break;
714 case V4L2_CID_POWER_LINE_FREQUENCY:
715 case V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ:
716 case V4L2_CID_MPEG_AUDIO_ENCODING:
717 case V4L2_CID_MPEG_AUDIO_L1_BITRATE:
718 case V4L2_CID_MPEG_AUDIO_L2_BITRATE:
719 case V4L2_CID_MPEG_AUDIO_L3_BITRATE:
720 case V4L2_CID_MPEG_AUDIO_AC3_BITRATE:
721 case V4L2_CID_MPEG_AUDIO_MODE:
722 case V4L2_CID_MPEG_AUDIO_MODE_EXTENSION:
723 case V4L2_CID_MPEG_AUDIO_EMPHASIS:
724 case V4L2_CID_MPEG_AUDIO_CRC:
24c19a21
HV		 725 case V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK:
726 case V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK:
0996517c
HV		 727 case V4L2_CID_MPEG_VIDEO_ENCODING:
728 case V4L2_CID_MPEG_VIDEO_ASPECT:
729 case V4L2_CID_MPEG_VIDEO_BITRATE_MODE:
730 case V4L2_CID_MPEG_STREAM_TYPE:
731 case V4L2_CID_MPEG_STREAM_VBI_FMT:
732 case V4L2_CID_EXPOSURE_AUTO:
733 case V4L2_CID_COLORFX:
734 case V4L2_CID_TUNE_PREEMPHASIS:
0b159acd
SA		 735 case V4L2_CID_FLASH_LED_MODE:
736 case V4L2_CID_FLASH_STROBE_SOURCE:
064f5096
KD		 737 case V4L2_CID_MPEG_VIDEO_HEADER_MODE:
738 case V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE:
739 case V4L2_CID_MPEG_VIDEO_H264_ENTROPY_MODE:
740 case V4L2_CID_MPEG_VIDEO_H264_LEVEL:
741 case V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_MODE:
742 case V4L2_CID_MPEG_VIDEO_H264_PROFILE:
743 case V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_IDC:
744 case V4L2_CID_MPEG_VIDEO_MPEG4_LEVEL:
745 case V4L2_CID_MPEG_VIDEO_MPEG4_PROFILE:
c7361ae1 746 case V4L2_CID_JPEG_CHROMA_SUBSAMPLING:
0996517c
HV		 747 *type = V4L2_CTRL_TYPE_MENU;
748 break;
c643ee13
SA		 749 case V4L2_CID_LINK_FREQ:
750 *type = V4L2_CTRL_TYPE_INTEGER_MENU;
751 break;
0996517c
HV		 752 case V4L2_CID_RDS_TX_PS_NAME:
753 case V4L2_CID_RDS_TX_RADIO_TEXT:
754 *type = V4L2_CTRL_TYPE_STRING;
755 break;
756 case V4L2_CID_USER_CLASS:
757 case V4L2_CID_CAMERA_CLASS:
758 case V4L2_CID_MPEG_CLASS:
759 case V4L2_CID_FM_TX_CLASS:
0b159acd 760 case V4L2_CID_FLASH_CLASS:
c7361ae1 761 case V4L2_CID_JPEG_CLASS:
8c9d236e 762 case V4L2_CID_IMAGE_SOURCE_CLASS:
c643ee13 763 case V4L2_CID_IMAGE_PROC_CLASS:
0996517c
HV		 764 *type = V4L2_CTRL_TYPE_CTRL_CLASS;
765 /* You can neither read not write these */
766 *flags |= V4L2_CTRL_FLAG_READ_ONLY | V4L2_CTRL_FLAG_WRITE_ONLY;
767 *min = *max = *step = *def = 0;
768 break;
769 case V4L2_CID_BG_COLOR:
770 *type = V4L2_CTRL_TYPE_INTEGER;
771 *step = 1;
772 *min = 0;
773 /* Max is calculated as RGB888 that is 2^24 */
774 *max = 0xFFFFFF;
775 break;
0b159acd 776 case V4L2_CID_FLASH_FAULT:
c7361ae1 777 case V4L2_CID_JPEG_ACTIVE_MARKER:
0b159acd
SA		 778 *type = V4L2_CTRL_TYPE_BITMASK;
779 break;
064f5096
KD		 780 case V4L2_CID_MIN_BUFFERS_FOR_CAPTURE:
781 case V4L2_CID_MIN_BUFFERS_FOR_OUTPUT:
782 *type = V4L2_CTRL_TYPE_INTEGER;
783 *flags |= V4L2_CTRL_FLAG_READ_ONLY;
784 break;
24c19a21
HV		 785 case V4L2_CID_MPEG_VIDEO_DEC_FRAME:
786 case V4L2_CID_MPEG_VIDEO_DEC_PTS:
c643ee13
SA		 787 *flags |= V4L2_CTRL_FLAG_VOLATILE;
788 /* Fall through */
789 case V4L2_CID_PIXEL_RATE:
24c19a21 790 *type = V4L2_CTRL_TYPE_INTEGER64;
c643ee13 791 *flags |= V4L2_CTRL_FLAG_READ_ONLY;
ca576811 792 *min = *max = *step = *def = 0;
24c19a21 793 break;
0996517c
HV		 794 default:
795 *type = V4L2_CTRL_TYPE_INTEGER;
796 break;
797 }
798 switch (id) {
799 case V4L2_CID_MPEG_AUDIO_ENCODING:
800 case V4L2_CID_MPEG_AUDIO_MODE:
801 case V4L2_CID_MPEG_VIDEO_BITRATE_MODE:
802 case V4L2_CID_MPEG_VIDEO_B_FRAMES:
803 case V4L2_CID_MPEG_STREAM_TYPE:
804 *flags |= V4L2_CTRL_FLAG_UPDATE;
805 break;
806 case V4L2_CID_AUDIO_VOLUME:
807 case V4L2_CID_AUDIO_BALANCE:
808 case V4L2_CID_AUDIO_BASS:
809 case V4L2_CID_AUDIO_TREBLE:
810 case V4L2_CID_BRIGHTNESS:
811 case V4L2_CID_CONTRAST:
812 case V4L2_CID_SATURATION:
813 case V4L2_CID_HUE:
814 case V4L2_CID_RED_BALANCE:
815 case V4L2_CID_BLUE_BALANCE:
816 case V4L2_CID_GAMMA:
817 case V4L2_CID_SHARPNESS:
818 case V4L2_CID_CHROMA_GAIN:
819 case V4L2_CID_RDS_TX_DEVIATION:
820 case V4L2_CID_AUDIO_LIMITER_RELEASE_TIME:
821 case V4L2_CID_AUDIO_LIMITER_DEVIATION:
822 case V4L2_CID_AUDIO_COMPRESSION_GAIN:
823 case V4L2_CID_AUDIO_COMPRESSION_THRESHOLD:
824 case V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME:
825 case V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME:
826 case V4L2_CID_PILOT_TONE_DEVIATION:
827 case V4L2_CID_PILOT_TONE_FREQUENCY:
828 case V4L2_CID_TUNE_POWER_LEVEL:
829 case V4L2_CID_TUNE_ANTENNA_CAPACITOR:
830 *flags |= V4L2_CTRL_FLAG_SLIDER;
831 break;
832 case V4L2_CID_PAN_RELATIVE:
833 case V4L2_CID_TILT_RELATIVE:
834 case V4L2_CID_FOCUS_RELATIVE:
835 case V4L2_CID_IRIS_RELATIVE:
836 case V4L2_CID_ZOOM_RELATIVE:
837 *flags |= V4L2_CTRL_FLAG_WRITE_ONLY;
838 break;
0b159acd
SA		 839 case V4L2_CID_FLASH_STROBE_STATUS:
840 case V4L2_CID_FLASH_READY:
841 *flags |= V4L2_CTRL_FLAG_READ_ONLY;
842 break;
0996517c
HV		 843 }
844}
845EXPORT_SYMBOL(v4l2_ctrl_fill);
846
847/* Helper function to determine whether the control type is compatible with
848 VIDIOC_G/S_CTRL. */
849static bool type_is_int(const struct v4l2_ctrl *ctrl)
850{
851 switch (ctrl->type) {
852 case V4L2_CTRL_TYPE_INTEGER64:
853 case V4L2_CTRL_TYPE_STRING:
854 /* Nope, these need v4l2_ext_control */
855 return false;
856 default:
857 return true;
858 }
859}
860
6e239399
HV		 861static void fill_event(struct v4l2_event *ev, struct v4l2_ctrl *ctrl, u32 changes)
862{
863 memset(ev->reserved, 0, sizeof(ev->reserved));
864 ev->type = V4L2_EVENT_CTRL;
865 ev->id = ctrl->id;
866 ev->u.ctrl.changes = changes;
867 ev->u.ctrl.type = ctrl->type;
868 ev->u.ctrl.flags = ctrl->flags;
869 if (ctrl->type == V4L2_CTRL_TYPE_STRING)
870 ev->u.ctrl.value64 = 0;
871 else
872 ev->u.ctrl.value64 = ctrl->cur.val64;
873 ev->u.ctrl.minimum = ctrl->minimum;
874 ev->u.ctrl.maximum = ctrl->maximum;
ce580fe5
SA		 875 if (ctrl->type == V4L2_CTRL_TYPE_MENU
876 || ctrl->type == V4L2_CTRL_TYPE_INTEGER_MENU)
6e239399
HV		 877 ev->u.ctrl.step = 1;
878 else
879 ev->u.ctrl.step = ctrl->step;
880 ev->u.ctrl.default_value = ctrl->default_value;
881}
882
883static void send_event(struct v4l2_fh *fh, struct v4l2_ctrl *ctrl, u32 changes)
884{
885 struct v4l2_event ev;
77068d36 886 struct v4l2_subscribed_event *sev;
6e239399 887
77068d36 888 if (list_empty(&ctrl->ev_subs))
3f66f0ed 889 return;
6e239399
HV		 890 fill_event(&ev, ctrl, changes);
891
77068d36 892 list_for_each_entry(sev, &ctrl->ev_subs, node)
e3e72f39
HG		 893 if (sev->fh != fh ||
894 (sev->flags & V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK))
77068d36 895 v4l2_event_queue_fh(sev->fh, &ev);
6e239399
HV		 896}
897
0996517c
HV		 898/* Helper function: copy the current control value back to the caller */
899static int cur_to_user(struct v4l2_ext_control *c,
900 struct v4l2_ctrl *ctrl)
901{
902 u32 len;
903
904 switch (ctrl->type) {
905 case V4L2_CTRL_TYPE_STRING:
906 len = strlen(ctrl->cur.string);
907 if (c->size < len + 1) {
908 c->size = len + 1;
909 return -ENOSPC;
910 }
911 return copy_to_user(c->string, ctrl->cur.string,
912 len + 1) ? -EFAULT : 0;
913 case V4L2_CTRL_TYPE_INTEGER64:
914 c->value64 = ctrl->cur.val64;
915 break;
916 default:
917 c->value = ctrl->cur.val;
918 break;
919 }
920 return 0;
921}
922
923/* Helper function: copy the caller-provider value as the new control value */
924static int user_to_new(struct v4l2_ext_control *c,
925 struct v4l2_ctrl *ctrl)
926{
927 int ret;
928 u32 size;
929
2a863793 930 ctrl->is_new = 1;
0996517c
HV		 931 switch (ctrl->type) {
932 case V4L2_CTRL_TYPE_INTEGER64:
933 ctrl->val64 = c->value64;
934 break;
935 case V4L2_CTRL_TYPE_STRING:
936 size = c->size;
937 if (size == 0)
938 return -ERANGE;
939 if (size > ctrl->maximum + 1)
940 size = ctrl->maximum + 1;
941 ret = copy_from_user(ctrl->string, c->string, size);
942 if (!ret) {
943 char last = ctrl->string[size - 1];
944
945 ctrl->string[size - 1] = 0;
946 /* If the string was longer than ctrl->maximum,
947 then return an error. */
948 if (strlen(ctrl->string) == ctrl->maximum && last)
949 return -ERANGE;
950 }
951 return ret ? -EFAULT : 0;
952 default:
953 ctrl->val = c->value;
954 break;
955 }
956 return 0;
957}
958
959/* Helper function: copy the new control value back to the caller */
960static int new_to_user(struct v4l2_ext_control *c,
961 struct v4l2_ctrl *ctrl)
962{
963 u32 len;
964
965 switch (ctrl->type) {
966 case V4L2_CTRL_TYPE_STRING:
967 len = strlen(ctrl->string);
968 if (c->size < len + 1) {
969 c->size = ctrl->maximum + 1;
970 return -ENOSPC;
971 }
972 return copy_to_user(c->string, ctrl->string,
973 len + 1) ? -EFAULT : 0;
974 case V4L2_CTRL_TYPE_INTEGER64:
975 c->value64 = ctrl->val64;
976 break;
977 default:
978 c->value = ctrl->val;
979 break;
980 }
981 return 0;
982}
983
984/* Copy the new value to the current value. */
ab892bac
HV		 985static void new_to_cur(struct v4l2_fh *fh, struct v4l2_ctrl *ctrl,
986 bool update_inactive)
0996517c 987{
6e239399
HV		 988 bool changed = false;
989
0996517c
HV		 990 if (ctrl == NULL)
991 return;
992 switch (ctrl->type) {
6e239399
HV		 993 case V4L2_CTRL_TYPE_BUTTON:
994 changed = true;
995 break;
0996517c
HV		 996 case V4L2_CTRL_TYPE_STRING:
997 /* strings are always 0-terminated */
6e239399 998 changed = strcmp(ctrl->string, ctrl->cur.string);
0996517c
HV		 999 strcpy(ctrl->cur.string, ctrl->string);
1000 break;
1001 case V4L2_CTRL_TYPE_INTEGER64:
6e239399 1002 changed = ctrl->val64 != ctrl->cur.val64;
0996517c
HV		 1003 ctrl->cur.val64 = ctrl->val64;
1004 break;
1005 default:
6e239399 1006 changed = ctrl->val != ctrl->cur.val;
0996517c
HV		 1007 ctrl->cur.val = ctrl->val;
1008 break;
1009 }
72d877ca 1010 if (update_inactive) {
5626b8c7
HV		 1011 /* Note: update_inactive can only be true for auto clusters. */
1012 ctrl->flags &=
1013 ~(V4L2_CTRL_FLAG_INACTIVE | V4L2_CTRL_FLAG_VOLATILE);
1014 if (!is_cur_manual(ctrl->cluster[0])) {
72d877ca 1015 ctrl->flags |= V4L2_CTRL_FLAG_INACTIVE;
5626b8c7
HV		 1016 if (ctrl->cluster[0]->has_volatiles)
1017 ctrl->flags |= V4L2_CTRL_FLAG_VOLATILE;
1018 }
1249a3a8 1019 fh = NULL;
72d877ca 1020 }
639884a6
HV		 1021 if (changed || update_inactive) {
1022 /* If a control was changed that was not one of the controls
1023 modified by the application, then send the event to all. */
1024 if (!ctrl->is_new)
1025 fh = NULL;
6e239399
HV		 1026 send_event(fh, ctrl,
1027 (changed ? V4L2_EVENT_CTRL_CH_VALUE : 0) |
1028 (update_inactive ? V4L2_EVENT_CTRL_CH_FLAGS : 0));
639884a6 1029 }
0996517c
HV		 1030}
1031
1032/* Copy the current value to the new value */
1033static void cur_to_new(struct v4l2_ctrl *ctrl)
1034{
1035 if (ctrl == NULL)
1036 return;
1037 switch (ctrl->type) {
1038 case V4L2_CTRL_TYPE_STRING:
1039 /* strings are always 0-terminated */
1040 strcpy(ctrl->string, ctrl->cur.string);
1041 break;
1042 case V4L2_CTRL_TYPE_INTEGER64:
1043 ctrl->val64 = ctrl->cur.val64;
1044 break;
1045 default:
1046 ctrl->val = ctrl->cur.val;
1047 break;
1048 }
1049}
1050
1051/* Return non-zero if one or more of the controls in the cluster has a new
1052 value that differs from the current value. */
1053static int cluster_changed(struct v4l2_ctrl *master)
1054{
1055 int diff = 0;
1056 int i;
1057
1058 for (i = 0; !diff && i < master->ncontrols; i++) {
1059 struct v4l2_ctrl *ctrl = master->cluster[i];
1060
1061 if (ctrl == NULL)
1062 continue;
1063 switch (ctrl->type) {
1064 case V4L2_CTRL_TYPE_BUTTON:
1065 /* Button controls are always 'different' */
1066 return 1;
1067 case V4L2_CTRL_TYPE_STRING:
1068 /* strings are always 0-terminated */
1069 diff = strcmp(ctrl->string, ctrl->cur.string);
1070 break;
1071 case V4L2_CTRL_TYPE_INTEGER64:
1072 diff = ctrl->val64 != ctrl->cur.val64;
1073 break;
1074 default:
1075 diff = ctrl->val != ctrl->cur.val;
1076 break;
1077 }
1078 }
1079 return diff;
1080}
1081
eb5b16ef
HV		 1082/* Validate integer-type control */
1083static int validate_new_int(const struct v4l2_ctrl *ctrl, s32 *pval)
0996517c 1084{
eb5b16ef 1085 s32 val = *pval;
0996517c 1086 u32 offset;
0996517c
HV		 1087
1088 switch (ctrl->type) {
1089 case V4L2_CTRL_TYPE_INTEGER:
1090 /* Round towards the closest legal value */
1091 val += ctrl->step / 2;
1092 if (val < ctrl->minimum)
1093 val = ctrl->minimum;
1094 if (val > ctrl->maximum)
1095 val = ctrl->maximum;
1096 offset = val - ctrl->minimum;
1097 offset = ctrl->step * (offset / ctrl->step);
1098 val = ctrl->minimum + offset;
eb5b16ef 1099 *pval = val;
0996517c
HV		 1100 return 0;
1101
1102 case V4L2_CTRL_TYPE_BOOLEAN:
eb5b16ef 1103 *pval = !!val;
0996517c
HV		 1104 return 0;
1105
1106 case V4L2_CTRL_TYPE_MENU:
ce580fe5 1107 case V4L2_CTRL_TYPE_INTEGER_MENU:
0996517c
HV		 1108 if (val < ctrl->minimum || val > ctrl->maximum)
1109 return -ERANGE;
ce580fe5
SA		 1110 if (ctrl->menu_skip_mask & (1 << val))
1111 return -EINVAL;
1112 if (ctrl->type == V4L2_CTRL_TYPE_MENU &&
1113 ctrl->qmenu[val][0] == '\0')
0996517c
HV		 1114 return -EINVAL;
1115 return 0;
1116
fa4d7096
HV		 1117 case V4L2_CTRL_TYPE_BITMASK:
1118 *pval &= ctrl->maximum;
1119 return 0;
1120
0996517c
HV		 1121 case V4L2_CTRL_TYPE_BUTTON:
1122 case V4L2_CTRL_TYPE_CTRL_CLASS:
eb5b16ef 1123 *pval = 0;
0996517c
HV		 1124 return 0;
1125
eb5b16ef
HV		 1126 default:
1127 return -EINVAL;
1128 }
1129}
1130
1131/* Validate a new control */
1132static int validate_new(const struct v4l2_ctrl *ctrl, struct v4l2_ext_control *c)
1133{
1134 char *s = c->string;
1135 size_t len;
1136
1137 switch (ctrl->type) {
1138 case V4L2_CTRL_TYPE_INTEGER:
1139 case V4L2_CTRL_TYPE_BOOLEAN:
1140 case V4L2_CTRL_TYPE_MENU:
ce580fe5 1141 case V4L2_CTRL_TYPE_INTEGER_MENU:
fa4d7096 1142 case V4L2_CTRL_TYPE_BITMASK:
eb5b16ef
HV		 1143 case V4L2_CTRL_TYPE_BUTTON:
1144 case V4L2_CTRL_TYPE_CTRL_CLASS:
1145 return validate_new_int(ctrl, &c->value);
1146
0996517c
HV		 1147 case V4L2_CTRL_TYPE_INTEGER64:
1148 return 0;
1149
1150 case V4L2_CTRL_TYPE_STRING:
1151 len = strlen(s);
1152 if (len < ctrl->minimum)
1153 return -ERANGE;
1154 if ((len - ctrl->minimum) % ctrl->step)
1155 return -ERANGE;
1156 return 0;
1157
1158 default:
1159 return -EINVAL;
1160 }
1161}
1162
1163static inline u32 node2id(struct list_head *node)
1164{
1165 return list_entry(node, struct v4l2_ctrl_ref, node)->ctrl->id;
1166}
1167
1168/* Set the handler's error code if it wasn't set earlier already */
1169static inline int handler_set_err(struct v4l2_ctrl_handler *hdl, int err)
1170{
1171 if (hdl->error == 0)
1172 hdl->error = err;
1173 return err;
1174}
1175
1176/* Initialize the handler */
1177int v4l2_ctrl_handler_init(struct v4l2_ctrl_handler *hdl,
1178 unsigned nr_of_controls_hint)
1179{
77e7c4e6
SA		 1180 hdl->lock = &hdl->_lock;
1181 mutex_init(hdl->lock);
0996517c
HV		 1182 INIT_LIST_HEAD(&hdl->ctrls);
1183 INIT_LIST_HEAD(&hdl->ctrl_refs);
1184 hdl->nr_of_buckets = 1 + nr_of_controls_hint / 8;
9884d7be
TM		 1185 hdl->buckets = kcalloc(hdl->nr_of_buckets, sizeof(hdl->buckets[0]),
1186 GFP_KERNEL);
0996517c
HV		 1187 hdl->error = hdl->buckets ? 0 : -ENOMEM;
1188 return hdl->error;
1189}
1190EXPORT_SYMBOL(v4l2_ctrl_handler_init);
1191
1192/* Free all controls and control refs */
1193void v4l2_ctrl_handler_free(struct v4l2_ctrl_handler *hdl)
1194{
1195 struct v4l2_ctrl_ref *ref, *next_ref;
1196 struct v4l2_ctrl *ctrl, *next_ctrl;
77068d36 1197 struct v4l2_subscribed_event *sev, *next_sev;
0996517c
HV		 1198
1199 if (hdl == NULL || hdl->buckets == NULL)
1200 return;
1201
77e7c4e6 1202 mutex_lock(hdl->lock);
0996517c
HV		 1203 /* Free all nodes */
1204 list_for_each_entry_safe(ref, next_ref, &hdl->ctrl_refs, node) {
1205 list_del(&ref->node);
1206 kfree(ref);
1207 }
1208 /* Free all controls owned by the handler */
1209 list_for_each_entry_safe(ctrl, next_ctrl, &hdl->ctrls, node) {
1210 list_del(&ctrl->node);
77068d36
HV		 1211 list_for_each_entry_safe(sev, next_sev, &ctrl->ev_subs, node)
1212 list_del(&sev->node);
0996517c
HV		 1213 kfree(ctrl);
1214 }
1215 kfree(hdl->buckets);
1216 hdl->buckets = NULL;
1217 hdl->cached = NULL;
1218 hdl->error = 0;
77e7c4e6 1219 mutex_unlock(hdl->lock);
0996517c
HV		 1220}
1221EXPORT_SYMBOL(v4l2_ctrl_handler_free);
1222
1223/* For backwards compatibility: V4L2_CID_PRIVATE_BASE should no longer
1224 be used except in G_CTRL, S_CTRL, QUERYCTRL and QUERYMENU when dealing
1225 with applications that do not use the NEXT_CTRL flag.
1226
1227 We just find the n-th private user control. It's O(N), but that should not
1228 be an issue in this particular case. */
1229static struct v4l2_ctrl_ref *find_private_ref(
1230 struct v4l2_ctrl_handler *hdl, u32 id)
1231{
1232 struct v4l2_ctrl_ref *ref;
1233
1234 id -= V4L2_CID_PRIVATE_BASE;
1235 list_for_each_entry(ref, &hdl->ctrl_refs, node) {
1236 /* Search for private user controls that are compatible with
1237 VIDIOC_G/S_CTRL. */
1238 if (V4L2_CTRL_ID2CLASS(ref->ctrl->id) == V4L2_CTRL_CLASS_USER &&
1239 V4L2_CTRL_DRIVER_PRIV(ref->ctrl->id)) {
1240 if (!type_is_int(ref->ctrl))
1241 continue;
1242 if (id == 0)
1243 return ref;
1244 id--;
1245 }
1246 }
1247 return NULL;
1248}
1249
1250/* Find a control with the given ID. */
1251static struct v4l2_ctrl_ref *find_ref(struct v4l2_ctrl_handler *hdl, u32 id)
1252{
1253 struct v4l2_ctrl_ref *ref;
1254 int bucket;
1255
1256 id &= V4L2_CTRL_ID_MASK;
1257
1258 /* Old-style private controls need special handling */
1259 if (id >= V4L2_CID_PRIVATE_BASE)
1260 return find_private_ref(hdl, id);
1261 bucket = id % hdl->nr_of_buckets;
1262
1263 /* Simple optimization: cache the last control found */
1264 if (hdl->cached && hdl->cached->ctrl->id == id)
1265 return hdl->cached;
1266
1267 /* Not in cache, search the hash */
1268 ref = hdl->buckets ? hdl->buckets[bucket] : NULL;
1269 while (ref && ref->ctrl->id != id)
1270 ref = ref->next;
1271
1272 if (ref)
1273 hdl->cached = ref; /* cache it! */
1274 return ref;
1275}
1276
1277/* Find a control with the given ID. Take the handler's lock first. */
1278static struct v4l2_ctrl_ref *find_ref_lock(
1279 struct v4l2_ctrl_handler *hdl, u32 id)
1280{
1281 struct v4l2_ctrl_ref *ref = NULL;
1282
1283 if (hdl) {
77e7c4e6 1284 mutex_lock(hdl->lock);
0996517c 1285 ref = find_ref(hdl, id);
77e7c4e6 1286 mutex_unlock(hdl->lock);
0996517c
HV		 1287 }
1288 return ref;
1289}
1290
1291/* Find a control with the given ID. */
1292struct v4l2_ctrl *v4l2_ctrl_find(struct v4l2_ctrl_handler *hdl, u32 id)
1293{
1294 struct v4l2_ctrl_ref *ref = find_ref_lock(hdl, id);
1295
1296 return ref ? ref->ctrl : NULL;
1297}
1298EXPORT_SYMBOL(v4l2_ctrl_find);
1299
1300/* Allocate a new v4l2_ctrl_ref and hook it into the handler. */
1301static int handler_new_ref(struct v4l2_ctrl_handler *hdl,
1302 struct v4l2_ctrl *ctrl)
1303{
1304 struct v4l2_ctrl_ref *ref;
1305 struct v4l2_ctrl_ref *new_ref;
1306 u32 id = ctrl->id;
1307 u32 class_ctrl = V4L2_CTRL_ID2CLASS(id) | 1;
1308 int bucket = id % hdl->nr_of_buckets; /* which bucket to use */
1309
1310 /* Automatically add the control class if it is not yet present. */
1311 if (id != class_ctrl && find_ref_lock(hdl, class_ctrl) == NULL)
1312 if (!v4l2_ctrl_new_std(hdl, NULL, class_ctrl, 0, 0, 0, 0))
1313 return hdl->error;
1314
1315 if (hdl->error)
1316 return hdl->error;
1317
1318 new_ref = kzalloc(sizeof(*new_ref), GFP_KERNEL);
1319 if (!new_ref)
1320 return handler_set_err(hdl, -ENOMEM);
1321 new_ref->ctrl = ctrl;
1322 if (ctrl->handler == hdl) {
1323 /* By default each control starts in a cluster of its own.
1324 new_ref->ctrl is basically a cluster array with one
1325 element, so that's perfect to use as the cluster pointer.
1326 But only do this for the handler that owns the control. */
1327 ctrl->cluster = &new_ref->ctrl;
1328 ctrl->ncontrols = 1;
1329 }
1330
1331 INIT_LIST_HEAD(&new_ref->node);
1332
77e7c4e6 1333 mutex_lock(hdl->lock);
0996517c
HV		 1334
1335 /* Add immediately at the end of the list if the list is empty, or if
1336 the last element in the list has a lower ID.
1337 This ensures that when elements are added in ascending order the
1338 insertion is an O(1) operation. */
1339 if (list_empty(&hdl->ctrl_refs) || id > node2id(hdl->ctrl_refs.prev)) {
1340 list_add_tail(&new_ref->node, &hdl->ctrl_refs);
1341 goto insert_in_hash;
1342 }
1343
1344 /* Find insert position in sorted list */
1345 list_for_each_entry(ref, &hdl->ctrl_refs, node) {
1346 if (ref->ctrl->id < id)
1347 continue;
1348 /* Don't add duplicates */
1349 if (ref->ctrl->id == id) {
1350 kfree(new_ref);
1351 goto unlock;
1352 }
1353 list_add(&new_ref->node, ref->node.prev);
1354 break;
1355 }
1356
1357insert_in_hash:
1358 /* Insert the control node in the hash */
1359 new_ref->next = hdl->buckets[bucket];
1360 hdl->buckets[bucket] = new_ref;
1361
1362unlock:
77e7c4e6 1363 mutex_unlock(hdl->lock);
0996517c
HV		 1364 return 0;
1365}
1366
1367/* Add a new control */
1368static struct v4l2_ctrl *v4l2_ctrl_new(struct v4l2_ctrl_handler *hdl,
1369 const struct v4l2_ctrl_ops *ops,
1370 u32 id, const char *name, enum v4l2_ctrl_type type,
1371 s32 min, s32 max, u32 step, s32 def,
ce580fe5
SA		 1372 u32 flags, const char * const *qmenu,
1373 const s64 *qmenu_int, void *priv)
0996517c
HV		 1374{
1375 struct v4l2_ctrl *ctrl;
1376 unsigned sz_extra = 0;
1377
1378 if (hdl->error)
1379 return NULL;
1380
1381 /* Sanity checks */
1382 if (id == 0 || name == NULL || id >= V4L2_CID_PRIVATE_BASE ||
0996517c 1383 (type == V4L2_CTRL_TYPE_INTEGER && step == 0) ||
fa4d7096 1384 (type == V4L2_CTRL_TYPE_BITMASK && max == 0) ||
0996517c 1385 (type == V4L2_CTRL_TYPE_MENU && qmenu == NULL) ||
ce580fe5 1386 (type == V4L2_CTRL_TYPE_INTEGER_MENU && qmenu_int == NULL) ||
0996517c
HV		 1387 (type == V4L2_CTRL_TYPE_STRING && max == 0)) {
1388 handler_set_err(hdl, -ERANGE);
1389 return NULL;
1390 }
fa4d7096
HV		 1391 if (type != V4L2_CTRL_TYPE_BITMASK && max < min) {
1392 handler_set_err(hdl, -ERANGE);
1393 return NULL;
1394 }
02ac0480
HV		 1395 if ((type == V4L2_CTRL_TYPE_INTEGER ||
1396 type == V4L2_CTRL_TYPE_MENU ||
ce580fe5 1397 type == V4L2_CTRL_TYPE_INTEGER_MENU ||
02ac0480
HV		 1398 type == V4L2_CTRL_TYPE_BOOLEAN) &&
1399 (def < min || def > max)) {
1400 handler_set_err(hdl, -ERANGE);
1401 return NULL;
1402 }
fa4d7096
HV		 1403 if (type == V4L2_CTRL_TYPE_BITMASK && ((def & ~max) || min || step)) {
1404 handler_set_err(hdl, -ERANGE);
1405 return NULL;
1406 }
0996517c
HV		 1407
1408 if (type == V4L2_CTRL_TYPE_BUTTON)
1409 flags |= V4L2_CTRL_FLAG_WRITE_ONLY;
1410 else if (type == V4L2_CTRL_TYPE_CTRL_CLASS)
1411 flags |= V4L2_CTRL_FLAG_READ_ONLY;
1412 else if (type == V4L2_CTRL_TYPE_STRING)
1413 sz_extra += 2 * (max + 1);
1414
1415 ctrl = kzalloc(sizeof(*ctrl) + sz_extra, GFP_KERNEL);
1416 if (ctrl == NULL) {
1417 handler_set_err(hdl, -ENOMEM);
1418 return NULL;
1419 }
1420
1421 INIT_LIST_HEAD(&ctrl->node);
77068d36 1422 INIT_LIST_HEAD(&ctrl->ev_subs);
0996517c
HV		 1423 ctrl->handler = hdl;
1424 ctrl->ops = ops;
1425 ctrl->id = id;
1426 ctrl->name = name;
1427 ctrl->type = type;
1428 ctrl->flags = flags;
1429 ctrl->minimum = min;
1430 ctrl->maximum = max;
1431 ctrl->step = step;
ce580fe5
SA		 1432 if (type == V4L2_CTRL_TYPE_MENU)
1433 ctrl->qmenu = qmenu;
1434 else if (type == V4L2_CTRL_TYPE_INTEGER_MENU)
1435 ctrl->qmenu_int = qmenu_int;
0996517c
HV		 1436 ctrl->priv = priv;
1437 ctrl->cur.val = ctrl->val = ctrl->default_value = def;
1438
1439 if (ctrl->type == V4L2_CTRL_TYPE_STRING) {
1440 ctrl->cur.string = (char *)&ctrl[1] + sz_extra - (max + 1);
1441 ctrl->string = (char *)&ctrl[1] + sz_extra - 2 * (max + 1);
1442 if (ctrl->minimum)
1443 memset(ctrl->cur.string, ' ', ctrl->minimum);
1444 }
1445 if (handler_new_ref(hdl, ctrl)) {
1446 kfree(ctrl);
1447 return NULL;
1448 }
77e7c4e6 1449 mutex_lock(hdl->lock);
0996517c 1450 list_add_tail(&ctrl->node, &hdl->ctrls);
77e7c4e6 1451 mutex_unlock(hdl->lock);
0996517c
HV		 1452 return ctrl;
1453}
1454
1455struct v4l2_ctrl *v4l2_ctrl_new_custom(struct v4l2_ctrl_handler *hdl,
1456 const struct v4l2_ctrl_config *cfg, void *priv)
1457{
1458 bool is_menu;
1459 struct v4l2_ctrl *ctrl;
1460 const char *name = cfg->name;
513521ea 1461 const char * const *qmenu = cfg->qmenu;
ce580fe5 1462 const s64 *qmenu_int = cfg->qmenu_int;
0996517c
HV		 1463 enum v4l2_ctrl_type type = cfg->type;
1464 u32 flags = cfg->flags;
1465 s32 min = cfg->min;
1466 s32 max = cfg->max;
1467 u32 step = cfg->step;
1468 s32 def = cfg->def;
1469
1470 if (name == NULL)
1471 v4l2_ctrl_fill(cfg->id, &name, &type, &min, &max, &step,
1472 &def, &flags);
1473
ce580fe5
SA		 1474 is_menu = (cfg->type == V4L2_CTRL_TYPE_MENU ||
1475 cfg->type == V4L2_CTRL_TYPE_INTEGER_MENU);
0996517c
HV		 1476 if (is_menu)
1477 WARN_ON(step);
1478 else
1479 WARN_ON(cfg->menu_skip_mask);
ce580fe5 1480 if (cfg->type == V4L2_CTRL_TYPE_MENU && qmenu == NULL)
0996517c 1481 qmenu = v4l2_ctrl_get_menu(cfg->id);
ce580fe5
SA		 1482 else if (cfg->type == V4L2_CTRL_TYPE_INTEGER_MENU &&
1483 qmenu_int == NULL) {
1484 handler_set_err(hdl, -EINVAL);
1485 return NULL;
1486 }
0996517c
HV		 1487
1488 ctrl = v4l2_ctrl_new(hdl, cfg->ops, cfg->id, name,
1489 type, min, max,
1490 is_menu ? cfg->menu_skip_mask : step,
ce580fe5 1491 def, flags, qmenu, qmenu_int, priv);
88365105 1492 if (ctrl)
0996517c 1493 ctrl->is_private = cfg->is_private;
0996517c
HV		 1494 return ctrl;
1495}
1496EXPORT_SYMBOL(v4l2_ctrl_new_custom);
1497
1498/* Helper function for standard non-menu controls */
1499struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl,
1500 const struct v4l2_ctrl_ops *ops,
1501 u32 id, s32 min, s32 max, u32 step, s32 def)
1502{
1503 const char *name;
1504 enum v4l2_ctrl_type type;
1505 u32 flags;
1506
1507 v4l2_ctrl_fill(id, &name, &type, &min, &max, &step, &def, &flags);
ce580fe5
SA		 1508 if (type == V4L2_CTRL_TYPE_MENU
1509 || type == V4L2_CTRL_TYPE_INTEGER_MENU) {
0996517c
HV		 1510 handler_set_err(hdl, -EINVAL);
1511 return NULL;
1512 }
1513 return v4l2_ctrl_new(hdl, ops, id, name, type,
ce580fe5 1514 min, max, step, def, flags, NULL, NULL, NULL);
0996517c
HV		 1515}
1516EXPORT_SYMBOL(v4l2_ctrl_new_std);
1517
1518/* Helper function for standard menu controls */
1519struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl,
1520 const struct v4l2_ctrl_ops *ops,
1521 u32 id, s32 max, s32 mask, s32 def)
1522{
513521ea 1523 const char * const *qmenu = v4l2_ctrl_get_menu(id);
0996517c
HV		 1524 const char *name;
1525 enum v4l2_ctrl_type type;
1526 s32 min;
1527 s32 step;
1528 u32 flags;
1529
1530 v4l2_ctrl_fill(id, &name, &type, &min, &max, &step, &def, &flags);
1531 if (type != V4L2_CTRL_TYPE_MENU) {
1532 handler_set_err(hdl, -EINVAL);
1533 return NULL;
1534 }
1535 return v4l2_ctrl_new(hdl, ops, id, name, type,
ce580fe5 1536 0, max, mask, def, flags, qmenu, NULL, NULL);
0996517c
HV		 1537}
1538EXPORT_SYMBOL(v4l2_ctrl_new_std_menu);
1539
1540/* Add a control from another handler to this handler */
1541struct v4l2_ctrl *v4l2_ctrl_add_ctrl(struct v4l2_ctrl_handler *hdl,
1542 struct v4l2_ctrl *ctrl)
1543{
1544 if (hdl == NULL || hdl->error)
1545 return NULL;
1546 if (ctrl == NULL) {
1547 handler_set_err(hdl, -EINVAL);
1548 return NULL;
1549 }
1550 if (ctrl->handler == hdl)
1551 return ctrl;
1552 return handler_new_ref(hdl, ctrl) ? NULL : ctrl;
1553}
1554EXPORT_SYMBOL(v4l2_ctrl_add_ctrl);
1555
1556/* Add the controls from another handler to our own. */
1557int v4l2_ctrl_add_handler(struct v4l2_ctrl_handler *hdl,
1558 struct v4l2_ctrl_handler *add)
1559{
072e6602 1560 struct v4l2_ctrl_ref *ref;
0996517c
HV		 1561 int ret = 0;
1562
1563 /* Do nothing if either handler is NULL or if they are the same */
1564 if (!hdl || !add || hdl == add)
1565 return 0;
1566 if (hdl->error)
1567 return hdl->error;
77e7c4e6 1568 mutex_lock(add->lock);
072e6602
HV		 1569 list_for_each_entry(ref, &add->ctrl_refs, node) {
1570 struct v4l2_ctrl *ctrl = ref->ctrl;
1571
0996517c
HV		 1572 /* Skip handler-private controls. */
1573 if (ctrl->is_private)
1574 continue;
6e239399
HV		 1575 /* And control classes */
1576 if (ctrl->type == V4L2_CTRL_TYPE_CTRL_CLASS)
1577 continue;
0996517c
HV		 1578 ret = handler_new_ref(hdl, ctrl);
1579 if (ret)
1580 break;
1581 }
77e7c4e6 1582 mutex_unlock(add->lock);
0996517c
HV		 1583 return ret;
1584}
1585EXPORT_SYMBOL(v4l2_ctrl_add_handler);
1586
1587/* Cluster controls */
1588void v4l2_ctrl_cluster(unsigned ncontrols, struct v4l2_ctrl **controls)
1589{
5626b8c7 1590 bool has_volatiles = false;
0996517c
HV		 1591 int i;
1592
1593 /* The first control is the master control and it must not be NULL */
72d877ca 1594 BUG_ON(ncontrols == 0 || controls[0] == NULL);
0996517c
HV		 1595
1596 for (i = 0; i < ncontrols; i++) {
1597 if (controls[i]) {
1598 controls[i]->cluster = controls;
1599 controls[i]->ncontrols = ncontrols;
5626b8c7
HV		 1600 if (controls[i]->flags & V4L2_CTRL_FLAG_VOLATILE)
1601 has_volatiles = true;
0996517c
HV		 1602 }
1603 }
5626b8c7 1604 controls[0]->has_volatiles = has_volatiles;
0996517c
HV		 1605}
1606EXPORT_SYMBOL(v4l2_ctrl_cluster);
1607
72d877ca
HV		 1608void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls,
1609 u8 manual_val, bool set_volatile)
1610{
1611 struct v4l2_ctrl *master = controls[0];
5626b8c7 1612 u32 flag = 0;
72d877ca
HV		 1613 int i;
1614
1615 v4l2_ctrl_cluster(ncontrols, controls);
1616 WARN_ON(ncontrols <= 1);
82a7c049 1617 WARN_ON(manual_val < master->minimum || manual_val > master->maximum);
5626b8c7 1618 WARN_ON(set_volatile && !has_op(master, g_volatile_ctrl));
72d877ca 1619 master->is_auto = true;
5626b8c7 1620 master->has_volatiles = set_volatile;
72d877ca
HV		 1621 master->manual_mode_value = manual_val;
1622 master->flags |= V4L2_CTRL_FLAG_UPDATE;
5626b8c7
HV		 1623
1624 if (!is_cur_manual(master))
1625 flag = V4L2_CTRL_FLAG_INACTIVE |
1626 (set_volatile ? V4L2_CTRL_FLAG_VOLATILE : 0);
72d877ca
HV		 1627
1628 for (i = 1; i < ncontrols; i++)
88365105 1629 if (controls[i])
72d877ca 1630 controls[i]->flags |= flag;
72d877ca
HV		 1631}
1632EXPORT_SYMBOL(v4l2_ctrl_auto_cluster);
1633
0996517c
HV		 1634/* Activate/deactivate a control. */
1635void v4l2_ctrl_activate(struct v4l2_ctrl *ctrl, bool active)
1636{
6e239399
HV		 1637 /* invert since the actual flag is called 'inactive' */
1638 bool inactive = !active;
1639 bool old;
1640
0996517c
HV		 1641 if (ctrl == NULL)
1642 return;
1643
6e239399 1644 if (inactive)
0996517c 1645 /* set V4L2_CTRL_FLAG_INACTIVE */
6e239399 1646 old = test_and_set_bit(4, &ctrl->flags);
0996517c
HV		 1647 else
1648 /* clear V4L2_CTRL_FLAG_INACTIVE */
6e239399
HV		 1649 old = test_and_clear_bit(4, &ctrl->flags);
1650 if (old != inactive)
1651 send_event(NULL, ctrl, V4L2_EVENT_CTRL_CH_FLAGS);
0996517c
HV		 1652}
1653EXPORT_SYMBOL(v4l2_ctrl_activate);
1654
1655/* Grab/ungrab a control.
1656 Typically used when streaming starts and you want to grab controls,
1657 preventing the user from changing them.
1658
1659 Just call this and the framework will block any attempts to change
1660 these controls. */
1661void v4l2_ctrl_grab(struct v4l2_ctrl *ctrl, bool grabbed)
1662{
6e239399
HV		 1663 bool old;
1664
0996517c
HV		 1665 if (ctrl == NULL)
1666 return;
1667
6e239399 1668 v4l2_ctrl_lock(ctrl);
0996517c
HV		 1669 if (grabbed)
1670 /* set V4L2_CTRL_FLAG_GRABBED */
6e239399 1671 old = test_and_set_bit(1, &ctrl->flags);
0996517c
HV		 1672 else
1673 /* clear V4L2_CTRL_FLAG_GRABBED */
6e239399
HV		 1674 old = test_and_clear_bit(1, &ctrl->flags);
1675 if (old != grabbed)
1676 send_event(NULL, ctrl, V4L2_EVENT_CTRL_CH_FLAGS);
1677 v4l2_ctrl_unlock(ctrl);
0996517c
HV		 1678}
1679EXPORT_SYMBOL(v4l2_ctrl_grab);
1680
1681/* Log the control name and value */
1682static void log_ctrl(const struct v4l2_ctrl *ctrl,
1683 const char *prefix, const char *colon)
1684{
0996517c
HV		 1685 if (ctrl->flags & (V4L2_CTRL_FLAG_DISABLED | V4L2_CTRL_FLAG_WRITE_ONLY))
1686 return;
1687 if (ctrl->type == V4L2_CTRL_TYPE_CTRL_CLASS)
1688 return;
1689
1690 printk(KERN_INFO "%s%s%s: ", prefix, colon, ctrl->name);
1691
1692 switch (ctrl->type) {
1693 case V4L2_CTRL_TYPE_INTEGER:
1694 printk(KERN_CONT "%d", ctrl->cur.val);
1695 break;
1696 case V4L2_CTRL_TYPE_BOOLEAN:
1697 printk(KERN_CONT "%s", ctrl->cur.val ? "true" : "false");
1698 break;
1699 case V4L2_CTRL_TYPE_MENU:
1700 printk(KERN_CONT "%s", ctrl->qmenu[ctrl->cur.val]);
1701 break;
ce580fe5
SA		 1702 case V4L2_CTRL_TYPE_INTEGER_MENU:
1703 printk(KERN_CONT "%lld", ctrl->qmenu_int[ctrl->cur.val]);
1704 break;
fa4d7096
HV		 1705 case V4L2_CTRL_TYPE_BITMASK:
1706 printk(KERN_CONT "0x%08x", ctrl->cur.val);
1707 break;
0996517c
HV		 1708 case V4L2_CTRL_TYPE_INTEGER64:
1709 printk(KERN_CONT "%lld", ctrl->cur.val64);
1710 break;
1711 case V4L2_CTRL_TYPE_STRING:
1712 printk(KERN_CONT "%s", ctrl->cur.string);
1713 break;
1714 default:
1715 printk(KERN_CONT "unknown type %d", ctrl->type);
1716 break;
1717 }
88365105
HV		 1718 if (ctrl->flags & (V4L2_CTRL_FLAG_INACTIVE |
1719 V4L2_CTRL_FLAG_GRABBED |
1720 V4L2_CTRL_FLAG_VOLATILE)) {
1721 if (ctrl->flags & V4L2_CTRL_FLAG_INACTIVE)
1722 printk(KERN_CONT " inactive");
1723 if (ctrl->flags & V4L2_CTRL_FLAG_GRABBED)
1724 printk(KERN_CONT " grabbed");
1725 if (ctrl->flags & V4L2_CTRL_FLAG_VOLATILE)
1726 printk(KERN_CONT " volatile");
1727 }
1728 printk(KERN_CONT "\n");
0996517c
HV		 1729}
1730
1731/* Log all controls owned by the handler */
1732void v4l2_ctrl_handler_log_status(struct v4l2_ctrl_handler *hdl,
1733 const char *prefix)
1734{
1735 struct v4l2_ctrl *ctrl;
1736 const char *colon = "";
1737 int len;
1738
1739 if (hdl == NULL)
1740 return;
1741 if (prefix == NULL)
1742 prefix = "";
1743 len = strlen(prefix);
1744 if (len && prefix[len - 1] != ' ')
1745 colon = ": ";
77e7c4e6 1746 mutex_lock(hdl->lock);
0996517c
HV		 1747 list_for_each_entry(ctrl, &hdl->ctrls, node)
1748 if (!(ctrl->flags & V4L2_CTRL_FLAG_DISABLED))
1749 log_ctrl(ctrl, prefix, colon);
77e7c4e6 1750 mutex_unlock(hdl->lock);
0996517c
HV		 1751}
1752EXPORT_SYMBOL(v4l2_ctrl_handler_log_status);
1753
1754/* Call s_ctrl for all controls owned by the handler */
1755int v4l2_ctrl_handler_setup(struct v4l2_ctrl_handler *hdl)
1756{
1757 struct v4l2_ctrl *ctrl;
1758 int ret = 0;
1759
1760 if (hdl == NULL)
1761 return 0;
77e7c4e6 1762 mutex_lock(hdl->lock);
0996517c
HV		 1763 list_for_each_entry(ctrl, &hdl->ctrls, node)
1764 ctrl->done = false;
1765
1766 list_for_each_entry(ctrl, &hdl->ctrls, node) {
1767 struct v4l2_ctrl *master = ctrl->cluster[0];
1768 int i;
1769
1770 /* Skip if this control was already handled by a cluster. */
71c6c4c9
HV		 1771 /* Skip button controls and read-only controls. */
1772 if (ctrl->done || ctrl->type == V4L2_CTRL_TYPE_BUTTON ||
1773 (ctrl->flags & V4L2_CTRL_FLAG_READ_ONLY))
0996517c
HV		 1774 continue;
1775
2a863793
HV		 1776 for (i = 0; i < master->ncontrols; i++) {
1777 if (master->cluster[i]) {
1778 cur_to_new(master->cluster[i]);
1779 master->cluster[i]->is_new = 1;
71c6c4c9 1780 master->cluster[i]->done = true;
2a863793
HV		 1781 }
1782 }
54c911eb 1783 ret = call_op(master, s_ctrl);
0996517c
HV		 1784 if (ret)
1785 break;
0996517c 1786 }
77e7c4e6 1787 mutex_unlock(hdl->lock);
0996517c
HV		 1788 return ret;
1789}
1790EXPORT_SYMBOL(v4l2_ctrl_handler_setup);
1791
1792/* Implement VIDIOC_QUERYCTRL */
1793int v4l2_queryctrl(struct v4l2_ctrl_handler *hdl, struct v4l2_queryctrl *qc)
1794{
1795 u32 id = qc->id & V4L2_CTRL_ID_MASK;
1796 struct v4l2_ctrl_ref *ref;
1797 struct v4l2_ctrl *ctrl;
1798
1799 if (hdl == NULL)
1800 return -EINVAL;
1801
77e7c4e6 1802 mutex_lock(hdl->lock);
0996517c
HV		 1803
1804 /* Try to find it */
1805 ref = find_ref(hdl, id);
1806
1807 if ((qc->id & V4L2_CTRL_FLAG_NEXT_CTRL) && !list_empty(&hdl->ctrl_refs)) {
1808 /* Find the next control with ID > qc->id */
1809
1810 /* Did we reach the end of the control list? */
1811 if (id >= node2id(hdl->ctrl_refs.prev)) {
1812 ref = NULL; /* Yes, so there is no next control */
1813 } else if (ref) {
1814 /* We found a control with the given ID, so just get
1815 the next one in the list. */
1816 ref = list_entry(ref->node.next, typeof(*ref), node);
1817 } else {
1818 /* No control with the given ID exists, so start
1819 searching for the next largest ID. We know there
1820 is one, otherwise the first 'if' above would have
1821 been true. */
1822 list_for_each_entry(ref, &hdl->ctrl_refs, node)
1823 if (id < ref->ctrl->id)
1824 break;
1825 }
1826 }
77e7c4e6 1827 mutex_unlock(hdl->lock);
0996517c
HV		 1828 if (!ref)
1829 return -EINVAL;
1830
1831 ctrl = ref->ctrl;
1832 memset(qc, 0, sizeof(*qc));
829fb2dc
HV		 1833 if (id >= V4L2_CID_PRIVATE_BASE)
1834 qc->id = id;
1835 else
1836 qc->id = ctrl->id;
0996517c
HV		 1837 strlcpy(qc->name, ctrl->name, sizeof(qc->name));
1838 qc->minimum = ctrl->minimum;
1839 qc->maximum = ctrl->maximum;
1840 qc->default_value = ctrl->default_value;
ce580fe5
SA		 1841 if (ctrl->type == V4L2_CTRL_TYPE_MENU
1842 || ctrl->type == V4L2_CTRL_TYPE_INTEGER_MENU)
0996517c
HV		 1843 qc->step = 1;
1844 else
1845 qc->step = ctrl->step;
1846 qc->flags = ctrl->flags;
1847 qc->type = ctrl->type;
1848 return 0;
1849}
1850EXPORT_SYMBOL(v4l2_queryctrl);
1851
1852int v4l2_subdev_queryctrl(struct v4l2_subdev *sd, struct v4l2_queryctrl *qc)
1853{
87a0c94c
HV		 1854 if (qc->id & V4L2_CTRL_FLAG_NEXT_CTRL)
1855 return -EINVAL;
0996517c
HV		 1856 return v4l2_queryctrl(sd->ctrl_handler, qc);
1857}
1858EXPORT_SYMBOL(v4l2_subdev_queryctrl);
1859
1860/* Implement VIDIOC_QUERYMENU */
1861int v4l2_querymenu(struct v4l2_ctrl_handler *hdl, struct v4l2_querymenu *qm)
1862{
1863 struct v4l2_ctrl *ctrl;
1864 u32 i = qm->index;
1865
1866 ctrl = v4l2_ctrl_find(hdl, qm->id);
1867 if (!ctrl)
1868 return -EINVAL;
1869
1870 qm->reserved = 0;
1871 /* Sanity checks */
ce580fe5
SA		 1872 switch (ctrl->type) {
1873 case V4L2_CTRL_TYPE_MENU:
1874 if (ctrl->qmenu == NULL)
1875 return -EINVAL;
1876 break;
1877 case V4L2_CTRL_TYPE_INTEGER_MENU:
1878 if (ctrl->qmenu_int == NULL)
1879 return -EINVAL;
1880 break;
1881 default:
1882 return -EINVAL;
1883 }
1884
1885 if (i < ctrl->minimum || i > ctrl->maximum)
0996517c 1886 return -EINVAL;
ce580fe5 1887
0996517c
HV		 1888 /* Use mask to see if this menu item should be skipped */
1889 if (ctrl->menu_skip_mask & (1 << i))
1890 return -EINVAL;
1891 /* Empty menu items should also be skipped */
ce580fe5
SA		 1892 if (ctrl->type == V4L2_CTRL_TYPE_MENU) {
1893 if (ctrl->qmenu[i] == NULL || ctrl->qmenu[i][0] == '\0')
1894 return -EINVAL;
1895 strlcpy(qm->name, ctrl->qmenu[i], sizeof(qm->name));
1896 } else {
1897 qm->value = ctrl->qmenu_int[i];
1898 }
0996517c
HV		 1899 return 0;
1900}
1901EXPORT_SYMBOL(v4l2_querymenu);
1902
1903int v4l2_subdev_querymenu(struct v4l2_subdev *sd, struct v4l2_querymenu *qm)
1904{
1905 return v4l2_querymenu(sd->ctrl_handler, qm);
1906}
1907EXPORT_SYMBOL(v4l2_subdev_querymenu);
1908
1909
1910
1911/* Some general notes on the atomic requirements of VIDIOC_G/TRY/S_EXT_CTRLS:
1912
1913 It is not a fully atomic operation, just best-effort only. After all, if
1914 multiple controls have to be set through multiple i2c writes (for example)
1915 then some initial writes may succeed while others fail. Thus leaving the
1916 system in an inconsistent state. The question is how much effort you are
1917 willing to spend on trying to make something atomic that really isn't.
1918
1919 From the point of view of an application the main requirement is that
1920 when you call VIDIOC_S_EXT_CTRLS and some values are invalid then an
1921 error should be returned without actually affecting any controls.
1922
1923 If all the values are correct, then it is acceptable to just give up
1924 in case of low-level errors.
1925
1926 It is important though that the application can tell when only a partial
1927 configuration was done. The way we do that is through the error_idx field
1928 of struct v4l2_ext_controls: if that is equal to the count field then no
1929 controls were affected. Otherwise all controls before that index were
1930 successful in performing their 'get' or 'set' operation, the control at
1931 the given index failed, and you don't know what happened with the controls
1932 after the failed one. Since if they were part of a control cluster they
1933 could have been successfully processed (if a cluster member was encountered
1934 at index < error_idx), they could have failed (if a cluster member was at
1935 error_idx), or they may not have been processed yet (if the first cluster
1936 member appeared after error_idx).
1937
1938 It is all fairly theoretical, though. In practice all you can do is to
1939 bail out. If error_idx == count, then it is an application bug. If
1940 error_idx < count then it is only an application bug if the error code was
1941 EBUSY. That usually means that something started streaming just when you
1942 tried to set the controls. In all other cases it is a driver/hardware
1943 problem and all you can do is to retry or bail out.
1944
1945 Note that these rules do not apply to VIDIOC_TRY_EXT_CTRLS: since that
1946 never modifies controls the error_idx is just set to whatever control
1947 has an invalid value.
1948 */
1949
1950/* Prepare for the extended g/s/try functions.
1951 Find the controls in the control array and do some basic checks. */
1952static int prepare_ext_ctrls(struct v4l2_ctrl_handler *hdl,
1953 struct v4l2_ext_controls *cs,
eb5b16ef 1954 struct v4l2_ctrl_helper *helpers)
0996517c 1955{
eb5b16ef
HV		 1956 struct v4l2_ctrl_helper *h;
1957 bool have_clusters = false;
0996517c
HV		 1958 u32 i;
1959
eb5b16ef 1960 for (i = 0, h = helpers; i < cs->count; i++, h++) {
0996517c 1961 struct v4l2_ext_control *c = &cs->controls[i];
eb5b16ef 1962 struct v4l2_ctrl_ref *ref;
0996517c
HV		 1963 struct v4l2_ctrl *ctrl;
1964 u32 id = c->id & V4L2_CTRL_ID_MASK;
1965
37cd3b73 1966 cs->error_idx = i;
0996517c
HV		 1967
1968 if (cs->ctrl_class && V4L2_CTRL_ID2CLASS(id) != cs->ctrl_class)
1969 return -EINVAL;
1970
1971 /* Old-style private controls are not allowed for
1972 extended controls */
1973 if (id >= V4L2_CID_PRIVATE_BASE)
1974 return -EINVAL;
eb5b16ef
HV		 1975 ref = find_ref_lock(hdl, id);
1976 if (ref == NULL)
0996517c 1977 return -EINVAL;
eb5b16ef 1978 ctrl = ref->ctrl;
0996517c
HV		 1979 if (ctrl->flags & V4L2_CTRL_FLAG_DISABLED)
1980 return -EINVAL;
1981
eb5b16ef
HV		 1982 if (ctrl->cluster[0]->ncontrols > 1)
1983 have_clusters = true;
1984 if (ctrl->cluster[0] != ctrl)
1985 ref = find_ref_lock(hdl, ctrl->cluster[0]->id);
1986 /* Store the ref to the master control of the cluster */
1987 h->mref = ref;
1988 h->ctrl = ctrl;
1989 /* Initially set next to 0, meaning that there is no other
1990 control in this helper array belonging to the same
1991 cluster */
1992 h->next = 0;
0996517c 1993 }
0996517c 1994
eb5b16ef
HV		 1995 /* We are done if there were no controls that belong to a multi-
1996 control cluster. */
1997 if (!have_clusters)
1998 return 0;
0996517c 1999
eb5b16ef
HV		 2000 /* The code below figures out in O(n) time which controls in the list
2001 belong to the same cluster. */
0996517c 2002
eb5b16ef 2003 /* This has to be done with the handler lock taken. */
77e7c4e6 2004 mutex_lock(hdl->lock);
0996517c 2005
eb5b16ef
HV		 2006 /* First zero the helper field in the master control references */
2007 for (i = 0; i < cs->count; i++)
2008 helpers[i].mref->helper = 0;
2009 for (i = 0, h = helpers; i < cs->count; i++, h++) {
2010 struct v4l2_ctrl_ref *mref = h->mref;
2011
2012 /* If the mref->helper is set, then it points to an earlier
2013 helper that belongs to the same cluster. */
2014 if (mref->helper) {
2015 /* Set the next field of mref->helper to the current
2016 index: this means that that earlier helper now
2017 points to the next helper in the same cluster. */
2018 mref->helper->next = i;
2019 /* mref should be set only for the first helper in the
2020 cluster, clear the others. */
2021 h->mref = NULL;
2022 }
2023 /* Point the mref helper to the current helper struct. */
2024 mref->helper = h;
0996517c 2025 }
77e7c4e6 2026 mutex_unlock(hdl->lock);
eb5b16ef 2027 return 0;
0996517c
HV		 2028}
2029
2030/* Handles the corner case where cs->count == 0. It checks whether the
2031 specified control class exists. If that class ID is 0, then it checks
2032 whether there are any controls at all. */
2033static int class_check(struct v4l2_ctrl_handler *hdl, u32 ctrl_class)
2034{
2035 if (ctrl_class == 0)
2036 return list_empty(&hdl->ctrl_refs) ? -EINVAL : 0;
2037 return find_ref_lock(hdl, ctrl_class | 1) ? 0 : -EINVAL;
2038}
2039
2040
2041
2042/* Get extended controls. Allocates the helpers array if needed. */
2043int v4l2_g_ext_ctrls(struct v4l2_ctrl_handler *hdl, struct v4l2_ext_controls *cs)
2044{
eb5b16ef
HV		 2045 struct v4l2_ctrl_helper helper[4];
2046 struct v4l2_ctrl_helper *helpers = helper;
0996517c 2047 int ret;
ddac5c10 2048 int i, j;
0996517c
HV		 2049
2050 cs->error_idx = cs->count;
2051 cs->ctrl_class = V4L2_CTRL_ID2CLASS(cs->ctrl_class);
2052
2053 if (hdl == NULL)
2054 return -EINVAL;
2055
2056 if (cs->count == 0)
2057 return class_check(hdl, cs->ctrl_class);
2058
2059 if (cs->count > ARRAY_SIZE(helper)) {
5f0049bd
XW		 2060 helpers = kmalloc_array(cs->count, sizeof(helper[0]),
2061 GFP_KERNEL);
0996517c
HV		 2062 if (helpers == NULL)
2063 return -ENOMEM;
2064 }
2065
37cd3b73
HV		 2066 ret = prepare_ext_ctrls(hdl, cs, helpers);
2067 cs->error_idx = cs->count;
0996517c
HV		 2068
2069 for (i = 0; !ret && i < cs->count; i++)
2070 if (helpers[i].ctrl->flags & V4L2_CTRL_FLAG_WRITE_ONLY)
2071 ret = -EACCES;
2072
2073 for (i = 0; !ret && i < cs->count; i++) {
eb5b16ef
HV		 2074 int (*ctrl_to_user)(struct v4l2_ext_control *c,
2075 struct v4l2_ctrl *ctrl) = cur_to_user;
2076 struct v4l2_ctrl *master;
0996517c 2077
eb5b16ef 2078 if (helpers[i].mref == NULL)
0996517c
HV		 2079 continue;
2080
eb5b16ef 2081 master = helpers[i].mref->ctrl;
0996517c
HV		 2082 cs->error_idx = i;
2083
2084 v4l2_ctrl_lock(master);
ddac5c10
HV		 2085
2086 /* g_volatile_ctrl will update the new control values */
5626b8c7
HV		 2087 if ((master->flags & V4L2_CTRL_FLAG_VOLATILE) ||
2088 (master->has_volatiles && !is_cur_manual(master))) {
ddac5c10
HV		 2089 for (j = 0; j < master->ncontrols; j++)
2090 cur_to_new(master->cluster[j]);
54c911eb 2091 ret = call_op(master, g_volatile_ctrl);
eb5b16ef 2092 ctrl_to_user = new_to_user;
ddac5c10
HV		 2093 }
2094 /* If OK, then copy the current (for non-volatile controls)
2095 or the new (for volatile controls) control values to the
2096 caller */
eb5b16ef
HV		 2097 if (!ret) {
2098 u32 idx = i;
2099
2100 do {
2101 ret = ctrl_to_user(cs->controls + idx,
2102 helpers[idx].ctrl);
2103 idx = helpers[idx].next;
2104 } while (!ret && idx);
2105 }
0996517c 2106 v4l2_ctrl_unlock(master);
0996517c
HV		 2107 }
2108
2109 if (cs->count > ARRAY_SIZE(helper))
2110 kfree(helpers);
2111 return ret;
2112}
2113EXPORT_SYMBOL(v4l2_g_ext_ctrls);
2114
2115int v4l2_subdev_g_ext_ctrls(struct v4l2_subdev *sd, struct v4l2_ext_controls *cs)
2116{
2117 return v4l2_g_ext_ctrls(sd->ctrl_handler, cs);
2118}
2119EXPORT_SYMBOL(v4l2_subdev_g_ext_ctrls);
2120
2121/* Helper function to get a single control */
2122static int get_ctrl(struct v4l2_ctrl *ctrl, s32 *val)
2123{
2124 struct v4l2_ctrl *master = ctrl->cluster[0];
2125 int ret = 0;
ddac5c10 2126 int i;
0996517c
HV		 2127
2128 if (ctrl->flags & V4L2_CTRL_FLAG_WRITE_ONLY)
2129 return -EACCES;
2130
2131 v4l2_ctrl_lock(master);
2132 /* g_volatile_ctrl will update the current control values */
5626b8c7 2133 if (ctrl->flags & V4L2_CTRL_FLAG_VOLATILE) {
ddac5c10
HV		 2134 for (i = 0; i < master->ncontrols; i++)
2135 cur_to_new(master->cluster[i]);
54c911eb 2136 ret = call_op(master, g_volatile_ctrl);
ddac5c10
HV		 2137 *val = ctrl->val;
2138 } else {
2139 *val = ctrl->cur.val;
2140 }
0996517c
HV		 2141 v4l2_ctrl_unlock(master);
2142 return ret;
2143}
2144
2145int v4l2_g_ctrl(struct v4l2_ctrl_handler *hdl, struct v4l2_control *control)
2146{
2147 struct v4l2_ctrl *ctrl = v4l2_ctrl_find(hdl, control->id);
2148
2149 if (ctrl == NULL || !type_is_int(ctrl))
2150 return -EINVAL;
2151 return get_ctrl(ctrl, &control->value);
2152}
2153EXPORT_SYMBOL(v4l2_g_ctrl);
2154
2155int v4l2_subdev_g_ctrl(struct v4l2_subdev *sd, struct v4l2_control *control)
2156{
2157 return v4l2_g_ctrl(sd->ctrl_handler, control);
2158}
2159EXPORT_SYMBOL(v4l2_subdev_g_ctrl);
2160
2161s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl)
2162{
2163 s32 val = 0;
2164
2165 /* It's a driver bug if this happens. */
2166 WARN_ON(!type_is_int(ctrl));
2167 get_ctrl(ctrl, &val);
2168 return val;
2169}
2170EXPORT_SYMBOL(v4l2_ctrl_g_ctrl);
2171
2172
2173/* Core function that calls try/s_ctrl and ensures that the new value is
2174 copied to the current value on a set.
2175 Must be called with ctrl->handler->lock held. */
e6402585
HV		 2176static int try_or_set_cluster(struct v4l2_fh *fh,
2177 struct v4l2_ctrl *master, bool set)
0996517c 2178{
72d877ca 2179 bool update_flag;
eb5b16ef 2180 int ret;
0996517c
HV		 2181 int i;
2182
2183 /* Go through the cluster and either validate the new value or
2184 (if no new value was set), copy the current value to the new
2185 value, ensuring a consistent view for the control ops when
2186 called. */
eb5b16ef 2187 for (i = 0; i < master->ncontrols; i++) {
0996517c
HV		 2188 struct v4l2_ctrl *ctrl = master->cluster[i];
2189
2190 if (ctrl == NULL)
2191 continue;
2192
eb5b16ef
HV		 2193 if (!ctrl->is_new) {
2194 cur_to_new(ctrl);
0996517c
HV		 2195 continue;
2196 }
eb5b16ef
HV		 2197 /* Check again: it may have changed since the
2198 previous check in try_or_set_ext_ctrls(). */
2199 if (set && (ctrl->flags & V4L2_CTRL_FLAG_GRABBED))
2200 return -EBUSY;
0996517c
HV		 2201 }
2202
eb5b16ef 2203 ret = call_op(master, try_ctrl);
0996517c
HV		 2204
2205 /* Don't set if there is no change */
72d877ca
HV		 2206 if (ret || !set || !cluster_changed(master))
2207 return ret;
2208 ret = call_op(master, s_ctrl);
72d877ca
HV		 2209 if (ret)
2210 return ret;
2211
eb5b16ef 2212 /* If OK, then make the new values permanent. */
72d877ca
HV		 2213 update_flag = is_cur_manual(master) != is_new_manual(master);
2214 for (i = 0; i < master->ncontrols; i++)
ab892bac 2215 new_to_cur(fh, master->cluster[i], update_flag && i > 0);
72d877ca 2216 return 0;
0996517c
HV		 2217}
2218
e6402585
HV		 2219/* Validate controls. */
2220static int validate_ctrls(struct v4l2_ext_controls *cs,
2221 struct v4l2_ctrl_helper *helpers, bool set)
0996517c 2222{
e6402585 2223 unsigned i;
0996517c
HV		 2224 int ret = 0;
2225
eb5b16ef 2226 cs->error_idx = cs->count;
0996517c
HV		 2227 for (i = 0; i < cs->count; i++) {
2228 struct v4l2_ctrl *ctrl = helpers[i].ctrl;
2229
e6402585 2230 cs->error_idx = i;
0996517c
HV		 2231
2232 if (ctrl->flags & V4L2_CTRL_FLAG_READ_ONLY)
2233 return -EACCES;
2234 /* This test is also done in try_set_control_cluster() which
2235 is called in atomic context, so that has the final say,
2236 but it makes sense to do an up-front check as well. Once
2237 an error occurs in try_set_control_cluster() some other
2238 controls may have been set already and we want to do a
2239 best-effort to avoid that. */
2240 if (set && (ctrl->flags & V4L2_CTRL_FLAG_GRABBED))
2241 return -EBUSY;
eb5b16ef
HV		 2242 ret = validate_new(ctrl, &cs->controls[i]);
2243 if (ret)
2244 return ret;
0996517c 2245 }
e6402585
HV		 2246 return 0;
2247}
2248
5626b8c7
HV		 2249/* Obtain the current volatile values of an autocluster and mark them
2250 as new. */
2251static void update_from_auto_cluster(struct v4l2_ctrl *master)
2252{
2253 int i;
2254
2255 for (i = 0; i < master->ncontrols; i++)
2256 cur_to_new(master->cluster[i]);
2257 if (!call_op(master, g_volatile_ctrl))
2258 for (i = 1; i < master->ncontrols; i++)
2259 if (master->cluster[i])
2260 master->cluster[i]->is_new = 1;
2261}
2262
e6402585
HV		 2263/* Try or try-and-set controls */
2264static int try_set_ext_ctrls(struct v4l2_fh *fh, struct v4l2_ctrl_handler *hdl,
2265 struct v4l2_ext_controls *cs,
2266 bool set)
2267{
2268 struct v4l2_ctrl_helper helper[4];
2269 struct v4l2_ctrl_helper *helpers = helper;
2270 unsigned i, j;
2271 int ret;
2272
2273 cs->error_idx = cs->count;
2274 cs->ctrl_class = V4L2_CTRL_ID2CLASS(cs->ctrl_class);
2275
2276 if (hdl == NULL)
2277 return -EINVAL;
2278
2279 if (cs->count == 0)
2280 return class_check(hdl, cs->ctrl_class);
0996517c 2281
e6402585 2282 if (cs->count > ARRAY_SIZE(helper)) {
0a3475eb
XW		 2283 helpers = kmalloc_array(cs->count, sizeof(helper[0]),
2284 GFP_KERNEL);
e6402585
HV		 2285 if (!helpers)
2286 return -ENOMEM;
2287 }
2288 ret = prepare_ext_ctrls(hdl, cs, helpers);
2289 if (!ret)
2290 ret = validate_ctrls(cs, helpers, set);
2291 if (ret && set)
2292 cs->error_idx = cs->count;
0996517c 2293 for (i = 0; !ret && i < cs->count; i++) {
eb5b16ef
HV		 2294 struct v4l2_ctrl *master;
2295 u32 idx = i;
0996517c 2296
eb5b16ef 2297 if (helpers[i].mref == NULL)
0996517c
HV		 2298 continue;
2299
37cd3b73 2300 cs->error_idx = i;
eb5b16ef
HV		 2301 master = helpers[i].mref->ctrl;
2302 v4l2_ctrl_lock(master);
0996517c 2303
2a863793 2304 /* Reset the 'is_new' flags of the cluster */
0996517c
HV		 2305 for (j = 0; j < master->ncontrols; j++)
2306 if (master->cluster[j])
2a863793 2307 master->cluster[j]->is_new = 0;
0996517c 2308
5626b8c7
HV		 2309 /* For volatile autoclusters that are currently in auto mode
2310 we need to discover if it will be set to manual mode.
2311 If so, then we have to copy the current volatile values
2312 first since those will become the new manual values (which
2313 may be overwritten by explicit new values from this set
2314 of controls). */
2315 if (master->is_auto && master->has_volatiles &&
2316 !is_cur_manual(master)) {
2317 /* Pick an initial non-manual value */
2318 s32 new_auto_val = master->manual_mode_value + 1;
2319 u32 tmp_idx = idx;
2320
2321 do {
2322 /* Check if the auto control is part of the
2323 list, and remember the new value. */
2324 if (helpers[tmp_idx].ctrl == master)
2325 new_auto_val = cs->controls[tmp_idx].value;
2326 tmp_idx = helpers[tmp_idx].next;
2327 } while (tmp_idx);
2328 /* If the new value == the manual value, then copy
2329 the current volatile values. */
2330 if (new_auto_val == master->manual_mode_value)
2331 update_from_auto_cluster(master);
2332 }
2333
0996517c 2334 /* Copy the new caller-supplied control values.
2a863793 2335 user_to_new() sets 'is_new' to 1. */
eb5b16ef
HV		 2336 do {
2337 ret = user_to_new(cs->controls + idx, helpers[idx].ctrl);
2338 idx = helpers[idx].next;
2339 } while (!ret && idx);
0996517c
HV		 2340
2341 if (!ret)
e6402585 2342 ret = try_or_set_cluster(fh, master, set);
0996517c
HV		 2343
2344 /* Copy the new values back to userspace. */
eb5b16ef
HV		 2345 if (!ret) {
2346 idx = i;
2347 do {
adf41b9b 2348 ret = new_to_user(cs->controls + idx,
e6402585 2349 helpers[idx].ctrl);
eb5b16ef
HV		 2350 idx = helpers[idx].next;
2351 } while (!ret && idx);
2352 }
2353 v4l2_ctrl_unlock(master);
0996517c 2354 }
0996517c 2355
0996517c
HV		 2356 if (cs->count > ARRAY_SIZE(helper))
2357 kfree(helpers);
2358 return ret;
2359}
2360
2361int v4l2_try_ext_ctrls(struct v4l2_ctrl_handler *hdl, struct v4l2_ext_controls *cs)
2362{
ab892bac 2363 return try_set_ext_ctrls(NULL, hdl, cs, false);
0996517c
HV		 2364}
2365EXPORT_SYMBOL(v4l2_try_ext_ctrls);
2366
ab892bac
HV		 2367int v4l2_s_ext_ctrls(struct v4l2_fh *fh, struct v4l2_ctrl_handler *hdl,
2368 struct v4l2_ext_controls *cs)
0996517c 2369{
ab892bac 2370 return try_set_ext_ctrls(fh, hdl, cs, true);
0996517c
HV		 2371}
2372EXPORT_SYMBOL(v4l2_s_ext_ctrls);
2373
2374int v4l2_subdev_try_ext_ctrls(struct v4l2_subdev *sd, struct v4l2_ext_controls *cs)
2375{
ab892bac 2376 return try_set_ext_ctrls(NULL, sd->ctrl_handler, cs, false);
0996517c
HV		 2377}
2378EXPORT_SYMBOL(v4l2_subdev_try_ext_ctrls);
2379
2380int v4l2_subdev_s_ext_ctrls(struct v4l2_subdev *sd, struct v4l2_ext_controls *cs)
2381{
ab892bac 2382 return try_set_ext_ctrls(NULL, sd->ctrl_handler, cs, true);
0996517c
HV		 2383}
2384EXPORT_SYMBOL(v4l2_subdev_s_ext_ctrls);
2385
2386/* Helper function for VIDIOC_S_CTRL compatibility */
ab892bac 2387static int set_ctrl(struct v4l2_fh *fh, struct v4l2_ctrl *ctrl, s32 *val)
0996517c
HV		 2388{
2389 struct v4l2_ctrl *master = ctrl->cluster[0];
2390 int ret;
2391 int i;
2392
eb5b16ef
HV		 2393 ret = validate_new_int(ctrl, val);
2394 if (ret)
2395 return ret;
2396
0996517c
HV		 2397 v4l2_ctrl_lock(ctrl);
2398
2a863793 2399 /* Reset the 'is_new' flags of the cluster */
0996517c
HV		 2400 for (i = 0; i < master->ncontrols; i++)
2401 if (master->cluster[i])
2a863793 2402 master->cluster[i]->is_new = 0;
0996517c 2403
5626b8c7
HV		 2404 /* For autoclusters with volatiles that are switched from auto to
2405 manual mode we have to update the current volatile values since
2406 those will become the initial manual values after such a switch. */
2407 if (master->is_auto && master->has_volatiles && ctrl == master &&
2408 !is_cur_manual(master) && *val == master->manual_mode_value)
2409 update_from_auto_cluster(master);
0996517c 2410 ctrl->val = *val;
2a863793 2411 ctrl->is_new = 1;
e6402585 2412 ret = try_or_set_cluster(fh, master, true);
0996517c
HV		 2413 *val = ctrl->cur.val;
2414 v4l2_ctrl_unlock(ctrl);
2415 return ret;
2416}
2417
ab892bac
HV		 2418int v4l2_s_ctrl(struct v4l2_fh *fh, struct v4l2_ctrl_handler *hdl,
2419 struct v4l2_control *control)
0996517c
HV		 2420{
2421 struct v4l2_ctrl *ctrl = v4l2_ctrl_find(hdl, control->id);
2422
2423 if (ctrl == NULL || !type_is_int(ctrl))
2424 return -EINVAL;
2425
7ebbc39f
HV		 2426 if (ctrl->flags & V4L2_CTRL_FLAG_READ_ONLY)
2427 return -EACCES;
2428
ab892bac 2429 return set_ctrl(fh, ctrl, &control->value);
0996517c
HV		 2430}
2431EXPORT_SYMBOL(v4l2_s_ctrl);
2432
2433int v4l2_subdev_s_ctrl(struct v4l2_subdev *sd, struct v4l2_control *control)
2434{
ab892bac 2435 return v4l2_s_ctrl(NULL, sd->ctrl_handler, control);
0996517c
HV		 2436}
2437EXPORT_SYMBOL(v4l2_subdev_s_ctrl);
2438
2439int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val)
2440{
2441 /* It's a driver bug if this happens. */
2442 WARN_ON(!type_is_int(ctrl));
ab892bac 2443 return set_ctrl(NULL, ctrl, &val);
0996517c
HV		 2444}
2445EXPORT_SYMBOL(v4l2_ctrl_s_ctrl);
6e239399 2446
3e366149 2447static int v4l2_ctrl_add_event(struct v4l2_subscribed_event *sev)
6e239399 2448{
3e366149
HG		 2449 struct v4l2_ctrl *ctrl = v4l2_ctrl_find(sev->fh->ctrl_handler, sev->id);
2450
2451 if (ctrl == NULL)
2452 return -EINVAL;
2453
6e239399 2454 v4l2_ctrl_lock(ctrl);
77068d36 2455 list_add_tail(&sev->node, &ctrl->ev_subs);
6e239399 2456 if (ctrl->type != V4L2_CTRL_TYPE_CTRL_CLASS &&
77068d36 2457 (sev->flags & V4L2_EVENT_SUB_FL_SEND_INITIAL)) {
6e239399 2458 struct v4l2_event ev;
c12fcfd6 2459 u32 changes = V4L2_EVENT_CTRL_CH_FLAGS;
6e239399 2460
c12fcfd6
HV		 2461 if (!(ctrl->flags & V4L2_CTRL_FLAG_WRITE_ONLY))
2462 changes |= V4L2_EVENT_CTRL_CH_VALUE;
2463 fill_event(&ev, ctrl, changes);
77068d36 2464 v4l2_event_queue_fh(sev->fh, &ev);
6e239399
HV		 2465 }
2466 v4l2_ctrl_unlock(ctrl);
3e366149 2467 return 0;
6e239399 2468}
6e239399 2469
3e366149 2470static void v4l2_ctrl_del_event(struct v4l2_subscribed_event *sev)
6e239399 2471{
3e366149
HG		 2472 struct v4l2_ctrl *ctrl = v4l2_ctrl_find(sev->fh->ctrl_handler, sev->id);
2473
6e239399 2474 v4l2_ctrl_lock(ctrl);
77068d36 2475 list_del(&sev->node);
6e239399
HV		 2476 v4l2_ctrl_unlock(ctrl);
2477}
3e366149
HG		 2478
2479void v4l2_ctrl_replace(struct v4l2_event *old, const struct v4l2_event *new)
2480{
2481 u32 old_changes = old->u.ctrl.changes;
2482
2483 old->u.ctrl = new->u.ctrl;
2484 old->u.ctrl.changes |= old_changes;
2485}
2486EXPORT_SYMBOL(v4l2_ctrl_replace);
2487
2488void v4l2_ctrl_merge(const struct v4l2_event *old, struct v4l2_event *new)
2489{
2490 new->u.ctrl.changes |= old->u.ctrl.changes;
2491}
2492EXPORT_SYMBOL(v4l2_ctrl_merge);
2493
2494const struct v4l2_subscribed_event_ops v4l2_ctrl_sub_ev_ops = {
2495 .add = v4l2_ctrl_add_event,
2496 .del = v4l2_ctrl_del_event,
2497 .replace = v4l2_ctrl_replace,
2498 .merge = v4l2_ctrl_merge,
2499};
2500EXPORT_SYMBOL(v4l2_ctrl_sub_ev_ops);
e2ecb257
HV		 2501
2502int v4l2_ctrl_log_status(struct file *file, void *fh)
2503{
2504 struct video_device *vfd = video_devdata(file);
2505 struct v4l2_fh *vfh = file->private_data;
2506
2507 if (test_bit(V4L2_FL_USES_V4L2_FH, &vfd->flags) && vfd->v4l2_dev)
2508 v4l2_ctrl_handler_log_status(vfh->ctrl_handler,
2509 vfd->v4l2_dev->name);
2510 return 0;
2511}
2512EXPORT_SYMBOL(v4l2_ctrl_log_status);
a26243b0
HV		 2513
2514int v4l2_ctrl_subscribe_event(struct v4l2_fh *fh,
2515 struct v4l2_event_subscription *sub)
2516{
2517 if (sub->type == V4L2_EVENT_CTRL)
3e366149 2518 return v4l2_event_subscribe(fh, sub, 0, &v4l2_ctrl_sub_ev_ops);
a26243b0
HV		 2519 return -EINVAL;
2520}
2521EXPORT_SYMBOL(v4l2_ctrl_subscribe_event);
2522
2523unsigned int v4l2_ctrl_poll(struct file *file, struct poll_table_struct *wait)
2524{
2525 struct v4l2_fh *fh = file->private_data;
2526
2527 if (v4l2_event_pending(fh))
2528 return POLLPRI;
2529 poll_wait(file, &fh->wait, wait);
2530 return 0;
2531}
2532EXPORT_SYMBOL(v4l2_ctrl_poll);
Linux 6.x block layer and io_uring tree(s)