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