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.

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-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 |
      ----------------------------
//////////////////////////////////////////////////////////////////////

'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 Request Packet Structure
image::ldlm-enqueue-intent-layout-request.png["LDLM_ENQUEUE Intent:Layout Request Packet Structure",height=50]

//////////////////////////////////////////////////////////////////////
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 |
      --------------
//////////////////////////////////////////////////////////////////////

'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 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'::
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".