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