1 /* SPDX-License-Identifier: GPL-2.0 */
2 /*
3 *
4 * V 4 L 2 D R I V E R H E L P E R A P I
5 *
6 * Moved from videodev2.h
7 *
8 * Some commonly needed functions for drivers (v4l2-common.o module)
9 */
10 #ifndef _V4L2_DEV_H
11 #define _V4L2_DEV_H
12
13 #include <linux/poll.h>
14 #include <linux/fs.h>
15 #include <linux/device.h>
16 #include <linux/cdev.h>
17 #include <linux/mutex.h>
18 #include <linux/videodev2.h>
19
20 #include <media/media-entity.h>
21
22 #define VIDEO_MAJOR 81
23
24 /**
25 * enum vfl_devnode_type - type of V4L2 device node
26 *
27 * @VFL_TYPE_GRABBER: for video input/output devices
28 * @VFL_TYPE_VBI: for vertical blank data (i.e. closed captions, teletext)
29 * @VFL_TYPE_RADIO: for radio tuners
30 * @VFL_TYPE_SUBDEV: for V4L2 subdevices
31 * @VFL_TYPE_SDR: for Software Defined Radio tuners
32 * @VFL_TYPE_TOUCH: for touch sensors
33 * @VFL_TYPE_MAX: number of VFL types, must always be last in the enum
34 */
35 enum vfl_devnode_type {
36 VFL_TYPE_GRABBER = 0,
37 VFL_TYPE_VBI,
38 VFL_TYPE_RADIO,
39 VFL_TYPE_SUBDEV,
40 VFL_TYPE_SDR,
41 VFL_TYPE_TOUCH,
42 VFL_TYPE_MAX /* Shall be the last one */
43 };
44
45 /**
46 * enum vfl_direction - Identifies if a &struct video_device corresponds
47 * to a receiver, a transmitter or a mem-to-mem device.
48 *
49 * @VFL_DIR_RX: device is a receiver.
50 * @VFL_DIR_TX: device is a transmitter.
51 * @VFL_DIR_M2M: device is a memory to memory device.
52 *
53 * Note: Ignored if &enum vfl_devnode_type is %VFL_TYPE_SUBDEV.
54 */
55 enum vfl_devnode_direction {
56 VFL_DIR_RX,
57 VFL_DIR_TX,
58 VFL_DIR_M2M,
59 };
60
61 struct v4l2_ioctl_callbacks;
62 struct video_device;
63 struct v4l2_device;
64 struct v4l2_ctrl_handler;
65
66 /**
67 * enum v4l2_video_device_flags - Flags used by &struct video_device
68 *
69 * @V4L2_FL_REGISTERED:
70 * indicates that a &struct video_device is registered.
71 * Drivers can clear this flag if they want to block all future
72 * device access. It is cleared by video_unregister_device.
73 * @V4L2_FL_USES_V4L2_FH:
74 * indicates that file->private_data points to &struct v4l2_fh.
75 * This flag is set by the core when v4l2_fh_init() is called.
76 * All new drivers should use it.
77 */
78 enum v4l2_video_device_flags {
79 V4L2_FL_REGISTERED = 0,
80 V4L2_FL_USES_V4L2_FH = 1,
81 };
82
83 /* Priority helper functions */
84
85 /**
86 * struct v4l2_prio_state - stores the priority states
87 *
88 * @prios: array with elements to store the array priorities
89 *
90 *
91 * .. note::
92 * The size of @prios array matches the number of priority types defined
93 * by enum &v4l2_priority.
94 */
95 struct v4l2_prio_state {
96 atomic_t prios[4];
97 };
98
99 /**
100 * v4l2_prio_init - initializes a struct v4l2_prio_state
101 *
102 * @global: pointer to &struct v4l2_prio_state
103 */
104 void v4l2_prio_init(struct v4l2_prio_state *global);
105
106 /**
107 * v4l2_prio_change - changes the v4l2 file handler priority
108 *
109 * @global: pointer to the &struct v4l2_prio_state of the device node.
110 * @local: pointer to the desired priority, as defined by enum &v4l2_priority
111 * @new: Priority type requested, as defined by enum &v4l2_priority.
112 *
113 * .. note::
114 * This function should be used only by the V4L2 core.
115 */
116 int v4l2_prio_change(struct v4l2_prio_state *global, enum v4l2_priority *local,
117 enum v4l2_priority new);
118
119 /**
120 * v4l2_prio_open - Implements the priority logic for a file handler open
121 *
122 * @global: pointer to the &struct v4l2_prio_state of the device node.
123 * @local: pointer to the desired priority, as defined by enum &v4l2_priority
124 *
125 * .. note::
126 * This function should be used only by the V4L2 core.
127 */
128 void v4l2_prio_open(struct v4l2_prio_state *global, enum v4l2_priority *local);
129
130 /**
131 * v4l2_prio_close - Implements the priority logic for a file handler close
132 *
133 * @global: pointer to the &struct v4l2_prio_state of the device node.
134 * @local: priority to be released, as defined by enum &v4l2_priority
135 *
136 * .. note::
137 * This function should be used only by the V4L2 core.
138 */
139 void v4l2_prio_close(struct v4l2_prio_state *global, enum v4l2_priority local);
140
141 /**
142 * v4l2_prio_max - Return the maximum priority, as stored at the @global array.
143 *
144 * @global: pointer to the &struct v4l2_prio_state of the device node.
145 *
146 * .. note::
147 * This function should be used only by the V4L2 core.
148 */
149 enum v4l2_priority v4l2_prio_max(struct v4l2_prio_state *global);
150
151 /**
152 * v4l2_prio_check - Implements the priority logic for a file handler close
153 *
154 * @global: pointer to the &struct v4l2_prio_state of the device node.
155 * @local: desired priority, as defined by enum &v4l2_priority local
156 *
157 * .. note::
158 * This function should be used only by the V4L2 core.
159 */
160 int v4l2_prio_check(struct v4l2_prio_state *global, enum v4l2_priority local);
161
162 /**
163 * struct v4l2_file_operations - fs operations used by a V4L2 device
164 *
165 * @owner: pointer to struct module
166 * @read: operations needed to implement the read() syscall
167 * @write: operations needed to implement the write() syscall
168 * @poll: operations needed to implement the poll() syscall
169 * @unlocked_ioctl: operations needed to implement the ioctl() syscall
170 * @compat_ioctl32: operations needed to implement the ioctl() syscall for
171 * the special case where the Kernel uses 64 bits instructions, but
172 * the userspace uses 32 bits.
173 * @get_unmapped_area: called by the mmap() syscall, used when %!CONFIG_MMU
174 * @mmap: operations needed to implement the mmap() syscall
175 * @open: operations needed to implement the open() syscall
176 * @release: operations needed to implement the release() syscall
177 *
178 * .. note::
179 *
180 * Those operations are used to implemente the fs struct file_operations
181 * at the V4L2 drivers. The V4L2 core overrides the fs ops with some
182 * extra logic needed by the subsystem.
183 */
184 struct v4l2_file_operations {
185 struct module *owner;
186 ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
187 ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);
188 __poll_t (*poll) (struct file *, struct poll_table_struct *);
189 long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long);
190 #ifdef CONFIG_COMPAT
191 long (*compat_ioctl32) (struct file *, unsigned int, unsigned long);
192 #endif
193 unsigned long (*get_unmapped_area) (struct file *, unsigned long,
194 unsigned long, unsigned long, unsigned long);
195 int (*mmap) (struct file *, struct vm_area_struct *);
196 int (*open) (struct file *);
197 int (*release) (struct file *);
198 };
199
200 /*
201 * Newer version of video_device, handled by videodev2.c
202 * This version moves redundant code from video device code to
203 * the common handler
204 */
205
206 /**
207 * struct video_device - Structure used to create and manage the V4L2 device
208 * nodes.
209 *
210 * @entity: &struct media_entity
211 * @intf_devnode: pointer to &struct media_intf_devnode
212 * @pipe: &struct media_pipeline
213 * @fops: pointer to &struct v4l2_file_operations for the video device
214 * @device_caps: device capabilities as used in v4l2_capabilities
215 * @dev: &struct device for the video device
216 * @cdev: character device
217 * @v4l2_dev: pointer to &struct v4l2_device parent
218 * @dev_parent: pointer to &struct device parent
219 * @ctrl_handler: Control handler associated with this device node.
220 * May be NULL.
221 * @queue: &struct vb2_queue associated with this device node. May be NULL.
222 * @prio: pointer to &struct v4l2_prio_state with device's Priority state.
223 * If NULL, then v4l2_dev->prio will be used.
224 * @name: video device name
225 * @vfl_type: V4L device type, as defined by &enum vfl_devnode_type
226 * @vfl_dir: V4L receiver, transmitter or m2m
227 * @minor: device node 'minor'. It is set to -1 if the registration failed
228 * @num: number of the video device node
229 * @flags: video device flags. Use bitops to set/clear/test flags.
230 * Contains a set of &enum v4l2_video_device_flags.
231 * @index: attribute to differentiate multiple indices on one physical device
232 * @fh_lock: Lock for all v4l2_fhs
233 * @fh_list: List of &struct v4l2_fh
234 * @dev_debug: Internal device debug flags, not for use by drivers
235 * @tvnorms: Supported tv norms
236 *
237 * @release: video device release() callback
238 * @ioctl_ops: pointer to &struct v4l2_ioctl_ops with ioctl callbacks
239 *
240 * @valid_ioctls: bitmap with the valid ioctls for this device
241 * @lock: pointer to &struct mutex serialization lock
242 *
243 * .. note::
244 * Only set @dev_parent if that can't be deduced from @v4l2_dev.
245 */
246
247 struct video_device
248 {
249 #if defined(CONFIG_MEDIA_CONTROLLER)
250 struct media_entity entity;
251 struct media_intf_devnode *intf_devnode;
252 struct media_pipeline pipe;
253 #endif
254 const struct v4l2_file_operations *fops;
255
256 u32 device_caps;
257
258 /* sysfs */
259 struct device dev;
260 struct cdev *cdev;
261
262 struct v4l2_device *v4l2_dev;
263 struct device *dev_parent;
264
265 struct v4l2_ctrl_handler *ctrl_handler;
266
267 struct vb2_queue *queue;
268
269 struct v4l2_prio_state *prio;
270
271 /* device info */
272 char name[32];
273 enum vfl_devnode_type vfl_type;
274 enum vfl_devnode_direction vfl_dir;
275 int minor;
276 u16 num;
277 unsigned long flags;
278 int index;
279
280 /* V4L2 file handles */
281 spinlock_t fh_lock;
282 struct list_head fh_list;
283
284 int dev_debug;
285
286 v4l2_std_id tvnorms;
287
288 /* callbacks */
289 void (*release)(struct video_device *vdev);
290 const struct v4l2_ioctl_ops *ioctl_ops;
291 DECLARE_BITMAP(valid_ioctls, BASE_VIDIOC_PRIVATE);
292
293 struct mutex *lock;
294 };
295
296 /**
297 * media_entity_to_video_device - Returns a &struct video_device from
298 * the &struct media_entity embedded on it.
299 *
300 * @__entity: pointer to &struct media_entity
301 */
302 #define media_entity_to_video_device(__entity) \
303 container_of(__entity, struct video_device, entity)
304
305 /**
306 * to_video_device - Returns a &struct video_device from the
307 * &struct device embedded on it.
308 *
309 * @cd: pointer to &struct device
310 */
311 #define to_video_device(cd) container_of(cd, struct video_device, dev)
312
313 /**
314 * __video_register_device - register video4linux devices
315 *
316 * @vdev: struct video_device to register
317 * @type: type of device to register, as defined by &enum vfl_devnode_type
318 * @nr: which device node number is desired:
319 * (0 == /dev/video0, 1 == /dev/video1, ..., -1 == first free)
320 * @warn_if_nr_in_use: warn if the desired device node number
321 * was already in use and another number was chosen instead.
322 * @owner: module that owns the video device node
323 *
324 * The registration code assigns minor numbers and device node numbers
325 * based on the requested type and registers the new device node with
326 * the kernel.
327 *
328 * This function assumes that struct video_device was zeroed when it
329 * was allocated and does not contain any stale date.
330 *
331 * An error is returned if no free minor or device node number could be
332 * found, or if the registration of the device node failed.
333 *
334 * Returns 0 on success.
335 *
336 * .. note::
337 *
338 * This function is meant to be used only inside the V4L2 core.
339 * Drivers should use video_register_device() or
340 * video_register_device_no_warn().
341 */
342 int __must_check __video_register_device(struct video_device *vdev,
343 enum vfl_devnode_type type,
344 int nr, int warn_if_nr_in_use,
345 struct module *owner);
346
347 /**
348 * video_register_device - register video4linux devices
349 *
350 * @vdev: struct video_device to register
351 * @type: type of device to register, as defined by &enum vfl_devnode_type
352 * @nr: which device node number is desired:
353 * (0 == /dev/video0, 1 == /dev/video1, ..., -1 == first free)
354 *
355 * Internally, it calls __video_register_device(). Please see its
356 * documentation for more details.
357 *
358 * .. note::
359 * if video_register_device fails, the release() callback of
360 * &struct video_device structure is *not* called, so the caller
361 * is responsible for freeing any data. Usually that means that
362 * you video_device_release() should be called on failure.
363 */
video_register_device(struct video_device * vdev,enum vfl_devnode_type type,int nr)364 static inline int __must_check video_register_device(struct video_device *vdev,
365 enum vfl_devnode_type type,
366 int nr)
367 {
368 return __video_register_device(vdev, type, nr, 1, vdev->fops->owner);
369 }
370
371 /**
372 * video_register_device_no_warn - register video4linux devices
373 *
374 * @vdev: struct video_device to register
375 * @type: type of device to register, as defined by &enum vfl_devnode_type
376 * @nr: which device node number is desired:
377 * (0 == /dev/video0, 1 == /dev/video1, ..., -1 == first free)
378 *
379 * This function is identical to video_register_device() except that no
380 * warning is issued if the desired device node number was already in use.
381 *
382 * Internally, it calls __video_register_device(). Please see its
383 * documentation for more details.
384 *
385 * .. note::
386 * if video_register_device fails, the release() callback of
387 * &struct video_device structure is *not* called, so the caller
388 * is responsible for freeing any data. Usually that means that
389 * you video_device_release() should be called on failure.
390 */
391 static inline int __must_check
video_register_device_no_warn(struct video_device * vdev,enum vfl_devnode_type type,int nr)392 video_register_device_no_warn(struct video_device *vdev,
393 enum vfl_devnode_type type, int nr)
394 {
395 return __video_register_device(vdev, type, nr, 0, vdev->fops->owner);
396 }
397
398 /**
399 * video_unregister_device - Unregister video devices.
400 *
401 * @vdev: &struct video_device to register
402 *
403 * Does nothing if vdev == NULL or if video_is_registered() returns false.
404 */
405 void video_unregister_device(struct video_device *vdev);
406
407 /**
408 * video_device_alloc - helper function to alloc &struct video_device
409 *
410 * Returns NULL if %-ENOMEM or a &struct video_device on success.
411 */
412 struct video_device * __must_check video_device_alloc(void);
413
414 /**
415 * video_device_release - helper function to release &struct video_device
416 *
417 * @vdev: pointer to &struct video_device
418 *
419 * Can also be used for video_device->release\(\).
420 */
421 void video_device_release(struct video_device *vdev);
422
423 /**
424 * video_device_release_empty - helper function to implement the
425 * video_device->release\(\) callback.
426 *
427 * @vdev: pointer to &struct video_device
428 *
429 * This release function does nothing.
430 *
431 * It should be used when the video_device is a static global struct.
432 *
433 * .. note::
434 * Having a static video_device is a dubious construction at best.
435 */
436 void video_device_release_empty(struct video_device *vdev);
437
438 /**
439 * v4l2_disable_ioctl- mark that a given command isn't implemented.
440 * shouldn't use core locking
441 *
442 * @vdev: pointer to &struct video_device
443 * @cmd: ioctl command
444 *
445 * This function allows drivers to provide just one v4l2_ioctl_ops struct, but
446 * disable ioctls based on the specific card that is actually found.
447 *
448 * .. note::
449 *
450 * This must be called before video_register_device.
451 * See also the comments for determine_valid_ioctls().
452 */
v4l2_disable_ioctl(struct video_device * vdev,unsigned int cmd)453 static inline void v4l2_disable_ioctl(struct video_device *vdev,
454 unsigned int cmd)
455 {
456 if (_IOC_NR(cmd) < BASE_VIDIOC_PRIVATE)
457 set_bit(_IOC_NR(cmd), vdev->valid_ioctls);
458 }
459
460 /**
461 * video_get_drvdata - gets private data from &struct video_device.
462 *
463 * @vdev: pointer to &struct video_device
464 *
465 * returns a pointer to the private data
466 */
video_get_drvdata(struct video_device * vdev)467 static inline void *video_get_drvdata(struct video_device *vdev)
468 {
469 return dev_get_drvdata(&vdev->dev);
470 }
471
472 /**
473 * video_set_drvdata - sets private data from &struct video_device.
474 *
475 * @vdev: pointer to &struct video_device
476 * @data: private data pointer
477 */
video_set_drvdata(struct video_device * vdev,void * data)478 static inline void video_set_drvdata(struct video_device *vdev, void *data)
479 {
480 dev_set_drvdata(&vdev->dev, data);
481 }
482
483 /**
484 * video_devdata - gets &struct video_device from struct file.
485 *
486 * @file: pointer to struct file
487 */
488 struct video_device *video_devdata(struct file *file);
489
490 /**
491 * video_drvdata - gets private data from &struct video_device using the
492 * struct file.
493 *
494 * @file: pointer to struct file
495 *
496 * This is function combines both video_get_drvdata() and video_devdata()
497 * as this is used very often.
498 */
video_drvdata(struct file * file)499 static inline void *video_drvdata(struct file *file)
500 {
501 return video_get_drvdata(video_devdata(file));
502 }
503
504 /**
505 * video_device_node_name - returns the video device name
506 *
507 * @vdev: pointer to &struct video_device
508 *
509 * Returns the device name string
510 */
video_device_node_name(struct video_device * vdev)511 static inline const char *video_device_node_name(struct video_device *vdev)
512 {
513 return dev_name(&vdev->dev);
514 }
515
516 /**
517 * video_is_registered - returns true if the &struct video_device is registered.
518 *
519 *
520 * @vdev: pointer to &struct video_device
521 */
video_is_registered(struct video_device * vdev)522 static inline int video_is_registered(struct video_device *vdev)
523 {
524 return test_bit(V4L2_FL_REGISTERED, &vdev->flags);
525 }
526
527 #endif /* _V4L2_DEV_H */
528