Changeset 673 for trunk/kernel/fs/vfs.h

Timestamp:

Nov 19, 2020, 11:54:16 PM (3 years ago)

Author:

alain

Message:

Introduce the DEBUG_VFS_ERROR in kernel_config to make
error messges display conditional.

File:

• trunk/kernel/fs/vfs.h (modified) (20 diffs)

trunk/kernel/fs/vfs.h

@@ -3 +3 @@
  *
  * Author  Mohamed Lamine Karaoui (2014,2015)
- *         Alain Greiner (2016,2017,2018,2019,2020)
+ *         Alain Greiner          (2016,2017,2018,2019,2020)
  *
  * Copyright (c) UPMC Sorbonne Universites
@@ -49 +49 @@
 struct vfs_ctx_s;
 struct vfs_file_s;
-
+struct remote_buf_s;
 struct mapper_s;
 struct process_s;
@@ -66 +66 @@
 #define VFS_LOOKUP_CREATE   0x10     /* file must be created if missing                  */
 #define VFS_LOOKUP_EXCL     0x20     /* file cannot previously exist                     */
+
+
+
 
 /******************************************************************************************
@@ -105 +108 @@
 }
 vfs_ctx_t;
+
+/******************************************************************************************
+ *        These functions access / modify  a VFS context.
+ *****************************************************************************************/
+
+/****************************************************************************************** 
+ * This function initialises a (statically allocated) VFS context in cluster identified
+ * by the <cxy> argument. 
+ * It is called by the kernel_init() function.
+ ******************************************************************************************
+ * @ cxy            : target cluster identifier.
+ * @ fs_type        : file system type.
+ * @ total_clusters : total number of clusters on device.
+ * @ cluster_size   : cluster size on device (bytes).
+ * @ vfs_root_xp    : extended pointer on VFS root inode.
+ * @ extend         : fs_type_specific extension.
+ *****************************************************************************************/
+void vfs_ctx_init( cxy_t           cxy,
+                   vfs_fs_type_t   type,
+                       uint32_t        total_clusters,
+                       uint32_t        cluster_size,
+                       xptr_t          vfs_root_xp,
+                   void          * extend );
+
+/****************************************************************************************** 
+ * This function allocates an inode identifier from the local cluster inum allocator.
+ * The inum respects a fixed format:
+ * - the 16 MSB bits contain the cluster identifier : cxy
+ * - the 16 LSB bits contains the local inode identifier  : lid
+ ******************************************************************************************
+ * @ ctx_xp   : [in]  extended pointer on file system context.
+ * @ inum     : [out] buffer for allocated inode identifier.
+ * @ return 0 if success / return non-zero if error.
+ *****************************************************************************************/
+error_t vfs_ctx_inum_alloc( xptr_t     ctx_xp,
+                            uint32_t * inum );
+
+/****************************************************************************************** 
+ * This function release an inode identifier.                                  
+ ******************************************************************************************
+ * @ ctx_xp   : [in] extended pointer on file system context.
+ * @ inum     : [in] released inode identifier.
+ *****************************************************************************************/
+void vfs_ctx_inum_release( xptr_t      ctx_xp,
+                           uint32_t    inum );
+
+
+
+
+
+
+/******************************************************************************************
+ * This file structure describes an open file/directory for a given process.
+ * It is not replicated, and is dynamically allocated in the cluster that contains
+ * the associated inode / socket / pipe , when a thread makes an open(), opendir(),
+ * socket(), or pipe() system call. It cannot exist a <file> structure without a 
+ * a <mapper>, <socket>, or <pipe> structure (depending on type) in same cluster.
+ * It can exist a <file> structure without an <inode> (for PIPE and SOCK types).
+ *****************************************************************************************/
+
+/* this enum define the VFS inode types values                                           */
+/* WARNING : this enum must be kept consistent with macros in <shared_stat.h> file       */
+/*           and with types in <shared_dirent.h> file.                                   */
+
+typedef enum   
+{
+    FILE_TYPE_REG   =     0,           /*! regular file                                 */
+    FILE_TYPE_DIR   =     1,           /*! directory                                    */
+    FILE_TYPE_FIFO  =     2,           /*! POSIX named fifo                             */
+    FILE_TYPE_PIPE  =     3,           /*! POSIX anonymous pipe                         */
+    FILE_TYPE_SOCK  =     4,           /*! POSIX anonymous socket                       */
+    FILE_TYPE_DEV   =     5,           /*! character device                             */
+    FILE_TYPE_BLK   =     6,           /*! block device                                 */
+    FILE_TYPE_SYML  =     7,           /*! symbolic link                                */
+}
+vfs_file_type_t;
+
+typedef enum
+{
+    FD_ATTR_READ_ENABLE    = 0x01,     /*! read access possible                          */
+    FD_ATTR_WRITE_ENABLE   = 0x02,     /*! write access possible                         */
+    FD_ATTR_APPEND         = 0x04,     /*! append on each write                          */
+    FD_ATTR_CLOSE_EXEC     = 0x08,     /*! close file on exec                            */
+    FD_ATTR_SYNC           = 0x10,     /*! synchronise FS on each write                  */
+    FD_ATTR_IS_DIR         = 0x20,     /*! this is a directory                           */
+}
+vfs_file_attr_t;
+
+typedef struct vfs_file_s
+{
+        struct vfs_ctx_s      * ctx;        /*! local pointer on FS context.                 */
+        vfs_file_attr_t         attr;       /*! file attributes bit vector (see above)       */
+        vfs_file_type_t        type;       /*! same type as inode                           */
+        uint32_t                offset;     /*! seek position in file                        */
+        remote_rwlock_t         lock;       /*! protect offset modifications                 */
+        struct vfs_inode_s    * inode;      /*! local pointer on associated inode            */
+        struct mapper_s       * mapper;     /*! associated mapper (REG or DIR types only)    */
+    struct socket_s       * socket;     /*! associated socket (SOCK type only)           */
+    struct pipe_s         * pipe;       /*! associated pipe (FIFO or PIPE types only)    */
+        void                  * extend;     /*! FS specific extension                        */
+}
+vfs_file_t;
+
+/******************************************************************************************
+ *        These low-level functions access / modify a VFS file descriptor
+ *****************************************************************************************/
+
+/****************************************************************************************** 
+ * This function allocates memory and initializes a new file descriptor in the
+ * cluster defined by the <inode_xp> argument.
+ * It can be called by any thread running in any cluster.
+ ****************************************************************************************** 
+ * @ inode_xp  : [in]  extended pointer on associated inode.
+ * @ attr      : [in]  file descriptor attributes.
+ * @ file_xp   : [out] buffer for extended pointer on created file descriptor.
+ * @ return 0 if success / return ENOMEM if error.
+ *****************************************************************************************/
+error_t vfs_file_create( xptr_t        inode_xp,
+                         uint32_t      attr,
+                         xptr_t      * file_xp );  
+
+/****************************************************************************************** 
+ * This function releases memory allocated to file descriptor identified
+ * by the <file_xp> argument.
+ * It can be called by any thread running in any cluster.
+ ****************************************************************************************** 
+ * @ file_xp  : [in] extended pointer on file descriptor.
+ *****************************************************************************************/
+void vfs_file_destroy( xptr_t  file_xp );  
+
+/****************************************************************************************** 
+ * This debug function copies the name of a the file identified by <file_xp>
+ * argument to a local buffer identified by the <name> argument.
+ * The local buffer size must be at least CONFIG_VFS_MAX_NAME_LENGTH. 
+ *****************************************************************************************
+ * @ ionde_xp  : [in] extended pointer on the remote inode.
+ * @ name      : [out] local string.
+ ***************************************************************************************/
+void vfs_file_get_name( xptr_t inode_xp,
+                        char * name );
+
+
+
 
 /******************************************************************************************
@@ -124 +270 @@
  *****************************************************************************************/
 
