LUDOC-293 protocol: Merge all recent patches

[doc/protocol.git] / ldlm_enqueue.txt

diff --git a/ldlm_enqueue.txt b/ldlm_enqueue.txt
index 4c4cf7c..f1e029c 100644 (file)
--- a/ldlm_enqueue.txt
+++ b/ldlm_enqueue.txt
@@ -7,7 +7,7 @@ clients. In its simplest form it just exchanges 'ldlm_request' and
 'ldlm_reply' descriptors of the desired and granted locks.
 
 .LDLM_ENQUEUE Generic Packet Structure
-image::ldlm-enqueue-generic.png["LDLM_ENQUEUE Generic Packet Structure",height=150]
+image::ldlm-enqueue-generic.png["LDLM_ENQUEUE Generic Packet Structure",height=100]
 
 //////////////////////////////////////////////////////////////////////
 The ldlm-enqueue-generic.png diagram resembles this text
@@ -20,9 +20,6 @@ art:
       --reply---------------------
       | ptlrpc_body | ldlm_reply |
       ----------------------------
-      --extent lvb reply--------------------
-      | ptlrpc_body | ldlm_reply | ost_lvb |
-      --------------------------------------
 //////////////////////////////////////////////////////////////////////
 
 However, there are many variants to this RPCs. A lock request may signal
@@ -48,6 +45,47 @@ art:
       -----------------------------------------
 //////////////////////////////////////////////////////////////////////
 
+And in this example the intent is to get attribute information.
+
+.LDLM_ENQUEUE Intent:Getattr Generic Packet Structure
+image::ldlm-enqueue-intent-getattr-generic.png["LDLM_ENQUEUE Intent:Getattr Generic Packet Structure",height=150]
+
+//////////////////////////////////////////////////////////////////////
+The ldlm-enqueue-intent-getattr-generic.png diagram resembles this text
+art:
+
+       LDLM_ENQUEUE:
+      --intent:getattr request-------------------------------
+      | ptlrpc_body | ldlm_request | ldlm_intent | mdt_body |
+      lustre_capa |name |
+      -------------------------------------------------------
+      --intent:getattr reply--------------------------
+      | ptlrpc_body | ldlm_reply | mdt_body | mdt_md |
+      ------------------------------------------------
+      --intent:lvb reply--------------------
+      | ptlrpc_body | ldlm_reply | ost_lvb |
+      --------------------------------------
+//////////////////////////////////////////////////////////////////////
+
+Here is another example of an intent, in this case the 'getxattr' intent.
+
+.LDLM_ENQUEUE Intent:Getxattr Generic Packet Structure
+image::ldlm-enqueue-intent-getxattr-generic.png["LDLM_ENQUEUE Intent:Getxattr Generic Packet Structure",height=125]
+
+//////////////////////////////////////////////////////////////////////
+The ldlm-enqueue-intent-getxattr-generic.png diagram resembles this text
+art:
+
+       LDLM_ENQUEUE:
+      --intent:getxattr request------------------------------------
+      | ptlrpc_body | ldlm_request |ldlm_intent | mdt_body | capa |
+      -------------------------------------------------------------
+      --intent:getxattr reply----------------------------------------
+      | ptlrpc_body | ldlm_reply | mdt_body | lov_mds_md | ACL data |
+      | EA data | EA vals | EA lens |
+      ---------------------------------------------------------------
+//////////////////////////////////////////////////////////////////////
+
 'ptlrpc_body'::
 RPC descriptor.
 
@@ -62,10 +100,48 @@ Description of the intent being included with the lock request.
 Description of the layout information that is the subject of a layout
 intent.
 
+'mdt_body'::
+In a request, an indication (in the 'mbo_valid' field) of what
+attributes the requester would like. In a reply, (again based on
+'mbo_valid') the values being returned.
+
+'lustre_capa'::
+So called "capabilities" structure. This is deprecated in recent
+versions of Lustre, and commonly appears in the packet header as a zero
+length buffer.
+
+'name'::
+A text field supplying the name of the desired resource.
+
 'ldlm_reply'::
 Resembling the 'ldlm_request', but in this case indicating what the
 LDLM actually granted as well as relevant policy data.
 
+'mdt_md'::
+Layout data for the resource. This buffer is optional and will appear
+as zero length in some packets.
+
+'mdt_body'::
+Metadata about a given resource.
+
+'ACL data'::
+Access Control List data associated with a resource.
+
+'EA data'::
+The names of any extended attributes associated with the resource. The
+names are null-terminated strings concatenated into a single sequnce.
+
+'EA vals'::
+A block of data concatenating the values for the extended attributes
+listed in "EA vals".
+
+'EA lens'::
+The sizes of the extended attirbute values. This is a sequence of
+32-bit unsigned integers, one for each extended
+attribute. The sizes give the length of the corresponding extended
+attribute in the "EA vals" block of data. Thus the sum of those sizes
+equals the length of the "EA vals".
+
 Lock Value Block::
 A Lock Value Block (LVB) is included in the LDLM_ENQUEUE reply message
 when one of three things needs to be communicated back to the
@@ -84,4 +160,4 @@ An LVB to communicate layout data associated with a resource. It is
 returned from an MDT to a client requesting a lock a lock with a
 layout intent. In an intent request (as opposed to a reply and as yet
 unimplemanted) it will modify the layout. It will not be included
-(zero length) in requests in current releases. 
+(zero length) in requests in current releases.