a47cc819f37bb7f5535afbf2bf720766ae51dfdd
[linux-2.6.git] / Documentation / filesystems / vfs.txt
1
2               Overview of the Linux Virtual File System
3
4         Original author: Richard Gooch <rgooch@atnf.csiro.au>
5
6                   Last updated on October 28, 2005
7
8   Copyright (C) 1999 Richard Gooch
9   Copyright (C) 2005 Pekka Enberg
10
11   This file is released under the GPLv2.
12
13
14 Introduction
15 ============
16
17 The Virtual File System (also known as the Virtual Filesystem Switch)
18 is the software layer in the kernel that provides the filesystem
19 interface to userspace programs. It also provides an abstraction
20 within the kernel which allows different filesystem implementations to
21 coexist.
22
23 VFS system calls open(2), stat(2), read(2), write(2), chmod(2) and so
24 on are called from a process context. Filesystem locking is described
25 in the document Documentation/filesystems/Locking.
26
27
28 Directory Entry Cache (dcache)
29 ------------------------------
30
31 The VFS implements the open(2), stat(2), chmod(2), and similar system
32 calls. The pathname argument that is passed to them is used by the VFS
33 to search through the directory entry cache (also known as the dentry
34 cache or dcache). This provides a very fast look-up mechanism to
35 translate a pathname (filename) into a specific dentry. Dentries live
36 in RAM and are never saved to disc: they exist only for performance.
37
38 The dentry cache is meant to be a view into your entire filespace. As
39 most computers cannot fit all dentries in the RAM at the same time,
40 some bits of the cache are missing. In order to resolve your pathname
41 into a dentry, the VFS may have to resort to creating dentries along
42 the way, and then loading the inode. This is done by looking up the
43 inode.
44
45
46 The Inode Object
47 ----------------
48
49 An individual dentry usually has a pointer to an inode. Inodes are
50 filesystem objects such as regular files, directories, FIFOs and other
51 beasts.  They live either on the disc (for block device filesystems)
52 or in the memory (for pseudo filesystems). Inodes that live on the
53 disc are copied into the memory when required and changes to the inode
54 are written back to disc. A single inode can be pointed to by multiple
55 dentries (hard links, for example, do this).
56
57 To look up an inode requires that the VFS calls the lookup() method of
58 the parent directory inode. This method is installed by the specific
59 filesystem implementation that the inode lives in. Once the VFS has
60 the required dentry (and hence the inode), we can do all those boring
61 things like open(2) the file, or stat(2) it to peek at the inode
62 data. The stat(2) operation is fairly simple: once the VFS has the
63 dentry, it peeks at the inode data and passes some of it back to
64 userspace.
65
66
67 The File Object
68 ---------------
69
70 Opening a file requires another operation: allocation of a file
71 structure (this is the kernel-side implementation of file
72 descriptors). The freshly allocated file structure is initialized with
73 a pointer to the dentry and a set of file operation member functions.
74 These are taken from the inode data. The open() file method is then
75 called so the specific filesystem implementation can do it's work. You
76 can see that this is another switch performed by the VFS. The file
77 structure is placed into the file descriptor table for the process.
78
79 Reading, writing and closing files (and other assorted VFS operations)
80 is done by using the userspace file descriptor to grab the appropriate
81 file structure, and then calling the required file structure method to
82 do whatever is required. For as long as the file is open, it keeps the
83 dentry in use, which in turn means that the VFS inode is still in use.
84
85
86 Registering and Mounting a Filesystem
87 =====================================
88
89 To register and unregister a filesystem, use the following API
90 functions:
91
92    #include <linux/fs.h>
93
94    extern int register_filesystem(struct file_system_type *);
95    extern int unregister_filesystem(struct file_system_type *);
96
97 The passed struct file_system_type describes your filesystem. When a
98 request is made to mount a device onto a directory in your filespace,
99 the VFS will call the appropriate get_sb() method for the specific
100 filesystem. The dentry for the mount point will then be updated to
101 point to the root inode for the new filesystem.
102
103 You can see all filesystems that are registered to the kernel in the
104 file /proc/filesystems.
105
106
107 struct file_system_type
108 -----------------------
109
110 This describes the filesystem. As of kernel 2.6.13, the following
111 members are defined:
112
113 struct file_system_type {
114         const char *name;
115         int fs_flags;
116         int (*get_sb) (struct file_system_type *, int,
117                        const char *, void *, struct vfsmount *);
118         void (*kill_sb) (struct super_block *);
119         struct module *owner;
120         struct file_system_type * next;
121         struct list_head fs_supers;
122 };
123
124   name: the name of the filesystem type, such as "ext2", "iso9660",
125         "msdos" and so on
126
127   fs_flags: various flags (i.e. FS_REQUIRES_DEV, FS_NO_DCACHE, etc.)
128
129   get_sb: the method to call when a new instance of this
130         filesystem should be mounted
131
132   kill_sb: the method to call when an instance of this filesystem
133         should be unmounted
134
135   owner: for internal VFS use: you should initialize this to THIS_MODULE in
136         most cases.
137
138   next: for internal VFS use: you should initialize this to NULL
139
140 The get_sb() method has the following arguments:
141
142   struct super_block *sb: the superblock structure. This is partially
143         initialized by the VFS and the rest must be initialized by the
144         get_sb() method
145
146   int flags: mount flags
147
148   const char *dev_name: the device name we are mounting.
149
150   void *data: arbitrary mount options, usually comes as an ASCII
151         string
152
153   int silent: whether or not to be silent on error
154
155 The get_sb() method must determine if the block device specified
156 in the superblock contains a filesystem of the type the method
157 supports. On success the method returns the superblock pointer, on
158 failure it returns NULL.
159
160 The most interesting member of the superblock structure that the
161 get_sb() method fills in is the "s_op" field. This is a pointer to
162 a "struct super_operations" which describes the next level of the
163 filesystem implementation.
164
165 Usually, a filesystem uses one of the generic get_sb() implementations
166 and provides a fill_super() method instead. The generic methods are:
167
168   get_sb_bdev: mount a filesystem residing on a block device
169
170   get_sb_nodev: mount a filesystem that is not backed by a device
171
172   get_sb_single: mount a filesystem which shares the instance between
173         all mounts
174
175 A fill_super() method implementation has the following arguments:
176
177   struct super_block *sb: the superblock structure. The method fill_super()
178         must initialize this properly.
179
180   void *data: arbitrary mount options, usually comes as an ASCII
181         string
182
183   int silent: whether or not to be silent on error
184
185
186 The Superblock Object
187 =====================
188
189 A superblock object represents a mounted filesystem.
190
191
192 struct super_operations
193 -----------------------
194
195 This describes how the VFS can manipulate the superblock of your
196 filesystem. As of kernel 2.6.13, the following members are defined:
197
198 struct super_operations {
199         struct inode *(*alloc_inode)(struct super_block *sb);
200         void (*destroy_inode)(struct inode *);
201
202         void (*read_inode) (struct inode *);
203
204         void (*dirty_inode) (struct inode *);
205         int (*write_inode) (struct inode *, int);
206         void (*put_inode) (struct inode *);
207         void (*drop_inode) (struct inode *);
208         void (*delete_inode) (struct inode *);
209         void (*put_super) (struct super_block *);
210         void (*write_super) (struct super_block *);
211         int (*sync_fs)(struct super_block *sb, int wait);
212         void (*write_super_lockfs) (struct super_block *);
213         void (*unlockfs) (struct super_block *);
214         int (*statfs) (struct dentry *, struct kstatfs *);
215         int (*remount_fs) (struct super_block *, int *, char *);
216         void (*clear_inode) (struct inode *);
217         void (*umount_begin) (struct super_block *);
218
219         void (*sync_inodes) (struct super_block *sb,
220                                 struct writeback_control *wbc);
221         int (*show_options)(struct seq_file *, struct vfsmount *);
222
223         ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t);
224         ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t);
225 };
226
227 All methods are called without any locks being held, unless otherwise
228 noted. This means that most methods can block safely. All methods are
229 only called from a process context (i.e. not from an interrupt handler
230 or bottom half).
231
232   alloc_inode: this method is called by inode_alloc() to allocate memory
233         for struct inode and initialize it.  If this function is not
234         defined, a simple 'struct inode' is allocated.  Normally
235         alloc_inode will be used to allocate a larger structure which
236         contains a 'struct inode' embedded within it.
237
238   destroy_inode: this method is called by destroy_inode() to release
239         resources allocated for struct inode.  It is only required if
240         ->alloc_inode was defined and simply undoes anything done by
241         ->alloc_inode.
242
243   read_inode: this method is called to read a specific inode from the
244         mounted filesystem.  The i_ino member in the struct inode is
245         initialized by the VFS to indicate which inode to read. Other
246         members are filled in by this method.
247
248         You can set this to NULL and use iget5_locked() instead of iget()
249         to read inodes.  This is necessary for filesystems for which the
250         inode number is not sufficient to identify an inode.
251
252   dirty_inode: this method is called by the VFS to mark an inode dirty.
253
254   write_inode: this method is called when the VFS needs to write an
255         inode to disc.  The second parameter indicates whether the write
256         should be synchronous or not, not all filesystems check this flag.
257
258   put_inode: called when the VFS inode is removed from the inode
259         cache.
260
261   drop_inode: called when the last access to the inode is dropped,
262         with the inode_lock spinlock held.
263
264         This method should be either NULL (normal UNIX filesystem
265         semantics) or "generic_delete_inode" (for filesystems that do not
266         want to cache inodes - causing "delete_inode" to always be
267         called regardless of the value of i_nlink)
268
269         The "generic_delete_inode()" behavior is equivalent to the
270         old practice of using "force_delete" in the put_inode() case,
271         but does not have the races that the "force_delete()" approach
272         had. 
273
274   delete_inode: called when the VFS wants to delete an inode
275
276   put_super: called when the VFS wishes to free the superblock
277         (i.e. unmount). This is called with the superblock lock held
278
279   write_super: called when the VFS superblock needs to be written to
280         disc. This method is optional
281
282   sync_fs: called when VFS is writing out all dirty data associated with
283         a superblock. The second parameter indicates whether the method
284         should wait until the write out has been completed. Optional.
285
286   write_super_lockfs: called when VFS is locking a filesystem and
287         forcing it into a consistent state.  This method is currently
288         used by the Logical Volume Manager (LVM).
289
290   unlockfs: called when VFS is unlocking a filesystem and making it writable
291         again.
292
293   statfs: called when the VFS needs to get filesystem statistics. This
294         is called with the kernel lock held
295
296   remount_fs: called when the filesystem is remounted. This is called
297         with the kernel lock held
298
299   clear_inode: called then the VFS clears the inode. Optional
300
301   umount_begin: called when the VFS is unmounting a filesystem.
302
303   sync_inodes: called when the VFS is writing out dirty data associated with
304         a superblock.
305
306   show_options: called by the VFS to show mount options for /proc/<pid>/mounts.
307
308   quota_read: called by the VFS to read from filesystem quota file.
309
310   quota_write: called by the VFS to write to filesystem quota file.
311
312 The read_inode() method is responsible for filling in the "i_op"
313 field. This is a pointer to a "struct inode_operations" which
314 describes the methods that can be performed on individual inodes.
315
316
317 The Inode Object
318 ================
319
320 An inode object represents an object within the filesystem.
321
322
323 struct inode_operations
324 -----------------------
325
326 This describes how the VFS can manipulate an inode in your
327 filesystem. As of kernel 2.6.13, the following members are defined:
328
329 struct inode_operations {
330         int (*create) (struct inode *,struct dentry *,int, struct nameidata *);
331         struct dentry * (*lookup) (struct inode *,struct dentry *, struct nameidata *);
332         int (*link) (struct dentry *,struct inode *,struct dentry *);
333         int (*unlink) (struct inode *,struct dentry *);
334         int (*symlink) (struct inode *,struct dentry *,const char *);
335         int (*mkdir) (struct inode *,struct dentry *,int);
336         int (*rmdir) (struct inode *,struct dentry *);
337         int (*mknod) (struct inode *,struct dentry *,int,dev_t);
338         int (*rename) (struct inode *, struct dentry *,
339                         struct inode *, struct dentry *);
340         int (*readlink) (struct dentry *, char __user *,int);
341         void * (*follow_link) (struct dentry *, struct nameidata *);
342         void (*put_link) (struct dentry *, struct nameidata *, void *);
343         void (*truncate) (struct inode *);
344         int (*permission) (struct inode *, int, struct nameidata *);
345         int (*setattr) (struct dentry *, struct iattr *);
346         int (*getattr) (struct vfsmount *mnt, struct dentry *, struct kstat *);
347         int (*setxattr) (struct dentry *, const char *,const void *,size_t,int);
348         ssize_t (*getxattr) (struct dentry *, const char *, void *, size_t);
349         ssize_t (*listxattr) (struct dentry *, char *, size_t);
350         int (*removexattr) (struct dentry *, const char *);
351 };
352
353 Again, all methods are called without any locks being held, unless
354 otherwise noted.
355
356   create: called by the open(2) and creat(2) system calls. Only
357         required if you want to support regular files. The dentry you
358         get should not have an inode (i.e. it should be a negative
359         dentry). Here you will probably call d_instantiate() with the
360         dentry and the newly created inode
361
362   lookup: called when the VFS needs to look up an inode in a parent
363         directory. The name to look for is found in the dentry. This
364         method must call d_add() to insert the found inode into the
365         dentry. The "i_count" field in the inode structure should be
366         incremented. If the named inode does not exist a NULL inode
367         should be inserted into the dentry (this is called a negative
368         dentry). Returning an error code from this routine must only
369         be done on a real error, otherwise creating inodes with system
370         calls like create(2), mknod(2), mkdir(2) and so on will fail.
371         If you wish to overload the dentry methods then you should
372         initialise the "d_dop" field in the dentry; this is a pointer
373         to a struct "dentry_operations".
374         This method is called with the directory inode semaphore held
375
376   link: called by the link(2) system call. Only required if you want
377         to support hard links. You will probably need to call
378         d_instantiate() just as you would in the create() method
379
380   unlink: called by the unlink(2) system call. Only required if you
381         want to support deleting inodes
382
383   symlink: called by the symlink(2) system call. Only required if you
384         want to support symlinks. You will probably need to call
385         d_instantiate() just as you would in the create() method
386
387   mkdir: called by the mkdir(2) system call. Only required if you want
388         to support creating subdirectories. You will probably need to
389         call d_instantiate() just as you would in the create() method
390
391   rmdir: called by the rmdir(2) system call. Only required if you want
392         to support deleting subdirectories
393
394   mknod: called by the mknod(2) system call to create a device (char,
395         block) inode or a named pipe (FIFO) or socket. Only required
396         if you want to support creating these types of inodes. You
397         will probably need to call d_instantiate() just as you would
398         in the create() method
399
400   rename: called by the rename(2) system call to rename the object to
401         have the parent and name given by the second inode and dentry.
402
403   readlink: called by the readlink(2) system call. Only required if
404         you want to support reading symbolic links
405
406   follow_link: called by the VFS to follow a symbolic link to the
407         inode it points to.  Only required if you want to support
408         symbolic links.  This method returns a void pointer cookie
409         that is passed to put_link().
410
411   put_link: called by the VFS to release resources allocated by
412         follow_link().  The cookie returned by follow_link() is passed
413         to this method as the last parameter.  It is used by
414         filesystems such as NFS where page cache is not stable
415         (i.e. page that was installed when the symbolic link walk
416         started might not be in the page cache at the end of the
417         walk).
418
419   truncate: called by the VFS to change the size of a file.  The
420         i_size field of the inode is set to the desired size by the
421         VFS before this method is called.  This method is called by
422         the truncate(2) system call and related functionality.
423
424   permission: called by the VFS to check for access rights on a POSIX-like
425         filesystem.
426
427   setattr: called by the VFS to set attributes for a file. This method
428         is called by chmod(2) and related system calls.
429
430   getattr: called by the VFS to get attributes of a file. This method
431         is called by stat(2) and related system calls.
432
433   setxattr: called by the VFS to set an extended attribute for a file.
434         Extended attribute is a name:value pair associated with an
435         inode. This method is called by setxattr(2) system call.
436
437   getxattr: called by the VFS to retrieve the value of an extended
438         attribute name. This method is called by getxattr(2) function
439         call.
440
441   listxattr: called by the VFS to list all extended attributes for a
442         given file. This method is called by listxattr(2) system call.
443
444   removexattr: called by the VFS to remove an extended attribute from
445         a file. This method is called by removexattr(2) system call.
446
447
448 The Address Space Object
449 ========================
450
451 The address space object is used to group and manage pages in the page
452 cache.  It can be used to keep track of the pages in a file (or
453 anything else) and also track the mapping of sections of the file into
454 process address spaces.
455
456 There are a number of distinct yet related services that an
457 address-space can provide.  These include communicating memory
458 pressure, page lookup by address, and keeping track of pages tagged as
459 Dirty or Writeback.
460
461 The first can be used independently to the others.  The VM can try to
462 either write dirty pages in order to clean them, or release clean
463 pages in order to reuse them.  To do this it can call the ->writepage
464 method on dirty pages, and ->releasepage on clean pages with
465 PagePrivate set. Clean pages without PagePrivate and with no external
466 references will be released without notice being given to the
467 address_space.
468
469 To achieve this functionality, pages need to be placed on an LRU with
470 lru_cache_add and mark_page_active needs to be called whenever the
471 page is used.
472
473 Pages are normally kept in a radix tree index by ->index. This tree
474 maintains information about the PG_Dirty and PG_Writeback status of
475 each page, so that pages with either of these flags can be found
476 quickly.
477
478 The Dirty tag is primarily used by mpage_writepages - the default
479 ->writepages method.  It uses the tag to find dirty pages to call
480 ->writepage on.  If mpage_writepages is not used (i.e. the address
481 provides its own ->writepages) , the PAGECACHE_TAG_DIRTY tag is
482 almost unused.  write_inode_now and sync_inode do use it (through
483 __sync_single_inode) to check if ->writepages has been successful in
484 writing out the whole address_space.
485
486 The Writeback tag is used by filemap*wait* and sync_page* functions,
487 via wait_on_page_writeback_range, to wait for all writeback to
488 complete.  While waiting ->sync_page (if defined) will be called on
489 each page that is found to require writeback.
490
491 An address_space handler may attach extra information to a page,
492 typically using the 'private' field in the 'struct page'.  If such
493 information is attached, the PG_Private flag should be set.  This will
494 cause various VM routines to make extra calls into the address_space
495 handler to deal with that data.
496
497 An address space acts as an intermediate between storage and
498 application.  Data is read into the address space a whole page at a
499 time, and provided to the application either by copying of the page,
500 or by memory-mapping the page.
501 Data is written into the address space by the application, and then
502 written-back to storage typically in whole pages, however the
503 address_space has finer control of write sizes.
504
505 The read process essentially only requires 'readpage'.  The write
506 process is more complicated and uses prepare_write/commit_write or
507 set_page_dirty to write data into the address_space, and writepage,
508 sync_page, and writepages to writeback data to storage.
509
510 Adding and removing pages to/from an address_space is protected by the
511 inode's i_mutex.
512
513 When data is written to a page, the PG_Dirty flag should be set.  It
514 typically remains set until writepage asks for it to be written.  This
515 should clear PG_Dirty and set PG_Writeback.  It can be actually
516 written at any point after PG_Dirty is clear.  Once it is known to be
517 safe, PG_Writeback is cleared.
518
519 Writeback makes use of a writeback_control structure...
520
521 struct address_space_operations
522 -------------------------------
523
524 This describes how the VFS can manipulate mapping of a file to page cache in
525 your filesystem. As of kernel 2.6.16, the following members are defined:
526
527 struct address_space_operations {
528         int (*writepage)(struct page *page, struct writeback_control *wbc);
529         int (*readpage)(struct file *, struct page *);
530         int (*sync_page)(struct page *);
531         int (*writepages)(struct address_space *, struct writeback_control *);
532         int (*set_page_dirty)(struct page *page);
533         int (*readpages)(struct file *filp, struct address_space *mapping,
534                         struct list_head *pages, unsigned nr_pages);
535         int (*prepare_write)(struct file *, struct page *, unsigned, unsigned);
536         int (*commit_write)(struct file *, struct page *, unsigned, unsigned);
537         sector_t (*bmap)(struct address_space *, sector_t);
538         int (*invalidatepage) (struct page *, unsigned long);
539         int (*releasepage) (struct page *, int);
540         ssize_t (*direct_IO)(int, struct kiocb *, const struct iovec *iov,
541                         loff_t offset, unsigned long nr_segs);
542         struct page* (*get_xip_page)(struct address_space *, sector_t,
543                         int);
544         /* migrate the contents of a page to the specified target */
545         int (*migratepage) (struct page *, struct page *);
546 };
547
548   writepage: called by the VM to write a dirty page to backing store.
549       This may happen for data integrity reasons (i.e. 'sync'), or
550       to free up memory (flush).  The difference can be seen in
551       wbc->sync_mode.
552       The PG_Dirty flag has been cleared and PageLocked is true.
553       writepage should start writeout, should set PG_Writeback,
554       and should make sure the page is unlocked, either synchronously
555       or asynchronously when the write operation completes.
556
557       If wbc->sync_mode is WB_SYNC_NONE, ->writepage doesn't have to
558       try too hard if there are problems, and may choose to write out
559       other pages from the mapping if that is easier (e.g. due to
560       internal dependencies).  If it chooses not to start writeout, it
561       should return AOP_WRITEPAGE_ACTIVATE so that the VM will not keep
562       calling ->writepage on that page.
563
564       See the file "Locking" for more details.
565
566   readpage: called by the VM to read a page from backing store.
567        The page will be Locked when readpage is called, and should be
568        unlocked and marked uptodate once the read completes.
569        If ->readpage discovers that it needs to unlock the page for
570        some reason, it can do so, and then return AOP_TRUNCATED_PAGE.
571        In this case, the page will be relocated, relocked and if
572        that all succeeds, ->readpage will be called again.
573
574   sync_page: called by the VM to notify the backing store to perform all
575         queued I/O operations for a page. I/O operations for other pages
576         associated with this address_space object may also be performed.
577
578         This function is optional and is called only for pages with
579         PG_Writeback set while waiting for the writeback to complete.
580
581   writepages: called by the VM to write out pages associated with the
582         address_space object.  If wbc->sync_mode is WBC_SYNC_ALL, then
583         the writeback_control will specify a range of pages that must be
584         written out.  If it is WBC_SYNC_NONE, then a nr_to_write is given
585         and that many pages should be written if possible.
586         If no ->writepages is given, then mpage_writepages is used
587         instead.  This will choose pages from the address space that are
588         tagged as DIRTY and will pass them to ->writepage.
589
590   set_page_dirty: called by the VM to set a page dirty.
591         This is particularly needed if an address space attaches
592         private data to a page, and that data needs to be updated when
593         a page is dirtied.  This is called, for example, when a memory
594         mapped page gets modified.
595         If defined, it should set the PageDirty flag, and the
596         PAGECACHE_TAG_DIRTY tag in the radix tree.
597
598   readpages: called by the VM to read pages associated with the address_space
599         object. This is essentially just a vector version of
600         readpage.  Instead of just one page, several pages are
601         requested.
602         readpages is only used for read-ahead, so read errors are
603         ignored.  If anything goes wrong, feel free to give up.
604
605   prepare_write: called by the generic write path in VM to set up a write
606         request for a page.  This indicates to the address space that
607         the given range of bytes is about to be written.  The
608         address_space should check that the write will be able to
609         complete, by allocating space if necessary and doing any other
610         internal housekeeping.  If the write will update parts of
611         any basic-blocks on storage, then those blocks should be
612         pre-read (if they haven't been read already) so that the
613         updated blocks can be written out properly.
614         The page will be locked.  If prepare_write wants to unlock the
615         page it, like readpage, may do so and return
616         AOP_TRUNCATED_PAGE.
617         In this case the prepare_write will be retried one the lock is
618         regained.
619
620         Note: the page _must not_ be marked uptodate in this function
621         (or anywhere else) unless it actually is uptodate right now. As
622         soon as a page is marked uptodate, it is possible for a concurrent
623         read(2) to copy it to userspace.
624
625   commit_write: If prepare_write succeeds, new data will be copied
626         into the page and then commit_write will be called.  It will
627         typically update the size of the file (if appropriate) and
628         mark the inode as dirty, and do any other related housekeeping
629         operations.  It should avoid returning an error if possible -
630         errors should have been handled by prepare_write.
631
632   bmap: called by the VFS to map a logical block offset within object to
633         physical block number. This method is used by the FIBMAP
634         ioctl and for working with swap-files.  To be able to swap to
635         a file, the file must have a stable mapping to a block
636         device.  The swap system does not go through the filesystem
637         but instead uses bmap to find out where the blocks in the file
638         are and uses those addresses directly.
639
640
641   invalidatepage: If a page has PagePrivate set, then invalidatepage
642         will be called when part or all of the page is to be removed
643         from the address space.  This generally corresponds to either a
644         truncation or a complete invalidation of the address space
645         (in the latter case 'offset' will always be 0).
646         Any private data associated with the page should be updated
647         to reflect this truncation.  If offset is 0, then
648         the private data should be released, because the page
649         must be able to be completely discarded.  This may be done by
650         calling the ->releasepage function, but in this case the
651         release MUST succeed.
652
653   releasepage: releasepage is called on PagePrivate pages to indicate
654         that the page should be freed if possible.  ->releasepage
655         should remove any private data from the page and clear the
656         PagePrivate flag.  It may also remove the page from the
657         address_space.  If this fails for some reason, it may indicate
658         failure with a 0 return value.
659         This is used in two distinct though related cases.  The first
660         is when the VM finds a clean page with no active users and
661         wants to make it a free page.  If ->releasepage succeeds, the
662         page will be removed from the address_space and become free.
663
664         The second case if when a request has been made to invalidate
665         some or all pages in an address_space.  This can happen
666         through the fadvice(POSIX_FADV_DONTNEED) system call or by the
667         filesystem explicitly requesting it as nfs and 9fs do (when
668         they believe the cache may be out of date with storage) by
669         calling invalidate_inode_pages2().
670         If the filesystem makes such a call, and needs to be certain
671         that all pages are invalidated, then its releasepage will
672         need to ensure this.  Possibly it can clear the PageUptodate
673         bit if it cannot free private data yet.
674
675   direct_IO: called by the generic read/write routines to perform
676         direct_IO - that is IO requests which bypass the page cache
677         and transfer data directly between the storage and the
678         application's address space.
679
680   get_xip_page: called by the VM to translate a block number to a page.
681         The page is valid until the corresponding filesystem is unmounted.
682         Filesystems that want to use execute-in-place (XIP) need to implement
683         it.  An example implementation can be found in fs/ext2/xip.c.
684
685   migrate_page:  This is used to compact the physical memory usage.
686         If the VM wants to relocate a page (maybe off a memory card
687         that is signalling imminent failure) it will pass a new page
688         and an old page to this function.  migrate_page should
689         transfer any private data across and update any references
690         that it has to the page.
691
692 The File Object
693 ===============
694
695 A file object represents a file opened by a process.
696
697
698 struct file_operations
699 ----------------------
700
701 This describes how the VFS can manipulate an open file. As of kernel
702 2.6.17, the following members are defined:
703
704 struct file_operations {
705         loff_t (*llseek) (struct file *, loff_t, int);
706         ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
707         ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);
708         ssize_t (*aio_read) (struct kiocb *, const struct iovec *, unsigned long, loff_t);
709         ssize_t (*aio_write) (struct kiocb *, const struct iovec *, unsigned long, loff_t);
710         int (*readdir) (struct file *, void *, filldir_t);
711         unsigned int (*poll) (struct file *, struct poll_table_struct *);
712         int (*ioctl) (struct inode *, struct file *, unsigned int, unsigned long);
713         long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long);
714         long (*compat_ioctl) (struct file *, unsigned int, unsigned long);
715         int (*mmap) (struct file *, struct vm_area_struct *);
716         int (*open) (struct inode *, struct file *);
717         int (*flush) (struct file *);
718         int (*release) (struct inode *, struct file *);
719         int (*fsync) (struct file *, struct dentry *, int datasync);
720         int (*aio_fsync) (struct kiocb *, int datasync);
721         int (*fasync) (int, struct file *, int);
722         int (*lock) (struct file *, int, struct file_lock *);
723         ssize_t (*readv) (struct file *, const struct iovec *, unsigned long, loff_t *);
724         ssize_t (*writev) (struct file *, const struct iovec *, unsigned long, loff_t *);
725         ssize_t (*sendfile) (struct file *, loff_t *, size_t, read_actor_t, void *);
726         ssize_t (*sendpage) (struct file *, struct page *, int, size_t, loff_t *, int);
727         unsigned long (*get_unmapped_area)(struct file *, unsigned long, unsigned long, unsigned long, unsigned long);
728         int (*check_flags)(int);
729         int (*dir_notify)(struct file *filp, unsigned long arg);
730         int (*flock) (struct file *, int, struct file_lock *);
731         ssize_t (*splice_write)(struct pipe_inode_info *, struct file *, size_t, unsigned 
732 int);
733         ssize_t (*splice_read)(struct file *, struct pipe_inode_info *, size_t, unsigned  
734 int);
735 };
736
737 Again, all methods are called without any locks being held, unless
738 otherwise noted.
739
740   llseek: called when the VFS needs to move the file position index
741
742   read: called by read(2) and related system calls
743
744   aio_read: called by io_submit(2) and other asynchronous I/O operations
745
746   write: called by write(2) and related system calls
747
748   aio_write: called by io_submit(2) and other asynchronous I/O operations
749
750   readdir: called when the VFS needs to read the directory contents
751
752   poll: called by the VFS when a process wants to check if there is
753         activity on this file and (optionally) go to sleep until there
754         is activity. Called by the select(2) and poll(2) system calls
755
756   ioctl: called by the ioctl(2) system call
757
758   unlocked_ioctl: called by the ioctl(2) system call. Filesystems that do not
759         require the BKL should use this method instead of the ioctl() above.
760
761   compat_ioctl: called by the ioctl(2) system call when 32 bit system calls
762          are used on 64 bit kernels.
763
764   mmap: called by the mmap(2) system call
765
766   open: called by the VFS when an inode should be opened. When the VFS
767         opens a file, it creates a new "struct file". It then calls the
768         open method for the newly allocated file structure. You might
769         think that the open method really belongs in
770         "struct inode_operations", and you may be right. I think it's
771         done the way it is because it makes filesystems simpler to
772         implement. The open() method is a good place to initialize the
773         "private_data" member in the file structure if you want to point
774         to a device structure
775
776   flush: called by the close(2) system call to flush a file
777
778   release: called when the last reference to an open file is closed
779
780   fsync: called by the fsync(2) system call
781
782   fasync: called by the fcntl(2) system call when asynchronous
783         (non-blocking) mode is enabled for a file
784
785   lock: called by the fcntl(2) system call for F_GETLK, F_SETLK, and F_SETLKW
786         commands
787
788   readv: called by the readv(2) system call
789
790   writev: called by the writev(2) system call
791
792   sendfile: called by the sendfile(2) system call
793
794   get_unmapped_area: called by the mmap(2) system call
795
796   check_flags: called by the fcntl(2) system call for F_SETFL command
797
798   dir_notify: called by the fcntl(2) system call for F_NOTIFY command
799
800   flock: called by the flock(2) system call
801
802   splice_write: called by the VFS to splice data from a pipe to a file. This
803                 method is used by the splice(2) system call
804
805   splice_read: called by the VFS to splice data from file to a pipe. This
806                method is used by the splice(2) system call
807
808 Note that the file operations are implemented by the specific
809 filesystem in which the inode resides. When opening a device node
810 (character or block special) most filesystems will call special
811 support routines in the VFS which will locate the required device
812 driver information. These support routines replace the filesystem file
813 operations with those for the device driver, and then proceed to call
814 the new open() method for the file. This is how opening a device file
815 in the filesystem eventually ends up calling the device driver open()
816 method.
817
818
819 Directory Entry Cache (dcache)
820 ==============================
821
822
823 struct dentry_operations
824 ------------------------
825
826 This describes how a filesystem can overload the standard dentry
827 operations. Dentries and the dcache are the domain of the VFS and the
828 individual filesystem implementations. Device drivers have no business
829 here. These methods may be set to NULL, as they are either optional or
830 the VFS uses a default. As of kernel 2.6.22, the following members are
831 defined:
832
833 struct dentry_operations {
834         int (*d_revalidate)(struct dentry *, struct nameidata *);
835         int (*d_hash) (struct dentry *, struct qstr *);
836         int (*d_compare) (struct dentry *, struct qstr *, struct qstr *);
837         int (*d_delete)(struct dentry *);
838         void (*d_release)(struct dentry *);
839         void (*d_iput)(struct dentry *, struct inode *);
840         char *(*d_dname)(struct dentry *, char *, int);
841 };
842
843   d_revalidate: called when the VFS needs to revalidate a dentry. This
844         is called whenever a name look-up finds a dentry in the
845         dcache. Most filesystems leave this as NULL, because all their
846         dentries in the dcache are valid
847
848   d_hash: called when the VFS adds a dentry to the hash table
849
850   d_compare: called when a dentry should be compared with another
851
852   d_delete: called when the last reference to a dentry is
853         deleted. This means no-one is using the dentry, however it is
854         still valid and in the dcache
855
856   d_release: called when a dentry is really deallocated
857
858   d_iput: called when a dentry loses its inode (just prior to its
859         being deallocated). The default when this is NULL is that the
860         VFS calls iput(). If you define this method, you must call
861         iput() yourself
862
863   d_dname: called when the pathname of a dentry should be generated.
864         Usefull for some pseudo filesystems (sockfs, pipefs, ...) to delay
865         pathname generation. (Instead of doing it when dentry is created,
866         its done only when the path is needed.). Real filesystems probably
867         dont want to use it, because their dentries are present in global
868         dcache hash, so their hash should be an invariant. As no lock is
869         held, d_dname() should not try to modify the dentry itself, unless
870         appropriate SMP safety is used. CAUTION : d_path() logic is quite
871         tricky. The correct way to return for example "Hello" is to put it
872         at the end of the buffer, and returns a pointer to the first char.
873         dynamic_dname() helper function is provided to take care of this.
874
875 Example :
876
877 static char *pipefs_dname(struct dentry *dent, char *buffer, int buflen)
878 {
879         return dynamic_dname(dentry, buffer, buflen, "pipe:[%lu]",
880                                 dentry->d_inode->i_ino);
881 }
882
883 Each dentry has a pointer to its parent dentry, as well as a hash list
884 of child dentries. Child dentries are basically like files in a
885 directory.
886
887
888 Directory Entry Cache API
889 --------------------------
890
891 There are a number of functions defined which permit a filesystem to
892 manipulate dentries:
893
894   dget: open a new handle for an existing dentry (this just increments
895         the usage count)
896
897   dput: close a handle for a dentry (decrements the usage count). If
898         the usage count drops to 0, the "d_delete" method is called
899         and the dentry is placed on the unused list if the dentry is
900         still in its parents hash list. Putting the dentry on the
901         unused list just means that if the system needs some RAM, it
902         goes through the unused list of dentries and deallocates them.
903         If the dentry has already been unhashed and the usage count
904         drops to 0, in this case the dentry is deallocated after the
905         "d_delete" method is called
906
907   d_drop: this unhashes a dentry from its parents hash list. A
908         subsequent call to dput() will deallocate the dentry if its
909         usage count drops to 0
910
911   d_delete: delete a dentry. If there are no other open references to
912         the dentry then the dentry is turned into a negative dentry
913         (the d_iput() method is called). If there are other
914         references, then d_drop() is called instead
915
916   d_add: add a dentry to its parents hash list and then calls
917         d_instantiate()
918
919   d_instantiate: add a dentry to the alias hash list for the inode and
920         updates the "d_inode" member. The "i_count" member in the
921         inode structure should be set/incremented. If the inode
922         pointer is NULL, the dentry is called a "negative
923         dentry". This function is commonly called when an inode is
924         created for an existing negative dentry
925
926   d_lookup: look up a dentry given its parent and path name component
927         It looks up the child of that given name from the dcache
928         hash table. If it is found, the reference count is incremented
929         and the dentry is returned. The caller must use d_put()
930         to free the dentry when it finishes using it.
931
932 For further information on dentry locking, please refer to the document
933 Documentation/filesystems/dentry-locking.txt.
934
935
936 Resources
937 =========
938
939 (Note some of these resources are not up-to-date with the latest kernel
940  version.)
941
942 Creating Linux virtual filesystems. 2002
943     <http://lwn.net/Articles/13325/>
944
945 The Linux Virtual File-system Layer by Neil Brown. 1999
946     <http://www.cse.unsw.edu.au/~neilb/oss/linux-commentary/vfs.html>
947
948 A tour of the Linux VFS by Michael K. Johnson. 1996
949     <http://www.tldp.org/LDP/khg/HyperNews/get/fs/vfstour.html>
950
951 A small trail through the Linux kernel by Andries Brouwer. 2001
952     <http://www.win.tue.nl/~aeb/linux/vfs/trail.html>