code.delx.au - refind/blob - filesystems/design.dox

   1 /*
   2  * \file design.dox
   3  * Documentation title page with design information
   4  */
   5
   6
   7 /**
   8 \mainpage File System Wrapper Documentation
   9
  10 Welcome to the documentation for FSW. This doxygen-generated documentation
  11 is intended for developers that either want to integrate FSW into their
  12 own project or want to write additional file system drivers.
  13
  14 \section goals Design Goals
  15
  16 File System Wrapper wants to provide reusable, read-only file system drivers
  17 for a range of common file systems. Reusability is achieved through a common
  18 abstraction layer (called the "core"), which serves as the API for the host
  19 environment driver. Once the required glue code is written for a host
  20 environment, that host has access to all file system types implemented by FSW,
  21 with no code to be written per file system type.
  22
  23 Why read-only? There are a range of reasons why FSW only provides read-only
  24 access:
  25
  26 - Read-only drivers are much easier to write than read-write drivers.
  27 - Write access isn't easily abstracted in an OS-independent way because
  28   of more delicate buffer I/O handling requirements and features like
  29   journalling.
  30 - There is no risk of destroying data on the disk.
  31 - Having read access is much better than having no access at all.
  32   (Read-only drivers for several file systems can be written in the time
  33   it would take to develop a read-write driver for just one file system.)
  34 - Boot loaders only need read access in most cases.
  35
  36 \section model Object and Data Model
  37
  38 \subsection main_objects Main Objects
  39
  40 There are three main "objects" that FSW works with: volume, dnode, and shandle.
  41
  42 The fsw_volume structure keeps the information that applies to a file
  43 system volume as a whole. Most importantly, it keeps pointers to the host driver
  44 and file system driver dispatch tables, which are used by the core to call
  45 the appropriate functions.
  46
  47 The fsw_dnode structure represents a "directory node", that is any file-like
  48 object in the file system: regular files, directories, symbolic links as well
  49 as special files like device nodes. When compared with Unix-style file systems,
  50 a dnode is very similar to an inode, but it retains some essential information
  51 from the directory: the canonical name and the parent directory. FSW requires that
  52 a dnode is uniquely identified by an integer number (currently 32 bit in size).
  53 Inode numbers can be used for this purpose, non-Unix file systems will have to
  54 come up with a unique number in some way.
  55
  56 The fsw_shandle structure is used to access file data ("storage handle").
  57 A dnode only represents the file as such and doesn't offer access to its data.
  58 An shandle is linked to a certain dnode, but there may be several shandles per
  59 dnode. The shandle stores a file position pointer (byte offset) that can be changed
  60 at will. With the current design, an shandle is also used for directory iteration,
  61 even if the file system stores directory information in a central tree structure.
  62
  63 \subsection disk_access Disk Data Access
  64
  65 Data on the disk is accessed in blocks, addressed by a sequential number starting
  66 at zero. The block size to use can be set by the file system driver. FSW supports
  67 two separate block sizes: the "physical block size" is used when accessing the disk,
  68 the "logical block size" is used when accessing a file's data. For most file
  69 systems, these two are identical, but there may be some where the file allocation
  70 block size is larger than the sector or block size used to store metadata. (FAT
  71 comes to mind as an example.)
  72
  73 For accessing the actual file data, the file system driver doesn't handle the
  74 disk I/O, but merely returns information about the mapping from file logical
  75 blocks to disk physical blocks in the fsw_extent structure. This allows host OS
  76 buffer mechanisms to be used for file data. In special cases, like tail-packing,
  77 fragments or compressed file systems, the file system driver can return file data
  78 in an allocated buffer.
  79
  80 \subsection data_hooks Data Extension Hooks
  81
  82 File system specific data can be stored by extending the fsw_volume and fsw_dnode
  83 structures. The core code uses the structure sizes stored in the fsw_fstype_table
  84 to allocate memory for these structures. The fsw_shandle and fsw_extent structures
  85 are not designed to be extended.
  86
  87 Host specific data must be stored in separate structures private to the host
  88 environment driver. The fsw_volume structure provides a host_data variable to
  89 store a pointer. The fsw_dnode structure has no such field, because it is assumed
  90 that all actions regarding dnodes are initiated on the host side and so the
  91 host-specific private structure is known.
  92
  93 \section callconv Calling Conventions
  94
  95 All functions that can fail return a status code in a fsw_status_t. This type is an
  96 integer. A boolean test yields true if there was an error and false if the function
  97 executed successfully, i.e. success is signalled by a 0 return value.
  98
  99 Functions that return data do so either by filling a structure passed in by the caller,
 100 or by allocating a structure on the heap and returning a pointer through a
 101 double-indirect parameter. A returned object pointer is the last parameter in the
 102 parameter list.
 103
 104 (More to be written about specific conventions for dnodes, shandles, strings.)
 105
 106 */