include/media/v4l2-device.h

   1 /* SPDX-License-Identifier: GPL-2.0-or-later */
   2 /*
   3     V4L2 device support header.
   4
   5     Copyright (C) 2008  Hans Verkuil <hverkuil@xs4all.nl>
   6
   7  */
   8
   9 #ifndef _V4L2_DEVICE_H
  10 #define _V4L2_DEVICE_H
  11
  12 #include <media/media-device.h>
  13 #include <media/v4l2-subdev.h>
  14 #include <media/v4l2-dev.h>
  15
  16 #define V4L2_DEVICE_NAME_SIZE (20 + 16)
  17
  18 struct v4l2_ctrl_handler;
  19
  20 /**
  21  * struct v4l2_device - main struct to for V4L2 device drivers
  22  *
  23  * @dev: pointer to struct device.
  24  * @mdev: pointer to struct media_device, may be NULL.
  25  * @subdevs: used to keep track of the registered subdevs
  26  * @lock: lock this struct; can be used by the driver as well
  27  *      if this struct is embedded into a larger struct.
  28  * @name: unique device name, by default the driver name + bus ID
  29  * @notify: notify operation called by some sub-devices.
  30  * @ctrl_handler: The control handler. May be %NULL.
  31  * @prio: Device's priority state
  32  * @ref: Keep track of the references to this struct.
  33  * @release: Release function that is called when the ref count
  34  *      goes to 0.
  35  *
  36  * Each instance of a V4L2 device should create the v4l2_device struct,
  37  * either stand-alone or embedded in a larger struct.
  38  *
  39  * It allows easy access to sub-devices (see v4l2-subdev.h) and provides
  40  * basic V4L2 device-level support.
  41  *
  42  * .. note::
  43  *
  44  *    #) @dev->driver_data points to this struct.
  45  *    #) @dev might be %NULL if there is no parent device
  46  */
  47 struct v4l2_device {
  48         struct device *dev;
  49         struct media_device *mdev;
  50         struct list_head subdevs;
  51         spinlock_t lock;
  52         char name[V4L2_DEVICE_NAME_SIZE];
  53         void (*notify)(struct v4l2_subdev *sd,
  54                         unsigned int notification, void *arg);
  55         struct v4l2_ctrl_handler *ctrl_handler;
  56         struct v4l2_prio_state prio;
  57         struct kref ref;
  58         void (*release)(struct v4l2_device *v4l2_dev);
  59 };
  60
  61 /**
  62  * v4l2_device_get - gets a V4L2 device reference
  63  *
  64  * @v4l2_dev: pointer to struct &v4l2_device
  65  *
  66  * This is an ancillary routine meant to increment the usage for the
  67  * struct &v4l2_device pointed by @v4l2_dev.
  68  */
  69 static inline void v4l2_device_get(struct v4l2_device *v4l2_dev)
  70 {
  71         kref_get(&v4l2_dev->ref);
  72 }
  73
  74 /**
  75  * v4l2_device_put - puts a V4L2 device reference
  76  *
  77  * @v4l2_dev: pointer to struct &v4l2_device
  78  *
  79  * This is an ancillary routine meant to decrement the usage for the
  80  * struct &v4l2_device pointed by @v4l2_dev.
  81  */
  82 int v4l2_device_put(struct v4l2_device *v4l2_dev);
  83
  84 /**
  85  * v4l2_device_register - Initialize v4l2_dev and make @dev->driver_data
  86  *      point to @v4l2_dev.
  87  *
  88  * @dev: pointer to struct &device
  89  * @v4l2_dev: pointer to struct &v4l2_device
  90  *
  91  * .. note::
  92  *      @dev may be %NULL in rare cases (ISA devices).
  93  *      In such case the caller must fill in the @v4l2_dev->name field
  94  *      before calling this function.
  95  */
  96 int __must_check v4l2_device_register(struct device *dev,
  97                                       struct v4l2_device *v4l2_dev);
  98
  99 /**
 100  * v4l2_device_set_name - Optional function to initialize the
 101  *      name field of struct &v4l2_device
 102  *
 103  * @v4l2_dev: pointer to struct &v4l2_device
 104  * @basename: base name for the device name
 105  * @instance: pointer to a static atomic_t var with the instance usage for
 106  *      the device driver.
 107  *
 108  * v4l2_device_set_name() initializes the name field of struct &v4l2_device
 109  * using the driver name and a driver-global atomic_t instance.
 110  *
 111  * This function will increment the instance counter and returns the
 112  * instance value used in the name.
 113  *
 114  * Example:
 115  *
 116  *   static atomic_t drv_instance = ATOMIC_INIT(0);
 117  *
 118  *   ...
 119  *
 120  *   instance = v4l2_device_set_name(&\ v4l2_dev, "foo", &\ drv_instance);
 121  *
 122  * The first time this is called the name field will be set to foo0 and
 123  * this function returns 0. If the name ends with a digit (e.g. cx18),
 124  * then the name will be set to cx18-0 since cx180 would look really odd.
 125  */
 126 int v4l2_device_set_name(struct v4l2_device *v4l2_dev, const char *basename,
 127                          atomic_t *instance);
 128
 129 /**
 130  * v4l2_device_disconnect - Change V4L2 device state to disconnected.
 131  *
 132  * @v4l2_dev: pointer to struct v4l2_device
 133  *
 134  * Should be called when the USB parent disconnects.
 135  * Since the parent disappears, this ensures that @v4l2_dev doesn't have
 136  * an invalid parent pointer.
 137  *
 138  * .. note:: This function sets @v4l2_dev->dev to NULL.
 139  */
 140 void v4l2_device_disconnect(struct v4l2_device *v4l2_dev);
 141
 142 /**
 143  *  v4l2_device_unregister - Unregister all sub-devices and any other
 144  *       resources related to @v4l2_dev.
 145  *
 146  * @v4l2_dev: pointer to struct v4l2_device
 147  */
 148 void v4l2_device_unregister(struct v4l2_device *v4l2_dev);
 149
 150 /**
 151  * v4l2_device_register_subdev - Registers a subdev with a v4l2 device.
 152  *
 153  * @v4l2_dev: pointer to struct &v4l2_device
 154  * @sd: pointer to &struct v4l2_subdev
 155  *
 156  * While registered, the subdev module is marked as in-use.
 157  *
 158  * An error is returned if the module is no longer loaded on any attempts
 159  * to register it.
 160  */
 161 int __must_check v4l2_device_register_subdev(struct v4l2_device *v4l2_dev,
 162                                              struct v4l2_subdev *sd);
 163
 164 /**
 165  * v4l2_device_unregister_subdev - Unregisters a subdev with a v4l2 device.
 166  *
 167  * @sd: pointer to &struct v4l2_subdev
 168  *
 169  * .. note ::
 170  *
 171  *      Can also be called if the subdev wasn't registered. In such
 172  *      case, it will do nothing.
 173  */
 174 void v4l2_device_unregister_subdev(struct v4l2_subdev *sd);
 175
 176 /**
 177  * __v4l2_device_register_subdev_nodes - Registers device nodes for
 178  *      all subdevs of the v4l2 device that are marked with the
 179  *      %V4L2_SUBDEV_FL_HAS_DEVNODE flag.
 180  *
 181  * @v4l2_dev: pointer to struct v4l2_device
 182  * @read_only: subdevices read-only flag. True to register the subdevices
 183  *      device nodes in read-only mode, false to allow full access to the
 184  *      subdevice userspace API.
 185  */
 186 int __must_check
 187 __v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev,
 188                                     bool read_only);
 189
 190 /**
 191  * v4l2_device_register_subdev_nodes - Registers subdevices device nodes with
 192  *      unrestricted access to the subdevice userspace operations
 193  *
 194  * Internally calls __v4l2_device_register_subdev_nodes(). See its documentation
 195  * for more details.
 196  *
 197  * @v4l2_dev: pointer to struct v4l2_device
 198  */
 199 static inline int __must_check
 200 v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev)
 201 {
 202 #if defined(CONFIG_VIDEO_V4L2_SUBDEV_API)
 203         return __v4l2_device_register_subdev_nodes(v4l2_dev, false);
 204 #else
 205         return 0;
 206 #endif
 207 }
 208
 209 /**
 210  * v4l2_device_register_ro_subdev_nodes - Registers subdevices device nodes
 211  *      in read-only mode
 212  *
 213  * Internally calls __v4l2_device_register_subdev_nodes(). See its documentation
 214  * for more details.
 215  *
 216  * @v4l2_dev: pointer to struct v4l2_device
 217  */
 218 static inline int __must_check
 219 v4l2_device_register_ro_subdev_nodes(struct v4l2_device *v4l2_dev)
 220 {
 221 #if defined(CONFIG_VIDEO_V4L2_SUBDEV_API)
 222         return __v4l2_device_register_subdev_nodes(v4l2_dev, true);
 223 #else
 224         return 0;
 225 #endif
 226 }
 227
 228 /**
 229  * v4l2_subdev_notify - Sends a notification to v4l2_device.
 230  *
 231  * @sd: pointer to &struct v4l2_subdev
 232  * @notification: type of notification. Please notice that the notification
 233  *      type is driver-specific.
 234  * @arg: arguments for the notification. Those are specific to each
 235  *      notification type.
 236  */
 237 static inline void v4l2_subdev_notify(struct v4l2_subdev *sd,
 238                                       unsigned int notification, void *arg)
 239 {
 240         if (sd && sd->v4l2_dev && sd->v4l2_dev->notify)
 241                 sd->v4l2_dev->notify(sd, notification, arg);
 242 }
 243
 244 /**
 245  * v4l2_device_supports_requests - Test if requests are supported.
 246  *
 247  * @v4l2_dev: pointer to struct v4l2_device
 248  */
 249 static inline bool v4l2_device_supports_requests(struct v4l2_device *v4l2_dev)
 250 {
 251         return v4l2_dev->mdev && v4l2_dev->mdev->ops &&
 252                v4l2_dev->mdev->ops->req_queue;
 253 }
 254
 255 /* Helper macros to iterate over all subdevs. */
 256
 257 /**
 258  * v4l2_device_for_each_subdev - Helper macro that interates over all
 259  *      sub-devices of a given &v4l2_device.
 260  *
 261  * @sd: pointer that will be filled by the macro with all
 262  *      &struct v4l2_subdev pointer used as an iterator by the loop.
 263  * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
 264  *
 265  * This macro iterates over all sub-devices owned by the @v4l2_dev device.
 266  * It acts as a for loop iterator and executes the next statement with
 267  * the @sd variable pointing to each sub-device in turn.
 268  */
 269 #define v4l2_device_for_each_subdev(sd, v4l2_dev)                       \
 270         list_for_each_entry(sd, &(v4l2_dev)->subdevs, list)
 271
 272 /**
 273  * __v4l2_device_call_subdevs_p - Calls the specified operation for
 274  *      all subdevs matching the condition.
 275  *
 276  * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
 277  * @sd: pointer that will be filled by the macro with all
 278  *      &struct v4l2_subdev pointer used as an iterator by the loop.
 279  * @cond: condition to be match
 280  * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
 281  *     Each element there groups a set of operations functions.
 282  * @f: operation function that will be called if @cond matches.
 283  *      The operation functions are defined in groups, according to
 284  *      each element at &struct v4l2_subdev_ops.
 285  * @args: arguments for @f.
 286  *
 287  * Ignore any errors.
 288  *
 289  * Note: subdevs cannot be added or deleted while walking
 290  * the subdevs list.
 291  */
 292 #define __v4l2_device_call_subdevs_p(v4l2_dev, sd, cond, o, f, args...) \
 293         do {                                                            \
 294                 list_for_each_entry((sd), &(v4l2_dev)->subdevs, list)   \
 295                         if ((cond) && (sd)->ops->o && (sd)->ops->o->f)  \
 296                                 (sd)->ops->o->f((sd) , ##args);         \
 297         } while (0)
 298
 299 /**
 300  * __v4l2_device_call_subdevs - Calls the specified operation for
 301  *      all subdevs matching the condition.
 302  *
 303  * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
 304  * @cond: condition to be match
 305  * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
 306  *     Each element there groups a set of operations functions.
 307  * @f: operation function that will be called if @cond matches.
 308  *      The operation functions are defined in groups, according to
 309  *      each element at &struct v4l2_subdev_ops.
 310  * @args: arguments for @f.
 311  *
 312  * Ignore any errors.
 313  *
 314  * Note: subdevs cannot be added or deleted while walking
 315  * the subdevs list.
 316  */
 317 #define __v4l2_device_call_subdevs(v4l2_dev, cond, o, f, args...)       \
 318         do {                                                            \
 319                 struct v4l2_subdev *__sd;                               \
 320                                                                         \
 321                 __v4l2_device_call_subdevs_p(v4l2_dev, __sd, cond, o,   \
 322                                                 f , ##args);            \
 323         } while (0)
 324
 325 /**
 326  * __v4l2_device_call_subdevs_until_err_p - Calls the specified operation for
 327  *      all subdevs matching the condition.
 328  *
 329  * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
 330  * @sd: pointer that will be filled by the macro with all
 331  *      &struct v4l2_subdev sub-devices associated with @v4l2_dev.
 332  * @cond: condition to be match
 333  * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
 334  *     Each element there groups a set of operations functions.
 335  * @f: operation function that will be called if @cond matches.
 336  *      The operation functions are defined in groups, according to
 337  *      each element at &struct v4l2_subdev_ops.
 338  * @args: arguments for @f.
 339  *
 340  * Return:
 341  *
 342  * If the operation returns an error other than 0 or ``-ENOIOCTLCMD``
 343  * for any subdevice, then abort and return with that error code, zero
 344  * otherwise.
 345  *
 346  * Note: subdevs cannot be added or deleted while walking
 347  * the subdevs list.
 348  */
 349 #define __v4l2_device_call_subdevs_until_err_p(v4l2_dev, sd, cond, o, f, args...) \
 350 ({                                                                      \
 351         long __err = 0;                                                 \
 352                                                                         \
 353         list_for_each_entry((sd), &(v4l2_dev)->subdevs, list) {         \
 354                 if ((cond) && (sd)->ops->o && (sd)->ops->o->f)          \
 355                         __err = (sd)->ops->o->f((sd) , ##args);         \
 356                 if (__err && __err != -ENOIOCTLCMD)                     \
 357                         break;                                          \
 358         }                                                               \
 359         (__err == -ENOIOCTLCMD) ? 0 : __err;                            \
 360 })
 361
 362 /**
 363  * __v4l2_device_call_subdevs_until_err - Calls the specified operation for
 364  *      all subdevs matching the condition.
 365  *
 366  * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
 367  * @cond: condition to be match
 368  * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
 369  *     Each element there groups a set of operations functions.
 370  * @f: operation function that will be called if @cond matches.
 371  *      The operation functions are defined in groups, according to
 372  *      each element at &struct v4l2_subdev_ops.
 373  * @args: arguments for @f.
 374  *
 375  * Return:
 376  *
 377  * If the operation returns an error other than 0 or ``-ENOIOCTLCMD``
 378  * for any subdevice, then abort and return with that error code,
 379  * zero otherwise.
 380  *
 381  * Note: subdevs cannot be added or deleted while walking
 382  * the subdevs list.
 383  */
 384 #define __v4l2_device_call_subdevs_until_err(v4l2_dev, cond, o, f, args...) \
 385 ({                                                                      \
 386         struct v4l2_subdev *__sd;                                       \
 387         __v4l2_device_call_subdevs_until_err_p(v4l2_dev, __sd, cond, o, \
 388                                                 f , ##args);            \
 389 })
 390
 391 /**
 392  * v4l2_device_call_all - Calls the specified operation for
 393  *      all subdevs matching the &v4l2_subdev.grp_id, as assigned
 394  *      by the bridge driver.
 395  *
 396  * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
 397  * @grpid: &struct v4l2_subdev->grp_id group ID to match.
 398  *          Use 0 to match them all.
 399  * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
 400  *     Each element there groups a set of operations functions.
 401  * @f: operation function that will be called if @cond matches.
 402  *      The operation functions are defined in groups, according to
 403  *      each element at &struct v4l2_subdev_ops.
 404  * @args: arguments for @f.
 405  *
 406  * Ignore any errors.
 407  *
 408  * Note: subdevs cannot be added or deleted while walking
 409  * the subdevs list.
 410  */
 411 #define v4l2_device_call_all(v4l2_dev, grpid, o, f, args...)            \
 412         do {                                                            \
 413                 struct v4l2_subdev *__sd;                               \
 414                                                                         \
 415                 __v4l2_device_call_subdevs_p(v4l2_dev, __sd,            \
 416                         (grpid) == 0 || __sd->grp_id == (grpid), o, f , \
 417                         ##args);                                        \
 418         } while (0)
 419
 420 /**
 421  * v4l2_device_call_until_err - Calls the specified operation for
 422  *      all subdevs matching the &v4l2_subdev.grp_id, as assigned
 423  *      by the bridge driver, until an error occurs.
 424  *
 425  * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
 426  * @grpid: &struct v4l2_subdev->grp_id group ID to match.
 427  *         Use 0 to match them all.
 428  * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
 429  *     Each element there groups a set of operations functions.
 430  * @f: operation function that will be called if @cond matches.
 431  *      The operation functions are defined in groups, according to
 432  *      each element at &struct v4l2_subdev_ops.
 433  * @args: arguments for @f.
 434  *
 435  * Return:
 436  *
 437  * If the operation returns an error other than 0 or ``-ENOIOCTLCMD``
 438  * for any subdevice, then abort and return with that error code,
 439  * zero otherwise.
 440  *
 441  * Note: subdevs cannot be added or deleted while walking
 442  * the subdevs list.
 443  */
 444 #define v4l2_device_call_until_err(v4l2_dev, grpid, o, f, args...)      \
 445 ({                                                                      \
 446         struct v4l2_subdev *__sd;                                       \
 447         __v4l2_device_call_subdevs_until_err_p(v4l2_dev, __sd,          \
 448                         (grpid) == 0 || __sd->grp_id == (grpid), o, f , \
 449                         ##args);                                        \
 450 })
 451
 452 /**
 453  * v4l2_device_mask_call_all - Calls the specified operation for
 454  *      all subdevices where a group ID matches a specified bitmask.
 455  *
 456  * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
 457  * @grpmsk: bitmask to be checked against &struct v4l2_subdev->grp_id
 458  *          group ID to be matched. Use 0 to match them all.
 459  * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
 460  *     Each element there groups a set of operations functions.
 461  * @f: operation function that will be called if @cond matches.
 462  *      The operation functions are defined in groups, according to
 463  *      each element at &struct v4l2_subdev_ops.
 464  * @args: arguments for @f.
 465  *
 466  * Ignore any errors.
 467  *
 468  * Note: subdevs cannot be added or deleted while walking
 469  * the subdevs list.
 470  */
 471 #define v4l2_device_mask_call_all(v4l2_dev, grpmsk, o, f, args...)      \
 472         do {                                                            \
 473                 struct v4l2_subdev *__sd;                               \
 474                                                                         \
 475                 __v4l2_device_call_subdevs_p(v4l2_dev, __sd,            \
 476                         (grpmsk) == 0 || (__sd->grp_id & (grpmsk)), o,  \
 477                         f , ##args);                                    \
 478         } while (0)
 479
 480 /**
 481  * v4l2_device_mask_call_until_err - Calls the specified operation for
 482  *      all subdevices where a group ID matches a specified bitmask.
 483  *
 484  * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
 485  * @grpmsk: bitmask to be checked against &struct v4l2_subdev->grp_id
 486  *          group ID to be matched. Use 0 to match them all.
 487  * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
 488  *     Each element there groups a set of operations functions.
 489  * @f: operation function that will be called if @cond matches.
 490  *      The operation functions are defined in groups, according to
 491  *      each element at &struct v4l2_subdev_ops.
 492  * @args: arguments for @f.
 493  *
 494  * Return:
 495  *
 496  * If the operation returns an error other than 0 or ``-ENOIOCTLCMD``
 497  * for any subdevice, then abort and return with that error code,
 498  * zero otherwise.
 499  *
 500  * Note: subdevs cannot be added or deleted while walking
 501  * the subdevs list.
 502  */
 503 #define v4l2_device_mask_call_until_err(v4l2_dev, grpmsk, o, f, args...) \
 504 ({                                                                      \
 505         struct v4l2_subdev *__sd;                                       \
 506         __v4l2_device_call_subdevs_until_err_p(v4l2_dev, __sd,          \
 507                         (grpmsk) == 0 || (__sd->grp_id & (grpmsk)), o,  \
 508                         f , ##args);                                    \
 509 })
 510
 511
 512 /**
 513  * v4l2_device_has_op - checks if any subdev with matching grpid has a
 514  *      given ops.
 515  *
 516  * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
 517  * @grpid: &struct v4l2_subdev->grp_id group ID to match.
 518  *         Use 0 to match them all.
 519  * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
 520  *     Each element there groups a set of operations functions.
 521  * @f: operation function that will be called if @cond matches.
 522  *      The operation functions are defined in groups, according to
 523  *      each element at &struct v4l2_subdev_ops.
 524  */
 525 #define v4l2_device_has_op(v4l2_dev, grpid, o, f)                       \
 526 ({                                                                      \
 527         struct v4l2_subdev *__sd;                                       \
 528         bool __result = false;                                          \
 529         list_for_each_entry(__sd, &(v4l2_dev)->subdevs, list) {         \
 530                 if ((grpid) && __sd->grp_id != (grpid))                 \
 531                         continue;                                       \
 532                 if (v4l2_subdev_has_op(__sd, o, f)) {                   \
 533                         __result = true;                                \
 534                         break;                                          \
 535                 }                                                       \
 536         }                                                               \
 537         __result;                                                       \
 538 })
 539
 540 /**
 541  * v4l2_device_mask_has_op - checks if any subdev with matching group
 542  *      mask has a given ops.
 543  *
 544  * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
 545  * @grpmsk: bitmask to be checked against &struct v4l2_subdev->grp_id
 546  *          group ID to be matched. Use 0 to match them all.
 547  * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
 548  *     Each element there groups a set of operations functions.
 549  * @f: operation function that will be called if @cond matches.
 550  *      The operation functions are defined in groups, according to
 551  *      each element at &struct v4l2_subdev_ops.
 552  */
 553 #define v4l2_device_mask_has_op(v4l2_dev, grpmsk, o, f)                 \
 554 ({                                                                      \
 555         struct v4l2_subdev *__sd;                                       \
 556         bool __result = false;                                          \
 557         list_for_each_entry(__sd, &(v4l2_dev)->subdevs, list) {         \
 558                 if ((grpmsk) && !(__sd->grp_id & (grpmsk)))             \
 559                         continue;                                       \
 560                 if (v4l2_subdev_has_op(__sd, o, f)) {                   \
 561                         __result = true;                                \
 562                         break;                                          \
 563                 }                                                       \
 564         }                                                               \
 565         __result;                                                       \
 566 })
 567
 568 #endif