1 Ptlrpc_body - The Lustre RPC Descriptor
2 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5 Every Lustre message starts with both the above header and an
6 additional set of fields (in its first "buffer") given by the 'struct
7 ptlrpc_body_v3' structure. This preamble has information information
8 relevant to every RPC type. In particular, the RPC type is itself
9 encoded in the 'pb_opc' Lustre operation number. The value of that
10 opcode, as well as whether it is an RPC 'request' or 'reply',
11 determines what else will be in the message following the preamble.
13 #define PTLRPC_NUM_VERSIONS 4
14 #define JOBSTATS_JOBID_SIZE 32
16 struct lustre_handle pb_handle;
23 __u64 pb_last_committed;
29 __u32 pb_service_time;
32 __u64 pb_pre_versions[PTLRPC_NUM_VERSIONS];
34 char pb_jobid[JOBSTATS_JOBID_SIZE];
38 In a connection request, sent by a client to a server and regarding a
39 specific target, the 'pb_handle' is 0. In the reply to a connection
40 request, sent by the target, the handle is a value uniquely
41 identifying the target. Subsequent messages between this client and
42 this target will use this handle to to gain access to their shared
43 state. The handle is persistent across client reconnects to the same
44 instance of the server, but if the client unmounts the filesystem or
45 is evicted then it must re-connect as a new client.
47 The 'pb_type' is PTL_RPC_MSG_REQUEST in messages when they are
48 initiated, it is PTL_RPC_MSG_REPLY in a reply, and it is
49 PTL_RPC_MSG_ERR in a reply to convey that a message was received that
50 could not be interpreted, that is, if it was corrupt or
51 incomplete. The encoding of those type values is given by:
53 #define PTL_RPC_MSG_REQUEST 4711
54 #define PTL_RPC_MSG_ERR 4712
55 #define PTL_RPC_MSG_REPLY 4713
57 The 'pb_type' = PTL_RPC_MSG_ERR is only for message handling errors.
58 This may be a message that failed to be interpreted as an actual
59 message, or it may indicate some more general problem with the
60 connection between the client and the target. Note that other errors,
61 such as those that emerge from processing the actual message content,
62 do not use the PTL_RPC_MSG_ERR type.
64 The 'pb_status' field provides an error return code, if any, for the
65 RPC. When 'pb_type' = PTL_RPC_MSG_ERR the 'pb_status' will also be
66 set to one of the following message handling errors:
71 | pb_type | pb_status | if
72 | PTL_RPC_MSG_ERR | -ENOMEM | No memory for reply buffer
73 | PTL_RPC_MSG_ERR | -ENOTSUPP | Invalid opcode
74 | PTL_RPC_MSG_ERR | -EINVAL | Bad magic or version
75 | PTL_RPC_MSG_ERR | -EPROTO | Request is malformed or cannot be
76 processed in current context
79 A PTL_RPC_MSG_ERR message does not need to allocate memory, so it
80 should normally be sent as a reply even if there is not enough memory
81 to allocate the normal reply buffer, unless the underlying network
82 transport itself cannot allocate memory to send it. (fixme: and what
85 In most cases there is a reply with 'pb_type' = PTL_RPC_MSG_REPLY,
86 indicating that the request was processed, but it may still have
87 'pb_status' set to a non-zero value to indicate that the request
88 encountered an error during processing (see below). This may indicate
89 something very specific to the particular RPC, but it may also be a
90 very general sort of error. Those that are specific to particular RPCs
91 will be documented with the respective RPCs, and those that are more
92 generic are listed here:
97 | pb_type | pb_status | meaning
98 | PTL_RPC_MSG_REPLY | -ENOTCONN | Client is not connected to the
99 target, typically meaning the
100 server was restarted or the
101 client was evicted, and the
102 client needs to reconnect.
103 | PTL_RPC_MSG_REPLY | -EINPROGRESS | The request cannot be processed
104 currently due to some other
105 factor, such as during initial
106 mount, a delay contacting the
107 quota master during a write, or
108 LFSCK rebuilding the OI table,
109 but the client should continue
110 to retry after a delay until
111 interrupted or successful. This
112 avoids blocking the server
113 threads with client requests
114 that cannot currently be
115 processed, but other requests
116 might be processed in the
118 | PTL_RPC_MSG_REPLY | -ESHUTDOWN | The server is being stopped and
119 no new connections are allowed.
122 The significance of -ENOTCONN is discussed more fully in
123 <<connection>>, but a brief comment may be useful here. The networking
124 layers supporting the exchange of RPCs can be in good working order
125 when 'pb_status' = -ENOTCONN is returned in an RPC reply message. The
126 connection refered to by that status is the Lustre connection. That
127 connection is part of the shared state between Lustre clients and
128 servers that gets established via MDS_CONNECT and OST_CONNECT RPCs,
129 and can be lost due to an 'eviction'. So, even when that Lusre
130 connection is lost (or has not been established, yet), RPC messages
133 The 'pb_version' identifies the version of the Lustre protocol and is
134 derived from the following constants. The lower two bytes give the
135 version of PtlRPC being employed in the message, and the upper two
136 bytes encode the role of the host for the service being
137 requested. That role is one of OBD, MDS, OST, DLM, LOG, or MGS.
139 #define PTLRPC_MSG_VERSION 0x00000003
140 #define LUSTRE_VERSION_MASK 0xffff0000
141 #define LUSTRE_OBD_VERSION 0x00010000
142 #define LUSTRE_MDS_VERSION 0x00020000
143 #define LUSTRE_OST_VERSION 0x00030000
144 #define LUSTRE_DLM_VERSION 0x00040000
145 #define LUSTRE_LOG_VERSION 0x00050000
146 #define LUSTRE_MGS_VERSION 0x00060000
149 The 'pb_opc' value (operation code) gives the actual Lustre operation
150 that is the subject of this message. For example, MDS_CONNECT is a
151 Lustre operation (number 38). The following list gives the name used
152 and the value for each operation.
157 <<ost-setattr-rpc,OST_SETATTR>> = 2,
163 <<ost-connect-rpc,OST_CONNECT>> = 8,
164 <<ost-connect-rpc,OST_DISCONNECT>> = 9,
173 OST_QUOTA_ADJUST_QUNIT = 20,
175 <<mds-getattr-rpc,MDS_GETATTR>> = 33,
176 MDS_GETATTR_NAME = 34,
180 <<mds-connect-rpc,MDS_CONNECT>> = 38,
181 <<mds-disconnect,MDS_DISCONNECT>> = 39,
182 <<mds-getstatus-rpc,MDS_GETSTATUS>> = 40,
183 <mds-statfs-rpc,MDS_STATFS>> = 41,
187 MDS_DONE_WRITING = 45,
191 <<mds-getxattr-rpc,MDS_GETXATTR>> = 49,
196 MDS_HSM_STATE_GET = 54,
197 MDS_HSM_STATE_SET = 55,
199 MDS_HSM_PROGRESS = 57,
200 MDS_HSM_REQUEST = 58,
201 MDS_HSM_CT_REGISTER = 59,
202 MDS_HSM_CT_UNREGISTER = 60,
203 MDS_SWAP_LAYOUTS = 61,
205 <<ldlm-enqueue-rpc,LDLM_ENQUEUE>> = 101,
207 <ldlm-cancel-rpc,LDLM_CANCEL>> = 103,
208 <ldlm_bl_callback-rpc,LDLM_BL_CALLBACK>> = 104,
209 <ldlm-cp-callback-rpc,LDLM_CP_CALLBACK>> = 105,
210 LDLM_GL_CALLBACK = 106,
213 <<mgs-connect-rpc,MGS_CONNECT>> = 250,
214 <<mgs-disconnect-rpc,MGS_DISCONNECT>> = 251,
216 MGS_TARGET_REG = 253,
217 MGS_TARGET_DEL = 254,
219 <<mgs-config-read-rpc,MGS_CONFIG_READ>> = 256,
222 OBD_LOG_CANCEL = 401,
223 OBD_QC_CALLBACK = 402,
226 <<llog-origin-handle-create-rpc,LLOG_ORIGIN_HANDLE_CREATE>> = 501,
227 <<llog-origin-handle-next-block,LLOG_ORIGIN_HANDLE_NEXT_BLOCK>> = 502,
228 <<llog-origin-handle-read-header,LLOG_ORIGIN_HANDLE_READ_HEADER>> = 503,
229 LLOG_ORIGIN_HANDLE_WRITE_REC = 504,
230 LLOG_ORIGIN_HANDLE_CLOSE = 505,
231 LLOG_ORIGIN_CONNECT = 506,
232 LLOG_ORIGIN_HANDLE_PREV_BLOCK = 508,
233 LLOG_ORIGIN_HANDLE_DESTROY = 509,
241 SEC_CTX_INIT_CONT = 802,
250 The symbols and values above identify the operations Lustre uses in
251 its protocol. They are examined in detail in the
252 <<lustre-operations,Lustre Operations>> section. Lustre carries out
253 each of these operations via the exchange of a pair of messages: a
254 request and a reply. The details of each message are specific to each
255 operation. The <<lustre-messages,Lustre Messages>> chapter discusses
256 each message and its contents.
258 The 'pb_status' field was already mentioned above in conjuction with
259 the 'pb_type' field in replies. In a request message 'pb_status' is
260 set to the 'pid' of the process making the request. In a reply
261 message, a zero indicates that the service successfully initiated the
262 requested operation. When an error is being reported the value will
263 encode a standard Linux kernel (POSIX) error code as initially
264 defined for the i386/x86_64 architecture. The 'pb_status' value is
265 returned as a negative number, so for example, a permissions error
266 would be indicated as -EPERM.
268 'pb_last_xid' and 'pb_last_seen' are not used.
270 The 'pb_last_committed' value is always zero in a request. In a reply
271 it is the highest transaction number that has been committed to
272 storage. The transaction numbers are maintained on a per-target basis
273 and each series of transaction numbers is a strictly increasing
274 sequence for modifications originating from any client. This field is
275 set in any kind of reply message including pings and non-modifying
276 transactions. If 'pb_last_committed' is larger than, or equal to, any
277 of the client's uncommitted requests (see 'pb_transno' below) then the
278 server is confirming those requests have been committed to stable
279 storage. At that point the client will free the request structures.
281 The 'pb_transno' value is always zero in a new request. It is also
282 zero for replies to operations that do not modify the file system. For
283 replies to operations that do modify the file system it is the
284 target-unique, server-assigned transaction number for the client
285 request. The 'pb_transno' assigned to each modifying request is in
286 strictly increasing order, but may not be sequential for a single
287 client, and the client may receive replies in a different order than
288 they were processed by the server.Upon receipt of the reply, the
289 client copies this transaction number from 'pb_transno' of the reply
290 to 'pb_transno' of the saved request. If 'pb_transno' is larger than
291 'pb_last_commited' (above) then the request has only been processed at
292 the target and is not yet committed to stable storage. The client
293 must save the request for later resend to the server in case the
294 target fails before the modification can be committed to disk.If the
295 request has to be replayed it will include the transaction number.
297 The 'pb_flags' value governs the client state machine. Fixme: document
298 what the states and transitions are of this state machine. Currently,
299 only the bottom two bytes are used, and they encode state according to
300 the following values:
302 #define MSG_GEN_FLAG_MASK 0x0000ffff
303 #define MSG_LAST_REPLAY 0x0001
304 #define MSG_RESENT 0x0002
305 #define MSG_REPLAY 0x0004
306 #define MSG_DELAY_REPLAY 0x0010
307 #define MSG_VERSION_REPLAY 0x0020
308 #define MSG_REQ_REPLAY_DONE 0x0040
309 #define MSG_LOCK_REPLAY_DONE 0x0080
312 MGS_LAST_REPLAY is currently unused. It had been used to indicate that
313 this is the last RPC request to be replayed by this client during
314 recovery. MGS_LAST_REPLAY has been replaced by MSG_REQ_REPLAY_DONE
315 and MSG_LOCK_REPLAY_DONE.
317 MGS_RESENT is set when this RPC request is being resent because no
320 MGS_REPLAY indicates this RPC request is being replayed after the
321 client received a reply but before it was committed to storage. The
322 'pb_transno' field holds the server-assigned transaction number.
324 MGS_DELAY_REPLAY is currently unused.
326 MSG_VERSION_REPLAY indicates that a replayed request has
327 pb_pre_versions[] filled with the prior object versions and can be
328 used with Version Based Recovery.
330 MSG_LOCK_REPLAY_DONE indicates the client has completed lock replay,
331 and is ready to finish recovery.
333 The 'pb_op_flags' values are specific to a particular 'pb_opc', but
334 are currently only used by the *_CONNECT RPCs.The 'pb_op_flags' value
335 for connect operations governs the client connection status state
339 #define MSG_CONNECT_RECOVERING 0x00000001
340 #define MSG_CONNECT_RECONNECT 0x00000002
341 #define MSG_CONNECT_REPLAYABLE 0x00000004
342 #define MSG_CONNECT_LIBCLIENT 0x00000010
343 #define MSG_CONNECT_INITIAL 0x00000020
344 #define MSG_CONNECT_ASYNC 0x00000040
345 #define MSG_CONNECT_NEXT_VER 0x00000080
346 #define MSG_CONNECT_TRANSNO 0x00000100
349 MGS_CONNECT_RECOVERING indicate the server is in recovery
351 MGS_CONNECT_RECONNECT indicates the client is reconnecting after
352 non-responsiveness from the server.
354 MGS_CONNECT_REPLAYABLE indicates the server connection supports RPC
355 replay (only OSTs support non-recoverable connections, but that is not
358 The MGS_CONNECT_LIBCLIENT is for the a 'liblustre' client. It is
361 The client sends MGS_CONNECT_INITIAL the first time the client is
362 connecting to the server. MSG_CONNECT_INITIAL connections are not
363 allowed during server recovery.
365 MGS_CONNECT_ASYNC is currently unused.
367 MSG_CONNECT_NEXT_VER indicates that the client can understand the next
368 higher protocol version, and the server can reply to the connect with
369 that RPC version if it is supported, otherwise it will reply with the
370 same RPC version as the request. This allows RPC protocol versions to
371 be negotiated during a transition period (e.g. upgrade from RPC from
372 LUSTRE_MSG_MAGIC_V1 to LUSTRE_MSG_MAGIC_V2).
374 In normal operation an initial request to connect will set
375 'pb_op_flags' to MSG_CONNECT_INITIAL (in some earlier versions
376 MSG_CONNECT_NEXT_VER was mistakenly included, though it did no
377 harm). The reply to that connection request (and all other,
378 non-connect, requests and replies) will set 'pb_op_flags' to 0.
380 The 'pb_conn_cnt' (connection count) value in a request message
381 reports the client's "era", which is part of the client and server's
382 shared state. The value of the era is initialized to one when it is
383 first connected to the MDT. Each subsequent connection (after an
384 eviction) increments the era for the client. Since the 'pb_conn_cnt'
385 reflects the client's era at the time the message was composed the
386 server can use this value to discard late-arriving messages requesting
387 operations on out-of-date shared state.
389 The 'pb_timeout' value in a request indicates how long (in seconds)
390 the requester plans to wait before timing out the operation. That is,
391 the corresponding reply for this message should arrive within this
392 time frame. The service may extend this time frame via an "early
393 reply", which is a reply to this message that notifies the requester
394 that it should extend its timeout interval by the value of the
395 'pb_timeout' field in the reply. The "early reply" does not indicate
396 the operation has actually been initiated. Clients maintain multiple
397 request queues, called "portals", and each type of operation is
398 assigned to one of these queues. There is a timeout value associated
399 with each queue, and the timeout update affects all the messages
400 associated with the given queue, not just the specific message that
401 initiated the request. Finally, in a reply message (one that does
402 indicate the operation has been initiated) the timeout value updates
403 the timeout interval for the queue. Is this last point different from
404 the "early reply" update?
406 The 'pb_service_time' value is zero in a request. In a reply it
407 indicates how long this particular operation actually took from the
408 time it first arrived in the request queue (at the service) to the
409 time the server replied. Note that the client can use this value and
410 the local elapsed time for the operation to calculate network latency.
412 The 'pb_limit' value is zero in a request. In a reply it is a value
413 sent from a lock service to a client to set the maximum number of
414 locks available to the client. When dynamic lock LRU's are enabled
415 this allows for managing the size of the LRU.
417 The 'pb_slv' value is zero in a request. On a DLM service, the "server
418 lock volume" is a value that characterizes (estimates) the amount of
419 traffic, or load, on that lock service. It is calculated as the
420 product of the number of locks and their age. In a reply, the 'pb_slv'
421 value indicates to the client the available share of the total lock
422 load on the server that the client is allowed to consume. The client
423 is then responsible for reducing its number or (or age) of locks to
424 stay within this limit.
426 The array of 'pb_pre_versions' values has four entries. They are
427 always zero in a new request message. They are also zero in replies to
428 operations that do not modify the file system. For an operation that
429 does modify the file system, the reply encodes the most recent
430 transaction numbers for the objects modified by this operation, and
431 the 'pb_pre_versions' values are copied into the original request when
432 the reply arrives. If the request needs to be replayed then the
433 updated 'pb_pre_versions' values accompany the replayed request.
435 'pb_padding' is reserved for future use.
437 The 'pb_jobid' (string) value gives a unique identifier associated
438 with the process on behalf of which this message was generated. The
439 identifier is assigned to the user process by a job scheduler, if any.