v4l2-common.c revision 2576415846bcbad3c0a6885fc44f950837106364
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 67MODULE_AUTHOR("Bill Dirks, Justin Schoeman, Gerd Knorr"); 68MODULE_DESCRIPTION("misc helper functions for v4l2 device drivers"); 69MODULE_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. */ 86int 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} 111EXPORT_SYMBOL(v4l2_ctrl_check); 112 113/* Fill in a struct v4l2_queryctrl */ 114int v4l2_ctrl_query_fill(struct v4l2_queryctrl *qctrl, s32 min, s32 max, s32 step, s32 def) 115{ 116 const char *name; 117 118 v4l2_ctrl_fill(qctrl->id, &name, &qctrl->type, 119 &min, &max, &step, &def, &qctrl->flags); 120 121 if (name == NULL) 122 return -EINVAL; 123 124 qctrl->minimum = min; 125 qctrl->maximum = max; 126 qctrl->step = step; 127 qctrl->default_value = def; 128 qctrl->reserved[0] = qctrl->reserved[1] = 0; 129 strlcpy(qctrl->name, name, sizeof(qctrl->name)); 130 return 0; 131} 132EXPORT_SYMBOL(v4l2_ctrl_query_fill); 133 134/* Fill in a struct v4l2_querymenu based on the struct v4l2_queryctrl and 135 the menu. The qctrl pointer may be NULL, in which case it is ignored. 136 If menu_items is NULL, then the menu items are retrieved using 137 v4l2_ctrl_get_menu. */ 138int v4l2_ctrl_query_menu(struct v4l2_querymenu *qmenu, struct v4l2_queryctrl *qctrl, 139 const char * const *menu_items) 140{ 141 int i; 142 143 qmenu->reserved = 0; 144 if (menu_items == NULL) 145 menu_items = v4l2_ctrl_get_menu(qmenu->id); 146 if (menu_items == NULL || 147 (qctrl && (qmenu->index < qctrl->minimum || qmenu->index > qctrl->maximum))) 148 return -EINVAL; 149 for (i = 0; i < qmenu->index && menu_items[i]; i++) ; 150 if (menu_items[i] == NULL || menu_items[i][0] == '\0') 151 return -EINVAL; 152 strlcpy(qmenu->name, menu_items[qmenu->index], sizeof(qmenu->name)); 153 return 0; 154} 155EXPORT_SYMBOL(v4l2_ctrl_query_menu); 156 157/* Fill in a struct v4l2_querymenu based on the specified array of valid 158 menu items (terminated by V4L2_CTRL_MENU_IDS_END). 159 Use this if there are 'holes' in the list of valid menu items. */ 160int v4l2_ctrl_query_menu_valid_items(struct v4l2_querymenu *qmenu, const u32 *ids) 161{ 162 const char * const *menu_items = v4l2_ctrl_get_menu(qmenu->id); 163 164 qmenu->reserved = 0; 165 if (menu_items == NULL || ids == NULL) 166 return -EINVAL; 167 while (*ids != V4L2_CTRL_MENU_IDS_END) { 168 if (*ids++ == qmenu->index) { 169 strlcpy(qmenu->name, menu_items[qmenu->index], 170 sizeof(qmenu->name)); 171 return 0; 172 } 173 } 174 return -EINVAL; 175} 176EXPORT_SYMBOL(v4l2_ctrl_query_menu_valid_items); 177 178/* ctrl_classes points to an array of u32 pointers, the last element is 179 a NULL pointer. Each u32 array is a 0-terminated array of control IDs. 180 Each array must be sorted low to high and belong to the same control 181 class. The array of u32 pointers must also be sorted, from low class IDs 182 to high class IDs. 183 184 This function returns the first ID that follows after the given ID. 185 When no more controls are available 0 is returned. */ 186u32 v4l2_ctrl_next(const u32 * const * ctrl_classes, u32 id) 187{ 188 u32 ctrl_class = V4L2_CTRL_ID2CLASS(id); 189 const u32 *pctrl; 190 191 if (ctrl_classes == NULL) 192 return 0; 193 194 /* if no query is desired, then check if the ID is part of ctrl_classes */ 195 if ((id & V4L2_CTRL_FLAG_NEXT_CTRL) == 0) { 196 /* find class */ 197 while (*ctrl_classes && V4L2_CTRL_ID2CLASS(**ctrl_classes) != ctrl_class) 198 ctrl_classes++; 199 if (*ctrl_classes == NULL) 200 return 0; 201 pctrl = *ctrl_classes; 202 /* find control ID */ 203 while (*pctrl && *pctrl != id) pctrl++; 204 return *pctrl ? id : 0; 205 } 206 id &= V4L2_CTRL_ID_MASK; 207 id++; /* select next control */ 208 /* find first class that matches (or is greater than) the class of 209 the ID */ 210 while (*ctrl_classes && V4L2_CTRL_ID2CLASS(**ctrl_classes) < ctrl_class) 211 ctrl_classes++; 212 /* no more classes */ 213 if (*ctrl_classes == NULL) 214 return 0; 215 pctrl = *ctrl_classes; 216 /* find first ctrl within the class that is >= ID */ 217 while (*pctrl && *pctrl < id) pctrl++; 218 if (*pctrl) 219 return *pctrl; 220 /* we are at the end of the controls of the current class. */ 221 /* continue with next class if available */ 222 ctrl_classes++; 223 if (*ctrl_classes == NULL) 224 return 0; 225 return **ctrl_classes; 226} 227EXPORT_SYMBOL(v4l2_ctrl_next); 228 229/* I2C Helper functions */ 230 231#if IS_ENABLED(CONFIG_I2C) 232 233void v4l2_i2c_subdev_init(struct v4l2_subdev *sd, struct i2c_client *client, 234 const struct v4l2_subdev_ops *ops) 235{ 236 v4l2_subdev_init(sd, ops); 237 sd->flags |= V4L2_SUBDEV_FL_IS_I2C; 238 /* the owner is the same as the i2c_client's driver owner */ 239 sd->owner = client->driver->driver.owner; 240 sd->dev = &client->dev; 241 /* i2c_client and v4l2_subdev point to one another */ 242 v4l2_set_subdevdata(sd, client); 243 i2c_set_clientdata(client, sd); 244 /* initialize name */ 245 snprintf(sd->name, sizeof(sd->name), "%s %d-%04x", 246 client->driver->driver.name, i2c_adapter_id(client->adapter), 247 client->addr); 248} 249EXPORT_SYMBOL_GPL(v4l2_i2c_subdev_init); 250 251/* Load an i2c sub-device. */ 252struct v4l2_subdev *v4l2_i2c_new_subdev_board(struct v4l2_device *v4l2_dev, 253 struct i2c_adapter *adapter, struct i2c_board_info *info, 254 const unsigned short *probe_addrs) 255{ 256 struct v4l2_subdev *sd = NULL; 257 struct i2c_client *client; 258 259 BUG_ON(!v4l2_dev); 260 261 request_module(I2C_MODULE_PREFIX "%s", info->type); 262 263 /* Create the i2c client */ 264 if (info->addr == 0 && probe_addrs) 265 client = i2c_new_probed_device(adapter, info, probe_addrs, 266 NULL); 267 else 268 client = i2c_new_device(adapter, info); 269 270 /* Note: by loading the module first we are certain that c->driver 271 will be set if the driver was found. If the module was not loaded 272 first, then the i2c core tries to delay-load the module for us, 273 and then c->driver is still NULL until the module is finally 274 loaded. This delay-load mechanism doesn't work if other drivers 275 want to use the i2c device, so explicitly loading the module 276 is the best alternative. */ 277 if (client == NULL || client->driver == NULL) 278 goto error; 279 280 /* Lock the module so we can safely get the v4l2_subdev pointer */ 281 if (!try_module_get(client->driver->driver.owner)) 282 goto error; 283 sd = i2c_get_clientdata(client); 284 285 /* Register with the v4l2_device which increases the module's 286 use count as well. */ 287 if (v4l2_device_register_subdev(v4l2_dev, sd)) 288 sd = NULL; 289 /* Decrease the module use count to match the first try_module_get. */ 290 module_put(client->driver->driver.owner); 291 292error: 293 /* If we have a client but no subdev, then something went wrong and 294 we must unregister the client. */ 295 if (client && sd == NULL) 296 i2c_unregister_device(client); 297 return sd; 298} 299EXPORT_SYMBOL_GPL(v4l2_i2c_new_subdev_board); 300 301struct v4l2_subdev *v4l2_i2c_new_subdev(struct v4l2_device *v4l2_dev, 302 struct i2c_adapter *adapter, const char *client_type, 303 u8 addr, const unsigned short *probe_addrs) 304{ 305 struct i2c_board_info info; 306 307 /* Setup the i2c board info with the device type and 308 the device address. */ 309 memset(&info, 0, sizeof(info)); 310 strlcpy(info.type, client_type, sizeof(info.type)); 311 info.addr = addr; 312 313 return v4l2_i2c_new_subdev_board(v4l2_dev, adapter, &info, probe_addrs); 314} 315EXPORT_SYMBOL_GPL(v4l2_i2c_new_subdev); 316 317/* Return i2c client address of v4l2_subdev. */ 318unsigned short v4l2_i2c_subdev_addr(struct v4l2_subdev *sd) 319{ 320 struct i2c_client *client = v4l2_get_subdevdata(sd); 321 322 return client ? client->addr : I2C_CLIENT_END; 323} 324EXPORT_SYMBOL_GPL(v4l2_i2c_subdev_addr); 325 326/* Return a list of I2C tuner addresses to probe. Use only if the tuner 327 addresses are unknown. */ 328const unsigned short *v4l2_i2c_tuner_addrs(enum v4l2_i2c_tuner_type type) 329{ 330 static const unsigned short radio_addrs[] = { 331#if IS_ENABLED(CONFIG_MEDIA_TUNER_TEA5761) 332 0x10, 333#endif 334 0x60, 335 I2C_CLIENT_END 336 }; 337 static const unsigned short demod_addrs[] = { 338 0x42, 0x43, 0x4a, 0x4b, 339 I2C_CLIENT_END 340 }; 341 static const unsigned short tv_addrs[] = { 342 0x42, 0x43, 0x4a, 0x4b, /* tda8290 */ 343 0x60, 0x61, 0x62, 0x63, 0x64, 344 I2C_CLIENT_END 345 }; 346 347 switch (type) { 348 case ADDRS_RADIO: 349 return radio_addrs; 350 case ADDRS_DEMOD: 351 return demod_addrs; 352 case ADDRS_TV: 353 return tv_addrs; 354 case ADDRS_TV_WITH_DEMOD: 355 return tv_addrs + 4; 356 } 357 return NULL; 358} 359EXPORT_SYMBOL_GPL(v4l2_i2c_tuner_addrs); 360 361#endif /* defined(CONFIG_I2C) */ 362 363#if defined(CONFIG_SPI) 364 365/* Load an spi sub-device. */ 366 367void v4l2_spi_subdev_init(struct v4l2_subdev *sd, struct spi_device *spi, 368 const struct v4l2_subdev_ops *ops) 369{ 370 v4l2_subdev_init(sd, ops); 371 sd->flags |= V4L2_SUBDEV_FL_IS_SPI; 372 /* the owner is the same as the spi_device's driver owner */ 373 sd->owner = spi->dev.driver->owner; 374 sd->dev = &spi->dev; 375 /* spi_device and v4l2_subdev point to one another */ 376 v4l2_set_subdevdata(sd, spi); 377 spi_set_drvdata(spi, sd); 378 /* initialize name */ 379 strlcpy(sd->name, spi->dev.driver->name, sizeof(sd->name)); 380} 381EXPORT_SYMBOL_GPL(v4l2_spi_subdev_init); 382 383struct v4l2_subdev *v4l2_spi_new_subdev(struct v4l2_device *v4l2_dev, 384 struct spi_master *master, struct spi_board_info *info) 385{ 386 struct v4l2_subdev *sd = NULL; 387 struct spi_device *spi = NULL; 388 389 BUG_ON(!v4l2_dev); 390 391 if (info->modalias[0]) 392 request_module(info->modalias); 393 394 spi = spi_new_device(master, info); 395 396 if (spi == NULL || spi->dev.driver == NULL) 397 goto error; 398 399 if (!try_module_get(spi->dev.driver->owner)) 400 goto error; 401 402 sd = spi_get_drvdata(spi); 403 404 /* Register with the v4l2_device which increases the module's 405 use count as well. */ 406 if (v4l2_device_register_subdev(v4l2_dev, sd)) 407 sd = NULL; 408 409 /* Decrease the module use count to match the first try_module_get. */ 410 module_put(spi->dev.driver->owner); 411 412error: 413 /* If we have a client but no subdev, then something went wrong and 414 we must unregister the client. */ 415 if (spi && sd == NULL) 416 spi_unregister_device(spi); 417 418 return sd; 419} 420EXPORT_SYMBOL_GPL(v4l2_spi_new_subdev); 421 422#endif /* defined(CONFIG_SPI) */ 423 424/* Clamp x to be between min and max, aligned to a multiple of 2^align. min 425 * and max don't have to be aligned, but there must be at least one valid 426 * value. E.g., min=17,max=31,align=4 is not allowed as there are no multiples 427 * of 16 between 17 and 31. */ 428static unsigned int clamp_align(unsigned int x, unsigned int min, 429 unsigned int max, unsigned int align) 430{ 431 /* Bits that must be zero to be aligned */ 432 unsigned int mask = ~((1 << align) - 1); 433 434 /* Round to nearest aligned value */ 435 if (align) 436 x = (x + (1 << (align - 1))) & mask; 437 438 /* Clamp to aligned value of min and max */ 439 if (x < min) 440 x = (min + ~mask) & mask; 441 else if (x > max) 442 x = max & mask; 443 444 return x; 445} 446 447/* Bound an image to have a width between wmin and wmax, and height between 448 * hmin and hmax, inclusive. Additionally, the width will be a multiple of 449 * 2^walign, the height will be a multiple of 2^halign, and the overall size 450 * (width*height) will be a multiple of 2^salign. The image may be shrunk 451 * or enlarged to fit the alignment constraints. 452 * 453 * The width or height maximum must not be smaller than the corresponding 454 * minimum. The alignments must not be so high there are no possible image 455 * sizes within the allowed bounds. wmin and hmin must be at least 1 456 * (don't use 0). If you don't care about a certain alignment, specify 0, 457 * as 2^0 is 1 and one byte alignment is equivalent to no alignment. If 458 * you only want to adjust downward, specify a maximum that's the same as 459 * the initial value. 460 */ 461void v4l_bound_align_image(u32 *w, unsigned int wmin, unsigned int wmax, 462 unsigned int walign, 463 u32 *h, unsigned int hmin, unsigned int hmax, 464 unsigned int halign, unsigned int salign) 465{ 466 *w = clamp_align(*w, wmin, wmax, walign); 467 *h = clamp_align(*h, hmin, hmax, halign); 468 469 /* Usually we don't need to align the size and are done now. */ 470 if (!salign) 471 return; 472 473 /* How much alignment do we have? */ 474 walign = __ffs(*w); 475 halign = __ffs(*h); 476 /* Enough to satisfy the image alignment? */ 477 if (walign + halign < salign) { 478 /* Max walign where there is still a valid width */ 479 unsigned int wmaxa = __fls(wmax ^ (wmin - 1)); 480 /* Max halign where there is still a valid height */ 481 unsigned int hmaxa = __fls(hmax ^ (hmin - 1)); 482 483 /* up the smaller alignment until we have enough */ 484 do { 485 if (halign >= hmaxa || 486 (walign <= halign && walign < wmaxa)) { 487 *w = clamp_align(*w, wmin, wmax, walign + 1); 488 walign = __ffs(*w); 489 } else { 490 *h = clamp_align(*h, hmin, hmax, halign + 1); 491 halign = __ffs(*h); 492 } 493 } while (halign + walign < salign); 494 } 495} 496EXPORT_SYMBOL_GPL(v4l_bound_align_image); 497 498const struct v4l2_frmsize_discrete *v4l2_find_nearest_format( 499 const struct v4l2_discrete_probe *probe, 500 s32 width, s32 height) 501{ 502 int i; 503 u32 error, min_error = UINT_MAX; 504 const struct v4l2_frmsize_discrete *size, *best = NULL; 505 506 if (!probe) 507 return best; 508 509 for (i = 0, size = probe->sizes; i < probe->num_sizes; i++, size++) { 510 error = abs(size->width - width) + abs(size->height - height); 511 if (error < min_error) { 512 min_error = error; 513 best = size; 514 } 515 if (!error) 516 break; 517 } 518 519 return best; 520} 521EXPORT_SYMBOL_GPL(v4l2_find_nearest_format); 522 523void v4l2_get_timestamp(struct timeval *tv) 524{ 525 struct timespec ts; 526 527 ktime_get_ts(&ts); 528 tv->tv_sec = ts.tv_sec; 529 tv->tv_usec = ts.tv_nsec / NSEC_PER_USEC; 530} 531EXPORT_SYMBOL_GPL(v4l2_get_timestamp); 532