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