Re: [PATCH bpf-next] docs/bpf: Document some special sdiv/smod operations

[Yonghong Song <yonghong.song@linux.dev>]

On 11/8/24 10:53 AM, Dave Thaler wrote:
>> -----Original Message-----
>> From: Alexei Starovoitov <alexei.starovoitov@gmail.com>
>> Sent: Friday, November 8, 2024 10:38 AM
>> To: Dave Thaler <dthaler1968@googlemail.com>
>> Cc: Yonghong Song <yonghong.song@linux.dev>; bpf@ietf.org; bpf
>> <bpf@vger.kernel.org>; Alexei Starovoitov <ast@kernel.org>; Andrii Nakryiko
>> <andrii@kernel.org>; Daniel Borkmann <daniel@iogearbox.net>; Martin KaFai Lau
>> <martin.lau@kernel.org>
>> Subject: Re: [PATCH bpf-next] docs/bpf: Document some special sdiv/smod
>> operations
>>
>> On Thu, Nov 7, 2024 at 6:30 PM Dave Thaler <dthaler1968@googlemail.com>
>> wrote:
>>>
>>> Alexei Starovoitov <alexei.starovoitov@gmail.com> wrote:
>>>> On Tue, Oct 1, 2024 at 12:54 PM Dave Thaler
>>>> <dthaler1968@googlemail.com>
>>>> wrote:
>>> [...]
>>>>> I'm adding bpf@ietf.org to the To line since all changes in the
>>>>> standardization directory should include that mailing list.
>>>>>
>>>>> The WG should discuss whether any changes should be done via a new
>>>>> RFC that obsoletes the first one, or as RFCs that Update and just
>>>>> describe deltas (additions, etc.).
>>>>>
>>>>> There are precedents both ways and I don't have a strong
>>>>> preference, but I have a weak preference for delta-based ones
>>>>> since they're shorter and are less likely to re-open discussion on
>>>>> previously resolved issues, thus often saving the WG time.
>>>> Delta-based additions make sense to me.
>>>>
>>>>> Also FYI to Linux kernel folks:
>>>>> With WG and AD approval, it's also possible (but not ideal) to
>>>>> take changes at AUTH48.  That'd be up to the chairs and AD to
>>>>> decide though, and normally that's just for purely editorial
>>>>> clarifications, e.g., to confusion called out by the RFC editor pass.
>>>> Also agree. We should keep AUTH going its course as-is.
>>>> All ISA additions can be in the future delta RFC.
>>>>
>>>> As far as file logistics... my preference is to keep
>>>> Documentation/bpf/standardization/instruction-set.rst
>>>> up to date.
>>>> Right now it's effectively frozen while awaiting changes (if any) necessary for
>> AUTH.
>>>> After official RFC is issued we can start landing patches into
>>>> instruction-set.rst and git diff 04efaebd72d1..whatever_future_sha
>>>> instruction-set.rst will automatically generate the future delta RFC.
>>>> Once RFC number is issued we can add a git tag for the particular
>>>> sha that was the base for RFC as a documentation step and to simplify future 'git
>> diff'.
>>> My concern is that index.rst says:
>>>> This directory contains documents that are being iterated on as part
>>>> of the BPF standardization effort with the IETF. See the `IETF BPF
>>>> Working Group`_ page for the working group charter, documents, and more.
>>> So having a document that is NOT part of the IETF BPF Working Group
>>> would seem out of place and, in my view, better located up a level (outside
>> standardization).
>>
>> It's a part of bpf wg. It's not a new document.
> RFC 9669 is immutable.  Any additions require a new document, in
> IETF terminology, since would result in a new RFC number.
>
>>> Here’s some examples of delta-based RFCs which explain the gap and
>>> provide the addition or clarification, and formally Update (not
>>> replace/obsolete) the original
>>> RFC:
>>> * https://www.rfc-editor.org/rfc/rfc6585.html: Additional HTTP Status
>>> Codes
>>> * https://www.rfc-editor.org/rfc/rfc6840.html: Clarifications and Implementation
>> Notes
>>>     for DNS Security (DNSSEC)
>>> * https://www.rfc-editor.org/rfc/rfc9295.html: Clarifications for Ed25519, Ed448,
>>>     X25519, and X448 Algorithm Identifiers
>>> * https://www.rfc-editor.org/rfc/rfc5756.html: Updates for RSAES-OAEP and
>>>     RSASSA-PSS Algorithm Parameters
>>>
>>> Having a full document too is valuable but unless the IETF BPF WG
>>> decides to take on a -bis document, I'd suggest keeping it out of the
>> "standardization"
>>> (say up 1 level) to avoid confusion, and just have one or more
>>> delta-based rst files in the standardization directory.
>> This patch is effectively a fix to the standard.
> Two of the examples I provided above fit into that category.
> Two are examples of adding new codepoints.
>
>> It's a standard git development process when fixes are applied to the existing
>> document.
>> Forking the whole doc into a different file just to apply fixes makes no sense to me.
> Welcome to the IETF and immutable RFCs 😊
>
>> The formal delta-s for IETF can be created out of git.
> Not in the IETF per se, since a new document needs new boilerplate, with
> a new abstract, introduction, etc.  At most, part of the document could be created
> out of git, but I'm not convinced that git diffs alone (as opposed to some English
> prose too for each, as in the examples I cited) make for good content in an IETF document.
>
>> We only need to tag the current version and then git diff rfc9669_tag..HEAD will give
>> us that delta.
>> That will satisfy IETF process and won't mess up normal git style kernel
>> development.
> I am not convinced it is sufficient.  Can you point to any precedents in the IETF for
> such an approach?  I can't offhand... See the RFC 5756 reference above for what
> I mean by English prose for each diff.

I think we can add sufficient details in the commit message. What things we need to
put in the commit message to satisfy the rIETF equirement?

>> btw do we still need to do any minor edit/fixes to instruction-set.rst before tagging it
>> as RFC9669 ?
> Yes, we need to backport the formatting/nits from the RFC editor pass.
>
> Dave
>