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 - putss 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