fs.h

Simple Operating Systems （简称SOS）是一个可以运行在X86平台上（包括QEMU

};


/**
 * The CENTRAL data structure of the whole thing. A so-called "inode"
 *
 * This represents the meta-information related to a file on disk: its
 * permission, where its data is located. Actually, in SOS, these
 * information are not stored in this structure. Instead, we define a
 * series of methods in this structure that MUST be implemented by the
 * FS and that realize the higher level operations needed by the
 * OS. These operations will rely on the meta-information that the FS
 * code MUST define and manage by itself (hence the
 * sos_fs_node::custom_data field).
 */
struct sos_fs_node
{
  /**
   * An struct sos_fs_node always belong to exactly ONE file system
   */
  struct sos_fs_manager_instance * fs;

  /**
   * The so-called "inode": location of this node inside the FS
   * instance. Updated by struct
   * sos_fs_manager_instance::fetch_node_from_disk()
   */
  sos_ui64_t storage_location;

  /**
   * Number of ON-DISK links to this node.
   *
   * - For everything but directories: the number of hard links to the file
   * - For directories: 1 + the number of children nodes
   *
   * @note Publicly readable. Written only by
   * sos_fs_node_ops_dir::link() and sos_fs_node_ops_dir::unlink()
   */
  sos_count_t ondisk_lnk_cnt;

  /**
   * Number of IN-MEMORY nscache_nodes referencing this FS node.
   *
   * Corresponds to the number of struct sos_fs_nscache_node pointing
   * to this node. This could be as much as ondisk_lnk_cnt + 1, but is
   * usually less
   *
   * @note Reserved to fs.c
   */
  sos_count_t inmem_ref_cnt;

  /**
   * Directory, symlink, ...
   *
   * @see sos_fs_node_type_t
   *
   * @note Publicly readable. Written only by fs.c
   */
  sos_fs_node_type_t type;

#define SOS_FS_READABLE          00400
#define SOS_FS_WRITABLE          00200
#define SOS_FS_EXECUTABLE        00100
  /**
   * read/write, ... @see the SOS_FS_*ABLE flags
   * @note Publicly readable. Written only by fs.c
   */
  sos_ui32_t access_rights;

  /**
   * @note Reserved to fs.c
   */
  sos_bool_t dirty;

  /**
   * Incremented each time one of the opened files for this node is
   * modified
   * @note Publicly readable. Written only by fs.c
   */
  sos_lcount_t generation;

  /** Operations common to all node types */
  struct sos_fs_node_ops_file  *ops_file;

  /** Operations specific to some node types */
  union
  {
    /** when type == SOS_FS_NODE_DIRECTORY */
    struct sos_fs_node_ops_dir      *ops_dir;

    /** when type == SOS_FS_NODE_SYMLINK */
    struct sos_fs_node_ops_symlink  *ops_symlink;
  }; /* Anonymous union (gcc extension) */


  /**
   * Simply free this FS node from the kernel memory: it does NOT
   * mean that the corresponding on-disk node is free ! Actually, the
   * corresponding ON-DISK node is free iff ondisk_lnk_cnt == 0. No
   * need to sync anything to disk, as the VFS will sync the node
   * before calling this method
   *
   * @note Mandatory, may block, no special locking needed
   */
  sos_ret_t (*destructor)(struct sos_fs_node * this);

  /**
   * Called when a process opens the node
   *
   * @note Mandatory, may block. Appropriate locking MUST be implemented
   */
  sos_ret_t (*new_opened_file)(struct sos_fs_node * this,
			       const struct sos_process * owner,
			       sos_ui32_t open_flags,
			       struct sos_fs_opened_file ** result_of);

  /**
   * Called when a process opens the node
   *
   * @note Mandatory, may block. Appropriate locking MUST be implemented
   */
  sos_ret_t (*close_opened_file)(struct sos_fs_node * this,
				 struct sos_fs_opened_file * of);

  /**
   * This should hold the meta information for this node as needed by
   * the FS instance.
   */
  void * custom_data;

  /** Hash linkage entry for this FS node in the nodecache
     dictionary */
  struct sos_hash_linkage hlink_nodecache;

  /** Linkage to list the dirty nodes of the given FS */
  struct sos_fs_node *prev_dirty, *next_dirty;
};



/**
 * The list of methods implementing the basic VFS operations on the
 * given struct sos_fs_node
 *
 * @see sos_fs_node::ops_file
 */
struct sos_fs_node_ops_file
{
  /**
   * Change size of file
   *
   * @note Optional, may block. Appropriate locking MUST be implemented
   */
  sos_ret_t (*truncate)(struct sos_fs_node *this,
			sos_lsoffset_t length);

  /**
   * Retrieve the status (eg size) of the file
   *
   * @note Mandatory, may block. Appropriate locking MUST be implemented
   */
  sos_ret_t (*stat)(struct sos_fs_node * this,
		    struct sos_fs_stat * result);

  /**
   * Flush any change to disk
   *
   * @note Mandatory, may block. Appropriate locking MUST be implemented
   */
  sos_ret_t (*sync)(struct sos_fs_node *this);

