LUDOC-296 protocol: Rearrange presentation to be more top-down

[doc/protocol.git] / mds_statfs.txt

diff --git a/mds_statfs.txt b/mds_statfs.txt
index 1a12e06..5b8263f 100644 (file)
--- a/mds_statfs.txt
+++ b/mds_statfs.txt
@@ -2,49 +2,31 @@ RPC 41: MDS_STATFS
 ~~~~~~~~~~~~~~~~~~
 [[mds-statfs-rpc]]
 
-MDS_STATFS is an RPC that queries data about the underlying file
-system for a given MDT.
-////
-It is generated in response to an explicit call for 'statfs'
-information from the VFS via the 'statfs(2)' function.
-////
-
-The MDS_STATFS request message is a so-called "empty" message in that
-it only has a buffer for the 'ptlrpc_body' with the 'pb_opc' value
-MDS_STATFS (41).
-
-The reply message conveys 'statfs' data when it succeeds, and an error
-code if it doesn't.
+MDS_STATFS ('pb_opc' = 41) is an RPC that queries data about the
+underlying file system for a given MDT. It's form and use are nearly
+identical to the OST_STATFS RPC. Refer to <<ost-statfs-rpc>> for
+details. The only differences in MDS_STATFS are that it has a distinct
+'pb_opc' value and it carries information about an MDT (instead of an
+OST).  An MDT will send regular OST_STATFS RPCs to each OST in order
+to keep its information about free space and utilization updated.
+That allows the MDS to make more optimal file allocation decisions.
 
 .MDS_STATFS Generic Packet Structure
+image::mds-statfs-generic.png["MDS_STATFS Generic Packet Structure",height=100]
+
+//////////////////////////////////////////////////////////////////////
+The mds-statfs-generic.png diagram resembles this text art:
 
-:frame: none
-:grid: none
-[width="50%", cols="2a"]
-|====
-| request
-[cols="1"]
-!===================
-! <<struct-ptlrpc-body,ptlrpc_body>> !
-!===================
-| reply
-[cols="2"]
-!===================
-! <<struct-ptlrpc-body,ptlrpc_body>> ! <<struct-obd_statfs,obd_statfs>> !
-!===================
-|====
+       MDS_STATFS:
+      --request------
+      | ptlrpc_body |
+      ---------------
+      --reply---------------------
+      | ptlrpc_body | obd_statfs |
+      ----------------------------
+//////////////////////////////////////////////////////////////////////
 
-'ptlrpc_body':: RPC descriptor. Only the 'pb_opc' value (MDS_STATFS =
-41) is directly relevant to the MDS_STATFS request message. The rest
-of the 'ptlrpc_body' fields handle generic information about the
-RPC, as discussed in <<struct-ptlrpc-body>>, including generic error
-conditions. In a normal reply ('pb_type' = PTL_RPC_MSG_REPLY) the
-'pb_status' field is 0.  The one error that can be returned in
-'pb_status' that is speficially from OST_STATFS' handling is -ENOMEM,
-which occurs if there is not enough memory to allocate a temporary
-buffer for the 'statfs' data.
+'ptlrpc_body':: RPC descriptor. See <<ptlrpc_body>>.
 
-'obd_statfs'::
-File system wide statistics corresponding to 'struct statfs' as well
-as Lustre-specific information. See <<struct-obd-statfs>> for a
-detailed discussion.
+'obd_statfs':: Statfs information about the target. See
+<struct-obd-statfs>>.