data_types.txt

   1 Data Structures and Defines
   2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
   3 [[data-structs]]
   4
   5 The following data types are used in the Lustre protocol description.
   6
   7 .Basic Data Types
   8 [options="header"]
   9 |=====
  10 | data types  | size
  11 | __u8       | an 8-bit unsigned integer
  12 | __u16      | a 16-bit unsigned integer
  13 | __u32      | a 32-bit unsigned integer
  14 | __u64      | a 64-bit unsigned integer
  15 | __s64      | a 64-bit signed integer
  16 | obd_time   | an __s64
  17 |=====
  18
  19
  20 The following topics introduce the various kinds of data that are
  21 represented and manipulated in Lustre messages and representations of
  22 the shared state on clients and servers.
  23
  24 Grant
  25 ^^^^^
  26 [[grant]]
  27
  28 A grant value is part of a client's state for a given target. It
  29 provides an upper bound to the amount of dirty cache data the client
  30 will allow that is destined for the target. The value is established
  31 by agreement between the server and the client and represents a
  32 guarantee by the server that the target storage has space for the
  33 dirty data. The client can ask for additional grant, which the server
  34 may provide depending on how full the target is.
  35
  36 LOV Index
  37 ^^^^^^^^^
  38 [[lov-index]]
  39
  40 Each target is assigned an LOV index (by the 'mkfs' command line) as
  41 the target is added to the file system. This value is stored in the
  42 MGS in order to identify its role in the file system.
  43
  44 Transaction Number
  45 ^^^^^^^^^^^^^^^^^^
  46 [[transno]]
  47
  48 For each target there is a sequence of values (a strictly increasing
  49 series of numbers) where each operation that can modify the file
  50 system is assigned the next number in the series. This is the
  51 transaction number, and it imposes a strict serial ordering to all of
  52 the file system modifying operations.  For file system modifying
  53 requests the server generates the next value in the sequence and
  54 informs the client of the value in the 'pb_transno' field of the
  55 'ptlrpc_body' of its reply to the client's request. For replys to
  56 requests that do not modify the file system the 'pb_transno' field in
  57 the 'ptlrpc_body' is just set to 0.
  58
  59 Extended Attributes
  60 ^^^^^^^^^^^^^^^^^^^
  61
  62 I have not figured out how so called 'eadata' buffers are handled,
  63 yet. I am told that this is not just for extended attributes, but is a
  64 generic structure.
  65
  66 Lustre Capabilities
  67 ^^^^^^^^^^^^^^^^^^^
  68
  69 A 'lustre_capa' structure conveys details about the capabilities
  70 supported (or requested) between a client and a given target. I am
  71 told that this is deprecated in later version of Lustre.
  72
  73 ----
  74 #define CAPA_HMAC_MAX_LEN       64
  75 struct lustre_capa {
  76         struct lu_fid   lc_fid;
  77         __u64           lc_opc;
  78         __u64           lc_uid;
  79         __u64           lc_gid;
  80         __u32           lc_flags;
  81         __u32           lc_keyid;
  82         __u32           lc_timeout;
  83         __u32           lc_expiry;
  84         __u8            lc_hmac[CAPA_HMAC_MAX_LEN];
  85 }
  86 ----
  87
  88 include::lustre_file_ids.txt[]
  89
  90
  91 MGS Configuration Reference
  92 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  93
  94 ----
  95 #define MTI_NAME_MAXLEN  64
  96 struct mgs_config_body {
  97         char     mcb_name[MTI_NAME_MAXLEN]; /* logname */
  98         __u64    mcb_offset;    /* next index of config log to request */
  99         __u16    mcb_type;      /* type of log: CONFIG_T_[CONFIG|RECOVER] */
 100         __u8     mcb_reserved;
 101         __u8     mcb_bits;      /* bits unit size of config log */
 102         __u32    mcb_units;     /* # of units for bulk transfer */
 103 };
 104 ----
 105
 106 The 'mgs_config_body' structure has information identifying to the MGS
 107 which Lustre file system the client is asking about.
 108
 109 MGS Configuration Data
 110 ^^^^^^^^^^^^^^^^^^^^^^
 111
 112 ----
 113 struct mgs_config_res {
 114         __u64    mcr_offset;    /* index of last config log */
 115         __u64    mcr_size;      /* size of the log */
 116 };
 117 ----
 118
 119 The 'mgs_config_res' structure returns information about the Lustre
 120 file system.
 121
 122 include::lustre_handle.txt[]
 123
 124 Lustre Message Header
 125 ^^^^^^^^^^^^^^^^^^^^^
 126 [[lustre-message-header]]
 127
 128 Every message has an initial header that informs the receiver about
 129 the size of the rest of the message to follow along with a few other
 130 details.
 131
 132 ----
 133 #define LUSTRE_MSG_MAGIC_V2 0x0BD00BD3
 134 #define MSGHDR_AT_SUPPORT               0x1
 135 struct lustre_msg_v2 {
 136         __u32 lm_bufcount;
 137         __u32 lm_secflvr;
 138         __u32 lm_magic;
 139         __u32 lm_repsize;
 140         __u32 lm_cksum;
 141         __u32 lm_flags;
 142         __u32 lm_padding_2;
 143         __u32 lm_padding_3;
 144         __u32 lm_buflens[0];
 145 };
 146 #define lustre_msg lustre_msg_v2
 147 ----
 148
 149 The 'lm_buffcount' field gives the number of buffers that will follow
 150 the header. The header and sequence of buffers constitutes one
 151 message. Each of the buffers is a sequence of bytes whose contents
 152 corresponds to one of the structures described in this section. There
 153 will always be at least one, and no message has more than eight.
 154
 155 The 'lm_secflvr' field gives an indication of whether any sort of
 156 cyptographic encoding of the subsequent buffers will be in force. The
 157 value is zero if there is no "crypto" and gives a code identifying the
 158 "flavor" of crypto if it is employed. Further, if crypto is employed
 159 there will only be one buffer following (i.e. buffcount = 1), and that
 160 buffer is an encoding of what would otherwise have been the sequence
 161 of buffers normally following the header. This document will defer all
 162 discussion of cryptography. An chapter is planned that will address it
 163 separately.
 164
 165 The 'lm_magic' field is a "magic" value (LUSTRE_MSG_MAGIC_V2) that is
 166 checked in order to positively identify that the message is intended
 167 for the use to which it is being put. That is, we are indeed dealing
 168 with a Lustre message, and not, for example, corrupted memory or a bad
 169 pointer.
 170
 171 The 'lm_repsize' field is an indication from the sender of an action
 172 request of the maximum available space that has been set aside for
 173 any reply to the request. A reply that attempts to use more than that
 174 much space will be discarded.
 175
 176 The 'lm_cksum' has to do with the <<security>> settings for the
 177 cluster. Fixme: This may not be in current use. We need to verify.
 178
 179 The 'lm_flags' field can be set to enable adaptive timeouts support
 180 with the value MSGHDR_AT_SUPPORT.
 181
 182 The 'lm_padding*' fields are reserved for future use.
 183
 184 The array of 'lm_bufflens' values has 'lm_bufcount' entries. Each
 185 entry corresponds to, and gives the length of, one of the buffers that
 186 will follow.
 187
 188 The entire header is required to be a multiple of eight bytes
 189 long. Thus there may need to an extra four bytes of padding after the
 190 'lm_bufflens' array if that array has an odd number of entries.
 191
 192 include::ptlrpc_body.txt[]
 193
 194 Object Based Disk UUID
 195 ^^^^^^^^^^^^^^^^^^^^^^
 196
 197 ----
 198 #define UUID_MAX        40
 199 struct obd_uuid {
 200         char uuid[UUID_MAX];
 201 };
 202 ----
 203
 204 OST ID
 205 ^^^^^^
 206
 207 ----
 208 struct ost_id {
 209         union {
 210                 struct ostid {
 211                         __u64   oi_id;
 212                         __u64   oi_seq;
 213                 } oi;
 214                 struct lu_fid oi_fid;
 215         } LUSTRE_ANONYMOUS_UNION_NAME;
 216 };
 217 ----