[AFS3-std] Re: AFSVol GetSizeV2 draft

[Andrew Deason]

On Wed, 2 Feb 2011 16:18:23 -0600
David Boyes <dboyes@sinenomine.net> wrote:

> Abstract:
> 
> 12: what you're describing in this document is your proposed
> implementation, not the actual code, right? If so, then the text of
> line 12 should reflect that it is a proposal, not a description of an
> implementation.

Is "This document proposes" in place of "This document defines"
sufficient for this?

> Body:
> 
> 14: "greater" than what? That needs to refer to something, but there's
> nothing specified to compare it to.

Yes, I wasn't sure how to phrase it. This is just intended to
distinguish it from the existing RPC that does the same thing. Without
those extra qualifiers, I thought what it described was the existing
GetSize RPC. Does something like this make more sense?

>> This document proposes an additional RX remote procedure call that
>> may be used to obtain the size of an AFS-3 volume dump from an AFS-3
>> Volume Service. While an RPC already exists for this purpose
>> (GetSize), this document proposes a more flexible mechanism that is
>> able to accurately determine the size of a volume dump in more
>> scenarios.

> 79, ff: the previous lines have described what the context is, but you
> haven't clearly stated what you are proposing. I would suggest that you
> insert here a clear statement of the desired function, and provide the 3
> Good Reasons why it's worth implementing here.

A proposed extra sentence:

"This document proposes a new RPC, GetSizeV2, to fill this gap, to allow
computation of the sizes of volume dumps generated by DumpV2."

I'm not sure how much justification I can give beyond that; I think
there is general agreement that something like this deserves to exist at
least in some form. Any further reasons I give would just be repetitive;
it seems like a basic "we can't do X; this lets us do X".

> 83,84: Where are these flags documented? If there's no formal
> documentation of them, it would probably be smart to provide a short
> summary of what the definition of each one of the flags is, the
> meaning of each, and the context rather than referring to the other
> RPC. This document has to stand alone in lieu of any other extant
> documentation.

As far as GetSizeV2 cares about these error codes, I feel their meaning
is clear from when they are referred to in the description of GetSizeV2.
It seems redundant to say in this section "VOLSERBAD_ACCESS is returned
if the caller has insufficient privileges to execute the specified
operation", and then to say in the section describing GetSizeV2, "If the
caller has insufficient privileges to run GetSizeV2, VOLSERBAD_ACCESS is
returned".

If you just want the values defined here, then sure.

I should point out that draft-brashear-afs3-pts-extended-names-07 and
draft-wilkinson-afs3-bos-identities-00 do effectively the same thing
(the former being effectively out-the-door at this point, AIUI). Do all
of these need to define all error codes in such a manner?

> 94: Since no documentation exists for GetSize outside the code, you
> need to summarize the function of it here.  Ditto DumpV2 at #96.

Would it be appropriate to just have a couple of small sections
describing GetSize and DumpV2, and referring to them? Is it appropriate
to just describe/summarize them in prose and not have the XDR
definitions like normal? I would like it if I didn't need to give full
standardization of GetSize and DumpV2 along with GetSizeV2 in here.

Should we assume you have similar objections to
draft-wilkinson-afs3-bos-identities-00 ?

> 105,106: are there concerns with the impending rollover of the Unix
> epoch in 2087? If so, discuss them here.

ACK (assuming this stays the same; see response to Derrick's comment).

> 114-118: Move these lines to a separate section (3.3) entitled "Return
> Codes". Also, is there a symbolic value for 0, rather than assuming
> the C library returns 0 for OK on all platforms?

We've been using 0 everywhere (and I don't think we care what the
platform uses as a constant for success; we always return 0). We have
the symbolic constant RXGEN_SUCCESS that we could in theory use, but no
relevant code in OpenAFS actually uses it. (The client-side stub
routines make use of it for local processing, but nothing that gets sent
over the wire actually originates from an RXGEN_SUCCESS expansion, I
think)

> 162: is there a official name for the AFS AN registry? If so, use it
> here.

I don't know; other AFS-3 drafts don't give any. It's possible that we
could refer to it as the registry defined in
draft-wilkinson-afs3-standardisation-00 Section 2.3.2, but other drafts
should probably do that, too. And can I even do that, since that I-D is
expired?

-- 
Andrew Deason
adeason@sinenomine.net