LUDOC-270 protocol: Update the outline and add support files

[doc/protocol.git] / ldlm.txt

diff --git a/ldlm.txt b/ldlm.txt
new file mode 100644 (file)
index 0000000..93906ea
--- /dev/null
+++ b/ldlm.txt
@@ -0,0 +1,159 @@
+The Lustre Distributed Lock Manager
+-----------------------------------
+[[ldlm]]
+
+The discussion of the LDLM is deferred for now. We'll get into it soon
+enough.
+
+LDLM Structures
+~~~~~~~~~~~~~~~
+
+Lock Modes
+^^^^^^^^^^
+
+----
+typedef enum {
+        LCK_MINMODE = 0,
+        LCK_EX      = 1,
+        LCK_PW      = 2,
+        LCK_PR      = 4,
+        LCK_CW      = 8,
+        LCK_CR      = 16,
+        LCK_NL      = 32,
+        LCK_GROUP   = 64,
+        LCK_COS     = 128,
+        LCK_MAXMODE
+} ldlm_mode_t;
+----
+
+LDLM Extent
+^^^^^^^^^^^
+
+----
+struct ldlm_extent {
+        __u64 start;
+        __u64 end;
+        __u64 gid;
+};
+----
+
+LDLM Flock Wire
+^^^^^^^^^^^^^^^
+
+----
+struct ldlm_flock_wire {
+        __u64 lfw_start;
+        __u64 lfw_end;
+        __u64 lfw_owner;
+        __u32 lfw_padding;
+        __u32 lfw_pid;
+};
+----
+
+LDLM Inode Bits
+^^^^^^^^^^^^^^^
+
+----
+struct ldlm_inodebits {
+        __u64 bits;
+};
+----
+
+LDLM Wire Policy Data
+^^^^^^^^^^^^^^^^^^^^^
+
+----
+typedef union {
+        struct ldlm_extent l_extent;
+        struct ldlm_flock_wire l_flock;
+        struct ldlm_inodebits l_inodebits;
+} ldlm_wire_policy_data_t;
+----
+
+Resource Descriptor
+^^^^^^^^^^^^^^^^^^^
+
+----
+struct ldlm_resource_desc {
+        ldlm_type_t lr_type;
+        __u32 lr_padding;       /* also fix lustre_swab_ldlm_resource_desc */
+        struct ldlm_res_id lr_name;
+};
+----
+
+The 'ldlm_type_t' is given by one of these values:
+----
+typedef enum {
+        LDLM_PLAIN     = 10,
+        LDLM_EXTENT    = 11,
+        LDLM_FLOCK     = 12,
+        LDLM_IBITS     = 13
+} ldlm_type_t;
+----
+
+Lock Descriptor
+^^^^^^^^^^^^^^^
+
+----
+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;
+};
+----
+
+Lock Request
+^^^^^^^^^^^^
+
+----
+#define LDLM_LOCKREQ_HANDLES 2
+struct ldlm_request {
+        __u32 lock_flags;
+        __u32 lock_count;
+        struct ldlm_lock_desc lock_desc;
+        struct lustre_handle lock_handle[LDLM_LOCKREQ_HANDLES];
+};
+----
+
+Lock Reply
+^^^^^^^^^^
+
+----
+struct ldlm_reply {
+        __u32 lock_flags;
+        __u32 lock_padding;     /* also fix lustre_swab_ldlm_reply */
+        struct ldlm_lock_desc lock_desc;
+        struct lustre_handle lock_handle;
+        __u64  lock_policy_res1;
+        __u64  lock_policy_res2;
+};
+----
+
+Lock Value Block
+^^^^^^^^^^^^^^^^
+
+A lock value block is part of reply messages from servers when an
+LDLM_ENQUEUE command has been issued. There are two varieties. Which
+is chosen depends on the target.
+
+----
+struct ost_lvb_v1 {
+    __u64        lvb_size;
+    obd_time     lvb_mtime;
+    obd_time     lvb_atime;
+    obd_time     lvb_ctime;
+    __u64        lvb_blocks;
+};
+struct ost_lvb {
+    __u64        lvb_size;
+    obd_time     lvb_mtime;
+    obd_time     lvb_atime;
+    obd_time     lvb_ctime;
+    __u64        lvb_blocks;
+    __u32        lvb_mtime_ns;
+    __u32        lvb_atime_ns;
+    __u32        lvb_ctime_ns;
+    __u32        lvb_padding;
+};
+----