1 /* SPDX-License-Identifier: GPL-2.0-or-later */ 2 /* 3 v4l2 common internal API header 4 5 This header contains internal shared ioctl definitions for use by the 6 internal low-level v4l2 drivers. 7 Each ioctl begins with VIDIOC_INT_ to clearly mark that it is an internal 8 define, 9 10 Copyright (C) 2005 Hans Verkuil <hverkuil@xs4all.nl> 11 12 */ 13 14 #ifndef V4L2_COMMON_H_ 15 #define V4L2_COMMON_H_ 16 17 #include <media/v4l2-dev.h> 18 19 /* Common printk constructs for v4l-i2c drivers. These macros create a unique 20 prefix consisting of the driver name, the adapter number and the i2c 21 address. */ 22 #define v4l_printk(level, name, adapter, addr, fmt, arg...) \ 23 printk(level "%s %d-%04x: " fmt, name, i2c_adapter_id(adapter), addr , ## arg) 24 25 #define v4l_client_printk(level, client, fmt, arg...) \ 26 v4l_printk(level, (client)->dev.driver->name, (client)->adapter, \ 27 (client)->addr, fmt , ## arg) 28 29 #define v4l_err(client, fmt, arg...) \ 30 v4l_client_printk(KERN_ERR, client, fmt , ## arg) 31 32 #define v4l_warn(client, fmt, arg...) \ 33 v4l_client_printk(KERN_WARNING, client, fmt , ## arg) 34 35 #define v4l_info(client, fmt, arg...) \ 36 v4l_client_printk(KERN_INFO, client, fmt , ## arg) 37 38 /* These three macros assume that the debug level is set with a module 39 parameter called 'debug'. */ 40 #define v4l_dbg(level, debug, client, fmt, arg...) \ 41 do { \ 42 if (debug >= (level)) \ 43 v4l_client_printk(KERN_DEBUG, client, fmt , ## arg); \ 44 } while (0) 45 46 /* Add a version of v4l_dbg to be used on drivers using dev_foo() macros */ 47 #define dev_dbg_lvl(__dev, __level, __debug, __fmt, __arg...) \ 48 do { \ 49 if (__debug >= (__level)) \ 50 dev_printk(KERN_DEBUG, __dev, __fmt, ##__arg); \ 51 } while (0) 52 53 /* ------------------------------------------------------------------------- */ 54 55 /* These printk constructs can be used with v4l2_device and v4l2_subdev */ 56 #define v4l2_printk(level, dev, fmt, arg...) \ 57 printk(level "%s: " fmt, (dev)->name , ## arg) 58 59 #define v4l2_err(dev, fmt, arg...) \ 60 v4l2_printk(KERN_ERR, dev, fmt , ## arg) 61 62 #define v4l2_warn(dev, fmt, arg...) \ 63 v4l2_printk(KERN_WARNING, dev, fmt , ## arg) 64 65 #define v4l2_info(dev, fmt, arg...) \ 66 v4l2_printk(KERN_INFO, dev, fmt , ## arg) 67 68 /* These three macros assume that the debug level is set with a module 69 parameter called 'debug'. */ 70 #define v4l2_dbg(level, debug, dev, fmt, arg...) \ 71 do { \ 72 if (debug >= (level)) \ 73 v4l2_printk(KERN_DEBUG, dev, fmt , ## arg); \ 74 } while (0) 75 76 /** 77 * v4l2_ctrl_query_fill- Fill in a struct v4l2_queryctrl 78 * 79 * @qctrl: pointer to the &struct v4l2_queryctrl to be filled 80 * @min: minimum value for the control 81 * @max: maximum value for the control 82 * @step: control step 83 * @def: default value for the control 84 * 85 * Fills the &struct v4l2_queryctrl fields for the query control. 86 * 87 * .. note:: 88 * 89 * This function assumes that the @qctrl->id field is filled. 90 * 91 * Returns -EINVAL if the control is not known by the V4L2 core, 0 on success. 92 */ 93 94 int v4l2_ctrl_query_fill(struct v4l2_queryctrl *qctrl, 95 s32 min, s32 max, s32 step, s32 def); 96 97 /* ------------------------------------------------------------------------- */ 98 99 struct v4l2_device; 100 struct v4l2_subdev; 101 struct v4l2_subdev_ops; 102 103 /* I2C Helper functions */ 104 #include <linux/i2c.h> 105 106 /** 107 * enum v4l2_i2c_tuner_type - specifies the range of tuner address that 108 * should be used when seeking for I2C devices. 109 * 110 * @ADDRS_RADIO: Radio tuner addresses. 111 * Represent the following I2C addresses: 112 * 0x10 (if compiled with tea5761 support) 113 * and 0x60. 114 * @ADDRS_DEMOD: Demod tuner addresses. 115 * Represent the following I2C addresses: 116 * 0x42, 0x43, 0x4a and 0x4b. 117 * @ADDRS_TV: TV tuner addresses. 118 * Represent the following I2C addresses: 119 * 0x42, 0x43, 0x4a, 0x4b, 0x60, 0x61, 0x62, 120 * 0x63 and 0x64. 121 * @ADDRS_TV_WITH_DEMOD: TV tuner addresses if demod is present, this 122 * excludes addresses used by the demodulator 123 * from the list of candidates. 124 * Represent the following I2C addresses: 125 * 0x60, 0x61, 0x62, 0x63 and 0x64. 126 * 127 * NOTE: All I2C addresses above use the 7-bit notation. 128 */ 129 enum v4l2_i2c_tuner_type { 130 ADDRS_RADIO, 131 ADDRS_DEMOD, 132 ADDRS_TV, 133 ADDRS_TV_WITH_DEMOD, 134 }; 135 136 #if defined(CONFIG_VIDEO_V4L2_I2C) 137 138 /** 139 * v4l2_i2c_new_subdev - Load an i2c module and return an initialized 140 * &struct v4l2_subdev. 141 * 142 * @v4l2_dev: pointer to &struct v4l2_device 143 * @adapter: pointer to struct i2c_adapter 144 * @client_type: name of the chip that's on the adapter. 145 * @addr: I2C address. If zero, it will use @probe_addrs 146 * @probe_addrs: array with a list of address. The last entry at such 147 * array should be %I2C_CLIENT_END. 148 * 149 * returns a &struct v4l2_subdev pointer. 150 */ 151 struct v4l2_subdev *v4l2_i2c_new_subdev(struct v4l2_device *v4l2_dev, 152 struct i2c_adapter *adapter, const char *client_type, 153 u8 addr, const unsigned short *probe_addrs); 154 155 /** 156 * v4l2_i2c_new_subdev_board - Load an i2c module and return an initialized 157 * &struct v4l2_subdev. 158 * 159 * @v4l2_dev: pointer to &struct v4l2_device 160 * @adapter: pointer to struct i2c_adapter 161 * @info: pointer to struct i2c_board_info used to replace the irq, 162 * platform_data and addr arguments. 163 * @probe_addrs: array with a list of address. The last entry at such 164 * array should be %I2C_CLIENT_END. 165 * 166 * returns a &struct v4l2_subdev pointer. 167 */ 168 struct v4l2_subdev *v4l2_i2c_new_subdev_board(struct v4l2_device *v4l2_dev, 169 struct i2c_adapter *adapter, struct i2c_board_info *info, 170 const unsigned short *probe_addrs); 171 172 /** 173 * v4l2_i2c_subdev_set_name - Set name for an I²C sub-device 174 * 175 * @sd: pointer to &struct v4l2_subdev 176 * @client: pointer to struct i2c_client 177 * @devname: the name of the device; if NULL, the I²C device's name will be used 178 * @postfix: sub-device specific string to put right after the I²C device name; 179 * may be NULL 180 */ 181 void v4l2_i2c_subdev_set_name(struct v4l2_subdev *sd, struct i2c_client *client, 182 const char *devname, const char *postfix); 183 184 /** 185 * v4l2_i2c_subdev_init - Initializes a &struct v4l2_subdev with data from 186 * an i2c_client struct. 187 * 188 * @sd: pointer to &struct v4l2_subdev 189 * @client: pointer to struct i2c_client 190 * @ops: pointer to &struct v4l2_subdev_ops 191 */ 192 void v4l2_i2c_subdev_init(struct v4l2_subdev *sd, struct i2c_client *client, 193 const struct v4l2_subdev_ops *ops); 194 195 /** 196 * v4l2_i2c_subdev_addr - returns i2c client address of &struct v4l2_subdev. 197 * 198 * @sd: pointer to &struct v4l2_subdev 199 * 200 * Returns the address of an I2C sub-device 201 */ 202 unsigned short v4l2_i2c_subdev_addr(struct v4l2_subdev *sd); 203 204 /** 205 * v4l2_i2c_tuner_addrs - Return a list of I2C tuner addresses to probe. 206 * 207 * @type: type of the tuner to seek, as defined by 208 * &enum v4l2_i2c_tuner_type. 209 * 210 * NOTE: Use only if the tuner addresses are unknown. 211 */ 212 const unsigned short *v4l2_i2c_tuner_addrs(enum v4l2_i2c_tuner_type type); 213 214 /** 215 * v4l2_i2c_subdev_unregister - Unregister a v4l2_subdev 216 * 217 * @sd: pointer to &struct v4l2_subdev 218 */ 219 void v4l2_i2c_subdev_unregister(struct v4l2_subdev *sd); 220 221 #else 222 223 static inline struct v4l2_subdev * 224 v4l2_i2c_new_subdev(struct v4l2_device *v4l2_dev, 225 struct i2c_adapter *adapter, const char *client_type, 226 u8 addr, const unsigned short *probe_addrs) 227 { 228 return NULL; 229 } 230 231 static inline struct v4l2_subdev * 232 v4l2_i2c_new_subdev_board(struct v4l2_device *v4l2_dev, 233 struct i2c_adapter *adapter, struct i2c_board_info *info, 234 const unsigned short *probe_addrs) 235 { 236 return NULL; 237 } 238 239 static inline void 240 v4l2_i2c_subdev_set_name(struct v4l2_subdev *sd, struct i2c_client *client, 241 const char *devname, const char *postfix) 242 {} 243 244 static inline void 245 v4l2_i2c_subdev_init(struct v4l2_subdev *sd, struct i2c_client *client, 246 const struct v4l2_subdev_ops *ops) 247 {} 248 249 static inline unsigned short v4l2_i2c_subdev_addr(struct v4l2_subdev *sd) 250 { 251 return I2C_CLIENT_END; 252 } 253 254 static inline const unsigned short * 255 v4l2_i2c_tuner_addrs(enum v4l2_i2c_tuner_type type) 256 { 257 return NULL; 258 } 259 260 static inline void v4l2_i2c_subdev_unregister(struct v4l2_subdev *sd) 261 {} 262 263 #endif 264 265 /* ------------------------------------------------------------------------- */ 266 267 /* SPI Helper functions */ 268 269 #include <linux/spi/spi.h> 270 271 #if defined(CONFIG_SPI) 272 273 /** 274 * v4l2_spi_new_subdev - Load an spi module and return an initialized 275 * &struct v4l2_subdev. 276 * 277 * 278 * @v4l2_dev: pointer to &struct v4l2_device. 279 * @master: pointer to struct spi_master. 280 * @info: pointer to struct spi_board_info. 281 * 282 * returns a &struct v4l2_subdev pointer. 283 */ 284 struct v4l2_subdev *v4l2_spi_new_subdev(struct v4l2_device *v4l2_dev, 285 struct spi_master *master, struct spi_board_info *info); 286 287 /** 288 * v4l2_spi_subdev_init - Initialize a v4l2_subdev with data from an 289 * spi_device struct. 290 * 291 * @sd: pointer to &struct v4l2_subdev 292 * @spi: pointer to struct spi_device. 293 * @ops: pointer to &struct v4l2_subdev_ops 294 */ 295 void v4l2_spi_subdev_init(struct v4l2_subdev *sd, struct spi_device *spi, 296 const struct v4l2_subdev_ops *ops); 297 298 /** 299 * v4l2_spi_subdev_unregister - Unregister a v4l2_subdev 300 * 301 * @sd: pointer to &struct v4l2_subdev 302 */ 303 void v4l2_spi_subdev_unregister(struct v4l2_subdev *sd); 304 305 #else 306 307 static inline struct v4l2_subdev * 308 v4l2_spi_new_subdev(struct v4l2_device *v4l2_dev, 309 struct spi_master *master, struct spi_board_info *info) 310 { 311 return NULL; 312 } 313 314 static inline void 315 v4l2_spi_subdev_init(struct v4l2_subdev *sd, struct spi_device *spi, 316 const struct v4l2_subdev_ops *ops) 317 {} 318 319 static inline void v4l2_spi_subdev_unregister(struct v4l2_subdev *sd) 320 {} 321 #endif 322 323 /* ------------------------------------------------------------------------- */ 324 325 /* 326 * FIXME: these remaining ioctls/structs should be removed as well, but they 327 * are still used in tuner-simple.c (TUNER_SET_CONFIG) and cx18/ivtv (RESET). 328 * To remove these ioctls some more cleanup is needed in those modules. 329 * 330 * It doesn't make much sense on documenting them, as what we really want is 331 * to get rid of them. 332 */ 333 334 /* s_config */ 335 struct v4l2_priv_tun_config { 336 int tuner; 337 void *priv; 338 }; 339 #define TUNER_SET_CONFIG _IOW('d', 92, struct v4l2_priv_tun_config) 340 341 #define VIDIOC_INT_RESET _IOW ('d', 102, u32) 342 343 /* ------------------------------------------------------------------------- */ 344 345 /* Miscellaneous helper functions */ 346 347 /** 348 * v4l_bound_align_image - adjust video dimensions according to 349 * a given constraints. 350 * 351 * @width: pointer to width that will be adjusted if needed. 352 * @wmin: minimum width. 353 * @wmax: maximum width. 354 * @walign: least significant bit on width. 355 * @height: pointer to height that will be adjusted if needed. 356 * @hmin: minimum height. 357 * @hmax: maximum height. 358 * @halign: least significant bit on height. 359 * @salign: least significant bit for the image size (e. g. 360 * :math:`width * height`). 361 * 362 * Clip an image to have @width between @wmin and @wmax, and @height between 363 * @hmin and @hmax, inclusive. 364 * 365 * Additionally, the @width will be a multiple of :math:`2^{walign}`, 366 * the @height will be a multiple of :math:`2^{halign}`, and the overall 367 * size :math:`width * height` will be a multiple of :math:`2^{salign}`. 368 * 369 * .. note:: 370 * 371 * #. The clipping rectangle may be shrunk or enlarged to fit the alignment 372 * constraints. 373 * #. @wmax must not be smaller than @wmin. 374 * #. @hmax must not be smaller than @hmin. 375 * #. The alignments must not be so high there are no possible image 376 * sizes within the allowed bounds. 377 * #. @wmin and @hmin must be at least 1 (don't use 0). 378 * #. For @walign, @halign and @salign, if you don't care about a certain 379 * alignment, specify ``0``, as :math:`2^0 = 1` and one byte alignment 380 * is equivalent to no alignment. 381 * #. If you only want to adjust downward, specify a maximum that's the 382 * same as the initial value. 383 */ 384 void v4l_bound_align_image(unsigned int *width, unsigned int wmin, 385 unsigned int wmax, unsigned int walign, 386 unsigned int *height, unsigned int hmin, 387 unsigned int hmax, unsigned int halign, 388 unsigned int salign); 389 390 /** 391 * v4l2_find_nearest_size - Find the nearest size among a discrete 392 * set of resolutions contained in an array of a driver specific struct. 393 * 394 * @array: a driver specific array of image sizes 395 * @array_size: the length of the driver specific array of image sizes 396 * @width_field: the name of the width field in the driver specific struct 397 * @height_field: the name of the height field in the driver specific struct 398 * @width: desired width. 399 * @height: desired height. 400 * 401 * Finds the closest resolution to minimize the width and height differences 402 * between what requested and the supported resolutions. The size of the width 403 * and height fields in the driver specific must equal to that of u32, i.e. four 404 * bytes. 405 * 406 * Returns the best match or NULL if the length of the array is zero. 407 */ 408 #define v4l2_find_nearest_size(array, array_size, width_field, height_field, \ 409 width, height) \ 410 ({ \ 411 BUILD_BUG_ON(sizeof((array)->width_field) != sizeof(u32) || \ 412 sizeof((array)->height_field) != sizeof(u32)); \ 413 (typeof(&(array)[0]))__v4l2_find_nearest_size( \ 414 (array), array_size, sizeof(*(array)), \ 415 offsetof(typeof(*(array)), width_field), \ 416 offsetof(typeof(*(array)), height_field), \ 417 width, height); \ 418 }) 419 const void * 420 __v4l2_find_nearest_size(const void *array, size_t array_size, 421 size_t entry_size, size_t width_offset, 422 size_t height_offset, s32 width, s32 height); 423 424 /** 425 * v4l2_g_parm_cap - helper routine for vidioc_g_parm to fill this in by 426 * calling the g_frame_interval op of the given subdev. It only works 427 * for V4L2_BUF_TYPE_VIDEO_CAPTURE(_MPLANE), hence the _cap in the 428 * function name. 429 * 430 * @vdev: the struct video_device pointer. Used to determine the device caps. 431 * @sd: the sub-device pointer. 432 * @a: the VIDIOC_G_PARM argument. 433 */ 434 int v4l2_g_parm_cap(struct video_device *vdev, 435 struct v4l2_subdev *sd, struct v4l2_streamparm *a); 436 437 /** 438 * v4l2_s_parm_cap - helper routine for vidioc_s_parm to fill this in by 439 * calling the s_frame_interval op of the given subdev. It only works 440 * for V4L2_BUF_TYPE_VIDEO_CAPTURE(_MPLANE), hence the _cap in the 441 * function name. 442 * 443 * @vdev: the struct video_device pointer. Used to determine the device caps. 444 * @sd: the sub-device pointer. 445 * @a: the VIDIOC_S_PARM argument. 446 */ 447 int v4l2_s_parm_cap(struct video_device *vdev, 448 struct v4l2_subdev *sd, struct v4l2_streamparm *a); 449 450 /* Compare two v4l2_fract structs */ 451 #define V4L2_FRACT_COMPARE(a, OP, b) \ 452 ((u64)(a).numerator * (b).denominator OP \ 453 (u64)(b).numerator * (a).denominator) 454 455 /* ------------------------------------------------------------------------- */ 456 457 /* Pixel format and FourCC helpers */ 458 459 /** 460 * enum v4l2_pixel_encoding - specifies the pixel encoding value 461 * 462 * @V4L2_PIXEL_ENC_UNKNOWN: Pixel encoding is unknown/un-initialized 463 * @V4L2_PIXEL_ENC_YUV: Pixel encoding is YUV 464 * @V4L2_PIXEL_ENC_RGB: Pixel encoding is RGB 465 * @V4L2_PIXEL_ENC_BAYER: Pixel encoding is Bayer 466 */ 467 enum v4l2_pixel_encoding { 468 V4L2_PIXEL_ENC_UNKNOWN = 0, 469 V4L2_PIXEL_ENC_YUV = 1, 470 V4L2_PIXEL_ENC_RGB = 2, 471 V4L2_PIXEL_ENC_BAYER = 3, 472 }; 473 474 /** 475 * struct v4l2_format_info - information about a V4L2 format 476 * @format: 4CC format identifier (V4L2_PIX_FMT_*) 477 * @pixel_enc: Pixel encoding (see enum v4l2_pixel_encoding above) 478 * @mem_planes: Number of memory planes, which includes the alpha plane (1 to 4). 479 * @comp_planes: Number of component planes, which includes the alpha plane (1 to 4). 480 * @bpp: Array of per-plane bytes per pixel 481 * @hdiv: Horizontal chroma subsampling factor 482 * @vdiv: Vertical chroma subsampling factor 483 * @block_w: Per-plane macroblock pixel width (optional) 484 * @block_h: Per-plane macroblock pixel height (optional) 485 */ 486 struct v4l2_format_info { 487 u32 format; 488 u8 pixel_enc; 489 u8 mem_planes; 490 u8 comp_planes; 491 u8 bpp[4]; 492 u8 hdiv; 493 u8 vdiv; 494 u8 block_w[4]; 495 u8 block_h[4]; 496 }; 497 498 static inline bool v4l2_is_format_rgb(const struct v4l2_format_info *f) 499 { 500 return f && f->pixel_enc == V4L2_PIXEL_ENC_RGB; 501 } 502 503 static inline bool v4l2_is_format_yuv(const struct v4l2_format_info *f) 504 { 505 return f && f->pixel_enc == V4L2_PIXEL_ENC_YUV; 506 } 507 508 static inline bool v4l2_is_format_bayer(const struct v4l2_format_info *f) 509 { 510 return f && f->pixel_enc == V4L2_PIXEL_ENC_BAYER; 511 } 512 513 const struct v4l2_format_info *v4l2_format_info(u32 format); 514 void v4l2_apply_frmsize_constraints(u32 *width, u32 *height, 515 const struct v4l2_frmsize_stepwise *frmsize); 516 int v4l2_fill_pixfmt(struct v4l2_pix_format *pixfmt, u32 pixelformat, 517 u32 width, u32 height); 518 int v4l2_fill_pixfmt_mp(struct v4l2_pix_format_mplane *pixfmt, u32 pixelformat, 519 u32 width, u32 height); 520 521 #endif /* V4L2_COMMON_H_ */ 522