lustre_operations.txt

   1 Lustre Operations
   2 -----------------
   3 [[lustre-operations]]
   4
   5 Lustre operations are denoted by the 'pb_opc' op-code field of the
   6 message preamble. Each operation is implemented as a pair of messages,
   7 with the 'pb_type' field set to PTLRPC_MSG_REQUEST for requests
   8 initiating the operation, and PTLRPC_MSG_REPLY for replies. Note that
   9 as a general matter, the receipt by a client of the rply message only
  10 assures the client hat the server has initiated the action, if
  11 any. See the discussion on <<transno,transaction numbers>>
  12 and <<recovery>> for how the client is given confirmation that a
  13 request has been completed.
  14
  15 include::ost_setattr.txt[]
  16
  17 Command 8: OST CONNECT - Client connection to an OST
  18 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  19
  20 .OST_CONNECT (8)
  21 [options="header"]
  22 |====
  23 | request            | reply
  24 | obd_connect_client | obd_connect_server
  25 |====
  26
  27 When a client initiates a connection to a specific target on an OSS,
  28 it does so by sending an 'obd_connect_client' message and awaiting the
  29 reply from the OSS of an 'obd_connect_server' message. From a previous
  30 interaction with the MGS the client knows the UUID of the target OST,
  31 and can fill that value into the 'obd_connect_client' message.
  32
  33 The 'ocd_connect_flags' field is set to (fixme: what?) reflecting the
  34 capabilities appropriate to the client. The 'ocd_brw_size' is set to the
  35 largest value for the size of an RPC that the client can handle. The
  36 'ocd_ibits_known' and 'ocd_checksum_types' values are set to what the client
  37 considers appropriate. Other fields in the preamble and
  38 'obd_connect_data' structures are zero, as is the 'lustre_handle'
  39 element.
  40
  41 Once the server receives the 'obd_connect_client' message on behalf of
  42 the given target it replies with an 'obd_connect_server' message. In
  43 that message the server sends the 'pb__handle' to uniquely
  44 identify the connection for subsequent communication. The client notes
  45 that handle in its import for the given target.
  46
  47 fixme: Are there circumstances that could lead to the 'status'
  48 value in the reply being non-zero? What would lead to that and what
  49 error values would result?
  50
  51 The target maintains the last committed transaction for a client in
  52 its export for that client. If this is the first connection, then that
  53 last transactiion value would just be zero. If there were previous
  54 transactions for the client, then the transaction number for the last
  55 such committed transaction is put in the 'pb_last_committed' field.
  56
  57 In a connection request the operation is not file system modifying, so
  58 the 'pb_transno' value will be zero in the reply as well.
  59
  60 fixme: there is still some work to be done about how the fields are
  61 managed.
  62
  63 Command 9: OST DISCONNECT - Disconnect client from an OST
  64 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  65
  66 .OST_DISCONNECT (9)
  67 [options="header"]
  68 |====
  69 | request | reply
  70 | empty   | empty
  71 |====
  72
  73 The information exchanged in a DISCONNECT message is that normally
  74 conveyed in the mesage preamble.
  75
  76 include::ost_punch.txt[]
  77
  78 Command 33: MDS GETATTR - Get MDS Attributes
  79 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  80
  81 .MDS_GETATTR (33)
  82 [options="header"]
  83 |====
  84 | request       | reply
  85 | mdt_body_capa | mds_getattr_server
  86 |====
  87
  88
  89 include::mds_reint.txt[]
  90
  91 Command 38: MDS CONNECT - Client connection to an MDS
  92 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  93
  94 .MDS_CONNECT (38)
  95 [options="header"]
  96 |====
  97 | request            | reply
  98 | obd_connect_client | obd_connect_server
  99 |====
 100
 101 N.B. This is nearly identical to the explanation for OST_CONNECT and
 102 for MGS_CONNECT.  We may want to simplify and/or unify the discussion
 103 and only call out how this one differees from a generic CONNECT
 104 operation.
 105
 106 When a client initiates a connection to a specific target on an MDS,
 107 it does so by sending an 'obd_connect_client' message and awaiting the
 108 reply from the MDS of an 'obd_connect_server' message. From a previous
 109 interaction with the MGS the client knows the UUID of the target MDT,
 110 and can fill that value into the 'obd_connect_client' message.
 111
 112 The 'ocd_connect_flags' field is set to (fixme: what?) reflecting the
 113 capabilities appropriate to the client. The 'ocd_brw_size' is set to the
 114 largest value for the size of an RPC that the client can handle. The
 115 'ocd_ibits_known' and 'ocd_checksum_types' values are set to what the client
 116 considers appropriate. Other fields in the preamble and
 117 'obd_connect_data' structures are zero, as is the 'lustre_handle'
 118 element.
 119
 120 Once the server receives the 'obd_connect_client' message on behalf of
 121 the given target it replies with an 'obd_connect_server' message. In
 122 that message the server sends the 'pb__handle' to uniquely
 123 identify the connection for subsequent communication. The client notes
 124 that handle in its import for the given target.
 125
 126 fixme: Are there circumstances that could lead to the 'status'
 127 value in the reply being non-zero? What would lead to that and what
 128 error values would result?
 129
 130 The target maintains the last committed transaction for a client in
 131 its export for that client. If this is the first connection, then that
 132 last transactiion value would just be zero. If there were previous
 133 transactions for the client, then the transaction number for the last
 134 such committed transaction is put in the 'pb_last_committed' field.
 135
 136 In a connection request the operation is not file system modifying, so
 137 the 'pb_transno' value will be zero in the reply as well.
 138
 139 fixme: there is still some work to be done about how the fields are
 140 managed.
 141
 142 Command 39: MDS DISCONNECT - Disconnect client from an MDS
 143 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 144
 145 .MDS_DISCONNECT (39)
 146 [options="header"]
 147 |====
 148 | request | reply
 149 | empty   | empty
 150 |====
 151
 152 The information exchanged in a DISCONNECT message is that normally
 153 conveyed in the mesage preamble.
 154
 155 Command 40: MDS GETSTATUS - get the status from a target
 156 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 157
 158 The MDS_GETSTATUS command targets a specific MDT. If there are several,
 159 the client will need to send a separate message for each.
 160
 161 .MDS_GETSTATUS (40)
 162 [options="header"]
 163 |====
 164 | request       | reply
 165 | mdt_body_only | mdt_body_capa
 166 |====
 167
 168 The 'mdt_body_only' request message is one that provides information
 169 about a specific MDT, identifying which (among several possible)
 170 target is being asked about.
 171
 172 In the reply there is additional information about the MDT's
 173 capabilities.
 174
 175 Command 41: MDS STATFS - get statfs data from the server
 176 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 177
 178 .MDS_STATFS (41)
 179 [options="header"]
 180 |====
 181 | request | reply
 182 | empty   | obd_statfs_server
 183 |====
 184
 185 The 'empty' request message is one that only has the 'ptlrpc_body'
 186 data encoded. The fields have thier generic values for a request from
 187 this client, with 'pb_opc' being set to MDS_STATFS (41).
 188
 189 In the reply there is, in addition to the 'ptlrpc_body', data relevant
 190 to a 'statfs' system call.
 191
 192 include::mds_getxattr.txt[]
 193
 194 include::ldlm_enqueue.txt[]
 195
 196 include::ldlm_cancel.txt[]
 197
 198 include::ldlm_bl_callback.txt[]
 199
 200 include::ldlm_cp_callback.txt[]
 201
 202 Command 250: MGS CONNECT - Client connection to an MGS
 203 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 204
 205 .MGS_CONNECT (250)
 206 [options="header"]
 207 |====
 208 | request            | reply
 209 | obd_connect_client | obd_connect_server
 210 |====
 211
 212 When a client initiates a connection to the MGS,
 213 it does so by sending an 'obd_connect_client' message and awaiting the
 214 reply from the MGS of an 'obd_connect_server' message. This is the
 215 first operation carried out by a client upon the issue of a 'mount'
 216 command, and the target UUID is provided on the command line.
 217
 218 The target UUID is just "MGS", and the client UUID is set to the
 219 32byte string it gets from ... where?
 220
 221 The 'struct lustre_handle' (the fourth buffer in the message) has its
 222 cookie set to .. what? It is set, but where does it come from?
 223
 224 The 'ocd_connect_flags' field is set to (fixme: what?) reflecting the
 225 capabilities appropriate to the client. The 'ocd_brw_size' is set to the
 226 largest value for the size of an RPC that the client can handle. The
 227 'ocd_ibits_known' and 'ocd_checksum_types' values are set to what the client
 228 considers appropriate. Other fields in the preamble and
 229 'obd_connect_data' structures are zero.
 230
 231 Once the server receives the 'obd_connect_client' message on behalf of
 232 the given target it replies with an 'obd_connect_server' message. In
 233 that message the server sends the 'pb__handle' to uniquely
 234 identify the connection for subsequent communication. The client notes
 235 that handle in its import for the given target.
 236
 237 fixme: Are there circumstances that could lead to the 'status'
 238 value in the reply being non-zero? What would lead to that and what
 239 error values would result?
 240
 241 The target maintains the last committed transaction for a client in
 242 its export for that client. If this is the first connection, then that
 243 last transactiion value would just be zero. If there were previous
 244 transactions for the client, then the transaction number for the last
 245 such committed transaction is put in the 'pb_last_committed' field.
 246
 247 In a connection request the operation is not file system modifying, so
 248 the 'pb_transno' value will be zero in the reply as well.
 249
 250 Command 251: MGS DISCONNECT - Disconnect client from an MGS
 251 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 252
 253 .MGS_DISCONNECT (251)
 254 [options="header"]
 255 |====
 256 | request | reply
 257 | empty   | empty
 258 |====
 259
 260 N.B. The usual 'struct req_format' definition does not exist for
 261 MGS_DISCONNECT. It will take a more careful code review to verify that
 262 it also has 'empty' messages gong back and forth.
 263
 264 The information exchanged in a DISCONNECT message is that normally
 265 conveyed in the mesage preamble.
 266
 267 Command 256: MGS CONFIG READ - Read MGS configuration info
 268 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 269
 270 .MGS_CONFIG_READ (256)
 271 [options="header"]
 272 |====
 273 | request            | reply
 274 | mgs_config_read_client | mgs_config_read_server
 275 |====
 276
 277 Command 501: LLOG ORIGIN HANDLE CREATE - Create llog handle
 278 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 279
 280 .LLOG_ORIGIN_HANDLE_CREATE (510)
 281 [options="header"]
 282 |====
 283 | request                          | reply
 284 | llog_origin_handle_create_client | llogd_body_only
 285 |====
 286
 287 Command 502: LLOG ORIGIN HANDLE NEXT BLOCK - Read the next block
 288 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 289
 290 .LLOG_ORIGIN_HANDLE_NEXT_BLOCK (502)
 291 [options="header"]
 292 |====
 293 | request         | reply
 294 | llogd_body_only | llog_origin_handle_next_block_server
 295 |====
 296
 297 Command 503: LLOG ORIGIN HANDLE READ HEADER - Read handle header
 298 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 299
 300 .LLOG_ORIGIN_HANDLE_READ_HEADER (503)
 301 [options="header"]
 302 |====
 303 | request         | reply
 304 | llogd_body_only | llog_log_hdr_only
 305 |====
 306
 307 LLOG_ORIGIN_HANDLE_NEXT_BLOCK