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

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

Improve the FAT32 file system to support cat, rm, cp commands.

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