BPF Instruction Set Architecture (ISA)
draft-ietf-bpf-isa-04

Received changes through RFC Editor sync (changed state to RFC, created became rfc relationship between draft-ietf-bpf-isa and RFC 9669, changed IESG state to RFC Published)

# Document Shepherd Write-Up for Group Documents

*This version is dated 4 July 2022.*

Thank you for your service as a document shepherd. Among the responsibilities is
answering the questions in this write-up to give helpful context to Last Call
and Internet Engineering Steering Group ([IESG][1]) reviewers, and your
diligence in completing it is appreciated. The full role of the shepherd is
further described in [RFC 4858][2]. You will need the cooperation of the authors
and editors to complete these checks.

Note that some numbered items contain multiple related questions; please be sure
to answer all of them.

## Document History

1. Does the working group (WG) consensus represent the strong concurrence of a
  few individuals, with others being silent, or did it reach broad agreement?


The working group has reached broad agreement with respect to the publication of this document. All of the key participants and implementers are in strong agreement that the document is ready to be progressed to the IESG.


2. Was there controversy about particular points, or were there decisions where
  the consensus was particularly rough?


The main points of controversy were the following:

- Instruction conformance groups [18]
Some of the technical advisors initially felt [19] that we should only have “legacy” and “rest” conformance groups. This resulted in several long and contentious discussions, as can be seen on the email thread in [19]. Thankfully, we ultimately got broad consensus on the conformance groups that are listed in the document now. Note that these conformance groups roughly reflect RISC-V conformance groups, and thus our expectation that vendors implementing BPF offload will be faced with roughly the same constraints as those anticipated by vendors implementing RISC-V chips. However, while the conformance groups are quite similar, they do have some differences due to e.g. the presence of legacy BPF packet instructions which are included in the historical “packet” BPF conformance group.

- callx instruction [20]
The question of whether to include an indirect call instruction by helper ID was debated over several email threads, and discussed at IETF 119. Ultimately, broad consensus was reached on BPF_JMP | BPF_X not being appropriate to include in the current iteration of the standard. While clang can be made to emit an indirect call when compiled with -O0, and with the helper pointer not declared const, it was decided at IETF 119 that this isn’t supported or intended behavior, and that would decide on the semantics of indirect calls at a later time.

- BPF memory model [21]
One member of the WG brought up that the ISA is missing a memory model, which would inform expected semantics of e.g. atomic instructions, as well as whether an address space is flat, etc. In the end, it was decided and agreed upon with broad consensus to defer this to an extension of the ISA [22]. For now, BPF matches the Linux Kernel Memory Model (LKMM). For posterity, this was discussed in some detail at IETF 118 [22].


3. Has anyone threatened an appeal or otherwise indicated extreme discontent? If
  so, please summarize the areas of conflict in separate email messages to the
  responsible Area Director. (It should be in a separate email because this
  questionnaire is publicly available.)

No


4. For protocol documents, are there existing implementations of the contents of
  the document? Have a significant number of potential implementers indicated
  plans to implement? Are any existing implementations reported somewhere,
  either in the document itself (as [RFC 7942][3] recommends) or elsewhere
  (where)?

There are several widely-used implementations of the BPF ISA in industry. These implementations include but are not limited to BPF in Linux [23], BPF in Windows [24], and uBPF [25].


## Additional Reviews

5. Do the contents of this document closely interact with technologies in other
  IETF working groups or external organizations, and would it therefore benefit
  from their review? Have those reviews occurred? If yes, describe which
  reviews took place.

No


6. Describe how the document meets any required formal expert review criteria,
  such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

N/A


7. If the document contains a YANG module, has the final version of the module
  been checked with any of the [recommended validation tools][4] for syntax and
  formatting validation? If there are any resulting errors or warnings, what is
  the justification for not fixing them at this time? Does the YANG module
  comply with the Network Management Datastore Architecture (NMDA) as specified
  in [RFC 8342][5]?

N/A


8. Describe reviews and automated checks performed to validate sections of the
  final version of the document written in a formal language, such as XML code,
  BNF rules, MIB definitions, CBOR's CDDL, etc.


N/A

## Document Shepherd Checks

9. Based on the shepherd's review of the document, is it their opinion that this
  document is needed, clearly written, complete, correctly designed, and ready
  to be handed off to the responsible Area Director?

Yes



10. Several IETF Areas have assembled [lists of common issues that their
    reviewers encounter][6]. For which areas have such issues been identified
    and addressed? For which does this still need to happen in subsequent
    reviews?

After reading over Internet Area (int) common issues [26], all such issues should be addressed.


11. What type of RFC publication is being requested on the IETF stream ([Best
    Current Practice][12], [Proposed Standard, Internet Standard][13],
    [Informational, Experimental or Historic][14])? Why is this the proper type
    of RFC? Do all Datatracker state attributes correctly reflect this intent?

The RFC publication type being requested is Proposed Standard. This type was chosen because the BPF Instruction Set Architecture is stable, and is already widely implemented and used across industry.

12. Have reasonable efforts been made to remind all authors of the intellectual
    property rights (IPR) disclosure obligations described in [BCP 79][7]? To
    the best of your knowledge, have all required disclosures been filed? If
    not, explain why. If yes, summarize any relevant discussion, including links
    to publicly-available messages when applicable.

Yes. This was discussed at length, and addressed before the BPF working group was formed, as in e.g. [27]. To the best of our knowledge, all authors and contributors are aware of all IPR disclosure obligations, and all required disclosures have been filed.


13. Has each author, editor, and contributor shown their willingness to be
    listed as such? If the total number of authors and editors on the front page
    is greater than five, please provide a justification.

Yes



14. Document any remaining I-D nits in this document. Simply running the [idnits
    tool][8] is not enough; please review the ["Content Guidelines" on
    authors.ietf.org][15]. (Also note that the current idnits tool generates
    some incorrect warnings; a rewrite is underway.)

The only remaining nit is that some lines in the document exceed the maximum width of 72 characters. This width violation appears to occur for certain tables that are rendered in text using the XML-to-TXT conversion tool. By wrapping certain columns, such as the “description” column in the conformance group registry table in section 7.1, the width violation should no longer be an issue. Thus, for now we’ll leave the task of adjusting the width of any excessively-wide tables to the RFC editor.


15. Should any informative references be normative or vice-versa? See the [IESG
    Statement on Normative and Informative References][16].

No


16. List any normative references that are not freely available to anyone. Did
    the community have sufficient access to review any such normative
    references?

N/A


17. Are there any normative downward references (see [RFC 3967][9] and [BCP
    97][10]) that are not already listed in the [DOWNREF registry][17]? If so,
    list them.

No


18. Are there normative references to documents that are not ready to be
    submitted to the IESG for publication or are otherwise in an unclear state?
    If so, what is the plan for their completion?

No. The ISA document will likely be a normative reference for other documents published by the WG, but it does not contain any normative references to documents that are not ready to be submitted to the IESG for publication.


19. Will publication of this document change the status of any existing RFCs? If
    so, does the Datatracker metadata correctly reflect this and are those RFCs
    listed on the title page, in the abstract, and discussed in the
    introduction? If not, explain why and point to the part of the document
    where the relationship of this document to these other RFCs is discussed.

No


20. Describe the document shepherd's review of the IANA considerations section,
    especially with regard to its consistency with the body of the document.
    Confirm that all aspects of the document requiring IANA assignments are
    associated with the appropriate reservations in IANA registries. Confirm
    that any referenced IANA registries have been clearly identified. Confirm
    that each newly created IANA registry specifies its initial contents,
    allocations procedures, and a reasonable name (see [RFC 8126][11]).

All aspects of the document regarding IANA assignments are enumerated in Chapter 5: IANA Considerations and the document Appendix. The document contains no references to existing IANA registries. The proposals for newly created IANA registries include the following:

- BPF Instruction Conformance Group Registry
- BPF Instruction Set Registry

Both proposals include reasonable names, clear descriptions of the contents and meaning of each field in an entry, and procedures for adding and deprecating entries.

Initial entries for the BPF Instruction Conformance Group Registry are enumerated in section 5.1. BPF Instruction Conformance Group Registry. Initial entries for the BPF Instruction Set Registry are enumerated in the document Appendix.


21. List any new IANA registries that require Designated Expert Review for
    future allocations. Are the instructions to the Designated Expert clear?
    Please include suggestions of designated experts, if appropriate.

Some of the IANA registries require Designated Expert Review.


