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 .LDLM Lock Descriptor
  70 [[struct-ldlm-lock-desc]]
  71 ****
  72 The lock descriptor conveys the specific details about a particular
  73 lock being requested or granted. It appears in
  74 <<struct-ldlm-request>>.
  75
  76 [source,c]
  77 ----
  78 struct ldlm_lock_desc {
  79         struct ldlm_resource_desc l_resource;
  80         ldlm_mode_t l_req_mode;
  81         ldlm_mode_t l_granted_mode;
  82         ldlm_wire_policy_data_t l_policy_data;
  83 };
  84 ----
  85 ****
  86
  87 .LDLM Resource Descriptor
  88 [[struct-ldlm-resource-desc]]
  89 ****
  90 The resource descriptor identifies the individual resource that is
  91 being locked, along with what sort of thing it is.
  92
  93 [source,c]
  94 ----
  95 struct ldlm_resource_desc {
  96         ldlm_type_t lr_type;
  97         __u32 lr_padding;       /* also fix lustre_swab_ldlm_resource_desc */
  98         struct ldlm_res_id lr_name;
  99 };
 100 ----
 101 ****
 102
 103 The 'lr_type' field identifies one of the four types of lock that
 104 might be placed on a resource. A "plain" lock type just locks a
 105 particular resource. An "extent" lock type only locks a contiguous
 106 sequence of byte offsets within a regular file. An "flock" lock type
 107 represents an application layer advisory lock from the 'flock()'
 108 system call. While Lustre manages "flock" types locks on behalf of the
 109 application, they do not affect Lustre operation.  An "ibits" lock
 110 type allows fine grained locking of different parts of a single
 111 resource. A single lock request or cancellation may operate on one or
 112 more lock bits, or individual lock bits may be granted on the same
 113 resource separately.  See also <<ldlm-wire-policy-data-t>>.  A lock
 114 descriptor may also have no type at all, in which case the 'lr_type'
 115 field is 0, meaning "no lock".
 116
 117 .LDLM Type
 118 [[ldlm-type-t]]
 119 ****
 120 [source,c]
 121 ----
 122 enum {
 123         LDLM_PLAIN     = 10,
 124         LDLM_EXTENT    = 11,
 125         LDLM_FLOCK     = 12,
 126         LDLM_IBITS     = 13,
 127 } ldlm_type_t;
 128 ----
 129 ****
 130
 131 The 'lr_name' field of the 'ldlm_resource_desc' (See
 132 <<struct-ldlm-res-id>>) field identifies the resource that is the
 133 object of the locking operation.
 134
 135 .LDLM Resource ID
 136 [[struct-ldlm-res-id]]
 137 ****
 138 [source,c]
 139 ----
 140 struct ldlm_res_id {
 141         __u64 name[4];
 142 };
 143 ----
 144
 145 The 'name' identifies for the resource in question. It may be a FID
 146 (See <<struct-lu-fid>>), or they may be other uniquely identifying
 147 values for the resource.
 148 ****
 149
 150 The 'l_req_mode' and 'l_granted_mode' fields give the kind of lock
 151 being requested and the kind of lock that has been granted. The field
 152 values are:
 153
 154 .LDLM Mode
 155 [[ldlm-mode-t]]
 156 ****
 157 [source,c]
 158 ----
 159 enum {
 160         LCK_EX      = 1, /* exclusive */
 161         LCK_PW      = 2, /* privileged write */
 162         LCK_PR      = 4, /* privileged read */
 163         LCK_CW      = 8, /* concurrent write */
 164         LCK_CR      = 16, /* concurrent read */
 165         LCK_NL      = 32, /* */
 166         LCK_GROUP   = 64, /* */
 167         LCK_COS     = 128, /* */
 168 } ldlm_mode_t;
 169 ----
 170
 171 Despite the fact that the lock modes are not overlapping, these lock
 172 modes are exclusive.  In addition the mode value 0 is the MINMODE,
 173 i.e. no lock at all.
 174 ****
 175
 176 In an 'ldlm_request' structure the 'l_req_mode' field is the value
 177 actually being requested and the 'l_granted_mode' field is the value
 178 that currently is in place on for the requester. In an 'ldlm_reply'
 179 the 'l_req_mode' field may be modified if more or fewer privileges
 180 were granted than requested, and the 'l_granted_mode' is what has, in
 181 fact, been granted.
 182
 183 The 'l_policy_data' field gives the kind of resource being
 184 requested/granted. It is a union of these struct definitions:
 185
 186 .LDLM Wire Policy Data
 187 [[ldlm-wire-policy-data-t]]
 188 ****
 189 [source,c]
 190 ----
 191 typedef union {
 192         struct ldlm_extent l_extent;
 193         struct ldlm_flock_wire l_flock;
 194         struct ldlm_inodebits l_inodebits;
 195 } ldlm_wire_policy_data_t;
 196 ----
 197 ****
 198
 199 .LDLM Extent
 200 [[struct-ldlm-extent]]
 201 ****
 202 [source,c]
 203 ----
 204 struct ldlm_extent {
 205         __u64 start;
 206         __u64 end;
 207         __u64 gid;
 208 };
 209 ----
 210 ****
 211
 212 .LDLM Flock Wire
 213 [[struct-ldlm-flock-wire]]
 214 ****
 215 [source,c]
 216 ----
 217 struct ldlm_flock_wire {
 218         __u64 lfw_start;
 219         __u64 lfw_end;
 220         __u64 lfw_owner;
 221         __u32 lfw_padding;
 222         __u32 lfw_pid;
 223 };
 224 ----
 225 ****
 226
 227 .LDLM Inodebits
 228 [[struct-ldlm-inodebits]]
 229 ****
 230 [source,c]
 231 ----
 232 struct ldlm_inodebits {
 233         __u64 bits;
 234 };
 235 ----
 236 ****
 237
 238 Thus the lock may be on an 'extent', a contiguous sequence of bytes
 239 in a regular file; an 'flock wire', whatever to heck that is; or a
 240 portion of an inode. For a "plain" lock (or one with no type at all)
 241 the 'l_policy_data' field has zero length.
 242
 243 The 'lock_handle' array's first element holds the handle for the lock
 244 manager (see the description of <<struct-lustre-handle>>) involved in
 245 the operation. There is only one lock manager involved in any given
 246 RPC. The second handle is set to zero except in the rare case that
 247 there is also an early lock cancellation. The latter case will be
 248 discussed elsewhere.
 249