LUDOC-297 protocol: Update protocol document

[doc/protocol.git] / ost_connect.txt

diff --git a/ost_connect.txt b/ost_connect.txt
index aace506..476ac6d 100644 (file)
--- a/ost_connect.txt
+++ b/ost_connect.txt
@@ -3,43 +3,68 @@ RPC 8: OST CONNECT - Client connection to an OST
 [[ost-connect-rpc]]
 
 When a client initiates a connection to a specific target on an OSS,
-it does so via an OST_CONNECT RPC ('pb_oc' = 8). From a previous
-interaction with the MGS the client knows the UUID of the target OST,
-and can fill that value into the 'obd_connect_client' message.
+it does so via an OST_CONNECT RPC ('pb_opc' = 8).
 
-.OST_CONNECT Generic Packet Structure
-image::ost-connect-generic.png["OST_CONNECT Generic Packet Structure",height=100]
+.OST_CONNECT Request Packet Structure
+image::ost-connect-request.png["OST_CONNECT Request Packet Structure",height=50]
 
 //////////////////////////////////////////////////////////////////////
-The ost-connect-generic.png diagram resembles this text art:
+The ost-connect-request.png diagram resembles this text art:
 
        OST_CONNECT:
-      --request--------------------------------------------
-      | ptlrpc_body | obd_uuid | obd_uuid | lustre_handle |
-      -----------------------------------------------------
-      |  obd_connect_data |
-      ---------------------
-      --reply---------------------------
-      | ptlrpc_body | obd_connect_data |
-      ----------------------------------
+      --request--------------------------------------------------
+      | ptlrpc_body | target_uuid | client_uuid | lustre_handle |
+      -----------------------------------------------------------
+      | obd_connect_data |
+      --------------------
 //////////////////////////////////////////////////////////////////////
 
 'ptlrpc_body'::
-RPC descriptor.
+RPC descriptor. See <<struct-ptlrpc-body>>. In a connect message the
+'ptlrpc_body' field 'pb_handle', which is a <<struct-lustre-handle>>,
+is 0. That 'lustre_handle' is distinct from the one mentioned
+below.
+
+'target_uuid'::
+A string identifying the target. See <<struct-obd-uuid>>. The client
+learns the UUID strings for the targets via an interaction with the
+MGS.
 
-'obd_uuid'::
-UUIDs of the target (first) and client (second) entities. See
-<<struct-obd-uuid>>.
+'client_uuid'::
+A string with the client's own UUID. This is also a
+<<struct-obd-uuid>>. The target sets the 'exp_client_uuid' field of
+its 'eport' structure to this value.
 
 'lustre_handle'::
-See <<struct-lustre-handle>>.
+See <<struct-lustre-handle>>. This 'lustre_handle' is distinct from
+the 'pb_handle' field in the 'ptlrpc_body'.  This 'lustre_handle'
+provied a unique 'cookie' to identify this client for this connection
+attempt. After a disconnect, a subsequent connect RPC will have a
+different value. The target preserves this cookie in the 'exp_handle'
+field of its 'obd_export' structure for this client. In that way it
+can distinguish between a resent connection request and an entirely
+new connection request.
 
 'obd_connect_data'::
 See <<struct-obd-connect-data>>.
 
-In the OST_CONNECT RPC reply from the server the 'ptlrpc_body' field
-'pb__handle' is set to uniquely identify the connection for subsequent
-communication. The client notes that handle in its import for the
-given target.
+.OST_CONNECT Reply Packet Structure
+image::ost-connect-reply.png["OST_CONNECT Reply Packet Structure",height=50]
 
+//////////////////////////////////////////////////////////////////////
+The ost-connect-reply.png diagram resembles this text art:
 
+       OST_CONNECT:
+      --reply---------------------------
+      | ptlrpc_body | obd_connect_data |
+      ----------------------------------
+//////////////////////////////////////////////////////////////////////
+
+'ptlrpc_body'::
+RPC descriptor. See <<struct-ptlrpc-body>>. The 'pb_handle' field has
+the value, $C_t$, uniquely identifying that target. The value $C_t$ is
+preserved in the 'imp_remote_handle' field of the client's import
+structure for this target. See <<struct-obd-import>>.
+
+'obd_connect_data'::
+See <<struct-obd-connect-data>>.