lustre_messages.txt

   1 Lustre Messages
   2 ---------------
   3 [[lustre-messages]]
   4
   5 A Lustre message is a sequence of bytes. The message begins with a
   6 <<lustre-message-header,Lustre Message Header>> and has between one
   7 and nine subsequences called "buffers". Each buffer has a structure
   8 (the size and meaning of the bytes) that corresponds to the 'struct'
   9 entities in the <<data-structs,Data Structures and Defines Section>>
  10 Section. The header gives the number of buffers in its 'lm_buffcount'
  11 field. The first buffer in any message is always the
  12 <<lustre-message-preamble,Lustre Message Preamble>>. The operation
  13 code ('pb_opc' field) and the message type ('pb_type' field: request
  14 or reply?) in the preamble together specify the "format" of the
  15 message, where the format is the number and content of the remaining
  16 buffers. As a shorthand, it is useful to name each of these formats,
  17 and the following list gives all of the formats along with the number
  18 and content of the buffers for messages in that format. Note that
  19 while the combination of 'pb_opc' and 'pb_type' uniquely determines a
  20 message's format, the reverse is not true. A given format may be used
  21 in many different messages.
  22
  23 The "Empty" Message
  24 ~~~~~~~~~~~~~~~~~~~
  25
  26 'empty'
  27 ^^^^^^^
  28
  29 .example
  30 [options="header"]
  31 |====
  32 | pb_opc     | pb_type
  33 | MDS_STATFS | PTL_RPC_MSG_REQUEST
  34 |====
  35
  36
  37 An 'empty' message is one that consists only of the Lustre message
  38 preamble 'ptlrpc_body'. It occurs as either the request of the reply
  39 (or both) in a variety of Lustre operations.
  40
  41 .format
  42 [options="header"]
  43 |====
  44 | structure        | meaning
  45 | ptlrpc_body      | message preamble
  46 |====
  47
  48 The LDLM Enqueue Client Message
  49 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  50
  51 'ldlm_enqueue_client'
  52 ^^^^^^^^^^^^^^^^^^^^^
  53
  54 .example
  55 [options="header"]
  56 |====
  57 | pb_opc       | pb_type
  58 | LDLM_ENQUEUE | PTL_RPC_MSG_REQUEST
  59 |====
  60
  61
  62 An 'ldlm_enqueue_client' message format is used to acquire a lock.
  63
  64 .format
  65 [options="header"]
  66 |====
  67 | structure        | meaning
  68 | ptlrpc_body      | message preamble
  69 | ldlm_request     | details of the lock request
  70 |====
  71
  72 An 'ldlm_enqueue_client' message concatenates two data elements into a
  73 single byte-stream. The two elements correspond to structures
  74 detailed in the <<data-structs,Data Structures and Defines Section>>.
  75
  76 The LDLM Enqueue Server Message
  77 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  78
  79 'ldlm_enqueue_server'
  80 ^^^^^^^^^^^^^^^^^^^^^
  81
  82 .example
  83 [options="header"]
  84 |====
  85 | pb_opc       | pb_type
  86 | LDLM_ENQUEUE | PTL_RPC_MSG_REPLY
  87 |====
  88
  89
  90 An 'ldlm_enqueue_server' message format is used to inform a client
  91 about the status of its request for a lock.
  92
  93 .format
  94 [options="header"]
  95 |====
  96 | structure        | meaning
  97 | ptlrpc_body      | message preamble
  98 | ldlm_reply       | details of the lock request
  99 |====
 100
 101 An 'ldlm_enqueue_server' message concatenates two data elements
 102 into a single byte-stream. The three elements correspond to structures
 103 detailed in the <<data-structs,Data Structures and Defines Section>>.
 104
 105 The LDLM Enqueue Server Message with LVB
 106 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 107
 108 'ldlm_enqueue_lvb_server'
 109 ^^^^^^^^^^^^^^^^^^^^^^^^^
 110
 111 .example
 112 [options="header"]
 113 |====
 114 | pb_opc       | pb_type
 115 | LDLM_ENQUEUE | PTL_RPC_MSG_REPLY
 116 |====
 117
 118
 119 An 'ldlm_enqueue_lvb_server' message format is used to inform a client
 120 about the status of its request for a lock.
 121
 122 .format
 123 [options="header"]
 124 |====
 125 | structure        | meaning
 126 | ptlrpc_body      | message preamble
 127 | ldlm_reply       | details of the lock request
 128 | ost_lvb          | lock value block
 129 |====
 130
 131 An 'ldlm_enqueue_lvb_server' message concatenates three data elements
 132 into a single byte-stream. It closely resembles the
 133 'ldlm_enqueue_server' message with the addition of a lock value
 134 block. The three elements correspond to structures detailed in the
 135 <<data-structs,Data Structures and Defines Section>>.
 136
 137 The LLog Origin Handle Create Client
 138 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 139
 140 'llog_origin_handle_create_client'
 141 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 142
 143 .example
 144 [options="header"]
 145 |====
 146 | pb_opc                    | pb_type
 147 | LLOG_ORIGIN_HANDLE_CREATE | PTL_RPC_MSG_REQUEST
 148 |====
 149
 150
 151 An 'llog_origin_handle_create_client' message format is used to
 152 ask for the creation of a log entry object.
 153
 154 .format
 155 [options="header"]
 156 |====
 157 | structure    | meaning
 158 | ptlrpc_body  | message preamble
 159 | llogd_body   | LLog description
 160 | string       | The name of the desired log
 161 |====
 162
 163 Fixme: I don't actually see where the string gets set.
 164
 165 The LLog Service (body-only) Message
 166 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 167
 168 'llogd_body_only'
 169 ^^^^^^^^^^^^^^^^^
 170
 171 .example
 172 [options="header"]
 173 |====
 174 | pb_opc                    | pb_type
 175 | LLOG_ORIGIN_HANDLE_CREATE | PTL_RPC_MSG_REPLY
 176 |====
 177
 178
 179 An 'llogd_body_only' message replies with information about the log.
 180
 181 .format
 182 [options="header"]
 183 |====
 184 | structure    | meaning
 185 | ptlrpc_body  | message preamble
 186 | llogd_body   | LLog description
 187 |====
 188
 189
 190 The LLog Log (header-only) Message
 191 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 192
 193 'llog_log_hdr_only'
 194 ^^^^^^^^^^^^^^^^^^^
 195
 196 .example
 197 [options="header"]
 198 |====
 199 | pb_opc                         | pb_type
 200 | LLOG_ORIGIN_HANDLE_READ_HEADER | PTL_RPC_MSG_REPLY
 201 |====
 202
 203
 204 An 'llog_log_hdr_only' message replies with header information from
 205 the log.
 206
 207 .format
 208 [options="header"]
 209 |====
 210 | structure     | meaning
 211 | ptlrpc_body   | message preamble
 212 | llog_log_hdr  | LLog log header info
 213 |====
 214
 215
 216 The LLog Return Next Block from Server
 217 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 218
 219 'llog_origin_handle_next_block_server'
 220 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 221
 222 .example
 223 [options="header"]
 224 |====
 225 | pb_opc                        | pb_type
 226 | LLOG_ORIGIN_HANDLE_NEXT_BLOCK | PTL_RPC_MSG_REPLY
 227 |====
 228
 229
 230 An 'llog_origin_handle_next_block_server' message replies with the
 231 next block of data from the log.
 232
 233 .format
 234 [options="header"]
 235 |====
 236 | structure     | meaning
 237 | ptlrpc_body   | message preamble
 238 | llogd_body    | LLog description
 239 | eadata        | variable length field for extended attributes
 240 |====
 241
 242
 243 The MDS Getattr Server Message
 244 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 245
 246 'mds_getattr_server'
 247 ^^^^^^^^^^^^^^^^^^^^
 248
 249 .example
 250 [options="header"]
 251 |====
 252 | pb_opc      | pb_type
 253 | MDS_GETATTR | PTL_RPC_MSG_REPLY
 254 |====
 255
 256 An 'mds_getattr_server' message format is used to convey MDT data along
 257 with information about the Lustre capabilities of that MDT.
 258
 259 .format
 260 [options="header"]
 261 |====
 262 | structure        | meaning
 263 | ptlrpc_body      | message preamble
 264 | mdt_body         | Information about the MDT
 265 | MDT_MD           | OST stripe and index info
 266 | ACL              | ACLs for the fid
 267 | lustre_capa      | Security capa info for fid1
 268 | lustre_capa      | Security capa info for fid2
 269 |====
 270
 271 An 'mdt_getattr_server' message concatenates three data elements into
 272 a single byte-stream. The three elements correspond to structures
 273 detailed in the <<data-structs,Data Structures and Defines Section>>.
 274
 275 The MDT Capability Message
 276 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 277
 278 'mdt_body_capa'
 279 ^^^^^^^^^^^^^^^
 280
 281 .example
 282 [options="header"]
 283 |====
 284 | pb_opc        | pb_type
 285 | MDS_GETSTATUS | PTL_RPC_MSG_REPLY
 286 | MDS_GETATTR   | PTL_RPC_MSG_REQUEST
 287 |====
 288
 289 An 'mdt_body_capa' message format is used to convey MDT data along
 290 with information about the Lustre capabilities of that MDT.
 291
 292 .format
 293 [options="header"]
 294 |====
 295 | structure        | meaning
 296 | ptlrpc_body      | message preamble
 297 | mdt_body         | Information about the MDT
 298 | lustre_capa      | security capa info
 299 |====
 300
 301 An 'mdt_body_capa' message concatenates three data elements into
 302 a single byte-stream. The three elements correspond to structures
 303 detailed in the <<data-structs,Data Structures and Defines Section>>.
 304
 305 The MDT "Body Only" Message
 306 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 307
 308 'mdt_body_only'
 309 ^^^^^^^^^^^^^^^
 310
 311 .example
 312 [options="header"]
 313 |====
 314 | pb_opc        | pb_type
 315 | MDS_GETSTATUS | PTL_RPC_MSG_REQUEST
 316 |====
 317
 318
 319 An 'mdt_body_only' message format is used to convey MDT data.
 320
 321 .format
 322 [options="header"]
 323 |====
 324 | structure        | meaning
 325 | ptlrpc_body      | message preamble
 326 | mdt_body         | Information about the MDT
 327 |====
 328
 329 An 'mdt_body_only' message concatenates two data elements into
 330 a single byte-stream. The two elements correspond to structures
 331 detailed in the <<data-structs,Data Structures and Defines Section>>.
 332
 333 The MGS Config Read Client Message
 334 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 335
 336 'mgs_config_read_client'
 337 ^^^^^^^^^^^^^^^^^^^^^^^^
 338
 339 .example
 340 [options="header"]
 341 |====
 342 | pb_opc          | pb_type
 343 | MGS_CONFIG_READ | PTL_RPC_MSG_REQUEST
 344 |====
 345
 346 An 'mgs_config_read_client' message requests configuration data from
 347 the MGS.
 348
 349 .format
 350 [options="header"]
 351 |====
 352 | structure        | meaning
 353 | ptlrpc_body      | message preamble
 354 | mgs_config_body  | Information about the MGS supporting the request
 355 |====
 356
 357
 358 The MGS Config Read Server Message
 359 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 360
 361 'mgs_config_read_server'
 362 ^^^^^^^^^^^^^^^^^^^^^^^^
 363
 364 .example
 365 [options="header"]
 366 |====
 367 | pb_opc          | pb_type
 368 | MGS_CONFIG_READ | PTL_RPC_MSG_REPLY
 369 |====
 370
 371 An 'mgs_config_read_server' message returns configuration data from
 372 the MGS.
 373
 374 .format
 375 [options="header"]
 376 |====
 377 | structure        | meaning
 378 | ptlrpc_body      | message preamble
 379 | mgs_config_body  | Information about the MGS supporting the request
 380 |====
 381
 382
 383 The OBD Connect Client Message
 384 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 385
 386 'obd_connect_client'
 387 ^^^^^^^^^^^^^^^^^^^^
 388
 389 .example
 390 [options="header"]
 391 |====
 392 | pb_opc      | pb_type
 393 | MDS_CONNECT | PTL_RPC_MSG_REQUEST
 394 |====
 395
 396
 397 An 'obd_connect_client' message format is used to initiate the
 398 connection from one host to a target on another host. Clients will
 399 connect to the MGS, to MDTS on MDSs, and to OSTs on OSSs. Furthermore,
 400 MDSs and OSSs will connect to the MGS, and MDSs will connect to OSTs
 401 on OSSs. In each case the host initiating the the connection request
 402 sends an 'obd_connect_client' message. The reply to this message is
 403 the obd_connect_server message.
 404
 405 .format
 406 [options="header"]
 407 |====
 408 | structure        | meaning
 409 | ptlrpc_body      | message preamble
 410 | obd_uuid         | UUID of the target
 411 | obd_uuid         | UUID of the client
 412 | lustre_handle    | connection handle
 413 | obd_connect_data | connection data
 414 |====
 415
 416 An 'obd_connect_client' message concatenates five data elements into
 417 a single byte-stream. The five elements correspond to structures
 418 detailed in the <<data-structs,Data Structures and Defines Section>>.
 419
 420 The connection handle sent in a client connection request message is
 421 unique to that connection. The server notes it and a connection
 422 request with a new or different handle indicates that the client is
 423 attempting to make a new connection (or a delayed message about an
 424 old one?).
 425
 426 The OBD Connect Server Message
 427 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 428
 429 ' obd_connect_server'
 430 ^^^^^^^^^^^^^^^^^^^^^
 431
 432 .example
 433 [options="header"]
 434 |====
 435 | pb_opc      | pb_type
 436 | MDS_CONNECT | PTL_RPC_MSG_REPLY
 437 |====
 438
 439 The 'obd_connect_server' mess-sage format is sent by a server in reply
 440 to an 'obd_connect_client' connection request message. to a target on
 441 that server. MGSs, MDSs, and OSSs send these replies.
 442
 443 .format
 444 [options="header"]
 445 |====
 446 | structure        | meaning
 447 | ptlrpc_body      | message preamble
 448 | obd_connect_data | connection data
 449 |====
 450
 451 An 'obd_connect_server' message concatenates two data elements into a
 452 single byte-stream.
 453
 454 The OBD Statfs Server Message
 455 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 456
 457 'obd_statfs_server'
 458 ^^^^^^^^^^^^^^^^^^^
 459
 460 .example
 461 [options="header"]
 462 |====
 463 | pb_opc     | pb_type
 464 | MDS_STATFS | PTL_RPC_MSG_REPLY
 465 |====
 466
 467 The 'obd_statfs_server' message returns 'statfs' system call
 468 information to the client.
 469
 470 .format
 471 [options="header"]
 472 |====
 473 | structure        | meaning
 474 | ptlrpc_body      | message preamble
 475 | obd_statfs       | statfs system call info
 476 |====
 477