-/* this enum define the VFS inode types values                                           */
-/* WARNING : this enum must be kept consistent with macros in <shared_stat.h> file       */
-/*           and with types in <shared_dirent.h> file.                                   */
-
-typedef enum   
-{
-    INODE_TYPE_FILE  =     0,           /*! regular file                                 */
-    INODE_TYPE_DIR   =     1,           /*! directory                                    */
-    INODE_TYPE_FIFO  =     2,           /*! POSIX named pipe                             */
-    INODE_TYPE_PIPE  =     3,           /*! POSIX anonymous pipe                         */
-    INODE_TYPE_SOCK  =     4,           /*! POSIX socket                                 */
-    INODE_TYPE_DEV   =     5,           /*! character device                             */
-    INODE_TYPE_BLK   =     6,           /*! block device                                 */
-    INODE_TYPE_SYML  =     7,           /*! symbolic link                                */
-}
-vfs_inode_type_t;
-
 /* this enum define the VFS inode attributes values */
 
@@ -153 +282 @@
 typedef struct vfs_inode_s
 {
-    struct vfs_ctx_s * ctx;              /*! local pointer on FS context                 */
-    uint32_t           inum;             /*! inode identifier (unique in file system)    */
-    uint32_t           attr;             /*! inode attributes (see above)                */
-    vfs_inode_type_t   type;             /*! inode type (see above)                      */
-    uint32_t           size;             /*! number of bytes                             */
-    uint32_t           uid;              /*! user owner identifier                       */
-    uint32_t           gid;              /*! group owner identifier                      */
-    uint32_t           rights;           /*! access rights                               */
-    xlist_entry_t      parents;          /*! root of list of parents dentries            */
-    uint32_t           links;            /*! number of parent dentries (hard links)      */
-    xhtab_t            children;         /*! embedded xhtab of children dentries         */
-    remote_rwlock_t    size_lock;        /*! protect read/write to size                  */
-    remote_rwlock_t    main_lock;        /*! protect inode tree traversal and modifs     */
-    struct mapper_s  * mapper;           /*! associated file cache                       */
-    void             * extend;           /*! fs_type_specific inode extension            */
+    struct vfs_ctx_s    * ctx;           /*! local pointer on FS context                 */
+    uint32_t              inum;          /*! inode identifier (unique in file system)    */
+    uint32_t              attr;          /*! inode attributes (see above)                */
+    vfs_file_type_t      type;          /*! inode type (see above)                      */
+    uint32_t              size;          /*! number of bytes                             */
+    uint32_t              uid;           /*! user owner identifier                       */
+    uint32_t              gid;           /*! group owner identifier                      */
+    uint32_t              rights;        /*! access rights                               */
+    xlist_entry_t         parents;       /*! root of list of parents dentries            */
+    uint32_t              links;         /*! number of parent dentries (hard links)      */
+    xhtab_t               children;      /*! embedded xhtab of children dentries         */
+    remote_rwlock_t       size_lock;     /*! protect read/write to size                  */
+    remote_rwlock_t       main_lock;     /*! protect inode tree traversal and modifs     */
+    struct mapper_s     * mapper;        /*! associated file (REG or DIR types only)     */
+    struct remote_buf_s * pipe;          /*! associated pipe (FIFO type only)            */
+    void                * extend;        /*! fs_type_specific inode extension            */
 }
 vfs_inode_t;
