basement/request_message_pairs.txt

   1 Named Request Message Pairs
   2 ===========================
   3
   4 Each request message pair is identified in the source code by a symbol
   5 that starts iwth "RQF_". Each has a name and two message formats. The
   6 request message pair's name is a string. The two message formats in a
   7 message pair are the symbols given for a request message, on the one
   8 hand, and a reply message, on the other.
   9
  10 Names
  11 =====
  12
  13 The name appears as a string in the first position (argument) of a
  14 "struct req_format" declaration. The symbol for the message pair is
  15 usually the same as the name string but with "RQF_" in front of
  16 it. Thus the message pair named "MDS_CONNECT" appears in the code as
  17 the symbol "RQF_MDS_CONNECT". The name itself is only used for
  18 reporting purposes, for example in the traces decoded and reported
  19 through the Lustre wireshark extension. There are a few occasions
  20 (likely bugs) where the name and the symbol do not actually match in
  21 the way described above. Those instances are:
  22
  23 - Both RQF_LDLM_GL_DESC_CALLBACK and RQF_LDLM_GL_CALLBACK use the name
  24   LDLM_GL_CALLBACK
  25 - RQF_LOG_CANCEL is named OBD_LOG_CANCEL
  26 - RQF_MDS_REINT_CREATE_SLAVE is named MDS_REINT_CREATE_EA
  27 - Both RQF_MDS_CLOSE and RQF_MDS_RELEASE_CLOSE are named MDS_CLOSE
  28 - Both RQF_OUT_UPDATE and RQF_OUT_UPDATE_OBJ are named OUT_UPDATE
  29
  30 The RQF_* symbols are gathered in the:
  31
  32   static struct req_format *req_formats[]  =
  33
  34 array in layout.c. Their declarations, with the pair's name and the
  35 names of the two actual message formats, follow soon after in the same
  36 file.
  37
  38 Messages
  39 ========
  40
  41 The pair of symbols in a request message pair identify the format for
  42 each corresponding PtlRPC message, with the first of the pair being a
  43 request for action of some sort and the second being the reply
  44 appropriate to the request. See message_formats.txt for details about
  45 the structure of each message format. In many cases the host making
  46 the request will be a Lustre client, but that is not universally the
  47 case. For example, a lock callback might be initiated by the MDS and
  48 the request sent from the MDS to a Lustre client. In other cases the
  49 message request is between two Lustre servers. The message pairs
  50 always list the (symbol for the) request first and then the
  51 reply. Many of those pairs employ the words "client" and "server" in
  52 the symbol's name. This is unfortunate. Such "client" messages are not
  53 necessarily sent from Lustre clients and such "server" messages are
  54 not necessarily replies sent from Lustre servers. A symbol with the
  55 word "client" should always be thought of simply as the format of a
  56 message initiating a request. Likewise, "server" symbols simply mean
  57 the format for a message in reply to a request, whatever the actual
  58 host that sends the reply.  So the message pair should be understood
  59 as a message initiating a request and the message that is anticipated
  60 in reply to that request.
  61
  62 Op Codes
  63 ========
  64
  65 The name in the RQF_BLA definition will sometimes, but not always,
  66 correspond to the source code symbolic representation (in
  67 lustre/include/lustre/lustre_idl.h) of an "op code" as encoded in the
  68 "__u32 pb_opc" field of the "struct ptlrpc_body_v3". The op code
  69 symbols are defined in a collection of *_cmd_t enumerations in
  70 lustre_idl.h.
  71
  72 Historically, PtlRPC message consturuction was somewhat ad hoc, and
  73 carried out at the point where the message was needed. A newer and
  74 more systematic construction mechanism resulted in the list of "struct
  75 req_format RQF_*" message pair declarations. There are still some 21 or
  76 so op codes defined in lustre_idl.h that have no corresponding "struct
  77 req_format RQF_BLA" in layouts.c. One example is the "MGS_CONNECT" op
  78 code. A code audit will be necessary to see if any of those are
  79 obsolete (and/or unused) op codes or if they should be updated to the
  80 new form. There are also about 50 "struct req_format RQF_BLA" message
  81 pairs defined in layout.c for which there is no corresponding "BLA" op
  82 code. A code audit will be needed to determine if any or all of them
  83 should be introduced to lustre_idl.h as new op codes or if they (some
  84 of them) are obsolete or unused. In some cases (eg. RQF_MDS_REINT_*)
  85 one op code (eb. MDS_OPEN) is overloaded for all the message pairs of
  86 that type.
  87
  88 The following are the 94 named message pairs from layout.c. Each one
  89 defines a pair of message formats, which are identified by name. The
  90 message formats are reused and there are 95 such message formats for
  91 the 94 named message pairs. The message formats themselves are
  92 detailed in message_formats.txt. As mentioned above, the first of the
  93 pair should be thought of as the actual "request message" being made,
  94 and the second of the pair is the "reply message".
  95
  96 struct req_format                  name                            op code
  97 -----------------                  -----------------               -----------------
  98 RQF_CONNECT                        CONNECT
  99         obd_connect_client
 100         obd_connect_server
 101
 102 RQF_FLD_QUERY                      FLD_QUERY
 103         fld_query_client
 104         fld_query_server
 105
 106 RQF_FLD_READ                       FLD_READ
 107         fld_read_client
 108         fld_read_server
 109
 110 RQF_LDLM_BL_CALLBACK               LDLM_BL_CALLBACK                LDLM_BL_CALLBACK
 111         ldlm_enqueue_client
 112         empty
 113
 114 RQF_LDLM_CALLBACK                  LDLM_CALLBACK
 115         ldlm_enqueue_client
 116         empty
 117
 118 RQF_LDLM_CANCEL                    LDLM_CANCEL                     LDLM_CANCEL
 119         ldlm_enqueue_client
 120         empty
 121
 122 RQF_LDLM_CONVERT                   LDLM_CONVERT                    LDLM_CONVERT
 123         ldlm_enqueue_client
 124         ldlm_enqueue_server
 125
 126 RQF_LDLM_CP_CALLBACK               LDLM_CP_CALLBACK                LDLM_CP_CALLBACK
 127         ldlm_cp_callback_client
 128         empty
 129
 130 RQF_LDLM_ENQUEUE                   LDLM_ENQUEUE                    LDLM_ENQUEUE
 131         ldlm_enqueue_client
 132         ldlm_enqueue_lvb_server
 133
 134 RQF_LDLM_ENQUEUE_LVB               LDLM_ENQUEUE_LVB
 135         ldlm_enqueue_client
 136         ldlm_enqueue_lvb_server
 137
 138 RQF_LDLM_GL_CALLBACK               LDLM_GL_CALLBACK                LDLM_GL_CALLBACK
 139         ldlm_enqueue_client
 140         ldlm_gl_callback_server
 141
 142 RQF_LDLM_GL_DESC_CALLBACK          LDLM_GL_CALLBACK
 143         ldlm_gl_callback_desc_client
 144         ldlm_gl_callback_server
 145
 146 RQF_LDLM_INTENT                    LDLM_INTENT
 147         ldlm_intent_client
 148         ldlm_intent_server
 149
 150 RQF_LDLM_INTENT_BASIC              LDLM_INTENT_BASIC
 151         ldlm_intent_basic_client
 152         ldlm_enqueue_lvb_server
 153
 154 RQF_LDLM_INTENT_CREATE             LDLM_INTENT_CREATE
 155         ldlm_intent_create_client
 156         ldlm_intent_getattr_server
 157
 158 RQF_LDLM_INTENT_GETATTR            LDLM_INTENT_GETATTR
 159         ldlm_intent_getattr_client
 160         ldlm_intent_getattr_server
 161
 162 RQF_LDLM_INTENT_GETXATTR           LDLM_INTENT_GETXATTR
 163         ldlm_intent_getxattr_client
 164         ldlm_intent_getxattr_server
 165
 166 RQF_LDLM_INTENT_LAYOUT             LDLM_INTENT_LAYOUT
 167         ldlm_intent_layout_client
 168         ldlm_enqueue_lvb_server
 169
 170 RQF_LDLM_INTENT_OPEN               LDLM_INTENT_OPEN
 171         ldlm_intent_open_client
 172         ldlm_intent_open_server
 173
 174 RQF_LDLM_INTENT_QUOTA              LDLM_INTENT_QUOTA
 175         ldlm_intent_quota_client
 176         ldlm_intent_quota_server
 177
 178 RQF_LDLM_INTENT_UNLINK             LDLM_INTENT_UNLINK
 179         ldlm_intent_unlink_client
 180         ldlm_intent_server
 181
 182 RQF_LFSCK_NOTIFY                   LFSCK_NOTIFY                    LFSCK_NOTIFY
 183         obd_lfsck_request
 184         empty
 185
 186 RQF_LFSCK_QUERY                    LFSCK_QUERY                     LFSCK_QUERY
 187         obd_lfsck_request
 188         obd_lfsck_reply
 189
 190 RQF_LLOG_ORIGIN_CONNECT            LLOG_ORIGIN_CONNECT
 191         llogd_conn_body_only
 192         empty
 193
 194 RQF_LLOG_ORIGIN_HANDLE_CREATE      LLOG_ORIGIN_HANDLE_CREATE
 195         llog_origin_handle_create_client
 196         llogd_body_only
 197
 198 RQF_LLOG_ORIGIN_HANDLE_DESTROY     LLOG_ORIGIN_HANDLE_DESTROY
 199         llogd_body_only
 200         llogd_body_only
 201
 202 RQF_LLOG_ORIGIN_HANDLE_NEXT_BLOCK  LLOG_ORIGIN_HANDLE_NEXT_BLOCK
 203         llogd_body_only
 204         llog_origin_handle_next_block_server
 205
 206 RQF_LLOG_ORIGIN_HANDLE_PREV_BLOCK       LLOG_ORIGIN_HANDLE_PREV_BLOCK
 207         llogd_body_only
 208         llog_origin_handle_next_block_server
 209
 210 RQF_LLOG_ORIGIN_HANDLE_READ_HEADER      LLOG_ORIGIN_HANDLE_READ_HEADER
 211         llogd_body_only
 212         llog_log_hdr_only
 213
 214 RQF_LOG_CANCEL                     OBD_LOG_CANCEL                  OBD_LOG_CANCEL
 215         log_cancel_client
 216         empty
 217
 218 RQF_MDS_CLOSE                      MDS_CLOSE                       MDS_CLOSE
 219         mdt_close_client
 220         mds_last_unlink_server
 221
 222 RQF_MDS_CONNECT                    MDS_CONNECT                     MDS_CONNECT
 223         obd_connect_client
 224         obd_connect_server
 225
 226 RQF_MDS_DISCONNECT                 MDS_DISCONNECT                  MDS_DISCONNECT
 227         empty
 228         empty
 229
 230 RQF_MDS_DONE_WRITING               MDS_DONE_WRITING                MDS_DONE_WRITING
 231         mdt_close_client
 232         mdt_body_only
 233
 234 RQF_MDS_GETATTR                    MDS_GETATTR                     MDS_GETATTR
 235         mdt_body_capa
 236         mds_getattr_server
 237
 238 RQF_MDS_GETATTR_NAME               MDS_GETATTR_NAME                MDS_GETATTR_NAME
 239         mds_getattr_name_client
 240         mds_getattr_server
 241
 242 RQF_MDS_GETSTATUS                  MDS_GETSTATUS                   MDS_GETSTATUS
 243         mdt_body_only
 244         mdt_body_capa
 245
 246 RQF_MDS_GETXATTR                   MDS_GETXATTR                    MDS_GETXATTR
 247         mds_getxattr_client
 248         mds_getxattr_server
 249
 250 RQF_MDS_GET_INFO                   MDS_GET_INFO                    MDS_GET_INFO
 251         mds_getinfo_client
 252         mds_getinfo_server
 253
 254 RQF_MDS_HSM_ACTION                 MDS_HSM_ACTION                  MDS_HSM_ACTION
 255         mdt_body_capa
 256         mdt_hsm_action_server
 257
 258 RQF_MDS_HSM_CT_REGISTER            MDS_HSM_CT_REGISTER             MDS_HSM_CT_REGISTER
 259         mdt_hsm_ct_register
 260         empty
 261
 262 RQF_MDS_HSM_CT_UNREGISTER          MDS_HSM_CT_UNREGISTER           MDS_HSM_CT_UNREGISTER
 263         mdt_hsm_ct_unregister
 264         empty
 265
 266 RQF_MDS_HSM_PROGRESS               MDS_HSM_PROGRESS                MDS_HSM_PROGRESS
 267         mdt_hsm_progress
 268         empty
 269
 270 RQF_MDS_HSM_REQUEST                MDS_HSM_REQUEST                 MDS_HSM_REQUEST
 271         mdt_hsm_request
 272         empty
 273
 274 RQF_MDS_HSM_STATE_GET              MDS_HSM_STATE_GET               MDS_HSM_STATE_GET
 275         mdt_body_capa
 276         mdt_hsm_state_get_server
 277
 278 RQF_MDS_HSM_STATE_SET              MDS_HSM_STATE_SET               MDS_HSM_STATE_SET
 279         mdt_hsm_state_set
 280         empty
 281
 282 RQF_MDS_QUOTACHECK                 MDS_QUOTACHECK                  MDS_QUOTACHECK
 283         quotactl_only
 284         empty
 285
 286 RQF_MDS_QUOTACTL                   MDS_QUOTACTL                    MDS_QUOTACTL
 287         quotactl_only
 288         quotactl_only
 289
 290 RQF_MDS_READPAGE                   MDS_READPAGE                    MDS_READPAGE
 291         mdt_body_capa
 292         mdt_body_only
 293
 294 RQF_MDS_REINT                      MDS_REINT                       MDS_REINT
 295         mds_reint_client
 296         mdt_body_only
 297
 298 RQF_MDS_REINT_CREATE               MDS_REINT_CREATE                MDS_OPEN
 299         mds_reint_create_client
 300         mdt_body_capa
 301
 302 RQF_MDS_REINT_CREATE_RMT_ACL       MDS_REINT_CREATE_RMT_ACL        MDS_OPEN
 303         mds_reint_create_rmt_acl_client
 304         mdt_body_capa
 305
 306 RQF_MDS_REINT_CREATE_SLAVE         MDS_REINT_CREATE_EA             MDS_OPEN
 307         mds_reint_create_slave_client
 308         mdt_body_capa
 309
 310 RQF_MDS_REINT_CREATE_SYM           MDS_REINT_CREATE_SYM            MDS_OPEN
 311         mds_reint_create_sym_client
 312         mdt_body_capa
 313
 314 RQF_MDS_REINT_LINK                 MDS_REINT_LINK                  MDS_OPEN
 315         mds_reint_link_client
 316         mdt_body_only
 317
 318 RQF_MDS_REINT_OPEN                 MDS_REINT_OPEN                  MDS_OPEN
 319         mds_reint_open_client
 320         mds_reint_open_server
 321
 322 RQF_MDS_REINT_RENAME               MDS_REINT_RENAME                MDS_OPEN
 323         mds_reint_rename_client
 324         mds_last_unlink_server
 325
 326 RQF_MDS_REINT_SETATTR              MDS_REINT_SETATTR               MDS_OPEN
 327         mds_reint_setattr_client
 328         mds_setattr_server
 329
 330 RQF_MDS_REINT_SETXATTR             MDS_REINT_SETXATTR              MDS_OPEN
 331         mds_reint_setxattr_client
 332         mdt_body_only
 333
 334 RQF_MDS_REINT_UNLINK               MDS_REINT_UNLINK                MDS_OPEN
 335         mds_reint_unlink_client
 336         mds_last_unlink_server
 337
 338 RQF_MDS_RELEASE_CLOSE              MDS_CLOSE
 339         mdt_release_close_client
 340         mds_last_unlink_server
 341
 342 RQF_MDS_STATFS                     MDS_STATFS                      MDS_STATFS
 343         empty
 344         obd_statfs_server
 345
 346 RQF_MDS_SWAP_LAYOUTS               MDS_SWAP_LAYOUTS                MDS_SWAP_LAYOUTS
 347         mdt_swap_layouts
 348         empty
 349
 350 RQF_MDS_SYNC                       MDS_SYNC                        MDS_SYNC
 351         mdt_body_capa
 352         mdt_body_only
 353
 354 RQF_MGS_CONFIG_READ                MGS_CONFIG_READ                 MGS_CONFIG_READ
 355         mgs_config_read_client
 356         mgs_config_read_server
 357
 358 RQF_MGS_SET_INFO                   MGS_SET_INFO                    MGS_SET_INFO
 359         mgs_set_info
 360         mgs_set_info
 361
 362 RQF_MGS_TARGET_REG                 MGS_TARGET_REG                  MGS_TARGET_REG
 363         mgs_target_info_only
 364         mgs_target_info_only
 365
 366 RQF_OBD_IDX_READ                   OBD_IDX_READ                    OBD_IDX_READ
 367         obd_idx_read_client
 368         obd_idx_read_server
 369
 370 RQF_OBD_PING                       OBD_PING                        OBD_PING
 371         empty
 372         empty
 373
 374 RQF_OBD_SET_INFO                   OBD_SET_INFO
 375         obd_set_info_client
 376         empty
 377
 378 RQF_OST_BRW_READ                   OST_BRW_READ
 379         ost_brw_client
 380         ost_brw_read_server
 381
 382 RQF_OST_BRW_WRITE                  OST_BRW_WRITE
 383         ost_brw_client
 384         ost_brw_write_server
 385
 386 RQF_OST_CONNECT                    OST_CONNECT                     OST_CONNECT
 387         obd_connect_client
 388         obd_connect_server
 389
 390 RQF_OST_CREATE                     OST_CREATE                      OST_CREATE
 391         ost_body_only
 392         ost_body_only
 393
 394 RQF_OST_DESTROY                    OST_DESTROY                     OST_DESTROY
 395         ost_destroy_client
 396         ost_body_only
 397
 398 RQF_OST_DISCONNECT                 OST_DISCONNECT                  OST_DISCONNECT
 399         empty
 400         empty
 401
 402 RQF_OST_GETATTR                    OST_GETATTR                     OST_GETATTR
 403         ost_body_capa
 404         ost_body_only
 405
 406 RQF_OST_GET_INFO                   OST_GET_INFO                    OST_GET_INFO
 407         ost_get_info_generic_client
 408         ost_get_info_generic_server
 409
 410 RQF_OST_GET_INFO_FIEMAP            OST_GET_INFO_FIEMAP
 411         ost_get_fiemap_client
 412         ost_get_fiemap_server
 413
 414 RQF_OST_GET_INFO_LAST_FID          OST_GET_INFO_LAST_FID
 415         ost_get_last_fid_client
 416         ost_get_last_fid_server
 417
 418 RQF_OST_GET_INFO_LAST_ID           OST_GET_INFO_LAST_ID
 419         ost_get_info_generic_client
 420         ost_get_last_id_server
 421
 422 RQF_OST_PUNCH                      OST_PUNCH                       OST_PUNCH
 423         ost_body_capa
 424         ost_body_only
 425
 426 RQF_OST_QUOTACHECK                 OST_QUOTACHECK                  OST_QUOTACHECK
 427         quotactl_only
 428         empty
 429
 430 RQF_OST_QUOTACTL                   OST_QUOTACTL                    OST_QUOTACTL
 431         quotactl_only
 432         quotactl_only
 433
 434 RQF_OST_SETATTR                    OST_SETATTR                     OST_SETATTR
 435         ost_body_capa
 436         ost_body_only
 437
 438 RQF_OST_SET_GRANT_INFO             OST_SET_GRANT_INFO
 439         ost_grant_shrink_client
 440         ost_body_only
 441
 442 RQF_OST_SET_INFO_LAST_FID          OST_SET_INFO_LAST_FID
 443         obd_set_info_client
 444         empty
 445
 446 RQF_OST_STATFS                     OST_STATFS                      OST_STATFS
 447         empty
 448         obd_statfs_server
 449
 450 RQF_OST_SYNC                       OST_SYNC                        OST_SYNC
 451         ost_body_capa
 452         ost_body_only
 453
 454 RQF_OUT_UPDATE                     OUT_UPDATE_OBJ                  OUT_UPDATE
 455         mds_update_client
 456         mds_update_server
 457
 458 RQF_QC_CALLBACK                    QC_CALLBACK
 459         quotactl_only
 460         empty
 461
 462 RQF_QUOTA_DQACQ                    QUOTA_DQACQ
 463         quota_body_only
 464         quota_body_only
 465
 466 RQF_SEC_CTX                        SEC_CTX
 467         empty
 468         empty
 469
 470 RQF_SEQ_QUERY                      SEQ_QUERY
 471         seq_query_client
 472         seq_query_server
 473
 474 Extra Op Codes
 475 ==============
 476
 477 These op codes apear in some *_cmd_t enumeration in lustre_idl.h, but
 478 do not correspond to any RQF_* request format declaration in layout.c:
 479
 480 LDLM_SET_INFO
 481 MDS_IS_SUBDIR
 482 MDS_PIN
 483 MDS_SETXATTR
 484 MDS_SET_INFO
 485 MDS_UNPIN
 486 MDS_WRITEPAGE
 487 MGS_CONNECT
 488 MGS_DISCONNECT
 489 MGS_EXCEPTION
 490 MGS_TARGET_DEL
 491 OBD_LOG_CANCEL
 492 OST_CLOSE
 493 OST_OPEN
 494 OST_QUOTA_ADJUST_QUNIT
 495 OST_READ
 496 OST_REPLY
 497 OST_SET_INFO
 498 OST_WRITE
 499 QUOTA_DQREL
 500 SEC_CTX_FINI
 501 SEC_CTX_INIT
 502 SEC_CTX_INIT_CONT
 503
 504 A code audit will be needed to determine if they are unused or, like
 505 MGS_CONNECT, are introduced in an ad hoc fashion at the point the
 506 message is needed. If possible, the still in use op codes should be
 507 folded into the new "struct req_format" style of declaration, and
 508 their creation and management made uniform with the rest. In cases
 509 where this is impossible, the reason and the handling should both be
 510 explained clearly.
 511