From d117d093a2204f208e736a579a95003f87e1bb21 Mon Sep 17 00:00:00 2001 From: Ingo Weinhold Date: Sat, 28 Mar 2009 21:50:19 +0000 Subject: [PATCH] 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 | 134 +++++++++++++++++-------------- 1 file changed, 72 insertions(+), 62 deletions(-) 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. */