0001 ==========================
0002 Reference counting in pnfs
0003 ==========================
0004
0005 The are several inter-related caches. We have layouts which can
0006 reference multiple devices, each of which can reference multiple data servers.
0007 Each data server can be referenced by multiple devices. Each device
0008 can be referenced by multiple layouts. To keep all of this straight,
0009 we need to reference count.
0010
0011
0012 struct pnfs_layout_hdr
0013 ======================
0014
0015 The on-the-wire command LAYOUTGET corresponds to struct
0016 pnfs_layout_segment, usually referred to by the variable name lseg.
0017 Each nfs_inode may hold a pointer to a cache of these layout
0018 segments in nfsi->layout, of type struct pnfs_layout_hdr.
0019
0020 We reference the header for the inode pointing to it, across each
0021 outstanding RPC call that references it (LAYOUTGET, LAYOUTRETURN,
0022 LAYOUTCOMMIT), and for each lseg held within.
0023
0024 Each header is also (when non-empty) put on a list associated with
0025 struct nfs_client (cl_layouts). Being put on this list does not bump
0026 the reference count, as the layout is kept around by the lseg that
0027 keeps it in the list.
0028
0029 deviceid_cache
0030 ==============
0031
0032 lsegs reference device ids, which are resolved per nfs_client and
0033 layout driver type. The device ids are held in a RCU cache (struct
0034 nfs4_deviceid_cache). The cache itself is referenced across each
0035 mount. The entries (struct nfs4_deviceid) themselves are held across
0036 the lifetime of each lseg referencing them.
0037
0038 RCU is used because the deviceid is basically a write once, read many
0039 data structure. The hlist size of 32 buckets needs better
0040 justification, but seems reasonable given that we can have multiple
0041 deviceid's per filesystem, and multiple filesystems per nfs_client.
0042
0043 The hash code is copied from the nfsd code base. A discussion of
0044 hashing and variations of this algorithm can be found `here.
0045 <http://groups.google.com/group/comp.lang.c/browse_thread/thread/9522965e2b8d3809>`_
0046
0047 data server cache
0048 =================
0049
0050 file driver devices refer to data servers, which are kept in a module
0051 level cache. Its reference is held over the lifetime of the deviceid
0052 pointing to it.
0053
0054 lseg
0055 ====
0056
0057 lseg maintains an extra reference corresponding to the NFS_LSEG_VALID
0058 bit which holds it in the pnfs_layout_hdr's list. When the final lseg
0059 is removed from the pnfs_layout_hdr's list, the NFS_LAYOUT_DESTROYED
0060 bit is set, preventing any new lsegs from being added.
0061
0062 layout drivers
0063 ==============
0064
0065 PNFS utilizes what is called layout drivers. The STD defines 4 basic
0066 layout types: "files", "objects", "blocks", and "flexfiles". For each
0067 of these types there is a layout-driver with a common function-vectors
0068 table which are called by the nfs-client pnfs-core to implement the
0069 different layout types.
0070
0071 Files-layout-driver code is in: fs/nfs/filelayout/.. directory
0072 Blocks-layout-driver code is in: fs/nfs/blocklayout/.. directory
0073 Flexfiles-layout-driver code is in: fs/nfs/flexfilelayout/.. directory
0074
0075 blocks-layout setup
0076 ===================
0077
0078 TODO: Document the setup needs of the blocks layout driver
