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