-Command 101: LDLM ENQUEUE - Enqueue a lock request
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+RPC 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]
+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.
+
+.LDLM_ENQUEUE Request Packet Structure
+image::ldlm-enqueue-request.png["LDLM_ENQUEUE Request Packet Structure",height=50]
//////////////////////////////////////////////////////////////////////
-The ldlm-enqueue-generic.png diagram resembles this text
+The ldlm-enqueue-request.png diagram resembles this text
art:
LDLM_ENQUEUE:
--request---------------------
| ptlrpc_body | ldlm_request |
------------------------------
+//////////////////////////////////////////////////////////////////////
+
+'ptlrpc_body'::
+RPC descriptor. See <<struct-ptlrpc-body>>.
+
+include::struct_ldlm_request.txt[]
+
+.LDLM_ENQUEUE Reply Packet Structure
+image::ldlm-enqueue-reply.png["LDLM_ENQUEUE Reply Packet Structure",height=50]
+
+//////////////////////////////////////////////////////////////////////
+The ldlm-enqueue-reply.png diagram resembles this text
+art:
+
+ LDLM_ENQUEUE:
--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'
+'ptlrpc_body'::
+RPC descriptor. See <<struct-ptlrpc-body>>.
+
+include::struct_ldlm_reply.txt[]
+
+****
+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]
+.LDLM_ENQUEUE Intent:Layout Request Packet Structure
+image::ldlm-enqueue-intent-layout-request.png["LDLM_ENQUEUE Intent:Layout Request Packet Structure",height=50]
//////////////////////////////////////////////////////////////////////
-The ldlm-enqueue-intent-layout-generic.png diagram resembles this text
+The ldlm-enqueue-intent-layout-request.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 |
- -----------------------------------------
+ | lov_mds_md |
+ --------------
//////////////////////////////////////////////////////////////////////
'ptlrpc_body'::
-RPC descriptor.
+RPC descriptor. See <<struct-ptlrpc-body>>.
'ldlm_request'::
-Description of the lock being requested. Which resource is the target,
-what lock is current, and what lock desired.
+The LDLM Request structure. See <<struct-ldlm-request>>.
-'ldlm_intent'::
-Description of the intent being included with the lock request.
+include::struct_ldlm_intent.txt[]
+
+include::struct_layout_intent.txt[]
+
+include::struct_lov_mds_md.txt[]
+
+.LDLM_ENQUEUE Intent:Layout Reply Packet Structure
+image::ldlm-enqueue-intent-layout-reply.png["LDLM_ENQUEUE Intent:Layout Reply Packet Structure",height=50]
+
+//////////////////////////////////////////////////////////////////////
+The ldlm-enqueue-intent-layout-reply.png diagram resembles this text
+art:
+
+ LDLM_ENQUEUE:
+ --intent:layout reply--------------------
+ | ptlrpc_body | ldlm_reply | lov_mds_md |
+ -----------------------------------------
+//////////////////////////////////////////////////////////////////////
-'layout_intent'::
-Description of the layout information that is the subject of a layout
-intent.
+'ptlrpc_body'::
+RPC descriptor. See <<struct-ptlrpc-body>>.
'ldlm_reply'::
-Resembling the 'ldlm_request', but in this case indicating what the
-LDLM actually granted as well as relevant policy data.
+The LDLM Reply structure. See <<struct-ldlm-reply>>.
+****
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
+'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'::
+The LOV MDS MD structure. See <<struct-lov-mds-md>>.
+
+And in this example the intent is to get attribute information.
+
+.LDLM_ENQUEUE Intent:Getattr Request Packet Structure
+image::ldlm-enqueue-intent-getattr-request.png["LDLM_ENQUEUE Intent:Getattr Request Packet Structure",height=50]
+
+//////////////////////////////////////////////////////////////////////
+The ldlm-enqueue-intent-getattr-request.png diagram resembles this text
+art:
+
+ LDLM_ENQUEUE:
+ --intent:getattr request-------------------------------
+ | ptlrpc_body | ldlm_request | ldlm_intent | mdt_body |
+ -------------------------------------------------------
+ | lustre_capa | name |
+ ----------------------
+//////////////////////////////////////////////////////////////////////
+
+'ptlrpc_body'::
+RPC descriptor. See <<struct-ptlrpc-body>>.
+
+'ldlm_request'::
+The LDLM Request structure. See <<struct-ldlm-request>>.
+
+'ldlm_intent'::
+The LDLM Intent structure. See <<struct-ldlm-intent>>.
+
+'mdt_body'::
+Metadata about the resource. See <<struct-mdt-body>>.
+
+'lustre_capa'::
+A "capabilities" structure. See <<struct-lustre-capa>>.
+
+'name'::
+A text field supplying the name of the desired resource.
+
+.LDLM_ENQUEUE Intent:Getattr Reply Packet Structure
+image::ldlm-enqueue-intent-getattr-reply.png["LDLM_ENQUEUE Intent:Getattr Reply Packet Structure",height=50]
+
+//////////////////////////////////////////////////////////////////////
+The ldlm-enqueue-intent-getattr-reply.png diagram resembles this text
+art:
+
+ LDLM_ENQUEUE:
+ --intent:getattr reply--------------------------
+ | ptlrpc_body | ldlm_reply | mdt_body | mdt_md |
+ ------------------------------------------------
+//////////////////////////////////////////////////////////////////////
+
+'ptlrpc_body'::
+RPC descriptor. See <<struct-ptlrpc-body>>.
+
+'ldlm_reply'::
+The LDLM Reply structure. See <<struct-ldlm-reply>>.
+
+'mdt_body'::
+Metadata about the resource. See <<struct-mdt-body>>.
+
+'mdt_md'::
+Layout data for the resource. This buffer is optional and will appear
+as zero length in some packets.
+
+.LDLM_ENQUEUE Intent:Lvb Reply Packet Structure
+image::ldlm-enqueue-intent-lvb-reply.png["LDLM_ENQUEUE Intent:Lvb Reply Packet Structure",height=50]
+
+//////////////////////////////////////////////////////////////////////
+The ldlm-enqueue-intent-lvb-reply.png diagram resembles this text
+art:
+
+ LDLM_ENQUEUE:
+ --intent:lvb reply--------------------
+ | ptlrpc_body | ldlm_reply | ost_lvb |
+ --------------------------------------
+//////////////////////////////////////////////////////////////////////
+
+'ptlrpc_body'::
+RPC descriptor. See <<struct-ptlrpc-body>>.
+
+'ldlm_reply'::
+The LDLM Reply structure. See <<struct-ldlm-reply>>.
+
+include::struct_ost_lvb.txt[]
+
+Here is another example of an intent, in this case the 'getxattr' intent.
+
+.LDLM_ENQUEUE Intent:Getxattr Request Packet Structure
+image::ldlm-enqueue-intent-getxattr-request.png["LDLM_ENQUEUE Intent:Getxattr Request Packet Structure",height=75]
+
+//////////////////////////////////////////////////////////////////////
+The ldlm-enqueue-intent-getxattr-request.png diagram resembles this text
+art:
+
+ LDLM_ENQUEUE:
+ --intent:getxattr request-----------------------------
+ | ptlrpc_body | ldlm_request |ldlm_intent | mdt_body |
+ ------------------------------------------------------
+ | lustre_capa |
+ ---------------
+//////////////////////////////////////////////////////////////////////
+
+'ptlrpc_body'::
+RPC descriptor. See <<struct-ptlrpc-body>>.
+
+'ldlm_request'::
+The LDLM Request structure. See <<struct-ldlm-request>>.
+
+'ldlm_intent'::
+The LDLM Intent structure. See <<struct-ldlm-intent>>.
+
+'mdt_body'::
+Metadata about the resource. See <<struct-mdt-body>>.
+
+'lustre_capa'::
+A "capabilities" structure. See <<struct-lustre-capa>>.
+
+.LDLM_ENQUEUE Intent:Getxattr Reply Packet Structure
+image::ldlm-enqueue-intent-getxattr-reply.png["LDLM_ENQUEUE Intent:Getxattr Reply Packet Structure",height=50]
+
+//////////////////////////////////////////////////////////////////////
+The ldlm-enqueue-intent-getxattr-reply.png diagram resembles this text
+art:
+
+ LDLM_ENQUEUE:
+ --intent:getxattr reply----------------------------------------
+ | ptlrpc_body | ldlm_reply | mdt_body | lov_mds_md | ACL data |
+ | EA data | EA vals | EA lens |
+ ---------------------------------------------------------------
+//////////////////////////////////////////////////////////////////////
+
+'ptlrpc_body'::
+RPC descriptor. See <<struct-ptlrpc-body>>.
+
+'ldlm_reply'::
+The LDLM Reply structure. See <<struct-ldlm-reply>>.
+
+'mdt_body'::
+Metadata about the resource. See <<struct-mdt-body>>.
'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.
+The LOV MDS MD structure. See <<struct-lov-mds-md>>.
+
+'ACL data'::
+Access Control List data associated with a resource.
+
+'EA data'::
+The names of any extended attributes associated with the resource. The
+names are null-terminated strings concatenated into a single sequence.
+
+'EA vals'::
+A block of data concatenating the values for the extended attributes
+listed in "EA vals".
+
+'EA lens'::
+The sizes of the extended attribute values. This is a sequence of
+32-bit unsigned integers, one for each extended
+attribute. The sizes give the length of the corresponding extended
+attribute in the "EA vals" block of data. Thus the sum of those sizes
+equals the length of the "EA vals".
+
git://git.whamcloud.com / doc / protocol.git / blobdiff