source: trunk/kernel/fs/vfs.h

Last change on this file was 683, checked in by alain, 6 years ago

All modifications required to support the <tcp_chat> application
including error recovery in case of packet loss.A
File size: 61.0 KB
Line 
1/*
2 * vfs.h - Virtual File System definition.
3 *
4 * Author Mohamed Lamine Karaoui (2014,2015)
5 * Alain Greiner (2016,2017,2018,2019,2020)
6 *
7 * Copyright (c) UPMC Sorbonne Universites
8 *
9 * This file is part of ALMOS-MKH.
10 *
11 * ALMOS-MKH is free software; you can redistribute it and/or modify it
12 * under the terms of the GNU General Public License as published by
13 * the Free Software Foundation; version 2.0 of the License.
14 *
15 * ALMOS-MKH is distributed in the hope that it will be useful, but
16 * WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 * General Public License for more details.
19 *
20 * You should have received a copy of the GNU General Public License
21 * along with ALMOS-MKH; if not, write to the Free Software Foundation,
22 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
23 */
24
25#ifndef _VFS_H_
26#define _VFS_H_
27
28#include <kernel_config.h>
29#include <hal_kernel_types.h>
30#include <hal_atomic.h>
31#include <remote_rwlock.h>
32#include <remote_busylock.h>
33#include <busylock.h>
34#include <list.h>
35#include <xlist.h>
36#include <bits.h>
37#include <xhtab.h>
38#include <errno.h>
39#include <shared_syscalls.h>
40#include <fatfs.h>
41#include <ramfs.h>
42#include <devfs.h>
43#include <dev_ioc.h>
44
45/**** Forward declarations ***/
46
47struct vfs_inode_s;
48struct vfs_dentry_s;
49struct vfs_ctx_s;
50struct vfs_file_s;
51struct remote_buf_s;
52struct mapper_s;
53struct process_s;
54struct device_s;
55struct vseg_s;
56struct page_s;
57struct ksock_s;
58
59/******************************************************************************************
60 * These flags are used to define the working mode of the vfs_lookup() function.
61 *****************************************************************************************/
62
63#define VFS_LOOKUP_DIR 0x01 /* the searched inode must be a directory */
64#define VFS_LOOKUP_OPEN 0x02 /* the search is for an open/opendir */
65#define VFS_LOOKUP_PARENT 0x04 /* return the parent inode (not the inode itself) */
66#define VFS_LOOKUP_CREATE 0x10 /* file must be created if missing */
67#define VFS_LOOKUP_EXCL 0x20 /* file cannot previously exist */
68
69
70
71
72/******************************************************************************************
73 * This structure defines a VFS context, that contains informations common to all inodes
74 * and dentries for a given file system. As it is declared as a global variable in the
75 * kdata segment (fs_context[] array), it is replicated in all clusters.
76 * The <extend> field is a pointer on the FS specific context extension.
77 * This extension is dynamically allocated by kernel_init in all clusters.
78 * In each cluster, the inum allocator can be accessed by any thread runing
79 * in any cluster, and is therefore protected by a remote_busylock.
80 *****************************************************************************************/
81
82typedef enum
83{
84 FS_TYPE_RAMFS = 0,
85 FS_TYPE_DEVFS = 1,
86 FS_TYPE_FATFS = 2,
87
88 FS_TYPES_NR = 3,
89}
90vfs_fs_type_t;
91
92typedef enum
93{
94 CTX_ATTR_READ_ONLY = 0x01, /*! write access prohibited */
95 CTX_ATTR_SYNC = 0x10, /*! synchronise FS on each write */
96}
97vfs_ctx_attr_t;
98
99typedef struct vfs_ctx_s
100{
101 vfs_fs_type_t type; /*! File System type */
102 uint32_t total_clusters; /*! total number of clusters on device */
103 uint32_t cluster_size; /*! cluster size on device (bytes) */
104 xptr_t vfs_root_xp; /*! extended pointer on VFS root inode */
105 remote_busylock_t lock; /*! lock protecting inum allocator */
106 uint32_t bitmap[BITMAP_SIZE(CONFIG_VFS_MAX_INODES)]; /* inum allocator */
107 void * extend; /*! FS specific context extension */
108}
109vfs_ctx_t;
110
111/******************************************************************************************
112 * These functions access / modify a VFS context.
113 *****************************************************************************************/
114
115/******************************************************************************************
116 * This function initialises a (statically allocated) VFS context in cluster identified
117 * by the <cxy> argument.
118 * It is called by the kernel_init() function.
119 ******************************************************************************************
120 * @ cxy : target cluster identifier.
121 * @ fs_type : file system type.
122 * @ total_clusters : total number of clusters on device.
123 * @ cluster_size : cluster size on device (bytes).
124 * @ vfs_root_xp : extended pointer on VFS root inode.
125 * @ extend : fs_type_specific extension.
126 *****************************************************************************************/
127void vfs_ctx_init( cxy_t cxy,
128 vfs_fs_type_t type,
129 uint32_t total_clusters,
130 uint32_t cluster_size,
131 xptr_t vfs_root_xp,
132 void * extend );
133
134/******************************************************************************************
135 * This function allocates an inode identifier from the local cluster inum allocator.
136 * The inum respects a fixed format:
137 * - the 16 MSB bits contain the cluster identifier : cxy
138 * - the 16 LSB bits contains the local inode identifier : lid
139 ******************************************************************************************
140 * @ ctx_xp : [in] extended pointer on file system context.
141 * @ inum : [out] buffer for allocated inode identifier.
142 * @ return 0 if success / return non-zero if error.
143 *****************************************************************************************/
144error_t vfs_ctx_inum_alloc( xptr_t ctx_xp,
145 uint32_t * inum );
146
147/******************************************************************************************
148 * This function release an inode identifier.
149 ******************************************************************************************
150 * @ ctx_xp : [in] extended pointer on file system context.
151 * @ inum : [in] released inode identifier.
152 *****************************************************************************************/
153void vfs_ctx_inum_release( xptr_t ctx_xp,
154 uint32_t inum );
155
156
157
158
159
160
161/******************************************************************************************
162 * This file structure describes an open file/directory for a given process.
163 * It is not replicated, and is dynamically allocated in the cluster that contains
164 * the associated inode / socket / pipe , when a thread makes an open(), opendir(),
165 * socket(), or pipe() system call. It cannot exist a <file> structure without a
166 * a <mapper>, <socket>, or <pipe> structure (depending on type) in same cluster.
167 * It can exist a <file> structure without an <inode> (for PIPE and SOCK types).
168 *****************************************************************************************/
169
170/* this enum define the VFS file types */
171/* WARNING : this enum must be kept consistent with macros in <shared_stat.h> file */
172/* and with types in <shared_dirent.h> file. */
173
174typedef enum
175{
176 FILE_TYPE_REG = 0, /*! regular file */
177 FILE_TYPE_DIR = 1, /*! directory */
178 FILE_TYPE_FIFO = 2, /*! POSIX named fifo */
179 FILE_TYPE_PIPE = 3, /*! POSIX anonymous pipe */
180 FILE_TYPE_SOCK = 4, /*! POSIX anonymous socket */
181 FILE_TYPE_DEV = 5, /*! character device */
182 FILE_TYPE_BLK = 6, /*! block device */
183 FILE_TYPE_SYML = 7, /*! symbolic link */
184}
185vfs_file_type_t;
186
187typedef enum
188{
189 FD_ATTR_READ_ENABLE = 0x01, /*! read access possible */
190 FD_ATTR_WRITE_ENABLE = 0x02, /*! write access possible */
191 FD_ATTR_APPEND = 0x04, /*! append on each write */
192 FD_ATTR_CLOSE_EXEC = 0x08, /*! close file on exec */
193 FD_ATTR_SYNC = 0x10, /*! synchronise FS on each write */
194 FD_ATTR_IS_DIR = 0x20, /*! this is a directory */
195}
196vfs_file_attr_t;
197
198typedef struct vfs_file_s
199{
200 struct vfs_ctx_s * ctx; /*! local pointer on FS context. */
201 vfs_file_attr_t attr; /*! file attributes bit vector (see above) */
202 vfs_file_type_t type; /*! same type as inode */
203 uint32_t offset; /*! seek position in file */
204 remote_rwlock_t lock; /*! protect offset modifications */
205 struct vfs_inode_s * inode; /*! local pointer on associated inode */
206 struct mapper_s * mapper; /*! associated mapper (REG or DIR types only) */
207 struct socket_s * socket; /*! associated socket (SOCK type only) */
208 struct pipe_s * pipe; /*! associated pipe (FIFO or PIPE types only) */
209 void * extend; /*! FS specific extension */
210}
211vfs_file_t;
212
213/******************************************************************************************
214 * These low-level functions access / modify a VFS file descriptor
215 *****************************************************************************************/
216
217/******************************************************************************************
218 * This function allocates memory and initializes a new file descriptor in the
219 * cluster defined by the <inode_xp> argument.
220 * It can be called by any thread running in any cluster.
221 ******************************************************************************************
222 * @ inode_xp : [in] extended pointer on associated inode.
223 * @ attr : [in] file descriptor attributes.
224 * @ file_xp : [out] buffer for extended pointer on created file descriptor.
225 * @ return 0 if success / return ENOMEM if error.
226 *****************************************************************************************/
227error_t vfs_file_create( xptr_t inode_xp,
228 uint32_t attr,
229 xptr_t * file_xp );
230
231/******************************************************************************************
232 * This function releases memory allocated to file descriptor identified
233 * by the <file_xp> argument.
234 * It can be called by any thread running in any cluster.
235 ******************************************************************************************
236 * @ file_xp : [in] extended pointer on file descriptor.
237 *****************************************************************************************/
238void vfs_file_destroy( xptr_t file_xp );
239
240/******************************************************************************************
241 * This debug function copies the name of a the file identified by <file_xp>
242 * argument to a local buffer identified by the <name> argument.
243 * The local buffer size must be at least CONFIG_VFS_MAX_NAME_LENGTH.
244 *****************************************************************************************
245 * @ ionde_xp : [in] extended pointer on the remote inode.
246 * @ name : [out] local string.
247 ***************************************************************************************/
248void vfs_file_get_name( xptr_t inode_xp,
249 char * name );
250
251
252
253
254/******************************************************************************************
255 * This structure define a VFS inode.
256 * An inode can have several children dentries (if it is a directory), an can have several
257 * parents dentries (if it has several aliases links):
258 * - The "parents" field is the root of the xlist of parents dentries, and the "links"
259 * fiels define the number of aliases parent dentries. only a FILE inode can have
260 * several parents (no hard links for directories).
261 * - The "children" field is an embedded xhtab containing pointers on all local children
262 * dentries. This set of children is empty for a FILE inode.
263 * Synchronisation:
264 * - the main_lock (remote_rwlock) is used during the inode tree traversal,
265 * or for inode modification (add/remove children in xhtab).
266 * - the size_lock (remote_rwlock) is used during read/write accesses to the size
267 * field in the mapper.
268 * - access to the data stored in the associated mapper use the mapper remote_rwlock
269 * protecting radix tree traversal and modifications.
270 *****************************************************************************************/
271
272/* this enum define the VFS inode attributes values */
273
274typedef enum
275{
276 INODE_ATTR_DIRTY = 0x01, /*! modified versus the value on device */
277 INODE_ATTR_INLOAD = 0x04, /*! loading from device in progress */
278 INODE_ATTR_NEW = 0x08, /*! not saved on device yet */
279}
280vfs_inode_attr_t;
281
282typedef struct vfs_inode_s
283{
284 struct vfs_ctx_s * ctx; /*! local pointer on FS context */
285 uint32_t inum; /*! inode identifier (unique in file system) */
286 uint32_t attr; /*! inode attributes (see above) */
287 vfs_file_type_t type; /*! inode type (see vfs_file_t) */
288 uint32_t size; /*! number of bytes */
289 uint32_t uid; /*! user owner identifier */
290 uint32_t gid; /*! group owner identifier */
291 uint32_t rights; /*! access rights */
292 xlist_entry_t parents; /*! root of list of parents dentries */
293 uint32_t links; /*! number of parent dentries (hard links) */
294 xhtab_t children; /*! embedded xhtab of children dentries */
295 remote_rwlock_t size_lock; /*! protect read/write to size */
296 remote_rwlock_t main_lock; /*! protect inode tree traversal and modifs */
297 struct mapper_s * mapper; /*! associated file (REG or DIR types only) */
298 struct remote_buf_s * pipe; /*! associated pipe (FIFO type only) */
299 void * extend; /*! fs_type_specific inode extension */
300}
301vfs_inode_t;
302
303/* This define the masks for the inode <rights> field */
304
305#define VFS_ISUID 0x0004000
306#define VFS_ISGID 0x0002000
307#define VFS_ISVTX 0x0001000
308
309#define VFS_IRWXU 0x0000700
310#define VFS_IRUSR 0x0000400
311#define VFS_IWUSR 0x0000200
312#define VFS_IXUSR 0x0000100
313
314#define VFS_IRWXG 0x0000070
315#define VFS_IRGRP 0x0000040
316#define VFS_IWGRP 0x0000020
317#define VFS_IXGRP 0x0000010
318
319#define VFS_IRWXO 0x0000007
320#define VFS_IROTH 0x0000004
321#define VFS_IWOTH 0x0000002
322#define VFS_IXOTH 0x0000001
323
324/******************************************************************************************
325 * These low-level functions access / modify a VFS inode descriptor
326 *****************************************************************************************/
327
328/******************************************************************************************
329 * This function returns a printable string for the inode type.
330 *****************************************************************************************/
331const char * vfs_inode_type_str( vfs_file_type_t type );
332
333/******************************************************************************************
334 * This function allocates memory in cluster identified by the <cxy> argument
335 * for an inode descriptor and for the associated mapper, and partially initialise
336 * this inode from arguments values.
337 * It does NOT link it to the Inode Tree, as this is done by add_child_in_parent().
338 * It can be called by any thread running in any cluster.
339 ******************************************************************************************
340 * @ cxy : [in] target cluster identifier
341 * @ fs_type : [in] file system type.
342 * @ attr : [in] inode attributes.
343 * @ rights : [in] inode access rights.
344 * @ uid : [in] user owner ID.
345 * @ gid : [in] group owner ID.
346 * @ inode_xp : [out] buffer for extended pointer on created inode.
347 * @ return 0 if success / return -1 if error.
348 *****************************************************************************************/
349error_t vfs_inode_create( cxy_t cxy,
350 vfs_fs_type_t fs_type,
351 uint32_t attr,
352 uint32_t rights,
353 uid_t uid,
354 gid_t gid,
355 xptr_t * inode_xp );
356
357/******************************************************************************************
358 * This function releases memory allocated to an inode descriptor, including
359 * all memory allocated to the mapper (both mapper descriptor and radix tree).
360 * The mapper should not contain any dirty page (should be synchronized before deletion).
361 * It can be called by any thread running in any cluster.
362 ******************************************************************************************
363 * @ inode_xp : extended pointer on inode descriptor.
364 *****************************************************************************************/
365void vfs_inode_destroy( xptr_t inode_xp );
366
367/******************************************************************************************
368 * This function returns the <size> of a file/dir from a remote inode,
369 * taking the remote_rwlock protecting <size> in READ_MODE.
370 * It can be called by any thread running in any cluster.
371 *****************************************************************************************
372 * @ inode_xp : extended pointer on the remote inode.
373 * @ return the current size.
374 *****************************************************************************************/
375uint32_t vfs_inode_get_size( xptr_t inode_xp );
376
377/******************************************************************************************
378 * This function updates the "size" field of a remote inode identified by <inode_xp>.
379 * It takes the rwlock protecting the file size in WRITE_MODE, and set the "size" field
380 * when the current size is smaller than the requested <size> argument.
381 * It can be called by any thread running in any cluster.
382 *****************************************************************************************
383 * @ inode_xp : extended pointer on the remote inode.
384 * @ size : requested size value.
385 *****************************************************************************************/
386void vfs_inode_update_size( xptr_t inode_xp,
387 uint32_t size );
388
389/******************************************************************************************
390 * This function takes the main lock of a remote inode identified by the <inode_xp>.
391 * This lock protect all inode fields, including the children dentries.
392 * It can be called by any thread running in any cluster.
393 *****************************************************************************************
394 * @ inode_xp : extended pointer on the remote inode.
395 *****************************************************************************************/
396void vfs_inode_lock( xptr_t inode_xp );
397
398/******************************************************************************************
399 * This function releases the main lock of a remote inode identified by <inode_xp>.
400 * This lock protect all inode fiels, including the children dentries.
401 * It can be called by any thread running in any cluster.
402 *****************************************************************************************
403 * @ inode_xp : extended pointer on the remote inode.
404 *****************************************************************************************/
405void vfs_inode_unlock( xptr_t inode_xp );
406
407/******************************************************************************************
408 * This debug function copies the name of a remote inode identified by the <inode_xp>
409 * argument to a local buffer identified by the <name> argument.
410 * The local buffer size must be at least CONFIG_VFS_MAX_NAME_LENGTH.
411 * It can be called by any thread running in any cluster.
412 ******************************************************************************************
413 * @ inode_xp : extended pointer on the remote inode.
414 * @ name : local buffer pointer.
415 *****************************************************************************************/
416void vfs_inode_get_name( xptr_t inode_xp,
417 char * name );
418
419/******************************************************************************************
420 * This function accesses successively all pages of a file identified by the <inode_xp>,
421 * argument, to force misses, and load all pages into mapper.
422 * The target inode can be a directory or a file, but this function is mainly used
423 * to prefetch a complete directory to the mapper.
424 * This function does NOT take any lock.
425 * It can be called by any thread running in any cluster.
426 ******************************************************************************************
427 * @ inode_xp : extended pointer on inode.
428 * @ return 0 if success / return -1 if device access failure.
429 *****************************************************************************************/
430error_t vfs_inode_load_all_pages( xptr_t inode_xp );
431
432/******************************************************************************************
433 * This debug function display the curren state of an inode descriptor.
434 * It can be called by any thread running in any cluster.
435 *****************************************************************************************/
436void vfs_inode_display( xptr_t inode_xp );
437
438
439
440
441
442
443/******************************************************************************************
444 * This structure defines a directory entry.
445 * A dentry contains the name of a remote file/dir, an extended pointer on the
446 * inode representing this file/dir, a local pointer on the inode representing
447 * the parent directory.
448 * A dentry can be member of the set of children of a given directory inode (xhtab).
449 * A dentry can be member of the set of parents of a given inode (xlist).
450 *****************************************************************************************/
451
452typedef struct vfs_dentry_s
453{
454 struct vfs_ctx_s * ctx; /*! local pointer on FS context */
455 char name[CONFIG_VFS_MAX_NAME_LENGTH];
456 uint32_t length; /*! name length (bytes) */
457 struct vfs_inode_s * parent; /*! local pointer on parent inode */
458 xptr_t child_xp; /*! extended pointer on child inode */
459 xlist_entry_t children; /*! member of set of children dentries */
460 xlist_entry_t parents; /*! member of set of parent dentries */
461 void * extend; /*! FS specific extension */
462}
463vfs_dentry_t;
464
465/******************************************************************************************
466 * These low-level functions access / modify a VFS dentry descriptor
467 *****************************************************************************************/
468
469/******************************************************************************************
470 * This function allocates memory in cluster identified by the <cxy> argument
471 * for a dentry descriptor, initialises it from arguments values, and returns
472 * in <dentry_xp> the extended pointer on dentry.
473 * It can be called by any thread running in any cluster.
474 ******************************************************************************************
475 * @ cxy : [in] target cluster identifier
476 * @ fs_type : [in] file system type.
477 * @ name : [in] directory entry file/dir name.
478 * @ dentry_xp : [out] buffer for extended pointer on created dentry.
479 * @ return 0 if success / return ENOMEM or EINVAL if error.
480 *****************************************************************************************/
481error_t vfs_dentry_create( cxy_t cxy,
482 vfs_fs_type_t fs_type,
483 char * name,
484 xptr_t * dentry_xp );
485
486/******************************************************************************************
487 * This function removes the dentry from the parent inode xhtab, and releases the memory
488 * allocated to the dentry descriptor.
489 * It can be called by any thread running in any cluster.
490 ******************************************************************************************
491 * @ dentry_xp : [in] extended pointer on dentry descriptor.
492 *****************************************************************************************/
493void vfs_dentry_destroy( xptr_t dentry_xp );
494
495
496
497
498
499
500
501
502/******************************************************************************************
503 * These functions access / modify the distributed VFS Inode Tree
504 *****************************************************************************************/
505
506/******************************************************************************************
507 * This function returns in a kernel <buffer> allocated by the caller function,
508 * the pathname of a file/dir identified by the <inode_xp> argument.
509 * It traverse the Inode Tree from the target node to the root.
510 * It can be called by any thread running in any cluster.
511 * As this buffer if filled in "reverse order" (i.e. from the target inode to the root),
512 * the pathname is stored in the higher part of the buffer.
513 * A pointer on the first character of the pathname is returned in <first> buffer.
514 *
515 * WARNING : This function takes & releases the remote_rwlock protecting the Inode Tree.
516 ******************************************************************************************
517 * @ inode_xp : [in] extended pointer on target inode descriptor.
518 * @ buffer : [in] kernel buffer for pathname (allocated by caller).
519 * @ first : [out] pointer on first character in buffer.
520 * @ max_size : [in] max number of characters in buffer.
521 * @ return 0 if success / return EINVAL if buffer too small.
522 *****************************************************************************************/
523error_t vfs_get_path( xptr_t inode_xp,
524 char * buffer,
525 char ** first,
526 uint32_t max_size );
527
528/******************************************************************************************
529 * This function traverses the the Inode Tree, from inode identified by the <root_xp>
530 * argument, and returns in <inode_xp> the inode identified by the < pathname> argument.
531 * It can be called by a thread running in any cluster.
532 * It supports the following flags that define the lookup modes :
533 * - VFS_LOOKUP_DIR : the searched inode must be a directory
534 * - VFS_LOOKUP_OPEN : the search is for an open/opendir
535 * - VFS_LOOKUP_PARENT : return the parent inode (not the inode itself)
536 * - VFS_LOOKUP_CREATE : file/directory must be created if missing on IOC
537 * - VFS_LOOKUP_EXCL : file cannot previously exist
538 * As the inode Tree is a cache, the search policy is the following :
539 * - If a given directory name in the path is not found in the inode tree, it try to load
540 * the missing dentry/inode couple, from informations found in the parent directory.
541 * - If this directory entry does not exist on IOC, it returns an error.
542 * - If the file identified by the pathname does not exist on IOC but the
543 * flag CREATE is set, the inode is created. It returns an error otherwise.
544 * - If the the file identified by the pathname exist on device, but both flags EXCL
545 * and CREATE are set, an error is returned.
546 * - If the PARENT flag is set, it returns in <inode_xp> an extended pointer on the parent
547 * inode, and copies in <last_name> buffer a string containing the last name in path.
548 *
549 * WARNING : The lock protecting the Inode Tree must be taken in read mode by the caller.
550 *
551 * TODO the access rights are not checked yet.
552 ******************************************************************************************
553 * @ root_xp : [in] extended pointer on root inode (can be root of a subtree).
554 * @ pathname : [in] path (can be relative or absolute).
555 * @ lookup_mode : [in] flags defining the searching mode.
556 * @ inode_xp : [out] buffer for extended pointer on searched inode.
557 * @ last_name : [out] pointer on buffer for last name in path.
558 * @ return 0 if success / ENOENT if inode not found , EACCES if permisson denied,
559 *****************************************************************************************/
560error_t vfs_lookup( xptr_t root_xp,
561 char * pathname,
562 uint32_t lookup_mode,
563 xptr_t * inode_xp,
564 char * last_name );
565
566/******************************************************************************************
567 * This function creates a new couple dentry/inode, and insert it in the Inode-Tree.
568 * Only the distributed Inode-Tree is modified: it does NOT modify the parent mapper,
569 * and does NOT update the FS on IOC device.
570 * It set the inode type to the default FILE_TYPE_REG value.
571 * It can be executed by any thread running in any cluster (can be different from both
572 * the child cluster and the parent cluster).
573 * The new child inode and the parent inode can have different FS types.
574 *
575 * WARNING : The lock protecting the Inode Tree must be taken in write mode by the caller.
576 ******************************************************************************************
577 * Implementation note
578 * As there are cross-references between inode and dentry, this function implements
579 * a five steps scenario :
580 * 1) The dentry descriptor is created in the cluster containing the existing <parent_xp>
581 * inode, and partially initialized, using the RPC_VFS_CREATE DENTRY if required.
582 * 2) The inode and its associated mapper are created in cluster identified by <child_cxy>,
583 * and partially initialised, using the RPC_VFS_CREATE_INODE if required.
584 * 3) The pointers on dentry in parent inode are updated, using remote access.
585 * 4) The pointers on dentry in child inode are updated, using remotes access.
586 * 5) The pointers on parent and child inode in dentry are updated, using remotes access.
587 *****************************************************************************************
588 * @ child_inode_cxy : [in] target cluster for child inode.
589 * @ fs_type : [in] child inode FS type.
590 * @ parent_inode_xp : [in] extended pointer on parent inode.
591 * @ name : [in] new directory entry name.
592 * @ dentry_xp : [out] buffer for extended pointer on dentry
593 * @ child_inode_xp : [out] buffer for extended pointer on child inode.
594 * @ return 0 if success / -1 if dentry or inode cannot be created.
595 *****************************************************************************************/
596error_t vfs_add_child_in_parent( cxy_t child_inode_cxy,
597 vfs_fs_type_t fs_type,
598 xptr_t parent_inode_xp,
599 char * name,
600 xptr_t * dentry_xp,
601 xptr_t * child_inode_xp );
602
603/******************************************************************************************
604 * This function removes a remote dentry and the associated inode from the Inode-Tree.
605 * - It removes the dentry from the parent inode xhtab ("children" field), and from the
606 * child inode xlist ("parents" field).
607 * - It releases the memory allocated to the dentry descriptor.
608 * - If the number of parents of the child inode is one, it also releases the memory
609 * allocated to the child inode.
610 * Only the Inode Tree is modified: it does NOT modify the parent mapper,
611 * and does NOT update the FS on IOC device.
612 * It can be executed by any thread running in any cluster (can be different from both
613 * the inode cluster and the dentry cluster).
614 *
615 * WARNING : The lock protecting the Inode Tree must be taken in write mode by the caller.
616 ******************************************************************************************
617 * @ dentry_xp : extended pointer on removed dentry.
618 *****************************************************************************************/
619void vfs_remove_child_from_parent( xptr_t dentry_xp );
620
621/******************************************************************************************
622 * This function creates in the directory identified by the <child_inode_xp> argument,
623 * the two special dentries <.> and <..>. The parent directory inode is defined
624 * by the <parent_inode_xp> argument. The two dentries are introduced in the Inode Tree.
625 * They are also introduced in the child directory mapper, and the IOC device is updated.
626 * This function is called by all functions creating a brand new directory : vfs_mkdir(),
627 * devfs_global_init(), and devfs_local_init().
628 *
629 * WARNING : The lock protecting the Inode Tree must be taken in write mode by the caller.
630 ******************************************************************************************
631 * @ child_xp : extended pointer on new directory inode.
632 * @ parent_xp : extended pointer on parent directory inode.
633 * @ return 0 if success / -1 if failure.
634 *****************************************************************************************/
635error_t vfs_add_special_dentries( xptr_t child_inode_xp,
636 xptr_t parent_inode_xp );
637
638/******************************************************************************************
639 * This recursive function diplays a complete inode/dentry sub-tree.
640 * Any inode can be selected as the sub-tree root.
641 *
642 * TODO : this function should be protected against a concurrent Inode-Tree change.
643 ******************************************************************************************
644 * @ inode_xp : extended pointer on sub-tree root inode.
645 *****************************************************************************************/
646void vfs_display( xptr_t inode_xp );
647
648/******************************************************************************************
649 * This function mount a given file system type for a given process
650 * TODO non implemented [AG].
651 *****************************************************************************************/
652error_t vfs_mount_fs_root( struct device_s * device,
653 uint32_t fs_type,
654 struct process_s * process );
655
656
657
658
659/******************************************************************************************
660 * These functions define the VFS "syscalls" API (user commands)
661 *****************************************************************************************/
662
663/******************************************************************************************
664 * This function moves <size> bytes between a remote file mapper, identified by the
665 * <file_xp> argument, and a - possibly distributed - user space <buffer>, taken into
666 * account the offset in <file_xp>. The transfer direction is defined by <to_buffer>.
667 * It is called by the sys_read() and sys_write() functions.
668 * - for a read, it checks the actual file size (registered in the inode descriptor),
669 * against the (offset + count), and moves only the significant bytes.
670 * - for a write, it updates the the file size in inode descriptor if required.
671 * In case of write to the mapper, the "inode.size" field is updated as required.
672 ******************************************************************************************
673 * @ to_buffer : mapper -> buffer if true / buffer -> mapper if false.
674 * @ file_xp : extended pointer on the remote file descriptor.
675 * @ buffer : user space pointer on buffer (can be physically distributed).
676 * @ count : requested number of bytes from offset.
677 * @ returns number of bytes actually moved if success / -1 if error.
678 *****************************************************************************************/
679uint32_t vfs_user_move( bool_t to_buffer,
680 xptr_t file_xp,
681 void * buffer,
682 uint32_t count );
683
684/******************************************************************************************
685 * This function moves <size> bytes between a remote file mapper, identified by the
686 * <file_xp> argument, and a - possibly remote - kernel <buffer_xp>, taken into
687 * account the offset in <file_xp>. The transfer direction is defined by <to_buffer>.
688 * It is called by the elf_load_process() function.
689 ******************************************************************************************
690 * @ to_buffer : mapper -> buffer if true / buffer -> mapper if false.
691 * @ file_xp : extended pointer on the remote file descriptor.
692 * @ buffer_xp : user space pointer on buffer (can be physically distributed).
693 * @ size : requested number of bytes from offset.
694 * @ returns 0 if success / -1 if error.
695 *****************************************************************************************/
696error_t vfs_kernel_move( bool_t to_buffer,
697 xptr_t file_xp,
698 xptr_t buffer_xp,
699 uint32_t size );
700
701/******************************************************************************************
702 * This function allocates a vfs_file_t structure in the cluster containing the inode
703 * identified by the <root_xp> & <path> arguments.
704 * It initializes it, register it in the reference process fd_array identified by the
705 * <process_xp> argument, and returns both the extended pointer on the file descriptor,
706 * and the allocated index in the <file_xp> and <file_id> buffers.
707 * The pathname can be relative to current directory or absolute.
708 * If the inode does not exist in the inode cache, it try to find the file on the IOC
709 * device, and creates an inode on a pseudo randomly selected cluster if found.
710 * It the requested file does not exist on device, it creates a new inode if the
711 * O_CREAT flag is set, and return an error otherwise.
712 *
713 * WARNING : this function takes & releases the remote_rwlock protecting the Inode Tree.
714 ******************************************************************************************
715 * @ root_xp : extended pointer on path root inode.
716 * @ path : file pathname (absolute or relative to current directory).
717 * @ process_xp : extended pointer on client reference process.
718 * @ flags : defined in vfs_file_t structure.
719 * @ mode : access rights (as defined by chmod).
720 * @ file_xp : [out] buffer for extended pointer on created remote file descriptor.
721 * @ file_id : [out] buffer for created file descriptor index in reference fd_array.
722 * @ return 0 if success / return non-zero if error.
723 *****************************************************************************************/
724error_t vfs_open( xptr_t root_xp,
725 char * path,
726 xptr_t process_xp,
727 uint32_t flags,
728 uint32_t mode,
729 xptr_t * file_xp,
730 uint32_t * file_id );
731
732/******************************************************************************************
733 * This function set a new value in the offset of the open file descriptor <file_xp>.
734 * This value depends on the <whence> argument:
735 * - if VFS_SEEK_SET, new value is <offset>
736 * - if VFS_SEEK_CUR, new value is current_offset + <offset>
737 * - if VFS_SEEK_END, new value is file_size + <offset>
738 ******************************************************************************************
739 * @ file_xp : extended pointer on the remote open file descriptor.
740 * @ offset : local pointer on source kernel buffer.
741 * @ whence : VFS_SEEK_SET / VFS_SEEK_CUR / VFS_SEEK_END.
742 * @ new_offset : [out] buffer for new offset value.
743 * @ returns 0 if success / -1 if error.
744 *****************************************************************************************/
745error_t vfs_lseek( xptr_t file_xp,
746 uint32_t offset,
747 uint32_t whence,
748 uint32_t * new_offset );
749
750/******************************************************************************************
751 * This function close the - non-replicated - file descriptor identified by the <file_xp>
752 * and <file_id> arguments. The <file_id> is required to reset the fd_array[] slot.
753 * It can be called by a thread running in any cluster, and executes the following actions:
754 * 1) It access the block device to updates all dirty pages from the mapper associated
755 * to the file, and removes these pages from the dirty list, using an RPC if required.
756 * 2) It updates the file size in all parent directory mapper(s), and update the modified
757 * pages on the block device, using RPCs if required, only if the size is modified.
758 * 3) All entries in the fd_array copies are directly reset by the calling thread,
759 * using remote accesses.
760 * 4) The memory allocated to file descriptor in cluster containing the inode is released,
761 * using an RPC if cluster containing the file descriptor is remote.
762 ******************************************************************************************
763 * @ file_xp : extended pointer on the file descriptor.
764 * @ file_id : file descriptor index in fd_array[].
765 * @ returns 0 if success / -1 if error.
766 *****************************************************************************************/
767error_t vfs_close( xptr_t file_xp,
768 uint32_t file_id );
769
770/******************************************************************************************
771 * This function is called by the kernel to create in the file system a new directory
772 * identified by the <root_xp> & <path> arguments, with the access permission defined
773 * by the <rights> argument. All nodes in the path - but the last - must exist.
774 *
775 * WARNING : this function takes & releases the remote_rwlock protecting the Inode Tree.
776 ******************************************************************************************
777 * @ root_xp : extended pointer on path root inode (any inode in Inode Tree).
778 * @ path : pathname (absolute or relative to current directory).
779 * @ rights : access rights.
780 * @ returns 0 if success / -1 if error.
781 *****************************************************************************************/
782error_t vfs_mkdir( xptr_t root_xp,
783 char * path,
784 uint32_t rights );
785
786/******************************************************************************************
787 * This function is called by the kernel to create in the file system a new directory
788 * entry identified by the <new_root_xp> & <new_path> arguments, to be linked to an
789 * existing inode, identified by the <old_root_xp> & <old_path> arguments.
790 * If the link is successful, the link count of the target inode is incremented.
791 * The <new_path> and <old_path> share equal access rights to the underlying inode.
792 * Both the IOC device and the Inode Tree are modified.
793 $
794 * TODO This function should handle any type of node, but the current implementation
795 * handles only the FILE and DIR types.
796 *
797 * WARNING : this function takes & releases the remote_rwlock protecting the Inode Tree.
798 ******************************************************************************************
799 * @ old_root_xp : extended pointer on old path root inode (any inode in Inode Tree).
800 * @ old_path : old pathname (absolute or relative to current directory).
801 * @ nld_root_xp : extended pointer on new path root inode (any inode in Inode Tree).
802 * @ new_path : new pathname (absolute or relative to current directory).
803 * @ returns 0 if success / -1 if error.
804 *****************************************************************************************/
805error_t vfs_link( xptr_t old_root_xp,
806 char * old_path,
807 xptr_t new_root_xp,
808 char * new_path );
809
810/******************************************************************************************
811 * This function is called by the kernel to remove from the file system a directory entry
812 * identified by the <root_xp> & <path> arguments.
813 * The link count of the target node is decremented.
814 * If the removed link is the last, the target inode is deleted.
815 * Both the IOC device and the Inode Tree are modified.
816 *
817 * TODO This function should handle any type of node, but the current implementation
818 * handles only only the FILE and DIR types.
819 *
820 * WARNING : this function takes & releases the remote_rwlock protecting the Inode Tree.
821 ******************************************************************************************
822 * @ root_xp : extended pointer on root inode (can be any inode in Inode Tree).
823 * @ path : pathname (absolute or relative to current directory).
824 * @ returns 0 if success / -1 if error.
825 *****************************************************************************************/
826error_t vfs_unlink( xptr_t root_xp,
827 char * path );
828
829/******************************************************************************************
830 * This function returns, in the structure pointed by the <st> pointer, various
831 * informations on the file identified by the <root_inode_xp> and <patname> arguments.
832 *
833 * TODO : only partially implemented yet (only size and inum fields).
834 *
835 * WARNING : this function takes & releases the remote_rwlock protecting the Inode Tree.
836 ******************************************************************************************
837 * @ root_xp : extended pointer on path root inode (any inode in Inode Tree)
838 * @ pathname : pathname to target inode.
839 * @ st : local pointer on the stat structure in kernel space.
840 * @ returns 0 if success / -1 if error.
841 *****************************************************************************************/
842error_t vfs_stat( xptr_t root_xp,
843 char * pathname,
844 struct stat * st );
845
846/******************************************************************************************
847 * This function creates a new inode/dentry couple for a new directory, and registers it
848 * in the Inode Tree, as defined by the <root_xp>, <path>, and <mode> arguments.
849 ******************************************************************************************
850 * @ root_xp : extended pointer on the path root directory.
851 * @ path : pathname (absolute or relative to CWD).
852 * @ mode : access rights (as defined by chmod)
853 * @ returns 0 if success / -1 if error.
854 *****************************************************************************************/
855error_t vfs_mkdir( xptr_t root_xp,
856 char * path,
857 uint32_t mode );
858
859/******************************************************************************************
860 * This function makes the directory identified by the <root_xp and <path> arguments
861 * to become the working directory for the calling process.
862 ******************************************************************************************
863 * @ root_xp : extended pointer on the path root directory.
864 * @ path : pathname (absolute or relative to CWD).
865 * return 0 if success / -1 if error.
866 *****************************************************************************************/
867error_t vfs_chdir( xptr_t root_xp,
868 char * path );
869
870/******************************************************************************************
871 * This function change the access rigths for the file/directory identified by the
872 * <root_xp> and <path> arguments as defined by the <mode> argument value.
873 * TODO not implemented yet
874 ******************************************************************************************
875 * @ root_xp : extended pointer on the path root directory.
876 * @ path : pathname (absolute or relative to CWD).
877 * @ mode : access rights
878 * return 0 if success / -1 if error.
879 *****************************************************************************************/
880error_t vfs_chmod( xptr_t root_xp,
881 char * path,
882 uint32_t mode );
883
884/******************************************************************************************
885 * This function creates a new inode/dentry couple of FIFO type, and registers it
886 * in the Inode Tree as specified by the <root_xp>, <path>, and <mode> arguments.
887 ******************************************************************************************
888 * @ root_xp : [in] extended pointer on the root directory in path.
889 * @ path : [in] pathname (absolute or relative to CWD).
890 * @ mode : [in] access rights new value.
891 *****************************************************************************************/
892error_t vfs_mkfifo( xptr_t root_xp,
893 char * path,
894 uint32_t mode );
895
896
897
898
899
900/******************************************************************************************
901 * These functions define the VFS "FS" API to access a specific File System
902 *****************************************************************************************/
903
904/******************************************************************************************
905 * This function introduces in a directory mapper identified by the <parent_inode_xp>
906 * argument, a new entry identified by the <dentry_ptr> argument.
907 * Depending on the file system type, it calls the proper, FS specific function.
908 * All informations related to the new directory must be contained in the dentry
909 * descriptor, or in the associated child inode descriptor.
910 * The dentry descriptor "extend" field is updated as required by the specific FS.
911 * Finally, it synchronously updates the parent directory on IOC device.
912 * This function can be called by any thread running in any cluster.
913 ******************************************************************************************
914 * @ parent : local pointer on parent (directory) inode.
915 * @ dentry : local pointer on dentry containing name.
916 * @ return 0 if success / return -1 if device access failure.
917 *****************************************************************************************/
918error_t vfs_fs_add_dentry( xptr_t parent_inode_xp,
919 vfs_dentry_t * dentry_ptr );
920
921/******************************************************************************************
922 * This function removes from a directory mapper identified by the <parent_inode_xp>
923 * argument, an entry identified by the <dentry_ptr> argument.
924 * Depending on the file system type, it calls the proper, FS specific function.
925 * Finally, it synchronously updates the parent directory on IOC device.
926 * This function can be called by any thread running in any cluster.
927 ******************************************************************************************
928 * @ parent_inode_xp : extended pointer on parent (directory) inode.
929 * @ dentry_ptr : local pointer on dentry containing name.
930 * @ return 0 if success / return -1 if device access failure.
931 *****************************************************************************************/
932error_t vfs_fs_remove_dentry( xptr_t parent_inode_xp,
933 vfs_dentry_t * dentry_ptr );
934
935/******************************************************************************************
936 * This function scan a directory mapper, identified by the <parent_inode_xp> argument
937 * to find a directory entry identified by the <dentry_ptr> argument,
938 * and updates both the child inode descriptor, and the associated dentry descriptor:
939 * - It set the "size", "type", and "extend" fields in inode descriptor.
940 * - It set the "extend" field in dentry descriptor.
941 * It is called by the vfs_lookup() function in case of miss, and does NOT take any lock.
942 * Depending on the file system type, it calls the relevant, FS specific function.
943 * This function can be called by any thread running in any cluster.
944 ******************************************************************************************
945 * @ parent_inode_xp : extended pointer on parent inode (directory).
946 * @ dentry_ptr : local pointer on new entry (in parent inode cluster).
947 * @ return 0 if success / return -1 if dentry not found.
948 *****************************************************************************************/
949error_t vfs_fs_new_dentry_from_mapper( xptr_t parent_inode_xp,
950 vfs_dentry_t * dentry_ptr );
951
952/*****************************************************************************************
953 * This function introduces a brand new dentry identified by the <dentry_ptr> argument
954 * in the mapper of a directory identified by the <parent_inode_xp> argument.
955 * It is called by the vfs_lookup() function, and does NOT take any lock.
956 * The child inode descriptor, and the dentry descriptor must have been previously
957 * allocated and introduced in the Inode Tree. The dentry descriptor contains the name.
958 * Depending on the file system type, it calls the relevant, FS specific function.
959 * This function can be called by any thread running in any cluster.
960 *****************************************************************************************
961 * @ parent_inode_xp : [in] extended pointer on parent inode (directory).
962 * @ dentry_ptr : [in] local pointer on dentry (in parent inode cluster).
963 * @ return 0 if success / return -1 if failure.
964 ****************************************************************************************/
965error_t vfs_fs_new_dentry_to_mapper( xptr_t parent_inode_xp,
966 vfs_dentry_t * dentry_ptr );
967
968/******************************************************************************************
969 * This function updates the "size" field of a directory entry identified by the
970 * <dentry_ptr> argument in a directory mapper identified by the <parent_inode_xp>
971 * from the value contained in the inode descriptor.
972 * The parent directory on device is synchronously updated.
973 * It is called by the vfs_close() function.
974 * Depending on the file system type, it calls the relevant, FS specific function.
975 * This function can be called by any thread running in any cluster.
976 ******************************************************************************************
977 * @ parent_inode_xp : local pointer on parent inode (directory).
978 * @ dentry_ptr : local pointer on dentry (in parent directory cluster).
979 * @ return 0 if success / return -1 if not found.
980 *****************************************************************************************/
981error_t vfs_fs_update_dentry( xptr_t parent_inode_xp,
982 vfs_dentry_t * dentry_ptr );
983
984/******************************************************************************************
985 * This function scan the mapper of an an existing parent inode directory, identified by
986 * the <inode> argument and copy up to <max_dirent> valid dentries to a
987 * local dirent array, defined by the <array> argument. The <min_dentry> argument defines
988 * the index of the first dentry to copied to the target dirent array.
989 * This function returns in the <entries> buffer the number of dentries actually written,
990 * and signals in the <done> buffer when the last valid entry has been found.
991 * If the <detailed> argument is true, a dentry/inode couple that does not exist in
992 * the Inode Tree is dynamically created, and all dirent fiels are documented in the
993 * dirent array. Otherwise, only the dentry name is documented.
994 * This function does NOT take any lock.
995 * Depending on the file system type, it calls the relevant, FS specific function.
996 *
997 * WARNING : this function must be called by a thread running in the cluster containing
998 * the target directory inode.
999 ******************************************************************************************
1000 * @ inode : [in] local pointer on directory inode.
1001 * @ array : [in] local pointer on array of dirents.
1002 * @ max_dirent : [in] max number of slots in dirent array.
1003 * @ min_dentry : [in] index of first dentry to be copied into array.
1004 * @ detailed : [in] dynamic inode creation if true.
1005 * @ entries : [out] number of dentries actually copied into array.
1006 * @ done : [out] Boolean true when last entry found.
1007 * @ return 0 if success / return -1 if failure.
1008 *****************************************************************************************/
1009error_t vfs_fs_get_user_dir( vfs_inode_t * inode,
1010 struct dirent * array,
1011 uint32_t max_dirent,
1012 uint32_t min_dentry,
1013 bool_t detailed,
1014 uint32_t * entries,
1015 bool_t * done );
1016
1017/*****************************************************************************************
1018 * This function updates the FS on the IOC device for a given inode identified by
1019 * the <inode> argument. It scan all pages registered in the associated mapper,
1020 * and copies from mapper to device each page marked as dirty.
1021 * WARNING : The target <inode> cannot be a directory, because all modifications in a
1022 * directory are synchronously done on the IOC device by the two vfs_fs_add_dentry()
1023 * and vfs_fs_remove_dentry() functions.
1024 * Depending on the file system type, it calls the relevant, FS specific function.
1025 * This function can be called by any thread running in any cluster.
1026 *****************************************************************************************
1027 * @ inode_xp : remote pointer on inode.
1028 * @ return 0 if success / return -1 if failure.
1029 ****************************************************************************************/
1030error_t vfs_fs_sync_inode( xptr_t inode_xp );
1031
1032/*****************************************************************************************
1033 * This function updates the FS defined by the <fs_type> argument on the IOC device
1034 * for the FAT itself. It scan all clusters registered in the FAT mapper, and copies
1035 * to device each page marked as dirty.
1036 * Depending on the file system type, it calls the relevant, FS specific function.
1037 * It can be called by a thread running in any cluster.
1038 *****************************************************************************************
1039 * @ fs_type : specific file system type.
1040 * @ return 0 if success / return EIO if failure during device access.
1041 ****************************************************************************************/
1042error_t vfs_fs_sync_fat( vfs_fs_type_t fs_type );
1043
1044/******************************************************************************************
1045 * This function makes all I/O operations required to release all clusters allocated
1046 * on IOC device to a given inode, identified by the <inode_xp> argument.
1047 * Depending on the file system type, it calls the proper, FS specific function.
1048 * It is called by the vfs_unlink() function.
1049 * This function does NOT take any lock.
1050 * Depending on the file system type, it calls the relevant, FS specific function.
1051 * This function can be executed by any thread running in any cluster.
1052 ******************************************************************************************
1053 * @ inode_xp : extended pointer on inode.
1054 * @ return 0 if success / return -1 if device access failure.
1055 *****************************************************************************************/
1056error_t vfs_fs_release_inode( xptr_t inode_xp );
1057
1058/******************************************************************************************
1059 * This function makes the I/O operation to move one page identified by the <page_xp>
1060 * argument to/from the IOC device from/to the mapper, as defined by the <cmd_type>.
1061 * It is used in case of MISS on the mapper (read), or when a dirty page in the mapper
1062 * must be updated in the File System (write).
1063 * The mapper pointer, and the page index in file are obtained from the page descriptor.
1064 * This function does NOT take any lock.
1065 * Depending on the file system type, it calls the proper, FS specific function.
1066 * This function can be executed by any thread running in any cluster.
1067 ******************************************************************************************
1068 * @ page_xp : extended pointer on page descriptor (for mapper and page_id).
1069 * @ cmd_type : IOC_READ / IOC_WRITE / IOC_SYNC_READ / IOC_SYNC_WRITE
1070 * @ returns 0 if success / return -1 if device access failure.
1071 *****************************************************************************************/
1072error_t vfs_fs_move_page( xptr_t page_xp,
1073 ioc_cmd_type_t cmd_type );
1074
1075
1076#endif /* _VFS_H_ */
Note: See TracBrowser for help on using the repository browser.