LUDOC-293 protocol: Merge all recent patches

[doc/protocol.git] / lustre_messages.txt

diff --git a/lustre_messages.txt b/lustre_messages.txt
index ad3b858..89188f6 100644 (file)
--- a/lustre_messages.txt
+++ b/lustre_messages.txt
@@ -4,14 +4,14 @@ Lustre Messages
 
 A Lustre message is a sequence of bytes. The message begins with a
 <<lustre-message-header,Lustre Message Header>> and has between one
-and nine subsequences called "buffers". Each buffer has a structure
+and nine sub-sequences called "buffers". Each buffer has a structure
 (the size and meaning of the bytes) that corresponds to the 'struct'
 entities in the <<data-structs,Data Structures and Defines Section>>
 Section. The header gives the number of buffers in its 'lm_buffcount'
 field. The first buffer in any message is always the
-<<lustre-message-preamble,Lustre Message Preamble>>. The operation
+<<struct-ptlrpc-body,Lustre RPC Descriptor>>. The operation
 code ('pb_opc' field) and the message type ('pb_type' field: request
-or reply?) in the preamble together specify the "format" of the
+or reply?) in the descriptor together specify the "format" of the
 message, where the format is the number and content of the remaining
 buffers. As a shorthand, it is useful to name each of these formats,
 and the following list gives all of the formats along with the number
@@ -20,119 +20,11 @@ while the combination of 'pb_opc' and 'pb_type' uniquely determines a
 message's format, the reverse is not true. A given format may be used
 in many different messages.
 
-The "Empty" Message
-~~~~~~~~~~~~~~~~~~~
-
-'empty'
-^^^^^^^
-
-.example
-[options="header"]
-|====
-| pb_opc     | pb_type
-| MDS_STATFS | PTL_RPC_MSG_REQUEST
-|====
-
-
-An 'empty' message is one that consists only of the Lustre message
-preamble 'ptlrpc_body'. It occurs as either the request of the reply
-(or both) in a variety of Lustre operations.
-
-.format
-[options="header"]
-|====
-| structure        | meaning
-| ptlrpc_body      | message preamble
-|====
-
-The LDLM Enqueue Client Message
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-'ldlm_enqueue_client'
-^^^^^^^^^^^^^^^^^^^^^
-
-.example
-[options="header"]
-|====
-| pb_opc       | pb_type
-| LDLM_ENQUEUE | PTL_RPC_MSG_REQUEST
-|====
-
-
-An 'ldlm_enqueue_client' message format is used to acquire a lock.
-
-.format
-[options="header"]
-|====
-| structure        | meaning
-| ptlrpc_body      | message preamble
-| ldlm_request     | details of the lock request
-|====
-
-An 'ldlm_enqueue_client' message concatenates two data elements into a
-single byte-stream. The two elements correspond to structures
-detailed in the <<data-structs,Data Structures and Defines Section>>.
-
-The LDLM Enqueue Server Message
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-'ldlm_enqueue_server'
-^^^^^^^^^^^^^^^^^^^^^
-
-.example
-[options="header"]
-|====
-| pb_opc       | pb_type
-| LDLM_ENQUEUE | PTL_RPC_MSG_REPLY
-|====
-
-
-An 'ldlm_enqueue_server' message format is used to inform a client
-about the status of its request for a lock.
-
-.format
-[options="header"]
-|====
-| structure        | meaning
-| ptlrpc_body      | message preamble
-| ldlm_reply       | details of the lock request
-|====
-
-An 'ldlm_enqueue_server' message concatenates two data elements
-into a single byte-stream. The three elements correspond to structures
-detailed in the <<data-structs,Data Structures and Defines Section>>.
-
-The LDLM Enqueue Server Message with LVB
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-'ldlm_enqueue_lvb_server'
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.example
-[options="header"]
-|====
-| pb_opc       | pb_type
-| LDLM_ENQUEUE | PTL_RPC_MSG_REPLY
-|====
-
-
-An 'ldlm_enqueue_lvb_server' message format is used to inform a client
-about the status of its request for a lock.
-
-.format
-[options="header"]
-|====
-| structure        | meaning
-| ptlrpc_body      | message preamble
-| ldlm_reply       | details of the lock request
-| ost_lvb          | lock value block
-|====
-
-An 'ldlm_enqueue_lvb_server' message concatenates three data elements
-into a single byte-stream. It closely resembles the
-'ldlm_enqueue_server' message with the addition of a lock value
-block. The three elements correspond to structures detailed in the
-<<data-structs,Data Structures and Defines Section>>.
+N.B. As each of the following "message formats" is introduced in the
+context of describing "Lustre commands", the corresponding section
+here will be deleted. These brief entries just state the name of the
+format and its structures. That information is better included in the
+section on the command itself. -ACU
 
 The LLog Origin Handle Create Client
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -155,7 +47,7 @@ ask for the creation of a log entry object.
 [options="header"]
 |====
 | structure    | meaning
