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 all subdevs
 178  *      of the v4l2 device that are marked with
 179  *      the %V4L2_SUBDEV_FL_HAS_DEVNODE flag.
 180  *
 181  * @v4l2_dev: pointer to struct v4l2_device
 182  */
 183 int __must_check
 184 v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev);
 185
 186 /**
 187  * v4l2_subdev_notify - Sends a notification to v4l2_device.
 188  *
 189  * @sd: pointer to &struct v4l2_subdev
 190  * @notification: type of notification. Please notice that the notification
 191  *      type is driver-specific.
 192  * @arg: arguments for the notification. Those are specific to each
 193  *      notification type.
 194  */
 195 static inline void v4l2_subdev_notify(struct v4l2_subdev *sd,
 196                                       unsigned int notification, void *arg)
 197 {
 198         if (sd && sd->v4l2_dev && sd->v4l2_dev->notify)
 199                 sd->v4l2_dev->notify(sd, notification, arg);
 200 }
 201
 202 /**
 203  * v4l2_device_supports_requests - Test if requests are supported.
 204  *
 205  * @v4l2_dev: pointer to struct v4l2_device
 206  */
 207 static inline bool v4l2_device_supports_requests(struct v4l2_device *v4l2_dev)
 208 {
 209         return v4l2_dev->mdev && v4l2_dev->mdev->ops &&
 210                v4l2_dev->mdev->ops->req_queue;
 211 }
 212
 213 /* Helper macros to iterate over all subdevs. */
 214
 215 /**
 216  * v4l2_device_for_each_subdev - Helper macro that interates over all
 217  *      sub-devices of a given &v4l2_device.
 218  *
 219  * @sd: pointer that will be filled by the macro with all
 220  *      &struct v4l2_subdev pointer used as an iterator by the loop.
 221  * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
 222  *
 223  * This macro iterates over all sub-devices owned by the @v4l2_dev device.
 224  * It acts as a for loop iterator and executes the next statement with
 225  * the @sd variable pointing to each sub-device in turn.
 226  */
 227 #define v4l2_device_for_each_subdev(sd, v4l2_dev)                       \
 228         list_for_each_entry(sd, &(v4l2_dev)->subdevs, list)
 229
 230 /**
 231  * __v4l2_device_call_subdevs_p - Calls the specified operation for
 232  *      all subdevs matching the condition.
 233  *
 234  * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
 235  * @sd: pointer that will be filled by the macro with all
 236  *      &struct v4l2_subdev pointer used as an iterator by the loop.
 237  * @cond: condition to be match
 238  * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
 239  *     Each element there groups a set of operations functions.
 240  * @f: operation function that will be called if @cond matches.
 241  *      The operation functions are defined in groups, according to
 242  *      each element at &struct v4l2_subdev_ops.
 243  * @args: arguments for @f.
 244  *
 245  * Ignore any errors.
 246  *
 247  * Note: subdevs cannot be added or deleted while walking
 248  * the subdevs list.
 249  */
 250 #define __v4l2_device_call_subdevs_p(v4l2_dev, sd, cond, o, f, args...) \
 251         do {                                                            \
 252                 list_for_each_entry((sd), &(v4l2_dev)->subdevs, list)   \
 253                         if ((cond) && (sd)->ops->o && (sd)->ops->o->f)  \
 254                                 (sd)->ops->o->f((sd) , ##args);         \
 255         } while (0)
 256
 257 /**
 258  * __v4l2_device_call_subdevs - Calls the specified operation for
 259  *      all subdevs matching the condition.
 260  *
 261  * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
 262  * @cond: condition to be match
 263  * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
 264  *     Each element there groups a set of operations functions.
 265  * @f: operation function that will be called if @cond matches.
 266  *      The operation functions are defined in groups, according to
 267  *      each element at &struct v4l2_subdev_ops.
 268  * @args: arguments for @f.
 269  *
 270  * Ignore any errors.
 271  *
 272  * Note: subdevs cannot be added or deleted while walking
 273  * the subdevs list.
 274  */
 275 #define __v4l2_device_call_subdevs(v4l2_dev, cond, o, f, args...)       \
 276         do {                                                            \
 277                 struct v4l2_subdev *__sd;                               \
 278                                                                         \
 279                 __v4l2_device_call_subdevs_p(v4l2_dev, __sd, cond, o,   \
 280                                                 f , ##args);            \
 281         } while (0)
 282
 283 /**
 284  * __v4l2_device_call_subdevs_until_err_p - Calls the specified operation for
 285  *      all subdevs matching the condition.
 286  *
 287  * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
 288  * @sd: pointer that will be filled by the macro with all
 289  *      &struct v4l2_subdev sub-devices associated with @v4l2_dev.
 290  * @cond: condition to be match
 291  * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
 292  *     Each element there groups a set of operations functions.
 293  * @f: operation function that will be called if @cond matches.
 294  *      The operation functions are defined in groups, according to
 295  *      each element at &struct v4l2_subdev_ops.
 296  * @args: arguments for @f.
 297  *
 298  * Return:
 299  *
 300  * If the operation returns an error other than 0 or ``-ENOIOCTLCMD``
 301  * for any subdevice, then abort and return with that error code, zero
 302  * otherwise.
 303  *
 304  * Note: subdevs cannot be added or deleted while walking
 305  * the subdevs list.
 306  */
 307 #define __v4l2_device_call_subdevs_until_err_p(v4l2_dev, sd, cond, o, f, args...) \
 308 ({                                                                      \
 309         long __err = 0;                                                 \
 310                                                                         \
 311         list_for_each_entry((sd), &(v4l2_dev)->subdevs, list) {         \
 312                 if ((cond) && (sd)->ops->o && (sd)->ops->o->f)          \
 313                         __err = (sd)->ops->o->f((sd) , ##args);         \
 314                 if (__err && __err != -ENOIOCTLCMD)                     \
 315                         break;                                          \
 316         }                                                               \
 317         (__err == -ENOIOCTLCMD) ? 0 : __err;                            \
 318 })
 319
 320 /**
 321  * __v4l2_device_call_subdevs_until_err - Calls the specified operation for
 322  *      all subdevs matching the condition.
 323  *
 324  * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
 325  * @cond: condition to be match
 326  * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
 327  *     Each element there groups a set of operations functions.
 328  * @f: operation function that will be called if @cond matches.
 329  *      The operation functions are defined in groups, according to
 330  *      each element at &struct v4l2_subdev_ops.
 331  * @args: arguments for @f.
 332  *
 333  * Return:
 334  *
 335  * If the operation returns an error other than 0 or ``-ENOIOCTLCMD``
 336  * for any subdevice, then abort and return with that error code,
 337  * zero otherwise.
 338  *
 339  * Note: subdevs cannot be added or deleted while walking
 340  * the subdevs list.
 341  */
 342 #define __v4l2_device_call_subdevs_until_err(v4l2_dev, cond, o, f, args...) \
 343 ({                                                                      \
 344         struct v4l2_subdev *__sd;                                       \
 345         __v4l2_device_call_subdevs_until_err_p(v4l2_dev, __sd, cond, o, \
 346                                                 f , ##args);            \
 347 })
 348
 349 /**
 350  * v4l2_device_call_all - Calls the specified operation for
 351  *      all subdevs matching the &v4l2_subdev.grp_id, as assigned
 352  *      by the bridge driver.
 353  *
 354  * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
 355  * @grpid: &struct v4l2_subdev->grp_id group ID to match.
 356  *          Use 0 to match them all.
 357  * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
 358  *     Each element there groups a set of operations functions.
 359  * @f: operation function that will be called if @cond matches.
 360  *      The operation functions are defined in groups, according to
 361  *      each element at &struct v4l2_subdev_ops.
 362  * @args: arguments for @f.
 363  *
 364  * Ignore any errors.
 365  *
 366  * Note: subdevs cannot be added or deleted while walking
 367  * the subdevs list.
 368  */
 369 #define v4l2_device_call_all(v4l2_dev, grpid, o, f, args...)            \
 370         do {                                                            \
 371                 struct v4l2_subdev *__sd;                               \
 372                                                                         \
 373                 __v4l2_device_call_subdevs_p(v4l2_dev, __sd,            \
 374                         (grpid) == 0 || __sd->grp_id == (grpid), o, f , \
 375                         ##args);                                        \
 376         } while (0)
 377
 378 /**
 379  * v4l2_device_call_until_err - Calls the specified operation for
 380  *      all subdevs matching the &v4l2_subdev.grp_id, as assigned
 381  *      by the bridge driver, until an error occurs.
 382  *
 383  * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
 384  * @grpid: &struct v4l2_subdev->grp_id group ID to match.
 385  *         Use 0 to match them all.
 386  * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
 387  *     Each element there groups a set of operations functions.
 388  * @f: operation function that will be called if @cond matches.
 389  *      The operation functions are defined in groups, according to
 390  *      each element at &struct v4l2_subdev_ops.
 391  * @args: arguments for @f.
 392  *
 393  * Return:
 394  *
 395  * If the operation returns an error other than 0 or ``-ENOIOCTLCMD``
 396  * for any subdevice, then abort and return with that error code,
 397  * zero otherwise.
 398  *
 399  * Note: subdevs cannot be added or deleted while walking
 400  * the subdevs list.
 401  */
 402 #define v4l2_device_call_until_err(v4l2_dev, grpid, o, f, args...)      \
 403 ({                                                                      \
 404         struct v4l2_subdev *__sd;                                       \
 405         __v4l2_device_call_subdevs_until_err_p(v4l2_dev, __sd,          \
 406                         (grpid) == 0 || __sd->grp_id == (grpid), o, f , \
 407                         ##args);                                        \
 408 })
 409
 410 /**
 411  * v4l2_device_mask_call_all - Calls the specified operation for
 412  *      all subdevices where a group ID matches a specified bitmask.
 413  *
 414  * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
 415  * @grpmsk: bitmask to be checked against &struct v4l2_subdev->grp_id
 416  *          group ID to be matched. Use 0 to match them all.
 417  * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
 418  *     Each element there groups a set of operations functions.
 419  * @f: operation function that will be called if @cond matches.
 420  *      The operation functions are defined in groups, according to
 421  *      each element at &struct v4l2_subdev_ops.
 422  * @args: arguments for @f.
 423  *
 424  * Ignore any errors.
 425  *
 426  * Note: subdevs cannot be added or deleted while walking
 427  * the subdevs list.
 428  */
 429 #define v4l2_device_mask_call_all(v4l2_dev, grpmsk, o, f, args...)      \
 430         do {                                                            \
 431                 struct v4l2_subdev *__sd;                               \
 432                                                                         \
 433                 __v4l2_device_call_subdevs_p(v4l2_dev, __sd,            \
 434                         (grpmsk) == 0 || (__sd->grp_id & (grpmsk)), o,  \
 435                         f , ##args);                                    \
 436         } while (0)
 437
 438 /**
 439  * v4l2_device_mask_call_until_err - Calls the specified operation for
 440  *      all subdevices where a group ID matches a specified bitmask.
 441  *
 442  * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
 443  * @grpmsk: bitmask to be checked against &struct v4l2_subdev->grp_id
 444  *          group ID to be matched. Use 0 to match them all.
 445  * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
 446  *     Each element there groups a set of operations functions.
 447  * @f: operation function that will be called if @cond matches.
 448  *      The operation functions are defined in groups, according to
 449  *      each element at &struct v4l2_subdev_ops.
 450  * @args: arguments for @f.
 451  *
 452  * Return:
 453  *
 454  * If the operation returns an error other than 0 or ``-ENOIOCTLCMD``
 455  * for any subdevice, then abort and return with that error code,
 456  * zero otherwise.
 457  *
 458  * Note: subdevs cannot be added or deleted while walking
 459  * the subdevs list.
 460  */
 461 #define v4l2_device_mask_call_until_err(v4l2_dev, grpmsk, o, f, args...) \
 462 ({                                                                      \
 463         struct v4l2_subdev *__sd;                                       \
 464         __v4l2_device_call_subdevs_until_err_p(v4l2_dev, __sd,          \
 465                         (grpmsk) == 0 || (__sd->grp_id & (grpmsk)), o,  \
 466                         f , ##args);                                    \
 467 })
 468
 469
 470 /**
 471  * v4l2_device_has_op - checks if any subdev with matching grpid has a
 472  *      given ops.
 473  *
 474  * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
 475  * @grpid: &struct v4l2_subdev->grp_id group ID to match.
 476  *         Use 0 to match them all.
 477  * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
 478  *     Each element there groups a set of operations functions.
 479  * @f: operation function that will be called if @cond matches.
 480  *      The operation functions are defined in groups, according to
 481  *      each element at &struct v4l2_subdev_ops.
 482  */
 483 #define v4l2_device_has_op(v4l2_dev, grpid, o, f)                       \
 484 ({                                                                      \
 485         struct v4l2_subdev *__sd;                                       \
 486         bool __result = false;                                          \
 487         list_for_each_entry(__sd, &(v4l2_dev)->subdevs, list) {         \
 488                 if ((grpid) && __sd->grp_id != (grpid))                 \
 489                         continue;                                       \
 490                 if (v4l2_subdev_has_op(__sd, o, f)) {                   \
 491                         __result = true;                                \
 492                         break;                                          \
 493                 }                                                       \
 494         }                                                               \
 495         __result;                                                       \
 496 })
 497
 498 /**
 499  * v4l2_device_mask_has_op - checks if any subdev with matching group
 500  *      mask has a given ops.
 501  *
 502  * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
 503  * @grpmsk: bitmask to be checked against &struct v4l2_subdev->grp_id
 504  *          group ID to be matched. Use 0 to match them all.
 505  * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
 506  *     Each element there groups a set of operations functions.
 507  * @f: operation function that will be called if @cond matches.
 508  *      The operation functions are defined in groups, according to
 509  *      each element at &struct v4l2_subdev_ops.
 510  */
 511 #define v4l2_device_mask_has_op(v4l2_dev, grpmsk, o, f)                 \
 512 ({                                                                      \
 513         struct v4l2_subdev *__sd;                                       \
 514         bool __result = false;                                          \
 515         list_for_each_entry(__sd, &(v4l2_dev)->subdevs, list) {         \
 516                 if ((grpmsk) && !(__sd->grp_id & (grpmsk)))             \
 517                         continue;                                       \
 518                 if (v4l2_subdev_has_op(__sd, o, f)) {                   \
 519                         __result = true;                                \
 520                         break;                                          \
 521                 }                                                       \
 522         }                                                               \
 523         __result;                                                       \
 524 })
 525
 526 #endif