1/* 2 * Copyright 2007 Haiku Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Ingo Weinhold 7 */ 8 9 /*! 10 \page fs_modules File System Modules 11 12 To support a particular file system (FS), a kernel module implementing a 13 special interface (\c file_system_module_info defined in \c <fs_interface.h>) 14 has to be provided. As for any other module the \c std_ops() hook is invoked 15 with \c B_MODULE_INIT directly after the FS module has been loaded by the 16 kernel, and with \c B_MODULE_UNINIT before it is unloaded, thus providing 17 a simple mechanism for one-time module initializations. The same module is 18 used for accessing any volume of that FS type. 19 20 21 \section objects File System Objects 22 23 There are several types of objects a FS module has to deal with directly or 24 indirectly: 25 26 - A \em volume is an instance of a file system. For a disk-based file 27 system it corresponds to a disk, partition, or disk image file. When 28 mounting a volume the virtual file system layer (VFS) assigns a unique 29 number (ID, of type \c mount_id aka \c dev_t) to it and a handle (type 30 \c fs_volume, in fact \c void*) provided by 31 the file system. Whenever the FS requests a volume-related service from the 32 kernel, it has to pass the volume ID, and whenever the VFS asks the FS to 33 perform an operation, it supplies the handle. Normally the handle is a 34 pointer to a data structure the FS allocates to associate data with the 35 volume. 36 37 - A \em node is contained by a volume. It can be of type file, directory, or 38 symbolic link (symlink). Just as volumes nodes are associated with an ID 39 (type \c vnode_id aka ino_t) and, if in use, also with a handle 40 (type \c fs_vnode, in fact \c void*). 41 Unlike the volume ID the node ID is defined by the FS. It often 42 has a meaning to the FS, e.g. file systems using inodes might choose the 43 inode number corresponding to the node. As long as the volume is mounted 44 and the node is known to the VFS, its node ID must not change. The node 45 handle is again a pointer to a data structure allocated by the FS. 46 47 - A \em vnode (VFS node) is the VFS representation of a node. A volume may 48 contain a great number of nodes, but at a time only a few are represented 49 by vnodes, usually only those that are currently in use (sometimes a few 50 more). 51 52 - An \em entry (directory entry) belongs to a directory, has a name, and 53 refers to a node. It is important to understand the difference between 54 entries and nodes: A node doesn't have a name, only the entries that refer 55 to it have. If a FS supports to have more than one entry refer to a single 56 node, it is also said to support "hard links". It is possible that no entry 57 refers to a node. This happens when a node (e.g. a file) is still open, but 58 the last entry referring to it has been removed (the node will be deleted 59 when the it is closed). While entries are to be understood as independent 60 entities, the FS interface does not use IDs or handles to refer to them; 61 it always uses directory and entry name pairs to do that. 62 63 - An \em attribute is a named and typed data container belonging to a node. A 64 node may have any number of attributes; they are organized in a (virtual or 65 actually existing) attribute directory, through which one can iterate. 66 67 - An \em index is supposed to provide fast searching capabilities for 68 attributes with a certain name. A volume's index directory allows for 69 iterating through the indices. 70 71 - A \em query is a fully virtual object for searching for entries via an 72 expression matching entry name, node size, node modification date, and/or 73 node attributes. The mechanism of retrieving the entries found by a query 74 is similar to that for reading a directory contents. A query can be live 75 in which case the creator of the query is notified by the FS whenever an 76 entry no longer matches the query expression or starts matching. 77 78 79 \section concepts Generic Concepts 80 81 A FS module has to (or can) provide quite a lot of hook functions. There are 82 a few concepts that apply to several groups of them: 83 84 - <em>Opening, Closing, and Cookies</em>: Many FS objects can be opened and 85 closed, namely nodes in general, directories, attribute directories, 86 attributes, the index directory, and queries. In each case there are three 87 hook functions: <tt>open*()</tt>, <tt>close*()</tt>, and 88 <tt>free*_cookie()</tt>. The <tt>open*()</tt> hook is passed all that is 89 needed to identify the object to be opened and, in some cases, additional 90 parameters e.g. specifying a particular opening mode. The implementation 91 is required to return a cookie (type \c fs_cookie, in fact \c void*), 92 usually a pointer to a data structure the FS allocates. In some cases (e.g. 93 when an iteration state is associated with the cookie) a new cookie must 94 be allocated for each instance of opening the object. The cookie is passed 95 to all hooks that operate on a thusly opened object. The <tt>close*()</tt> 96 hook is invoked to signal that the cookie is to be closed. At this point 97 the cookie might still be in use. Blocking FS hooks (e.g. blocking 98 read/write operations) using the same cookie have to be unblocked. When 99 the cookie stops being in use the <tt>free*_cookie()</tt> hook is called; 100 it has to free the cookie. 101 102 - <em>Entry Iteration</em>: For the FS objects serving as containers for 103 other objects, i.e. directories, attribute directories, the index 104 directory, and queries, the cookie mechanism is used for a stateful 105 iteration through the contained objects. The <tt>read_*()</tt> hook reads 106 the next one or more entries into a <tt>struct dirent</tt> buffer. The 107 <tt>rewind_*()</tt> hook resets the iteration state to the first entry. 108 109 - <em>Stat Information</em>: In case of nodes, attributes, and indices 110 detailed information about an object are requested via a 111 <tt>read*_stat()</tt> hook and must be written into a <tt>struct stat</tt> 112 buffer. 113 114 115 \section vnodes VNodes 116 117 A vnode is the VFS representation of a node. As soon as an access to a node 118 is requested, the VFS creates a corresponding vnode. The requesting entity 119 gets a reference to the vnode for the time it works with the vnode and 120 releases the reference when done. When the last reference to a vnode has been 121 surrendered, the vnode is unused and the VFS can decide to destroy it 122 (usually it is cached for a while longer). 123 124 When the VFS creates a vnode, it invokes the FS's 125 \link file_system_module_info::get_vnode get_vnode() \endlink 126 hook to let it create the respective node handle (unless the FS requests the 127 creation of the vnode explicitely by calling publish_vnode()). That's the 128 only hook that specifies a node by ID; to all other node-related hooks the 129 node handle is passed. When the VFS deletes the vnode, it invokes the FS's 130 \link file_system_module_info::put_vnode put_vnode() \endlink 131 hook or, if the node was marked removed, 132 \link file_system_module_info::remove_vnode remove_vnode() \endlink. 133 134 There are only four FS hooks through which the VFS gains knowledge of the 135 existence of a node. The first one is the 136 \link file_system_module_info::mount mount() \endlink 137 hook. It is supposed to call \c publish_vnode() for the root node of the 138 volume and return its ID. The second one is the 139 \link file_system_module_info::lookup lookup() \endlink 140 hook. Given a node handle of a directory and an entry name, it is supposed to 141 call \c get_vnode() for the node the entry refers to and return the node ID. 142 The remaining two hooks, 143 \link file_system_module_info::read_dir read_dir() \endlink and 144 \link file_system_module_info::read_query read_query() \endlink, 145 both return entries in a <tt>struct dirent</tt> structure, which also 146 contains the ID of the node the entry refers to. 147 148 149 \section mandatory_hooks Mandatory Hooks 150 151 Which hooks a FS module should provide mainly depends on what functionality 152 it features. E.g. a FS without support for attribute, indices, and/or queries 153 can omit the respective hooks (i.e. set them to \c NULL in the module 154 structure). Some hooks are mandatory, though. A minimal read-only FS module 155 must implement: 156 157 - \link file_system_module_info::mount mount() \endlink and 158 \link file_system_module_info::unmount unmount() \endlink: 159 Mounting and unmounting a volume is required for pretty obvious reasons. 160 161 - \link file_system_module_info::lookup lookup() \endlink: 162 The VFS uses this hook to resolve path names. It is probably one of the 163 most frequently invoked hooks. 164 165 - \link file_system_module_info::get_vnode get_vnode() \endlink and 166 \link file_system_module_info::put_vnode put_vnode() \endlink: 167 Create respectively destroy the FS's private node handle when 168 the VFS creates/deletes the vnode for a particular node. 169 170 - \link file_system_module_info::read_stat read_stat() \endlink: 171 Return a <tt>struct stat</tt> info for the given node, consisting of the 172 type and size of the node, its owner and access permissions, as well as 173 certain access times. 174 175 - \link file_system_module_info::open open() \endlink, 176 \link file_system_module_info::close close() \endlink, and 177 \link file_system_module_info::free_cookie free_cookie() \endlink: 178 Open and close a node as explained in \ref concepts. 179 180 - \link file_system_module_info::read read() \endlink: 181 Read data from an opened node (file). Even if the FS does not feature 182 files, the hook has to be present anyway; it should return an error in this 183 case. 184 185 - \link file_system_module_info::open_dir open_dir() \endlink, 186 \link file_system_module_info::close_dir close_dir() \endlink, and 187 \link file_system_module_info::free_dir_cookie free_dir_cookie() \endlink: 188 Open and close a directory for entry iteration as explained in 189 \ref concepts. 190 191 - \link file_system_module_info::read_dir read_dir() \endlink and 192 \link file_system_module_info::rewind_dir rewind_dir() \endlink: 193 Read the next entry/entries from a directory, respectively reset the 194 iterator to the first entry, as explained in \ref concepts. 195 196 Although not strictly mandatory, a FS should additionally implement the 197 following hooks: 198 199 - \link file_system_module_info::read_fs_info read_fs_info() \endlink: 200 Return general information about the volume, e.g. total and free size, and 201 what special features (attributes, MIME types, queries) the volume/FS 202 supports. 203 204 - \link file_system_module_info::read_symlink read_symlink() \endlink: 205 Read the value of a symbolic link. Needed only, if the FS and volume 206 support symbolic links at all. If absent symbolic links stored on the 207 volume won't be interpreted. 208 209 - \link file_system_module_info::access access() \endlink: 210 Return whether the current user has the given access permissions for a 211 node. If the hook is absent the user is considerd to have all permissions. 212*/ 213