Updated the FS introduction. It's in sync with the current API again, but some

new sections for caches and FS layers should be added.


git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@29768 a95241bf-73f2-0310-859d-f6bbb57e9c96

docs/user/drivers/fs_modules.dox

@@ -26,23 +26,29 @@
 	- A \em volume is an instance of a file system. For a disk-based file
 	  system it corresponds to a disk, partition, or disk image file. When
 	  mounting a volume the virtual file system layer (VFS) assigns a unique
-	  number (ID, of type \c mount_id aka \c dev_t) to it and a handle (type
-	  \c fs_volume, in fact \c void*) provided by
-	  the file system. Whenever the FS requests a volume-related service from the
-	  kernel, it has to pass the volume ID, and whenever the VFS asks the FS to
-	  perform an operation, it supplies the handle. Normally the handle is a
-	  pointer to a data structure the FS allocates to associate data with the
-	  volume.
+	  number (ID, of type \c dev_t) to it and a handle (type \c void*) provided
+	  by the file system. The VFS creates an instance of struct \c fs_volume
+	  that stores these two, an operation vector (\c fs_volume_ops), and other
+	  volume related items.
+	  Whenever the FS is asked to perform an operation the \c fs_volume object
+	  is supplied, and whenever the FS requests a volume-related service from
+	  the kernel, it also has to pass the \c fs_volume object or, in some cases,
+	  just the volume ID.
+	  Normally the handle is a pointer to a data structure the FS allocates to
+	  associate data with the volume.
 
 	- A \em node is contained by a volume. It can be of type file, directory, or
 	  symbolic link (symlink). Just as volumes nodes are associated with an ID
-	  (type \c vnode_id aka ino_t) and, if in use, also with a handle
-	  (type \c fs_vnode, in fact \c void*).
-	  Unlike the volume ID the node ID is defined by the FS. It often
-	  has a meaning to the FS, e.g. file systems using inodes might choose the
-	  inode number corresponding to the node. As long as the volume is mounted
-	  and the node is known to the VFS, its node ID must not change. The node
-	  handle is again a pointer to a data structure allocated by the FS.
+	  (type \c ino_t) and, if in use, also with a handle (type \c void*).
+	  As for volumes the VFS creates an instance of a structure (\c fs_vnode)
+	  for each node in use, storing the FS's handle for the node and an
+	  operation vector (\c fs_vnode_ops).
+	  Unlike the volume ID the node ID is defined by the FS.
+	  It often has a meaning to the FS, e.g. file systems using inodes might
+	  choose the inode number corresponding to the node. As long as the volume
+	  is mounted and the node is known to the VFS, its node ID must not change.
+	  The node handle is again a pointer to a data structure allocated by the
+	  FS.
 
 	- A \em vnode (VFS node) is the VFS representation of a node. A volume may
 	  contain a great number of nodes, but at a time only a few are represented
@@ -53,16 +59,17 @@
 	  refers to a node. It is important to understand the difference between
 	  entries and nodes: A node doesn't have a name, only the entries that refer
 	  to it have. If a FS supports to have more than one entry refer to a single
-	  node, it is also said to support "hard links". It is possible that no entry
-	  refers to a node. This happens when a node (e.g. a file) is still open, but
-	  the last entry referring to it has been removed (the node will be deleted
-	  when the it is closed). While entries are to be understood as independent
-	  entities, the FS interface does not use IDs or handles to refer to them;
-	  it always uses directory and entry name pairs to do that.
+	  node, it is also said to support "hard links". It is possible that no
+	  entry refers to a node. This happens when a node (e.g. a file) is still
+	  open, but the last entry referring to it has been removed (the node will
+	  be deleted when the it is closed). While entries are to be understood as
+	  independent entities, the FS interface does not use IDs or handles to
+	  refer to them; it always uses directory and entry name pairs to do that.
 
-	- An \em attribute is a named and typed data container belonging to a node. A
-	  node may have any number of attributes; they are organized in a (virtual or
-	  actually existing) attribute directory, through which one can iterate.
+	- An \em attribute is a named and typed data container belonging to a node.
+	  A node may have any number of attributes; they are organized in a
+	  (depending on the FS, virtual or actually existing) attribute directory,
+	  through which one can iterate.
 
 	- An \em index is supposed to provide fast searching capabilities for
 	  attributes with a certain name. A volume's index directory allows for
