Subject: [nfsv4] [PATCH] Clarify use of pNFS and stateids

From: Thomas Haynes <[email-masked]>
Date: Fri, 25 Apr 2014 16:37:31 -0700

From: loghyr <[email-masked]>

This is item #3 in the issues file. I scoured the mailing list
to pick up the thread in November.

As suggested on the WG ML, I've moved ALLOCATE and DEALLOCATE
out of the allowed DS operations. I've also explained that
these need to be atomic from the MDS.

I've clarified that the exeception to rule #16 is
a NFSv4.2 MDS working with a downrev DS.

Added some little nits as suggested by Trond.

Signed-off-by: Thomas Haynes <[email-masked]>
Suggested-by: Christoph Hellwig <[email-masked]>
---
 Makefile                 |  1 +
 nfsv42_middle_minorv.xml |  9 ++++++++-
 nfsv42_middle_pnfs.xml   | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 nfsv42_middle_space.xml  | 35 +++++++++++++++++++++--------------
 4 files changed, 76 insertions(+), 15 deletions(-)
 create mode 100644 nfsv42_middle_pnfs.xml

diff --git a/Makefile b/Makefile
index 9ba2101..1139b93 100755
--- a/Makefile
+++ b/Makefile
@@ -428,6 +428,7 @@ IDXMLSRC_BASE = \
 	${DOC_PREFIX}_middle_start.xml \
 	${DOC_PREFIX}_middle_introduction.xml \
 	${DOC_PREFIX}_middle_minorv.xml \
+	${DOC_PREFIX}_middle_pnfs.xml \
 	${DOC_PREFIX}_middle_copy.xml \
 	${DOC_PREFIX}_middle_advise.xml \
 	${DOC_PREFIX}_middle_sparse.xml \
diff --git a/nfsv42_middle_minorv.xml b/nfsv42_middle_minorv.xml
index 064ec47..a25813d 100644
--- a/nfsv42_middle_minorv.xml
+++ b/nfsv42_middle_minorv.xml
@@ -209,10 +209,17 @@
       </t>
 
       <t>
-        A client MUST NOT attempt to use a stateid, filehandle, or
+        A client SHOULD NOT attempt to use a stateid, filehandle, or
         similar returned object from the COMPOUND procedure with minor
         version X for another COMPOUND procedure with minor version Y,
         where X != Y.
+          <vspace blankLines="1"/>
+        Note that this is a "SHOULD" and not a "MUST" because of the
+        possibility that a NFSv4.2 metadata server could hand out a
+        layout to a NFSv4.1 storage device. Section 13.9.1 of
+        <xref target='RFC5661' /> discusses how the client gets
+        a stateid from the metadata server to present to a storage
+        device.
       </t>
     </list>
   </t>
