i2p/haiku-beta6
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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
This commit is contained in:
Ingo Weinhold
2009-03-28 21:50:19 +00:00
parent d2bef01cc4
commit d117d093a2
1 changed files with 72 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/drivers/fs_modules.dox
+72 -62
View File
@@ -26,23 +26,29 @@
- A \em volume is an instance of a file system. For a disk-based file - 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 system it corresponds to a disk, partition, or disk image file. When
mounting a volume the virtual file system layer (VFS) assigns a unique 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 number (ID, of type \c dev_t) to it and a handle (type \c void*) provided
\c fs_volume, in fact \c void*) provided by by the file system. The VFS creates an instance of struct \c fs_volume
the file system. Whenever the FS requests a volume-related service from the that stores these two, an operation vector (\c fs_volume_ops), and other
kernel, it has to pass the volume ID, and whenever the VFS asks the FS to volume related items.
perform an operation, it supplies the handle. Normally the handle is a Whenever the FS is asked to perform an operation the \c fs_volume object
pointer to a data structure the FS allocates to associate data with the is supplied, and whenever the FS requests a volume-related service from
volume. 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 - 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 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 ino_t) and, if in use, also with a handle (type \c void*).
(type \c fs_vnode, in fact \c void*). As for volumes the VFS creates an instance of a structure (\c fs_vnode)
Unlike the volume ID the node ID is defined by the FS. It often for each node in use, storing the FS's handle for the node and an
has a meaning to the FS, e.g. file systems using inodes might choose the operation vector (\c fs_vnode_ops).
inode number corresponding to the node. As long as the volume is mounted Unlike the volume ID the node ID is defined by the FS.
and the node is known to the VFS, its node ID must not change. The node It often has a meaning to the FS, e.g. file systems using inodes might
handle is again a pointer to a data structure allocated by the FS. 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 - 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 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 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 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 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 node, it is also said to support "hard links". It is possible that no
refers to a node. This happens when a node (e.g. a file) is still open, but entry refers to a node. This happens when a node (e.g. a file) is still
the last entry referring to it has been removed (the node will be deleted open, but the last entry referring to it has been removed (the node will
when the it is closed). While entries are to be understood as independent be deleted when the it is closed). While entries are to be understood as
entities, the FS interface does not use IDs or handles to refer to them; independent entities, the FS interface does not use IDs or handles to
it always uses directory and entry name pairs to do that. 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 - An \em attribute is a named and typed data container belonging to a node.
node may have any number of attributes; they are organized in a (virtual or A node may have any number of attributes; they are organized in a
actually existing) attribute directory, through which one can iterate. (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 - An \em index is supposed to provide fast searching capabilities for
attributes with a certain name. A volume's index directory allows 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 <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 needed to identify the object to be opened and, in some cases, additional
parameters e.g. specifying a particular opening mode. The implementation parameters e.g. specifying a particular opening mode. The implementation
is required to return a cookie (type \c fs_cookie, in fact \c void*), is required to return a cookie (type \c void*), usually a pointer to a
usually a pointer to a data structure the FS allocates. In some cases (e.g. data structure the FS allocates. In some cases (e.g.
when an iteration state is associated with the cookie) a new cookie must 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 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> 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 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 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 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 releases the reference when done. When the last reference to a vnode has
surrendered, the vnode is unused and the VFS can decide to destroy it been surrendered, the vnode is unused and the VFS can decide to destroy it
(usually it is cached for a while longer). (usually it is cached for a while longer).
When the VFS creates a vnode, it invokes the FS's When the VFS creates a vnode, it invokes the volume's
\link file_system_module_info::get_vnode get_vnode() \endlink \link fs_volume_ops::get_vnode get_vnode() \endlink
hook to let it create the respective node handle (unless the FS requests the 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 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 only hook that specifies a node by ID; all other node-related hooks are
node handle is passed. When the VFS deletes the vnode, it invokes the FS's defined in the respective node's operation vector and they are passed the
\link file_system_module_info::put_vnode put_vnode() \endlink 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, 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 There are only four FS hooks through which the VFS gains knowledge of the
existence of a node. The first one is the existence of a node. The first one is the
\link file_system_module_info::mount mount() \endlink \link file_system_module_info::mount mount() \endlink
hook. It is supposed to call \c publish_vnode() for the root node of the 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 volume and return its ID. The second one is the
\link file_system_module_info::lookup lookup() \endlink \link fs_vnode_ops::lookup lookup() \endlink
hook. Given a node handle of a directory and an entry name, it is supposed to hook. Given a \c fs_vnode object of a directory and an entry name, it is
call \c get_vnode() for the node the entry refers to and return the node ID. supposed to call \c get_vnode() for the node the entry refers to and return
the node ID.
The remaining two hooks, The remaining two hooks,
\link file_system_module_info::read_dir read_dir() \endlink and \link fs_vnode_ops::read_dir read_dir() \endlink and
\link file_system_module_info::read_query read_query() \endlink, \link fs_volume_ops::read_query read_query() \endlink,
both return entries in a <tt>struct dirent</tt> structure, which also both return entries in a <tt>struct dirent</tt> structure, which also
contains the ID of the node the entry refers to. contains the ID of the node the entry refers to.
@@ -149,64 +158,65 @@
\section mandatory_hooks Mandatory Hooks \section mandatory_hooks Mandatory Hooks
Which hooks a FS module should provide mainly depends on what functionality 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 it features. E.g. a FS without support for attribute, indices, and/or
can omit the respective hooks (i.e. set them to \c NULL in the module queries can omit the respective hooks (i.e. set them to \c NULL in the
structure). Some hooks are mandatory, though. A minimal read-only FS module module, \c fs_volume_ops, and \c fs_vnode_ops structure). Some hooks are
must implement: mandatory, though. A minimal read-only FS module must implement:
- \link file_system_module_info::mount mount() \endlink and - \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. 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 The VFS uses this hook to resolve path names. It is probably one of the
most frequently invoked hooks. most frequently invoked hooks.
- \link file_system_module_info::get_vnode get_vnode() \endlink and - \link fs_volume_ops::get_vnode get_vnode() \endlink and
\link file_system_module_info::put_vnode put_vnode() \endlink: \link fs_vnode_ops::put_vnode put_vnode() \endlink:
Create respectively destroy the FS's private node handle when Create respectively destroy the FS's private node handle when
the VFS creates/deletes the vnode for a particular node. 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 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 type and size of the node, its owner and access permissions, as well as
certain access times. certain access times.
- \link file_system_module_info::open open() \endlink, - \link fs_vnode_ops::open open() \endlink,
\link file_system_module_info::close close() \endlink, and \link fs_vnode_ops::close close() \endlink, and
\link file_system_module_info::free_cookie free_cookie() \endlink: \link fs_vnode_ops::free_cookie free_cookie() \endlink:
Open and close a node as explained in \ref concepts. 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 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 files, the hook has to be present anyway; it should return an error in
case. this case.
- \link file_system_module_info::open_dir open_dir() \endlink, - \link fs_vnode_ops::open_dir open_dir() \endlink,
\link file_system_module_info::close_dir close_dir() \endlink, and \link fs_vnode_ops::close_dir close_dir() \endlink, and
\link file_system_module_info::free_dir_cookie free_dir_cookie() \endlink: \link fs_vnode_ops::free_dir_cookie free_dir_cookie() \endlink:
Open and close a directory for entry iteration as explained in Open and close a directory for entry iteration as explained in
\ref concepts. \ref concepts.
- \link file_system_module_info::read_dir read_dir() \endlink and - \link fs_vnode_ops::read_dir read_dir() \endlink and
\link file_system_module_info::rewind_dir rewind_dir() \endlink: \link fs_vnode_ops::rewind_dir rewind_dir() \endlink:
Read the next entry/entries from a directory, respectively reset the Read the next entry/entries from a directory, respectively reset the
iterator to the first entry, as explained in \ref concepts. iterator to the first entry, as explained in \ref concepts.
Although not strictly mandatory, a FS should additionally implement the Although not strictly mandatory, a FS should additionally implement the
following hooks: 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 Return general information about the volume, e.g. total and free size, and
what special features (attributes, MIME types, queries) the volume/FS what special features (attributes, MIME types, queries) the volume/FS
supports. 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 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 support symbolic links at all. If absent symbolic links stored on the
volume won't be interpreted. 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 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.
*/ */