[1]: https://www.ietf.org/about/groups/iesg/
[2]: https://www.rfc-editor.org/rfc/rfc4858.html
[3]: https://www.rfc-editor.org/rfc/rfc7942.html
[4]: https://wiki.ietf.org/group/ops/yang-review-tools
[5]: https://www.rfc-editor.org/rfc/rfc8342.html
[6]: https://wiki.ietf.org/group/iesg/ExpertTopics
[7]: https://www.rfc-editor.org/info/bcp79
[8]: https://www.ietf.org/tools/idnits/
[9]: https://www.rfc-editor.org/rfc/rfc3967.html
[10]: https://www.rfc-editor.org/info/bcp97
[11]: https://www.rfc-editor.org/rfc/rfc8126.html
[12]: https://www.rfc-editor.org/rfc/rfc2026.html#section-5
[13]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.1
[14]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.2
[15]: https://authors.ietf.org/en/content-guidelines-overview
[16]: https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/
[17]: https://datatracker.ietf.org/doc/downref/
[18]: https://mailarchive.ietf.org/arch/msg/bpf/W_GWZeh3cUPN0o1D0Lxwwbldfi0/
[19]: https://mailarchive.ietf.org/arch/msg/bpf/_CViBgpJOIQM0fvKcHWQCpCRFvg/
[20]: https://mailarchive.ietf.org/arch/msg/bpf/JNrxzJiBd09zaqU_pVeQ4s8mqKg/
[21]: https://mailarchive.ietf.org/arch/msg/bpf/8Fkl_dExCX-YbPGOmWbG4SJFBKw/
[22]: https://mailarchive.ietf.org/arch/msg/bpf/_WoygSMs8VP6QNG6A8qRtFl0Hgw/
[23]: https://docs.kernel.org/bpf/
[24]: https://github.com/microsoft/ebpf-for-windows
[25]: https://github.com/iovisor/ubpf
[26]: https://wiki.ietf.org/group/int/IntAreaIssues
[27]: https://mailarchive.ietf.org/arch/msg/bpf/VMU0nSo-T71QfXC50Q1Bu2ejD_g/

[Ballot discuss]
The shepherd writeup says:

"None of the IANA registries require Designated Expert Review."

But this isn't quite correct, as RFC 8126 says a Specification Required registry requires designated experts and strongly prefers the inclusion of guidance to them, and section 7.1 refers to parts of that registry have a Specification Required policy.  Please clarify.

[Ballot comment]
Thanks for this.

Although one would hope that “big-endian” and “little-endian” are widely understood, it might not be a bad idea to supply definitions and/or a reference.

[Ballot comment]
Can the headers in the tables such as in Section 3 be extended so it is
more clear how many bits are in the various fields ? eg the IETF style is:
                    1                  2                  3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|    opcode    |    regs      |            offset            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                              imm                              |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+



Why "host vs big" endian instead of "host order vs network order" or
"little vs big endian" ? I understand not all hosts are "host endian",
I am just a little confused why to fixup two common sets into a new set.


NITS:

boilerplate got rendered badly

[Ballot comment]
Thank you to Ines Robles for the GENART review.

** Section 4.3.1
“Historically, each helper function was identified by a static ID encoded in the 'imm' field. The available helper functions may differ for each program type, but static IDs are unique across all program types.”

Are static IDs unique across all instances of a given platform running a program?  I don’t understand what a “program type” is.

** Section 4.3.1.  As a document reader, I’m not sure what I do with this section as it defines a concept of helper functions but doesn’t specify it.

** Section 7.1.1
“Registration requests for 'Provisional' registration can be included in an Internet-Draft; when the documents expire or are approved for publication as an RFC, the registration will be updated.”

In the case of an expired I-D, what does it mean for the “registration to be updated”? 

** Section 7.2
“This document proposes a new IANA registry for BPF instructions, as follows:”

The text in Section 7.1 says it is creating a “sub-registry”.  Here it is a “registry”.  Why the discrepancy?

** Section 7.5

“'Provisional' registrations can be updated by the original registrant or anyone designated by the original registrant.”

How does one perform this designation?

[Ballot comment]
Nice document, easy to read and understand and the shepherd's write-up companion is also clear.

Just two COMMENTs (no need to reply, but replies will be appreciated):

1) like Gunter, having an expansion to "eBPF is related or is the successor of extended Berkeley Packet Filter" would comfort the readers about what they are reading.

2) I find puzzling the absence of betoh16() in the presence of htobe16() functions.

[Ballot comment]
# Gunter Van de Velde, RTG AD, comments for draft-ietf-bpf-isa-03

Please find https://www.ietf.org/blog/handling-iesg-ballot-positions/ documenting the handling of ballots.

This is rather far away from my expertise area and i trust my fellow ADs more skilled in this area to have a more thorough technology review.
From a generalist perspective the text reads good and the draft is well structured. I see no objections for this work to proceed


#COMMENTS
#========

12   eBPF (which is no longer an acronym for anything), also commonly

I assumed that 'e' was for 'extended' and that BPF stands for 'BSD Packet
Filter' originally described and specified in a paper titled "The BSD
Packet Filter: A New Architecture for User-level Packet Capture" by
Steven McCanne and Van Jacobson, presented at the 1993 Winter
USENIX Conference. This paper introduced the BPF architecture, which
was designed for efficient packet filtering and capture. 

Hence a bit surprised why the first words of the first line in
the first paragraph of the draft abstract suggest that its
not an acronym?

105   14 [RFC2119] _RFC8174 __

This text seems to need an editorial edit

(Via drafts-lastcall@iana.org): IESG/Authors/WG Chairs:

IANA has completed its review of draft-ietf-bpf-isa-02. If any part of this review is inaccurate, please let us know.

IANA understands that, upon approval of this document, there are three actions which we must complete.

First, a new registry group will be created called the BPF Instructions registry group. The new registry group will be located on the IANA protocol parameters matrix located at:

https://www.iana.org/protocols

The reference for the new registry group will be [ RFC-to-be ].

Second, in the new registry group created in the first action above, a new registry will be created called the BPF Instruction Conformance Groups registry. The registration policy for the new registry is as follows (as defined in RFC8126):

Permanent: Standards action or IESG Approval
Provisional: Specification required
Historical: Specification required

There are initial registrations in the new registry as follows:

name description includes excludes status reference

Name: atomic32
Description: 32-bit atomic instructions
Includes:
Excludes:
Status: Permanent
Reference [ RFC-to-be; Section 5.3 ]

Name: atomic64
Description: 64-bit atomic instructions
Includes: atomic32
Excludes:
Status: Permanent
Reference [ RFC-to-be; Section 5.3 ]

Name: base32
Description: 32-bit base instructions
Includes:
Excludes:
Status: Permanent
Reference [ RFC-to-be ]

Name: base64
Description: 64-bit base instructions
Includes: base32
Excludes:
Status: Permanent
Reference [ RFC-to-be ]

Name: divmul32
Description: 32-bit division and modulo
Includes:
Excludes:
Status: Permanent
Reference [ RFC-to-be; Section 4.1 ]

Name: divmul64
Description: 64-bit division and modulo
Includes: divmul32
Excludes:
Status: Permanent
Reference [ RFC-to-be; Section 4.1 ]

Name: packet
Description: Legacy packet instructions
Includes:
Excludes:
Status: Historical
Reference [ RFC-to-be; Section 5.5]

Third, also in the new registry group created in the first action above, a new registry will be created called the BPF Instruction Set registry. The registration policy for the new registry is as follows (as defined in RFC8126):

Permanent: Standards action or IESG Approval
Provisional: Specification required
Historical: Specification required

There are initial registrations in the new registry documented in the Appendix of the current draft [ RFC-to-be; Section 9 ]. IANA will use that Appendix to populate the new registry.

We understand that these are the only actions required to be completed upon approval of this document.

NOTE: The actions requested in this document will not be completed until the document has been approved for publication as an RFC. This message is meant only to confirm the list of actions that will be performed.

For definitions of IANA review states, please see:

https://datatracker.ietf.org/help/state/draft/iana-review

Thank you,

David Dong
IANA Services Sr. Specialist

The following Last Call announcement was sent out (ends 2024-05-16):

From: The IESG
To: IETF-Announce
CC: bpf-chairs@ietf.org, bpf@ietf.org, draft-ietf-bpf-isa@ietf.org, ek.ietf@gmail.com, void@manifault.com
Reply-To: last-call@ietf.org
Sender:
Subject: Last Call:  (BPF Instruction Set Architecture (ISA)) to Proposed Standard


The IESG has received a request from the BPF/eBPF WG (bpf) to consider the
following document: - 'BPF Instruction Set Architecture (ISA)'
  as Proposed Standard

The IESG plans to make a decision in the next few weeks, and solicits final
comments on this action. Please send substantive comments to the
last-call@ietf.org mailing lists by 2024-05-16. Exceptionally, comments may
be sent to iesg@ietf.org instead. In either case, please retain the beginning
of the Subject line to allow automated sorting.

Abstract


  This document specifies the BPF instruction set architecture (ISA).




The file can be obtained via
https://datatracker.ietf.org/doc/draft-ietf-bpf-isa/



No IPR declarations have been submitted directly on this I-D.

# Internet AD comments for draft-ietf-bpf-isa-02
CC @ekline

* comment syntax:
  - https://github.com/mnot/ietf-comments/blob/main/format.md

