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 <<struct-ptlrpc-body>>.
  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. <<struct-ldlm-request>>
  95
  96 'ldlm_intent'::
  97 Description of the intent being included with the lock request.
  98 <<struct-ldlm-intent>>
  99
 100 'layout_intent'::
 101 Description of the layout information that is the subject of a layout
 102 intent.
 103
 104 'mdt_body'::
 105 In a request, an indication (in the 'mbo_valid' field) of what
 106 attributes the requester would like. In a reply, (again based on
 107 'mbo_valid') the values being returned. <<struct-mdt-body>>
 108
 109 'lustre_capa'::
 110 So called "capabilities" structure. This is deprecated in recent
 111 versions of Lustre, and commonly appears in the packet header as a zero
 112 length buffer.
 113
 114 'name'::
 115 A text field supplying the name of the desired resource.
 116
 117 'ldlm_reply'::
 118 Resembling the 'ldlm_request', but in this case indicating what the
 119 LDLM actually granted as well as relevant policy data. <<struct-ldlm-reply>>
 120
 121 'mdt_body'::
 122 Metadata about a given resource. <<struct-mdt-body>>
 123
 124 'ACL data'::
 125 Access Control List data associated with a resource.
 126
 127 'EA data'::
 128 The names of any extended attributes associated with the resource. The
 129 names are null-terminated strings concatenated into a single sequnce.
 130
 131 'EA vals'::
 132 A block of data concatenating the values for the extended attributes
 133 listed in "EA vals".
 134
 135 'EA lens'::
 136 The sizes of the extended attirbute values. This is a sequence of
 137 32-bit unsigned integers, one for each extended
 138 attribute. The sizes give the length of the corresponding extended
 139 attribute in the "EA vals" block of data. Thus the sum of those sizes
 140 equals the length of the "EA vals".
 141
 142 Lock Value Block::
 143 A Lock Value Block (LVB) is included in the LDLM_ENQUEUE reply message
 144 when one of three things needs to be communicated back to the
 145 requester. The three alternatives are captured by the
 146 'ost_lvb' structure, the 'lov_mds_md' structure, and one other related
 147 to quotas (and not yet incorporated into this document). LDLM_ENQUEUE
 148 reply RPCs may include a zero length instance of an LVB.
 149
 150 'ost_lvb'::
 151 An LVB to communicate attribute data for an extent associated with a
 152 resource on a lock. It is returned from an OST to a client requesting
 153 an extent lock. <<struct-ost-lvb>>
 154
 155 'lov_mds_md'::
 156 Layout data associated with a resource. It is
 157 returned from an MDT to a client requesting a lock a lock with a
 158 layout intent. In an intent request (as opposed to a reply and as yet
 159 unimplemanted) it will modify the layout. It will not be included
 160 (zero length) in requests in current releases. <<struct-lov-mds-md>>