@@ -191 +321 @@
 #define VFS_IWOTH      0x0000002
 #define VFS_IXOTH      0x0000001
+
+/******************************************************************************************
+ *        These low-level functions access / modify a VFS inode descriptor
+ *****************************************************************************************/
+
+/****************************************************************************************** 
+ * This function returns a printable string for the inode type.
+ *****************************************************************************************/
+const char * vfs_inode_type_str( vfs_file_type_t type );
+
+/****************************************************************************************** 
+ * This function allocates memory in cluster identified by the <cxy> argument 
+ * for an inode descriptor and for the associated mapper, and partially initialise 
+ * this inode from arguments values.
+ * It does NOT link it to the Inode Tree, as this is done by add_child_in_parent(). 
+ * It can be called by any thread running in any cluster.
+ ******************************************************************************************
+ * @ cxy        : [in]  target cluster identifier
+ * @ fs_type    : [in]  file system type.
+ * @ attr       : [in]  inode attributes.
+ * @ rights     : [in]  inode access rights.
+ * @ uid        : [in]  user owner ID.
+ * @ gid        : [in]  group owner ID.
+ * @ inode_xp   : [out] buffer for extended pointer on created inode.
+ * @ return 0 if success / return -1 if error.
+ *****************************************************************************************/
+error_t vfs_inode_create( cxy_t             cxy,
+                          vfs_fs_type_t     fs_type,
+                          uint32_t          attr,
+                          uint32_t          rights,
+                          uid_t             uid,
+                          gid_t             gid,
+                          xptr_t          * inode_xp );
+
+/****************************************************************************************** 
+ * This function releases memory allocated to an inode descriptor, including
+ * all memory allocated to the mapper (both mapper descriptor and radix tree).
+ * The mapper should not contain any dirty page (should be synchronized before deletion).
+ * It can be called by any thread running in any cluster.
+ ****************************************************************************************** 
+ * @ inode_xp  : extended pointer on inode descriptor.
+ *****************************************************************************************/
+void vfs_inode_destroy( xptr_t  inode_xp );  
+
+/****************************************************************************************** 
+ * This function returns the <size> of a file/dir from a remote inode,
+ * taking the remote_rwlock protecting <size> in READ_MODE.
+ * It can be called by any thread running in any cluster.
+ *****************************************************************************************
+ * @ inode_xp  : extended pointer on the remote inode.
+ * @ return the current size.
+ *****************************************************************************************/
+uint32_t vfs_inode_get_size( xptr_t inode_xp );
+
+/****************************************************************************************** 
+ * This function updates the "size" field of a remote inode identified by <inode_xp>.
+ * It takes the rwlock protecting the file size in WRITE_MODE, and set the "size" field
+ * when the current size is smaller than the requested <size> argument. 
+ * It can be called by any thread running in any cluster.
+ *****************************************************************************************
+ * @ inode_xp  : extended pointer on the remote inode.
+ * @ size      : requested size value.
+ *****************************************************************************************/
+void vfs_inode_update_size( xptr_t   inode_xp,
+                            uint32_t size );
+
+/****************************************************************************************** 
+ * This function takes the main lock of a remote inode identified by the <inode_xp>.
+ * This lock protect all inode fields, including the children dentries.
+ * It can be called by any thread running in any cluster.
+ *****************************************************************************************
+ * @ inode_xp  : extended pointer on the remote inode.
+ *****************************************************************************************/
+void vfs_inode_lock( xptr_t inode_xp );
+
+/****************************************************************************************** 
+ * This function releases the main lock of a remote inode identified by <inode_xp>.
+ * This lock protect all inode fiels, including the children dentries.
+ * It can be called by any thread running in any cluster.
+ *****************************************************************************************
+ * @ inode_xp  : extended pointer on the remote inode.
+ *****************************************************************************************/
+void vfs_inode_unlock( xptr_t inode_xp );
+
+/****************************************************************************************** 
+ * This debug function copies the name of a remote inode identified by the <inode_xp>
+ * argument to a local buffer identified by the <name> argument.
+ * The local buffer size must be at least CONFIG_VFS_MAX_NAME_LENGTH. 
+ * It can be called by any thread running in any cluster.
+ ******************************************************************************************
+ * @ inode_xp  : extended pointer on the remote inode.
+ * @ name      : local buffer pointer.
+ *****************************************************************************************/
+void vfs_inode_get_name( xptr_t inode_xp,
+                         char * name );
+
+/******************************************************************************************
+ * This function accesses successively all pages of a file identified by the <inode_xp>,
+ * argument, to force misses, and load all pages into mapper.
+ * The target inode can be a directory or a file, but this function is mainly used 
+ * to prefetch a complete directory to the mapper.
+ * This function does NOT take any lock.
+ * It can be called by any thread running in any cluster.
+ ******************************************************************************************
+ * @ inode_xp  : extended pointer on inode.
+ * @ return 0 if success / return -1 if device access failure.
+ *****************************************************************************************/
+error_t vfs_inode_load_all_pages( xptr_t inode_xp );
+
+/****************************************************************************************** 
+ * This debug function display the curren state of an inode descriptor.
+ * It can be called by any thread running in any cluster.
+ *****************************************************************************************/
+void vfs_inode_display( xptr_t inode_xp );
+
+
+
+
+
 
 /******************************************************************************************
@@ -215 +464 @@
 
 /******************************************************************************************
- * This file structure describes an open file/directory for a given process.
- * It is not replicated, and is dynamically allocated in the cluster that contains
- * the inode, when a thread makes an open() or opendir() system call.
- * It cannot exist a file structure without an inode structure in same cluster.
- * As the fd_array (containing extended pointers on the open file descriptors)
- * is replicated in all process descriptors, we need a references counter.
- *****************************************************************************************/
-
-typedef enum
-{
-    FD_ATTR_READ_ENABLE    = 0x01,     /*! read access possible                          */
-    FD_ATTR_WRITE_ENABLE   = 0x02,     /*! write access possible                         */
-    FD_ATTR_APPEND         = 0x04,     /*! append on each write                          */
-    FD_ATTR_CLOSE_EXEC     = 0x08,     /*! close file on exec                            */
-    FD_ATTR_SYNC           = 0x10,     /*! synchronise FS on each write                  */
-    FD_ATTR_IS_DIR         = 0x20,     /*! this is a directory                           */
-}
-vfs_file_attr_t;
-
-typedef struct vfs_file_s
-{
-        struct vfs_ctx_s      * ctx;        /*! local pointer on FS context.                 */
-        vfs_file_attr_t         attr;       /*! file attributes bit vector (see above)       */
-        vfs_inode_type_t        type;       /*! same type as inode                           */
-        uint32_t                offset;     /*! seek position in file                        */
-        uint32_t                refcount;   /*! all pointers on this file descriptor         */
-        remote_rwlock_t         lock;       /*! protect offset modifications                 */
-        struct mapper_s       * mapper;     /*! associated file cache                        */
-        struct vfs_inode_s    * inode;      /*! local pointer on associated inode            */
-    struct socket_s       * socket;     /*! local pointer on associated socket           */
-        void                  * extend;     /*! FS specific extension                        */
-}
-vfs_file_t;
-
-
-/******************************************************************************************
- *        These functions access / modify  a VFS context.
- *****************************************************************************************/
-
-/****************************************************************************************** 
- * This function initialises a (statically allocated) VFS context in cluster identified
- * by the <cxy> argument. 
- * It is called by the kernel_init() function.
- ******************************************************************************************
- * @ cxy            : target cluster identifier.
- * @ fs_type        : file system type.
- * @ total_clusters : total number of clusters on device.
- * @ cluster_size   : cluster size on device (bytes).
- * @ vfs_root_xp    : extended pointer on VFS root inode.
- * @ extend         : fs_type_specific extension.
- *****************************************************************************************/
-void vfs_ctx_init( cxy_t           cxy,
-                   vfs_fs_type_t   type,
-                       uint32_t        total_clusters,
-                       uint32_t        cluster_size,
-                       xptr_t          vfs_root_xp,
-                   void          * extend );
-
-/****************************************************************************************** 
- * This function allocates an inode identifier from the local cluster inum allocator.
- * The inum respects a fixed format:
- * - the 16 MSB bits contain the cluster identifier : cxy
- * - the 16 LSB bits contains the local inode identifier  : lid
- ******************************************************************************************
- * @ ctx_xp   : [in]  extended pointer on file system context.
- * @ inum     : [out] buffer for allocated inode identifier.
- * @ return 0 if success / return non-zero if error.
- *****************************************************************************************/
-error_t vfs_ctx_inum_alloc( xptr_t     ctx_xp,
-                            uint32_t * inum );
-
-/****************************************************************************************** 
- * This function release an inode identifier.                                  
- ******************************************************************************************
- * @ ctx_xp   : [in] extended pointer on file system context.
- * @ inum     : [in] released inode identifier.
- *****************************************************************************************/
-void vfs_ctx_inum_release( xptr_t      ctx_xp,
-                           uint32_t    inum );
-
-
-
-/******************************************************************************************
- *        These low-level functions access / modify a VFS inode descriptor
- *****************************************************************************************/
-
-/****************************************************************************************** 
- * This function returns a printable string for the inode type.
- *****************************************************************************************/
-const char * vfs_inode_type_str( vfs_inode_type_t type );
-
-/****************************************************************************************** 
- * This function allocates memory in cluster identified by the <cxy> argument 
- * for an inode descriptor and for the associated mapper, and partially initialise 
- * this inode from arguments values.
- * It does NOT link it to the Inode Tree, as this is done by add_child_in_parent(). 
- * It can be called by any thread running in any cluster.
- ******************************************************************************************
- * @ cxy        : [in]  target cluster identifier
- * @ fs_type    : [in]  file system type.
- * @ attr       : [in]  inode attributes.
- * @ rights     : [in]  inode access rights.
- * @ uid        : [in]  user owner ID.
- * @ gid        : [in]  group owner ID.
- * @ inode_xp   : [out] buffer for extended pointer on created inode.
- * @ return 0 if success / return -1 if error.
- *****************************************************************************************/
-error_t vfs_inode_create( cxy_t             cxy,
-                          vfs_fs_type_t     fs_type,
-                          uint32_t          attr,
-                          uint32_t          rights,
-                          uid_t             uid,
-                          gid_t             gid,
-                          xptr_t          * inode_xp );
-
-/****************************************************************************************** 
- * This function releases memory allocated to an inode descriptor, including
- * all memory allocated to the mapper (both mapper descriptor and radix tree).
- * The mapper should not contain any dirty page (should be synchronized before deletion).
- * It can be called by any thread running in any cluster.
- ****************************************************************************************** 
- * @ inode_xp  : extended pointer on inode descriptor.
- *****************************************************************************************/
-void vfs_inode_destroy( xptr_t  inode_xp );  
-
-/****************************************************************************************** 
- * This function returns the <size> of a file/dir from a remote inode,
- * taking the remote_rwlock protecting <size> in READ_MODE.
- * It can be called by any thread running in any cluster.
- *****************************************************************************************
- * @ inode_xp  : extended pointer on the remote inode.
- * @ return the current size.
- *****************************************************************************************/
-uint32_t vfs_inode_get_size( xptr_t inode_xp );
-
-/****************************************************************************************** 
- * This function updates the "size" field of a remote inode identified by <inode_xp>.
- * It takes the rwlock protecting the file size in WRITE_MODE, and set the "size" field
- * when the current size is smaller than the requested <size> argument. 
- * It can be called by any thread running in any cluster.
- *****************************************************************************************
- * @ inode_xp  : extended pointer on the remote inode.
- * @ size      : requested size value.
- *****************************************************************************************/
-void vfs_inode_update_size( xptr_t   inode_xp,
-                            uint32_t size );
-
-/****************************************************************************************** 
- * This function takes the main lock of a remote inode identified by the <inode_xp>.
- * This lock protect all inode fields, including the children dentries.
- * It can be called by any thread running in any cluster.
- *****************************************************************************************
- * @ inode_xp  : extended pointer on the remote inode.
- *****************************************************************************************/
-void vfs_inode_lock( xptr_t inode_xp );
-
-/****************************************************************************************** 
- * This function releases the main lock of a remote inode identified by <inode_xp>.
- * This lock protect all inode fiels, including the children dentries.
- * It can be called by any thread running in any cluster.
- *****************************************************************************************
- * @ inode_xp  : extended pointer on the remote inode.
- *****************************************************************************************/
-void vfs_inode_unlock( xptr_t inode_xp );
-
-/****************************************************************************************** 
- * This debug function copies the name of a remote inode identified by the <inode_xp>
- * argument to a local buffer identified by the <name> argument.
- * The local buffer size must be at least CONFIG_VFS_MAX_NAME_LENGTH. 
- * It can be called by any thread running in any cluster.
- ******************************************************************************************
- * @ inode_xp  : extended pointer on the remote inode.
- * @ name      : local buffer pointer.
- *****************************************************************************************/
-void vfs_inode_get_name( xptr_t inode_xp,
-                         char * name );
-
-/******************************************************************************************
- * This function accesses successively all pages of a file identified by the <inode_xp>,
- * argument, to force misses, and load all pages into mapper.
- * The target inode can be a directory or a file, but this function is mainly used 
- * to prefetch a complete directory to the mapper.
- * This function does NOT take any lock.
- * It can be called by any thread running in any cluster.
- ******************************************************************************************
- * @ inode_xp  : extended pointer on inode.
- * @ return 0 if success / return -1 if device access failure.
- *****************************************************************************************/
-error_t vfs_inode_load_all_pages( xptr_t inode_xp );
-
-/****************************************************************************************** 
- * This debug function display the curren state of an inode descriptor.
- * It can be called by any thread running in any cluster.
- *****************************************************************************************/
-void vfs_inode_display( xptr_t inode_xp );
-
-/******************************************************************************************
  *        These low-level functions access / modify a VFS dentry descriptor
  *****************************************************************************************/
