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 include::struct_ldlm_request.txt[]
  93
  94 include::struct_ldlm_intent.txt[]
  95
  96 include::struct_layout_intent.txt[]
  97
  98 'mdt_body'::
  99 In a request, an indication (in the 'mbo_valid' field) of what
 100 attributes the requester would like. In a reply, (again based on
 101 'mbo_valid') the values being returned. <<struct-mdt-body>>
 102
 103 'lustre_capa'::
 104 So called "capabilities" structure. This is deprecated in recent
 105 versions of Lustre, and commonly appears in the packet header as a zero
 106 length buffer.
 107
 108 'name'::
 109 A text field supplying the name of the desired resource.
 110
 111 include::struct_ldlm_reply.txt[]
 112
 113 'ACL data'::
 114 Access Control List data associated with a resource.
 115
 116 'EA data'::
 117 The names of any extended attributes associated with the resource. The
 118 names are null-terminated strings concatenated into a single sequnce.
 119
 120 'EA vals'::
 121 A block of data concatenating the values for the extended attributes
 122 listed in "EA vals".
 123
 124 'EA lens'::
 125 The sizes of the extended attirbute values. This is a sequence of
 126 32-bit unsigned integers, one for each extended
 127 attribute. The sizes give the length of the corresponding extended
 128 attribute in the "EA vals" block of data. Thus the sum of those sizes
 129 equals the length of the "EA vals".
 130
 131 Lock Value Block::
 132 A Lock Value Block (LVB) is included in the LDLM_ENQUEUE reply message
 133 when one of three things needs to be communicated back to the
 134 requester. The three alternatives are captured by the
 135 'ost_lvb' structure, the 'lov_mds_md' structure, and one other related
 136 to quotas (and not yet incorporated into this document). LDLM_ENQUEUE
 137 reply RPCs may include a zero length instance of an LVB.
 138
 139 include::struct_ost_lvb.txt[]
 140
 141 include::struct_lov_mds_md.txt[]
 142