Subject: [nfsv4] Issue 58: pnfs: layout return flag for fsid returns

From: Benny Halevy <[email-masked]>
Date: Tue, 27 Jun 2006 21:50:27 +0300

Following is the test I propose for the RETURN_FSID feature.

It does not discuss the issues I raised in
http://www1.ietf.org/mail-archive/web/nfsv4/current/msg03209.html
I think we should open a new entry on the tracker for the broader
synchronization issues...

Benny

  14.5.1.  Basic Operation

     Since a layout protects a client's access to a file via a direct
     client-storage-device path, a layout need only be recalled when it is
     semantically unable to serve this function.  Typically, this occurs
     when the layout no longer encapsulates the true location of the file
     over the byte range it represents.  Any operation or action (e.g.,
     server driven restriping or load balancing) that changes the layout
     will result in a recall of the layout.  A layout is recalled by the
     CB_LAYOUTRECALL callback operation (see Section 24.9).  This callback
     can either recall a layout segment identified by a byte range, or all
-   the layouts associated with a file system (FSID).  However, there is
-   no single operation to return all layouts associated with an FSID;
+   the layouts associated with a file system (FSID).
     multiple layout segments may be returned in a single compound
     operation.  Section 14.5.3 discusses sequencing issues surrounding
     the getting, returning, and recalling of layouts.

  22.48.  LAYOUTRETURN - Release Layout Information

  22.48.1.  SYNOPSIS

-   (cfh), clientid, offset, length, reclaim, iomode, layout_type -> -
+
+   (cfh), clientid, layout_type, iomode, layoutreturn, reclaim -> -
+

  22.48.2.  ARGUMENT

+
+   enum layoutreturn_type4 {
+       RETURN_FILE = 1,
+       RETURN_FSID = 2
+   };
+
+
+   struct layoutreturn_file4 {
+       offset4         offset;
+       length4         length;
+   };
+
+
+   union layoutreturn4 switch(layoutreturn_type4 returntype) {
+       case RETURN_FILE:
+           layoutreturn_file4 layout;
+
+       case RETURN_FSID:
+           void;
+   };
+
+
     struct LAYOUTRETURN4args {
         /* CURRENT_FH: file */
         clientid4               clientid;
-       offset4                 offset;
-       length4                 length;
-       bool                    reclaim;
-       pnfs_layoutiomode4      iomode;
         pnfs_layouttype4        layout_type;
+       pnfs_layoutiomode4      iomode;
+       layoutreturn4           layoutreturn;
+       bool                    reclaim;
     };

  22.48.3.  RESULT

     struct LAYOUTRETURN4res {
         nfsstat4        status;
     };

  22.48.4.  DESCRIPTION

-   Returns the layout segment represented by the current filehandle,
-   clientid, byte range, iomode, and layout type.  After this call, the
-   client MUST NOT use the layout and the associated storage protocol to
+   Returns one or more layout segments represented by the clientid,
+   layout_type, and iomode.  When layoutreturn is RETURN_FILE the
+   returned layout segment is identified by the current filehandle,
+   offset, and length.  When layoutreturn is RETURN_FSID the current
+   filehandle is used to identify the file system and all layouts
+   matching the clientid, layout_type, and iomode are returned.
+   After this call, the client MUST NOT use the returned layout(s) and
+   the associated storage protocol to
     access the file data.  The layout being returned may be a subdivision
     of a layout previously fetched through LAYOUTGET.  As well, it may be
     a subset or superset of a layout specified by CB_LAYOUTRECALL.
     However, if it is a subset, the recall is not complete until the full
     byte range has been returned.  It is also permissible, and no error
     should result, for a client to return a byte range covering a layout
     it does not hold.  If the length is all 1s, the layout covers the
     range from offset to EOF.  An iomode of ANY specifies that all
     layouts that match the other arguments to LAYOUTRETURN (i.e.,
-   clientid, byte range, and type) are being returned.
+   clientid, type, filehandle and byte range, or fsid) are being returned.

     The "reclaim" field set to "true" in a LAYOUTRETURN request specifies
     that the client is attempting to return a layout that was acquired
     before the reboot of the metadata server during the metadata server's
     grace period.  Returning layouts that were acquired during the
     metadata server's grace period MUST set the "reclaim" field to
-   "false".  See LAYOUTCOMMIT (Section 22.47) for more details.
+   "false".  The "reclaim" field MUST be set to false also when layoutreturn
+   is for RETURN_FSID. See LAYOUTCOMMIT (Section 22.46) for more details.

     Layouts may be returned when recalled or voluntarily (i.e., before
     the server has recalled them).  In either case the client must
     properly propagate state changed under the context of the layout to
     storage or to the server before returning the layout.

     If a client fails to return a layout in a timely manner, then the
     metadata server should use its control protocol with the storage
     devices to fence the client from accessing the data referenced by the
     layout.  See Section 14.5 for more details.

     If the layout identified in the arguments does not exist, the error
     NFS4ERR_BADLAYOUT is returned.  If a layout exists, but the iomode
     does not match, NFS4ERR_BADIOMODE is returned.

     If the LAYOUTRETURN request sets the "reclaim" field to "true" after
     the metadata server's grace period, NFS4ERR_NO_GRACE is returned.

+   If the LAYOUTRETURN request sets the "reclaim" field to "true" and
+   returntype is set to RETURN_FSID, NFS4ERR_INVAL is returned.
+
     On success, the current filehandle retains its value.

-   [[Comment.6: Should LAYOUTRETURN be modified to handle FSID
-   callbacks?]]

  22.48.5.  IMPLEMENTATION

+   Returning all layouts in a file system is done in response to a
+   CB_LAYOUTRECALL for that file system as the final return operation.
+   It is possible that the client already returned some or all outstanding
+   layouts via individual LAYOUTRETURN calls and the call for RETURN_FSID
+   marks the end of the return sequence from the client point of view.
+   See "Recall Callback Robustness" (Section 14.5.2) for more details.
+
  22.48.6.  ERRORS

     NFS4ERR_BADLAYOUT NFS4ERR_BADIOMODE NFS4ERR_FHEXPIRED NFS4ERR_INVAL
     NFS4ERR_NOFILEHANDLE NFS4ERR_NO_GRACE NFS4ERR_STALE
     NFS4ERR_STALE_CLIENTID NFS4ERR_UNKNOWN_LAYOUTTYPE

_______________________________________________
nfsv4 mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/nfsv4