Mostly just cosmetic things and a few clarifications questions from a
novice. Nothing to hold up IETF LC, though.

## Comments

### S2.4

* Do you want to use RFC 2119/8174 language anywhere in here?  For instance:

  "implementation must support the base32 conformance group and may support"

    -->

  "implementation MUST support the base32 conformance group and MAY support"

### S3.1, others

* Consider explicitly including the bit-width of fields in the descriptive
  text (rather than requiring folks to count "+-+"s).  E.g.

  opcode (8 bits) operation to perform, ...
    specific (5 bits) The format of ...

* src_reg and dst_reg appearing to be 4-bit fields but listed as having a
  valid decimal range of only 0-10 invites questions about R11-R15, I think.

* "Unused fields shall be cleared to zero" ->
  "Unused fields SHALL be cleared to zero" (iff. you decide to use 2119/8174)

  This may have already been discussed and rejected; I just cannot recall.

### S4.1

* Should Table 5 show that 0xe and 0xf are presently unassigned (and possibly
  therefore reserved)?

### S4.2

* To be clear, one of "ALU TO_LE" and "ALU TO_BE" is likely to be a no-op
  (depending upon the byte order of the host CPU architecture)?

### S4.3

* Should Table 7 show that 0xe and 0xf are presently unassigned (and possibly
  therefore reserved)?

### S4.3.1

* Consider indicating that this is an area for future work / out of scope of
  this document (since BTF is presently intended to be a separate document).

### S5

* Should Table 8 show that 0x7 is presently unassigned (and possibly
  therefore reserved)?

## Nits

### S7.1.1

* "included from this group" -> "included by this group"?

# Document Shepherd Write-Up for Group Documents

*This version is dated 4 July 2022.*

Thank you for your service as a document shepherd. Among the responsibilities is
answering the questions in this write-up to give helpful context to Last Call
and Internet Engineering Steering Group ([IESG][1]) reviewers, and your
diligence in completing it is appreciated. The full role of the shepherd is
further described in [RFC 4858][2]. You will need the cooperation of the authors
and editors to complete these checks.

Note that some numbered items contain multiple related questions; please be sure
to answer all of them.

## Document History

1. Does the working group (WG) consensus represent the strong concurrence of a
  few individuals, with others being silent, or did it reach broad agreement?


The working group has reached broad agreement with respect to the publication of this document. All of the key participants and implementers are in strong agreement that the document is ready to be progressed to the IESG.


2. Was there controversy about particular points, or were there decisions where
  the consensus was particularly rough?


The main points of controversy were the following:

- Instruction conformance groups [18]
Some of the technical advisors initially felt [19] that we should only have “legacy” and “rest” conformance groups. This resulted in several long and contentious discussions, as can be seen on the email thread in [19]. Thankfully, we ultimately got broad consensus on the conformance groups that are listed in the document now. Note that these conformance groups roughly reflect RISC-V conformance groups, and thus our expectation that vendors implementing BPF offload will be faced with roughly the same constraints as those anticipated by vendors implementing RISC-V chips. However, while the conformance groups are quite similar, they do have some differences due to e.g. the presence of legacy BPF packet instructions which are included in the historical “packet” BPF conformance group.

- callx instruction [20]
The question of whether to include an indirect call instruction by helper ID was debated over several email threads, and discussed at IETF 119. Ultimately, broad consensus was reached on BPF_JMP | BPF_X not being appropriate to include in the current iteration of the standard. While clang can be made to emit an indirect call when compiled with -O0, and with the helper pointer not declared const, it was decided at IETF 119 that this isn’t supported or intended behavior, and that would decide on the semantics of indirect calls at a later time.

- BPF memory model [21]
One member of the WG brought up that the ISA is missing a memory model, which would inform expected semantics of e.g. atomic instructions, as well as whether an address space is flat, etc. In the end, it was decided and agreed upon with broad consensus to defer this to an extension of the ISA [22]. For now, BPF matches the Linux Kernel Memory Model (LKMM). For posterity, this was discussed in some detail at IETF 118 [22].


3. Has anyone threatened an appeal or otherwise indicated extreme discontent? If
  so, please summarize the areas of conflict in separate email messages to the
  responsible Area Director. (It should be in a separate email because this
  questionnaire is publicly available.)

No


4. For protocol documents, are there existing implementations of the contents of
  the document? Have a significant number of potential implementers indicated
  plans to implement? Are any existing implementations reported somewhere,
  either in the document itself (as [RFC 7942][3] recommends) or elsewhere
  (where)?

There are several widely-used implementations of the BPF ISA in industry. These implementations include but are not limited to BPF in Linux [23], BPF in Windows [24], and uBPF [25].


## Additional Reviews

5. Do the contents of this document closely interact with technologies in other
  IETF working groups or external organizations, and would it therefore benefit
  from their review? Have those reviews occurred? If yes, describe which
  reviews took place.

No


6. Describe how the document meets any required formal expert review criteria,
  such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

N/A


7. If the document contains a YANG module, has the final version of the module
  been checked with any of the [recommended validation tools][4] for syntax and
  formatting validation? If there are any resulting errors or warnings, what is
  the justification for not fixing them at this time? Does the YANG module
  comply with the Network Management Datastore Architecture (NMDA) as specified
  in [RFC 8342][5]?

N/A


8. Describe reviews and automated checks performed to validate sections of the
  final version of the document written in a formal language, such as XML code,
  BNF rules, MIB definitions, CBOR's CDDL, etc.


N/A

## Document Shepherd Checks

9. Based on the shepherd's review of the document, is it their opinion that this
  document is needed, clearly written, complete, correctly designed, and ready
  to be handed off to the responsible Area Director?

Yes



10. Several IETF Areas have assembled [lists of common issues that their
    reviewers encounter][6]. For which areas have such issues been identified
    and addressed? For which does this still need to happen in subsequent
    reviews?

After reading over Internet Area (int) common issues [26], all such issues should be addressed.


11. What type of RFC publication is being requested on the IETF stream ([Best
    Current Practice][12], [Proposed Standard, Internet Standard][13],
    [Informational, Experimental or Historic][14])? Why is this the proper type
    of RFC? Do all Datatracker state attributes correctly reflect this intent?

The RFC publication type being requested is Proposed Standard. This type was chosen because the BPF Instruction Set Architecture is stable, and is already widely implemented and used across industry.

12. Have reasonable efforts been made to remind all authors of the intellectual
    property rights (IPR) disclosure obligations described in [BCP 79][7]? To
    the best of your knowledge, have all required disclosures been filed? If
    not, explain why. If yes, summarize any relevant discussion, including links
    to publicly-available messages when applicable.

Yes. This was discussed at length, and addressed before the BPF working group was formed, as in e.g. [27]. To the best of our knowledge, all authors and contributors are aware of all IPR disclosure obligations, and all required disclosures have been filed.


13. Has each author, editor, and contributor shown their willingness to be
    listed as such? If the total number of authors and editors on the front page
    is greater than five, please provide a justification.

Yes



14. Document any remaining I-D nits in this document. Simply running the [idnits
    tool][8] is not enough; please review the ["Content Guidelines" on
    authors.ietf.org][15]. (Also note that the current idnits tool generates
    some incorrect warnings; a rewrite is underway.)

The only remaining nit is that some lines in the document exceed the maximum width of 72 characters. This width violation appears to occur for certain tables that are rendered in text using the XML-to-TXT conversion tool. By wrapping certain columns, such as the “description” column in the conformance group registry table in section 7.1, the width violation should no longer be an issue. Thus, for now we’ll leave the task of adjusting the width of any excessively-wide tables to the RFC editor.


15. Should any informative references be normative or vice-versa? See the [IESG
    Statement on Normative and Informative References][16].

No


16. List any normative references that are not freely available to anyone. Did
    the community have sufficient access to review any such normative
    references?

N/A


17. Are there any normative downward references (see [RFC 3967][9] and [BCP
    97][10]) that are not already listed in the [DOWNREF registry][17]? If so,
    list them.

No


18. Are there normative references to documents that are not ready to be
    submitted to the IESG for publication or are otherwise in an unclear state?
    If so, what is the plan for their completion?

No. The ISA document will likely be a normative reference for other documents published by the WG, but it does not contain any normative references to documents that are not ready to be submitted to the IESG for publication.


19. Will publication of this document change the status of any existing RFCs? If
    so, does the Datatracker metadata correctly reflect this and are those RFCs
    listed on the title page, in the abstract, and discussed in the
    introduction? If not, explain why and point to the part of the document
    where the relationship of this document to these other RFCs is discussed.

No


20. Describe the document shepherd's review of the IANA considerations section,
    especially with regard to its consistency with the body of the document.
    Confirm that all aspects of the document requiring IANA assignments are
    associated with the appropriate reservations in IANA registries. Confirm
    that any referenced IANA registries have been clearly identified. Confirm
    that each newly created IANA registry specifies its initial contents,
    allocations procedures, and a reasonable name (see [RFC 8126][11]).

