include/media/v4l2-device.h

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