xref: /linux/include/media/v4l2-device.h (revision c532de5a67a70f8533d495f8f2aaa9a0491c3ad0) 
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