Subject: [nfsv4] GETDEVICEINFO and GETDEVICELIST in the draft-15 spec

From: [email-masked]
Date: Thu, 1 Nov 2007 15:09:10 -0400

I have two minor issues with the draft-15 spec related to GETDEVICEINFO
and GETDEVICELIST.  The spec does not adequately specify the meaning of
gdia_maxcount.  The sentence describing its usage states:

"The client provides gdia_maxcount to limit the amount of device address
information to be returned for the mapping. If the mapping can not be
returned within the maximum specified, NFS4ERR_TOOSMALL is returned."

This sentence does not make clear if gdia_maxount limits the number of
bytes in the GETDEVICEINFO4res data structure, within the "device_addr4"
structure, or within the protocol specific opaque data "da_addr_body".
I propose that the wording be changed to clarify that this refers to the
number of bytes in the "device_addr4" portion of the response.

"The client provides gdia_maxcount to limit the amount of device address
information to be returned for the mapping. If the device address can
not be returned within the maximum specified, NFS4ERR_TOOSMALL is
returned."

Furthermore, in the case of returning NFS4ERR_TOOSMALL, the server
should provide some means for the client to figure out the right amount
of storage to allocate so that the call can succeed.  In draft-15 the
client has no way of knowing how much storage to allocate when it
retries the call.

union GETDEVICEINFO4res switch (nfsstat4 gdir_status) {

case NFS4_OK:

        GETDEVICEINFO4resok     gdir_resok4;

default:

        void;

};

union GETDEVICELIST4res switch (nfsstat4 gdlr_status) {

case NFS4_OK:

        GETDEVICELIST4resok     gdlr_resok4;

default:

        void;

};

I suggest that both the above result data structures be changed to allow
the server to specify a minimum count required for the RPC to succeed.

union GETDEVICEINFO4res switch (nfsstat4 gdir_status) {

case NFS4_OK:

        GETDEVICEINFO4resok     gdir_resok4;

case NFS4ERR_TOOSMALL:

        count4 gdir_mincount;   

default:

        void;

};

union GETDEVICELIST4res switch (nfsstat4 gdlr_status) {

case NFS4_OK:

        GETDEVICELIST4resok     gdlr_resok4;

case NFS4ERR_TOOSMALL:

        count4 gdlr_mincount

default:

        void;

};

The accompanying text in section 18.40.4 should be changed from

----

If the device address can not be returned within the maximum specified,
NFS4ERR_TOOSMALL is returned.

----

to

---

If the device address can not be returned within the maximum specified,
NFS4ERR_TOOSMALL is returned along with the minimum size necessary for
the call to succeed.

---

Similarly, section 18.41.4 should change from

--

If gdia_maxcount is smaller than the size of a single entry, the error
NFS4ERR_TOOSMALL is returned.

--

To

--

If gdia_maxcount is smaller than the size of a single entry, the error
NFS4ERR_TOOSMALL is returned along with the minimum size necessary to
encode a single entry.

--

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

---

From: Spencer Shepler <[email-masked]>
Date: Mon, 05 Nov 2007 23:54:08 -0600

On Nov 1, 2007, at 2:09 PM, [email-masked] wrote:

> I have two minor issues with the draft-15 spec related to  
> GETDEVICEINFO and GETDEVICELIST.  The spec does not adequately  
> specify the meaning of gdia_maxcount.  The sentence describing its  
> usage states:
>
>
>
> “The client provides gdia_maxcount to limit the amount of device  
> address information to be returned for the mapping. If the mapping  
> can not be returned within the maximum specified, NFS4ERR_TOOSMALL  
> is returned.”
>
>
>
> This sentence does not make clear if gdia_maxount limits the number  
> of bytes in the GETDEVICEINFO4res data structure, within the  
> “device_addr4” structure, or within the protocol specific opaque  
> data “da_addr_body”.  I propose that the wording be changed to  
> clarify that this refers to the number of bytes in the  
> “device_addr4” portion of the response.

I agree that the use of gdia_maxcount is underspecified.

However, I would prefer the the "maxcount" be interpreted
as it is for the READDIR operation.