  /**
   * Change the sos_fs_node::access_rights attribute
   *
   * @note Mandatory, may block. Appropriate locking MUST be implemented
   */
  sos_ret_t (*chmod)(struct sos_fs_node * this,
		     sos_ui32_t new_access_rights);
};


/**
 * The list of methods implementing the basic VFS symlink operations
 *
 * @see sos_fs_node::ops_symlink
 */
struct sos_fs_node_ops_symlink
{
  /**
   * Used by the _kernel_ to resolve the symlinks. To change/create a
   * symlink target, it is needed only from userland: the read/write
   * methods are made for this
   *
   * @param target Pointer to the string representing the target's
   * path, allocated for the fs_node's lifetime !
   *
   * @note Mandatory, may block. Appropriate locking MUST be implemented
   */
  sos_ret_t (*expand)(struct sos_fs_node *this,
		      char const  ** target,
		      sos_size_t * target_len);
};


/**
 * The list of methods implementing the basic VFS directory operations
 *
 * @see sos_fs_node::ops_dir
 */
struct sos_fs_node_ops_dir
{
  /**
   * Look for the on-disk location of the sos_fs_node having the given
   * name
   *
   * @note Mandatory, may block. Appropriate locking MUST be implemented
   */
  sos_ret_t (*lookup)(struct sos_fs_node *this,
		      const char * name, sos_ui16_t namelen,
		      sos_ui64_t * result_storage_location);

  /**
   * Add a new reference in the current sos_fs_node to the on-disk
   * location of the given sos_fs_node
   *
   * @note Responsible for updating this->ondisk_lnk_cnt
   * @note Mandatory for writable directories, may block. Appropriate
   * locking MUST be implemented
   */
  sos_ret_t (*link)(struct sos_fs_node *this,
		    const struct sos_process *actor,
		    const char * entry_name, sos_ui16_t entry_namelen,
		    struct sos_fs_node * node);

  /**
   * Remove the entry in the current sos_fs_node for the on-disk
   * location with the given name
   *
   * @note Responsible for updating this->ondisk_lnk_cnt
   * @note Mandatory for writable directories, may block. Appropriate
   * locking MUST be implemented
   */
  sos_ret_t (*unlink)(struct sos_fs_node *this,
		      const struct sos_process *actor,
		      const char * entry_name, sos_ui16_t entry_namelen);
};


/**
 * The data structure holding information and method related to a
 * particular usage of a file. A so-called "struct file"
 *
 * This represents the kernel structure behind a "file descriptor" or
 * behind a chdir/chroot. Among other things, it holds the methods
 * responsible for reading/writing into the file, and for moving the
 * file pointer (see @sos_fs_opened_file::position) inside it.
 */
struct sos_fs_opened_file
{
  /** The process that opened the file/dir */
  const struct sos_process * owner;

  /**
   * The reference to the sos_fs_nscache_node and, hence, to the underlying sos_fs_node.
   *
   * Used to cache the in-memory fs nodes
   */
  struct sos_fs_nscache_node * direntry;

  /** Use for memory-management */
  sos_count_t ref_cnt;

  /**
   * Always > 0 (ie max size = 2^63-1 = 9.2 10^18). We make it
   * "signed" here to limit its range. Because we must be able to
   * seek to the begining of the file with SEEK_END and a negative
   * offset, so the max size of the file must be reachable by a lseek
   * offset
   *
   * @note reserved to filesystem instance code. Not modified nor used
   * by fs.c
   */
  sos_lsoffset_t     position;

  /**
   * Incremented each time this opened file is modified
   *
   * Used to implement a readdir method resilient to
   * creat/mkdir/rmdir/unlink
   */
  sos_lcount_t generation;

  /**
   * @see SOS_FS_OPEN_* flags
   */
  sos_ui32_t open_flags;

  /** Operations common to all node types */
  struct sos_fs_ops_opened_file * ops_file;

  /** Operations specific to some node types */
  union
  {
    /** when direntry->fs_node->type == SOS_FS_NODE_DIRECTORY */
    struct sos_fs_ops_opened_dir      * ops_dir;
  }; /* Anonymous union (gcc extension) */

  /**
   * Called upon fork() to duplicate all the opened files
   */
  sos_ret_t (*duplicate)(struct sos_fs_opened_file *this,
			 const struct sos_process  * for_owner,
			 struct sos_fs_opened_file **result);

  void * custom_data;
};


/**
 * Reference position for sos_fs_seek
 */
typedef enum { SOS_SEEK_SET=42,
	       SOS_SEEK_CUR=24,
	       SOS_SEEK_END=84 } sos_seek_whence_t;
/**
 * The list of methods implementing the basic VFS opened file
 * operations
 *
 * See the Unix manual pages, they basically form the interfaces to to
 * these functions
 *
 * @see sos_fs_opened_file::ops_file
 */
struct sos_fs_ops_opened_file
{
  /**
   * @note Mandatory, may block. Appropriate locking MUST be implemented
   * @note Please call sos_fs_mark_dirty() if disk contents is changed
   */
  sos_ret_t (*seek)(struct sos_fs_opened_file *this,
		    sos_lsoffset_t offset,
		    sos_seek_whence_t whence,
		    /* out */ sos_lsoffset_t * result_position);