To support a particular file system (FS), a kernel module implementing a special interface (
file_system_module_info defined in
<fs_interface.h>) has to be provided. As for any other module the
std_ops() hook is invoked with
B_MODULE_INIT directly after the FS module has been loaded by the kernel, and with
B_MODULE_UNINIT before it is unloaded, thus providing a simple mechanism for one-time module initializations. The same module is used for accessing any volume of that FS type.
There are several types of objects a FS module has to deal with directly or indirectly:
- A 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
mount_id aka dev_t) to it and a handle (type fs_volume, in fact 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.
- A 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
vnode_id aka ino_t) and, if in use, also with a handle (type fs_vnode, in fact 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.
- A 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 by vnodes, usually only those that are currently in use (sometimes a few more).
- An entry (directory entry) belongs to a directory, has a name, and 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.
- An 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 index is supposed to provide fast searching capabilities for attributes with a certain name. A volume's index directory allows for iterating through the indices.
- A query is a fully virtual object for searching for entries via an expression matching entry name, node size, node modification date, and/or node attributes. The mechanism of retrieving the entries found by a query is similar to that for reading a directory contents. A query can be live in which case the creator of the query is notified by the FS whenever an entry no longer matches the query expression or starts matching.
A FS module has to (or can) provide quite a lot of hook functions. There are a few concepts that apply to several groups of them:
- Opening, Closing, and Cookies: Many FS objects can be opened and closed, namely nodes in general, directories, attribute directories, attributes, the index directory, and queries. In each case there are three hook functions:
open*(), close*(), and 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 fs_cookie, in fact 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*() hook is invoked to signal that the cookie is to be closed. At this point the cookie might still be in use. Blocking FS hooks (e.g. blocking read/write operations) using the same cookie have to be unblocked. When the cookie stops being in use the free*_cookie() hook is called; it has to free the cookie.
- Entry Iteration: For the FS objects serving as containers for other objects, i.e. directories, attribute directories, the index directory, and queries, the cookie mechanism is used for a stateful iteration through the contained objects. The
read_*() hook reads the next one or more entries into a struct dirent buffer. The rewind_*() hook resets the iteration state to the first entry.
- Stat Information: In case of nodes, attributes, and indices detailed information about an object are requested via a
read*_stat() hook and must be written into a struct stat buffer.
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 (usually it is cached for a while longer).
When the VFS creates a vnode, it invokes the FS's get_vnode() 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 put_vnode() hook or, if the node was marked removed, remove_vnode() .
There are only four FS hooks through which the VFS gains knowledge of the existence of a node. The first one is the mount() hook. It is supposed to call publish_vnode() for the root node of the volume and return its ID. The second one is the lookup() hook. Given a node handle of a directory and an entry name, it is supposed to call get_vnode() for the node the entry refers to and return the node ID. The remaining two hooks, read_dir() and read_query() , both return entries in a struct dirent structure, which also contains the ID of the node the entry refers to.
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
NULL in the module structure). Some hooks are mandatory, though. A minimal read-only FS module must implement:
- mount() and unmount() : Mounting and unmounting a volume is required for pretty obvious reasons.
- lookup() : The VFS uses this hook to resolve path names. It is probably one of the most frequently invoked hooks.
- get_vnode() and put_vnode() : Create respectively destroy the FS's private node handle when the VFS creates/deletes the vnode for a particular node.
- read_stat() : 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.
- read() : 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.
Although not strictly mandatory, a FS should additionally implement the following hooks:
- read_fs_info() : Return general information about the volume, e.g. total and free size, and what special features (attributes, MIME types, queries) the volume/FS supports.
- read_symlink() : 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.
- access() : 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.
The Haiku Book pre-R1 - File System Modules
Generated on 14 Feb 2008
