ldlm_enqueue.txt

   1 RPC 101: LDLM ENQUEUE - Enqueue a lock request
   2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   3 [[ldlm-enqueue-rpc]]
   4
   5 An RPC that implements distributed locking across the servers and
   6 clients. In its simplest form it just exchanges 'ldlm_request' and
   7 'ldlm_reply' descriptors of the desired and granted locks.
   8
   9 .LDLM_ENQUEUE Generic Packet Structure
  10 image::ldlm-enqueue-generic.png["LDLM_ENQUEUE Generic Packet Structure",height=100]
  11
  12 //////////////////////////////////////////////////////////////////////
  13 The ldlm-enqueue-generic.png diagram resembles this text
  14 art:
  15
  16        LDLM_ENQUEUE:
  17       --request---------------------
  18       | ptlrpc_body | ldlm_request |
  19       ------------------------------
  20       --reply---------------------
  21       | ptlrpc_body | ldlm_reply |
  22       ----------------------------
  23 //////////////////////////////////////////////////////////////////////
  24
  25 However, there are many variants to this RPCs. A lock request may signal
  26 an intention to carry out an operation once a lock has been
  27 granted. In the following example, the RPCs are fostering the 'intent'
  28 to look at how a resource is mapped to the available targets, so
  29 called 'layout' information.
  30
  31 .LDLM_ENQUEUE Intent:Layout Generic Packet Structure
  32 image::ldlm-enqueue-intent-layout-generic.png["LDLM_ENQUEUE Intent:Layout Generic Packet Structure",height=100]
  33
  34 //////////////////////////////////////////////////////////////////////
  35 The ldlm-enqueue-intent-layout-generic.png diagram resembles this text
  36 art:
  37
  38        LDLM_ENQUEUE:
  39       --intent:layout request------------------------------------
  40       | ptlrpc_body | ldlm_request |ldlm_intent | layout_intent |
  41       lov_mds_md |
  42       -----------------------------------------------------------
  43       --intent:layout reply--------------------
  44       | ptlrpc_body | ldlm_reply | lov_mds_md |
  45       -----------------------------------------
  46 //////////////////////////////////////////////////////////////////////
  47
  48 And in this example the intent is to get attribute information.
  49
  50 .LDLM_ENQUEUE Intent:Getattr Generic Packet Structure
  51 image::ldlm-enqueue-intent-getattr-generic.png["LDLM_ENQUEUE Intent:Getattr Generic Packet Structure",height=150]
  52
  53 //////////////////////////////////////////////////////////////////////
  54 The ldlm-enqueue-intent-getattr-generic.png diagram resembles this text
  55 art:
  56
  57        LDLM_ENQUEUE:
  58       --intent:getattr request-------------------------------
  59       | ptlrpc_body | ldlm_request | ldlm_intent | mdt_body |
  60       lustre_capa |name |
  61       -------------------------------------------------------
  62       --intent:getattr reply--------------------------
  63       | ptlrpc_body | ldlm_reply | mdt_body | mdt_md |
  64       ------------------------------------------------
  65       --intent:lvb reply--------------------
  66       | ptlrpc_body | ldlm_reply | ost_lvb |
  67       --------------------------------------
  68 //////////////////////////////////////////////////////////////////////
  69
  70 Here is another example of an intent, in this case the 'getxattr' intent.
  71
  72 .LDLM_ENQUEUE Intent:Getxattr Generic Packet Structure
  73 image::ldlm-enqueue-intent-getxattr-generic.png["LDLM_ENQUEUE Intent:Getxattr Generic Packet Structure",height=125]
  74
  75 //////////////////////////////////////////////////////////////////////
  76 The ldlm-enqueue-intent-getxattr-generic.png diagram resembles this text
  77 art:
  78
  79        LDLM_ENQUEUE:
  80       --intent:getxattr request------------------------------------
  81       | ptlrpc_body | ldlm_request |ldlm_intent | mdt_body | capa |
  82       -------------------------------------------------------------
  83       --intent:getxattr reply----------------------------------------
  84       | ptlrpc_body | ldlm_reply | mdt_body | lov_mds_md | ACL data |
  85       | EA data | EA vals | EA lens |
  86       ---------------------------------------------------------------
  87 //////////////////////////////////////////////////////////////////////
  88
  89 'ptlrpc_body'::
  90 RPC descriptor.
  91
  92 'ldlm_request'::
  93 Description of the lock being requested. Which resource is the target,
  94 what lock is current, and what lock desired.
  95
  96 'ldlm_intent'::
  97 Description of the intent being included with the lock request.
  98
  99 'layout_intent'::
 100 Description of the layout information that is the subject of a layout
 101 intent.
 102
 103 'mdt_body'::
 104 In a request, an indication (in the 'mbo_valid' field) of what
 105 attributes the requester would like. In a reply, (again based on
 106 'mbo_valid') the values being returned.
 107
 108 'lustre_capa'::
 109 So called "capabilities" structure. This is deprecated in recent
 110 versions of Lustre, and commonly appears in the packet header as a zero
 111 length buffer.
 112
 113 'name'::
 114 A text field supplying the name of the desired resource.
 115
 116 'ldlm_reply'::
 117 Resembling the 'ldlm_request', but in this case indicating what the
 118 LDLM actually granted as well as relevant policy data.
 119
 120 'mdt_md'::
 121 Layout data for the resource. This buffer is optional and will appear
 122 as zero length in some packets.
 123
 124 'mdt_body'::
 125 Metadata about a given resource.
 126
 127 'ACL data'::
 128 Access Control List data associated with a resource.
 129
 130 'EA data'::
 131 The names of any extended attributes associated with the resource. The
 132 names are null-terminated strings concatenated into a single sequnce.
 133
 134 'EA vals'::
 135 A block of data concatenating the values for the extended attributes
 136 listed in "EA vals".
 137
 138 'EA lens'::
 139 The sizes of the extended attirbute values. This is a sequence of
 140 32-bit unsigned integers, one for each extended
 141 attribute. The sizes give the length of the corresponding extended
 142 attribute in the "EA vals" block of data. Thus the sum of those sizes
 143 equals the length of the "EA vals".
 144
 145 Lock Value Block::
 146 A Lock Value Block (LVB) is included in the LDLM_ENQUEUE reply message
 147 when one of three things needs to be communicated back to the
 148 requester. The three alternatives are captured by the
 149 'ost_lvb'structure, the 'lov_mds_md' structure, and one other related
 150 to quotas (and not yet incorporated into this document). LDLM_ENQUEUE
 151 reply RPCs may include a zero length instance of an LVB.
 152
 153 'ost_lvb'::
 154 An LVB to communicate attribute data for an extent associated with a
 155 resource on a lock. It is returned from an OST to a client requesting
 156 an extent lock.
 157
 158 'lov_mds_md'::
 159 An LVB to communicate layout data associated with a resource. It is
 160 returned from an MDT to a client requesting a lock a lock with a
 161 layout intent. In an intent request (as opposed to a reply and as yet
 162 unimplemanted) it will modify the layout. It will not be included
 163 (zero length) in requests in current releases.