@@ -442 +494 @@
 
 
-/******************************************************************************************
- *        These low-level functions access / modify a VFS file descriptor
- *****************************************************************************************/
-
-/****************************************************************************************** 
- * This function allocates memory and initializes a new file descriptor in the
- * cluster defined by the <inode_xp> argument.
- * It can be called by any thread running in any cluster.
- ****************************************************************************************** 
- * @ inode_xp  : [in]  extended pointer on associated inode.
- * @ attr      : [in]  file descriptor attributes.
- * @ file_xp   : [out] buffer for extended pointer on created file descriptor.
- * @ return 0 if success / return ENOMEM if error.
- *****************************************************************************************/
-error_t vfs_file_create( xptr_t        inode_xp,
-                         uint32_t      attr,
-                         xptr_t      * file_xp );  
-
-/****************************************************************************************** 
- * This function releases memory allocated to file descriptor identified
- * by the <file_xp> argument.
- * It can be called by any thread running in any cluster.
- ****************************************************************************************** 
- * @ file_xp  : [in] extended pointer on file descriptor.
- *****************************************************************************************/
-void vfs_file_destroy( xptr_t  file_xp );  
-
-/****************************************************************************************** 
- * These functions increment (resp. decrement) the count field in a remote file
- * descriptor, using a remote_atomic access. 
- *****************************************************************************************
- * @ file_xp  : extended pointer on file descriptor.
- *****************************************************************************************/
-void vfs_file_count_up  ( xptr_t   file_xp );
-void vfs_file_count_down( xptr_t   file_xp );
-
-/****************************************************************************************** 
- * This debug function copies the name of a the file identified by <file_xp>
- * argument to a local buffer identified by the <name> argument.
- * The local buffer size must be at least CONFIG_VFS_MAX_NAME_LENGTH. 
- *****************************************************************************************
- * @ ionde_xp  : [in] extended pointer on the remote inode.
- * @ name      : [out] local string.
- ***************************************************************************************/
-void vfs_file_get_name( xptr_t inode_xp,
-                        char * name );
+
+
 
 
@@ -532 +540 @@
  *   the missing dentry/inode couple, from informations found in the parent directory.
  * - If this directory entry does not exist on IOC, it returns an error.
