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