All aspects of the document regarding IANA assignments are enumerated in Chapter 5: IANA Considerations and the document Appendix. The document contains no references to existing IANA registries. The proposals for newly created IANA registries include the following:

- BPF Instruction Conformance Group Registry
- BPF Instruction Set Registry

Both proposals include reasonable names, clear descriptions of the contents and meaning of each field in an entry, and procedures for adding and deprecating entries.

Initial entries for the BPF Instruction Conformance Group Registry are enumerated in section 5.1. BPF Instruction Conformance Group Registry. Initial entries for the BPF Instruction Set Registry are enumerated in the document Appendix.


21. List any new IANA registries that require Designated Expert Review for
    future allocations. Are the instructions to the Designated Expert clear?
    Please include suggestions of designated experts, if appropriate.

None of the IANA registries require Designated Expert Review.


[1]: https://www.ietf.org/about/groups/iesg/
[2]: https://www.rfc-editor.org/rfc/rfc4858.html
[3]: https://www.rfc-editor.org/rfc/rfc7942.html
[4]: https://wiki.ietf.org/group/ops/yang-review-tools
[5]: https://www.rfc-editor.org/rfc/rfc8342.html
[6]: https://wiki.ietf.org/group/iesg/ExpertTopics
[7]: https://www.rfc-editor.org/info/bcp79
[8]: https://www.ietf.org/tools/idnits/
[9]: https://www.rfc-editor.org/rfc/rfc3967.html
[10]: https://www.rfc-editor.org/info/bcp97
[11]: https://www.rfc-editor.org/rfc/rfc8126.html
[12]: https://www.rfc-editor.org/rfc/rfc2026.html#section-5
[13]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.1
[14]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.2
[15]: https://authors.ietf.org/en/content-guidelines-overview
[16]: https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/
[17]: https://datatracker.ietf.org/doc/downref/
[18]: https://mailarchive.ietf.org/arch/msg/bpf/W_GWZeh3cUPN0o1D0Lxwwbldfi0/
[19]: https://mailarchive.ietf.org/arch/msg/bpf/_CViBgpJOIQM0fvKcHWQCpCRFvg/
[20]: https://mailarchive.ietf.org/arch/msg/bpf/JNrxzJiBd09zaqU_pVeQ4s8mqKg/
[21]: https://mailarchive.ietf.org/arch/msg/bpf/8Fkl_dExCX-YbPGOmWbG4SJFBKw/
[22]: https://mailarchive.ietf.org/arch/msg/bpf/_WoygSMs8VP6QNG6A8qRtFl0Hgw/
[23]: https://docs.kernel.org/bpf/
[24]: https://github.com/microsoft/ebpf-for-windows
[25]: https://github.com/iovisor/ubpf
[26]: https://wiki.ietf.org/group/int/IntAreaIssues
[27]: https://mailarchive.ietf.org/arch/msg/bpf/VMU0nSo-T71QfXC50Q1Bu2ejD_g/

# Document Shepherd Write-Up for Group Documents

*This version is dated 4 July 2022.*

Thank you for your service as a document shepherd. Among the responsibilities is
answering the questions in this write-up to give helpful context to Last Call
and Internet Engineering Steering Group ([IESG][1]) reviewers, and your
diligence in completing it is appreciated. The full role of the shepherd is
further described in [RFC 4858][2]. You will need the cooperation of the authors
and editors to complete these checks.

Note that some numbered items contain multiple related questions; please be sure
to answer all of them.

## Document History

1. Does the working group (WG) consensus represent the strong concurrence of a
  few individuals, with others being silent, or did it reach broad agreement?


The working group has reached broad agreement with respect to the publication of this document. All of the key participants and implementers are in strong agreement that the document is ready to be progressed to the IESG.


2. Was there controversy about particular points, or were there decisions where
  the consensus was particularly rough?


The main points of controversy were the following:

- Instruction conformance groups [18]
Some of the technical advisors initially felt [19] that we should only have “legacy” and “rest” conformance groups. This resulted in several long and contentious discussions, as can be seen on the email thread in [19]. Thankfully, we ultimately got broad consensus on the conformance groups that are listed in the document now. Note that these conformance groups roughly reflect RISC-V conformance groups, and thus our expectation that vendors implementing BPF offload will be faced with roughly the same constraints as those anticipated by vendors implementing RISC-V chips. However, while the conformance groups are quite similar, they do have some differences due to e.g. the presence of legacy BPF packet instructions which are included in the historical “packet” BPF conformance group.

- callx instruction [20]
The question of whether to include an indirect call instruction by helper ID was debated over several email threads, and discussed at IETF 119. Ultimately, broad consensus was reached on BPF_JMP | BPF_X not being appropriate to include in the current iteration of the standard. While clang can be made to emit an indirect call when compiled with -O0, and with the helper pointer not declared const, it was decided at IETF 119 that this isn’t supported or intended behavior, and that would decide on the semantics of indirect calls at a later time.

- BPF memory model [21]
One member of the WG brought up that the ISA is missing a memory model, which would inform expected semantics of e.g. atomic instructions, as well as whether an address space is flat, etc. In the end, it was decided and agreed upon with broad consensus to defer this to an extension of the ISA [22]. For now, BPF matches the Linux Kernel Memory Model (LKMM). For posterity, this was discussed in some detail at IETF 118 [22].


3. Has anyone threatened an appeal or otherwise indicated extreme discontent? If
  so, please summarize the areas of conflict in separate email messages to the
  responsible Area Director. (It should be in a separate email because this
  questionnaire is publicly available.)

No


4. For protocol documents, are there existing implementations of the contents of
  the document? Have a significant number of potential implementers indicated
  plans to implement? Are any existing implementations reported somewhere,
  either in the document itself (as [RFC 7942][3] recommends) or elsewhere
  (where)?

There are several widely-used implementations of the BPF ISA in industry. These implementations include but are not limited to BPF in Linux [23], BPF in Windows [24], and uBPF [25].


## Additional Reviews

5. Do the contents of this document closely interact with technologies in other
  IETF working groups or external organizations, and would it therefore benefit
  from their review? Have those reviews occurred? If yes, describe which
  reviews took place.

No


6. Describe how the document meets any required formal expert review criteria,
  such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

N/A


7. If the document contains a YANG module, has the final version of the module
  been checked with any of the [recommended validation tools][4] for syntax and
  formatting validation? If there are any resulting errors or warnings, what is
  the justification for not fixing them at this time? Does the YANG module
  comply with the Network Management Datastore Architecture (NMDA) as specified
  in [RFC 8342][5]?

N/A


8. Describe reviews and automated checks performed to validate sections of the
  final version of the document written in a formal language, such as XML code,
  BNF rules, MIB definitions, CBOR's CDDL, etc.


N/A

## Document Shepherd Checks

9. Based on the shepherd's review of the document, is it their opinion that this
  document is needed, clearly written, complete, correctly designed, and ready
  to be handed off to the responsible Area Director?

Yes



10. Several IETF Areas have assembled [lists of common issues that their
    reviewers encounter][6]. For which areas have such issues been identified
    and addressed? For which does this still need to happen in subsequent
    reviews?

After reading over Internet Area (int) common issues [26], all such issues should be addressed.


11. What type of RFC publication is being requested on the IETF stream ([Best
    Current Practice][12], [Proposed Standard, Internet Standard][13],
    [Informational, Experimental or Historic][14])? Why is this the proper type
    of RFC? Do all Datatracker state attributes correctly reflect this intent?

The RFC publication type being requested is Proposed Standard. This type was chosen because the BPF Instruction Set Architecture is stable, and is already widely implemented and used across industry.

12. Have reasonable efforts been made to remind all authors of the intellectual
    property rights (IPR) disclosure obligations described in [BCP 79][7]? To
    the best of your knowledge, have all required disclosures been filed? If
    not, explain why. If yes, summarize any relevant discussion, including links
    to publicly-available messages when applicable.

Yes. This was discussed at length, and addressed before the BPF working group was formed, as in e.g. [27]. To the best of our knowledge, all authors and contributors are aware of all IPR disclosure obligations, and all required disclosures have been filed.


13. Has each author, editor, and contributor shown their willingness to be
    listed as such? If the total number of authors and editors on the front page
    is greater than five, please provide a justification.

Yes



14. Document any remaining I-D nits in this document. Simply running the [idnits
    tool][8] is not enough; please review the ["Content Guidelines" on
    authors.ietf.org][15]. (Also note that the current idnits tool generates
    some incorrect warnings; a rewrite is underway.)

The only remaining nit is that some lines in the document exceed the maximum width of 72 characters. This width violation appears to occur for certain tables that are rendered in text using the XML-to-TXT conversion tool. By wrapping certain columns, such as the “description” column in the conformance group registry table in section 7.1, the width violation should no longer be an issue. Thus, for now we’ll leave the task of adjusting the width of any excessively-wide tables to the RFC editor.