Quoting from that operation description:
   "The maxcount value of the argument is the maximum number of bytes  
for
    the result.  This maximum size represents all of the data being
    returned within the READDIR4resok structure and includes the XDR
    overhead.  The server may return less data.  If the server is unable
    to return a single directory entry within the maxcount limit, the
    error NFS4ERR_TOOSMALL will be returned to the client."

Therefore, I would suggest the text for GETDEVICEINFO be:

"The client provides gdia_maxcount to limit the number of bytes for the
  result.  This maximum size represents all of the data being returned
  within the GETDEVICEINFO4resok structure and includes the XDR
  overhead.  The server may return less data.  If the server is unable
  to return the information within the gdia_maxcount limit, the error
  NFS4ERR_TOOSMALL will be returned."

And for GETDEVICELIST:

"The client provides gdla_maxcount to limit the number of bytes for the
  result.  This maximum size represents all of the data being returned
  within the GETDEVICELIST4resok structure and includes the XDR
  overhead.  The server may return less data.  If the server is unable
  to return a single entry device list item within the gdla_maxcount
  limit, the error NFS4ERR_TOOSMALL will be returned."

The remaining suggestions of adding NFS4ERR_TOOSMALL to the
return union is fine with me.

Spencer

---

From: "Noveck, Dave" <[email-masked]>
Date: Tue, 6 Nov 2007 06:09:33 -0500

NFS4ERR_TOOSMALL is already specified as a valid error for these ops. 

-----Original Message-----
From: Spencer Shepler [mailto:[email-masked]] 
Sent: Tuesday, November 06, 2007 12:54 AM
To: NFSv4
Subject: Re: [nfsv4] GETDEVICEINFO and GETDEVICELIST in the draft-15
spec

On Nov 1, 2007, at 2:09 PM, [email-masked] wrote:

> GETDEVICEINFO and GETDEVICELIST.  The spec does not adequately specify

> the meaning of gdia_maxcount.  The sentence describing its usage 
> states:
>
>
>
> "The client provides gdia_maxcount to limit the amount of device 
> address information to be returned for the mapping. If the mapping can

> bytes in the GETDEVICEINFO4res data structure, within the 
> "device_addr4" structure, or within the protocol specific opaque data 
> "da_addr_body".  I propose that the wording be changed to clarify that

> this refers to the number of bytes in the "device_addr4" portion of 
> the response.

However, I would prefer the the "maxcount" be interpreted as it is for
the READDIR operation.

And for GETDEVICELIST:

The remaining suggestions of adding NFS4ERR_TOOSMALL to the return union
is fine with me.

Spencer

---

From: Benny Halevy <[email-masked]>
Date: Tue, 06 Nov 2007 15:25:14 +0200

Spencer Shepler wrote:
>> can not be returned within the maximum specified, NFS4ERR_TOOSMALL is 
>> returned.”
>>
>>
>>
>> “device_addr4” structure, or within the protocol specific opaque data 
>> “da_addr_body”.  I propose that the wording be changed to clarify 
>> that this refers to the number of bytes in the “device_addr4” portion 
>> of the response.
>
>   "The maxcount value of the argument is the maximum number of bytes for
I agree with Spencer.  This was my interpretation too.

---

From: [email-masked]
Date: Tue, 6 Nov 2007 09:13:38 -0500

I also agree with Spencer's updated suggestions for GETDEVICEINFO and
GETDEVICELIST.
Thanks, Jason

-----Original Message-----
From: Benny Halevy [mailto:[email-masked]] 
Sent: Tuesday, November 06, 2007 8:25 AM
To: Spencer Shepler
Cc: NFSv4
Subject: Re: [nfsv4] GETDEVICEINFO and GETDEVICELIST in the draft-15
spec

>> "da_addr_body".  I propose that the wording be changed to clarify 
>> that this refers to the number of bytes in the "device_addr4" portion

for

---

From: Spencer Shepler <[email-masked]>
Date: Tue, 06 Nov 2007 11:41:48 -0600

Thanks. The updates have been made.

Spencer