Greetings,
Here is a patch for Documentation/filesystems/vfs.txt to add more
information and stuff I found useful to know that was not in the
original document.
Since this is my best understanding of how the filesystems work/are
supposed to work, please tell me about any misconceptions/inaccuracies
present.
As can be seen in the patch, there are still some questions in my mind
about how some of this works. I intend to continue adding to this, so
consider this patch to be a work-in-progress and a RFC.
This patch is against the file at
http://www.atnf.csiro.au/~rgooch/linux/docs/vfs.txt
with information based upon a 2.2.5 kernel. (So the information may or
may not apply to 2.3.*)
Feedback/comments/criticisms/etc. welcome and requested. (cc:
appreciated, but I am subscribed)
Thank you for your time,
Eli
-- --------------------. "To the systems programmer, users and applications Eli Carter | serve only to provide a test load." eli.carter@inet.com `---------------------------------- (random fortune)
--- vfs.txt.orig Tue May 23 12:55:51 2000 +++ vfs.txt Tue May 23 12:55:00 2000 @@ -150,7 +150,9 @@ struct super_block *sb: the superblock structure. This is partially initialised by the VFS and the rest must be initialised by the - read_super() method + read_super() method. The VFS initiallizes the following elements: + s_dev, s_flags, s_dirt, then calls the filesystem specific + read_super, then initializes s_dev, s_rd_only, s_type void *data: arbitrary mount options, usually comes as an ASCII string @@ -211,6 +213,7 @@ put_super: called when the VFS wishes to free the superblock (i.e. unmount). This is called with the superblock lock held + This cleans up and frees anything held by the filesystem. write_super: called when the VFS superblock needs to be written to disc. This method is optional @@ -219,7 +222,8 @@ is called with the kernel lock held remount_fs: called when the filesystem is remounted. This is called - with the kernel lock held + with the kernel lock held. It is used to change the mount options + on the filesystem. A non-zero return value indicates failure. clear_inode: called then the VFS clears the inode. Optional @@ -269,7 +273,8 @@ required if you want to support regular files. The dentry you get should not have an inode (i.e. it should be a negative dentry). Here you will probably call d_instantiate() with the - dentry and the newly created inode + dentry and the newly created inode. Returns <0 on error, 0 + on success. lookup: called when the VFS needs to lookup an inode in a parent directory. The name to look for is found in the dentry. This @@ -316,6 +321,27 @@ inode it points to. Only required if you want to support symbolic links + readpage: there is a generic_readpage + + writepage: + + bmap: given an inode and a file block number, return the + corresponding device block number. + + truncate: truncates a file to length 0, doing any required housecleaning. + + permission: returns 0 if permissions are allowed, -EACCES if denied, + -EROFS if it is a readonly filesystem. Decision is based upon the + low 16 bits of the inode->i_mode field; the bitmap for this is defined + in <linux/stat.h> fs/namei.c has a permission() function -- is this + the default? + + smap: + + updatepage: + + revalidate: + struct file_operations <section> ====================== @@ -350,6 +376,9 @@ write: called by write(2) and related system calls readdir: called when the VFS needs to read the directory contents + This starts at f_pos and moves the f_pos to the end of the last + directory entry read. On error returns <0, other wise returns + 0. poll: called by the VFS when a process wants to check if there is activity on this file and (optionally) go to sleep until there @@ -467,3 +496,101 @@ pointer is NULL, the dentry is called a "negative dentry". This function is commonly called when an inode is created for an existing negative dentry + + +system include files <section> +==================== + +A few things need to be added to <linux/fs.h> to support a new filesystem. +The struct inode and struct super_block each have a union that holds the +filesystem specific data. A new filesystem will need to have its inode +and superblock structures added to these unions. Alternatively, there is +a generic pointer in those unions which can be used instead to alleviate +the need to modify these two structures. + +There are typically three include files created per supported filesystem: + somefs_fs.h Has the on-disk representation of the filesystem + somefs_fs_i.h Defines the somefs_inode_info structure + somefs_fs_sb.h Defines the somefs_sb_info structure + + +for the novice <section> +============== + +bread()s (block read) may only be done with a size argument of s_blocksize. + + +locking issues <section> +============== + +super_block + [un]lock_super() + +inode + ->i_flock + ->i_sem - a semaphore + ->i_atomic_write - atomic write semaphore + + +useful helper functions <section> +======================= + +iget() Returns a struct inode* given an inode number. +iput() Releases a struct inode* gotten from iget(). +clear_inode() Calls filesystem specific clear_inode. +make_bad_inode() Returns a struct inode* with all its functions set to + return -EIO. +get_empty_inode() Returns an empty struct inode*. + +generic_file_mmap() A generic implementation of mmap(). +generic_file_read() A generic implementation of read(); requires an + implementation of bmap()? +generic_readpage() + +EIO_ERROR A function that returns -EIO. Used in bad_file_ops and + bad_inode_ops. + + +useful constant values <section> +====================== + +variables <subsection> +--------- +bad_file_ops +bad_inode_ops + +error return values <subsection> +------------------- +-EACCES User does not have required privledges. +-EBADF Bad file handle. +-EEXIST An operation finds the file already exists +-EFAULT A copy_[to|from]_user() failed. +-EFBIG File is too big for the filesystem to handle. +-EINVAL Arguments are not valid, out of bounds, etc. +-EIO A bread() failed +-EISDIR An operation was attempted on a directory that a directory does + not support. +-ENAMETOOLONG The filename in question is too long for this filesystem. +-ENOENT The filename was not found. +-ENOMEM Not enough memory to complete the requested operation. +-ENOSPC Out of space on the underlying device. +-ENOTDIR A directory only operation was attempted on something other + than a directory. +-ENOTEMPTY Attempt to remove a non-empty directory. +-EPERM User does not have required permissions to complete operation. + + +glossary <section> +======== + +negative dentry - A dentry with the d_inode (a struct inode*) member + set to NULL. This indicates to the filesystem .... what exactly? + + +credits <section> +======= + +Original and maintained by Richard Gooch <rgooch@atnf.csiro.au> +2000-05-22 Additional information on various functions and pointers + for newbies. eli.carter@inet.com +
- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.rutgers.edu Please read the FAQ at http://www.tux.org/lkml/
This archive was generated by hypermail 2b29 : Tue May 23 2000 - 21:00:24 EST