source: trunk/kernel/fs/vfs.h @ 610

Last change on this file since 610 was 610, checked in by alain, 3 years ago

Fix several bugs in VFS to support the following
ksh commandis : cp, mv, rm, mkdir, cd, pwd

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