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