Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 1 | |
| 2 | Making Filesystems Exportable |
| 3 | ============================= |
| 4 | |
Christoph Hellwig | e38f981 | 2007-10-21 16:42:19 -0700 | [diff] [blame] | 5 | Overview |
| 6 | -------- |
| 7 | |
| 8 | All filesystem operations require a dentry (or two) as a starting |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 9 | point. Local applications have a reference-counted hold on suitable |
Christoph Hellwig | e38f981 | 2007-10-21 16:42:19 -0700 | [diff] [blame] | 10 | dentries via open file descriptors or cwd/root. However remote |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 11 | applications that access a filesystem via a remote filesystem protocol |
| 12 | such as NFS may not be able to hold such a reference, and so need a |
| 13 | different way to refer to a particular dentry. As the alternative |
| 14 | form of reference needs to be stable across renames, truncates, and |
| 15 | server-reboot (among other things, though these tend to be the most |
| 16 | problematic), there is no simple answer like 'filename'. |
| 17 | |
| 18 | The mechanism discussed here allows each filesystem implementation to |
Christoph Hellwig | e38f981 | 2007-10-21 16:42:19 -0700 | [diff] [blame] | 19 | specify how to generate an opaque (outside of the filesystem) byte |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 20 | string for any dentry, and how to find an appropriate dentry for any |
| 21 | given opaque byte string. |
| 22 | This byte string will be called a "filehandle fragment" as it |
| 23 | corresponds to part of an NFS filehandle. |
| 24 | |
| 25 | A filesystem which supports the mapping between filehandle fragments |
Christoph Hellwig | e38f981 | 2007-10-21 16:42:19 -0700 | [diff] [blame] | 26 | and dentries will be termed "exportable". |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 27 | |
| 28 | |
| 29 | |
| 30 | Dcache Issues |
| 31 | ------------- |
| 32 | |
| 33 | The dcache normally contains a proper prefix of any given filesystem |
| 34 | tree. This means that if any filesystem object is in the dcache, then |
| 35 | all of the ancestors of that filesystem object are also in the dcache. |
| 36 | As normal access is by filename this prefix is created naturally and |
| 37 | maintained easily (by each object maintaining a reference count on |
| 38 | its parent). |
| 39 | |
| 40 | However when objects are included into the dcache by interpreting a |
| 41 | filehandle fragment, there is no automatic creation of a path prefix |
| 42 | for the object. This leads to two related but distinct features of |
| 43 | the dcache that are not needed for normal filesystem access. |
| 44 | |
| 45 | 1/ The dcache must sometimes contain objects that are not part of the |
| 46 | proper prefix. i.e that are not connected to the root. |
| 47 | 2/ The dcache must be prepared for a newly found (via ->lookup) directory |
| 48 | to already have a (non-connected) dentry, and must be able to move |
| 49 | that dentry into place (based on the parent and name in the |
| 50 | ->lookup). This is particularly needed for directories as |
| 51 | it is a dcache invariant that directories only have one dentry. |
| 52 | |
| 53 | To implement these features, the dcache has: |
| 54 | |
| 55 | a/ A dentry flag DCACHE_DISCONNECTED which is set on |
| 56 | any dentry that might not be part of the proper prefix. |
| 57 | This is set when anonymous dentries are created, and cleared when a |
| 58 | dentry is noticed to be a child of a dentry which is in the proper |
| 59 | prefix. |
| 60 | |
| 61 | b/ A per-superblock list "s_anon" of dentries which are the roots of |
| 62 | subtrees that are not in the proper prefix. These dentries, as |
| 63 | well as the proper prefix, need to be released at unmount time. As |
| 64 | these dentries will not be hashed, they are linked together on the |
| 65 | d_hash list_head. |
| 66 | |
| 67 | c/ Helper routines to allocate anonymous dentries, and to help attach |
| 68 | loose directory dentries at lookup time. They are: |
J. Bruce Fields | 9635389 | 2014-02-18 12:31:31 -0500 | [diff] [blame] | 69 | d_obtain_alias(inode) will return a dentry for the given inode. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 70 | If the inode already has a dentry, one of those is returned. |
| 71 | If it doesn't, a new anonymous (IS_ROOT and |
| 72 | DCACHE_DISCONNECTED) dentry is allocated and attached. |
| 73 | In the case of a directory, care is taken that only one dentry |
| 74 | can ever be attached. |
Al Viro | 41d28bc | 2014-10-12 22:24:21 -0400 | [diff] [blame] | 75 | d_splice_alias(inode, dentry) will introduce a new dentry into the tree; |
| 76 | either the passed-in dentry or a preexisting alias for the given inode |
| 77 | (such as an anonymous one created by d_obtain_alias), if appropriate. |
| 78 | It returns NULL when the passed-in dentry is used, following the calling |
| 79 | convention of ->lookup. |
J. Bruce Fields | 9635389 | 2014-02-18 12:31:31 -0500 | [diff] [blame] | 80 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 81 | |
| 82 | Filesystem Issues |
| 83 | ----------------- |
| 84 | |
| 85 | For a filesystem to be exportable it must: |
| 86 | |
| 87 | 1/ provide the filehandle fragment routines described below. |
| 88 | 2/ make sure that d_splice_alias is used rather than d_add |
| 89 | when ->lookup finds an inode for a given parent and name. |
Phillip Lougher | 5b9f456 | 2011-07-26 03:40:45 +0100 | [diff] [blame] | 90 | |
Masanari Iida | 9ed354b | 2013-08-20 20:33:17 +0900 | [diff] [blame] | 91 | If inode is NULL, d_splice_alias(inode, dentry) is equivalent to |
Phillip Lougher | 5b9f456 | 2011-07-26 03:40:45 +0100 | [diff] [blame] | 92 | |
| 93 | d_add(dentry, inode), NULL |
| 94 | |
| 95 | Similarly, d_splice_alias(ERR_PTR(err), dentry) = ERR_PTR(err) |
| 96 | |
| 97 | Typically the ->lookup routine will simply end with a: |
Christoph Hellwig | e38f981 | 2007-10-21 16:42:19 -0700 | [diff] [blame] | 98 | |
| 99 | return d_splice_alias(inode, dentry); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 100 | } |
| 101 | |
| 102 | |
| 103 | |
| 104 | A file system implementation declares that instances of the filesystem |
| 105 | are exportable by setting the s_export_op field in the struct |
| 106 | super_block. This field must point to a "struct export_operations" |
Christoph Hellwig | e38f981 | 2007-10-21 16:42:19 -0700 | [diff] [blame] | 107 | struct which has the following members: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 108 | |
Christoph Hellwig | e38f981 | 2007-10-21 16:42:19 -0700 | [diff] [blame] | 109 | encode_fh (optional) |
| 110 | Takes a dentry and creates a filehandle fragment which can later be used |
| 111 | to find or create a dentry for the same object. The default |
| 112 | implementation creates a filehandle fragment that encodes a 32bit inode |
| 113 | and generation number for the inode encoded, and if necessary the |
| 114 | same information for the parent. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 115 | |
Christoph Hellwig | e38f981 | 2007-10-21 16:42:19 -0700 | [diff] [blame] | 116 | fh_to_dentry (mandatory) |
| 117 | Given a filehandle fragment, this should find the implied object and |
J. Bruce Fields | 9635389 | 2014-02-18 12:31:31 -0500 | [diff] [blame] | 118 | create a dentry for it (possibly with d_obtain_alias). |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 119 | |
Christoph Hellwig | e38f981 | 2007-10-21 16:42:19 -0700 | [diff] [blame] | 120 | fh_to_parent (optional but strongly recommended) |
| 121 | Given a filehandle fragment, this should find the parent of the |
J. Bruce Fields | 9635389 | 2014-02-18 12:31:31 -0500 | [diff] [blame] | 122 | implied object and create a dentry for it (possibly with |
| 123 | d_obtain_alias). May fail if the filehandle fragment is too small. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 124 | |
Christoph Hellwig | e38f981 | 2007-10-21 16:42:19 -0700 | [diff] [blame] | 125 | get_parent (optional but strongly recommended) |
| 126 | When given a dentry for a directory, this should return a dentry for |
| 127 | the parent. Quite possibly the parent dentry will have been allocated |
| 128 | by d_alloc_anon. The default get_parent function just returns an error |
| 129 | so any filehandle lookup that requires finding a parent will fail. |
| 130 | ->lookup("..") is *not* used as a default as it can leave ".." entries |
| 131 | in the dcache which are too messy to work with. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 132 | |
Christoph Hellwig | e38f981 | 2007-10-21 16:42:19 -0700 | [diff] [blame] | 133 | get_name (optional) |
| 134 | When given a parent dentry and a child dentry, this should find a name |
| 135 | in the directory identified by the parent dentry, which leads to the |
| 136 | object identified by the child dentry. If no get_name function is |
| 137 | supplied, a default implementation is provided which uses vfs_readdir |
| 138 | to find potential names, and matches inode numbers to find the correct |
| 139 | match. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 140 | |
| 141 | |
| 142 | A filehandle fragment consists of an array of 1 or more 4byte words, |
| 143 | together with a one byte "type". |
| 144 | The decode_fh routine should not depend on the stated size that is |
| 145 | passed to it. This size may be larger than the original filehandle |
| 146 | generated by encode_fh, in which case it will have been padded with |
| 147 | nuls. Rather, the encode_fh routine should choose a "type" which |
| 148 | indicates the decode_fh how much of the filehandle is valid, and how |
| 149 | it should be interpreted. |