LUDOC-293 protocol: Merge all recent patches

[doc/protocol.git] / getxattr.txt

diff --git a/getxattr.txt b/getxattr.txt
new file mode 100644 (file)
index 0000000..33d698a
--- /dev/null
+++ b/getxattr.txt
@@ -0,0 +1,97 @@
+Getxattr
+~~~~~~~~
+
+The 'getxattr' VFS method queries extended attribute information for a
+resource given a path ('getxattr()' system call) or FID ('fgetxattr()'
+system call). If provided a path Lustre will go through a path lookup
+first (not shown [fixme: this should be a cross reference]) in order
+to determine the FID for the resource.
+
+Lustre maintains extended attribute information on the MDS, and a
+single RPC (request and reply) retrieves the information from the
+MDT. The RPC is an LDLM_ENQUEUE with the 'getxattr' intent. The RPC is
+shown in <<getxattr-rpcs>>.
+
+.Getxattr RPCs
+[[getxattr-rpcs]]
+image::getxattr_rpcs.png["getxattr RPCs",height=100]
+
+//////////////////////////////////////////////////////////////////////
+The getxattr_rpcs.png diagram resembles this text art:
+
+Time
+Step Client         MDT          OST
+     -------        -------      -------
+1    LDLM_ENQUEUE--->
+2               <---LDLM_ENQUEUE
+//////////////////////////////////////////////////////////////////////
+
+1 - The client issues an LDLM_ENQUEUE with a 'getxattr' intent request
+to the MDS.
+
+The LDLM_ENQUEUE request identifies the resource, and asks for a
+protected read lock on the inode (LDLM_IBITS = 13) with a 'getxattr'
+intent. It accompanies the request with a 'struct mdt_body' that
+provides the FID. The 'mbo_valid' field of the 'mdt_body' is
+0x3000000001 which corresponds to these flags:
+
+.Flags for 'mbo_valid' field of 'struct mdt_body'
+[options="header"]
+|====
+| Flag                | Meaning
+| OBD_MD_FLID         | FID
+| OBD_MD_FLXATTR      | extended attributes
+| OBD_MD_FLXATTRLS    | extended attributes size
+|====
+
+The inclusion of OBD_MD_FLXATTR and OBD_MD_FLXATTRLS indicate that the
+extended attributes are the information being requested for the FID.
+
+.LDLM_ENQUEUE Intent:Getxattr Request Packet Structure
+image::ldlm-enqueue-intent-getxattr-request.png["LDLM_ENQUEUE Intent:Getxattr Request Packet Structure",height=50]
+
+//////////////////////////////////////////////////////////////////////
+The ldlm-enqueue-intent-getxattr-request.png diagram resembles this
+text art:
+
+        LDLM_ENQUEUE:
+      --intent:getxattr request------------------------------
+      | ptlrpc_body | ldlm_request | ldlm_intent | mdt_body |
+      -------------------------------------------------------
+//////////////////////////////////////////////////////////////////////
+
+2 - The MDT replies with an LDLM_ENQUEUE with the extended attributes
+data.
+
+The LDLM_ENQUEUE reply grants the protected read lock on the inode
+bits. A 'struct mdt_body' (see <<struct-mdt-body>>) is present with no
+valid metadata ('mbo_valid' = 0), but the 'mbo_eadatasize',
+'mbo_aclsize', and 'mb_maxmdsize' fields are valid. Those values give
+the sizes of the 'EA data' and 'EA vals' buffers, respectively, and
+the number of (__u32) entries in the 'EA lens' array. The 'struct
+lov_mds_md' and the ACL data are also present but carry no
+information.
+
+.LDLM_ENQUEUE Intent:Getxattr Reply Packet Structure
+image::ldlm-enqueue-intent-getxattr-reply.png["LDLM_ENQUEUE Intent:Getxattr Reply Packet Structure",height=80]
+
+//////////////////////////////////////////////////////////////////////
+The ldlm-enqueue-intent-getxattr-reply.png diagram resembles this
+text art:
+
+        LDLM_ENQUEUE:
+      --intent:getxattr reply----------------------------------------
+      | ptlrpc_body | ldlm_reply | mdt_body | lov_mds_md | ACL data |
+      | EA data | EA vals | EA lens |
+      ---------------------------------------------------------------
+//////////////////////////////////////////////////////////////////////
+
+The last three sections of the message convey the extended attributes
+information. They are formed as follow: The "EA data" section lists a
+sequence of null-terminated strings, where each string identifies an
+extended attribute. The "EA vals" section is a block of data holding
+the values of the listed extended attributes. The "EA lens" section is
+an array of sizes (__u32). Each of those sizes gives the length of the
+EA value, in order, in the "EA values" block.
+
+