diff --git a/docs/user/drivers/fs_modules.dox b/docs/user/drivers/fs_modules.dox
index d825b7f0b3..81e7bc5a03 100644
--- a/docs/user/drivers/fs_modules.dox
+++ b/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 @@
free*_cookie(). The open*() 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 close*()
@@ -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 struct dirent 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 struct stat 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.
*/