LUDOC-276 protocol: Document RPCs for setattr

[doc/protocol.git] / ldlm_lock_desc.txt

diff --git a/ldlm_lock_desc.txt b/ldlm_lock_desc.txt
new file mode 100644 (file)
index 0000000..755f442
--- /dev/null
+++ b/ldlm_lock_desc.txt
@@ -0,0 +1,84 @@
+LDLM Lock Descriptor
+^^^^^^^^^^^^^^^^^^^^
+[[struct-ldlm-lock-desc]]
+
+The lock descriptor conveys the specific details about a particular
+lock being requested or granted. It appears in
+<<struct-ldlm-request>>.
+
+----
+struct ldlm_lock_desc {
+        struct ldlm_resource_desc l_resource;
+        ldlm_mode_t l_req_mode;
+        ldlm_mode_t l_granted_mode;
+        ldlm_wire_policy_data_t l_policy_data;
+};
+----
+
+The 'l_resource' field identifies the resource upon which the lock is
+being requested or granted. See the description of
+<<struct-ldlm-resource-desc>>.
+
+The 'l_req_mode' and 'l_granted_mode' fields give the kind of lock
+being requested and the kind of lock that has been granted. The field
+values are:
+
+----
+typedef enum {
+        LCK_EX      = 1, /* exclusive */
+        LCK_PW      = 2, /* privileged write */
+        LCK_PR      = 4, /* privileged read */
+        LCK_CW      = 8, /* concurrent write */
+        LCK_CR      = 16, /* concurrent read */
+        LCK_NL      = 32, /* */
+        LCK_GROUP   = 64, /* */
+        LCK_COS     = 128, /* */
+} ldlm_mode_t;
+----
+
+Despite the fact that the lock modes are not overlapping, these lock
+modes are exclusive.  In addition the mode value 0 is the MINMODE,
+i.e. no lock at all.
+
+In a request 'l_req_mode' is the value actually being requested and
+'l_granted_mode' is the value that currently is in place on for the
+requester. In a reply the 'l_req_mode' may be modified if more or
+fewer privileges were granted than requested, and the
+'l_granted_mode' is what has, in fact, been granted.
+
+The 'l_policy_data' field gives the kind of resource being
+requested/granted. It is a union of these struct definitions:
+[[ldlm-wire-policy-data-t]]
+
+----
+typedef union {
+        struct ldlm_extent l_extent;
+        struct ldlm_flock_wire l_flock;
+        struct ldlm_inodebits l_inodebits;
+} ldlm_wire_policy_data_t;
+----
+
+----
+struct ldlm_extent {
+        __u64 start;
+        __u64 end;
+        __u64 gid;
+};
+struct ldlm_flock_wire {
+        __u64 lfw_start;
+        __u64 lfw_end;
+        __u64 lfw_owner;
+        __u32 lfw_padding;
+        __u32 lfw_pid;
+};
+struct ldlm_inodebits {
+        __u64 bits;
+};
+----
+
+Thus the lock may be on an 'extent', a contiguous sequence of bytes
+in a regular file; an 'flock wire', whatever to heck that is; or a
+portion of an inode. For a "plain" lock (or one with no type at all)
+the 'l_policy_data' field has zero length.
+
+