1 /* SPDX-License-Identifier: GPL-2.0-only */ 2 /* 3 * Media device node 4 * 5 * Copyright (C) 2010 Nokia Corporation 6 * 7 * Contacts: Laurent Pinchart <laurent.pinchart@ideasonboard.com> 8 * Sakari Ailus <sakari.ailus@iki.fi> 9 * 10 * -- 11 * 12 * Common functions for media-related drivers to register and unregister media 13 * device nodes. 14 */ 15 16 #ifndef _MEDIA_DEVNODE_H 17 #define _MEDIA_DEVNODE_H 18 19 #include <linux/poll.h> 20 #include <linux/fs.h> 21 #include <linux/device.h> 22 #include <linux/cdev.h> 23 #include <linux/debugfs.h> 24 25 struct media_device; 26 27 /* debugfs top-level media directory */ 28 extern struct dentry *media_debugfs_root; 29 30 /* 31 * Flag to mark the media_devnode struct as registered. Drivers must not touch 32 * this flag directly, it will be set and cleared by media_devnode_register and 33 * media_devnode_unregister. 34 */ 35 #define MEDIA_FLAG_REGISTERED 0 36 37 /** 38 * struct media_file_operations - Media device file operations 39 * 40 * @owner: should be filled with %THIS_MODULE 41 * @read: pointer to the function that implements read() syscall 42 * @write: pointer to the function that implements write() syscall 43 * @poll: pointer to the function that implements poll() syscall 44 * @ioctl: pointer to the function that implements ioctl() syscall 45 * @compat_ioctl: pointer to the function that will handle 32 bits userspace 46 * calls to the ioctl() syscall on a Kernel compiled with 64 bits. 47 * @open: pointer to the function that implements open() syscall 48 * @release: pointer to the function that will release the resources allocated 49 * by the @open function. 50 */ 51 struct media_file_operations { 52 struct module *owner; 53 ssize_t (*read) (struct file *, char __user *, size_t, loff_t *); 54 ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *); 55 __poll_t (*poll) (struct file *, struct poll_table_struct *); 56 long (*ioctl) (struct file *, unsigned int, unsigned long); 57 long (*compat_ioctl) (struct file *, unsigned int, unsigned long); 58 int (*open) (struct file *); 59 int (*release) (struct file *); 60 }; 61 62 /** 63 * struct media_devnode - Media device node 64 * @media_dev: pointer to struct &media_device 65 * @fops: pointer to struct &media_file_operations with media device ops 66 * @dev: pointer to struct &device containing the media controller device 67 * @cdev: struct cdev pointer character device 68 * @parent: parent device 69 * @minor: device node minor number 70 * @flags: flags, combination of the ``MEDIA_FLAG_*`` constants 71 * @release: release callback called at the end of ``media_devnode_release()`` 72 * routine at media-device.c. 73 * 74 * This structure represents a media-related device node. 75 * 76 * The @parent is a physical device. It must be set by core or device drivers 77 * before registering the node. 78 */ 79 struct media_devnode { 80 struct media_device *media_dev; 81 82 /* device ops */ 83 const struct media_file_operations *fops; 84 85 /* sysfs */ 86 struct device dev; /* media device */ 87 struct cdev cdev; /* character device */ 88 struct device *parent; /* device parent */ 89 90 /* device info */ 91 int minor; 92 unsigned long flags; /* Use bitops to access flags */ 93 94 /* callbacks */ 95 void (*release)(struct media_devnode *devnode); 96 }; 97 98 /* dev to media_devnode */ 99 #define to_media_devnode(cd) container_of(cd, struct media_devnode, dev) 100 101 /** 102 * media_devnode_register - register a media device node 103 * 104 * @mdev: struct media_device we want to register a device node 105 * @devnode: media device node structure we want to register 106 * @owner: should be filled with %THIS_MODULE 107 * 108 * The registration code assigns minor numbers and registers the new device node 109 * with the kernel. An error is returned if no free minor number can be found, 110 * or if the registration of the device node fails. 111 * 112 * Zero is returned on success. 113 * 114 * Note that if the media_devnode_register call fails, the release() callback of 115 * the media_devnode structure is *not* called, so the caller is responsible for 116 * freeing any data. 117 */ 118 int __must_check media_devnode_register(struct media_device *mdev, 119 struct media_devnode *devnode, 120 struct module *owner); 121 122 /** 123 * media_devnode_unregister_prepare - clear the media device node register bit 124 * @devnode: the device node to prepare for unregister 125 * 126 * This clears the passed device register bit. Future open calls will be met 127 * with errors. Should be called before media_devnode_unregister() to avoid 128 * races with unregister and device file open calls. 129 * 130 * This function can safely be called if the device node has never been 131 * registered or has already been unregistered. 132 */ 133 void media_devnode_unregister_prepare(struct media_devnode *devnode); 134 135 /** 136 * media_devnode_unregister - unregister a media device node 137 * @devnode: the device node to unregister 138 * 139 * This unregisters the passed device. Future open calls will be met with 140 * errors. 141 * 142 * Should be called after media_devnode_unregister_prepare() 143 */ 144 void media_devnode_unregister(struct media_devnode *devnode); 145 146 /** 147 * media_devnode_data - returns a pointer to the &media_devnode 148 * 149 * @filp: pointer to struct &file 150 */ 151 static inline struct media_devnode *media_devnode_data(struct file *filp) 152 { 153 return filp->private_data; 154 } 155 156 /** 157 * media_devnode_is_registered - returns true if &media_devnode is registered; 158 * false otherwise. 159 * 160 * @devnode: pointer to struct &media_devnode. 161 * 162 * Note: If mdev is NULL, it also returns false. 163 */ 164 static inline int media_devnode_is_registered(struct media_devnode *devnode) 165 { 166 if (!devnode) 167 return false; 168 169 return test_bit(MEDIA_FLAG_REGISTERED, &devnode->flags); 170 } 171 172 #endif /* _MEDIA_DEVNODE_H */ 173