-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=100]
+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 |
----------------------------
//////////////////////////////////////////////////////////////////////
-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 |
-----------------------------------------------------------
+ | lov_mds_md |
+ --------------
+//////////////////////////////////////////////////////////////////////
+
+'ptlrpc_body'::
+RPC descriptor. See <<struct-ptlrpc-body>>.
+
+'ldlm_request'::
+The LDLM Request structure. See <<struct-ldlm-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 |
-----------------------------------------
//////////////////////////////////////////////////////////////////////
+'ptlrpc_body'::
+RPC descriptor. See <<struct-ptlrpc-body>>.
+
+'ldlm_reply'::
+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
+to quotas (and not yet incorporated into this document). LDLM_ENQUEUE
+reply RPCs may include a zero length instance of an LVB.
+****
+
+'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 Generic Packet Structure
-image::ldlm-enqueue-intent-getattr-generic.png["LDLM_ENQUEUE Intent:Getattr Generic Packet Structure",height=150]
+.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-generic.png diagram resembles this text
+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 |
-------------------------------------------------------
+ | 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 Generic Packet Structure
-image::ldlm-enqueue-intent-getxattr-generic.png["LDLM_ENQUEUE Intent:Getxattr Generic Packet Structure",height=125]
+.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-generic.png diagram resembles this text
+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 | capa |
- -------------------------------------------------------------
- --intent:getxattr reply----------------------------------------
- | ptlrpc_body | ldlm_reply | mdt_body | lov_mds_md | ACL data |
- | EA data | EA vals | EA lens |
- ---------------------------------------------------------------
+ --intent:getxattr request-----------------------------
+ | ptlrpc_body | ldlm_request |ldlm_intent | mdt_body |
+ ------------------------------------------------------
+ | lustre_capa |
+ ---------------
//////////////////////////////////////////////////////////////////////
'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.
-
-'layout_intent'::
-Description of the layout information that is the subject of a layout
-intent.
+The LDLM Intent structure. See <<struct-ldlm-intent>>.
'mdt_body'::
-In a request, an indication (in the 'mbo_valid' field) of what
-attributes the requester would like. In a reply, (again based on
-'mbo_valid') the values being returned.
+Metadata about the resource. See <<struct-mdt-body>>.
'lustre_capa'::
-So called "capabilities" structure. This is deprecated in recent
-versions of Lustre, and commonly appears in the packet header as a zero
-length buffer.
+A "capabilities" structure. See <<struct-lustre-capa>>.
-'name'::
-A text field supplying the name of the desired resource.
+.LDLM_ENQUEUE Intent:Getxattr Reply Packet Structure
+image::ldlm-enqueue-intent-getxattr-reply.png["LDLM_ENQUEUE Intent:Getxattr Reply Packet Structure",height=50]
-'ldlm_reply'::
-Resembling the 'ldlm_request', but in this case indicating what the
-LDLM actually granted as well as relevant policy data.
+//////////////////////////////////////////////////////////////////////
+The ldlm-enqueue-intent-getxattr-reply.png diagram resembles this text
+art:
-'mdt_md'::
-Layout data for the resource. This buffer is optional and will appear
-as zero length in some packets.
+ 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 a given resource.
+Metadata about the resource. See <<struct-mdt-body>>.
+
+'lov_mds_md'::
+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 sequnce.
+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 attirbute values. This is a sequence of
+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".
-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.
git://git.whamcloud.com / doc / protocol.git / blobdiff