diff --git a/nfsv42_middle_pnfs.xml b/nfsv42_middle_pnfs.xml
new file mode 100644
index 0000000..7fde106
--- /dev/null
+++ b/nfsv42_middle_pnfs.xml
@@ -0,0 +1,46 @@
+<!-- Copyright (C) The IETF Trust (2014) -->
+<!-- Copyright (C) The Internet Society (2014) -->
+
+<section anchor="ss:pnfs" title="pNFS considerations for New Operations">
+  <section anchor="ss:pnfs:atom" title="Atomicty for ALLOCATE and DEALLOCATE">
+    <t>
+      Both ALLOCATE (see <xref target='op:allocate' />) and
+      DEALLOCATE (see <xref target='op:deallocate' />) are sent to the
+      metadata server, which is responsible for coordinating the
+      changes onto the storage devices. In particular, both operations
+      must either fully succeed or fail, it cannot be the case that
+      one storage device succeeds whilst another fails.
+    </t>
+  </section>
+
+  <section anchor="ss:pnfs:flt" title="NFSv4.2 as a Storage Protocol in pNFS: the File Layout Type">
+    <t>
+      A file layout provided by a NFSv4.2 server may refer either to a DS
+      that only implements NFSv4.1 as specified in <xref target='RFC5661' />,
+      or to a DS that implements additions from NFSv4.2, in which
+      case the rules in <xref target='ss:pnfs:ops' /> apply. As the File
+      Layout Type does not provide a means for informing the client as
+      to which minor version a particular DS is providing, it will have
+      to negotiate this via the normal RPC semantics of major and minor
+      version discovery.
+    </t>
+
+    <section anchor="ss:pnfs:ops" title="Operations Sent to NFSv4.2 Data Servers">
+      <t>
+        In addition to the commands listed in <xref target='RFC5661' />,
+        NFSv4.2 data servers MAY accept a COMPOUND containing the following
+        additional operations: READ_PLUS (see
+        <xref target='op:read_plus' />), WRITE_SAME (see
+        <xref target='op:write_same' />), and SEEK (see
+        <xref target='op:seek' />), which will be treated like the
+        subset specified as "Operations Sent to NFSv4.1 Data Servers"
+        in Section 13.6 of <xref target='RFC5661' />.
+      </t>
+
+      <t>
+        Additional details on the implementation of these operations in a pNFS
+        context are documented in the operation specific sections.
+      </t>
+    </section>
+  </section>
+</section>
diff --git a/nfsv42_middle_space.xml b/nfsv42_middle_space.xml
index 22df40d..63be968 100644
--- a/nfsv42_middle_space.xml
+++ b/nfsv42_middle_space.xml
@@ -83,7 +83,7 @@
 
     <t>
       The following operations and attributes can be used to resolve
-      this issues:
+      these issues:
     </t>
 
     <t>
@@ -93,14 +93,20 @@
           deleted, taking block sharing into consideration.
         </t>
 
-        <t hangText="WRITE_HOLE">
-          This operation zeros and/or deallocates the blocks
-          backing a region of the file.
+        <t hangText="DEALLOCATE">
+          This operation delallocates the blocks backing a
+          region of the file.
+        </t>
+
+        <t hangText="WRITE_SAME">
+          This operation zeros the blocks backing a region of the
+          file. It does not deallocate the blocks, so it does not
+          reduce the space reservation.
         </t>
 
-	<t hangText="READ_PLUS or SEEK">
+        <t hangText="READ_PLUS or SEEK">
           These operations can return the reservation status of blocks
-	  backing a region of the file.
+          backing a region of the file.
         </t>
       </list>
     </t>
@@ -146,18 +152,19 @@
       over-reported.  However, over-reporting is better than under-reporting.
     </t>
   </section>
+
   <section anchor='ss:space:info' title='Space Reservation Information'>
   <?rfc include='autogen/type_space_info4.xml'?>
       <t>
         The space_info4 type is used to report the reservation space
-	in the READ_PLUS (see <xref target='op:read_plus' />) and SEEK
-	(see <xref target='op:seek' /> operations to report the
-	reservation state of a data block or hole.  A data block or
-	hole may either be reserved, that means a future write MUST not
-	return NFS4ERR_NOSPC, or it might be unreserved in which case
-	a future write may return NFS4ERR_NOSPC.  Servers may not know
-	the allocation state, in which case it might return unknown
-	in the space_info fields in the READ_PLUS and SEEK return values.
+        in the READ_PLUS (see <xref target='op:read_plus' />) and SEEK
+        (see <xref target='op:seek' /> operations to report the
+        reservation state of a data block or hole.  A data block or
+        hole may either be reserved, that means a future write MUST not
+        return NFS4ERR_NOSPC, or it might be unreserved in which case
+        a future write may return NFS4ERR_NOSPC.  Servers may not know
+        the allocation state, in which case it might return unknown
+        in the space_info fields in the READ_PLUS and SEEK return values.
       </t>
   </section>
 </section>
-- 
1.9.0