@@ -88,8 +95,8 @@
 	  <tt>free*_cookie()</tt>. The <tt>open*()</tt> hook is passed all that is
 	  needed to identify the object to be opened and, in some cases, additional
 	  parameters e.g. specifying a particular opening mode. The implementation
-	  is required to return a cookie (type \c fs_cookie, in fact \c void*),
-	  usually a pointer to a data structure the FS allocates. In some cases (e.g.
+	  is required to return a cookie (type \c void*), usually a pointer to a
+	  data structure the FS allocates. In some cases (e.g.
 	  when an iteration state is associated with the cookie) a new cookie must
 	  be allocated for each instance of opening the object. The cookie is passed
 	  to all hooks that operate on a thusly opened object. The <tt>close*()</tt>
@@ -117,31 +124,33 @@
 	A vnode is the VFS representation of a node. As soon as an access to a node
 	is requested, the VFS creates a corresponding vnode. The requesting entity
 	gets a reference to the vnode for the time it works with the vnode and
-	releases the reference when done. When the last reference to a vnode has been
-	surrendered, the vnode is unused and the VFS can decide to destroy it
+	releases the reference when done. When the last reference to a vnode has
+	been surrendered, the vnode is unused and the VFS can decide to destroy it
 	(usually it is cached for a while longer).
 
-	When the VFS creates a vnode, it invokes the FS's
-	\link file_system_module_info::get_vnode get_vnode() \endlink
+	When the VFS creates a vnode, it invokes the volume's
+	\link fs_volume_ops::get_vnode get_vnode() \endlink
 	hook to let it create the respective node handle (unless the FS requests the
 	creation of the vnode explicitely by calling publish_vnode()). That's the
-	only hook that specifies a node by ID; to all other node-related hooks the
-	node handle is passed. When the VFS deletes the vnode, it invokes the FS's
-	\link file_system_module_info::put_vnode put_vnode() \endlink
+	only hook that specifies a node by ID; all other node-related hooks are
+	defined in the respective node's operation vector and they are passed the
+	respective \c fs_vnode object. When the VFS deletes the vnode, it invokes
+	the nodes's \link fs_vnode_ops::put_vnode put_vnode() \endlink
 	hook or, if the node was marked removed,
-	\link file_system_module_info::remove_vnode remove_vnode() \endlink.
+	\link fs_vnode_ops::remove_vnode remove_vnode() \endlink.
 
 	There are only four FS hooks through which the VFS gains knowledge of the
 	existence of a node. The first one is the
 	\link file_system_module_info::mount mount() \endlink
 	hook. It is supposed to call \c publish_vnode() for the root node of the
 	volume and return its ID. The second one is the
-	\link file_system_module_info::lookup lookup() \endlink
-	hook. Given a node handle of a directory and an entry name, it is supposed to
-	call \c get_vnode() for the node the entry refers to and return the node ID.
+	\link fs_vnode_ops::lookup lookup() \endlink
+	hook. Given a \c fs_vnode object of a directory and an entry name, it is
+	supposed to call \c get_vnode() for the node the entry refers to and return
+	the node ID.
 	The remaining two hooks,
-	\link file_system_module_info::read_dir read_dir() \endlink and
-	\link file_system_module_info::read_query read_query() \endlink,
+	\link fs_vnode_ops::read_dir read_dir() \endlink and
+	\link fs_volume_ops::read_query read_query() \endlink,
 	both return entries in a <tt>struct dirent</tt> structure, which also
 	contains the ID of the node the entry refers to.
 
@@ -149,64 +158,65 @@
 	\section mandatory_hooks Mandatory Hooks
 
 	Which hooks a FS module should provide mainly depends on what functionality
-	it features. E.g. a FS without support for attribute, indices, and/or queries
-	can omit the respective hooks (i.e. set them to \c NULL in the module
-	structure). Some hooks are mandatory, though. A minimal read-only FS module
-	must implement:
+	it features. E.g. a FS without support for attribute, indices, and/or
+	queries can omit the respective hooks (i.e. set them to \c NULL in the
+	module, \c fs_volume_ops, and \c fs_vnode_ops structure). Some hooks are
+	mandatory, though. A minimal read-only FS module must implement:
 
 	- \link file_system_module_info::mount mount() \endlink and
-	  \link file_system_module_info::unmount unmount() \endlink:
+	  \link fs_volume_ops::unmount unmount() \endlink:
 	  Mounting and unmounting a volume is required for pretty obvious reasons.
 
-	- \link file_system_module_info::lookup lookup() \endlink:
+	- \link fs_vnode_ops::lookup lookup() \endlink:
 	  The VFS uses this hook to resolve path names. It is probably one of the
 	  most frequently invoked hooks.
 
-	- \link file_system_module_info::get_vnode get_vnode() \endlink and
-	  \link file_system_module_info::put_vnode put_vnode() \endlink:
+	- \link fs_volume_ops::get_vnode get_vnode() \endlink and
+	  \link fs_vnode_ops::put_vnode put_vnode() \endlink:
 	  Create respectively destroy the FS's private node handle when
 	  the VFS creates/deletes the vnode for a particular node.
 
-	- \link file_system_module_info::read_stat read_stat() \endlink:
+	- \link fs_vnode_ops::read_stat read_stat() \endlink:
 	  Return a <tt>struct stat</tt> info for the given node, consisting of the
 	  type and size of the node, its owner and access permissions, as well as
 	  certain access times.
 
-	- \link file_system_module_info::open open() \endlink,
-	  \link file_system_module_info::close close() \endlink, and
-	  \link file_system_module_info::free_cookie free_cookie() \endlink:
+	- \link fs_vnode_ops::open open() \endlink,
+	  \link fs_vnode_ops::close close() \endlink, and
+	  \link fs_vnode_ops::free_cookie free_cookie() \endlink:
 	  Open and close a node as explained in \ref concepts.
 
-	- \link file_system_module_info::read read() \endlink:
+	- \link fs_vnode_ops::read read() \endlink:
 	  Read data from an opened node (file). Even if the FS does not feature
-	  files, the hook has to be present anyway; it should return an error in this
-	  case.
+	  files, the hook has to be present anyway; it should return an error in
+	  this case.
 
-	- \link file_system_module_info::open_dir open_dir() \endlink,
-	  \link file_system_module_info::close_dir close_dir() \endlink, and
-	  \link file_system_module_info::free_dir_cookie free_dir_cookie() \endlink:
+	- \link fs_vnode_ops::open_dir open_dir() \endlink,
+	  \link fs_vnode_ops::close_dir close_dir() \endlink, and
+	  \link fs_vnode_ops::free_dir_cookie free_dir_cookie() \endlink:
 	  Open and close a directory for entry iteration as explained in
 	  \ref concepts.
 
-	- \link file_system_module_info::read_dir read_dir() \endlink and
-	  \link file_system_module_info::rewind_dir rewind_dir() \endlink:
+	- \link fs_vnode_ops::read_dir read_dir() \endlink and
+	  \link fs_vnode_ops::rewind_dir rewind_dir() \endlink:
 	  Read the next entry/entries from a directory, respectively reset the
 	  iterator to the first entry, as explained in \ref concepts.
 
 	Although not strictly mandatory, a FS should additionally implement the
 	following hooks:
 
-	- \link file_system_module_info::read_fs_info read_fs_info() \endlink:
+	- \link fs_volume_ops::read_fs_info read_fs_info() \endlink:
 	  Return general information about the volume, e.g. total and free size, and
 	  what special features (attributes, MIME types, queries) the volume/FS
 	  supports.
 
-	- \link file_system_module_info::read_symlink read_symlink() \endlink:
+	- \link fs_vnode_ops::read_symlink read_symlink() \endlink:
 	  Read the value of a symbolic link. Needed only, if the FS and volume
 	  support symbolic links at all. If absent symbolic links stored on the
 	  volume won't be interpreted.
 
-	- \link file_system_module_info::access access() \endlink:
+	- \link fs_vnode_ops::access access() \endlink:
 	  Return whether the current user has the given access permissions for a
-	  node. If the hook is absent the user is considerd to have all permissions.
+	  node. If the hook is absent the user is considered to have all
+	  permissions.
 */