LUDOC-298 protocl: Editorial pass through the document.

[doc/protocol.git] / mds_reint.txt

diff --git a/mds_reint.txt b/mds_reint.txt
index 83153fc..57eae8f 100644 (file)
--- a/mds_reint.txt
+++ b/mds_reint.txt
@@ -2,10 +2,15 @@ RPC 36: MDS_REINT
 ~~~~~~~~~~~~~~~~~
 [[mds-reint-rpc]]
 
-An RPC that implements an operation that will change the state of
-an object on an MDT. There are a variety of operations all gathered
-under the MDS_REINT 'opcode'.
-
+An MDS_REINT RPC ('pb_opc' = 36) is one that implements an operation
+that will change the state of an object on an MDT. There are a variety
+of operations all gathered under the MDS_REINT 'opcode'. The possible
+values for the 'mdt_rec_reint' struct's 'rr_opcode' field give types
+of operations that are encoded as MDS_REINT RPCs:
+
+.MDS Reint Opcodes ('rr_opcode')
+****
+[source,c]
 ----
 typedef enum {
        REINT_SETATTR  = 1,
@@ -16,10 +21,10 @@ typedef enum {
        REINT_OPEN     = 6,
        REINT_SETXATTR = 7,
        REINT_RMENTRY  = 8,
-       REINT_MIGRATE  = 9,
-        REINT_MAX
-} mds_reint_t, mdt_reint_t;
+       REINT_MIGRATE  = 9
+};
 ----
+****
 
 include::struct_mdt_rec_reint.txt[]
 
@@ -27,10 +32,11 @@ REINT_SETATTR RPC
 ^^^^^^^^^^^^^^^^^
 [[mds-reint-setattr-rpc]]
 
-An RPC that implements the 'setattr' sub-command of the MDS_REINT.
+The REINT_SETATTR is an RPC that implements the 'setattr' sub-command
+of the MDS_REINT.
 
 .MDS_REINT:REINT_SETATTR Request Packet Structure
-image::mds-reint-setattr-request.png["MDS_REINT:REINT_SETATTR Request Packet Structure",height=50]
+image::mds-reint-setattr-request.png["MDS_REINT:REINT_SETATTR Request Packet Structure",height=75]
 
 //////////////////////////////////////////////////////////////////////
 The mds-reint-setattr-request.png diagram resembles this text art:
@@ -48,6 +54,10 @@ RPC descriptor. See <<struct-ptlrpc-body>>.
 
 include::struct_mdt_rec_setattr.txt[]
 
+After the 'mdt_rec_setattr' there are several more buffers defined for
+the RPC, but those before the 'ldlm_request' are often unused and
+appear as zero-length buffers in the header.
+
 'lustre_capa'::
 A "capabilities" structure. See <<struct-lustre-capa>>.
 
@@ -89,7 +99,7 @@ Metadata about the resource.
 
 'mdt_md'::
 Layout data for the resource. This buffer is optional and will appear
-as zero length in some packets.
+as zero length in some packets. This needs to be further explained.
 
 'acl'::
 Access control list data. This buffer is optional and will appear as
@@ -110,7 +120,7 @@ REINT_SETXATTR RPC
 An RPC that implements the 'setxattr' sub-command of the MDS_REINT.
 
 .MDS_REINT:REINT_SETXATTR Request Packet Structure
-image::mds-reint-setxattr-request.png["MDS_REINT:REINT_SETXATTR Request Packet Structure",height=50]
+image::mds-reint-setxattr-request.png["MDS_REINT:REINT_SETXATTR Request Packet Structure",height=75]
 
 //////////////////////////////////////////////////////////////////////
 The mds-reint-setxattr-request.png diagram resembles this text art:
@@ -128,8 +138,12 @@ RPC descriptor. See <<struct-ptlrpc-body>>.
 
 include::struct_mdt_rec_setxattr.txt[]
 
+Retruning to the remaining buffers in the REINT_SETXATTR RPC we again
+have several optional buffers followed by the 'ldlm_request'.
+
 'lustre_capa'::
-A "capabilities" structure. See <<struct-lustre-capa>>.
+A "capabilities" structure. See <<struct-lustre-capa>>. This buffer is
+optional and will appear as zero length in some packets.
 
 'mdt_ioepoch'::
 Identifying "epoch" information. This buffer is optional and will