LUDOC-297 protocol: Update protocol document

[doc/protocol.git] / struct_ldlm_request.txt

diff --git a/struct_ldlm_request.txt b/struct_ldlm_request.txt
index 3dc355a..55d94b6 100644 (file)
--- a/struct_ldlm_request.txt
+++ b/struct_ldlm_request.txt
@@ -66,8 +66,9 @@ interpreted. The flags are:
 The 'lock_count' field represents how many requests are queued on this
 resource.
 
+.LDLM Lock Descriptor
 [[struct-ldlm-lock-desc]]
-
+****
 The lock descriptor conveys the specific details about a particular
 lock being requested or granted. It appears in
 <<struct-ldlm-request>>.
@@ -81,9 +82,11 @@ struct ldlm_lock_desc {
         ldlm_wire_policy_data_t l_policy_data;
 };
 ----
+****
 
+.LDLM Resource Descriptor
 [[struct-ldlm-resource-desc]]
-
+****
 The resource descriptor identifies the individual resource that is
 being locked, along with what sort of thing it is.
 
@@ -95,8 +98,8 @@ struct ldlm_resource_desc {
         struct ldlm_res_id lr_name;
 };
 ----
+****
 
-[[ldlm-type-t]]
 The 'lr_type' field identifies one of the four types of lock that
 might be placed on a resource. A "plain" lock type just locks a
 particular resource. An "extent" lock type only locks a contiguous
@@ -111,6 +114,9 @@ resource separately.  See also <<ldlm-wire-policy-data-t>>.  A lock
 descriptor may also have no type at all, in which case the 'lr_type'
 field is 0, meaning "no lock".
 
+.LDLM Type
+[[ldlm-type-t]]
+****
 [source,c]
 ----
 enum {
@@ -120,11 +126,15 @@ enum {
         LDLM_IBITS     = 13,
 } ldlm_type_t;
 ----
+****
 
-[[struct-ldlm-res-id]]
-The 'lr_name' field identifies (by name) the resource(s) that are the
-objects of the locking operation.
+The 'lr_name' field of the 'ldlm_resource_desc' (See
+<<struct-ldlm-res-id>>) field identifies the resource that is the
+object of the locking operation.
 
+.LDLM Resource ID
+[[struct-ldlm-res-id]]
+****
 [source,c]
 ----
 struct ldlm_res_id {
@@ -132,16 +142,18 @@ struct ldlm_res_id {
 };
 ----
 
-The 'name' array holds identifiers for the resource in question. Those
-identifiers may be the elements of a 'struct lu_fid' file ID, or they
-may be other uniquely identifying values for the resource. See
-<<struct-lu-fid>>.
+The 'name' identifies for the resource in question. It may be a FID
+(See <<struct-lu-fid>>), or they may be other uniquely identifying
+values for the resource.
+****
 
-[[ldlm-mode-t]]
 The 'l_req_mode' and 'l_granted_mode' fields give the kind of lock
 being requested and the kind of lock that has been granted. The field
 values are:
 
+.LDLM Mode
+[[ldlm-mode-t]]
+****
 [source,c]
 ----
 enum {
@@ -159,17 +171,21 @@ enum {
 Despite the fact that the lock modes are not overlapping, these lock
 modes are exclusive.  In addition the mode value 0 is the MINMODE,
 i.e. no lock at all.
+****
 
-In a request 'l_req_mode' is the value actually being requested and
-'l_granted_mode' is the value that currently is in place on for the
-requester. In a reply the 'l_req_mode' may be modified if more or
-fewer privileges were granted than requested, and the
-'l_granted_mode' is what has, in fact, been granted.
+In an 'ldlm_request' structure the 'l_req_mode' field is the value
+actually being requested and the 'l_granted_mode' field is the value
+that currently is in place on for the requester. In an 'ldlm_reply'
+the 'l_req_mode' field may be modified if more or fewer privileges
+were granted than requested, and the 'l_granted_mode' is what has, in
+fact, been granted.
 
-[[ldlm-wire-policy-data-t]]
 The 'l_policy_data' field gives the kind of resource being
 requested/granted. It is a union of these struct definitions:
 
+.LDLM Wire Policy Data
+[[ldlm-wire-policy-data-t]]
+****
 [source,c]
 ----
 typedef union {
@@ -178,8 +194,11 @@ typedef union {
         struct ldlm_inodebits l_inodebits;
 } ldlm_wire_policy_data_t;
 ----
+****
 
+.LDLM Extent
 [[struct-ldlm-extent]]
+****
 [source,c]
 ----
 struct ldlm_extent {
@@ -188,8 +207,11 @@ struct ldlm_extent {
         __u64 gid;
 };
 ----
+****
 
+.LDLM Flock Wire
 [[struct-ldlm-flock-wire]]
+****
 [source,c]
 ----
 struct ldlm_flock_wire {
@@ -200,14 +222,18 @@ struct ldlm_flock_wire {
         __u32 lfw_pid;
 };
 ----
+****
 
+.LDLM Inodebits
 [[struct-ldlm-inodebits]]
+****
 [source,c]
 ----
 struct ldlm_inodebits {
         __u64 bits;
 };
 ----
+****
 
 Thus the lock may be on an 'extent', a contiguous sequence of bytes
 in a regular file; an 'flock wire', whatever to heck that is; or a