struct_lustre_msg.txt

Lustre Message Header
~~~~~~~~~~~~~~~~~~~~~
[[struct-lustre-msg]]

Every RPC has a header that informs the receiver about the number and
sizes of the buffers to follow. It also holds a few generic pieces of
information about the message.

[source,c]
----
#define LUSTRE_MSG_MAGIC_V2 0x0BD00BD3
#define MSGHDR_AT_SUPPORT               0x1
struct lustre_msg {
        __u32 lm_bufcount;
        __u32 lm_secflvr;
        __u32 lm_magic;
        __u32 lm_repsize;
        __u32 lm_cksum;
        __u32 lm_flags;
        __u32 lm_padding_2;
        __u32 lm_padding_3;
        __u32 lm_buflens[0];
};
----

The 'lm_bufcount' field holds the number of buffers that will follow
the header. The header and sequence of buffers constitutes one
message. Each message will always have at least one buffer, and no
message can have more than thirty-one buffers.

The 'lm_secflvr' field gives an indication of whether any sort of
cyptographic encoding of the subsequent buffers will be in force. The
value is zero if there is no "crypto". Otherwise, the value gives a
code identifying the "flavor" of crypto. Further, if crypto is
employed there will only be one buffer following (i.e. 'lm_bufcount' =
1), and that buffer holds an encoding of what would otherwise have
been the sequence of buffers normally following the header.
Cryptography will be discussed in a separate chapter. See
<<security>>.

The 'lm_magic' field is a "magic" value (LUSTRE_MSG_MAGIC_V2 =
0x0BD00BD3, 'OBD' for 'object based device') that is checked in order
to positively identify that the message is intended for the use to
which it is being put. That is, we are indeed dealing with a Lustre
message, and not, for example, corrupted memory or a bad pointer.

The 'lm_repsize' field in a request indicates the maximum available
space that has been reserved for any reply to the request. A reply
that attempts to use more than the reserved space will be discarded.

The 'lm_cksum' field contains a checksum of the 'ptlrpc_body' buffer
to allow the receiver to verify that the message is intact.  This is
used to verify that an 'early reply' has not been overwritten by the
actual reply message.  If the 'MSGHDR_CKSUM_INCOMPAT18' flag is set
(in requests since Lustre 1.8) and the server understands the flag,
then the server will send early reply messages with the appropriate
'lm_cksum'. The 'lm_cksum' is mandatory in Lustre 2.8 and later.

The 'lm_flags' field contains flags that affect the protocol.  The
'MSGHDR_AT_SUPPORT' (0x1) bit indicates that the sender understands
adaptive timeouts and can receive 'early reply' messages.  This flag
was introduced in Lustre 1.6.  The 'MSGHDR_CKSUM_INCOMPAT18' (0x2) bit
indicates that 'lm_cksum' is computed on the full 'ptlrpc_body'
message buffer rather than on the original 'ptlrpc_body_v2' structure
size (88 bytes).  It was introduced in Lustre 1.8 and is mandatory for
all requests in Lustre 2.8 and later.

The 'lm_padding*' fields are reserved for future use.

The array of 'lm_buflens' values has 'lm_bufcount' entries. Each
entry corresponds to, and gives the length in bytes of, one of the
buffers that will follow.  The entire header, and each of the buffers,
is required to be a multiple of eight bytes long to ensure the buffers
are properly aligned to hold __u64 values. Thus there may be an extra
four bytes of padding after the 'lm_buflens' array if that array has
an odd number of entries.