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 14Introduction 15============ 16 17The Virtual File System (also known as the Virtual Filesystem Switch) 18is the software layer in the kernel that provides the filesystem 19interface to userspace programs. It also provides an abstraction 20within the kernel which allows different filesystem implementations to 21coexist. 22 23VFS system calls open(2), stat(2), read(2), write(2), chmod(2) and so 24on are called from a process context. Filesystem locking is described 25in the document Documentation/filesystems/Locking. 26 27 28Directory Entry Cache (dcache) 29------------------------------ 30 31The VFS implements the open(2), stat(2), chmod(2), and similar system 32calls. The pathname argument that is passed to them is used by the VFS 33to search through the directory entry cache (also known as the dentry 34cache or dcache). This provides a very fast look-up mechanism to 35translate a pathname (filename) into a specific dentry. Dentries live 36in RAM and are never saved to disc: they exist only for performance. 37 38The dentry cache is meant to be a view into your entire filespace. As 39most computers cannot fit all dentries in the RAM at the same time, 40some bits of the cache are missing. In order to resolve your pathname 41into a dentry, the VFS may have to resort to creating dentries along 42the way, and then loading the inode. This is done by looking up the 43inode. 44 45 46The Inode Object 47---------------- 48 49An individual dentry usually has a pointer to an inode. Inodes are 50filesystem objects such as regular files, directories, FIFOs and other 51beasts. They live either on the disc (for block device filesystems) 52or in the memory (for pseudo filesystems). Inodes that live on the 53disc are copied into the memory when required and changes to the inode 54are written back to disc. A single inode can be pointed to by multiple 55dentries (hard links, for example, do this). 56 57To look up an inode requires that the VFS calls the lookup() method of 58the parent directory inode. This method is installed by the specific 59filesystem implementation that the inode lives in. Once the VFS has 60the required dentry (and hence the inode), we can do all those boring 61things like open(2) the file, or stat(2) it to peek at the inode 62data. The stat(2) operation is fairly simple: once the VFS has the 63dentry, it peeks at the inode data and passes some of it back to 64userspace. 65 66 67The File Object 68--------------- 69 70Opening a file requires another operation: allocation of a file 71structure (this is the kernel-side implementation of file 72descriptors). The freshly allocated file structure is initialized with 73a pointer to the dentry and a set of file operation member functions. 74These are taken from the inode data. The open() file method is then 75called so the specific filesystem implementation can do it's work. You 76can see that this is another switch performed by the VFS. The file 77structure is placed into the file descriptor table for the process. 78 79Reading, writing and closing files (and other assorted VFS operations) 80is done by using the userspace file descriptor to grab the appropriate 81file structure, and then calling the required file structure method to 82do whatever is required. For as long as the file is open, it keeps the 83dentry in use, which in turn means that the VFS inode is still in use. 84 85 86Registering and Mounting a Filesystem 87===================================== 88 89To register and unregister a filesystem, use the following API 90functions: 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 97The passed struct file_system_type describes your filesystem. When a 98request is made to mount a device onto a directory in your filespace, 99the VFS will call the appropriate get_sb() method for the specific 100filesystem. The dentry for the mount point will then be updated to 101point to the root inode for the new filesystem. 102 103You can see all filesystems that are registered to the kernel in the 104file /proc/filesystems. 105 106 107struct file_system_type 108----------------------- 109 110This describes the filesystem. As of kernel 2.6.13, the following 111members are defined: 112 113struct 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 140The 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 155The get_sb() method must determine if the block device specified 156in the superblock contains a filesystem of the type the method 157supports. On success the method returns the superblock pointer, on 158failure it returns NULL. 159 160The most interesting member of the superblock structure that the 161get_sb() method fills in is the "s_op" field. This is a pointer to 162a "struct super_operations" which describes the next level of the 163filesystem implementation. 164 165Usually, a filesystem uses one of the generic get_sb() implementations 166and 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 175A 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 186The Superblock Object 187===================== 188 189A superblock object represents a mounted filesystem. 190 191 192struct super_operations 193----------------------- 194 195This describes how the VFS can manipulate the superblock of your 196filesystem. As of kernel 2.6.13, the following members are defined: 197 198struct 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 227All methods are called without any locks being held, unless otherwise 228noted. This means that most methods can block safely. All methods are 229only called from a process context (i.e. not from an interrupt handler 230or 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 312The read_inode() method is responsible for filling in the "i_op" 313field. This is a pointer to a "struct inode_operations" which 314describes the methods that can be performed on individual inodes. 315 316 317The Inode Object 318================ 319 320An inode object represents an object within the filesystem. 321 322 323struct inode_operations 324----------------------- 325 326This describes how the VFS can manipulate an inode in your 327filesystem. As of kernel 2.6.13, the following members are defined: 328 329struct 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 353Again, all methods are called without any locks being held, unless 354otherwise 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 448The Address Space Object 449======================== 450 451The address space object is used to group and manage pages in the page 452cache. It can be used to keep track of the pages in a file (or 453anything else) and also track the mapping of sections of the file into 454process address spaces. 455 456There are a number of distinct yet related services that an 457address-space can provide. These include communicating memory 458pressure, page lookup by address, and keeping track of pages tagged as 459Dirty or Writeback. 460 461The first can be used independently to the others. The VM can try to 462either write dirty pages in order to clean them, or release clean 463pages in order to reuse them. To do this it can call the ->writepage 464method on dirty pages, and ->releasepage on clean pages with 465PagePrivate set. Clean pages without PagePrivate and with no external 466references will be released without notice being given to the 467address_space. 468 469To achieve this functionality, pages need to be placed on an LRU with 470lru_cache_add and mark_page_active needs to be called whenever the 471page is used. 472 473Pages are normally kept in a radix tree index by ->index. This tree 474maintains information about the PG_Dirty and PG_Writeback status of 475each page, so that pages with either of these flags can be found 476quickly. 477 478The 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 481provides its own ->writepages) , the PAGECACHE_TAG_DIRTY tag is 482almost unused. write_inode_now and sync_inode do use it (through 483__sync_single_inode) to check if ->writepages has been successful in 484writing out the whole address_space. 485 486The Writeback tag is used by filemap*wait* and sync_page* functions, 487via wait_on_page_writeback_range, to wait for all writeback to 488complete. While waiting ->sync_page (if defined) will be called on 489each page that is found to require writeback. 490 491An address_space handler may attach extra information to a page, 492typically using the 'private' field in the 'struct page'. If such 493information is attached, the PG_Private flag should be set. This will 494cause various VM routines to make extra calls into the address_space 495handler to deal with that data. 496 497An address space acts as an intermediate between storage and 498application. Data is read into the address space a whole page at a 499time, and provided to the application either by copying of the page, 500or by memory-mapping the page. 501Data is written into the address space by the application, and then 502written-back to storage typically in whole pages, however the 503address_space has finer control of write sizes. 504 505The read process essentially only requires 'readpage'. The write 506process is more complicated and uses prepare_write/commit_write or 507set_page_dirty to write data into the address_space, and writepage, 508sync_page, and writepages to writeback data to storage. 509 510Adding and removing pages to/from an address_space is protected by the 511inode's i_mutex. 512 513When data is written to a page, the PG_Dirty flag should be set. It 514typically remains set until writepage asks for it to be written. This 515should clear PG_Dirty and set PG_Writeback. It can be actually 516written at any point after PG_Dirty is clear. Once it is known to be 517safe, PG_Writeback is cleared. 518 519Writeback makes use of a writeback_control structure... 520 521struct address_space_operations 522------------------------------- 523 524This describes how the VFS can manipulate mapping of a file to page cache in 525your filesystem. As of kernel 2.6.16, the following members are defined: 526 527struct 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 692The File Object 693=============== 694 695A file object represents a file opened by a process. 696 697 698struct file_operations 699---------------------- 700 701This describes how the VFS can manipulate an open file. As of kernel 7022.6.17, the following members are defined: 703 704struct 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 732int); 733 ssize_t (*splice_read)(struct file *, struct pipe_inode_info *, size_t, unsigned 734int); 735}; 736 737Again, all methods are called without any locks being held, unless 738otherwise 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 808Note that the file operations are implemented by the specific 809filesystem in which the inode resides. When opening a device node 810(character or block special) most filesystems will call special 811support routines in the VFS which will locate the required device 812driver information. These support routines replace the filesystem file 813operations with those for the device driver, and then proceed to call 814the new open() method for the file. This is how opening a device file 815in the filesystem eventually ends up calling the device driver open() 816method. 817 818 819Directory Entry Cache (dcache) 820============================== 821 822 823struct dentry_operations 824------------------------ 825 826This describes how a filesystem can overload the standard dentry 827operations. Dentries and the dcache are the domain of the VFS and the 828individual filesystem implementations. Device drivers have no business 829here. These methods may be set to NULL, as they are either optional or 830the VFS uses a default. As of kernel 2.6.22, the following members are 831defined: 832 833struct 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 875Example : 876 877static 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 883Each dentry has a pointer to its parent dentry, as well as a hash list 884of child dentries. Child dentries are basically like files in a 885directory. 886 887 888Directory Entry Cache API 889-------------------------- 890 891There are a number of functions defined which permit a filesystem to 892manipulate 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 932For further information on dentry locking, please refer to the document 933Documentation/filesystems/dentry-locking.txt. 934 935 936Resources 937========= 938 939(Note some of these resources are not up-to-date with the latest kernel 940 version.) 941 942Creating Linux virtual filesystems. 2002 943 <http://lwn.net/Articles/13325/> 944 945The Linux Virtual File-system Layer by Neil Brown. 1999 946 <http://www.cse.unsw.edu.au/~neilb/oss/linux-commentary/vfs.html> 947 948A tour of the Linux VFS by Michael K. Johnson. 1996 949 <http://www.tldp.org/LDP/khg/HyperNews/get/fs/vfstour.html> 950 951A small trail through the Linux kernel by Andries Brouwer. 2001 952 <http://www.win.tue.nl/~aeb/linux/vfs/trail.html> 953