Re: [PATCH bpf-next] The original document has some inconsistency.

[David Vernet <void@manifault.com>]

[-- Attachment #1: Type: text/plain, Size: 3286 bytes --]

On Fri, Jan 12, 2024 at 12:16:47PM -0800, dthaler1968@googlemail.com wrote:

[...]

> > 
> > This is already pretty different from how we're visualizing and
> enumerating
> > the instructions in our document.
> 
> The packet layout diagram style above is indeed the most common
> (and I'd be fine if the WG wants to switch to that style), but there are
> RFCs that use other styles.  See for example RFC 9000 which uses a custom
> style, but has a full explanation defining it.

I guess my question would be why did RFC 9000 deviate, but I don't think
that's super relevant or important. As I mention below, I'm fine with
applying this change if you think it makes the doc more canonical.

Regarding question of the layout diagram style, at this point I don't
think we need to spend time switching the style, though I do think the
other style is more legible than what we have now. If someone wants to
do the work then I'd say go for it, but otherwise I'd prefer we don't
block on it given how close we are to WG last call.

> > Consider:
> > 
> > 1. They're not even using numerical values to define some fields, such
> >    as with Type of Service. They're specifying the exact values of
> >    individual bits within the field (e.g. with Precedence).
> > 
> > 2. They're using decimal instead of hexadecimal.
> 
> Sometimes values are given in decimal, sometimes in hexadecimal
> (e.g., see Table 1 of RFC 9000), sometimes in binary (e.g., Precedence as
> you noted).  Decimal is most common but hex or binary are ok if it's clear
> that's what's used.

Ack as well

> > Unless I'm missing something, it seems like the deviation in terms of
> using
> > 0x40 vs. 0x4 is specific to how they present examples in the appendices
> > (though even the appendices are using base 10).
> 
> For a 4-bit field, I've only seen cases where the value is 0x4, 4, or 0100,
> which fit into a 4-bit field.  I've not seen a case of 0x40.

Fair enough, though as mentioned above, I'm having trouble understanding
where deviations are acceptable or not. I trust your judgement though.

> > So while I certainly agree that we should follow conventions, I think I'd
> prefer
> > that we either follow them completely, or not sacrifice readability by
> following
> > them in specific ways which don't necessarily match the chosen format for
> > our document.
> 
> If you're suggesting we use packet layout format like you quoted, that'd
> be fine with me.

See above -- if someone wants to do the work then I'd say go for it, but
I don't think it should be a blocker.

[...]

> > I agree with you that we should stay consistent, but it seems like we're
> being
> > selective about it. Could you help me understand why the deviations we
> have
> > already wouldn't have required a separate section?
> 
> It's fair to argue that having a section defining the convention, like RFC
> 9000 did,
> would be recommended if one deviates from standard conventions.  
> But it'd be shorter (and perhaps less work) to use a more standard
> convention.

Agreed. At this point I'd say let's do whatever is kosher and will
require less time and effort; unless someone wants to spend time writing
up fancy ASCII diagrams.

Thanks,
David

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]