include/media/v4l2-common.h

   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  * struct v4l2_format_info - information about a V4L2 format
 461  * @format: 4CC format identifier (V4L2_PIX_FMT_*)
 462  * @mem_planes: Number of memory planes, which includes the alpha plane (1 to 4).
 463  * @comp_planes: Number of component planes, which includes the alpha plane (1 to 4).
 464  * @bpp: Array of per-plane bytes per pixel
 465  * @hdiv: Horizontal chroma subsampling factor
 466  * @vdiv: Vertical chroma subsampling factor
 467  * @block_w: Per-plane macroblock pixel width (optional)
 468  * @block_h: Per-plane macroblock pixel height (optional)
 469  */
 470 struct v4l2_format_info {
 471         u32 format;
 472         u8 mem_planes;
 473         u8 comp_planes;
 474         u8 bpp[4];
 475         u8 hdiv;
 476         u8 vdiv;
 477         u8 block_w[4];
 478         u8 block_h[4];
 479 };
 480
 481 const struct v4l2_format_info *v4l2_format_info(u32 format);
 482
 483 void v4l2_apply_frmsize_constraints(u32 *width, u32 *height,
 484                                     const struct v4l2_frmsize_stepwise *frmsize);
 485 int v4l2_fill_pixfmt(struct v4l2_pix_format *pixfmt, u32 pixelformat,
 486                      u32 width, u32 height);
 487 int v4l2_fill_pixfmt_mp(struct v4l2_pix_format_mplane *pixfmt, u32 pixelformat,
 488                         u32 width, u32 height);
 489
 490 #endif /* V4L2_COMMON_H_ */