--- /dev/null
+/*
+ * \file design.dox
+ * Documentation title page with design information
+ */
+
+
+/**
+\mainpage File System Wrapper Documentation
+
+Welcome to the documentation for FSW. This doxygen-generated documentation
+is intended for developers that either want to integrate FSW into their
+own project or want to write additional file system drivers.
+
+\section goals Design Goals
+
+File System Wrapper wants to provide reusable, read-only file system drivers
+for a range of common file systems. Reusability is achieved through a common
+abstraction layer (called the "core"), which serves as the API for the host
+environment driver. Once the required glue code is written for a host
+environment, that host has access to all file system types implemented by FSW,
+with no code to be written per file system type.
+
+Why read-only? There are a range of reasons why FSW only provides read-only
+access:
+
+- Read-only drivers are much easier to write than read-write drivers.
+- Write access isn't easily abstracted in an OS-independent way because
+ of more delicate buffer I/O handling requirements and features like
+ journalling.
+- There is no risk of destroying data on the disk.
+- Having read access is much better than having no access at all.
+ (Read-only drivers for several file systems can be written in the time
+ it would take to develop a read-write driver for just one file system.)
+- Boot loaders only need read access in most cases.
+
+\section model Object and Data Model
+
+\subsection main_objects Main Objects
+
+There are three main "objects" that FSW works with: volume, dnode, and shandle.
+
+The fsw_volume structure keeps the information that applies to a file
+system volume as a whole. Most importantly, it keeps pointers to the host driver
+and file system driver dispatch tables, which are used by the core to call
+the appropriate functions.
+
+The fsw_dnode structure represents a "directory node", that is any file-like
+object in the file system: regular files, directories, symbolic links as well
+as special files like device nodes. When compared with Unix-style file systems,
+a dnode is very similar to an inode, but it retains some essential information
+from the directory: the canonical name and the parent directory. FSW requires that
+a dnode is uniquely identified by an integer number (currently 32 bit in size).
+Inode numbers can be used for this purpose, non-Unix file systems will have to
+come up with a unique number in some way.
+
+The fsw_shandle structure is used to access file data ("storage handle").
+A dnode only represents the file as such and doesn't offer access to its data.
+An shandle is linked to a certain dnode, but there may be several shandles per
+dnode. The shandle stores a file position pointer (byte offset) that can be changed
+at will. With the current design, an shandle is also used for directory iteration,
+even if the file system stores directory information in a central tree structure.
+
+\subsection disk_access Disk Data Access
+
+Data on the disk is accessed in blocks, addressed by a sequential number starting
+at zero. The block size to use can be set by the file system driver. FSW supports
+two separate block sizes: the "physical block size" is used when accessing the disk,
+the "logical block size" is used when accessing a file's data. For most file
+systems, these two are identical, but there may be some where the file allocation
+block size is larger than the sector or block size used to store metadata. (FAT
+comes to mind as an example.)
+
+For accessing the actual file data, the file system driver doesn't handle the
+disk I/O, but merely returns information about the mapping from file logical
+blocks to disk physical blocks in the fsw_extent structure. This allows host OS
+buffer mechanisms to be used for file data. In special cases, like tail-packing,
+fragments or compressed file systems, the file system driver can return file data
+in an allocated buffer.
+
+\subsection data_hooks Data Extension Hooks
+
+File system specific data can be stored by extending the fsw_volume and fsw_dnode
+structures. The core code uses the structure sizes stored in the fsw_fstype_table
+to allocate memory for these structures. The fsw_shandle and fsw_extent structures
+are not designed to be extended.
+
+Host specific data must be stored in separate structures private to the host
+environment driver. The fsw_volume structure provides a host_data variable to
+store a pointer. The fsw_dnode structure has no such field, because it is assumed
+that all actions regarding dnodes are initiated on the host side and so the
+host-specific private structure is known.
+
+\section callconv Calling Conventions
+
+All functions that can fail return a status code in a fsw_status_t. This type is an
+integer. A boolean test yields true if there was an error and false if the function
+executed successfully, i.e. success is signalled by a 0 return value.
+
+Functions that return data do so either by filling a structure passed in by the caller,
+or by allocating a structure on the heap and returning a pointer through a
+double-indirect parameter. A returned object pointer is the last parameter in the
+parameter list.
+
+(More to be written about specific conventions for dnodes, shandles, strings.)
+
+*/