struct_ldlm_request.txt

   1 LDLM Request
   2 ^^^^^^^^^^^^
   3 [[struct-ldlm-request]]
   4
   5 The 'ldlm_request' structure is a description of the lock being
   6 requested. Which resource is the target, what lock is current, and
   7 what lock desired.
   8
   9 [source,c]
  10 ----
  11 struct ldlm_request {
  12         __u32 lock_flags;
  13         __u32 lock_count;
  14         struct ldlm_lock_desc lock_desc;
  15         struct lustre_handle lock_handle[2];
  16 };
  17 ----
  18
  19 The 'lock_flags' field governs how the lock request is to be
  20 interpreted. The flags are:
  21
  22 [source,c]
  23 ----
  24 #define LDLM_FL_LOCK_CHANGED            0x0000000000000001ULL // bit   0
  25 #define LDLM_FL_BLOCK_GRANTED           0x0000000000000002ULL // bit   1
  26 #define LDLM_FL_BLOCK_CONV              0x0000000000000004ULL // bit   2
  27 #define LDLM_FL_BLOCK_WAIT              0x0000000000000008ULL // bit   3
  28 #define LDLM_FL_AST_SENT                0x0000000000000020ULL // bit   5
  29 #define LDLM_FL_REPLAY                  0x0000000000000100ULL // bit   8
  30 #define LDLM_FL_INTENT_ONLY             0x0000000000000200ULL // bit   9
  31 #define LDLM_FL_HAS_INTENT              0x0000000000001000ULL // bit  12
  32 #define LDLM_FL_FLOCK_DEADLOCK          0x0000000000008000ULL // bit  15
  33 #define LDLM_FL_DISCARD_DATA            0x0000000000010000ULL // bit  16
  34 #define LDLM_FL_NO_TIMEOUT              0x0000000000020000ULL // bit  17
  35 #define LDLM_FL_BLOCK_NOWAIT            0x0000000000040000ULL // bit  18
  36 #define LDLM_FL_TEST_LOCK               0x0000000000080000ULL // bit  19
  37 #define LDLM_FL_CANCEL_ON_BLOCK         0x0000000000800000ULL // bit  23
  38 #define LDLM_FL_DENY_ON_CONTENTION      0x0000000040000000ULL // bit  30
  39 #define LDLM_FL_AST_DISCARD_DATA        0x0000000080000000ULL // bit  31
  40 #define LDLM_FL_FAIL_LOC                0x0000000100000000ULL // bit  32
  41 #define LDLM_FL_SKIPPED                 0x0000000200000000ULL // bit  33
  42 #define LDLM_FL_CBPENDING               0x0000000400000000ULL // bit  34
  43 #define LDLM_FL_WAIT_NOREPROC           0x0000000800000000ULL // bit  35
  44 #define LDLM_FL_CANCEL                  0x0000001000000000ULL // bit  36
  45 #define LDLM_FL_LOCAL_ONLY              0x0000002000000000ULL // bit  37
  46 #define LDLM_FL_FAILED                  0x0000004000000000ULL // bit  38
  47 #define LDLM_FL_CANCELING               0x0000008000000000ULL // bit  39
  48 #define LDLM_FL_LOCAL                   0x0000010000000000ULL // bit  40
  49 #define LDLM_FL_LVB_READY               0x0000020000000000ULL // bit  41
  50 #define LDLM_FL_KMS_IGNORE              0x0000040000000000ULL // bit  42
  51 #define LDLM_FL_CP_REQD                 0x0000080000000000ULL // bit  43
  52 #define LDLM_FL_CLEANED                 0x0000100000000000ULL // bit  44
  53 #define LDLM_FL_ATOMIC_CB               0x0000200000000000ULL // bit  45
  54 #define LDLM_FL_BL_AST                  0x0000400000000000ULL // bit  46
  55 #define LDLM_FL_BL_DONE                 0x0000800000000000ULL // bit  47
  56 #define LDLM_FL_NO_LRU                  0x0001000000000000ULL // bit  48
  57 #define LDLM_FL_FAIL_NOTIFIED           0x0002000000000000ULL // bit  49
  58 #define LDLM_FL_DESTROYED               0x0004000000000000ULL // bit  50
  59 #define LDLM_FL_SERVER_LOCK             0x0008000000000000ULL // bit  51
  60 #define LDLM_FL_RES_LOCKED              0x0010000000000000ULL // bit  52
  61 #define LDLM_FL_WAITED                  0x0020000000000000ULL // bit  53
  62 #define LDLM_FL_NS_SRV                  0x0040000000000000ULL // bit  54
  63 #define LDLM_FL_EXCL                    0x0080000000000000ULL // bit  55
  64 ----
  65
  66 The 'lock_count' field represents how many requests are queued on this
  67 resource.
  68
  69 [[struct-ldlm-lock-desc]]
  70
  71 The lock descriptor conveys the specific details about a particular
  72 lock being requested or granted. It appears in
  73 <<struct-ldlm-request>>.
  74
  75 [source,c]
  76 ----
  77 struct ldlm_lock_desc {
  78         struct ldlm_resource_desc l_resource;
  79         ldlm_mode_t l_req_mode;
  80         ldlm_mode_t l_granted_mode;
  81         ldlm_wire_policy_data_t l_policy_data;
  82 };
  83 ----
  84
  85 [[struct-ldlm-resource-desc]]
  86
  87 The resource descriptor identifies the individual resource that is
  88 being locked, along with what sort of thing it is.
  89
  90 [source,c]
  91 ----
  92 struct ldlm_resource_desc {
  93         ldlm_type_t lr_type;
  94         __u32 lr_padding;       /* also fix lustre_swab_ldlm_resource_desc */
  95         struct ldlm_res_id lr_name;
  96 };
  97 ----
  98
  99 [[ldlm-type-t]]
 100 The 'lr_type' field identifies one of the four types of lock that
 101 might be placed on a resource. A "plain" lock type just locks a
 102 particular resource. An "extent" lock type only locks a contiguous
 103 sequence of byte offsets within a regular file. An "flock" lock type
 104 represents an application layer advisory lock from the 'flock()'
 105 system call. While Lustre manages "flock" types locks on behalf of the
 106 application, they do not affect Lustre operation.  An "ibits" lock
 107 type allows fine grained locking of different parts of a single
 108 resource. A single lock request or cancellation may operate on one or
 109 more lock bits, or individual lock bits may be granted on the same
 110 resource separately.  See also <<ldlm-wire-policy-data-t>>.  A lock
 111 descriptor may also have no type at all, in which case the 'lr_type'
 112 field is 0, meaning "no lock".
 113
 114 [source,c]
 115 ----
 116 enum {
 117         LDLM_PLAIN     = 10,
 118         LDLM_EXTENT    = 11,
 119         LDLM_FLOCK     = 12,
 120         LDLM_IBITS     = 13,
 121 } ldlm_type_t;
 122 ----
 123
 124 [[struct-ldlm-res-id]]
 125 The 'lr_name' field identifies (by name) the resource(s) that are the
 126 objects of the locking operation.
 127
 128 [source,c]
 129 ----
 130 struct ldlm_res_id {
 131         __u64 name[4];
 132 };
 133 ----
 134
 135 The 'name' array holds identifiers for the resource in question. Those
 136 identifiers may be the elements of a 'struct lu_fid' file ID, or they
 137 may be other uniquely identifying values for the resource. See
 138 <<struct-lu-fid>>.
 139
 140 [[ldlm-mode-t]]
 141 The 'l_req_mode' and 'l_granted_mode' fields give the kind of lock
 142 being requested and the kind of lock that has been granted. The field
 143 values are:
 144
 145 [source,c]
 146 ----
 147 enum {
 148         LCK_EX      = 1, /* exclusive */
 149         LCK_PW      = 2, /* privileged write */
 150         LCK_PR      = 4, /* privileged read */
 151         LCK_CW      = 8, /* concurrent write */
 152         LCK_CR      = 16, /* concurrent read */
 153         LCK_NL      = 32, /* */
 154         LCK_GROUP   = 64, /* */
 155         LCK_COS     = 128, /* */
 156 } ldlm_mode_t;
 157 ----
 158
 159 Despite the fact that the lock modes are not overlapping, these lock
 160 modes are exclusive.  In addition the mode value 0 is the MINMODE,
 161 i.e. no lock at all.
 162
 163 In a request 'l_req_mode' is the value actually being requested and
 164 'l_granted_mode' is the value that currently is in place on for the
 165 requester. In a reply the 'l_req_mode' may be modified if more or
 166 fewer privileges were granted than requested, and the
 167 'l_granted_mode' is what has, in fact, been granted.
 168
 169 [[ldlm-wire-policy-data-t]]
 170 The 'l_policy_data' field gives the kind of resource being
 171 requested/granted. It is a union of these struct definitions:
 172
 173 [source,c]
 174 ----
 175 typedef union {
 176         struct ldlm_extent l_extent;
 177         struct ldlm_flock_wire l_flock;
 178         struct ldlm_inodebits l_inodebits;
 179 } ldlm_wire_policy_data_t;
 180 ----
 181
 182 [[struct-ldlm-extent]]
 183 [source,c]
 184 ----
 185 struct ldlm_extent {
 186         __u64 start;
 187         __u64 end;
 188         __u64 gid;
 189 };
 190 ----
 191
 192 [[struct-ldlm-flock-wire]]
 193 [source,c]
 194 ----
 195 struct ldlm_flock_wire {
 196         __u64 lfw_start;
 197         __u64 lfw_end;
 198         __u64 lfw_owner;
 199         __u32 lfw_padding;
 200         __u32 lfw_pid;
 201 };
 202 ----
 203
 204 [[struct-ldlm-inodebits]]
 205 [source,c]
 206 ----
 207 struct ldlm_inodebits {
 208         __u64 bits;
 209 };
 210 ----
 211
 212 Thus the lock may be on an 'extent', a contiguous sequence of bytes
 213 in a regular file; an 'flock wire', whatever to heck that is; or a
 214 portion of an inode. For a "plain" lock (or one with no type at all)
 215 the 'l_policy_data' field has zero length.
 216
 217 The 'lock_handle' array's first element holds the handle for the lock
 218 manager (see the description of <<struct-lustre-handle>>) involved in
 219 the operation. There is only one lock manager involved in any given
 220 RPC. The second handle is set to zero except in the rare case that
 221 there is also an early lock cancellation. The latter case will be
 222 discussed elsewhere.
 223