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

[doc/protocol.git] / ost_statfs.txt

diff --git a/ost_statfs.txt b/ost_statfs.txt
index dda2a61..16a6cec 100644 (file)
--- a/ost_statfs.txt
+++ b/ost_statfs.txt
@@ -2,12 +2,40 @@ RPC 13: OST_STATFS
 ~~~~~~~~~~~~~~~~~~
 [[ost-statfs-rpc]]
 
-OST_STATFS ('pb_opc' = 13) is an RPC that queries data about the
-underlying file system for a given OST. It's form and use are nearly
-identical to the MDS_STATFS RPC. Refer to <<mds-statfs-rpc>> for
-details. The only differences in OST_STATFS are that it has a distinct
-'pb_opc' value, it carries information about an OST (instead of an
-MDT).  The MDT may 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.
+OST_STATFS is an RPC that queries data about the underlying file
+system for a given OST.
+
+The OST_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
+OST_STATFS (13).
+
+The reply message conveys 'statfs' data when it succeeds, and an error
+code if it doesn't.
+
+.OST_STATFS Generic Packet Structure
+image::ost-statfs-generic.png["OST_STATFS Generic Packet Structure",height=100]
+
+//////////////////////////////////////////////////////////////////////
+The ost-statfs-generic.png diagram resembles this text art:
+
+       OST_STATFS:
+      --request------
+      | ptlrpc_body |
+      ---------------
+      --reply---------------------
+      | ptlrpc_body | obd_statfs |
+      ----------------------------
+//////////////////////////////////////////////////////////////////////
+
+'ptlrpc_body':: RPC descriptor. Only the 'pb_opc' value (OST_STATFS =
+41) is directly relevant to the OST_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.
+
+include::struct_obd_statfs.txt[]