LUDOC-293 protocol: Merge all recent patches

[doc/protocol.git] / setxattr.txt

diff --git a/setxattr.txt b/setxattr.txt
new file mode 100644 (file)
index 0000000..2f575de
--- /dev/null
+++ b/setxattr.txt
@@ -0,0 +1,77 @@
+Setxattr
+~~~~~~~~
+
+The 'setxattr' VFS method is used to modify the extended attributes
+associated with a resource. The 'fsetxattr()' system call induces the
+'setxattr' variant of the MDS_REINT RPC.
+
+.Setxattr RPCs for Modifying a Resource's Extended Attributes
+[[setxattr-rpcs]]
+image::setxattr_rpcs.png["setxattr RPCs for modifying a resource's Extended Attributes",height=100]
+
+//////////////////////////////////////////////////////////////////////
+The setxattr_rpcs.png diagram resembles this text art:
+
+Time
+Step Client         MDT          OST
+     -------        -------      -------
+1    MDS_REINT------->
+2            <-------MDS_REINT
+//////////////////////////////////////////////////////////////////////
+
+1 - The client issues an MDS_REINT with the REINT_SETXATTR
+sub-operation.
+
+In addition to the 'ptlrpc_body' (RPC message header), the MDS_REINT
+request RPC from the client has the REINT structure
+'mdt_rec_setxattr', the name of the extended attribute in question,
+the extended attribute data to put in place, and a lock request
+'ldlm_request'. For a detailed discussion of all the fields in the
+'mdt_rec_setxattr' and 'ldlm_request' refer to <<mdt-rec-setxattr>>
+and <<struct-ldlm-request>>.
+
+.MDS_REINT:REINT_SETXATTR Request Packet Structure
+image::mds-reint-setxattr-request.png["MDS_REINT:REINT_SETXATTR Request Packet Structure",height=50]
+
+//////////////////////////////////////////////////////////////////////
+The mds-reint-setxattr-request.png diagram resembles this text art:
+
+        MDS_REINT:
+      --REINT_SETXATTR-request-------------------------
+      | ptlrpc_body | mdt_rec_setxattr | ldlm_request |
+      -------------------------------------------------
+//////////////////////////////////////////////////////////////////////
+
+The 'setxattr' wants to set the 'ctime' associated with the EA update
+as well, so the one 'sx_valid' flag it uses is OBD_MD_FLCTIME
+(0x00008). The 'sx_valid' field also has the OBD_MD_FLXATTR
+(0x01000000000) flag set, though that is never checked or used.
+
+The 'ldlm_request' structure encompasses an early lock cancellation
+(see <<early-lock-cancellation>>) on the lock that the client had
+previously acquired for the target resource. The lock handle
+identifies this lock. Only lock_count and lock_handle are used, and
+the rest of the ldlm_request is cleared, i.e. all fields set to
+zero. In some instances the ldlm_request is empty (all zeros)
+indicating early lock cancellation is not being used. This may be a
+bug in the code for that instance.
+
+2 - The MDS_REINT reply acknowledges the updated attributes.
+
+In addition to the 'ptlrpc_body' (RPC message header), the MDS_REINT
+reply RPC to the client has the 'mdt_body' structure. For a detailed
+discussion of the fields in the 'mdt_body' refer to <<struct-mdt-body>>.
+
+.MDS_REINT:REINT_SETXATTR Reply Packet Structure
+image::mds-reint-setxattr-reply.png["MDS_REINT:REINT_SETXATTR Reply Packet Structure",height=50]
+
+//////////////////////////////////////////////////////////////////////
+The mds-reint-setxattr-reply.png diagram resembles this text art:
+
+      --REINT_SETXATTR-reply-----
+      | ptlrpc_body | mdt_body |
+      --------------------------
+//////////////////////////////////////////////////////////////////////
+
+The reply from the MDT after the setxattr operation has no valid
+'mdt_body' fields, 'mbo_valid = 0x0.