Subject: Re: [nfsv4] reading pNFS interfaces

From: Marc Eshel <[email-masked]>
Date: Thu, 9 Nov 2006 18:26:07 -0800

Marc Eshel <[email-masked]> wrote on 08/31/2006 05:14:24 PM:

> Is there a way that we can help the reader of the following section of 
the 
> draft (and other places that opaque is used) to find that definition for 

> the opaque struct which is nfsv4_file_layout_device4 in this case. We 
are 
> trying so hard to make the interface generic that it is impossible to 
read 
> the document. We can add a comment that can say that in the case of file 

> layout it is nfsv4_file_layout_device4 or have some naming convention 
> where the name of the field gdir_device_addr is some how related to 
> nfsv4_file_layout_device4, by having the same ending, for example 
> gdir_layout_device4. 
> 

The opaque structure in the following example for the file protocol is 
nfsv4_file_layout_device4 so one option is to rename gdir_device_addr to 
layout_device4. The object and block drafts will have a corresponding 
nfsv4_object_layout_device4 and nfsv4_block_layout_device4 we will have to 
explain our convention somewhere in the document. I am going to open an 
issue to keep track of this problem and if anyone have a better idea for 
the naming convention please let me know.
Marc.

16.40.3.  RESULT

   struct GETDEVICEINFO4resok {
           opaque                  gdir_device_addr<>;     <<<< rename to 
layout_device4 >>> 
   };

12.4.2.  File Striping and Data Access

   typedef netaddr4 nfsv4_file_layout_simple_device4;

   enum file_layout_device_type {
           FILE_SIMPLE  = 1,
           FILE_COMPLEX = 2
   };

   union nfsv4_file_layout_device4
       switch (file_layout_device_type fld_type) {
           case FILE_SIMPLE:
                   nfsv4_file_layout_simple_device4 nfld_dev_list<>;
           case FILE_COMPLEX:
                   deviceid4 dev_list<>;
           default:
                   void;
   };

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

---

From: Marc Eshel <[email-masked]>
Date: Sat, 11 Nov 2006 20:04:56 -0800

Here are the changes that I suggest to make in order to make it easier
to find the definitions for the opaque fields in the pNFS interfaces.
If this is reasonable can one of the editors make the changes?
Thanks, Marc.

3.2.20.  devlist_item4

   struct devlist_item4 {
           deviceid4          dli_id;
-          opaque             dli_device_addr<>;
+          opaque             dli_layout_device4<>;
   };

   An array of these values is returned by the GETDEVICELIST operation.
   They define the set of devices associated with a file system for the
   layout type specified in the GETDEVICELIST4args.

   The device address is used to set up a communication channel with the
   storage device.  Different layout types will require different types
   of structures to define how they communicate with storage devices.
-  The opaque device_addr field must be interpreted based on the
-  specified layout type.
+  The opaque dli_layout_device4 field must be interpreted based on the
+  specified layout type. Each layout type has a corresponding 
+  nfs4_[type]_layout_device4 struct. 

3.2.21.  layout4

   struct layout4 {
       offset4                 lo_offset;
       length4                 lo_length;
       layoutiomode4           lo_iomode;
       layouttype4             lo_type;
-      opaque                  lo_layout<>;
+      opaque                  lo_layouttype4<>;
   };

   The layout4 structure defines a layout for a file.  The layout type
   specific data is opaque within this structure and must be
-  interepreted based on the layout type.  Currently, only the NFSv4
-  file layout type is defined; see Section 12.4.2 for its definition.
+  interepreted based on the layout type. Each layout type has a 
+  corresponding nfs4_[type]_layouttype4 struct. File layout type is 
+  defined in Section 12.4.2.
   Since layouts are sub-dividable, the offset and length together with
   the file's filehandle, the clientid, iomode, and layout type,
   identifies the layout.

3.2.22.  layoutupdate4

   struct layoutupdate4 {
       layouttype4             lou_type;
-      opaque                  lou_data<>;
+      opaque                  lou_layoutupdate4<>;
   };

   The layoutupdate4 structure is used by the client to return 'updated'
   layout information to the metadata server at LAYOUTCOMMIT time.  This
   structure provides a channel to pass layout type specific information
   back to the metadata server.  E.g., for block/volume layout types
   this could include the list of reserved blocks that were written.
-  The contents of the opaque lou_data argument are determined by the
-  layout type and are defined in their context.  The NFSv4 file-based
+  The contents of the opaque lou_layoutupdate4 argument are determined by
+  the layout type and are defined in their context.  The NFSv4 file-based
   layout does not use this structure, thus the update_data field should
-  have a zero length.
+  have a zero length. For other layout types look for 
+  nfsv4_[type]_layoutupdate4.

3.2.23.  layouthint4

   struct layouthint4 {
       layouttype4           loh_type;
-      opaque                loh_data<>;
+      opaque                loh_layouthint4<>;
   };

   The layouthint4 structure is used by the client to pass in a hint
   about the type of layout it would like created for a particular file.
   It is the structure specified by the FILE_LAYOUT_HINT attribute
   described below.  The metadata server may ignore the hint, or may
   selectively ignore fields within the hint.  This hint should be
   provided at create time as part of the initial attributes within
-  OPEN.  The NFSv4 file-based layout uses the "nfsv4_file_layouthint"
-  structure as defined in Section 12.4.2. 
+  OPEN.  The NFSv4 file-based layout uses the "nfsv4_file_layouthint4"
+  structure as defined in Section 12.4.2. For other layout types look 
+  for nfsv4_[type]_layouthint4.

16.40.  Operation 47: GETDEVICEINFO - Get Device Information

16.40.1.  SYNOPSIS

-  (cfh), device_id, layout_type, maxcount -> device_addr
+  (cfh), device_id, layout_type, maxcount -> layout_device4

16.40.2.  ARGUMENT

   struct GETDEVICEINFO4args {
           /* CURRENT_FH: file */
           deviceid4               gdia_device_id;
           layouttype4             gdia_layout_type;
           count4                  gdia_maxcount;
   };

16.40.3.  RESULT

   struct GETDEVICEINFO4resok {
-          opaque                  gdir_device_addr<>;
+          opaque                  gdir_layout_device4<>;
   };

   union GETDEVICEINFO4res switch (nfsstat4 status) {
   case NFS4_OK:
           GETDEVICEINFO4resok     gdir_resok4;
   default:
           void;
   };

16.40.4.  DESCRIPTION

   Returns device address information for a specified device.  The
   device address MUST correspond to the layout type specified by the
   GETDEVICELIST4args.  The current filehandle (cfh) is used to identify
   the file system; device IDs are unique per file system (FSID) and are
   qualified by the layout type.

+  See nfs4_[type]_layout_device4 for opaque field definitions.
   See Section 12.3.1.4 for more details on device ID assignment.