LUDOC-296 protocol: Reorganize the document ot be top-down

[doc/protocol.git] / mds_connect.txt

diff --git a/mds_connect.txt b/mds_connect.txt
new file mode 100644 (file)
index 0000000..99dfa4b
--- /dev/null
+++ b/mds_connect.txt
@@ -0,0 +1,51 @@
+RPC 38: MDS CONNECT - Client connection to an MDS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[[mds-connect-rpc]]
+
+.MDS_CONNECT (38)
+[options="header"]
+|====
+| request            | reply
+| obd_connect_client | obd_connect_server
+|====
+
+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.
+
+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 can fill that value into the 'obd_connect_client' message.
+
+The 'ocd_connect_flags' field is set to (fixme: what?) reflecting the
+capabilities appropriate to the client. The 'ocd_brw_size' is set to the
+largest value for the size of an RPC that the client can handle. The
+'ocd_ibits_known' and 'ocd_checksum_types' values are set to what the client
+considers appropriate. Other fields in the descriptor and
+'obd_connect_data' structures are zero, as is the 'lustre_handle'
+element.
+
+Once the server receives the 'obd_connect_client' message on behalf of
+the given target it replies with an 'obd_connect_server' message. In
+that message the server sends the 'pb__handle' to uniquely
+identify the connection for subsequent communication. The client notes
+that handle in its import for the given target.
+
+fixme: Are there circumstances that could lead to the 'status'
+value in the reply being non-zero? What would lead to that and what
+error values would result?
+
+The target maintains the last committed transaction for a client in
+its export for that client. If this is the first connection, then that
+last transaction value would just be zero. If there were previous
+transactions for the client, then the transaction number for the last
+such committed transaction is put in the 'pb_last_committed' field.
+
+In a connection request the operation is not file system modifying, so
+the 'pb_transno' value will be zero in the reply as well.
+
+fixme: there is still some work to be done about how the fields are
+managed.