-| ptlrpc_body  | message preamble
+| ptlrpc_body  | RPC descriptor
 | llogd_body   | LLog description
 | string       | The name of the desired log
 |====
@@ -182,7 +74,7 @@ An 'llogd_body_only' message replies with information about the log.
 [options="header"]
 |====
 | structure    | meaning
-| ptlrpc_body  | message preamble
+| ptlrpc_body  | RPC descriptor
 | llogd_body   | LLog description
 |====
 
@@ -208,7 +100,7 @@ the log.
 [options="header"]
 |====
 | structure     | meaning
-| ptlrpc_body   | message preamble
+| ptlrpc_body   | RPC descriptor
 | llog_log_hdr  | LLog log header info
 |====
 
@@ -234,7 +126,7 @@ next block of data from the log.
 [options="header"]
 |====
 | structure     | meaning
-| ptlrpc_body   | message preamble
+| ptlrpc_body   | RPC descriptor
 | llogd_body    | LLog description
 | eadata       | variable length field for extended attributes
 |====
@@ -260,7 +152,7 @@ with information about the Lustre capabilities of that MDT.
 [options="header"]
 |====
 | structure        | meaning
-| ptlrpc_body      | message preamble
+| ptlrpc_body      | RPC descriptor
 | mdt_body        | Information about the MDT
 | MDT_MD          | OST stripe and index info
 | ACL             | ACLs for the fid
@@ -293,7 +185,7 @@ with information about the Lustre capabilities of that MDT.
 [options="header"]
 |====
 | structure        | meaning
-| ptlrpc_body      | message preamble
+| ptlrpc_body      | RPC descriptor
 | mdt_body        | Information about the MDT
 | lustre_capa     | security capa info
 |====
@@ -322,7 +214,7 @@ An 'mdt_body_only' message format is used to convey MDT data.
 [options="header"]
 |====
 | structure        | meaning
-| ptlrpc_body      | message preamble
+| ptlrpc_body      | RPC descriptor
 | mdt_body        | Information about the MDT
 |====
 
@@ -350,7 +242,7 @@ the MGS.
 [options="header"]
 |====
 | structure        | meaning
-| ptlrpc_body      | message preamble
+| ptlrpc_body      | RPC descriptor
 | mgs_config_body  | Information about the MGS supporting the request
 |====
 
@@ -375,7 +267,7 @@ the MGS.
 [options="header"]
 |====
 | structure        | meaning
-| ptlrpc_body      | message preamble
+| ptlrpc_body      | RPC descriptor
 | mgs_config_body  | Information about the MGS supporting the request
 |====
 
@@ -406,7 +298,7 @@ the obd_connect_server message.
 [options="header"]
 |====
 | structure        | meaning
-| ptlrpc_body      | message preamble
+| ptlrpc_body      | RPC descriptor
 | obd_uuid         | UUID of the target
 | obd_uuid         | UUID of the client
 | lustre_handle    | connection handle
@@ -444,7 +336,7 @@ that server. MGSs, MDSs, and OSSs send these replies.
 [options="header"]
 |====
 | structure        | meaning
-| ptlrpc_body      | message preamble
+| ptlrpc_body      | RPC descriptor
 | obd_connect_data | connection data
 |====
 
@@ -471,7 +363,7 @@ information to the client.
 [options="header"]
 |====
 | structure        | meaning
-| ptlrpc_body      | message preamble
+| ptlrpc_body      | RPC descriptor
 | obd_statfs      | statfs system call info
 |====