LUDOC-276 protocol: Document RPCs for setattr

[doc/protocol.git] / ldlm_enqueue.txt

diff --git a/ldlm_enqueue.txt b/ldlm_enqueue.txt
new file mode 100644 (file)
index 0000000..4c4cf7c
--- /dev/null
+++ b/ldlm_enqueue.txt
@@ -0,0 +1,87 @@
+Command 101: LDLM ENQUEUE - Enqueue a lock request
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[[ldlm-enqueue-rpc]]
+
+An RPC that implements distributed locking across the servers and
+clients. In its simplest form it just exchanges 'ldlm_request' and
+'ldlm_reply' descriptors of the desired and granted locks.
+
+.LDLM_ENQUEUE Generic Packet Structure
+image::ldlm-enqueue-generic.png["LDLM_ENQUEUE Generic Packet Structure",height=150]
+
+//////////////////////////////////////////////////////////////////////
+The ldlm-enqueue-generic.png diagram resembles this text
+art:
+
+       LDLM_ENQUEUE:
+      --request---------------------
+      | ptlrpc_body | ldlm_request |
+      ------------------------------
+      --reply---------------------
+      | ptlrpc_body | ldlm_reply |
+      ----------------------------
+      --extent lvb reply--------------------
+      | ptlrpc_body | ldlm_reply | ost_lvb |
+      --------------------------------------
+//////////////////////////////////////////////////////////////////////
+
+However, there are many variants to this RPCs. A lock request may signal
+an intention to carry out an operation once a lock has been
+granted. In the following example, the RPCs are fostering the 'intent'
+to look at how a resource is mapped to the available targets, so
+called 'layout' information.
+
+.LDLM_ENQUEUE Intent:Layout Generic Packet Structure
+image::ldlm-enqueue-intent-layout-generic.png["LDLM_ENQUEUE Intent:Layout Generic Packet Structure",height=100]
+
+//////////////////////////////////////////////////////////////////////
+The ldlm-enqueue-intent-layout-generic.png diagram resembles this text
+art:
+
+       LDLM_ENQUEUE:
+      --intent:layout request------------------------------------
+      | ptlrpc_body | ldlm_request |ldlm_intent | layout_intent |
+      lov_mds_md |
+      -----------------------------------------------------------
+      --intent:layout reply--------------------
+      | ptlrpc_body | ldlm_reply | lov_mds_md |
+      -----------------------------------------
+//////////////////////////////////////////////////////////////////////
+
+'ptlrpc_body'::
+RPC descriptor.
+
+'ldlm_request'::
+Description of the lock being requested. Which resource is the target,
+what lock is current, and what lock desired.
+
+'ldlm_intent'::
+Description of the intent being included with the lock request.
+
+'layout_intent'::
+Description of the layout information that is the subject of a layout
+intent.
+
+'ldlm_reply'::
+Resembling the 'ldlm_request', but in this case indicating what the
+LDLM actually granted as well as relevant policy data.
+
+Lock Value Block::
+A Lock Value Block (LVB) is included in the LDLM_ENQUEUE reply message
+when one of three things needs to be communicated back to the
+requester. The three alternatives are captured by the
+'ost_lvb'structure, the 'lov_mds_md' structure, and one other related
+to quotas (and not yet incorporated into this document). LDLM_ENQUEUE
+reply RPCs may include a zero length instance of an LVB.
+
+'ost_lvb'::
+An LVB to communicate attribute data for an extent associated with a
+resource on a lock. It is returned from an OST to a client requesting
+an extent lock.
+
+'lov_mds_md'::
+An LVB to communicate layout data associated with a resource. It is
+returned from an MDT to a client requesting a lock a lock with a
+layout intent. In an intent request (as opposed to a reply and as yet
+unimplemanted) it will modify the layout. It will not be included
+(zero length) in requests in current releases.