LUDOC-296 protocol: Rearrange presentation to be more top-down

[doc/protocol.git] / mds_connect.txt

diff --git a/mds_connect.txt b/mds_connect.txt
index 55437e4..a85dbac 100644 (file)
--- a/mds_connect.txt
+++ b/mds_connect.txt
@@ -2,38 +2,35 @@ RPC 38: MDS CONNECT - Client connection to an MDS
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 [[mds-connect-rpc]]
 
-.MDS_CONNECT (38)
-[options="header"]
-|====
-| request
-| ptlrpc_body | tgt_uuid | client_uuid | lustre_handle | obd_connect_data |
-|
-| reply
-| ptlrpc_body | obd_connect_data |
-|====
+.MDS_CONNECT Generic Packet Structure
+image::mds-connect-generic.png["MDS_CONNECT Generic Packet Structure",height=100]
 
-N.B. This is nearly identical to the explanation for OST_CONNECT and
-for MGS_CONNECT.  We may want to simplify and/or unify the discussion
-and only call out how this one differs from a generic CONNECT
-operation.
+//////////////////////////////////////////////////////////////////////
+The mds-connect-generic.png diagram resembles this text art:
 
-When a client initiates a connection to a specific target on an MDS,
-it does so by sending an 'obd_connect_client' message and awaiting the
-reply from the MDS of an 'obd_connect_server' message. From a previous
-interaction with the MGS the client knows the UUID of the target MDT,
-and must fill that value into the 'tgt_uuid' buffer of the request.
+       MDS_CONNECT:
+      --request--------------------------------------------
+      | ptlrpc_body | obd_uuid | obd_uuid | lustre_handle |
+      -----------------------------------------------------
+      |  obd_connect_data |
+      ---------------------
+      --reply---------------------------
+      | ptlrpc_body | obd_connect_data |
+      ----------------------------------
+//////////////////////////////////////////////////////////////////////
 
-The 'client_uuid' buffer holds the randomly-generated 128-bit UUID of
-the client.  The 'client_uuid' is unique for each mount of the client.
-Even if the same client mounts the same filesystem multiple times it
-will generate a new 'client_uuid' value for each mount.
+'ptlrpc_body'::
+RPC descriptor.
 
-The 'lustre_handle' buffer contains the cookie for this connection,
-and is zero for a new mount.  If the client is reconnecting to a
-server after a loss of communication, the 'lustre_handle' contains
-the connection cookie previously assigned by the server and returned
-to the client in the reply.  This allows the server to determine if
-the client connection matches any previous connection from this client.
+'obd_uuid'::
+UUIDs of the target (first) and client (second) entities. See
+<<struct-obd-uuid>>.
+
+'lustre_handle'::
+See <<struct-lustre-handle>>.
+
+'obd_connect_data'::
+See <<struct-obd-connect-data>>.
 
 The 'ocd_connect_flags' buffer is initialized to the set of features
 that the client supports for metadata targets.  For Lustre 2.7 clients