15. Should any informative references be normative or vice-versa? See the [IESG
    Statement on Normative and Informative References][16].

No


16. List any normative references that are not freely available to anyone. Did
    the community have sufficient access to review any such normative
    references?

N/A


17. Are there any normative downward references (see [RFC 3967][9] and [BCP
    97][10]) that are not already listed in the [DOWNREF registry][17]? If so,
    list them.

No


18. Are there normative references to documents that are not ready to be
    submitted to the IESG for publication or are otherwise in an unclear state?
    If so, what is the plan for their completion?

No. The ISA document will likely be a normative reference for other documents published by the WG, but it does not contain any normative references to documents that are not ready to be submitted to the IESG for publication.


19. Will publication of this document change the status of any existing RFCs? If
    so, does the Datatracker metadata correctly reflect this and are those RFCs
    listed on the title page, in the abstract, and discussed in the
    introduction? If not, explain why and point to the part of the document
    where the relationship of this document to these other RFCs is discussed.

No


20. Describe the document shepherd's review of the IANA considerations section,
    especially with regard to its consistency with the body of the document.
    Confirm that all aspects of the document requiring IANA assignments are
    associated with the appropriate reservations in IANA registries. Confirm
    that any referenced IANA registries have been clearly identified. Confirm
    that each newly created IANA registry specifies its initial contents,
    allocations procedures, and a reasonable name (see [RFC 8126][11]).

All aspects of the document regarding IANA assignments are enumerated in Chapter 5: IANA Considerations and the document Appendix. The document contains no references to existing IANA registries. The proposals for newly created IANA registries include the following:

- BPF Instruction Conformance Group Registry
- BPF Instruction Set Registry

Both proposals include reasonable names, clear descriptions of the contents and meaning of each field in an entry, and procedures for adding and deprecating entries.

Initial entries for the BPF Instruction Conformance Group Registry are enumerated in section 5.1. BPF Instruction Conformance Group Registry. Initial entries for the BPF Instruction Set Registry are enumerated in the document Appendix.


21. List any new IANA registries that require Designated Expert Review for
    future allocations. Are the instructions to the Designated Expert clear?
    Please include suggestions of designated experts, if appropriate.

None of the IANA registries require Designated Expert Review.


[1]: https://www.ietf.org/about/groups/iesg/
[2]: https://www.rfc-editor.org/rfc/rfc4858.html
[3]: https://www.rfc-editor.org/rfc/rfc7942.html
[4]: https://wiki.ietf.org/group/ops/yang-review-tools
[5]: https://www.rfc-editor.org/rfc/rfc8342.html
[6]: https://wiki.ietf.org/group/iesg/ExpertTopics
[7]: https://www.rfc-editor.org/info/bcp79
[8]: https://www.ietf.org/tools/idnits/
[9]: https://www.rfc-editor.org/rfc/rfc3967.html
[10]: https://www.rfc-editor.org/info/bcp97
[11]: https://www.rfc-editor.org/rfc/rfc8126.html
[12]: https://www.rfc-editor.org/rfc/rfc2026.html#section-5
[13]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.1
[14]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.2
[15]: https://authors.ietf.org/en/content-guidelines-overview
[16]: https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/
[17]: https://datatracker.ietf.org/doc/downref/
[18]: https://mailarchive.ietf.org/arch/msg/bpf/W_GWZeh3cUPN0o1D0Lxwwbldfi0/
[19]: https://mailarchive.ietf.org/arch/msg/bpf/_CViBgpJOIQM0fvKcHWQCpCRFvg/
[20]: https://mailarchive.ietf.org/arch/msg/bpf/JNrxzJiBd09zaqU_pVeQ4s8mqKg/
[21]: https://mailarchive.ietf.org/arch/msg/bpf/8Fkl_dExCX-YbPGOmWbG4SJFBKw/
[22]: https://mailarchive.ietf.org/arch/msg/bpf/_WoygSMs8VP6QNG6A8qRtFl0Hgw/
[23]: https://docs.kernel.org/bpf/
[24]: https://github.com/microsoft/ebpf-for-windows
[25]: https://github.com/iovisor/ubpf
[26]: https://wiki.ietf.org/group/int/IntAreaIssues
[27]: https://mailarchive.ietf.org/arch/msg/bpf/VMU0nSo-T71QfXC50Q1Bu2ejD_g/

# Document Shepherd Write-Up for Group Documents

*This version is dated 4 July 2022.*

Thank you for your service as a document shepherd. Among the responsibilities is
answering the questions in this write-up to give helpful context to Last Call
and Internet Engineering Steering Group ([IESG][1]) reviewers, and your
diligence in completing it is appreciated. The full role of the shepherd is
further described in [RFC 4858][2]. You will need the cooperation of the authors
and editors to complete these checks.

Note that some numbered items contain multiple related questions; please be sure
to answer all of them.

## Document History

1. Does the working group (WG) consensus represent the strong concurrence of a
  few individuals, with others being silent, or did it reach broad agreement?


The working group has reached broad agreement with respect to the publication of this document. All of the key participants and implementers are in strong agreement that the document is ready to be progressed to the IESG.


2. Was there controversy about particular points, or were there decisions where
  the consensus was particularly rough?


The main points of controversy were the following:

- Instruction conformance groups [18]
Some of the technical advisors initially felt [19] that we should only have “legacy” and “rest” conformance groups. This resulted in several long and contentious discussions, as can be seen on the email thread in [19]. Thankfully, we ultimately got broad consensus on the conformance groups that are listed in the document now. Note that these conformance groups roughly reflect RISC-V conformance groups, and thus our expectation that vendors implementing BPF offload will be faced with roughly the same constraints as those anticipated by vendors implementing RISC-V chips. However, while the conformance groups are quite similar, they do have some differences due to e.g. the presence of legacy BPF packet instructions which are included in the historical “packet” BPF conformance group.

- callx instruction [20]
The question of whether to include an indirect call instruction by helper ID was debated over several email threads, and discussed at IETF 119. Ultimately, broad consensus was reached on BPF_JMP | BPF_X not being appropriate to include in the current iteration of the standard. While clang can be made to emit an indirect call when compiled with -O0, and with the helper pointer not declared const, it was decided at IETF 119 that this isn’t supported or intended behavior, and that would decide on the semantics of indirect calls at a later time.

- BPF memory model [21]
One member of the WG brought up that the ISA is missing a memory model, which would inform expected semantics of e.g. atomic instructions, as well as whether an address space is flat, etc. In the end, it was decided and agreed upon with broad consensus to defer this to an extension of the ISA [22]. For now, BPF matches the Linux Kernel Memory Model (LKMM). For posterity, this was discussed in some detail at IETF 118 [22].


3. Has anyone threatened an appeal or otherwise indicated extreme discontent? If
  so, please summarize the areas of conflict in separate email messages to the
  responsible Area Director. (It should be in a separate email because this
  questionnaire is publicly available.)

No


4. For protocol documents, are there existing implementations of the contents of
  the document? Have a significant number of potential implementers indicated
  plans to implement? Are any existing implementations reported somewhere,
  either in the document itself (as [RFC 7942][3] recommends) or elsewhere
  (where)?

There are several widely-used implementations of the BPF ISA in industry. These implementations include but are not limited to BPF in Linux [23], BPF in Windows [24], and uBPF [25].


## Additional Reviews

5. Do the contents of this document closely interact with technologies in other
  IETF working groups or external organizations, and would it therefore benefit
  from their review? Have those reviews occurred? If yes, describe which
  reviews took place.

No


6. Describe how the document meets any required formal expert review criteria,
  such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

N/A


7. If the document contains a YANG module, has the final version of the module
  been checked with any of the [recommended validation tools][4] for syntax and
  formatting validation? If there are any resulting errors or warnings, what is
  the justification for not fixing them at this time? Does the YANG module
  comply with the Network Management Datastore Architecture (NMDA) as specified
  in [RFC 8342][5]?

N/A


8. Describe reviews and automated checks performed to validate sections of the
  final version of the document written in a formal language, such as XML code,
  BNF rules, MIB definitions, CBOR's CDDL, etc.


N/A

## Document Shepherd Checks

9. Based on the shepherd's review of the document, is it their opinion that this
  document is needed, clearly written, complete, correctly designed, and ready
  to be handed off to the responsible Area Director?

Yes



10. Several IETF Areas have assembled [lists of common issues that their
    reviewers encounter][6]. For which areas have such issues been identified
    and addressed? For which does this still need to happen in subsequent
    reviews?

After reading over Internet Area (int) common issues [26], all such issues should be addressed.


11. What type of RFC publication is being requested on the IETF stream ([Best
    Current Practice][12], [Proposed Standard, Internet Standard][13],
    [Informational, Experimental or Historic][14])? Why is this the proper type
    of RFC? Do all Datatracker state attributes correctly reflect this intent?

