LUDOC-296 protocol: remove internal details from descriptions

[doc/protocol.git] / obd_statfs.txt

diff --git a/obd_statfs.txt b/obd_statfs.txt
index 2b25d8b..1559099 100644 (file)
--- a/obd_statfs.txt
+++ b/obd_statfs.txt
@@ -42,7 +42,7 @@ system:
 [options="header"]
 |====
 | f_type                     | value
-| EXT?_SUPER_MAGIC (ldiskfs) | 0xEF53
+| EXT4_SUPER_MAGIC (ldiskfs) | 0xEF53
 | ZFS_SUPER_MAGIC            | 0x2fc12fc1
 |====
 
@@ -52,7 +52,9 @@ units of os_bsize.
 The 'os_bfree' field is the number of blocks not currently in use.
 
 The 'os_bavail' is the number of blocks available to be allocated to
-new files.
+new files.  The number of available blocks is typically lower than
+the number of free blocks due to <<grant>> and blocks reserved for
+target internal usage such as metadata.
 
 The 'os_files' field is the total number of files on the target, both
 allocated and free.  For some OSD types this is a static number, and
@@ -66,15 +68,15 @@ space changes.
 
 The 'os_fsid' is intended to be the target backing device UUID in
 ASCII format.  The current osd-ldiskfs and osd-zfs implementations
-don't fill this in.
+do not fill this field in.
 
 The 'os_bsize' field is the block size in bytes. This is for computing
-the total, free, and available space in combination with os_blocks,
-os_bfree, and os_bavail respectively.  It does not necessarily
+the total, free, and available space in combination with 'os_blocks',
+'os_bfree', and 'os_bavail' respectively.  It does not necessarily
 represent the minimum or optimal IO size.
 
 The 'os_namelen' field gives the maximum name length for files on the
-back-end file system.
+back-end file system in bytes.
 
 The 'os_maxbytes' field is the maximum size of a single object
 (i.e. the maximum byte offset that can be written to).  This is the
@@ -95,9 +97,10 @@ file system. It can be:
 In normal operation the 'os_state' value is returned as 0x0.  If the
 back-end file system has a RAID configuration that is degraded or
 rebuilding the state is returned with the OS_STATE_DEGRADED (0x1) flag
-set. If the file system has been set to read-only, for whatever
-reason, then the state is returned with the OS_STATE_READONLY (0x2)
-flag set, for example if it was explicitly mounted read-only, or
+set. If the file system has been set to read-only, either manually at
+mount or automatcially due to detected corruption of the underlying
+target filesystem, then 'os_state' is returned with OS_STATE_READONLY (0x2)
+set, for example if it was explicitly mounted read-only, or
 corruption has been detected at runtime in the backing filesystem.
 
 The 'os_fprecreated' field counts the number of pre-created objects