1 /**************************************************************************** 2 * include/fs/fs.h 3 * 4 * Copyright (C) 2007-2009, 2011-2013, 2015-2018 Gregory Nutt. All rights 5 * reserved. 6 * Author: Gregory Nutt <gnutt@nuttx.org> 7 * 8 * Redistribution and use in source and binary forms, with or without 9 * modification, are permitted provided that the following conditions 10 * are met: 11 * 12 * 1. Redistributions of source code must retain the above copyright 13 * notice, this list of conditions and the following disclaimer. 14 * 2. Redistributions in binary form must reproduce the above copyright 15 * notice, this list of conditions and the following disclaimer in 16 * the documentation and/or other materials provided with the 17 * distribution. 18 * 3. Neither the name NuttX nor the names of its contributors may be 19 * used to endorse or promote products derived from this software 20 * without specific prior written permission. 21 * 22 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 23 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 24 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 25 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 26 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 27 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 28 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 29 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 30 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 32 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 33 * POSSIBILITY OF SUCH DAMAGE. 34 * 35 ****************************************************************************/ 36 37 #ifndef _FS_DRIVER_H_ 38 #define _FS_DRIVER_H_ 39 40 #include <sys/stat.h> 41 #include "vnode.h" 42 #include "fs/file.h" 43 44 #ifdef __cplusplus 45 #if __cplusplus 46 extern "C" { 47 #endif /* __cplusplus */ 48 #endif /* __cplusplus */ 49 50 /* This structure provides information about the state of a block driver */ 51 52 struct geometry 53 { 54 bool geo_available; /* true: The device is available */ 55 bool geo_mediachanged; /* true: The media has changed since last query */ 56 bool geo_writeenabled; /* true: It is okay to write to this device */ 57 unsigned long long geo_nsectors; /* Number of sectors on the device */ 58 size_t geo_sectorsize; /* Size of one sector */ 59 }; 60 61 /* This structure is provided by block devices when they register with the 62 * system. It is used by file systems to perform filesystem transfers. It 63 * differs from the normal driver vtable in several ways -- most notably in 64 * that it deals in struct Vnode vs. struct filep. 65 */ 66 67 struct block_operations 68 { 69 int (*open)(struct Vnode *vnode); 70 int (*close)(struct Vnode *vnode); 71 ssize_t (*read)(struct Vnode *vnode, unsigned char *buffer, 72 unsigned long long start_sector, unsigned int nsectors); 73 ssize_t (*write)(struct Vnode *vnode, const unsigned char *buffer, 74 unsigned long long start_sector, unsigned int nsectors); 75 int (*geometry)(struct Vnode *vnode, struct geometry *geometry); 76 int (*ioctl)(struct Vnode *vnode, int cmd, unsigned long arg); 77 int (*unlink)(struct Vnode *vnode); 78 }; 79 80 struct drv_data 81 { 82 const void *ops; 83 mode_t mode; 84 void *priv; 85 }; 86 87 /**************************************************************************** 88 * Name: register_driver 89 * 90 * Description: 91 * Register a character driver vnode the pseudo file system. 92 * 93 * Input Parameters: 94 * path - The path to the vnode to create 95 * fops - The file operations structure 96 * mode - Access privileges (not used) 97 * priv - Private, user data that will be associated with the vnode. 98 * 99 * Returned Value: 100 * Zero on success (with the vnode point in 'vnode'); A negated errno 101 * value is returned on a failure (all error values returned by 102 * vnode_reserve): 103 * 104 * EINVAL - 'path' is invalid for this operation 105 * EEXIST - An vnode already exists at 'path' 106 * ENOMEM - Failed to allocate in-memory resources for the operation 107 * 108 * Attention: 109 * This function should be called after los_vfs_init has been called. 110 * The parameter path must point a valid string, which end with the terminating null byte. 111 * The total length of parameter path must less than the value defined by PATH_MAX. 112 * The prefix of the parameter path must be /dev/. 113 * The fops must pointed the right functions, otherwise the system will crash when the device is being operated. 114 * 115 ****************************************************************************/ 116 117 int register_driver(const char *path, 118 const struct file_operations_vfs *fops, mode_t mode, 119 void *priv); 120 121 /**************************************************************************** 122 * Name: register_blockdriver 123 * 124 * Description: 125 * Register a block driver vnode the pseudo file system. 126 * 127 * Attention: 128 * This function should be called after los_vfs_init has been called. 129 * The parameter path must point a valid string, which end with the terminating null byte. 130 * The length of parameter path must be less than the value defined by PATH_MAX. 131 * The prefix of the parameter path must be '/dev/'. 132 * The bops must pointed the right functions, otherwise the system will crash when the device is being operated. 133 * 134 * Input Parameters: 135 * path - The path to the vnode to create 136 * bops - The block driver operations structure 137 * mode - Access privileges (not used) 138 * priv - Private, user data that will be associated with the vnode. 139 * 140 * Returned Value: 141 * Zero on success (with the vnode point in 'vnode'); A negated errno 142 * value is returned on a failure (all error values returned by 143 * vnode_reserve): 144 * 145 * EINVAL - 'path' is invalid for this operation 146 * EEXIST - An vnode already exists at 'path' 147 * ENOMEM - Failed to allocate in-memory resources for the operation 148 * 149 ****************************************************************************/ 150 151 int register_blockdriver(const char *path, 152 const struct block_operations *bops, 153 mode_t mode, void *priv); 154 155 /**************************************************************************** 156 * Name: unregister_driver 157 * 158 * Description: 159 * Remove the character driver vnode at 'path' from the pseudo-file system 160 * 161 * Returned Value: 162 * Zero on success (with the vnode point in 'vnode'); A negated errno 163 * value is returned on a failure (all error values returned by 164 * vnode_reserve): 165 * 166 * EBUSY - Resource is busy ,not permit for this operation. 167 * ENOENT - 'path' is invalid for this operation. 168 * 169 * Attention: 170 * This function should be called after register_blockdriver has been called. 171 * The parameter path must point a valid string, which end with the terminating null byte. 172 * The total length of parameter path must less than the value defined by PATH_MAX. 173 * The block device node referred by parameter path must be really exist. 174 ****************************************************************************/ 175 176 int unregister_driver(const char *path); 177 178 /**************************************************************************** 179 * Name: unregister_blockdriver 180 * 181 * Description: 182 * Remove the block driver vnode at 'path' from the pseudo-file system 183 * 184 * Input Parameters: 185 * path - The path that the vnode to be destroyed. 186 * 187 * Returned Value: 188 * Zero on success (with the vnode point in 'vnode'); A negated errno 189 * value is returned on a failure (all error values returned by 190 * vnode_reserve): 191 * 192 * EBUSY - Resource is busy ,not permit for this operation. 193 * ENOENT - 'path' is invalid for this operation. 194 * 195 * Attention: 196 * This function should be called after register_blockdriver has been called. 197 * The parameter path must point a valid string, which end with the terminating null byte. 198 * The total length of parameter path must less than the value defined by PATH_MAX. 199 * The block device node referred by parameter path must be really exist. 200 * 201 ****************************************************************************/ 202 203 int unregister_blockdriver(const char *path); 204 205 206 /**************************************************************************** 207 * Name: open_blockdriver 208 * 209 * Description: 210 * Return the vnode of the block driver specified by 'pathname' 211 * 212 * Input Parameters: 213 * pathname - the full path to the block driver to be opened 214 * mountflags - if MS_RDONLY is not set, then driver must support write 215 * operations (see include/sys/mount.h) 216 * ppvnode - address of the location to return the vnode reference 217 * 218 * Returned Value: 219 * Returns zero on success or a negated errno on failure: 220 * 221 * EINVAL - pathname or pvnode is NULL 222 * ENOENT - No block driver of this name is registered 223 * ENOTBLK - The vnode associated with the pathname is not a block driver 224 * EACCESS - The MS_RDONLY option was not set but this driver does not 225 * support write access 226 * 227 * Aattention: 228 * The parameter path must point a valid string, which end with the terminating null byte. 229 * The total length of parameter path must less than the value defined by PATH_MAX. 230 * The parameter ppvnode must point a valid memory, which size must be enough for storing struct Vnode. 231 232 ****************************************************************************/ 233 234 #if CONFIG_NFILE_DESCRIPTORS > 0 235 int open_blockdriver(const char *pathname, int mountflags, 236 struct Vnode **ppvnode); 237 #endif 238 239 /**************************************************************************** 240 * Public Function Prototypes 241 ****************************************************************************/ 242 243 /**************************************************************************** 244 * Name: find_blockdriver 245 * 246 * Description: 247 * Return the inode of the block driver specified by 'pathname' 248 * 249 * Input Parameters: 250 * pathname - The full path to the block driver to be located 251 * mountflags - If MS_RDONLY is not set, then driver must support write 252 * operations (see include/sys/mount.h) 253 * ppinode - Address of the location to return the inode reference 254 * 255 * Returned Value: 256 * Returns zero on success or a negated errno on failure: 257 * 258 * ENOENT - No block driver of this name is registered 259 * ENOTBLK - The inode associated with the pathname is not a block driver 260 * EACCESS - The MS_RDONLY option was not set but this driver does not 261 * support write access 262 * 263 ****************************************************************************/ 264 265 int find_blockdriver(const char *pathname, int mountflags, 266 struct Vnode **vpp); 267 268 269 /**************************************************************************** 270 * Name: close_blockdriver 271 * 272 * Description: 273 * Call the close method and release the vnode 274 * 275 * Input Parameters: 276 * vnode - reference to the vnode of a block driver opened by open_blockdriver 277 * 278 * Returned Value: 279 * Returns zero on success or a negated errno on failure: 280 * 281 * EINVAL - vnode is NULL 282 * ENOTBLK - The vnode is not a block driver 283 * 284 * Attention: 285 * This function should be called after open_blockdriver has been called. 286 * 287 ****************************************************************************/ 288 289 #if CONFIG_NFILE_DESCRIPTORS > 0 290 int close_blockdriver(struct Vnode *vnode); 291 #endif 292 293 #ifdef __cplusplus 294 #if __cplusplus 295 } 296 #endif /* __cplusplus */ 297 #endif /* __cplusplus */ 298 #endif /* _FS_DRIVER_H_ */ 299