Diff markup

Differences between /sos/fs.h (Article 9) and /sos/fs.h (Article 9.5)

 /* Copyright (C) 2005      David Decotigny     !!  /* Copyright (C) 2005,2006 David Decotigny
    Copyright (C) 2000-2005 The KOS Team (Thoma        Copyright (C) 2000-2005 The KOS Team (Thomas Petazzoni, David
                            Decotigny, Julien M                                Decotigny, Julien Munier)
                                                    
    This program is free software; you can redi        This program is free software; you can redistribute it and/or
    modify it under the terms of the GNU Genera        modify it under the terms of the GNU General Public License
    as published by the Free Software Foundatio        as published by the Free Software Foundation; either version 2
    of the License, or (at your option) any lat        of the License, or (at your option) any later version.
                                                       
    This program is distributed in the hope tha        This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the         but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details        GNU General Public License for more details.
                                                       
    You should have received a copy of the GNU         You should have received a copy of the GNU General Public License
    along with this program; if not, write to t        along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place - Suite 3        Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
    USA.                                               USA. 
 */                                                 */
 #ifndef _SOS_FS_H_                                 #ifndef _SOS_FS_H_
 #define _SOS_FS_H_                                 #define _SOS_FS_H_
                                                    
                                                    
 /**                                                /**
  * @file fs.h                                       * @file fs.h
  *                                                  *
  * (Virtual) Filesystem management.                 * (Virtual) Filesystem management.
  *                                                  *
  * SOS provides a complete Unix-like file syst      * SOS provides a complete Unix-like file system service. Supported
  * features of this service are:                    * features of this service are:
  *   - mountpoints                                  *   - mountpoints
  *   - generic file system support (FS) throug      *   - generic file system support (FS) through object-oriented
  *     specialization (so-called VFS)               *     specialization (so-called VFS)
  *   - hard & symbolic links                        *   - hard & symbolic links
  *   - regular files and directories                *   - regular files and directories
  *   - block and character device special file      *   - block and character device special files (from article 9 onward)
  *   - file mapping                                 *   - file mapping
  *   - basic permission management ("rwx" only      *   - basic permission management ("rwx" only, no notion of owner)
  *   - chroot                                       *   - chroot
  *   - separation of disk node and namespace n      *   - separation of disk node and namespace notions allowing hard links
  *     and to move/rename/remove files or dire      *     and to move/rename/remove files or directories that are in use
  *   - basic FS interface (open/read/seek/crea      *   - basic FS interface (open/read/seek/creat/mkdir/rename/link
  *     / symlink/chmod/mount/fcntl/ioctl...)        *     / symlink/chmod/mount/fcntl/ioctl...)
  *   - deferred writes (ie file caching). @see      *   - deferred writes (ie file caching). @see sync(3)
  *                                                  *
  * Among the unsupported features:                  * Among the unsupported features:
  *   - no user-based permission (uid/gid, ACLS      *   - no user-based permission (uid/gid, ACLS)
  *   - no modification / access time accountin      *   - no modification / access time accounting
  *   - no Fifo/socket special files (yet)           *   - no Fifo/socket special files (yet)
  *   - no generic support library for common f      *   - no generic support library for common fcntl commands
  *     (F_SETOWN/GETLEASE/NOTIFY, etc.)             *     (F_SETOWN/GETLEASE/NOTIFY, etc.)
  *   - no flock-style functions                     *   - no flock-style functions
  *                                                  *
  * Rationale                                        * Rationale
  * =========                                        * =========
  * The VFS layer is based on 3 central concept      * The VFS layer is based on 3 central concepts:
  *                                                  *
  *  - The meta-information for each file store      *  - The meta-information for each file stored on disk: size,
  *    permissions, ... (struct sos_fs_node for      *    permissions, ... (struct sos_fs_node for SOS, inode for Unix)
  *                                                  *
  *    It is sufficient to know where this meta      *    It is sufficient to know where this meta-information is located
  *    on disk (a simple sector number most of       *    on disk (a simple sector number most of the time) to build the
  *    corresponding struct sos_fs_node into me      *    corresponding struct sos_fs_node into memory and to retrieve the
  *    data of the file from the disk                *    data of the file from the disk
  *                                                  *
  *    For example, consider that we know a sec      *    For example, consider that we know a sector that holds the meta
  *    information is located at sector 64589 o      *    information is located at sector 64589 on disk. By retrieving
  *    this meta information directly from disk      *    this meta information directly from disk, we can build the
  *    struct sos_fs_node, which would (for exa      *    struct sos_fs_node, which would (for example) tell that the
  *    corresponding file spans (for example) o      *    corresponding file spans (for example) over sectors 4345, 5645,
  *    4539 and 6575, is 1.7kB long                  *    4539 and 6575, is 1.7kB long
  *                                                  *
  *    Everything is stored this way on the dis      *    Everything is stored this way on the disk, even the
  *    directories. From the disk contents' poi      *    directories. From the disk contents' point of view, a directory
  *    is simply a file whose contents represen      *    is simply a file whose contents represent a list of mappings
  *    "name" -> meta-information location           *    "name" -> meta-information location
  *                                                  *
  *  - One or many nodes in the file hierarchy       *  - One or many nodes in the file hierarchy pointing to this data
  *    (struct sos_fs_nscache_node for SOS, str      *    (struct sos_fs_nscache_node for SOS, struct dentry for Linux). This
  *    tells that the entry "toto" in directory      *    tells that the entry "toto" in directory "/home/zorglub"
  *    corresponds to the given struct sos_fs_n      *    corresponds to the given struct sos_fs_node
  *                                                  *
  *    Actually, with the struct sos_fs_node ab      *    Actually, with the struct sos_fs_node above, we can reach any
  *    file in the system. However, dealing wit      *    file in the system. However, dealing with mountpoints requires
  *    an intermediary data structure because a      *    an intermediary data structure because a directory on a disk
  *    cannot make reference to children struct      *    cannot make reference to children struct sos_fs_node on other
  *    disk. This is one of the reasons why the      *    disk. This is one of the reasons why there is this struct
  *    sos_fs_nscache_node. Another reason is t      *    sos_fs_nscache_node. Another reason is that we kind-of "cache" the
  *    most used struct sos_fs_node: those that      *    most used struct sos_fs_node: those that lead from the global
  *    root ("/") to the files and directories       *    root ("/") to the files and directories currently being used
  *    (hence the name "nscache" for "namespace      *    (hence the name "nscache" for "namespace cache"). This speeds-up
  *    the path-resolving process (aka "lookup"      *    the path-resolving process (aka "lookup"), as the most-used path
  *    are already in-memory and the struct sos      *    are already in-memory and the struct sos_fs_node are already
  *    in-memory too.                                *    in-memory too.
  *                                                  *
  *    A struct sos_fs_nscache_node can have at      *    A struct sos_fs_nscache_node can have at most 1 parent (the ".."
  *    entry). It can also have 0 parent in cas      *    entry). It can also have 0 parent in case the node is being used
  *    by a process (file is opened or mapped),      *    by a process (file is opened or mapped), but the file is
  *    actually "removed", ie un-reachable from      *    actually "removed", ie un-reachable from any directory.
  *                                                  *
  *    Many such structures can reference the s      *    Many such structures can reference the same underlying struct
  *    sos_fs_node, which enables the support o      *    sos_fs_node, which enables the support of "hard links".
  *                                                  *
  *  - The "opened file" strucures. They store       *  - The "opened file" strucures. They store the information
  *    pertaining to a particular usage of a fi      *    pertaining to a particular usage of a file. The most important
  *    thing they store is the "file pointer",       *    thing they store is the "file pointer", which holds the
  *    location in the file where the next read      *    location in the file where the next read/write operation should
  *    start                                         *    start
  *                                                  *
  *    Each process has at least 2 such opened       *    Each process has at least 2 such opened files: its "current
  *    working directory" (RTFM chdir) and its       *    working directory" (RTFM chdir) and its "process root" (RTFM
  *    chroot). Those are heritated across fork      *    chroot). Those are heritated across fork() and can be changed by
  *    appropriate syscalls (resp. chdir/chroot      *    appropriate syscalls (resp. chdir/chroot). The main "root" of
  *    the system is the process root of the "i      *    the system is the process root of the "init" process. The usual
  *    opened files (think of open() and opendi      *    opened files (think of open() and opendir()) are stored in the
  *    file descriptor array (fds[]). This is t      *    file descriptor array (fds[]). This is the index in this array
  *    that is commonly called a "file descript      *    that is commonly called a "file descriptor".
  *                                                  *
  *                                                  *
  * The whole VFS layer comprises a series of o      * The whole VFS layer comprises a series of objects that can be
  * specialized to implement different FS suppo      * specialized to implement different FS support (fat, ext2, ffs, ...):
  *                                                  *
  *  - The notion of "file system manager", whi      *  - The notion of "file system manager", which basically is a
  *    container to a FS name (eg "FAT", "EXT2"      *    container to a FS name (eg "FAT", "EXT2", etc...) and a series of
  *    functions responsible for initializing a      *    functions responsible for initializing a particular "mounting" of
  *    a FS (the "mount" method). This is SOS's      *    a FS (the "mount" method). This is SOS's struct sos_fs_manager_type
  *                                                  *
  *  - The notion of "file system instance" whi      *  - The notion of "file system instance" which contains the data
  *    proper to a particular mounting of an FS      *    proper to a particular mounting of an FS. Its most important job
  *    is to allocate new struct sos_fs_node on      *    is to allocate new struct sos_fs_node on disk, or to retrieve the
  *    meta-information (ie struct sos_fs_node)      *    meta-information (ie struct sos_fs_node) located at the given
  *    location on disk. This is roughly THE pr      *    location on disk. This is roughly THE primary physical interface
  *    between the VFS and the disks. This is S      *    between the VFS and the disks. This is SOS's struct
  *    sos_fs_manager_instance, aka the Linux's      *    sos_fs_manager_instance, aka the Linux's superblock
  *                                                  *
  *    For each struct sos_fs_node that it allo      *    For each struct sos_fs_node that it allocates, or that is loads
  *    from disk into memory, this "instance ma      *    from disk into memory, this "instance manager" is responsible
  *    for inidicating the functions that imple      *    for inidicating the functions that implement the FS-dedicated
  *    routine such as read/write/mmap/ioctl/..      *    routine such as read/write/mmap/ioctl/... for this precise node.
  *                                                  *
  *    The nodes (struct sos_fs_node) of a stru      *    The nodes (struct sos_fs_node) of a struct
  *    sos_fs_manager_instance that are current      *    sos_fs_manager_instance that are currently loaded in memory are
  *    stored in a hash-table. The key of this       *    stored in a hash-table. The key of this map is the location of the
  *    meta-information on disk. That way, it i      *    meta-information on disk. That way, it is very fast to look for
  *    the given meta-information whose locatio      *    the given meta-information whose location on disk is knows: if
  *    it has already been loaded into memory,       *    it has already been loaded into memory, its memory address is
  *    quickly resolved thanks to this hash tab      *    quickly resolved thanks to this hash table.
  */                                                 */
                                                    
 #include <sos/types.h>                             #include <sos/types.h>
 #include <sos/errno.h>                             #include <sos/errno.h>
 #include <sos/hash.h>                              #include <sos/hash.h>
 #include <sos/umem_vmm.h>                          #include <sos/umem_vmm.h>
                                                    
 /* Forward declarations (structures defined in     /* Forward declarations (structures defined in this file) */
 struct sos_fs_manager_type;                        struct sos_fs_manager_type;
 struct sos_fs_manager_instance;                    struct sos_fs_manager_instance;
 struct sos_fs_statfs;                              struct sos_fs_statfs;
 struct sos_fs_node;                                struct sos_fs_node;
 struct sos_fs_opened_file;                         struct sos_fs_opened_file;
 struct sos_fs_stat;                                struct sos_fs_stat;
                                                    
 #include "fs_nscache.h"                            #include "fs_nscache.h"
                                                   >>  #include <sos/blkdev.h>
                                                    
 /**                                                /**
  * The type of filesystem object.                   * The type of filesystem object.
  *                                                  *
  * Each struct sos_fs_node has a type. Here ar      * Each struct sos_fs_node has a type. Here are the supported types.
  */                                                 */
 typedef enum {                                     typedef enum {
   SOS_FS_NODE_REGULAR_FILE = 0x42,                   SOS_FS_NODE_REGULAR_FILE = 0x42,
   SOS_FS_NODE_DIRECTORY    = 0x24,                   SOS_FS_NODE_DIRECTORY    = 0x24,
   SOS_FS_NODE_SYMLINK      = 0x84,                   SOS_FS_NODE_SYMLINK      = 0x84,
   SOS_FS_NODE_DEVICE_CHAR  = 0x48,                   SOS_FS_NODE_DEVICE_CHAR  = 0x48,
                                                   >>    SOS_FS_NODE_DEVICE_BLOCK = 0x12
 } sos_fs_node_type_t;                              } sos_fs_node_type_t;
                                                    
                                                    
 #define SOS_FS_MANAGER_NAME_MAXLEN 32              #define SOS_FS_MANAGER_NAME_MAXLEN 32
 /**                                                /**
  * Description of a supported Filesystem type.      * Description of a supported Filesystem type.
  *                                                  *
  * These descriptions are listed in an interna      * These descriptions are listed in an internal list (see
  * fs.c:fs_list), and each time we want to mou      * fs.c:fs_list), and each time we want to mount a FS, we precise a
  * name (eg "FAT", "EXT2", ...). The VFS will       * name (eg "FAT", "EXT2", ...). The VFS will look for this name into
  * the list of supported filesystem types, and      * the list of supported filesystem types, and, when found, call its
  * sos_fs_manager_type::mount() method.             * sos_fs_manager_type::mount() method.
  *                                                  *
  * New filesystem types are registered using s      * New filesystem types are registered using sos_fs_register_fs_type()
  */                                                 */
 struct sos_fs_manager_type                         struct sos_fs_manager_type
 {                                                  {
   char name[SOS_FS_MANAGER_NAME_MAXLEN];             char name[SOS_FS_MANAGER_NAME_MAXLEN];
                                                    
   /**                                                /**
    * Responsible for making sure the underlyin        * Responsible for making sure the underlying device (if any) really
    * stores the correct filesystem format, for        * stores the correct filesystem format, for creating the hash of fs
    * nodes and for calling sos_fs_register_fs_        * nodes and for calling sos_fs_register_fs_instance
    *                                                  *
    * @param device May be NULL                        * @param device May be NULL
    *                                                  *
    * @note mandatory, may block                       * @note mandatory, may block
    */                                                 */
   sos_ret_t (*mount)(struct sos_fs_manager_typ       sos_ret_t (*mount)(struct sos_fs_manager_type * this,
                      struct sos_fs_node * devi                          struct sos_fs_node * device,
                      const char * args,                                 const char * args,
                      struct sos_fs_manager_ins                          struct sos_fs_manager_instance ** mounted_fs);
                                                      
   /**                                                /**
    * Responsible for de-allocating the hash of        * Responsible for de-allocating the hash of fs nodes and for
    * calling sos_fs_unregister_fs_instance            * calling sos_fs_unregister_fs_instance
    *                                                  *
    * @note mandatory, may block                       * @note mandatory, may block
    */                                                 */
   sos_ret_t (*umount)(struct sos_fs_manager_ty       sos_ret_t (*umount)(struct sos_fs_manager_type * this,
                       struct sos_fs_manager_in                           struct sos_fs_manager_instance * mounted_fs);
                                                    
   /** Free of use */                                 /** Free of use */
   void * custom_data;                                void * custom_data;
                                                    
   /** List of filesystem instances of this typ       /** List of filesystem instances of this type currently mounted
       somewhere in the system */                         somewhere in the system */
   struct sos_fs_manager_instance * instances;        struct sos_fs_manager_instance * instances;
                                                    
   /** Linkage for the list of filesystem types       /** Linkage for the list of filesystem types registered in the
       system */                                          system */
   struct sos_fs_manager_type *prev, *next;           struct sos_fs_manager_type *prev, *next;
 };                                                 };
                                                    
                                                    
 /**                                                /**
  * Data related to a particular "mounting" of       * Data related to a particular "mounting" of a file system. A
  * so-called "superblock" under Linux               * so-called "superblock" under Linux
  *                                                  *
  * This holds the FUNDAMENTAL functions respon      * This holds the FUNDAMENTAL functions responsible for loading struct
  * sos_fs_node from disk, or for allocating th      * sos_fs_node from disk, or for allocating thom on disk. It also
  * holds the hash-table of struct sos_fs_node       * holds the hash-table of struct sos_fs_node already loaded into
  * memory.                                          * memory.
  */                                                 */
 struct sos_fs_manager_instance                     struct sos_fs_manager_instance
 {                                                  {
   /**                                                /**
    * @note Publicly readable. Written only by         * @note Publicly readable. Written only by sos_fs_manager_type::mount()
    */                                                 */
   struct sos_fs_manager_type * fs_type;              struct sos_fs_manager_type * fs_type;
                                                    
   /**                                                /**
    * Usually, a filesystem relies on a device         * Usually, a filesystem relies on a device (disk, network, ram,
    * ...) to fetch its data. This is the locat        * ...) to fetch its data. This is the location of the device.
    *                                                  *
    * @note Publicly readable. Written only by         * @note Publicly readable. Written only by fs.c
    */                                                 */
   struct sos_fs_node * device;                       struct sos_fs_node * device;
                                                    
 #define SOS_FS_MOUNT_SYNC     (1 << 0)             #define SOS_FS_MOUNT_SYNC     (1 << 0)
 #define SOS_FS_MOUNT_READONLY (1 << 1)             #define SOS_FS_MOUNT_READONLY (1 << 1)
 #define SOS_FS_MOUNT_NOEXEC   (1 << 2)             #define SOS_FS_MOUNT_NOEXEC   (1 << 2)
   /**                                                /**
    * Is this FS read-only, without EXEC file p        * Is this FS read-only, without EXEC file permission, write-through
    * ? Or-red combination of the SOS_FS_MOUNT_        * ? Or-red combination of the SOS_FS_MOUNT_ flags
    *                                                  *
    * @note Publicly readable. Written only by         * @note Publicly readable. Written only by fs.c
    */                                                 */
   sos_ui32_t flags;                                  sos_ui32_t flags;
                                                    
   /**                                                /**
    * The namespace node that is the root of TH        * The namespace node that is the root of THIS file system mounting
    *                                                  *
    * @note Publicly readable. Written only by         * @note Publicly readable. Written only by fs.c
    */                                                 */
   struct sos_fs_nscache_node * root;                 struct sos_fs_nscache_node * root;
                                                    
   /**                                                /**
    * List of dirty nodes. These are the nodes         * List of dirty nodes. These are the nodes that need to be written
    * back to disk. With FS supporting deferred        * back to disk. With FS supporting deferred-writes, the
    * sos_fs_sync() function will use this list        * sos_fs_sync() function will use this list to flush the dirty
    * nodes back to disk.                              * nodes back to disk.
    *                                                  *
    * @note Reserved to fs.c                           * @note Reserved to fs.c
    */                                                 */
   struct sos_fs_node * dirty_nodes;                  struct sos_fs_node * dirty_nodes;
                                                    
   /**                                                /**
    * Build a fresh new FS node at the given lo        * Build a fresh new FS node at the given location. This implies
    * the allocation of a new sos_fs_node struc        * the allocation of a new sos_fs_node structure in memory
    *                                                  *
    * @note Mandatory, may block. Appropriate l        * @note Mandatory, may block. Appropriate locking MUST be implemented
    */                                                 */
   sos_ret_t (*fetch_node_from_disk)(struct sos       sos_ret_t (*fetch_node_from_disk)(struct sos_fs_manager_instance * this,
                                     sos_ui64_t                                         sos_ui64_t storage_location,
                                     struct sos                                         struct sos_fs_node ** result);
                                                    
   /**                                                /**
    * Build a fresh new FS node ON THE DISK of         * Build a fresh new FS node ON THE DISK of the given type (dir,
    * plain file, symlink, ...), completely emp        * plain file, symlink, ...), completely empty ; return a newly
    * allocated IN-MEMORY node structure repres        * allocated IN-MEMORY node structure representing it
    *                                                  *
    * @param open_creat_flags is the open_flags        * @param open_creat_flags is the open_flags parameter passed to
    * sos_fs_open() when O_CREAT is set. 0 when        * sos_fs_open() when O_CREAT is set. 0 when allocated trough
    * creat/mkdir/mknod/symlink                        * creat/mkdir/mknod/symlink
    *                                                  *
    * @note Mandatory, may block. Appropriate l        * @note Mandatory, may block. Appropriate locking MUST be implemented
    */                                                 */
   sos_ret_t (*allocate_new_node)(struct sos_fs       sos_ret_t (*allocate_new_node)(struct sos_fs_manager_instance * this,
                                  sos_fs_node_t                                      sos_fs_node_type_t type,
                                  const struct                                       const struct sos_process * creator,
                                  sos_ui32_t ac                                      sos_ui32_t access_rights,
                                  sos_ui32_t op                                      sos_ui32_t open_creat_flags,
                                  struct sos_fs                                      struct sos_fs_node ** result);
                                                    
   /**                                                /**
    * Return filesystem status (RTFM df)               * Return filesystem status (RTFM df)
    *                                                  *
    * @note Optional, may block. Appropriate lo        * @note Optional, may block. Appropriate locking MUST be implemented
    */                                                 */
   sos_ret_t (*statfs)(struct sos_fs_manager_in       sos_ret_t (*statfs)(struct sos_fs_manager_instance * this,
                       struct sos_fs_statfs * r                           struct sos_fs_statfs * result);
                                                    
   /**                                                /**
    * Comparison callback called when looking f        * Comparison callback called when looking for file/dirs in the
    * namespace cache. Normally, a usual lexico        * namespace cache. Normally, a usual lexicographical comparison is
    * done (when this function points to NULL).        * done (when this function points to NULL). But for some FS, it
    * might be useful to use another comparison        * might be useful to use another comparison function (eg for
    * case-insensitive FS)                             * case-insensitive FS)
    *                                                  *
    * @note Optional (may be NULL), must NOT bl        * @note Optional (may be NULL), must NOT block
    */                                                 */
   sos_bool_t (*nsnode_same_name)(const char *        sos_bool_t (*nsnode_same_name)(const char * name1, sos_ui16_t namelen1,
                                  const char *                                       const char * name2, sos_ui16_t namelen2);
                                                    
   /**                                                /**
    * Hash table of the struct sos_fs_node of t        * Hash table of the struct sos_fs_node of this filesystem instance
    * loaded in memory: key=storage_location, e        * loaded in memory: key=storage_location, element=sos_fs_node
    */                                                 */
   struct sos_hash_table * nodecache;                 struct sos_hash_table * nodecache;
                                                    
   /**                                                /**
    * Unique identifier of this FS (used in syn        * Unique identifier of this FS (used in sync method, updated by
    * fs.c). This enables sync_all_fs to be res        * fs.c). This enables sync_all_fs to be resilient to mount/umount
    * and (un)register_fs_type/instance                * and (un)register_fs_type/instance
    */                                                 */
   sos_ui64_t uid;                                    sos_ui64_t uid;
                                                    
   void * custom_data;                                void * custom_data;
                                                    
   /** Linkage for the list of instances for th       /** Linkage for the list of instances for the underlying fs type */
   struct sos_fs_manager_instance * prev, * nex       struct sos_fs_manager_instance * prev, * next;
 };                                                 };
                                                    
                                                    
 /**                                                /**
  * The CENTRAL data structure of the whole thi      * The CENTRAL data structure of the whole thing. A so-called "inode"
  *                                                  *
  * This represents the meta-information relate      * This represents the meta-information related to a file on disk: its
  * permission, where its data is located. Actu      * permission, where its data is located. Actually, in SOS, these
  * information are not stored in this structur      * information are not stored in this structure. Instead, we define a
  * series of methods in this structure that MU      * series of methods in this structure that MUST be implemented by the
  * FS and that realize the higher level operat      * FS and that realize the higher level operations needed by the
  * OS. These operations will rely on the meta-      * OS. These operations will rely on the meta-information that the FS
  * code MUST define and manage by itself (henc      * code MUST define and manage by itself (hence the
  * sos_fs_node::custom_data field).                 * sos_fs_node::custom_data field).
  */                                                 */
 struct sos_fs_node                                 struct sos_fs_node
 {                                                  {
   /**                                                /**
    * An struct sos_fs_node always belong to ex        * An struct sos_fs_node always belong to exactly ONE file system
    */                                                 */
   struct sos_fs_manager_instance * fs;               struct sos_fs_manager_instance * fs;
                                                    
   /**                                                /**
    * The so-called "inode": location of this n        * The so-called "inode": location of this node inside the FS
    * instance. Updated by struct                      * instance. Updated by struct
    * sos_fs_manager_instance::fetch_node_from_        * sos_fs_manager_instance::fetch_node_from_disk()
    */                                                 */
   sos_ui64_t storage_location;                       sos_ui64_t storage_location;
                                                    
   /**                                                /**
    * Number of ON-DISK links to this node.            * Number of ON-DISK links to this node.
    *                                                  *
    * - For everything but directories: the num        * - For everything but directories: the number of hard links to the file
    * - For directories: 1 + the number of chil        * - For directories: 1 + the number of children nodes
    *                                                  *
    * @note Publicly readable. Written only by         * @note Publicly readable. Written only by
    * sos_fs_node_ops_dir::link() and sos_fs_no        * sos_fs_node_ops_dir::link() and sos_fs_node_ops_dir::unlink()
    */                                                 */
   sos_count_t ondisk_lnk_cnt;                        sos_count_t ondisk_lnk_cnt;
                                                    
   /**                                                /**
    * Number of IN-MEMORY nscache_nodes referen        * Number of IN-MEMORY nscache_nodes referencing this FS node.
    *                                                  *
    * Corresponds to the number of struct sos_f        * Corresponds to the number of struct sos_fs_nscache_node pointing
    * to this node. This could be as much as on        * to this node. This could be as much as ondisk_lnk_cnt + 1, but is
    * usually less                                     * usually less
    *                                                  *
    * @note Reserved to fs.c                           * @note Reserved to fs.c
    */                                                 */
   sos_count_t inmem_ref_cnt;                         sos_count_t inmem_ref_cnt;
                                                    
   /**                                                /**
    * Directory, symlink, ...                          * Directory, symlink, ...
    *                                                  *
    * @see sos_fs_node_type_t                          * @see sos_fs_node_type_t
    *                                                  *
    * @note Publicly readable. Written only by         * @note Publicly readable. Written only by fs.c
    */                                                 */
   sos_fs_node_type_t type;                           sos_fs_node_type_t type;
                                                    
 #define SOS_FS_READABLE          00400             #define SOS_FS_READABLE          00400
 #define SOS_FS_WRITABLE          00200             #define SOS_FS_WRITABLE          00200
 #define SOS_FS_EXECUTABLE        00100             #define SOS_FS_EXECUTABLE        00100
   /**                                                /**
    * read/write, ... @see the SOS_FS_*ABLE fla        * read/write, ... @see the SOS_FS_*ABLE flags
    * @note Publicly readable. Written only by         * @note Publicly readable. Written only by fs.c
    */                                                 */
   sos_ui32_t access_rights;                          sos_ui32_t access_rights;
                                                    
   /**                                                /**
    * @note Reserved to fs.c                           * @note Reserved to fs.c
    */                                                 */
   sos_bool_t dirty;                                  sos_bool_t dirty;
                                                    
   /**                                                /**
    * Incremented each time one of the opened f        * Incremented each time one of the opened files for this node is
    * modified                                         * modified
    * @note Publicly readable. Written only by         * @note Publicly readable. Written only by fs.c
    */                                                 */
   sos_lcount_t generation;                           sos_lcount_t generation;
                                                    
   /**                                                /**
    * @note Available only for device files (ch        * @note Available only for device files (char/block)
    * @note Publicly readable. Written only by         * @note Publicly readable. Written only by
    * sos_fs_manager_instance::fetch_node_from_        * sos_fs_manager_instance::fetch_node_from_disk() and mknod()
    */                                                 */
   struct sos_fs_dev_id_t                             struct sos_fs_dev_id_t
   {                                                  {
     sos_ui32_t device_class;    /**< aka "majo         sos_ui32_t device_class;    /**< aka "major" */
     sos_ui32_t device_instance; /**< aka "mino         sos_ui32_t device_instance; /**< aka "minor" */
   } dev_id;                                          } dev_id;
                                                    
   /** Operations common to all node types */         /** Operations common to all node types */
   struct sos_fs_node_ops_file  *ops_file;            struct sos_fs_node_ops_file  *ops_file;
                                                    
   /** Operations specific to some node types *       /** Operations specific to some node types */
   union                                              union
   {                                                  {
     /** when type == SOS_FS_NODE_DIRECTORY */          /** when type == SOS_FS_NODE_DIRECTORY */
     struct sos_fs_node_ops_dir      *ops_dir;          struct sos_fs_node_ops_dir      *ops_dir;
                                                    
                                                   >>      /**
                                                   >>       * when type == SOS_FS_NODE_DEVICE_BLOCK
                                                   >>       * The FS node has a link to some data pertaining to the device,
                                                   >>       * not to any special operations
                                                   >>       * @see blkdev.c for a definition of this structure
                                                   >>       */
                                                   >>      struct sos_blockdev_instance *block_device;
                                                   >>  
     /** when type == SOS_FS_NODE_SYMLINK */            /** when type == SOS_FS_NODE_SYMLINK */
     struct sos_fs_node_ops_symlink  *ops_symli         struct sos_fs_node_ops_symlink  *ops_symlink;
   }; /* Anonymous union (gcc extension) */           }; /* Anonymous union (gcc extension) */
                                                    
                                                    
   /**                                                /**
    * Flush any change to disk                  << 
    *                                           << 
    * @note Mandatory, may block. Appropriate l << 
    */                                          << 
   sos_ret_t (*sync)(struct sos_fs_node *this); << 
                                                << 
                                                << 
   /**                                          << 
    * Simply free this FS node from the kernel         * Simply free this FS node from the kernel memory: it does NOT
    * mean that the corresponding on-disk node         * mean that the corresponding on-disk node is free ! Actually, the
    * corresponding ON-DISK node is free iff on        * corresponding ON-DISK node is free iff ondisk_lnk_cnt == 0. No
    * need to sync anything to disk, as the VFS        * need to sync anything to disk, as the VFS will sync the node
    * before calling this method                       * before calling this method
    *                                                  *
    * @note Mandatory, may block, no special lo        * @note Mandatory, may block, no special locking needed
    */                                                 */
   sos_ret_t (*destructor)(struct sos_fs_node *       sos_ret_t (*destructor)(struct sos_fs_node * this);
                                                    
   /**                                                /**
    * Called when a process opens the node             * Called when a process opens the node
    *                                                  *
    * @note Mandatory, may block. Appropriate l        * @note Mandatory, may block. Appropriate locking MUST be implemented
    * @note FS-specific EXCPET for device speci        * @note FS-specific EXCPET for device special files (char &
    * block) because they are handled in an uni        * block) because they are handled in an uniform way by the
    * chardev/blockdev subsystems                      * chardev/blockdev subsystems
    * @note As a consequence, FS code can safel        * @note As a consequence, FS code can safely assume that "this" is
    * never a character or block device                * never a character or block device
    */                                                 */
   sos_ret_t (*new_opened_file)(struct sos_fs_n       sos_ret_t (*new_opened_file)(struct sos_fs_node * this,
                                const struct so                                    const struct sos_process * owner,
                                sos_ui32_t open                                    sos_ui32_t open_flags,
                                struct sos_fs_o                                    struct sos_fs_opened_file ** result_of);
                                                    
   /**                                                /**
    * Called when a process opens the node             * Called when a process opens the node
    *                                                  *
    * @note Mandatory, may block. Appropriate l        * @note Mandatory, may block. Appropriate locking MUST be implemented
    * @note FS-specific EXCEPT for device speci        * @note FS-specific EXCEPT for device special files (char &
    * block) because they are handled in an uni        * block) because they are handled in an uniform way by the
    * chardev/blockdev subsystems                      * chardev/blockdev subsystems
    * @note As a consequence, FS code can safel        * @note As a consequence, FS code can safely assume that "this" is
    * never a character or block device                * never a character or block device
    */                                                 */
   sos_ret_t (*close_opened_file)(struct sos_fs       sos_ret_t (*close_opened_file)(struct sos_fs_node * this,
                                  struct sos_fs                                      struct sos_fs_opened_file * of);
                                                    
   /**                                                /**
    * This should hold the meta information for        * This should hold the meta information for this node as needed by
    * the FS instance.                                 * the FS instance.
    */                                                 */
   void * custom_data;                                void * custom_data;
                                                    
   /** Hash linkage entry for this FS node in t       /** Hash linkage entry for this FS node in the nodecache
      dictionary */                                      dictionary */
   struct sos_hash_linkage hlink_nodecache;           struct sos_hash_linkage hlink_nodecache;
                                                    
   /** Linkage to list the dirty nodes of the g       /** Linkage to list the dirty nodes of the given FS */
   struct sos_fs_node *prev_dirty, *next_dirty;       struct sos_fs_node *prev_dirty, *next_dirty;
 };                                                 };
                                                    
                                                    
                                                    
 /**                                                /**
  * The list of methods implementing the basic       * The list of methods implementing the basic VFS operations on the
  * given struct sos_fs_node                         * given struct sos_fs_node
  *                                                  *
  * @see sos_fs_node::ops_file                       * @see sos_fs_node::ops_file
  */                                                 */
 struct sos_fs_node_ops_file                        struct sos_fs_node_ops_file
 {                                                  {
   /**                                                /**
    * Change size of file                              * Change size of file
    *                                                  *
    * @note Optional, may block. Appropriate lo        * @note Optional, may block. Appropriate locking MUST be implemented
    */                                                 */
   sos_ret_t (*truncate)(struct sos_fs_node *th       sos_ret_t (*truncate)(struct sos_fs_node *this,
                         sos_lsoffset_t length)                             sos_lsoffset_t length);
                                                    
   /**                                                /**
    * Retrieve the status (eg size) of the file        * Retrieve the status (eg size) of the file
    *                                                  *
    * @note Mandatory, may block. Appropriate l        * @note Mandatory, may block. Appropriate locking MUST be implemented
    */                                                 */
   sos_ret_t (*stat)(struct sos_fs_node * this,       sos_ret_t (*stat)(struct sos_fs_node * this,
                     struct sos_fs_stat * resul                         struct sos_fs_stat * result);
                                                    
   /**                                                /**
    * Change the sos_fs_node::access_rights att        * Change the sos_fs_node::access_rights attribute
    *                                                  *
    * @note Mandatory, may block. Appropriate l        * @note Mandatory, may block. Appropriate locking MUST be implemented
    */                                                 */
   sos_ret_t (*chmod)(struct sos_fs_node * this       sos_ret_t (*chmod)(struct sos_fs_node * this,
                      sos_ui32_t new_access_rig                          sos_ui32_t new_access_rights);
                                                   >>  
                                                   >>  
                                                   >>    /**
                                                   >>     * Flush any change to the node back to the file system backing store
                                                   >>     *
                                                   >>     * @note Mandatory, may block. Appropriate locking MUST be implemented
                                                   >>     */
                                                   >>    sos_ret_t (*sync)(struct sos_fs_node *this);
 };                                                 };
                                                    
                                                    
 /**                                                /**
  * The list of methods implementing the basic       * The list of methods implementing the basic VFS symlink operations
  *                                                  *
  * @see sos_fs_node::ops_symlink                    * @see sos_fs_node::ops_symlink
  */                                                 */
 struct sos_fs_node_ops_symlink                     struct sos_fs_node_ops_symlink
 {                                                  {
   /**                                                /**
    * Used by the _kernel_ to resolve the symli        * Used by the _kernel_ to resolve the symlinks. To change/create a
    * symlink target, it is needed only from us        * symlink target, it is needed only from userland: the read/write
    * methods are made for this                        * methods are made for this
    *                                                  *
    * @param target Pointer to the string repre        * @param target Pointer to the string representing the target's
    * path, allocated for the fs_node's lifetim        * path, allocated for the fs_node's lifetime !
    *                                                  *
    * @note Mandatory, may block. Appropriate l        * @note Mandatory, may block. Appropriate locking MUST be implemented
    */                                                 */
   sos_ret_t (*expand)(struct sos_fs_node *this       sos_ret_t (*expand)(struct sos_fs_node *this,
                       char const  ** target,                             char const  ** target,
                       sos_size_t * target_len)                           sos_size_t * target_len);
 };                                                 };
                                                    
                                                    
 /**                                                /**
  * The list of methods implementing the basic       * The list of methods implementing the basic VFS directory operations
  *                                                  *
  * @see sos_fs_node::ops_dir                        * @see sos_fs_node::ops_dir
  */                                                 */
 struct sos_fs_node_ops_dir                         struct sos_fs_node_ops_dir
 {                                                  {
   /**                                                /**
    * Look for the on-disk location of the sos_        * Look for the on-disk location of the sos_fs_node having the given
    * name                                             * name
    *                                                  *
    * @note Mandatory, may block. Appropriate l        * @note Mandatory, may block. Appropriate locking MUST be implemented
    */                                                 */
   sos_ret_t (*lookup)(struct sos_fs_node *this       sos_ret_t (*lookup)(struct sos_fs_node *this,
                       const char * name, sos_u                           const char * name, sos_ui16_t namelen,
                       sos_ui64_t * result_stor                           sos_ui64_t * result_storage_location);
                                                    
   /**                                                /**
    * Add a new reference in the current sos_fs        * Add a new reference in the current sos_fs_node to the on-disk
    * location of the given sos_fs_node                * location of the given sos_fs_node
    *                                                  *
    * @note Responsible for updating this->ondi        * @note Responsible for updating this->ondisk_lnk_cnt
    * @note Mandatory for writable directories,        * @note Mandatory for writable directories, may block. Appropriate
    * locking MUST be implemented                      * locking MUST be implemented
    */                                                 */
   sos_ret_t (*link)(struct sos_fs_node *this,        sos_ret_t (*link)(struct sos_fs_node *this,
                     const struct sos_process *                         const struct sos_process *actor,
                     const char * entry_name, s                         const char * entry_name, sos_ui16_t entry_namelen,
                     struct sos_fs_node * node)                         struct sos_fs_node * node);
                                                    
   /**                                                /**
    * Remove the entry in the current sos_fs_no        * Remove the entry in the current sos_fs_node for the on-disk
    * location with the given name                     * location with the given name
    *                                                  *
    * @note Responsible for updating this->ondi        * @note Responsible for updating this->ondisk_lnk_cnt
    * @note Mandatory for writable directories,        * @note Mandatory for writable directories, may block. Appropriate
    * locking MUST be implemented                      * locking MUST be implemented
    */                                                 */
   sos_ret_t (*unlink)(struct sos_fs_node *this       sos_ret_t (*unlink)(struct sos_fs_node *this,
                       const struct sos_process                           const struct sos_process *actor,
                       const char * entry_name,                           const char * entry_name, sos_ui16_t entry_namelen);
 };                                                 };
                                                    
                                                    
 /**                                                /**
  * The data structure holding information and       * The data structure holding information and method related to a
  * particular usage of a file. A so-called "st      * particular usage of a file. A so-called "struct file"
  *                                                  *
  * This represents the kernel structure behind      * This represents the kernel structure behind a "file descriptor" or
  * behind a chdir/chroot. Among other things,       * behind a chdir/chroot. Among other things, it holds the methods
  * responsible for reading/writing into the fi      * responsible for reading/writing into the file, and for moving the
  * file pointer (see @sos_fs_opened_file::posi      * file pointer (see @sos_fs_opened_file::position) inside it.
  */                                                 */
 struct sos_fs_opened_file                          struct sos_fs_opened_file
 {                                                  {
   /** The process that opened the file/dir */        /** The process that opened the file/dir */
   const struct sos_process * owner;                  const struct sos_process * owner;
                                                    
   /**                                                /**
    * The reference to the sos_fs_nscache_node         * The reference to the sos_fs_nscache_node and, hence, to the underlying sos_fs_node.
    *                                                  *
    * Used to cache the in-memory fs nodes             * Used to cache the in-memory fs nodes
    */                                                 */
   struct sos_fs_nscache_node * direntry;             struct sos_fs_nscache_node * direntry;
                                                    
   /** Use for memory-management */                   /** Use for memory-management */
   sos_count_t ref_cnt;                               sos_count_t ref_cnt;
                                                    
   /**                                                /**
    * Always > 0 (ie max size = 2^63-1 = 9.2 10        * Always > 0 (ie max size = 2^63-1 = 9.2 10^18). We make it
    * "signed" here to limit its range. Because        * "signed" here to limit its range. Because we must be able to
    * seek to the begining of the file with SEE        * seek to the begining of the file with SEEK_END and a negative
    * offset, so the max size of the file must         * offset, so the max size of the file must be reachable by a lseek
    * offset                                           * offset
    *                                                  *
    * @note reserved to filesystem instance cod        * @note reserved to filesystem instance code. Not modified nor used
    * by fs.c                                          * by fs.c
    */                                                 */
   sos_lsoffset_t     position;                       sos_lsoffset_t     position;
                                                    
   /**                                                /**
    * Incremented each time this opened file is        * Incremented each time this opened file is modified
    *                                                  *
    * Used to implement a readdir method resili        * Used to implement a readdir method resilient to
    * creat/mkdir/rmdir/unlink                         * creat/mkdir/rmdir/unlink
    */                                                 */
   sos_lcount_t generation;                           sos_lcount_t generation;
                                                    
   /**                                                /**
    * @see SOS_FS_OPEN_* flags                         * @see SOS_FS_OPEN_* flags
    */                                                 */
   sos_ui32_t open_flags;                             sos_ui32_t open_flags;
                                                    
   /** Operations common to all node types */         /** Operations common to all node types */
   struct sos_fs_ops_opened_file * ops_file;          struct sos_fs_ops_opened_file * ops_file;
                                                    
   /** Operations specific to some node types *       /** Operations specific to some node types */
   union                                              union
   {                                                  {
     /** when direntry->fs_node->type == SOS_FS         /** when direntry->fs_node->type == SOS_FS_NODE_DIRECTORY */
     struct sos_fs_ops_opened_dir      * ops_di         struct sos_fs_ops_opened_dir      * ops_dir;
                                                    
     /** when direntry->fs_node->type == SOS_FS         /** when direntry->fs_node->type == SOS_FS_NODE_DEVICE_CHAR */
     struct sos_fs_ops_opened_chardev  * ops_ch         struct sos_fs_ops_opened_chardev  * ops_chardev;
                                                   >>  
                                                   >>      /** when direntry->fs_node->type == SOS_FS_NODE_DEVICE_BLOCK */
                                                   >>      struct sos_fs_ops_opened_blockdev * ops_blockdev;
   }; /* Anonymous union (gcc extension) */           }; /* Anonymous union (gcc extension) */
                                                    
   /**                                                /**
    * Called upon fork() to duplicate all the o        * Called upon fork() to duplicate all the opened files
    *                                                  *
    * @note FS-specific EXCEPT for device speci        * @note FS-specific EXCEPT for device special files (char &
    * block) because they are handled in an uni        * block) because they are handled in an uniform way by the
    * chardev/blockdev subsystems                      * chardev/blockdev subsystems
    * @note As a consequence, FS code can safel        * @note As a consequence, FS code can safely assume that "this" is
    * never a character or block device                * never a character or block device
    */                                                 */
   sos_ret_t (*duplicate)(struct sos_fs_opened_       sos_ret_t (*duplicate)(struct sos_fs_opened_file *this,
                          const struct sos_proc                              const struct sos_process  * for_owner,
                          struct sos_fs_opened_                              struct sos_fs_opened_file **result);
                                                    
   void * custom_data;                                void * custom_data;
 };                                                 };
                                                    
                                                    
 /**                                                /**
  * Reference position for sos_fs_seek               * Reference position for sos_fs_seek
  */                                                 */
 typedef enum { SOS_SEEK_SET=42,                    typedef enum { SOS_SEEK_SET=42,
                SOS_SEEK_CUR=24,                                   SOS_SEEK_CUR=24,
                SOS_SEEK_END=84 } sos_seek_when                    SOS_SEEK_END=84 } sos_seek_whence_t;
 /**                                                /**
  * The list of methods implementing the basic       * The list of methods implementing the basic VFS opened file
  * operations                                       * operations
  *                                                  *
  * See the Unix manual pages, they basically f      * See the Unix manual pages, they basically form the interfaces to to
  * these functions                                  * these functions
  *                                                  *
  * @see sos_fs_opened_file::ops_file                * @see sos_fs_opened_file::ops_file
  */                                                 */
 struct sos_fs_ops_opened_file                      struct sos_fs_ops_opened_file
 {                                                  {
   /**                                                /**
    * @note Mandatory, may block. Appropriate l        * @note Mandatory, may block. Appropriate locking MUST be implemented
    * @note Please call sos_fs_mark_dirty() if         * @note Please call sos_fs_mark_dirty() if disk contents is changed
    */                                                 */
   sos_ret_t (*seek)(struct sos_fs_opened_file        sos_ret_t (*seek)(struct sos_fs_opened_file *this,
                     sos_lsoffset_t offset,                             sos_lsoffset_t offset,
                     sos_seek_whence_t whence,                          sos_seek_whence_t whence,
                     /* out */ sos_lsoffset_t *                         /* out */ sos_lsoffset_t * result_position);
                                                    
   /**                                                /**
    * @note Mandatory, may block. Appropriate l        * @note Mandatory, may block. Appropriate locking MUST be implemented
    * @note Please call sos_fs_mark_dirty() if         * @note Please call sos_fs_mark_dirty() if disk contents is changed
    */                                                 */
   sos_ret_t (*read)(struct sos_fs_opened_file        sos_ret_t (*read)(struct sos_fs_opened_file *this,
                     sos_uaddr_t dest_buf,                              sos_uaddr_t dest_buf,
                     sos_size_t * /* in/out */l                         sos_size_t * /* in/out */len);
                                                    
   /**                                                /**
    * @note Optional (might be NULL), may block        * @note Optional (might be NULL), may block. Appropriate locking
    * MUST be implemented                              * MUST be implemented
    * @note Please call sos_fs_mark_dirty() if         * @note Please call sos_fs_mark_dirty() if disk contents is changed
    */                                                 */
   sos_ret_t (*write)(struct sos_fs_opened_file       sos_ret_t (*write)(struct sos_fs_opened_file *this,
                      sos_uaddr_t src_buf,                               sos_uaddr_t src_buf,
                      sos_size_t * /* in/out */                          sos_size_t * /* in/out */len);
                                                    
   /**                                                /**
    * @note Optional (might be NULL), may block        * @note Optional (might be NULL), may block. Appropriate locking
    * MUST be implemented                              * MUST be implemented
    * @note Please call sos_fs_mark_dirty() if         * @note Please call sos_fs_mark_dirty() if disk contents is changed
    */                                                 */
   sos_ret_t (*mmap)(struct sos_fs_opened_file        sos_ret_t (*mmap)(struct sos_fs_opened_file *this,
                     sos_uaddr_t *uaddr, sos_si                         sos_uaddr_t *uaddr, sos_size_t size,
                     sos_ui32_t access_rights,                          sos_ui32_t access_rights,
                     sos_ui32_t flags,                                  sos_ui32_t flags,
                     sos_luoffset_t offset);                            sos_luoffset_t offset);
                                                    
   /**                                                /**
    * @note Optional (might be NULL), may block        * @note Optional (might be NULL), may block. Appropriate locking
    * MUST be implemented                              * MUST be implemented
    * @note Please call sos_fs_mark_dirty() if         * @note Please call sos_fs_mark_dirty() if disk contents is changed
    */                                                 */
   sos_ret_t (*fcntl)(struct sos_fs_opened_file       sos_ret_t (*fcntl)(struct sos_fs_opened_file *this,
                      int req_id,                                        int req_id,
                      sos_ui32_t req_arg /* Usu                          sos_ui32_t req_arg /* Usually: sos_uaddr_t */);
 };                                                 };
                                                    
                                                    
 /**                                                /**
  * The list of methods implementing the basic       * The list of methods implementing the basic VFS opened character device
  * operations                                       * operations
  *                                                  *
  * @see sos_fs_opened_file::ops_file                * @see sos_fs_opened_file::ops_file
  */                                                 */
 struct sos_fs_ops_opened_chardev                   struct sos_fs_ops_opened_chardev
 {                                                  {
   /**                                                /**
    * @note Optional (might be NULL), may block        * @note Optional (might be NULL), may block. Appropriate locking
    * MUST be implemented                              * MUST be implemented
    * @note Please call sos_fs_mark_dirty() if         * @note Please call sos_fs_mark_dirty() if disk contents is changed
    */                                                 */
   sos_ret_t (*ioctl)(struct sos_fs_opened_file       sos_ret_t (*ioctl)(struct sos_fs_opened_file *this,
                      int req_id,                                        int req_id,
                      sos_ui32_t req_arg /* Usu                          sos_ui32_t req_arg /* Usually: sos_uaddr_t */);
 };                                                 };
                                                    
                                                    
                                                   >>  /**
                                                   >>   * The list of methods implementing the basic VFS opened block device
                                                   >>   * operations
                                                   >>   *
                                                   >>   * @see sos_fs_opened_file::ops_file
                                                   >>   */
                                                   >>  struct sos_fs_ops_opened_blockdev
                                                   >>  {
                                                   >>    /**
                                                   >>     * @note Optional (might be NULL), may block. Appropriate locking
                                                   >>     * MUST be implemented
                                                   >>     * @note Please call sos_fs_mark_dirty() if disk contents is changed
                                                   >>     */
                                                   >>    sos_ret_t (*ioctl)(struct sos_fs_opened_file *this,
                                                   >>                       int req_id,
                                                   >>                       sos_ui32_t req_arg /* Usually: sos_uaddr_t */);
                                                   >>  };
                                                   >>  
                                                   >>  
 /** Data structure that is to be filled by rea     /** Data structure that is to be filled by readdir */
 struct sos_fs_dirent                               struct sos_fs_dirent
 {                                                  {
   sos_ui64_t storage_location;                       sos_ui64_t storage_location;
   sos_si64_t offset_in_dirfile;                      sos_si64_t offset_in_dirfile;
   sos_ui32_t type;                                   sos_ui32_t type;
   sos_ui16_t namelen;                                sos_ui16_t namelen;
                                                    
 #define SOS_FS_DIRENT_NAME_MAXLEN 128              #define SOS_FS_DIRENT_NAME_MAXLEN 128
   char       name[SOS_FS_DIRENT_NAME_MAXLEN];        char       name[SOS_FS_DIRENT_NAME_MAXLEN];
 };                                                 };
                                                    
                                                    
 /**                                                /**
  * The list of methods implementing the basic       * The list of methods implementing the basic VFS opened directory
  * operations                                       * operations
  *                                                  *
  * @see sos_fs_opened_file::ops_file                * @see sos_fs_opened_file::ops_file
  */                                                 */
 struct sos_fs_ops_opened_dir                       struct sos_fs_ops_opened_dir
 {                                                  {
   /**                                                /**
    * Each time it is called, responsible for f        * Each time it is called, responsible for filling the sos_fs_dirent
    * structure, return -SOS_ENOENT when done.         * structure, return -SOS_ENOENT when done.
    *                                                  *
    * @note Mandatory, may block. Appropriate l        * @note Mandatory, may block. Appropriate locking MUST be implemented
    * @note Please call sos_fs_mark_dirty() if         * @note Please call sos_fs_mark_dirty() if disk contents is changed
    */                                                 */
   sos_ret_t (*readdir)(struct sos_fs_opened_fi       sos_ret_t (*readdir)(struct sos_fs_opened_file *this,
                        struct sos_fs_dirent *                             struct sos_fs_dirent * result);
 };                                                 };
                                                    
                                                    
                                                    
 /**                                                /**
  * Used by the stat calls                           * Used by the stat calls
  *                                                  *
  * @see sos_fs_node_ops_file::stat                  * @see sos_fs_node_ops_file::stat
  */                                                 */
 struct sos_fs_stat                                 struct sos_fs_stat
 {                                                  {
   struct sos_fs_dev_id_t st_rdev;                    struct sos_fs_dev_id_t st_rdev;
   sos_fs_node_type_t     st_type;                    sos_fs_node_type_t     st_type;
   sos_ui64_t             st_storage_location;        sos_ui64_t             st_storage_location;
   sos_ui32_t             st_access_rights;           sos_ui32_t             st_access_rights;
   sos_count_t            st_nlink;                   sos_count_t            st_nlink;
   sos_si64_t             st_size;                    sos_si64_t             st_size;
 };                                                 };
                                                    
                                                    
 /**                                                /**
  * Used by the statvfs calls                        * Used by the statvfs calls
  *                                                  *
  * @see sos_fs_manager_instance::statfs             * @see sos_fs_manager_instance::statfs
  */                                                 */
 struct sos_fs_statfs                               struct sos_fs_statfs
 {                                                  {
   struct sos_fs_dev_id_t f_rdev;                     struct sos_fs_dev_id_t f_rdev;
   sos_size_t             f_sz_total;  /**< Tot       sos_size_t             f_sz_total;  /**< Total size */
   sos_size_t             f_sz_free;   /**< Siz       sos_size_t             f_sz_free;   /**< Size left on device */
   sos_count_t            f_node_total;/**< Tot       sos_count_t            f_node_total;/**< Total allocatable FS nodes */
   sos_count_t            f_node_avail;/**< Num       sos_count_t            f_node_avail;/**< Number of available free FS nodes */
   sos_ui32_t             f_flags;                    sos_ui32_t             f_flags;
 };                                                 };
                                                    
                                                    
 /**                                                /**
  * Must be called AFTER the FS manager types n      * Must be called AFTER the FS manager types needed to mount the root
  * filesystem have been registered                  * filesystem have been registered
  */                                                 */
 sos_ret_t sos_fs_subsystem_setup(const char *      sos_ret_t sos_fs_subsystem_setup(const char * root_device,
                                  const char *                                       const char * fs_type,
                                  const char *                                       const char * mount_args,
                                  struct sos_fs                                      struct sos_fs_manager_instance ** result_rootfs);
                                                    
                                                    
 /*  ******************************************     /*  ***************************************************************
  * The Following functions are relatively stan      * The Following functions are relatively standard
  *                                                  *
  * @see Unix manual pages for details               * @see Unix manual pages for details
  */                                                 */
                                                    
                                                    
 /**                                                /**
  * mount a file system                              * mount a file system
  *                                                  *
  * @param actor process calling mount               * @param actor process calling mount
  * @param _src_path(len) may be NULL (as for v      * @param _src_path(len) may be NULL (as for virtfs or /proc)
  * @fsname the name of the filesystem type to       * @fsname the name of the filesystem type to mount
  * @args any args passed to the sos_fs_manager      * @args any args passed to the sos_fs_manager_type::mount method
  * @result_fs the resulting filesystem instanc      * @result_fs the resulting filesystem instance
  */                                                 */
 sos_ret_t sos_fs_mount(struct sos_process * ac     sos_ret_t sos_fs_mount(struct sos_process * actor,
                        const char * _src_path,                            const char * _src_path,
                        sos_size_t _src_pathlen                            sos_size_t _src_pathlen,
                        const char * _dst_path,                            const char * _dst_path,
                        sos_size_t _dst_pathlen                            sos_size_t _dst_pathlen,
                        const char * fsname,                               const char * fsname,
                        sos_ui32_t mountflags,                             sos_ui32_t mountflags,
                        const char * args,                                 const char * args,
                        struct sos_fs_manager_i                            struct sos_fs_manager_instance ** /*out*/result_fs);
                                                    
 /**                                                /**
  * unmount the filesystem at the given locatio      * unmount the filesystem at the given location
  */                                                 */
 sos_ret_t sos_fs_umount(struct sos_process * a     sos_ret_t sos_fs_umount(struct sos_process * actor,
                         const char * _mountpoi                             const char * _mountpoint_path,
                         sos_size_t _mountpoint                             sos_size_t _mountpoint_pathlen);
                                                    
 /**                                                /**
  * Flush all the dirty nodes of all the FS to       * Flush all the dirty nodes of all the FS to disk
  */                                                 */
 sos_ret_t sos_fs_sync_all_fs();                !!  sos_ret_t sos_fs_sync_all_fs(void);
                                                    
 /**                                                /**
  * Retrieve filesystem status, or return -SOS_      * Retrieve filesystem status, or return -SOS_ENOSYS if filesystem
  * cannot report this                               * cannot report this
  */                                                 */
 sos_ret_t sos_fs_vfstat(const struct sos_proce     sos_ret_t sos_fs_vfstat(const struct sos_process * actor,
                         const char * _path,                                const char * _path,
                         sos_size_t _pathlen,                               sos_size_t _pathlen,
                         struct sos_fs_statfs *                             struct sos_fs_statfs * result);
                                                    
 /**                                                /**
  * Open flags                                       * Open flags
  */                                                 */
 #define SOS_FS_OPEN_EXCL        (1 << 0)           #define SOS_FS_OPEN_EXCL        (1 << 0)
 #define SOS_FS_OPEN_CREAT       (1 << 1)           #define SOS_FS_OPEN_CREAT       (1 << 1)
 #define SOS_FS_OPEN_TRUNC       (1 << 2)           #define SOS_FS_OPEN_TRUNC       (1 << 2)
 #define SOS_FS_OPEN_NOFOLLOW    (1 << 3)           #define SOS_FS_OPEN_NOFOLLOW    (1 << 3)
 #define SOS_FS_OPEN_DIRECTORY   (1 << 4) /* In     #define SOS_FS_OPEN_DIRECTORY   (1 << 4) /* Incompatible with CREAT/TRUNC */
 #define SOS_FS_OPEN_SYNC        (1 << 5)           #define SOS_FS_OPEN_SYNC        (1 << 5)
 #define SOS_FS_OPEN_CLOSEONEXEC (1 << 6) /* By     #define SOS_FS_OPEN_CLOSEONEXEC (1 << 6) /* By default, files are kept
                                             op                                                 open upon an exec() */
                                                    
 #define SOS_FS_OPEN_READ        (1 << 16)          #define SOS_FS_OPEN_READ        (1 << 16)
 #define SOS_FS_OPEN_WRITE       (1 << 17)          #define SOS_FS_OPEN_WRITE       (1 << 17)
                                                    
                                                    
 /**                                                /**
  * FS access rights                                 * FS access rights
  */                                                 */
 #define SOS_FS_S_IRUSR   00400                     #define SOS_FS_S_IRUSR   00400
 #define SOS_FS_S_IWUSR   00200                     #define SOS_FS_S_IWUSR   00200
 #define SOS_FS_S_IXUSR   00100                     #define SOS_FS_S_IXUSR   00100
                                                    
 #define SOS_FS_S_IRWXALL 07777 /* For symlinks     #define SOS_FS_S_IRWXALL 07777 /* For symlinks */
                                                    
 sos_ret_t sos_fs_open(const struct sos_process     sos_ret_t sos_fs_open(const struct sos_process *owner,
                       const char *_path,                                 const char *_path,
                       sos_size_t _pathlen,                               sos_size_t _pathlen,
                       sos_ui32_t open_flags,                             sos_ui32_t open_flags,
                       sos_ui32_t creat_access_                           sos_ui32_t creat_access_rights,
                       struct sos_fs_opened_fil                           struct sos_fs_opened_file ** of);
                                                    
 sos_ret_t sos_fs_close(struct sos_fs_opened_fi     sos_ret_t sos_fs_close(struct sos_fs_opened_file * of);
                                                    
 sos_ret_t sos_fs_read(struct sos_fs_opened_fil     sos_ret_t sos_fs_read(struct sos_fs_opened_file * of,
                       sos_uaddr_t dest_buf,                              sos_uaddr_t dest_buf,
                       sos_size_t * /* in/ou */                           sos_size_t * /* in/ou */len);
                                                    
 sos_ret_t sos_fs_readdir(struct sos_fs_opened_     sos_ret_t sos_fs_readdir(struct sos_fs_opened_file * of,
                          struct sos_fs_dirent                               struct sos_fs_dirent * result);
                                                    
 sos_ret_t sos_fs_write(struct sos_fs_opened_fi     sos_ret_t sos_fs_write(struct sos_fs_opened_file * of,
                        sos_uaddr_t src_buf,                               sos_uaddr_t src_buf,
                        sos_size_t * /* in/out                             sos_size_t * /* in/out */len);
                                                    
 sos_ret_t sos_fs_seek(struct sos_fs_opened_fil     sos_ret_t sos_fs_seek(struct sos_fs_opened_file *of,
                       sos_lsoffset_t offset,                             sos_lsoffset_t offset,
                       sos_seek_whence_t whence                           sos_seek_whence_t whence,
                       sos_lsoffset_t * result_                           sos_lsoffset_t * result_position);
                                                    
 sos_ret_t sos_fs_ftruncate(struct sos_fs_opene     sos_ret_t sos_fs_ftruncate(struct sos_fs_opened_file *of,
                            sos_lsoffset_t leng                                sos_lsoffset_t length);
                                                    
 sos_ret_t sos_fs_mmap(struct sos_fs_opened_fil     sos_ret_t sos_fs_mmap(struct sos_fs_opened_file *of,
                       sos_uaddr_t *uaddr, sos_                           sos_uaddr_t *uaddr, sos_size_t size,
                       sos_ui32_t access_rights                           sos_ui32_t access_rights,
                       sos_ui32_t flags,                                  sos_ui32_t flags,
                       sos_luoffset_t offset);                            sos_luoffset_t offset);
                                                    
 sos_ret_t sos_fs_fsync(struct sos_fs_opened_fi     sos_ret_t sos_fs_fsync(struct sos_fs_opened_file * of);
                                                    
 sos_ret_t sos_fs_fcntl(struct sos_fs_opened_fi     sos_ret_t sos_fs_fcntl(struct sos_fs_opened_file *of,
                        int req_id,                                        int req_id,
                        sos_ui32_t req_arg /* U                            sos_ui32_t req_arg /* Usually: sos_uaddr_t */);
                                                    
 sos_ret_t sos_fs_ioctl(struct sos_fs_opened_fi     sos_ret_t sos_fs_ioctl(struct sos_fs_opened_file *of,
                        int req_id,                                        int req_id,
                        sos_ui32_t req_arg /* U                            sos_ui32_t req_arg /* Usually: sos_uaddr_t */);
                                                    
 sos_ret_t sos_fs_creat(const struct sos_proces     sos_ret_t sos_fs_creat(const struct sos_process * creator,
                        const char * _path,                                const char * _path,
                        sos_size_t _pathlen,                               sos_size_t _pathlen,
                        sos_ui32_t access_right                            sos_ui32_t access_rights);
                                                    
 sos_ret_t sos_fs_link(const struct sos_process     sos_ret_t sos_fs_link(const struct sos_process * creator,
                       const char * _old_path,                            const char * _old_path,
                       sos_size_t _old_pathlen,                           sos_size_t _old_pathlen,
                       const char * _dest_path,                           const char * _dest_path,
                       sos_size_t _dest_pathlen                           sos_size_t _dest_pathlen);
                                                    
 sos_ret_t sos_fs_rename(const struct sos_proce     sos_ret_t sos_fs_rename(const struct sos_process * creator,
                         const char * _old_path                             const char * _old_path,
                         sos_size_t _old_pathle                             sos_size_t _old_pathlen,
                         const char * _dest_pat                             const char * _dest_path,
                         sos_size_t _dest_pathl                             sos_size_t _dest_pathlen);
                                                    
 sos_ret_t sos_fs_unlink(const struct sos_proce     sos_ret_t sos_fs_unlink(const struct sos_process * actor,
                         const char * _path,                                const char * _path,
                         sos_size_t _pathlen);                              sos_size_t _pathlen);
                                                    
 sos_ret_t sos_fs_symlink(const struct sos_proc     sos_ret_t sos_fs_symlink(const struct sos_process * creator,
                          const char * _path,                                const char * _path,
                          sos_size_t _pathlen,                               sos_size_t _pathlen,
                          sos_uaddr_t symlink_t                              sos_uaddr_t symlink_target,
                          sos_size_t symlink_ta                              sos_size_t symlink_target_len);
                                                    
 sos_ret_t sos_fs_mknod(const struct sos_proces     sos_ret_t sos_fs_mknod(const struct sos_process * creator,
                        const char * _path,                               const char * _path,
                        sos_size_t _pathlen,                              sos_size_t _pathlen,
                        sos_fs_node_type_t typ                            sos_fs_node_type_t type /* only block/char allowed */,
                        sos_ui32_t access_righ                            sos_ui32_t access_rights,
                        const struct sos_fs_de                            const struct sos_fs_dev_id_t * devid);
                                                   
 sos_ret_t sos_fs_mkdir(const struct sos_proce     sos_ret_t sos_fs_mkdir(const struct sos_process * creator,
                        const char * _path,                               const char * _path,
                        sos_size_t _pathlen,                              sos_size_t _pathlen,
                        sos_ui32_t access_righ                            sos_ui32_t access_rights);
                                                   
 sos_ret_t sos_fs_rmdir(const struct sos_proce     sos_ret_t sos_fs_rmdir(const struct sos_process * actor,
                        const char * _path,                               const char * _path,
                        sos_size_t _pathlen);                             sos_size_t _pathlen);
                                                   
 sos_ret_t sos_fs_chmod(const struct sos_proce     sos_ret_t sos_fs_chmod(const struct sos_process * actor,
                        const char * _path,                               const char * _path,
                        sos_size_t _pathlen,                              sos_size_t _pathlen,
                        sos_ui32_t access_righ                            sos_ui32_t access_rights);
                                                   
 sos_ret_t sos_fs_stat(const struct sos_proces     sos_ret_t sos_fs_stat(const struct sos_process * actor,
                       const char * _path,                               const char * _path,
                       sos_size_t _pathlen,                              sos_size_t _pathlen,
                       int nofollow,                                     int nofollow,
                       struct sos_fs_stat * re                           struct sos_fs_stat * result);
                                                   
                                                   
 /* ******************************************     /* ***************************************************************
  * Restricted functions reserved to FS code a      * Restricted functions reserved to FS code and block/char devices
  */                                                */
                                                   
 /**                                               /**
  * Function to be called when proposing a new      * Function to be called when proposing a new File system type
  */                                                */
 sos_ret_t sos_fs_register_fs_type(struct sos_     sos_ret_t sos_fs_register_fs_type(struct sos_fs_manager_type * fstype);
 sos_ret_t sos_fs_unregister_fs_type(struct so     sos_ret_t sos_fs_unregister_fs_type(struct sos_fs_manager_type * fstype);
                                                   
 /**                                               /**
  * Marthe given file as dirty, for FS support      * Marthe given file as dirty, for FS supporting deferred write access
  * mode                                            * mode
  */                                                */
 sos_ret_t sos_fs_mark_dirty(struct sos_fs_ope     sos_ret_t sos_fs_mark_dirty(struct sos_fs_opened_file * of);
                                                   
 /**                                               /**
  * Helper function to be called from the moun      * Helper function to be called from the mount() method of the FS
  * instance code. Responsible for creating an      * instance code. Responsible for creating and updating the "root"
  * field of the FS instance structure and for      * field of the FS instance structure and for connecting this FS in
  * the nscache                                     * the nscache
  * @param root_fsnode The root of the FS bein      * @param root_fsnode The root of the FS being mounted
  */                                                */
 sos_ret_t sos_fs_register_fs_instance(struct      sos_ret_t sos_fs_register_fs_instance(struct sos_fs_manager_instance * fs,
                                       struct                                            struct sos_fs_node * root_fsnode);
                                                   
 /**                                               /**
  * Helper function to be called from the umou      * Helper function to be called from the umount() method of the FS
  * instance code. Responsible for unregisteri      * instance code. Responsible for unregistering the instance from the
  * FS type's instances list and for disconnec      * FS type's instances list and for disconnecting this mountpoint in
  * the nscache.                                    * the nscache.
  */                                                */
 sos_ret_t sos_fs_unregister_fs_instance(struc     sos_ret_t sos_fs_unregister_fs_instance(struct sos_fs_manager_instance * fs);
                                                   
                                                   
 /* ******************************************     /* ***************************************************************
  * Restricted functions reserved to syscall.c      * Restricted functions reserved to syscall.c
  */                                                */
 sos_ret_t sos_fs_ref_opened_file(struct sos_f     sos_ret_t sos_fs_ref_opened_file(struct sos_fs_opened_file * of);
 sos_ret_t _sos_fs_unref_opened_file(struct so     sos_ret_t _sos_fs_unref_opened_file(struct sos_fs_opened_file ** of);
 #define sos_fs_unref_opened_file(f) _sos_fs_u     #define sos_fs_unref_opened_file(f) _sos_fs_unref_opened_file(&(f))
                                                   
                                                   
 /* ******************************************     /* ***************************************************************
  * Restricted functions to be used only by fs      * Restricted functions to be used only by fs_nscache.c
  */                                                */
                                                   
 sos_ret_t sos_fs_ref_fsnode(struct sos_fs_nod     sos_ret_t sos_fs_ref_fsnode(struct sos_fs_node * fsnode);
                                                   
 sos_ret_t _sos_fs_unref_fsnode(struct sos_fs_     sos_ret_t _sos_fs_unref_fsnode(struct sos_fs_node * fsnode);
 #define sos_fs_unref_fsnode(n) \                  #define sos_fs_unref_fsnode(n) \
   ({ sos_ret_t __retval = _sos_fs_unref_fsnod       ({ sos_ret_t __retval = _sos_fs_unref_fsnode(n); (n)=NULL; __retval; })
                                                   
                                                   
 /* ******************************************     /* ***************************************************************
  * Restricted functions reserved to process.c      * Restricted functions reserved to process.c and main.c:start_init()
  */                                                */
 sos_ret_t sos_fs_new_opened_file(const struct     sos_ret_t sos_fs_new_opened_file(const struct sos_process * proc,
                                  struct sos_f                                      struct sos_fs_nscache_node * nsnode,
                                  sos_ui32_t o                                      sos_ui32_t open_flags,
                                  struct sos_f                                      struct sos_fs_opened_file ** result_of);
                                                   
                                                   
 sos_ret_t sos_fs_duplicate_opened_file(struct     sos_ret_t sos_fs_duplicate_opened_file(struct sos_fs_opened_file * src_of,
                                        const                                             const struct sos_process * dst_proc,
                                        struct                                            struct sos_fs_opened_file ** result_of);
                                                   
                                                   
                                                   
 #endif /* _SOS_FS_H_ */                           #endif /* _SOS_FS_H_ */