1 /*
2  *	Video for Linux Two
3  *
4  *	A generic video device interface for the LINUX operating system
5  *	using a set of device structures/vectors for low level operations.
6  *
7  *	This file replaces the videodev.c file that comes with the
8  *	regular kernel distribution.
9  *
10  *	This program is free software; you can redistribute it and/or
11  *	modify it under the terms of the GNU General Public License
12  *	as published by the Free Software Foundation; either version
13  *	2 of the License, or (at your option) any later version.
14  *
15  * Author:	Bill Dirks <bill@thedirks.org>
16  *		based on code by Alan Cox, <alan@cymru.net>
17  *
18  */
19 
20 /*
21  * Video capture interface for Linux
22  *
23  *	A generic video device interface for the LINUX operating system
24  *	using a set of device structures/vectors for low level operations.
25  *
26  *		This program is free software; you can redistribute it and/or
27  *		modify it under the terms of the GNU General Public License
28  *		as published by the Free Software Foundation; either version
29  *		2 of the License, or (at your option) any later version.
30  *
31  * Author:	Alan Cox, <alan@lxorguk.ukuu.org.uk>
32  *
33  * Fixes:
34  */
35 
36 /*
37  * Video4linux 1/2 integration by Justin Schoeman
38  * <justin@suntiger.ee.up.ac.za>
39  * 2.4 PROCFS support ported from 2.4 kernels by
40  *  Iñaki García Etxebarria <garetxe@euskalnet.net>
41  * Makefile fix by "W. Michael Petullo" <mike@flyn.org>
42  * 2.4 devfs support ported from 2.4 kernels by
43  *  Dan Merillat <dan@merillat.org>
44  * Added Gerd Knorrs v4l1 enhancements (Justin Schoeman)
45  */
46 
47 #include <linux/module.h>
48 #include <linux/types.h>
49 #include <linux/kernel.h>
50 #include <linux/mm.h>
51 #include <linux/string.h>
52 #include <linux/errno.h>
53 #include <linux/i2c.h>
54 #if defined(CONFIG_SPI)
55 #include <linux/spi/spi.h>
56 #endif
57 #include <asm/uaccess.h>
58 #include <asm/pgtable.h>
59 #include <asm/io.h>
60 #include <asm/div64.h>
61 #include <media/v4l2-common.h>
62 #include <media/v4l2-device.h>
63 #include <media/v4l2-ctrls.h>
64 
65 #include <linux/videodev2.h>
66 
67 MODULE_AUTHOR("Bill Dirks, Justin Schoeman, Gerd Knorr");
68 MODULE_DESCRIPTION("misc helper functions for v4l2 device drivers");
69 MODULE_LICENSE("GPL");
70 
71 /*
72  *
73  *	V 4 L 2   D R I V E R   H E L P E R   A P I
74  *
75  */
76 
77 /*
78  *  Video Standard Operations (contributed by Michael Schimek)
79  */
80 
81 /* Helper functions for control handling			     */
82 
83 /* Check for correctness of the ctrl's value based on the data from
84    struct v4l2_queryctrl and the available menu items. Note that
85    menu_items may be NULL, in that case it is ignored. */
86 int v4l2_ctrl_check(struct v4l2_ext_control *ctrl, struct v4l2_queryctrl *qctrl,
87 		const char * const *menu_items)
88 {
89 	if (qctrl->flags & V4L2_CTRL_FLAG_DISABLED)
90 		return -EINVAL;
91 	if (qctrl->flags & V4L2_CTRL_FLAG_GRABBED)
92 		return -EBUSY;
93 	if (qctrl->type == V4L2_CTRL_TYPE_STRING)
94 		return 0;
95 	if (qctrl->type == V4L2_CTRL_TYPE_BUTTON ||
96 	    qctrl->type == V4L2_CTRL_TYPE_INTEGER64 ||
97 	    qctrl->type == V4L2_CTRL_TYPE_CTRL_CLASS)
98 		return 0;
99 	if (ctrl->value < qctrl->minimum || ctrl->value > qctrl->maximum)
100 		return -ERANGE;
101 	if (qctrl->type == V4L2_CTRL_TYPE_MENU && menu_items != NULL) {
102 		if (menu_items[ctrl->value] == NULL ||
103 		    menu_items[ctrl->value][0] == '\0')
104 			return -EINVAL;
105 	}
106 	if (qctrl->type == V4L2_CTRL_TYPE_BITMASK &&
107 			(ctrl->value & ~qctrl->maximum))
108 		return -ERANGE;
109 	return 0;
110 }
111 EXPORT_SYMBOL(v4l2_ctrl_check);
112 
113 /* Fill in a struct v4l2_queryctrl */
114 int v4l2_ctrl_query_fill(struct v4l2_queryctrl *qctrl, s32 _min, s32 _max, s32 _step, s32 _def)
115 {
116 	const char *name;
117 	s64 min = _min;
118 	s64 max = _max;
119 	u64 step = _step;
120 	s64 def = _def;
121 
122 	v4l2_ctrl_fill(qctrl->id, &name, &qctrl->type,
123 		       &min, &max, &step, &def, &qctrl->flags);
124 
125 	if (name == NULL)
126 		return -EINVAL;
127 
128 	qctrl->minimum = min;
129 	qctrl->maximum = max;
130 	qctrl->step = step;
131 	qctrl->default_value = def;
132 	qctrl->reserved[0] = qctrl->reserved[1] = 0;
133 	strlcpy(qctrl->name, name, sizeof(qctrl->name));
134 	return 0;
135 }
136 EXPORT_SYMBOL(v4l2_ctrl_query_fill);
137 
138 /* Fill in a struct v4l2_querymenu based on the struct v4l2_queryctrl and
139    the menu. The qctrl pointer may be NULL, in which case it is ignored.
140    If menu_items is NULL, then the menu items are retrieved using
141    v4l2_ctrl_get_menu. */
142 int v4l2_ctrl_query_menu(struct v4l2_querymenu *qmenu, struct v4l2_queryctrl *qctrl,
143 	       const char * const *menu_items)
144 {
145 	int i;
146 
147 	qmenu->reserved = 0;
148 	if (menu_items == NULL)
149 		menu_items = v4l2_ctrl_get_menu(qmenu->id);
150 	if (menu_items == NULL ||
151 	    (qctrl && (qmenu->index < qctrl->minimum || qmenu->index > qctrl->maximum)))
152 		return -EINVAL;
153 	for (i = 0; i < qmenu->index && menu_items[i]; i++) ;
154 	if (menu_items[i] == NULL || menu_items[i][0] == '\0')
155 		return -EINVAL;
156 	strlcpy(qmenu->name, menu_items[qmenu->index], sizeof(qmenu->name));
157 	return 0;
158 }
159 EXPORT_SYMBOL(v4l2_ctrl_query_menu);
160 
161 /* Fill in a struct v4l2_querymenu based on the specified array of valid
162    menu items (terminated by V4L2_CTRL_MENU_IDS_END).
163    Use this if there are 'holes' in the list of valid menu items. */
164 int v4l2_ctrl_query_menu_valid_items(struct v4l2_querymenu *qmenu, const u32 *ids)
165 {
166 	const char * const *menu_items = v4l2_ctrl_get_menu(qmenu->id);
167 
168 	qmenu->reserved = 0;
169 	if (menu_items == NULL || ids == NULL)
170 		return -EINVAL;
171 	while (*ids != V4L2_CTRL_MENU_IDS_END) {
172 		if (*ids++ == qmenu->index) {
173 			strlcpy(qmenu->name, menu_items[qmenu->index],
174 					sizeof(qmenu->name));
175 			return 0;
176 		}
177 	}
178 	return -EINVAL;
179 }
180 EXPORT_SYMBOL(v4l2_ctrl_query_menu_valid_items);
181 
182 /* ctrl_classes points to an array of u32 pointers, the last element is
183    a NULL pointer. Each u32 array is a 0-terminated array of control IDs.
184    Each array must be sorted low to high and belong to the same control
185    class. The array of u32 pointers must also be sorted, from low class IDs
186    to high class IDs.
187 
188    This function returns the first ID that follows after the given ID.
189    When no more controls are available 0 is returned. */
190 u32 v4l2_ctrl_next(const u32 * const * ctrl_classes, u32 id)
191 {
192 	u32 ctrl_class = V4L2_CTRL_ID2CLASS(id);
193 	const u32 *pctrl;
194 
195 	if (ctrl_classes == NULL)
196 		return 0;
197 
198 	/* if no query is desired, then check if the ID is part of ctrl_classes */
199 	if ((id & V4L2_CTRL_FLAG_NEXT_CTRL) == 0) {
200 		/* find class */
201 		while (*ctrl_classes && V4L2_CTRL_ID2CLASS(**ctrl_classes) != ctrl_class)
202 			ctrl_classes++;
203 		if (*ctrl_classes == NULL)
204 			return 0;
205 		pctrl = *ctrl_classes;
206 		/* find control ID */
207 		while (*pctrl && *pctrl != id) pctrl++;
208 		return *pctrl ? id : 0;
209 	}
210 	id &= V4L2_CTRL_ID_MASK;
211 	id++;	/* select next control */
212 	/* find first class that matches (or is greater than) the class of
213 	   the ID */
214 	while (*ctrl_classes && V4L2_CTRL_ID2CLASS(**ctrl_classes) < ctrl_class)
215 		ctrl_classes++;
216 	/* no more classes */
217 	if (*ctrl_classes == NULL)
218 		return 0;
219 	pctrl = *ctrl_classes;
220 	/* find first ctrl within the class that is >= ID */
221 	while (*pctrl && *pctrl < id) pctrl++;
222 	if (*pctrl)
223 		return *pctrl;
224 	/* we are at the end of the controls of the current class. */
225 	/* continue with next class if available */
226 	ctrl_classes++;
227 	if (*ctrl_classes == NULL)
228 		return 0;
229 	return **ctrl_classes;
230 }
231 EXPORT_SYMBOL(v4l2_ctrl_next);
232 
233 /* I2C Helper functions */
234 
235 #if IS_ENABLED(CONFIG_I2C)
236 
237 void v4l2_i2c_subdev_init(struct v4l2_subdev *sd, struct i2c_client *client,
238 		const struct v4l2_subdev_ops *ops)
239 {
240 	v4l2_subdev_init(sd, ops);
241 	sd->flags |= V4L2_SUBDEV_FL_IS_I2C;
242 	/* the owner is the same as the i2c_client's driver owner */
243 	sd->owner = client->dev.driver->owner;
244 	sd->dev = &client->dev;
245 	/* i2c_client and v4l2_subdev point to one another */
246 	v4l2_set_subdevdata(sd, client);
247 	i2c_set_clientdata(client, sd);
248 	/* initialize name */
249 	snprintf(sd->name, sizeof(sd->name), "%s %d-%04x",
250 		client->dev.driver->name, i2c_adapter_id(client->adapter),
251 		client->addr);
252 }
253 EXPORT_SYMBOL_GPL(v4l2_i2c_subdev_init);
254 
255 /* Load an i2c sub-device. */
256 struct v4l2_subdev *v4l2_i2c_new_subdev_board(struct v4l2_device *v4l2_dev,
257 		struct i2c_adapter *adapter, struct i2c_board_info *info,
258 		const unsigned short *probe_addrs)
259 {
260 	struct v4l2_subdev *sd = NULL;
261 	struct i2c_client *client;
262 
263 	BUG_ON(!v4l2_dev);
264 
265 	request_module(I2C_MODULE_PREFIX "%s", info->type);
266 
267 	/* Create the i2c client */
268 	if (info->addr == 0 && probe_addrs)
269 		client = i2c_new_probed_device(adapter, info, probe_addrs,
270 					       NULL);
271 	else
272 		client = i2c_new_device(adapter, info);
273 
274 	/* Note: by loading the module first we are certain that c->driver
275 	   will be set if the driver was found. If the module was not loaded
276 	   first, then the i2c core tries to delay-load the module for us,
277 	   and then c->driver is still NULL until the module is finally
278 	   loaded. This delay-load mechanism doesn't work if other drivers
279 	   want to use the i2c device, so explicitly loading the module
280 	   is the best alternative. */
281 	if (client == NULL || client->dev.driver == NULL)
282 		goto error;
283 
284 	/* Lock the module so we can safely get the v4l2_subdev pointer */
285 	if (!try_module_get(client->dev.driver->owner))
286 		goto error;
287 	sd = i2c_get_clientdata(client);
288 
289 	/* Register with the v4l2_device which increases the module's
290 	   use count as well. */
291 	if (v4l2_device_register_subdev(v4l2_dev, sd))
292 		sd = NULL;
293 	/* Decrease the module use count to match the first try_module_get. */
294 	module_put(client->dev.driver->owner);
295 
296 error:
297 	/* If we have a client but no subdev, then something went wrong and
298 	   we must unregister the client. */
299 	if (client && sd == NULL)
300 		i2c_unregister_device(client);
301 	return sd;
302 }
303 EXPORT_SYMBOL_GPL(v4l2_i2c_new_subdev_board);
304 
305 struct v4l2_subdev *v4l2_i2c_new_subdev(struct v4l2_device *v4l2_dev,
306 		struct i2c_adapter *adapter, const char *client_type,
307 		u8 addr, const unsigned short *probe_addrs)
308 {
309 	struct i2c_board_info info;
310 
311 	/* Setup the i2c board info with the device type and
312 	   the device address. */
313 	memset(&info, 0, sizeof(info));
314 	strlcpy(info.type, client_type, sizeof(info.type));
315 	info.addr = addr;
316 
317 	return v4l2_i2c_new_subdev_board(v4l2_dev, adapter, &info, probe_addrs);
318 }
319 EXPORT_SYMBOL_GPL(v4l2_i2c_new_subdev);
320 
321 /* Return i2c client address of v4l2_subdev. */
322 unsigned short v4l2_i2c_subdev_addr(struct v4l2_subdev *sd)
323 {
324 	struct i2c_client *client = v4l2_get_subdevdata(sd);
325 
326 	return client ? client->addr : I2C_CLIENT_END;
327 }
328 EXPORT_SYMBOL_GPL(v4l2_i2c_subdev_addr);
329 
330 /* Return a list of I2C tuner addresses to probe. Use only if the tuner
331    addresses are unknown. */
332 const unsigned short *v4l2_i2c_tuner_addrs(enum v4l2_i2c_tuner_type type)
333 {
334 	static const unsigned short radio_addrs[] = {
335 #if IS_ENABLED(CONFIG_MEDIA_TUNER_TEA5761)
336 		0x10,
337 #endif
338 		0x60,
339 		I2C_CLIENT_END
340 	};
341 	static const unsigned short demod_addrs[] = {
342 		0x42, 0x43, 0x4a, 0x4b,
343 		I2C_CLIENT_END
344 	};
345 	static const unsigned short tv_addrs[] = {
346 		0x42, 0x43, 0x4a, 0x4b,		/* tda8290 */
347 		0x60, 0x61, 0x62, 0x63, 0x64,
348 		I2C_CLIENT_END
349 	};
350 
351 	switch (type) {
352 	case ADDRS_RADIO:
353 		return radio_addrs;
354 	case ADDRS_DEMOD:
355 		return demod_addrs;
356 	case ADDRS_TV:
357 		return tv_addrs;
358 	case ADDRS_TV_WITH_DEMOD:
359 		return tv_addrs + 4;
360 	}
361 	return NULL;
362 }
363 EXPORT_SYMBOL_GPL(v4l2_i2c_tuner_addrs);
364 
365 #endif /* defined(CONFIG_I2C) */
366 
367 #if defined(CONFIG_SPI)
368 
369 /* Load an spi sub-device. */
370 
371 void v4l2_spi_subdev_init(struct v4l2_subdev *sd, struct spi_device *spi,
372 		const struct v4l2_subdev_ops *ops)
373 {
374 	v4l2_subdev_init(sd, ops);
375 	sd->flags |= V4L2_SUBDEV_FL_IS_SPI;
376 	/* the owner is the same as the spi_device's driver owner */
377 	sd->owner = spi->dev.driver->owner;
378 	sd->dev = &spi->dev;
379 	/* spi_device and v4l2_subdev point to one another */
380 	v4l2_set_subdevdata(sd, spi);
381 	spi_set_drvdata(spi, sd);
382 	/* initialize name */
383 	strlcpy(sd->name, spi->dev.driver->name, sizeof(sd->name));
384 }
385 EXPORT_SYMBOL_GPL(v4l2_spi_subdev_init);
386 
387 struct v4l2_subdev *v4l2_spi_new_subdev(struct v4l2_device *v4l2_dev,
388 		struct spi_master *master, struct spi_board_info *info)
389 {
390 	struct v4l2_subdev *sd = NULL;
391 	struct spi_device *spi = NULL;
392 
393 	BUG_ON(!v4l2_dev);
394 
395 	if (info->modalias[0])
396 		request_module(info->modalias);
397 
398 	spi = spi_new_device(master, info);
399 
400 	if (spi == NULL || spi->dev.driver == NULL)
401 		goto error;
402 
403 	if (!try_module_get(spi->dev.driver->owner))
404 		goto error;
405 
406 	sd = spi_get_drvdata(spi);
407 
408 	/* Register with the v4l2_device which increases the module's
409 	   use count as well. */
410 	if (v4l2_device_register_subdev(v4l2_dev, sd))
411 		sd = NULL;
412 
413 	/* Decrease the module use count to match the first try_module_get. */
414 	module_put(spi->dev.driver->owner);
415 
416 error:
417 	/* If we have a client but no subdev, then something went wrong and
418 	   we must unregister the client. */
419 	if (spi && sd == NULL)
420 		spi_unregister_device(spi);
421 
422 	return sd;
423 }
424 EXPORT_SYMBOL_GPL(v4l2_spi_new_subdev);
425 
426 #endif /* defined(CONFIG_SPI) */
427 
428 /* Clamp x to be between min and max, aligned to a multiple of 2^align.  min
429  * and max don't have to be aligned, but there must be at least one valid
430  * value.  E.g., min=17,max=31,align=4 is not allowed as there are no multiples
431  * of 16 between 17 and 31.  */
432 static unsigned int clamp_align(unsigned int x, unsigned int min,
433 				unsigned int max, unsigned int align)
434 {
435 	/* Bits that must be zero to be aligned */
436 	unsigned int mask = ~((1 << align) - 1);
437 
438 	/* Clamp to aligned min and max */
439 	x = clamp(x, (min + ~mask) & mask, max & mask);
440 
441 	/* Round to nearest aligned value */
442 	if (align)
443 		x = (x + (1 << (align - 1))) & mask;
444 
445 	return x;
446 }
447 
448 /* Bound an image to have a width between wmin and wmax, and height between
449  * hmin and hmax, inclusive.  Additionally, the width will be a multiple of
450  * 2^walign, the height will be a multiple of 2^halign, and the overall size
451  * (width*height) will be a multiple of 2^salign.  The image may be shrunk
452  * or enlarged to fit the alignment constraints.
453  *
454  * The width or height maximum must not be smaller than the corresponding
455  * minimum.  The alignments must not be so high there are no possible image
456  * sizes within the allowed bounds.  wmin and hmin must be at least 1
457  * (don't use 0).  If you don't care about a certain alignment, specify 0,
458  * as 2^0 is 1 and one byte alignment is equivalent to no alignment.  If
459  * you only want to adjust downward, specify a maximum that's the same as
460  * the initial value.
461  */
462 void v4l_bound_align_image(u32 *w, unsigned int wmin, unsigned int wmax,
463 			   unsigned int walign,
464 			   u32 *h, unsigned int hmin, unsigned int hmax,
465 			   unsigned int halign, unsigned int salign)
466 {
467 	*w = clamp_align(*w, wmin, wmax, walign);
468 	*h = clamp_align(*h, hmin, hmax, halign);
469 
470 	/* Usually we don't need to align the size and are done now. */
471 	if (!salign)
472 		return;
473 
474 	/* How much alignment do we have? */
475 	walign = __ffs(*w);
476 	halign = __ffs(*h);
477 	/* Enough to satisfy the image alignment? */
478 	if (walign + halign < salign) {
479 		/* Max walign where there is still a valid width */
480 		unsigned int wmaxa = __fls(wmax ^ (wmin - 1));
481 		/* Max halign where there is still a valid height */
482 		unsigned int hmaxa = __fls(hmax ^ (hmin - 1));
483 
484 		/* up the smaller alignment until we have enough */
485 		do {
486 			if (halign >= hmaxa ||
487 			    (walign <= halign && walign < wmaxa)) {
488 				*w = clamp_align(*w, wmin, wmax, walign + 1);
489 				walign = __ffs(*w);
490 			} else {
491 				*h = clamp_align(*h, hmin, hmax, halign + 1);
492 				halign = __ffs(*h);
493 			}
494 		} while (halign + walign < salign);
495 	}
496 }
497 EXPORT_SYMBOL_GPL(v4l_bound_align_image);
498 
499 const struct v4l2_frmsize_discrete *v4l2_find_nearest_format(
500 		const struct v4l2_discrete_probe *probe,
501 		s32 width, s32 height)
502 {
503 	int i;
504 	u32 error, min_error = UINT_MAX;
505 	const struct v4l2_frmsize_discrete *size, *best = NULL;
506 
507 	if (!probe)
508 		return best;
509 
510 	for (i = 0, size = probe->sizes; i < probe->num_sizes; i++, size++) {
511 		error = abs(size->width - width) + abs(size->height - height);
512 		if (error < min_error) {
513 			min_error = error;
514 			best = size;
515 		}
516 		if (!error)
517 			break;
518 	}
519 
520 	return best;
521 }
522 EXPORT_SYMBOL_GPL(v4l2_find_nearest_format);
523 
524 void v4l2_get_timestamp(struct timeval *tv)
525 {
526 	struct timespec ts;
527 
528 	ktime_get_ts(&ts);
529 	tv->tv_sec = ts.tv_sec;
530 	tv->tv_usec = ts.tv_nsec / NSEC_PER_USEC;
531 }
532 EXPORT_SYMBOL_GPL(v4l2_get_timestamp);
533