The RFC publication type being requested is Proposed Standard. This type was chosen because the BPF Instruction Set Architecture is stable, and is already widely implemented and used across industry.

12. Have reasonable efforts been made to remind all authors of the intellectual
    property rights (IPR) disclosure obligations described in [BCP 79][7]? To
    the best of your knowledge, have all required disclosures been filed? If
    not, explain why. If yes, summarize any relevant discussion, including links
    to publicly-available messages when applicable.

Yes. This was discussed at length, and addressed before the BPF working group was formed, as in e.g. [27]. To the best of our knowledge, all authors and contributors are aware of all IPR disclosure obligations, and all required disclosures have been filed.


13. Has each author, editor, and contributor shown their willingness to be
    listed as such? If the total number of authors and editors on the front page
    is greater than five, please provide a justification.

Yes



14. Document any remaining I-D nits in this document. Simply running the [idnits
    tool][8] is not enough; please review the ["Content Guidelines" on
    authors.ietf.org][15]. (Also note that the current idnits tool generates
    some incorrect warnings; a rewrite is underway.)

This should now be addressed.


15. Should any informative references be normative or vice-versa? See the [IESG
    Statement on Normative and Informative References][16].

No


16. List any normative references that are not freely available to anyone. Did
    the community have sufficient access to review any such normative
    references?

N/A


17. Are there any normative downward references (see [RFC 3967][9] and [BCP
    97][10]) that are not already listed in the [DOWNREF registry][17]? If so,
    list them.

No


18. Are there normative references to documents that are not ready to be
    submitted to the IESG for publication or are otherwise in an unclear state?
    If so, what is the plan for their completion?

No. The ISA document will likely be a normative reference for other documents published by the WG, but it does not contain any normative references to documents that are not ready to be submitted to the IESG for publication.


19. Will publication of this document change the status of any existing RFCs? If
    so, does the Datatracker metadata correctly reflect this and are those RFCs
    listed on the title page, in the abstract, and discussed in the
    introduction? If not, explain why and point to the part of the document
    where the relationship of this document to these other RFCs is discussed.

No


20. Describe the document shepherd's review of the IANA considerations section,
    especially with regard to its consistency with the body of the document.
    Confirm that all aspects of the document requiring IANA assignments are
    associated with the appropriate reservations in IANA registries. Confirm
    that any referenced IANA registries have been clearly identified. Confirm
    that each newly created IANA registry specifies its initial contents,
    allocations procedures, and a reasonable name (see [RFC 8126][11]).

All aspects of the document regarding IANA assignments are enumerated in Chapter 5: IANA Considerations and the document Appendix. The document contains no references to existing IANA registries. The proposals for newly created IANA registries include the following:

- BPF Instruction Conformance Group Registry
- BPF Instruction Set Registry

Both proposals include reasonable names, clear descriptions of the contents and meaning of each field in an entry, and procedures for adding and deprecating entries.

Initial entries for the BPF Instruction Conformance Group Registry are enumerated in section 5.1. BPF Instruction Conformance Group Registry. Initial entries for the BPF Instruction Set Registry are enumerated in the document Appendix.


21. List any new IANA registries that require Designated Expert Review for
    future allocations. Are the instructions to the Designated Expert clear?
    Please include suggestions of designated experts, if appropriate.

None of the IANA registries require Designated Expert Review.


[1]: https://www.ietf.org/about/groups/iesg/
[2]: https://www.rfc-editor.org/rfc/rfc4858.html
[3]: https://www.rfc-editor.org/rfc/rfc7942.html
[4]: https://wiki.ietf.org/group/ops/yang-review-tools
[5]: https://www.rfc-editor.org/rfc/rfc8342.html
[6]: https://wiki.ietf.org/group/iesg/ExpertTopics
[7]: https://www.rfc-editor.org/info/bcp79
[8]: https://www.ietf.org/tools/idnits/
[9]: https://www.rfc-editor.org/rfc/rfc3967.html
[10]: https://www.rfc-editor.org/info/bcp97
[11]: https://www.rfc-editor.org/rfc/rfc8126.html
[12]: https://www.rfc-editor.org/rfc/rfc2026.html#section-5
[13]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.1
[14]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.2
[15]: https://authors.ietf.org/en/content-guidelines-overview
[16]: https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/
[17]: https://datatracker.ietf.org/doc/downref/
[18]: https://mailarchive.ietf.org/arch/msg/bpf/W_GWZeh3cUPN0o1D0Lxwwbldfi0/
[19]: https://mailarchive.ietf.org/arch/msg/bpf/_CViBgpJOIQM0fvKcHWQCpCRFvg/
[20]: https://mailarchive.ietf.org/arch/msg/bpf/JNrxzJiBd09zaqU_pVeQ4s8mqKg/
[21]: https://mailarchive.ietf.org/arch/msg/bpf/8Fkl_dExCX-YbPGOmWbG4SJFBKw/
[22]: https://mailarchive.ietf.org/arch/msg/bpf/_WoygSMs8VP6QNG6A8qRtFl0Hgw/
[23]: https://docs.kernel.org/bpf/
[24]: https://github.com/microsoft/ebpf-for-windows
[25]: https://github.com/iovisor/ubpf
[26]: https://wiki.ietf.org/group/int/IntAreaIssues
[27]: https://mailarchive.ietf.org/arch/msg/bpf/VMU0nSo-T71QfXC50Q1Bu2ejD_g/

# Document Shepherd Write-Up for Group Documents

*This version is dated 4 July 2022.*

Thank you for your service as a document shepherd. Among the responsibilities is
answering the questions in this write-up to give helpful context to Last Call
and Internet Engineering Steering Group ([IESG][1]) reviewers, and your
diligence in completing it is appreciated. The full role of the shepherd is
further described in [RFC 4858][2]. You will need the cooperation of the authors
and editors to complete these checks.

Note that some numbered items contain multiple related questions; please be sure
to answer all of them.

## Document History

1. Does the working group (WG) consensus represent the strong concurrence of a
  few individuals, with others being silent, or did it reach broad agreement?


The working group has reached broad agreement with respect to the publication of this document. All of the key participants and implementers are in strong agreement that the document is ready to be progressed to the IESG.


2. Was there controversy about particular points, or were there decisions where
  the consensus was particularly rough?


The main points of controversy were the following:

- Instruction conformance groups [18]
Some of the technical advisors initially felt [19] that we should only have “legacy” and “rest” conformance groups. This resulted in several long and contentious discussions, as can be seen on the email thread in [19]. Thankfully, we ultimately got broad consensus on the conformance groups that are listed in the document now. Note that these conformance groups roughly reflect RISC-V conformance groups, and thus our expectation that vendors implementing BPF offload will be faced with roughly the same constraints as those anticipated by vendors implementing RISC-V chips. However, while the conformance groups are quite similar, they do have some differences due to e.g. the presence of legacy BPF packet instructions which are included in the historical “packet” BPF conformance group.

- callx instruction [20]
The question of whether to include an indirect call instruction by helper ID was debated over several email threads, and discussed at IETF 119. Ultimately, broad consensus was reached on BPF_JMP | BPF_X not being appropriate to include in the current iteration of the standard. While clang can be made to emit an indirect call when compiled with -O0, and with the helper pointer not declared const, it was decided at IETF 119 that this isn’t supported or intended behavior, and that would decide on the semantics of indirect calls at a later time.

- BPF memory model [21]
One member of the WG brought up that the ISA is missing a memory model, which would inform expected semantics of e.g. atomic instructions, as well as whether an address space is flat, etc. In the end, it was decided and agreed upon with broad consensus to defer this to an extension of the ISA [22]. For now, BPF matches the Linux Kernel Memory Model (LKMM). For posterity, this was discussed in some detail at IETF 118 [22].


3. Has anyone threatened an appeal or otherwise indicated extreme discontent? If
  so, please summarize the areas of conflict in separate email messages to the
  responsible Area Director. (It should be in a separate email because this
  questionnaire is publicly available.)

No


4. For protocol documents, are there existing implementations of the contents of
  the document? Have a significant number of potential implementers indicated
  plans to implement? Are any existing implementations reported somewhere,
  either in the document itself (as [RFC 7942][3] recommends) or elsewhere
  (where)?

There are several widely-used implementations of the BPF ISA in industry. These implementations include but are not limited to BPF in Linux [23], BPF in Windows [24], and uBPF [25].


## Additional Reviews

5. Do the contents of this document closely interact with technologies in other
  IETF working groups or external organizations, and would it therefore benefit
  from their review? Have those reviews occurred? If yes, describe which
  reviews took place.

No


6. Describe how the document meets any required formal expert review criteria,
  such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

N/A


7. If the document contains a YANG module, has the final version of the module
  been checked with any of the [recommended validation tools][4] for syntax and
  formatting validation? If there are any resulting errors or warnings, what is
  the justification for not fixing them at this time? Does the YANG module
  comply with the Network Management Datastore Architecture (NMDA) as specified
  in [RFC 8342][5]?