- * - If the the file identified by the pathname does not exist on IOC but the
+ * - If the file identified by the pathname does not exist on IOC but the
  *   flag CREATE is set, the inode is created. It returns an error otherwise.
  * - If the the file identified by the pathname exist on device, but both flags EXCL
@@ -539 +547 @@
  *   inode, and copies in <last_name> buffer a string containing the last name in path.
  *
- * WARNING : The remote_rwlock protecting the Inode Tree must be taken by the caller. 
+ * WARNING : The lock protecting the Inode Tree must be taken in read mode by the caller. 
  *
  * TODO the access rights are not checked yet.
@@ -558 +566 @@
 /******************************************************************************************
  * This function creates a new couple dentry/inode, and insert it in the Inode-Tree.
- * Only the distributed Inode Tree is modified: it does NOT modify the parent mapper, 
+ * Only the distributed Inode-Tree is modified: it does NOT modify the parent mapper, 
  * and does NOT update the FS on IOC device.
- * It set the inode type to the default INODE_TYPE_FILE value
+ * It set the inode type to the default FILE_TYPE_REG value.
  * It can be executed by any thread running in any cluster (can be different from both
  * the child cluster and the parent cluster).
  * The new child inode and the parent inode can have different FS types.
- * [Implementation note]
+ *
+ * WARNING : The lock protecting the Inode Tree must be taken in write mode by the caller. 
+ ******************************************************************************************
+ * Implementation note
  * As there are cross-references between inode and dentry, this function implements
  * a five steps scenario :
@@ -591 +602 @@
 
 /******************************************************************************************
- * This function removes a remote dentry from the Inode-Tree.
+ * This function removes a remote dentry and the associated inode from the Inode-Tree.
  * - It removes the dentry from the parent inode xhtab ("children" field), and from the
  *   child inode xlist ("parents" field).
@@ -601 +612 @@
  * It can be executed by any thread running in any cluster (can be different from both
  * the inode cluster and the dentry cluster).
+ *
+ * WARNING : The lock protecting the Inode Tree must be taken in write mode by the caller. 
  ******************************************************************************************
  * @ dentry_xp   : extended pointer on removed dentry.
@@ -613 +626 @@
  * This function is called by all functions creating a brand new directory : vfs_mkdir(),
  * devfs_global_init(), and devfs_local_init().
+ *
+ * WARNING : The lock protecting the Inode Tree must be taken in write mode by the caller. 
  ******************************************************************************************
  * @ child_xp    : extended pointer on new directory inode.
@@ -624 +639 @@
  * This recursive function diplays a complete inode/dentry sub-tree.
  * Any inode can be selected as the sub-tree root.
- * WARNING : this function is not protected against a concurrent inode/dentry removal...
+ *
+ * TODO : this function should be protected against a concurrent Inode-Tree change.
  ******************************************************************************************
  * @ inode_xp   : extended pointer on sub-tree root inode.
@@ -632 +648 @@
 /****************************************************************************************** 
  * This function mount a given file system type for a given process 
- * TODO non implemented yet [AG].     
+ * TODO non implemented [AG].     
  *****************************************************************************************/
 error_t vfs_mount_fs_root( struct device_s  * device,
@@ -829 +845 @@
 
 /****************************************************************************************** 
- * This function  creates a new directory as defined by the <root_xp> & <path> arguments.
- * TODO not implemented yet...
+ * This function  creates a new inode/dentry couple for a new directory, and registers it
+ * in the Inode Tree, as defined by the <root_xp>,  <path>, and <mode> arguments.
  ******************************************************************************************
  * @ root_xp  : extended pointer on the path root directory.
@@ -855 +871 @@
  * This function change the access rigths for the file/directory identified by the 
  * <root_xp> and <path> arguments as defined by the <mode> argument value.
+ * TODO not implemented yet
  ****************************************************************************************** 
  * @ root_xp  : extended pointer on the path root directory.
@@ -866 +883 @@
 
 /****************************************************************************************** 
- * This function creates a named FIFO file.
- * TODO not implemented yet                                                          
+ * This function creates a new inode/dentry couple of FIFO type, and registers it
+ * in the Inode Tree as specified by the <root_xp>, <path>, and <mode> arguments.
  ****************************************************************************************** 
- * @ root_xp  : extended pointer on the path root directory.
- * @ path     : pathname (absolute or relative to CWD).
- * @ mode     : access rights new value.
+ * @ root_xp  : [in] extended pointer on the root directory in path.
+ * @ path     : [in] pathname (absolute or relative to CWD).
+ * @ mode     : [in] access rights new value.
  *****************************************************************************************/
 error_t vfs_mkfifo( xptr_t       root_xp,