4 * A generic video device interface for the LINUX operating system
5 * using a set of device structures/vectors for low level operations.
7 * This file replaces the videodev.c file that comes with the
8 * regular kernel distribution.
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.
15 * Author: Bill Dirks <bill@thedirks.org>
16 * based on code by Alan Cox, <alan@cymru.net>
21 * Video capture interface for Linux
23 * A generic video device interface for the LINUX operating system
24 * using a set of device structures/vectors for low level operations.
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.
31 * Author: Alan Cox, <alan@lxorguk.ukuu.org.uk>
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)
47 #include <linux/module.h>
48 #include <linux/types.h>
49 #include <linux/kernel.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>
57 #include <asm/uaccess.h>
58 #include <asm/system.h>
59 #include <asm/pgtable.h>
61 #include <asm/div64.h>
62 #define __OLD_VIDIOC_ /* To allow fixing old calls*/
63 #include <media/v4l2-common.h>
64 #include <media/v4l2-device.h>
65 #include <media/v4l2-ctrls.h>
66 #include <media/v4l2-chip-ident.h>
68 #include <linux/videodev2.h>
70 MODULE_AUTHOR("Bill Dirks, Justin Schoeman, Gerd Knorr");
71 MODULE_DESCRIPTION("misc helper functions for v4l2 device drivers");
72 MODULE_LICENSE("GPL");
76 * V 4 L 2 D R I V E R H E L P E R A P I
81 * Video Standard Operations (contributed by Michael Schimek)
85 /* ----------------------------------------------------------------- */
86 /* priority handling */
88 #define V4L2_PRIO_VALID(val) (val == V4L2_PRIORITY_BACKGROUND || \
89 val == V4L2_PRIORITY_INTERACTIVE || \
90 val == V4L2_PRIORITY_RECORD)
92 void v4l2_prio_init(struct v4l2_prio_state *global)
94 memset(global, 0, sizeof(*global));
96 EXPORT_SYMBOL(v4l2_prio_init);
98 int v4l2_prio_change(struct v4l2_prio_state *global, enum v4l2_priority *local,
99 enum v4l2_priority new)
101 if (!V4L2_PRIO_VALID(new))
106 atomic_inc(&global->prios[new]);
107 if (V4L2_PRIO_VALID(*local))
108 atomic_dec(&global->prios[*local]);
112 EXPORT_SYMBOL(v4l2_prio_change);
114 void v4l2_prio_open(struct v4l2_prio_state *global, enum v4l2_priority *local)
116 v4l2_prio_change(global, local, V4L2_PRIORITY_DEFAULT);
118 EXPORT_SYMBOL(v4l2_prio_open);
120 void v4l2_prio_close(struct v4l2_prio_state *global, enum v4l2_priority local)
122 if (V4L2_PRIO_VALID(local))
123 atomic_dec(&global->prios[local]);
125 EXPORT_SYMBOL(v4l2_prio_close);
127 enum v4l2_priority v4l2_prio_max(struct v4l2_prio_state *global)
129 if (atomic_read(&global->prios[V4L2_PRIORITY_RECORD]) > 0)
130 return V4L2_PRIORITY_RECORD;
131 if (atomic_read(&global->prios[V4L2_PRIORITY_INTERACTIVE]) > 0)
132 return V4L2_PRIORITY_INTERACTIVE;
133 if (atomic_read(&global->prios[V4L2_PRIORITY_BACKGROUND]) > 0)
134 return V4L2_PRIORITY_BACKGROUND;
135 return V4L2_PRIORITY_UNSET;
137 EXPORT_SYMBOL(v4l2_prio_max);
139 int v4l2_prio_check(struct v4l2_prio_state *global, enum v4l2_priority local)
141 return (local < v4l2_prio_max(global)) ? -EBUSY : 0;
143 EXPORT_SYMBOL(v4l2_prio_check);
145 /* ----------------------------------------------------------------- */
147 /* Helper functions for control handling */
149 /* Check for correctness of the ctrl's value based on the data from
150 struct v4l2_queryctrl and the available menu items. Note that
151 menu_items may be NULL, in that case it is ignored. */
152 int v4l2_ctrl_check(struct v4l2_ext_control *ctrl, struct v4l2_queryctrl *qctrl,
153 const char **menu_items)
155 if (qctrl->flags & V4L2_CTRL_FLAG_DISABLED)
157 if (qctrl->flags & V4L2_CTRL_FLAG_GRABBED)
159 if (qctrl->type == V4L2_CTRL_TYPE_STRING)
161 if (qctrl->type == V4L2_CTRL_TYPE_BUTTON ||
162 qctrl->type == V4L2_CTRL_TYPE_INTEGER64 ||
163 qctrl->type == V4L2_CTRL_TYPE_CTRL_CLASS)
165 if (ctrl->value < qctrl->minimum || ctrl->value > qctrl->maximum)
167 if (qctrl->type == V4L2_CTRL_TYPE_MENU && menu_items != NULL) {
168 if (menu_items[ctrl->value] == NULL ||
169 menu_items[ctrl->value][0] == '\0')
174 EXPORT_SYMBOL(v4l2_ctrl_check);
176 /* Fill in a struct v4l2_queryctrl */
177 int v4l2_ctrl_query_fill(struct v4l2_queryctrl *qctrl, s32 min, s32 max, s32 step, s32 def)
181 v4l2_ctrl_fill(qctrl->id, &name, &qctrl->type,
182 &min, &max, &step, &def, &qctrl->flags);
187 qctrl->minimum = min;
188 qctrl->maximum = max;
190 qctrl->default_value = def;
191 qctrl->reserved[0] = qctrl->reserved[1] = 0;
192 strlcpy(qctrl->name, name, sizeof(qctrl->name));
195 EXPORT_SYMBOL(v4l2_ctrl_query_fill);
197 /* Fill in a struct v4l2_querymenu based on the struct v4l2_queryctrl and
198 the menu. The qctrl pointer may be NULL, in which case it is ignored.
199 If menu_items is NULL, then the menu items are retrieved using
200 v4l2_ctrl_get_menu. */
201 int v4l2_ctrl_query_menu(struct v4l2_querymenu *qmenu, struct v4l2_queryctrl *qctrl,
202 const char **menu_items)
207 if (menu_items == NULL)
208 menu_items = v4l2_ctrl_get_menu(qmenu->id);
209 if (menu_items == NULL ||
210 (qctrl && (qmenu->index < qctrl->minimum || qmenu->index > qctrl->maximum)))
212 for (i = 0; i < qmenu->index && menu_items[i]; i++) ;
213 if (menu_items[i] == NULL || menu_items[i][0] == '\0')
215 strlcpy(qmenu->name, menu_items[qmenu->index], sizeof(qmenu->name));
218 EXPORT_SYMBOL(v4l2_ctrl_query_menu);
220 /* Fill in a struct v4l2_querymenu based on the specified array of valid
221 menu items (terminated by V4L2_CTRL_MENU_IDS_END).
222 Use this if there are 'holes' in the list of valid menu items. */
223 int v4l2_ctrl_query_menu_valid_items(struct v4l2_querymenu *qmenu, const u32 *ids)
225 const char **menu_items = v4l2_ctrl_get_menu(qmenu->id);
228 if (menu_items == NULL || ids == NULL)
230 while (*ids != V4L2_CTRL_MENU_IDS_END) {
231 if (*ids++ == qmenu->index) {
232 strlcpy(qmenu->name, menu_items[qmenu->index],
233 sizeof(qmenu->name));
239 EXPORT_SYMBOL(v4l2_ctrl_query_menu_valid_items);
241 /* ctrl_classes points to an array of u32 pointers, the last element is
242 a NULL pointer. Each u32 array is a 0-terminated array of control IDs.
243 Each array must be sorted low to high and belong to the same control
244 class. The array of u32 pointers must also be sorted, from low class IDs
247 This function returns the first ID that follows after the given ID.
248 When no more controls are available 0 is returned. */
249 u32 v4l2_ctrl_next(const u32 * const * ctrl_classes, u32 id)
251 u32 ctrl_class = V4L2_CTRL_ID2CLASS(id);
254 if (ctrl_classes == NULL)
257 /* if no query is desired, then check if the ID is part of ctrl_classes */
258 if ((id & V4L2_CTRL_FLAG_NEXT_CTRL) == 0) {
260 while (*ctrl_classes && V4L2_CTRL_ID2CLASS(**ctrl_classes) != ctrl_class)
262 if (*ctrl_classes == NULL)
264 pctrl = *ctrl_classes;
265 /* find control ID */
266 while (*pctrl && *pctrl != id) pctrl++;
267 return *pctrl ? id : 0;
269 id &= V4L2_CTRL_ID_MASK;
270 id++; /* select next control */
271 /* find first class that matches (or is greater than) the class of
273 while (*ctrl_classes && V4L2_CTRL_ID2CLASS(**ctrl_classes) < ctrl_class)
275 /* no more classes */
276 if (*ctrl_classes == NULL)
278 pctrl = *ctrl_classes;
279 /* find first ctrl within the class that is >= ID */
280 while (*pctrl && *pctrl < id) pctrl++;
283 /* we are at the end of the controls of the current class. */
284 /* continue with next class if available */
286 if (*ctrl_classes == NULL)
288 return **ctrl_classes;
290 EXPORT_SYMBOL(v4l2_ctrl_next);
292 int v4l2_chip_match_host(const struct v4l2_dbg_match *match)
294 switch (match->type) {
295 case V4L2_CHIP_MATCH_HOST:
296 return match->addr == 0;
301 EXPORT_SYMBOL(v4l2_chip_match_host);
303 #if defined(CONFIG_I2C) || (defined(CONFIG_I2C_MODULE) && defined(MODULE))
304 int v4l2_chip_match_i2c_client(struct i2c_client *c, const struct v4l2_dbg_match *match)
308 if (c == NULL || match == NULL)
311 switch (match->type) {
312 case V4L2_CHIP_MATCH_I2C_DRIVER:
313 if (c->driver == NULL || c->driver->driver.name == NULL)
315 len = strlen(c->driver->driver.name);
316 /* legacy drivers have a ' suffix, don't try to match that */
317 if (len && c->driver->driver.name[len - 1] == '\'')
319 return len && !strncmp(c->driver->driver.name, match->name, len);
320 case V4L2_CHIP_MATCH_I2C_ADDR:
321 return c->addr == match->addr;
326 EXPORT_SYMBOL(v4l2_chip_match_i2c_client);
328 int v4l2_chip_ident_i2c_client(struct i2c_client *c, struct v4l2_dbg_chip_ident *chip,
329 u32 ident, u32 revision)
331 if (!v4l2_chip_match_i2c_client(c, &chip->match))
333 if (chip->ident == V4L2_IDENT_NONE) {
335 chip->revision = revision;
338 chip->ident = V4L2_IDENT_AMBIGUOUS;
343 EXPORT_SYMBOL(v4l2_chip_ident_i2c_client);
345 /* ----------------------------------------------------------------- */
347 /* I2C Helper functions */
350 void v4l2_i2c_subdev_init(struct v4l2_subdev *sd, struct i2c_client *client,
351 const struct v4l2_subdev_ops *ops)
353 v4l2_subdev_init(sd, ops);
354 sd->flags |= V4L2_SUBDEV_FL_IS_I2C;
355 /* the owner is the same as the i2c_client's driver owner */
356 sd->owner = client->driver->driver.owner;
357 /* i2c_client and v4l2_subdev point to one another */
358 v4l2_set_subdevdata(sd, client);
359 i2c_set_clientdata(client, sd);
360 /* initialize name */
361 snprintf(sd->name, sizeof(sd->name), "%s %d-%04x",
362 client->driver->driver.name, i2c_adapter_id(client->adapter),
365 EXPORT_SYMBOL_GPL(v4l2_i2c_subdev_init);
369 /* Load an i2c sub-device. */
370 struct v4l2_subdev *v4l2_i2c_new_subdev_board(struct v4l2_device *v4l2_dev,
371 struct i2c_adapter *adapter, const char *module_name,
372 struct i2c_board_info *info, const unsigned short *probe_addrs)
374 struct v4l2_subdev *sd = NULL;
375 struct i2c_client *client;
380 request_module(module_name);
382 request_module(I2C_MODULE_PREFIX "%s", info->type);
384 /* Create the i2c client */
385 if (info->addr == 0 && probe_addrs)
386 client = i2c_new_probed_device(adapter, info, probe_addrs,
389 client = i2c_new_device(adapter, info);
391 /* Note: by loading the module first we are certain that c->driver
392 will be set if the driver was found. If the module was not loaded
393 first, then the i2c core tries to delay-load the module for us,
394 and then c->driver is still NULL until the module is finally
395 loaded. This delay-load mechanism doesn't work if other drivers
396 want to use the i2c device, so explicitly loading the module
397 is the best alternative. */
398 if (client == NULL || client->driver == NULL)
401 /* Lock the module so we can safely get the v4l2_subdev pointer */
402 if (!try_module_get(client->driver->driver.owner))
404 sd = i2c_get_clientdata(client);
406 /* Register with the v4l2_device which increases the module's
407 use count as well. */
408 if (v4l2_device_register_subdev(v4l2_dev, sd))
410 /* Decrease the module use count to match the first try_module_get. */
411 module_put(client->driver->driver.owner);
414 /* We return errors from v4l2_subdev_call only if we have the
415 callback as the .s_config is not mandatory */
416 int err = v4l2_subdev_call(sd, core, s_config,
417 info->irq, info->platform_data);
419 if (err && err != -ENOIOCTLCMD) {
420 v4l2_device_unregister_subdev(sd);
426 /* If we have a client but no subdev, then something went wrong and
427 we must unregister the client. */
428 if (client && sd == NULL)
429 i2c_unregister_device(client);
432 EXPORT_SYMBOL_GPL(v4l2_i2c_new_subdev_board);
434 struct v4l2_subdev *v4l2_i2c_new_subdev_cfg(struct v4l2_device *v4l2_dev,
435 struct i2c_adapter *adapter,
436 const char *module_name, const char *client_type,
437 int irq, void *platform_data,
438 u8 addr, const unsigned short *probe_addrs)
440 struct i2c_board_info info;
442 /* Setup the i2c board info with the device type and
443 the device address. */
444 memset(&info, 0, sizeof(info));
445 strlcpy(info.type, client_type, sizeof(info.type));
448 info.platform_data = platform_data;
450 return v4l2_i2c_new_subdev_board(v4l2_dev, adapter, module_name,
453 EXPORT_SYMBOL_GPL(v4l2_i2c_new_subdev_cfg);
455 /* Return i2c client address of v4l2_subdev. */
456 unsigned short v4l2_i2c_subdev_addr(struct v4l2_subdev *sd)
458 struct i2c_client *client = v4l2_get_subdevdata(sd);
460 return client ? client->addr : I2C_CLIENT_END;
462 EXPORT_SYMBOL_GPL(v4l2_i2c_subdev_addr);
464 /* Return a list of I2C tuner addresses to probe. Use only if the tuner
465 addresses are unknown. */
466 const unsigned short *v4l2_i2c_tuner_addrs(enum v4l2_i2c_tuner_type type)
468 static const unsigned short radio_addrs[] = {
469 #if defined(CONFIG_MEDIA_TUNER_TEA5761) || defined(CONFIG_MEDIA_TUNER_TEA5761_MODULE)
475 static const unsigned short demod_addrs[] = {
476 0x42, 0x43, 0x4a, 0x4b,
479 static const unsigned short tv_addrs[] = {
480 0x42, 0x43, 0x4a, 0x4b, /* tda8290 */
481 0x60, 0x61, 0x62, 0x63, 0x64,
492 case ADDRS_TV_WITH_DEMOD:
497 EXPORT_SYMBOL_GPL(v4l2_i2c_tuner_addrs);
499 #endif /* defined(CONFIG_I2C) */
501 #if defined(CONFIG_SPI)
503 /* Load a spi sub-device. */
505 void v4l2_spi_subdev_init(struct v4l2_subdev *sd, struct spi_device *spi,
506 const struct v4l2_subdev_ops *ops)
508 v4l2_subdev_init(sd, ops);
509 sd->flags |= V4L2_SUBDEV_FL_IS_SPI;
510 /* the owner is the same as the spi_device's driver owner */
511 sd->owner = spi->dev.driver->owner;
512 /* spi_device and v4l2_subdev point to one another */
513 v4l2_set_subdevdata(sd, spi);
514 spi_set_drvdata(spi, sd);
515 /* initialize name */
516 strlcpy(sd->name, spi->dev.driver->name, sizeof(sd->name));
518 EXPORT_SYMBOL_GPL(v4l2_spi_subdev_init);
520 struct v4l2_subdev *v4l2_spi_new_subdev(struct v4l2_device *v4l2_dev,
521 struct spi_master *master, struct spi_board_info *info)
523 struct v4l2_subdev *sd = NULL;
524 struct spi_device *spi = NULL;
529 request_module(info->modalias);
531 spi = spi_new_device(master, info);
533 if (spi == NULL || spi->dev.driver == NULL)
536 if (!try_module_get(spi->dev.driver->owner))
539 sd = spi_get_drvdata(spi);
541 /* Register with the v4l2_device which increases the module's
542 use count as well. */
543 if (v4l2_device_register_subdev(v4l2_dev, sd))
546 /* Decrease the module use count to match the first try_module_get. */
547 module_put(spi->dev.driver->owner);
550 /* If we have a client but no subdev, then something went wrong and
551 we must unregister the client. */
552 if (spi && sd == NULL)
553 spi_unregister_device(spi);
557 EXPORT_SYMBOL_GPL(v4l2_spi_new_subdev);
559 #endif /* defined(CONFIG_SPI) */
561 /* Clamp x to be between min and max, aligned to a multiple of 2^align. min
562 * and max don't have to be aligned, but there must be at least one valid
563 * value. E.g., min=17,max=31,align=4 is not allowed as there are no multiples
564 * of 16 between 17 and 31. */
565 static unsigned int clamp_align(unsigned int x, unsigned int min,
566 unsigned int max, unsigned int align)
568 /* Bits that must be zero to be aligned */
569 unsigned int mask = ~((1 << align) - 1);
571 /* Round to nearest aligned value */
573 x = (x + (1 << (align - 1))) & mask;
575 /* Clamp to aligned value of min and max */
577 x = (min + ~mask) & mask;
584 /* Bound an image to have a width between wmin and wmax, and height between
585 * hmin and hmax, inclusive. Additionally, the width will be a multiple of
586 * 2^walign, the height will be a multiple of 2^halign, and the overall size
587 * (width*height) will be a multiple of 2^salign. The image may be shrunk
588 * or enlarged to fit the alignment constraints.
590 * The width or height maximum must not be smaller than the corresponding
591 * minimum. The alignments must not be so high there are no possible image
592 * sizes within the allowed bounds. wmin and hmin must be at least 1
593 * (don't use 0). If you don't care about a certain alignment, specify 0,
594 * as 2^0 is 1 and one byte alignment is equivalent to no alignment. If
595 * you only want to adjust downward, specify a maximum that's the same as
598 void v4l_bound_align_image(u32 *w, unsigned int wmin, unsigned int wmax,
600 u32 *h, unsigned int hmin, unsigned int hmax,
601 unsigned int halign, unsigned int salign)
603 *w = clamp_align(*w, wmin, wmax, walign);
604 *h = clamp_align(*h, hmin, hmax, halign);
606 /* Usually we don't need to align the size and are done now. */
610 /* How much alignment do we have? */
613 /* Enough to satisfy the image alignment? */
614 if (walign + halign < salign) {
615 /* Max walign where there is still a valid width */
616 unsigned int wmaxa = __fls(wmax ^ (wmin - 1));
617 /* Max halign where there is still a valid height */
618 unsigned int hmaxa = __fls(hmax ^ (hmin - 1));
620 /* up the smaller alignment until we have enough */
622 if (halign >= hmaxa ||
623 (walign <= halign && walign < wmaxa)) {
624 *w = clamp_align(*w, wmin, wmax, walign + 1);
627 *h = clamp_align(*h, hmin, hmax, halign + 1);
630 } while (halign + walign < salign);
633 EXPORT_SYMBOL_GPL(v4l_bound_align_image);
636 * v4l_fill_dv_preset_info - fill description of a digital video preset
637 * @preset - preset value
638 * @info - pointer to struct v4l2_dv_enum_preset
640 * drivers can use this helper function to fill description of dv preset
643 int v4l_fill_dv_preset_info(u32 preset, struct v4l2_dv_enum_preset *info)
645 static const struct v4l2_dv_preset_info {
650 { 0, 0, "Invalid" }, /* V4L2_DV_INVALID */
651 { 720, 480, "480p@59.94" }, /* V4L2_DV_480P59_94 */
652 { 720, 576, "576p@50" }, /* V4L2_DV_576P50 */
653 { 1280, 720, "720p@24" }, /* V4L2_DV_720P24 */
654 { 1280, 720, "720p@25" }, /* V4L2_DV_720P25 */
655 { 1280, 720, "720p@30" }, /* V4L2_DV_720P30 */
656 { 1280, 720, "720p@50" }, /* V4L2_DV_720P50 */
657 { 1280, 720, "720p@59.94" }, /* V4L2_DV_720P59_94 */
658 { 1280, 720, "720p@60" }, /* V4L2_DV_720P60 */
659 { 1920, 1080, "1080i@29.97" }, /* V4L2_DV_1080I29_97 */
660 { 1920, 1080, "1080i@30" }, /* V4L2_DV_1080I30 */
661 { 1920, 1080, "1080i@25" }, /* V4L2_DV_1080I25 */
662 { 1920, 1080, "1080i@50" }, /* V4L2_DV_1080I50 */
663 { 1920, 1080, "1080i@60" }, /* V4L2_DV_1080I60 */
664 { 1920, 1080, "1080p@24" }, /* V4L2_DV_1080P24 */
665 { 1920, 1080, "1080p@25" }, /* V4L2_DV_1080P25 */
666 { 1920, 1080, "1080p@30" }, /* V4L2_DV_1080P30 */
667 { 1920, 1080, "1080p@50" }, /* V4L2_DV_1080P50 */
668 { 1920, 1080, "1080p@60" }, /* V4L2_DV_1080P60 */
671 if (info == NULL || preset >= ARRAY_SIZE(dv_presets))
674 info->preset = preset;
675 info->width = dv_presets[preset].width;
676 info->height = dv_presets[preset].height;
677 strlcpy(info->name, dv_presets[preset].name, sizeof(info->name));
680 EXPORT_SYMBOL_GPL(v4l_fill_dv_preset_info);
682 const struct v4l2_frmsize_discrete *v4l2_find_nearest_format(
683 const struct v4l2_discrete_probe *probe,
684 s32 width, s32 height)
687 u32 error, min_error = UINT_MAX;
688 const struct v4l2_frmsize_discrete *size, *best = NULL;
693 for (i = 0, size = probe->sizes; i < probe->num_sizes; i++, size++) {
694 error = abs(size->width - width) + abs(size->height - height);
695 if (error < min_error) {
705 EXPORT_SYMBOL_GPL(v4l2_find_nearest_format);