N/A


8. Describe reviews and automated checks performed to validate sections of the
  final version of the document written in a formal language, such as XML code,
  BNF rules, MIB definitions, CBOR's CDDL, etc.


N/A

## Document Shepherd Checks

9. Based on the shepherd's review of the document, is it their opinion that this
  document is needed, clearly written, complete, correctly designed, and ready
  to be handed off to the responsible Area Director?

Yes



10. Several IETF Areas have assembled [lists of common issues that their
    reviewers encounter][6]. For which areas have such issues been identified
    and addressed? For which does this still need to happen in subsequent
    reviews?

After reading over Internet Area (int) common issues [26], all such issues should be addressed.


11. What type of RFC publication is being requested on the IETF stream ([Best
    Current Practice][12], [Proposed Standard, Internet Standard][13],
    [Informational, Experimental or Historic][14])? Why is this the proper type
    of RFC? Do all Datatracker state attributes correctly reflect this intent?

The RFC publication type being requested is Proposed Standard. This type was chosen because the BPF Instruction Set Architecture is stable, and is already widely implemented and used across industry.

12. Have reasonable efforts been made to remind all authors of the intellectual
    property rights (IPR) disclosure obligations described in [BCP 79][7]? To
    the best of your knowledge, have all required disclosures been filed? If
    not, explain why. If yes, summarize any relevant discussion, including links
    to publicly-available messages when applicable.

Yes. This was discussed at length, and addressed before the BPF working group was formed, as in e.g. [27]. To the best of our knowledge, all authors and contributors are aware of all IPR disclosure obligations, and all required disclosures have been filed.


13. Has each author, editor, and contributor shown their willingness to be
    listed as such? If the total number of authors and editors on the front page
    is greater than five, please provide a justification.

Yes



14. Document any remaining I-D nits in this document. Simply running the [idnits
    tool][8] is not enough; please review the ["Content Guidelines" on
    authors.ietf.org][15]. (Also note that the current idnits tool generates
    some incorrect warnings; a rewrite is underway.)


The expectation is for those to be addressed in the next several weeks.

15. Should any informative references be normative or vice-versa? See the [IESG
    Statement on Normative and Informative References][16].

No


16. List any normative references that are not freely available to anyone. Did
    the community have sufficient access to review any such normative
    references?

N/A


17. Are there any normative downward references (see [RFC 3967][9] and [BCP
    97][10]) that are not already listed in the [DOWNREF registry][17]? If so,
    list them.

No


18. Are there normative references to documents that are not ready to be
    submitted to the IESG for publication or are otherwise in an unclear state?
    If so, what is the plan for their completion?

No. The ISA document will likely be a normative reference for other documents published by the WG, but it does not contain any normative references to documents that are not ready to be submitted to the IESG for publication.


19. Will publication of this document change the status of any existing RFCs? If
    so, does the Datatracker metadata correctly reflect this and are those RFCs
    listed on the title page, in the abstract, and discussed in the
    introduction? If not, explain why and point to the part of the document
    where the relationship of this document to these other RFCs is discussed.

No


20. Describe the document shepherd's review of the IANA considerations section,
    especially with regard to its consistency with the body of the document.
    Confirm that all aspects of the document requiring IANA assignments are
    associated with the appropriate reservations in IANA registries. Confirm
    that any referenced IANA registries have been clearly identified. Confirm
    that each newly created IANA registry specifies its initial contents,
    allocations procedures, and a reasonable name (see [RFC 8126][11]).

All aspects of the document regarding IANA assignments are enumerated in Chapter 5: IANA Considerations and the document Appendix. The document contains no references to existing IANA registries. The proposals for newly created IANA registries include the following:

- BPF Instruction Conformance Group Registry
- BPF Instruction Set Registry

Both proposals include reasonable names, clear descriptions of the contents and meaning of each field in an entry, and procedures for adding and deprecating entries.

Initial entries for the BPF Instruction Conformance Group Registry are enumerated in section 5.1. BPF Instruction Conformance Group Registry. Initial entries for the BPF Instruction Set Registry are enumerated in the document Appendix.


21. List any new IANA registries that require Designated Expert Review for
    future allocations. Are the instructions to the Designated Expert clear?
    Please include suggestions of designated experts, if appropriate.

None of the IANA registries require Designated Expert Review.


[1]: https://www.ietf.org/about/groups/iesg/
[2]: https://www.rfc-editor.org/rfc/rfc4858.html
[3]: https://www.rfc-editor.org/rfc/rfc7942.html
[4]: https://wiki.ietf.org/group/ops/yang-review-tools
[5]: https://www.rfc-editor.org/rfc/rfc8342.html
[6]: https://wiki.ietf.org/group/iesg/ExpertTopics
[7]: https://www.rfc-editor.org/info/bcp79
[8]: https://www.ietf.org/tools/idnits/
[9]: https://www.rfc-editor.org/rfc/rfc3967.html
[10]: https://www.rfc-editor.org/info/bcp97
[11]: https://www.rfc-editor.org/rfc/rfc8126.html
[12]: https://www.rfc-editor.org/rfc/rfc2026.html#section-5
[13]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.1
[14]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.2
[15]: https://authors.ietf.org/en/content-guidelines-overview
[16]: https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/
[17]: https://datatracker.ietf.org/doc/downref/
[18]: https://mailarchive.ietf.org/arch/msg/bpf/W_GWZeh3cUPN0o1D0Lxwwbldfi0/
[19]: https://mailarchive.ietf.org/arch/msg/bpf/_CViBgpJOIQM0fvKcHWQCpCRFvg/
[20]: https://mailarchive.ietf.org/arch/msg/bpf/JNrxzJiBd09zaqU_pVeQ4s8mqKg/
[21]: https://mailarchive.ietf.org/arch/msg/bpf/8Fkl_dExCX-YbPGOmWbG4SJFBKw/
[22]: https://mailarchive.ietf.org/arch/msg/bpf/_WoygSMs8VP6QNG6A8qRtFl0Hgw/
[23]: https://docs.kernel.org/bpf/
[24]: https://github.com/microsoft/ebpf-for-windows
[25]: https://github.com/iovisor/ubpf
[26]: https://wiki.ietf.org/group/int/IntAreaIssues
[27]: https://mailarchive.ietf.org/arch/msg/bpf/VMU0nSo-T71QfXC50Q1Bu2ejD_g/

# Document Shepherd Write-Up for Group Documents

*This version is dated 4 July 2022.*

Thank you for your service as a document shepherd. Among the responsibilities is
answering the questions in this write-up to give helpful context to Last Call
and Internet Engineering Steering Group ([IESG][1]) reviewers, and your
diligence in completing it is appreciated. The full role of the shepherd is
further described in [RFC 4858][2]. You will need the cooperation of the authors
and editors to complete these checks.

Note that some numbered items contain multiple related questions; please be sure
to answer all of them.

## Document History

1. Does the working group (WG) consensus represent the strong concurrence of a
  few individuals, with others being silent, or did it reach broad agreement?


The working group has reached broad agreement with respect to the publication of this document. Most of the WG community is fairly silent in that they haven’t participated much in discussions, but the main participants are all in strong agreement that the document is ready to be passed to the IESG.


2. Was there controversy about particular points, or were there decisions where
  the consensus was particularly rough?


The main points of controversy were the following:

- Instruction conformance groups [18]
Some of the technical advisors initially felt [19] that we should only have “legacy” and “rest” conformance groups. This resulted in several long and contentious discussions, as can be seen on the email thread in [19]. Thankfully, we ultimately got broad consensus on the conformance groups that are listed in the document now. Note that these conformance groups roughly reflect RISC-V conformance groups, and thus our expectation that vendors implementing BPF offload will be faced with roughly the same constraints as those anticipated by vendors implementing RISC-V chips. However, while the conformance groups are quite similar, they do have some differences due to e.g. the presence of legacy BPF packet instructions which are included in the historical “packet” BPF conformance group.

- callx instruction [20]
The question of whether to include an indirect call instruction by helper ID was debated over several email threads, and discussed at IETF 119. Ultimately, broad consensus was reached on BPF_JMP | BPF_X not being appropriate to include in the current iteration of the standard. While clang can be made to emit an indirect call when compiled with -O0, and with the helper pointer not declared const, it was decided at IETF 119 that this isn’t supported or intended behavior, and that would decide on the semantics of indirect calls at a later time.

- BPF memory model [21]
One member of the WG brought up that the ISA is missing a memory model, which would inform expected semantics of e.g. atomic instructions, as well as whether an address space is flat, etc. In the end, it was decided and agreed upon with broad consensus to defer this to an extension of the ISA [22]. For now, BPF matches the Linux Kernel Memory Model (LKMM). For posterity, this was discussed in some detail at IETF 118 [22].


