struct_lustre_msg.txt

   1 Lustre Message Header
   2 ~~~~~~~~~~~~~~~~~~~~~
   3 [[struct-lustre-msg]]
   4
   5 Every message has an initial header that informs the receiver about
   6 the number of buffers and their size for the rest of the message to
   7 follow, along with other important information about the request or
   8 reply message.
   9
  10 [source,c]
  11 ----
  12 #define LUSTRE_MSG_MAGIC_V2 0x0BD00BD3
  13 #define MSGHDR_AT_SUPPORT               0x1
  14 struct lustre_msg {
  15         __u32 lm_bufcount;
  16         __u32 lm_secflvr;
  17         __u32 lm_magic;
  18         __u32 lm_repsize;
  19         __u32 lm_cksum;
  20         __u32 lm_flags;
  21         __u32 lm_padding_2;
  22         __u32 lm_padding_3;
  23         __u32 lm_buflens[0];
  24 };
  25 ----
  26
  27 The 'lm_bufcount' field holds the number of buffers that will follow
  28 the header. The header and sequence of buffers constitutes one
  29 message. Each of the buffers is a sequence of bytes whose contents
  30 corresponds to one of the structures described in this section. Each
  31 message will always have at least one buffer, and no message can have
  32 more than thirty-one buffers.
  33
  34 The 'lm_secflvr' field gives an indication of whether any sort of
  35 cyptographic encoding of the subsequent buffers will be in force. The
  36 value is zero if there is no "crypto" and gives a code identifying the
  37 "flavor" of crypto if it is employed. Further, if crypto is employed
  38 there will only be one buffer following (i.e. 'lm_bufcount' = 1), and
  39 that buffer holds an encoding of what would otherwise have been the
  40 sequence of buffers normally following the header.  Cryptography will
  41 be discussed in a separate chapter.
  42
  43 The 'lm_magic' field is a "magic" value (LUSTRE_MSG_MAGIC_V2 = 0x0BD00BD3,
  44 'OBD' for 'object based device') that is
  45 checked in order to positively identify that the message is intended
  46 for the use to which it is being put. That is, we are indeed dealing
  47 with a Lustre message, and not, for example, corrupted memory or a bad
  48 pointer.
  49
  50 The 'lm_repsize' field in a request indicates the maximum available
  51 space that has been reserved for any reply to the request. A reply
  52 that attempts to use more than the reserved space will be discarded.
  53
  54 The 'lm_cksum' field contains a checksum of the 'ptlrpc_body' buffer
  55 to allow the receiver to verify that the message is intact.  This is
  56 used to verify that an 'early reply' has not been overwritten by the
  57 actual reply message.  If the 'MSGHDR_CKSUM_INCOMPAT18' flag is set
  58 in requests since Lustre 1.8
  59 (the server will send early reply messages with the appropriate 'lm_cksum'
  60 if it understands the flag
  61 and is mandatory in Lustre 2.8 and later.
  62
  63 The 'lm_flags' field contains flags that affect the low-level RPC
  64 protocol.  The 'MSGHDR_AT_SUPPORT' (0x1) bit indicates that the sender
  65 understands adaptive timeouts and can receive 'early reply' messages
  66 to extend its waiting period rather than timing out.  This flag was
  67 introduced in Lustre 1.6.  The 'MSGHDR_CKSUM_INCOMPAT18' (0x2) bit
  68 indicates that 'lm_cksum' is computed on the full 'ptlrpc_body'
  69 message buffer rather than on the original 'ptlrpc_body_v2' structure
  70 size (88 bytes).  It was introduced in Lustre 1.8 and is mandatory
  71 for all requests in Lustre 2.8 and later.
  72
  73 The 'lm_padding*' fields are reserved for future use.
  74
  75 The array of 'lm_buflens' values has 'lm_bufcount' entries. Each
  76 entry corresponds to, and gives the length in bytes of, one of the
  77 buffers that will follow.  The entire header, and each of the buffers,
  78 is required to be a multiple of eight bytes long to ensure the buffers
  79 are properly aligned to hold __u64 values. Thus there may be an extra
  80 four bytes of padding after the 'lm_buflens' array if that array has
  81 an odd number of entries.
  82