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