3. Has anyone threatened an appeal or otherwise indicated extreme discontent? If
  so, please summarize the areas of conflict in separate email messages to the
  responsible Area Director. (It should be in a separate email because this
  questionnaire is publicly available.)

No


4. For protocol documents, are there existing implementations of the contents of
  the document? Have a significant number of potential implementers indicated
  plans to implement? Are any existing implementations reported somewhere,
  either in the document itself (as [RFC 7942][3] recommends) or elsewhere
  (where)?

While this is not a protocol document, there are several widely-used implementations of the BPF ISA in industry. These implementations include but are not limited to BPF in Linux [23], BPF in Windows [24], and uBPF [25].


## Additional Reviews

5. Do the contents of this document closely interact with technologies in other
  IETF working groups or external organizations, and would it therefore benefit
  from their review? Have those reviews occurred? If yes, describe which
  reviews took place.

No


6. Describe how the document meets any required formal expert review criteria,
  such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

N/A


7. If the document contains a YANG module, has the final version of the module
  been checked with any of the [recommended validation tools][4] for syntax and
  formatting validation? If there are any resulting errors or warnings, what is
  the justification for not fixing them at this time? Does the YANG module
  comply with the Network Management Datastore Architecture (NMDA) as specified
  in [RFC 8342][5]?

N/A


8. Describe reviews and automated checks performed to validate sections of the
  final version of the document written in a formal language, such as XML code,
  BNF rules, MIB definitions, CBOR's CDDL, etc.


XXX: Suresh and Erik


## Document Shepherd Checks

9. Based on the shepherd's review of the document, is it their opinion that this
  document is needed, clearly written, complete, correctly designed, and ready
  to be handed off to the responsible Area Director?

Yes [PENDING FINAL CHANGES BY DAVE THALER]



10. Several IETF Areas have assembled [lists of common issues that their
    reviewers encounter][6]. For which areas have such issues been identified
    and addressed? For which does this still need to happen in subsequent
    reviews?

After reading over Internet Area (int) common issues [26], all such issues should be addressed.


11. What type of RFC publication is being requested on the IETF stream ([Best
    Current Practice][12], [Proposed Standard, Internet Standard][13],
    [Informational, Experimental or Historic][14])? Why is this the proper type
    of RFC? Do all Datatracker state attributes correctly reflect this intent?

The RFC publication type being requested is Proposed Standard. This type was chosen because the BPF Instruction Set Architecture is stable, and is already widely implemented and used across industry. We believe that ‘Proposed Standard’ is more appropriate than ‘Internet Standard’, as this is the first standards document being published for BPF, and it remains to be seen what material impact the standard will have on the industry.


12. Have reasonable efforts been made to remind all authors of the intellectual
    property rights (IPR) disclosure obligations described in [BCP 79][7]? To
    the best of your knowledge, have all required disclosures been filed? If
    not, explain why. If yes, summarize any relevant discussion, including links
    to publicly-available messages when applicable.

Yes. This was discussed at length, and addressed before the BPF working group was formed, as in e.g. [27]. To the best of our knowledge, all authors and contributors are aware of all IPR disclosure obligations, and all required disclosures have been filed.


13. Has each author, editor, and contributor shown their willingness to be
    listed as such? If the total number of authors and editors on the front page
    is greater than five, please provide a justification.

Yes (right? XXX Suresh / Erik)



14. Document any remaining I-D nits in this document. Simply running the [idnits
    tool][8] is not enough; please review the ["Content Guidelines" on
    authors.ietf.org][15]. (Also note that the current idnits tool generates
    some incorrect warnings; a rewrite is underway.)

The following list describes outstanding nits: [28].  The most pertinent issues are the following:

- Missing an introduction section [29]
- Missing a Security Considerations section [30]
- Addressing line length exceeding 72 characters [31]

The expectation is for those to be addressed in the next several weeks.

15. Should any informative references be normative or vice-versa? See the [IESG
    Statement on Normative and Informative References][16].

No


16. List any normative references that are not freely available to anyone. Did
    the community have sufficient access to review any such normative
    references?

N/A


17. Are there any normative downward references (see [RFC 3967][9] and [BCP
    97][10]) that are not already listed in the [DOWNREF registry][17]? If so,
    list them.

No


18. Are there normative references to documents that are not ready to be
    submitted to the IESG for publication or are otherwise in an unclear state?
    If so, what is the plan for their completion?

No. The ISA document will likely be a normative reference for other documents published by the WG, but it does not contain any normative references to documents that are not ready to be submitted to the IESG for publication.


19. Will publication of this document change the status of any existing RFCs? If
    so, does the Datatracker metadata correctly reflect this and are those RFCs
    listed on the title page, in the abstract, and discussed in the
    introduction? If not, explain why and point to the part of the document
    where the relationship of this document to these other RFCs is discussed.

No


20. Describe the document shepherd's review of the IANA considerations section,
    especially with regard to its consistency with the body of the document.
    Confirm that all aspects of the document requiring IANA assignments are
    associated with the appropriate reservations in IANA registries. Confirm
    that any referenced IANA registries have been clearly identified. Confirm
    that each newly created IANA registry specifies its initial contents,
    allocations procedures, and a reasonable name (see [RFC 8126][11]).

All aspects of the document regarding IANA assignments are enumerated in Chapter 5: IANA Considerations and the document Appendix. The document contains no references to existing IANA registries. The proposals for newly created IANA registries include the following:

- BPF Instruction Conformance Group Registry
- BPF Instruction Set Registry

Both proposals include reasonable names, clear descriptions of the contents and meaning of each field in an entry, and procedures for adding and deprecating entries.

Initial entries for the BPF Instruction Conformance Group Registry are enumerated in section 5.1. BPF Instruction Conformance Group Registry. Initial entries for the BPF Instruction Set Registry are enumerated in the document Appendix.


21. List any new IANA registries that require Designated Expert Review for
    future allocations. Are the instructions to the Designated Expert clear?
    Please include suggestions of designated experts, if appropriate.

None of the IANA registries require Designated Expert Review. Instead, they require:

- A standards action of IESG review for permanent registrations
- A specification for either Provisional or Historical registrations

It was deemed that specifications were appropriate for Provisional or Historical registrations due to the expectation that all such instructions, including their encodings, semantics, and conformance groups, will always be documented in the Linux kernel following (at a minimum) review processes with the Linux Kernel Mailing List (LKML).

Permanent registrations will require Standards action or IESG Review to reflect the intention of the BPF community to follow a more structured and consensus-driven approach to innovation and extension of the BPF ecosystem.

[1]: https://www.ietf.org/about/groups/iesg/
[2]: https://www.rfc-editor.org/rfc/rfc4858.html
[3]: https://www.rfc-editor.org/rfc/rfc7942.html
[4]: https://wiki.ietf.org/group/ops/yang-review-tools
[5]: https://www.rfc-editor.org/rfc/rfc8342.html
[6]: https://wiki.ietf.org/group/iesg/ExpertTopics
[7]: https://www.rfc-editor.org/info/bcp79
[8]: https://www.ietf.org/tools/idnits/
[9]: https://www.rfc-editor.org/rfc/rfc3967.html
[10]: https://www.rfc-editor.org/info/bcp97
[11]: https://www.rfc-editor.org/rfc/rfc8126.html
[12]: https://www.rfc-editor.org/rfc/rfc2026.html#section-5
[13]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.1
[14]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.2
[15]: https://authors.ietf.org/en/content-guidelines-overview
[16]: https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/
[17]: https://datatracker.ietf.org/doc/downref/
[18]: https://mailarchive.ietf.org/arch/msg/bpf/W_GWZeh3cUPN0o1D0Lxwwbldfi0/
[19]: https://mailarchive.ietf.org/arch/msg/bpf/_CViBgpJOIQM0fvKcHWQCpCRFvg/
[20]: https://mailarchive.ietf.org/arch/msg/bpf/JNrxzJiBd09zaqU_pVeQ4s8mqKg/
[21]: https://mailarchive.ietf.org/arch/msg/bpf/8Fkl_dExCX-YbPGOmWbG4SJFBKw/
[22]: https://mailarchive.ietf.org/arch/msg/bpf/_WoygSMs8VP6QNG6A8qRtFl0Hgw/
[23]: https://docs.kernel.org/bpf/
[24]: https://github.com/microsoft/ebpf-for-windows
[25]: https://github.com/iovisor/ubpf
[26]: https://wiki.ietf.org/group/int/IntAreaIssues
[27]: https://mailarchive.ietf.org/arch/msg/bpf/VMU0nSo-T71QfXC50Q1Bu2ejD_g/
[28]: https://github.com/ietf-wg-bpf/ebpf-docs/issues?q=is%3Aopen+is%3Aissue+label%3AISA
[29]: https://github.com/ietf-wg-bpf/ebpf-docs/issues/122
[30]: https://github.com/ietf-wg-bpf/ebpf-docs/issues/121
[31]: https://github.com/ietf-wg-bpf/ebpf-docs/issues/123