* Re: [Bpf] [PATCH] bpf, docs: Add additional ABI working draft base text
2023-10-21 23:13 ` Will Hawkins
@ 2023-10-21 23:13 ` Will Hawkins
2023-10-21 23:26 ` [PATCH v2] " Will Hawkins
2023-10-24 0:55 ` [PATCH] " David Vernet
2 siblings, 0 replies; 42+ messages in thread
From: Will Hawkins @ 2023-10-21 23:13 UTC (permalink / raw)
To: David Vernet; +Cc: bpf, bpf
Thank you, David and Christoph, for the comments. I am sending a v2 of
the patch and will respond to open questions inline below.
On Tue, Oct 3, 2023 at 2:26 PM David Vernet <void@manifault.com> wrote:
>
> On Mon, Oct 02, 2023 at 10:19:55AM -0400, Will Hawkins wrote:
>
> Hi Will,
>
> Thanks for working on this. This is really great work and (obviously) a
> big improvement over my tiny little ABI doc. I left some comments below,
> as is to be expected given that it's only the first draft.
>
> > Per David's description of the IETF standardization process, this
> > document will form the basis for an informational eBPF ABI. The
> > work in this commit is a slightly more complete skeleton for the work
> > that we will do. Everything in this document (from formatting to topics
> > to details) is open for change and feedback.
> > ---
> > Documentation/bpf/standardization/abi.rst | 237 ++++++++++++++++++++--
> > 1 file changed, 225 insertions(+), 12 deletions(-)
> >
> > diff --git a/Documentation/bpf/standardization/abi.rst b/Documentation/bpf/standardization/abi.rst
> > index 0c2e10eeb89a..cadbd1b4d6b3 100644
> > --- a/Documentation/bpf/standardization/abi.rst
> > +++ b/Documentation/bpf/standardization/abi.rst
> > @@ -1,25 +1,238 @@
> > -.. contents::
> > -.. sectnum::
> > -
> > ===================================================
> > BPF ABI Recommended Conventions and Guidelines v1.0
> > ===================================================
> >
> > -This is version 1.0 of an informational document containing recommended
> > -conventions and guidelines for producing portable BPF program binaries.
> > +An application binary interface (ABI) defines the requirements that one or more binary software
> > +objects must meet in order to guarantee that they can interoperate and/or use the resources provided
> > +by operating systems/hardware combinations. (For alternate definitions of ABI, see
> > +[SYSVABI]_, [POWERPCABI]_)
> > +
> > +The purpose of this document is to define an ABI which will define the extent to which compiled
> > +eBPF programs are compatible with each other and the eBPF machine/processor [#]_ on which they
>
> s/eBPF/BPF throughout the doc
All done!
>
> > +are executing.
> > +
> > +The ABI is specified in two parts: a generic part and a processor-specific part.
> > +A pairing of of generic ABI with the processor-specific ABI for a certain instantiation
>
> s/of of/of
Good eyes, thank you!
>
> > +of an eBPF machine represents a complete binary interface for eBPF programs executing
> > +on that machine.
> > +
> > +This document is a generic ABI and specifies the parameters and behavior common to all
>
> Should this say, "This document is the generic ABI..." to reflect the
> fact that it's the first of the two ABI parts mentioned in the prior
> paragraph?
Absolutely. Great suggestion.
>
> > +instantiations of eBPF machines. In addition, it defines the details that must be specified by each
> > +processor-specific ABI.
> > +
> > +These psABIs are the second part of the ABI. Each instantiation of an eBPF machine must
> > +describe the mechanism through which binary interface compatibility is maintained with
> > +respect to the issues highlighted by this document. However, the details that must be
> > +defined by a psABI are a minimum -- a psABI may specify additional requirements for binary
> > +interface compatibility on a platform.
> > +
> > +.. contents::
> > +.. sectnum::
> > +
> > +How To Use This ABI
> > +===================
> > +
> > +Conformance
> > +===========
> > +
> > +Note: Red Hat specifies different levels of conformance over time [RHELABI]_.
>
> I don't think we should specify conformance guidelines for a
> distribution as part of the standardization document. RHEL, Debian,
> future distros, Windows, etc, can all decide what guidelines they give
> developers for backward compatibility, etc with their release cycles,
> but that's entirely separate from a standardization document that's
> enumerating generic or psABIs.
I agree 100%. The "Note:" here was more an author's "note to self"
about where we could look for other existing language that we could
appropriate to include in this document. I have updated the Note: to
be an Author's Note (here and elsewhere) to make that more obvious. I
hope that is okay!
>
> > +
> > +Related Work
> > +============
> > +eBPF programs are not unique for the way that they operate on a virtualized machine and processor.
> > +There are many programming languages that compile to an ISA that is specific to a virtual machine.
> > +Like the specification presented herein, those languages and virtual machines also have ABIs.
> > +
> > +For example, the Go programming language and the runtime included statically with each program compiled
> > +from Go source code have a defined ABI [GOABI]_. Java programs compiled to bytecode follow a well-defined
> > +ABI for interoperability with other compiled Java programs and libraries [JAVAABI]_. Programs compiled to
> > +bytecode for execution as user applications on the Android operating system (OS) adhere to a bytecode
> > +specification that shares much in common with an ABI [DALVIKABI]_. Finally, the Common Language Runtime (CLR)
> > +designed to execute programs compiled to the Microsoft Intermediate Language (MSIL) has a fully specified
> > +ABI [CLRABI]_.
>
> While this section is certainly useful background for the reader, I'm
> also not sure it's necessary or appropriate to include. These ABIs are
> independent of this one, and could change at any time. It's probably
> best if we avoid referencing external documents that aren't actual
> dependencies of this document. Feel free to disagree.
You make an excellent point. Although v2 does not make this change, do
you think that a reasonable adjustment would be to simply move this
section to the end of the document?
>
> > +Vocabulary
> > +==========
> > +
> > +#. Program: An eBPF Program is a self-contained set of eBPF instructions that execute
> > + on an eBPF processor.
>
> I wonder if we want to be a bit more concrete here. "Self-contained",
> for example, is arguably a bit ambiguous in terms of what it means. What
> do you think about this?
>
> "Program: A BPF Program is an ordered set of BPF instructions, with
> exactly one entry instruction where the program begins, and one or more
> BPF_EXIT instructions where program execution can end."
This suggestion is fantastic and I have used it verbatim!
>
> > +#. Program Type: Every eBPF program has an associated type. The program type defines, among other things,
> > + a program's possible attach types.
> > +#. Attach Type: An attach type defines the set of BPF hook points to which an eBPF
> > + program can attach.
> > +#. BPF Hook Points: Places in a BPF-enabled component (e.g., the Linux Kernel, the Windows kernel) where
> > + an eBPF program may be attached.
>
> Hmm, I'm not sure if having this vocabulary section at the beginning of
> the document is optimal. Consider that the above 3 definitions are quite
> sparse, and essentially do nothing other than reference each other, and
> they're also leaving out a lot of detail that will be explored more
> substantively later in the document (or in the framework / architecture
> informational document described in [0]).
>
> [0]: https://datatracker.ietf.org/wg/bpf/about/
>
> It seems like it might make more sense to follow the approach taken by
> the JVM specification [1], SysV ABI [2], and RISC-V psABI [3] (though
> they do have a section that defines appreviations and a couple of
> terms), and instead just have each chapter explain all of these concepts
> in more detail without any kind of introduction. What do you think?
I could go either way. Personally, when I read documents, I like
having a vocabulary section to give me some bearing. That way, as I
read the document, I know where to turn to see whether words with
which I am unfamiliar are things that I "should know" (and therefore
just Google) or are new terminology from this document. Again, I could
absolutely go either way and certainly appreciate your references to
other documents that work differently. When I wrote this section I
envisioned it like the vocabulary section from the C++ standard where
new terms of art are given basic definitions that are later expanded
throughout the document.
What if we did both -- we could keep the vocabulary section and
include pointers to the places later in the specification where the
terms are explained in additional detail?
>
> [1]: https://docs.oracle.com/javase/specs/jvms/se21/html/index.html
> [2]: https://refspecs.linuxfoundation.org/elf/x86_64-abi-0.95.pdf
> [3]: https://github.com/riscv-non-isa/riscv-elf-psabi-doc/releases/download/draft-20230929-e5c800e661a53efe3c2678d71a306323b60eb13b/riscv-abi.pdf
>
> > +#. eBPF Machine Instantiation:
> > +#. ABI-conforming system: A computer system that provides the binary sys- tem interface for application
> > + programs described in the System V ABI [SYSVABI]_.
> > +#. ABI-conforming program: A program written to include only the system routines, commands, and other
> > + resources included in the ABI, and a program compiled into an executable file that has the formats
> > + and characteristics specified for such files in the ABI, and a program whose behavior complies with
> > + the rules given in the ABI [SYSVABI]_.
> > +#. ABI-nonconforming program: A program which has been written to include system routines, commands, or
> > + other resources not included in the ABI, or a program which has been compiled into a format different
> > + from those specified in the ABI, or a program which does not behave as specified in the ABI [SYSVABI]_.
> > +#. Undefined Behavior: Behavior that may vary from instance to instance or may change at some time in the future.
> > + Some undesirable programming practices are marked in the ABI as yielding undefined behavior [SYSVABI]_.
> > +#. Unspecified Property: A property of an entity that is not explicitly included or referenced in this specification,
> > + and may change at some time in the future. In general, it is not good practice to make a program depend
> > + on an unspecified property [SYSVABI]_.
> > +
> > +Program Execution Environment
> > +=============================
> > +
> > +A loaded eBPF program is executed on an eBPF machine. That machine, physical or virtual, runs in a freestanding
> > +or hosted environment [#]_.
> > +
> > +eBPF Machine Freestanding Environment
> > +-------------------------------------
> > +
> > +
> > +eBPF Machine Hosted Environment
> > +-------------------------------
> > +
> > +A loaded eBPF program can be attached to a BPF hook point in a BPF-enabled application
> > +compatible with the attach type of its program type. When the BPF-enabled application's
> > +execution reaches a BPF hook point to which an eBPF program is attached, that program
> > +begins execution on the eBPF machine at its first instruction. The contents of eBPF machine's
> > +registers and memory at the time it starts execution are defined by the eBPF program's
> > +type and attach point.
> > +
> > +Processor Architecture
> > +======================
> > +
> > +This section describes the processor architecture available
> > +to programs. It also defines the reference language data types, giving the
> > +foundation for system interface specifications [SYSVABI]_
>
> Why are we linking to the SYSVABI doc here?
A great question -- in most places where I have referenced that
document it is akin to an academic reference -- I am attempting to
give the user the idea that the language used is not my own completely
original thought. I am attempting to tell the reader that this concept
or language has precedent in another document. I am very new to the
standards-writing process and realize that utilization of citations
may not be "how it works". Please let me know how to proceed!
>
> > +
> > +Registers
> > +---------
> > +
> > +General Purpose Registers
> > +^^^^^^^^^^^^^^^^^^^^^^^^^
> > +eBPF has 11 64-bit wide registers, `r0` - `r10`. The contents of the registers
> > +at the beginning of an eBPF program's execution depend on the program's type.
>
> We should probably also mention the 32 bit subregisters (they can only
> be accessed through special ALU operations), and that they zero-extend
> into 64 bit on writes.
I added a note on the subregisters. I decided to leave out the
information about how they zero extend on writes. I thought that was
something that should remain entirely within the scope of the ISA.
Please let me know if I am wrong!
>
> > +
> > +Frame Pointer Register
> > +^^^^^^^^^^^^^^^^^^^^^^
> > +The use of a frame pointer by programs is not required. If, however, an eBPF program
> > +does use a frame pointer, it must be stored in register `r10`.
>
> Should we also specify that it should be read only?
Agreed and done!
>
> > +
> > +Data Types
> > +----------
> >
> > -Registers and calling convention
> > -================================
> > +Numeric Types
> > +^^^^^^^^^^^^^
> >
> > -BPF has 10 general purpose registers and a read-only frame pointer register,
> > -all of which are 64-bits wide.
> > +The eBPF machine supports 32- and 64-bit signed and unsigned integers. It does
> > +not support floating-point data types. All signed integers are represented in
> > +twos-complement format where the sign bit is stored in the most-significant
> > +bit.
> >
> > -The BPF calling convention is defined as:
> > +Pointers
> > +^^^^^^^^
> >
> > -* R0: return value from function calls, and exit value for BPF programs
> > +Function Calling Sequence
> > +=========================
> > +This section defines the standard function calling sequence in a way that
> > +accommodates exceptions, stack management, register (non)volatility, and access
> > +to capabilities of the hosting environment (where applicable).
> > +
> > +Functions in eBPF may define between 0 and 5 parameters. Each of the arguments in
> > +a function call are passed in registers.
> > +
> > +The eBPF calling convention is defined as:
> > +
> > +* R0: return value from function calls, and exit value for eBPF programs
> > * R1 - R5: arguments for function calls
> > * R6 - R9: callee saved registers that function calls will preserve
> > * R10: read-only frame pointer to access stack
> >
> > -R0 - R5 are scratch registers and BPF programs needs to spill/fill them if
> > +R0 - R5 are scratch registers and eBPF programs needs to spill/fill them if
> > necessary across calls.
> > +
> > +Every function invocation proceeds as if it has exclusive access to an
> > +implementation-defined amount of stack space. R10 is a pointer to the byte of
> > +memory with the highest address in that stack space. The contents
> > +of a function invocation's stack space do not persist between invocations.
> > +
> > +**TODO** Discuss manufactured prologue and epilogue. Take language from the design FAQ.
> > +
> > +Execution Environment Interface
> > +===============================
> > +
> > +When an eBPF program executes in a hosted environment, the hosted environment may make
> > +available to eBPF programs certain capabilities. This section describes those capabilities
> > +and the mechanism for accessing them.
> > +
> > +
> > +Program Execution
> > +=================
> > +
> > +Program Return Values
> > +---------------------
> > +
> > +**NOTE** libbpf currently defines the return value of an ebpf program as a 32-bit unsigned integer.
> > +
> > +Program Loading and Dynamic Linking
> > +-----------------------------------
> > +This section describes the object file information and system actions that create
> > +running programs. Some information here applies to all systems; information specific
> > +to one processor resides in sections marked accordingly [SYSVABI]_.
> > +
> > +eBPF programs saved in ELF files must be loaded from storage and properly configured before
> > +they can be executed on an eBPF machine.
> > +
> > +Program Loading (Processor-Specific)
> > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > +
> > +Dynamic Linking
> > +^^^^^^^^^^^^^^^
> > +
> > +Global Offset Table (Processor-Specific)
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +Procedure Linkage Table (Processor-Specific)
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +Exception Handling
> > +==================
> > +
> > +eBPF Program Types
> > +==================
> > +**NOTE** This information may end up as a subsection somewhere else.
> > +
> > +eBPF Maps
> > +=========
> > +**NOTE** This information may end up as a subsection somewhere else.
> > +
> > +System Calls
> > +============
> > +
> > +**TODO**
> > +
> > +C Programming Language Support
> > +==============================
> > +
> > +**NOTE** This section could be included in order to define the contents
> > +of standardized processor-specific header files that would make it easier
> > +for programmers to write programs.
> > +
> > +Notes
> > +=====
> > +.. [#] The eBPF machine does not need to be a physical instantiation of a processor. In fact, many instantiations of eBPF machines are virtual.
> > +.. [#] See the [CSTD]_ for the inspiration for this distinction.
> > +
> > +References
> > +==========
> > +
> > +.. [SYSVABI] System V Application Binary Interface - Edition 4.1. SCO Developer Specs. The Santa Cruz Operation. 1997. https://www.sco.com/developers/devspecs/gabi41.pdf
> > +.. [POWERPCABI] Developing PowerPC Embedded Application Binary Interface (EABI) Compliant Programs. PowerPC Embedded Processors Application Note. IBM. 1998. http://class.ece.iastate.edu/arun/Cpre381_Sp06/lab/labw12a/eabi_app.pdf
> > +.. [GOABI] Go internal ABI specification. Go Source Code. No authors. 2023. https://go.googlesource.com/go/+/refs/heads/master/src/cmd/compile/abi-internal.md
> > +.. [JAVAABI] The Java (r) Language Specification - Java SE 7 Edition. Gosling, James et. al. Oracle. 2013. https://docs.oracle.com/javase/specs/jls/se7/html/index.html
>
> If we do share a link, it should probably be to the Java Virtual Machine
> specification rather than the language specification. I believe the most
> recent edition is 21.
I checked and the binary compatibility piece of the specification is
actually in the language spec. That said, it might make sense to just
link to both? I am willing to do whatever you suggest!
>
> > +.. [DALVIKABI] Dalvik Bytecode. Android Core Runtime Documentation. No authors. Google. 2022. https://source.android.com/docs/core/runtime/dalvik-bytecode
> > +.. [CLRABI] CLR ABI. The Book of the Runtime. No authors. Microsoft. 2023. https://github.com/dotnet/coreclr/blob/master/Documentation/botr/clr-abi.md.
> > +.. [CSTD] International Standard: Programming Languages - C. ISO/IEC. 2018. https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2310.pdf.
> > +.. [RHELABI] Red Hat Enterprise Linux 8: Application Compatibility Guide. Red Hat. 2023. https://access.redhat.com/articles/rhel8-abi-compatibility
> > +
>
> Everything else looks fine for now. Something I think we should figure
> out though is what we want to put each of the following docs from the
> charter:
I reflowed the entire document to make sure that the text is at most 80 columns.
>
> - [I] one or more documents that recommend conventions and guidelines
> for producing portable BPF program binaries,
>
> - [I] an architecture and framework document.
>
> It seems like some of what's going into this document (e.g. formally
> defining a "Program", data types, etc) could arguably belong in an
> architecture and framework document. Honestly, I think it would probably
> be easier and make more sense to just have a single monolithic BPF
> Machine informational document, though I'm not sure if that's viable at
> this point given that we specified different documents in the charter.
You make (as usual) an excellent point. I think that this question is
something that would be good to discuss as a group? Because you are
the chair, David, I will defer to you!
Thank you again David and Christoph for your comments!
Will
>
> Thanks,
> David
--
Bpf mailing list
Bpf@ietf.org
https://www.ietf.org/mailman/listinfo/bpf
^ permalink raw reply [flat|nested] 42+ messages in thread
* [PATCH v2] bpf, docs: Add additional ABI working draft base text
2023-10-21 23:13 ` Will Hawkins
2023-10-21 23:13 ` [Bpf] " Will Hawkins
@ 2023-10-21 23:26 ` Will Hawkins
2023-10-21 23:26 ` [Bpf] " Will Hawkins
2023-10-24 0:55 ` [PATCH] " David Vernet
2 siblings, 1 reply; 42+ messages in thread
From: Will Hawkins @ 2023-10-21 23:26 UTC (permalink / raw)
To: bpf, bpf; +Cc: Will Hawkins
Per David's description of the IETF standardization process, this
document will form the basis for an informational eBPF ABI. The
work in this commit is a slightly more complete skeleton for the work
that we will do. Everything in this document (from formatting to topics
to details) is open for change and feedback.
---
Documentation/bpf/standardization/abi.rst | 259 +++++++++++++++++++++-
1 file changed, 250 insertions(+), 9 deletions(-)
Changelog:
v1 -> v2:
- Address David's comments
- Reflow to a max of 80 character lines (Christoph's feedback)
diff --git a/Documentation/bpf/standardization/abi.rst b/Documentation/bpf/standardization/abi.rst
index 0c2e10eeb89a..f6a87b7a300c 100644
--- a/Documentation/bpf/standardization/abi.rst
+++ b/Documentation/bpf/standardization/abi.rst
@@ -1,18 +1,162 @@
-.. contents::
-.. sectnum::
-
===================================================
BPF ABI Recommended Conventions and Guidelines v1.0
===================================================
-This is version 1.0 of an informational document containing recommended
-conventions and guidelines for producing portable BPF program binaries.
+An application binary interface (ABI) defines the requirements that one or more
+binary software objects must meet in order to guarantee that they can
+interoperate and/or use the resources provided by operating systems/hardware
+combinations. (For alternate definitions of ABI, see [SYSVABI]_, [POWERPCABI]_)
+
+The purpose of this document is to define an ABI which will define the extent
+to which compiled BPF programs are compatible with each other and the BPF
+machine/processor [#]_ on which they are executing.
+
+The ABI is specified in two parts: a generic part and a processor-specific part.
+A pairing of generic ABI with the processor-specific ABI for a certain
+instantiation of a BPF machine represents a complete binary interface for BPF
+programs executing on that machine.
+
+This document is the generic ABI and specifies the parameters and behavior
+common to all instantiations of BPF machines. In addition, it defines the
+details that must be specified by each processor-specific ABI.
+
+These psABIs are the second part of the ABI. Each instantiation of a BPF
+machine must describe the mechanism through which binary interface
+compatibility is maintained with respect to the issues highlighted by this
+document. However, the details that must be defined by a psABI are a minimum --
+a psABI may specify additional requirements for binary interface compatibility
+on a platform.
+
+.. contents::
+.. sectnum::
+
+How To Use This ABI
+===================
+
+Conformance
+===========
+
+**Author's Note**: Red Hat specifies different levels of conformance over
+time [RHELABI]_.
+
+Related Work
+============
+BPF programs are not unique for the way that they operate on a virtualized
+machine and processor. There are many programming languages that compile to an
+ISA that is specific to a virtual machine. Like the specification presented
+herein, those languages and virtual machines also have ABIs.
+
+For example, the Go programming language and the runtime included statically
+with each program compiled from Go source code have a defined ABI [GOABI]_.
+Java programs compiled to bytecode follow a well-defined ABI for
+interoperability with other compiled Java programs and libraries [JAVAABI]_.
+Programs compiled to bytecode for execution as user applications on the Android
+operating system (OS) adhere to a bytecode specification that shares much in
+common with an ABI [DALVIKABI]_. Finally, the Common Language Runtime (CLR)
+designed to execute programs compiled to the Microsoft Intermediate Language
+(MSIL) has a fully specified ABI [CLRABI]_.
+
+Vocabulary
+==========
+
+#. Program: A BPF Program is an ordered set of BPF instructions, with exactly
+ one entry instruction where the program begins, and one or more exit
+ instructions where program execution can end.
+#. Program Type: Every BPF program has an associated type. The program type
+ defines, among other things, a program's possible attach types.
+#. Attach Type: An attach type defines the set of BPF hook points to which a BPF
+ program can attach.
+#. BPF Hook Points: Places in a BPF-enabled component (e.g., the Linux Kernel,
+ the Windows kernel) where a BPF program may be attached.
+#. ABI-conforming BPF Machine Instantiation: A physical or logical realization
+ of a computer system capable of executing BPF programs consistently with the
+ specifications outlined in this document.
+#. ABI-conforming BPF program: A BPF program written to include only the system
+ routines, commands, and other resources included in this ABI; or a BPF
+ program compiled into an executable file that has the formats and
+ characteristics specified for such files in this ABI; or a BPF program whose
+ behavior complies with the rules given in the ABI [SYSVABI]_.
+#. ABI-nonconforming program: A BPF program that is not ABI conforming.
+#. Undefined Behavior: Behavior that may vary from instance to instance or may
+ change at some time in the future. Some undesirable programming practices
+ are marked in this ABI as yielding undefined behavior [SYSVABI]_.
+#. Unspecified Property: A property of an entity defined in this document that
+ is not explicitly included, defined or referenced in this specification, and
+ may change at some time in the future. In general, it is not good practice
+ to make a program depend on an unspecified property [SYSVABI]_.
+
+Program Execution Environment
+=============================
+
+A loaded BPF program is executed in a freestanding or hosted environment. [#]_.
+
+BPF Program Freestanding Execution Environment
+----------------------------------------------
+
+**TODO**
+
+
+BPF Program Hosted Execution Environment
+----------------------------------------
+
+A hosted execution environment is one in which a BPF machine instantiation is
+embedded within another computer system known as a BPF-enabled application
+(e.g., a user application or an operating system kernel). A loaded BPF program
+can be attached to a BPF hook point in such a BPF-enabled application
+compatible with the attach type of its program type. When the BPF-enabled
+application's execution reaches a BPF hook point to which a BPF program is
+attached, that BPF program begins execution on the embedded BPF machine at the
+program's first instruction. The contents of the embedded BPF machine's
+registers and memory at the time it starts execution of the BPF program are
+defined by the BPF program's type and attach point.
+
+Processor Architecture
+======================
+
+This section describes the processor architecture available
+to programs. It also defines the reference language data types, giving the
+foundation for system interface specifications [SYSVABI]_
+
+Registers
+---------
+
+General Purpose Registers
+^^^^^^^^^^^^^^^^^^^^^^^^^
+BPF has 11 64-bit wide registers, `r0` - `r10`. There exists a single
+32-bit wide subregister for each one of the 11 64-bit wide registers. Those
+registers do not have their own names -- they are accessible indirectly
+through the 32-bit ALU instructions.
+
+The contents of the registers at the beginning of a BPF program's
+execution depend on the program's type.
-Registers and calling convention
-================================
+Frame Pointer Register
+^^^^^^^^^^^^^^^^^^^^^^
+The use of a frame pointer by programs is not required. If, however, a BPF
+program does use a frame pointer, it must be stored in register `r10` and
+must be read only.
-BPF has 10 general purpose registers and a read-only frame pointer register,
-all of which are 64-bits wide.
+Data Types
+----------
+
+Numeric Types
+^^^^^^^^^^^^^
+
+The BPF machine supports 32- and 64-bit signed and unsigned integers. It does
+not support floating-point data types. All signed integers are represented in
+twos-complement format where the sign bit is stored in the most-significant bit.
+
+Pointers
+^^^^^^^^
+
+Function Calling Sequence
+=========================
+This section defines the standard function calling sequence in a way that
+accommodates exceptions, stack management, register (non)volatility, and access
+to capabilities of the hosting environment (where applicable).
+
+Functions in BPF may define between 0 and 5 parameters. Each of the arguments in
+a function call are passed in registers.
The BPF calling convention is defined as:
@@ -23,3 +167,100 @@ The BPF calling convention is defined as:
R0 - R5 are scratch registers and BPF programs needs to spill/fill them if
necessary across calls.
+
+Every function invocation proceeds as if it has exclusive access to an
+implementation-defined amount of stack space. R10 is a pointer to the byte of
+memory with the highest address in that stack space. The contents
+of a function invocation's stack space do not persist between invocations.
+
+**TODO** Discuss manufactured prologue and epilogue. Take language from the
+design FAQ.
+
+Execution Environment Interface
+===============================
+
+When a BPF program executes in a hosted environment, the hosted environment
+may make available to BPF programs certain capabilities. This section
+describes those capabilities and the mechanism for accessing them.
+
+
+Program Execution
+=================
+
+Program Return Values
+---------------------
+
+**Author's Note** libbpf currently defines the return value of an ebpf program
+as a 32-bit unsigned integer.
+
+Program Loading and Dynamic Linking
+-----------------------------------
+This section describes the object file information and system actions that
+create running programs. Some information here applies to all systems;
+information specific to one processor resides in sections marked accordingly
+[SYSVABI]_.
+
+BPF programs saved in ELF files must be loaded from storage and properly
+configured before they can be executed on a BPF machine.
+
+Program Loading (Processor-Specific)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Dynamic Linking
+^^^^^^^^^^^^^^^
+
+Global Offset Table (Processor-Specific)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Procedure Linkage Table (Processor-Specific)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Exception Handling
+==================
+
+BPF Program Types
+==================
+**Author's Note** This information may end up as a subsection somewhere else.
+
+BPF Maps
+=========
+**Author's Note** This information may end up as a subsection somewhere else.
+
+System Calls
+============
+
+**TODO**
+
+C Programming Language Support
+==============================
+
+**Author's Note** This section could be included in order to define the contents
+of standardized processor-specific header files that would make it easier
+for programmers to write programs.
+
+Notes
+=====
+.. [#] The BPF machine does not need to be a physical instantiation of a processor.
+ In fact, many instantiations of BPF machines are virtual.
+.. [#] See the [CSTD]_ for the inspiration for this distinction.
+
+References
+==========
+
+.. [SYSVABI] System V Application Binary Interface - Edition 4.1. SCO Developer Specs.
+ The Santa Cruz Operation. 1997.
+ https://www.sco.com/developers/devspecs/gabi41.pdf
+.. [POWERPCABI] Developing PowerPC Embedded Application Binary Interface (EABI)
+ Compliant Programs. PowerPC Embedded Processors Application Note. IBM. 1998. http://class.ece.iastate.edu/arun/Cpre381_Sp06/lab/labw12a/eabi_app.pdf
+.. [GOABI] Go internal ABI specification. Go Source Code. No authors. 2023.
+ https://go.googlesource.com/go/+/refs/heads/master/src/cmd/compile/abi-internal.md
+.. [JAVAABI] The Java (r) Language Specification - Java SE 7 Edition. Gosling, James et. al.
+ Oracle. 2013. https://docs.oracle.com/javase/specs/jls/se7/html/index.html
+.. [DALVIKABI] Dalvik Bytecode. Android Core Runtime Documentation. No authors. Google.
+ 2022. https://source.android.com/docs/core/runtime/dalvik-bytecode
+.. [CLRABI] CLR ABI. The Book of the Runtime. No authors. Microsoft. 2023.
+ https://github.com/dotnet/coreclr/blob/master/Documentation/botr/clr-abi.md.
+.. [CSTD] International Standard: Programming Languages - C. ISO/IEC. 2018.
+ https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2310.pdf.
+.. [RHELABI] Red Hat Enterprise Linux 8: Application Compatibility Guide. Red Hat.
+ 2023. https://access.redhat.com/articles/rhel8-abi-compatibility.
--
2.41.0
^ permalink raw reply related [flat|nested] 42+ messages in thread* [Bpf] [PATCH v2] bpf, docs: Add additional ABI working draft base text
2023-10-21 23:26 ` [PATCH v2] " Will Hawkins
@ 2023-10-21 23:26 ` Will Hawkins
0 siblings, 0 replies; 42+ messages in thread
From: Will Hawkins @ 2023-10-21 23:26 UTC (permalink / raw)
To: bpf, bpf; +Cc: Will Hawkins
Per David's description of the IETF standardization process, this
document will form the basis for an informational eBPF ABI. The
work in this commit is a slightly more complete skeleton for the work
that we will do. Everything in this document (from formatting to topics
to details) is open for change and feedback.
---
Documentation/bpf/standardization/abi.rst | 259 +++++++++++++++++++++-
1 file changed, 250 insertions(+), 9 deletions(-)
Changelog:
v1 -> v2:
- Address David's comments
- Reflow to a max of 80 character lines (Christoph's feedback)
diff --git a/Documentation/bpf/standardization/abi.rst b/Documentation/bpf/standardization/abi.rst
index 0c2e10eeb89a..f6a87b7a300c 100644
--- a/Documentation/bpf/standardization/abi.rst
+++ b/Documentation/bpf/standardization/abi.rst
@@ -1,18 +1,162 @@
-.. contents::
-.. sectnum::
-
===================================================
BPF ABI Recommended Conventions and Guidelines v1.0
===================================================
-This is version 1.0 of an informational document containing recommended
-conventions and guidelines for producing portable BPF program binaries.
+An application binary interface (ABI) defines the requirements that one or more
+binary software objects must meet in order to guarantee that they can
+interoperate and/or use the resources provided by operating systems/hardware
+combinations. (For alternate definitions of ABI, see [SYSVABI]_, [POWERPCABI]_)
+
+The purpose of this document is to define an ABI which will define the extent
+to which compiled BPF programs are compatible with each other and the BPF
+machine/processor [#]_ on which they are executing.
+
+The ABI is specified in two parts: a generic part and a processor-specific part.
+A pairing of generic ABI with the processor-specific ABI for a certain
+instantiation of a BPF machine represents a complete binary interface for BPF
+programs executing on that machine.
+
+This document is the generic ABI and specifies the parameters and behavior
+common to all instantiations of BPF machines. In addition, it defines the
+details that must be specified by each processor-specific ABI.
+
+These psABIs are the second part of the ABI. Each instantiation of a BPF
+machine must describe the mechanism through which binary interface
+compatibility is maintained with respect to the issues highlighted by this
+document. However, the details that must be defined by a psABI are a minimum --
+a psABI may specify additional requirements for binary interface compatibility
+on a platform.
+
+.. contents::
+.. sectnum::
+
+How To Use This ABI
+===================
+
+Conformance
+===========
+
+**Author's Note**: Red Hat specifies different levels of conformance over
+time [RHELABI]_.
+
+Related Work
+============
+BPF programs are not unique for the way that they operate on a virtualized
+machine and processor. There are many programming languages that compile to an
+ISA that is specific to a virtual machine. Like the specification presented
+herein, those languages and virtual machines also have ABIs.
+
+For example, the Go programming language and the runtime included statically
+with each program compiled from Go source code have a defined ABI [GOABI]_.
+Java programs compiled to bytecode follow a well-defined ABI for
+interoperability with other compiled Java programs and libraries [JAVAABI]_.
+Programs compiled to bytecode for execution as user applications on the Android
+operating system (OS) adhere to a bytecode specification that shares much in
+common with an ABI [DALVIKABI]_. Finally, the Common Language Runtime (CLR)
+designed to execute programs compiled to the Microsoft Intermediate Language
+(MSIL) has a fully specified ABI [CLRABI]_.
+
+Vocabulary
+==========
+
+#. Program: A BPF Program is an ordered set of BPF instructions, with exactly
+ one entry instruction where the program begins, and one or more exit
+ instructions where program execution can end.
+#. Program Type: Every BPF program has an associated type. The program type
+ defines, among other things, a program's possible attach types.
+#. Attach Type: An attach type defines the set of BPF hook points to which a BPF
+ program can attach.
+#. BPF Hook Points: Places in a BPF-enabled component (e.g., the Linux Kernel,
+ the Windows kernel) where a BPF program may be attached.
+#. ABI-conforming BPF Machine Instantiation: A physical or logical realization
+ of a computer system capable of executing BPF programs consistently with the
+ specifications outlined in this document.
+#. ABI-conforming BPF program: A BPF program written to include only the system
+ routines, commands, and other resources included in this ABI; or a BPF
+ program compiled into an executable file that has the formats and
+ characteristics specified for such files in this ABI; or a BPF program whose
+ behavior complies with the rules given in the ABI [SYSVABI]_.
+#. ABI-nonconforming program: A BPF program that is not ABI conforming.
+#. Undefined Behavior: Behavior that may vary from instance to instance or may
+ change at some time in the future. Some undesirable programming practices
+ are marked in this ABI as yielding undefined behavior [SYSVABI]_.
+#. Unspecified Property: A property of an entity defined in this document that
+ is not explicitly included, defined or referenced in this specification, and
+ may change at some time in the future. In general, it is not good practice
+ to make a program depend on an unspecified property [SYSVABI]_.
+
+Program Execution Environment
+=============================
+
+A loaded BPF program is executed in a freestanding or hosted environment. [#]_.
+
+BPF Program Freestanding Execution Environment
+----------------------------------------------
+
+**TODO**
+
+
+BPF Program Hosted Execution Environment
+----------------------------------------
+
+A hosted execution environment is one in which a BPF machine instantiation is
+embedded within another computer system known as a BPF-enabled application
+(e.g., a user application or an operating system kernel). A loaded BPF program
+can be attached to a BPF hook point in such a BPF-enabled application
+compatible with the attach type of its program type. When the BPF-enabled
+application's execution reaches a BPF hook point to which a BPF program is
+attached, that BPF program begins execution on the embedded BPF machine at the
+program's first instruction. The contents of the embedded BPF machine's
+registers and memory at the time it starts execution of the BPF program are
+defined by the BPF program's type and attach point.
+
+Processor Architecture
+======================
+
+This section describes the processor architecture available
+to programs. It also defines the reference language data types, giving the
+foundation for system interface specifications [SYSVABI]_
+
+Registers
+---------
+
+General Purpose Registers
+^^^^^^^^^^^^^^^^^^^^^^^^^
+BPF has 11 64-bit wide registers, `r0` - `r10`. There exists a single
+32-bit wide subregister for each one of the 11 64-bit wide registers. Those
+registers do not have their own names -- they are accessible indirectly
+through the 32-bit ALU instructions.
+
+The contents of the registers at the beginning of a BPF program's
+execution depend on the program's type.
-Registers and calling convention
-================================
+Frame Pointer Register
+^^^^^^^^^^^^^^^^^^^^^^
+The use of a frame pointer by programs is not required. If, however, a BPF
+program does use a frame pointer, it must be stored in register `r10` and
+must be read only.
-BPF has 10 general purpose registers and a read-only frame pointer register,
-all of which are 64-bits wide.
+Data Types
+----------
+
+Numeric Types
+^^^^^^^^^^^^^
+
+The BPF machine supports 32- and 64-bit signed and unsigned integers. It does
+not support floating-point data types. All signed integers are represented in
+twos-complement format where the sign bit is stored in the most-significant bit.
+
+Pointers
+^^^^^^^^
+
+Function Calling Sequence
+=========================
+This section defines the standard function calling sequence in a way that
+accommodates exceptions, stack management, register (non)volatility, and access
+to capabilities of the hosting environment (where applicable).
+
+Functions in BPF may define between 0 and 5 parameters. Each of the arguments in
+a function call are passed in registers.
The BPF calling convention is defined as:
@@ -23,3 +167,100 @@ The BPF calling convention is defined as:
R0 - R5 are scratch registers and BPF programs needs to spill/fill them if
necessary across calls.
+
+Every function invocation proceeds as if it has exclusive access to an
+implementation-defined amount of stack space. R10 is a pointer to the byte of
+memory with the highest address in that stack space. The contents
+of a function invocation's stack space do not persist between invocations.
+
+**TODO** Discuss manufactured prologue and epilogue. Take language from the
+design FAQ.
+
+Execution Environment Interface
+===============================
+
+When a BPF program executes in a hosted environment, the hosted environment
+may make available to BPF programs certain capabilities. This section
+describes those capabilities and the mechanism for accessing them.
+
+
+Program Execution
+=================
+
+Program Return Values
+---------------------
+
+**Author's Note** libbpf currently defines the return value of an ebpf program
+as a 32-bit unsigned integer.
+
+Program Loading and Dynamic Linking
+-----------------------------------
+This section describes the object file information and system actions that
+create running programs. Some information here applies to all systems;
+information specific to one processor resides in sections marked accordingly
+[SYSVABI]_.
+
+BPF programs saved in ELF files must be loaded from storage and properly
+configured before they can be executed on a BPF machine.
+
+Program Loading (Processor-Specific)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Dynamic Linking
+^^^^^^^^^^^^^^^
+
+Global Offset Table (Processor-Specific)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Procedure Linkage Table (Processor-Specific)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Exception Handling
+==================
+
+BPF Program Types
+==================
+**Author's Note** This information may end up as a subsection somewhere else.
+
+BPF Maps
+=========
+**Author's Note** This information may end up as a subsection somewhere else.
+
+System Calls
+============
+
+**TODO**
+
+C Programming Language Support
+==============================
+
+**Author's Note** This section could be included in order to define the contents
+of standardized processor-specific header files that would make it easier
+for programmers to write programs.
+
+Notes
+=====
+.. [#] The BPF machine does not need to be a physical instantiation of a processor.
+ In fact, many instantiations of BPF machines are virtual.
+.. [#] See the [CSTD]_ for the inspiration for this distinction.
+
+References
+==========
+
+.. [SYSVABI] System V Application Binary Interface - Edition 4.1. SCO Developer Specs.
+ The Santa Cruz Operation. 1997.
+ https://www.sco.com/developers/devspecs/gabi41.pdf
+.. [POWERPCABI] Developing PowerPC Embedded Application Binary Interface (EABI)
+ Compliant Programs. PowerPC Embedded Processors Application Note. IBM. 1998. http://class.ece.iastate.edu/arun/Cpre381_Sp06/lab/labw12a/eabi_app.pdf
+.. [GOABI] Go internal ABI specification. Go Source Code. No authors. 2023.
+ https://go.googlesource.com/go/+/refs/heads/master/src/cmd/compile/abi-internal.md
+.. [JAVAABI] The Java (r) Language Specification - Java SE 7 Edition. Gosling, James et. al.
+ Oracle. 2013. https://docs.oracle.com/javase/specs/jls/se7/html/index.html
+.. [DALVIKABI] Dalvik Bytecode. Android Core Runtime Documentation. No authors. Google.
+ 2022. https://source.android.com/docs/core/runtime/dalvik-bytecode
+.. [CLRABI] CLR ABI. The Book of the Runtime. No authors. Microsoft. 2023.
+ https://github.com/dotnet/coreclr/blob/master/Documentation/botr/clr-abi.md.
+.. [CSTD] International Standard: Programming Languages - C. ISO/IEC. 2018.
+ https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2310.pdf.
+.. [RHELABI] Red Hat Enterprise Linux 8: Application Compatibility Guide. Red Hat.
+ 2023. https://access.redhat.com/articles/rhel8-abi-compatibility.
--
2.41.0
--
Bpf mailing list
Bpf@ietf.org
https://www.ietf.org/mailman/listinfo/bpf
^ permalink raw reply related [flat|nested] 42+ messages in thread
* Re: [PATCH] bpf, docs: Add additional ABI working draft base text
2023-10-21 23:13 ` Will Hawkins
2023-10-21 23:13 ` [Bpf] " Will Hawkins
2023-10-21 23:26 ` [PATCH v2] " Will Hawkins
@ 2023-10-24 0:55 ` David Vernet
2023-10-24 0:55 ` [Bpf] " David Vernet
` (2 more replies)
2 siblings, 3 replies; 42+ messages in thread
From: David Vernet @ 2023-10-24 0:55 UTC (permalink / raw)
To: Will Hawkins; +Cc: bpf, bpf
On Sat, Oct 21, 2023 at 07:13:58PM -0400, Will Hawkins wrote:
[...]
> > > +instantiations of eBPF machines. In addition, it defines the details that must be specified by each
> > > +processor-specific ABI.
> > > +
> > > +These psABIs are the second part of the ABI. Each instantiation of an eBPF machine must
> > > +describe the mechanism through which binary interface compatibility is maintained with
> > > +respect to the issues highlighted by this document. However, the details that must be
> > > +defined by a psABI are a minimum -- a psABI may specify additional requirements for binary
> > > +interface compatibility on a platform.
> > > +
> > > +.. contents::
> > > +.. sectnum::
> > > +
> > > +How To Use This ABI
> > > +===================
> > > +
> > > +Conformance
> > > +===========
> > > +
> > > +Note: Red Hat specifies different levels of conformance over time [RHELABI]_.
> >
> > I don't think we should specify conformance guidelines for a
> > distribution as part of the standardization document. RHEL, Debian,
> > future distros, Windows, etc, can all decide what guidelines they give
> > developers for backward compatibility, etc with their release cycles,
> > but that's entirely separate from a standardization document that's
> > enumerating generic or psABIs.
>
> I agree 100%. The "Note:" here was more an author's "note to self"
> about where we could look for other existing language that we could
> appropriate to include in this document. I have updated the Note: to
> be an Author's Note (here and elsewhere) to make that more obvious. I
> hope that is okay!
Hmm, I think that could get confusing. Can we just add comments anywhere
that we want to be able to record places for us to use as a reference
for language later? Ideally anything going into the document should be
text that we're intending to eventually publish, perhaps with the
exception of things like XXX: Fill in later.
> > > +Related Work
> > > +============
> > > +eBPF programs are not unique for the way that they operate on a virtualized machine and processor.
> > > +There are many programming languages that compile to an ISA that is specific to a virtual machine.
> > > +Like the specification presented herein, those languages and virtual machines also have ABIs.
> > > +
> > > +For example, the Go programming language and the runtime included statically with each program compiled
> > > +from Go source code have a defined ABI [GOABI]_. Java programs compiled to bytecode follow a well-defined
> > > +ABI for interoperability with other compiled Java programs and libraries [JAVAABI]_. Programs compiled to
> > > +bytecode for execution as user applications on the Android operating system (OS) adhere to a bytecode
> > > +specification that shares much in common with an ABI [DALVIKABI]_. Finally, the Common Language Runtime (CLR)
> > > +designed to execute programs compiled to the Microsoft Intermediate Language (MSIL) has a fully specified
> > > +ABI [CLRABI]_.
> >
> > While this section is certainly useful background for the reader, I'm
> > also not sure it's necessary or appropriate to include. These ABIs are
> > independent of this one, and could change at any time. It's probably
> > best if we avoid referencing external documents that aren't actual
> > dependencies of this document. Feel free to disagree.
>
> You make an excellent point. Although v2 does not make this change, do
> you think that a reasonable adjustment would be to simply move this
> section to the end of the document?
My initial expectation is that it's not a great idea to reference
external documents that could change, no longer be valid links, etc, but
I'd like to hear what others think. Dave -- is this typical for an IETF
informational document? It seems like if we did this we'd basically be
taking implicit dependencies on documents we can't actually control
(because they're not IETF), but I have no idea if this is normal or not.
> >
> > > +Vocabulary
> > > +==========
> > > +
> > > +#. Program: An eBPF Program is a self-contained set of eBPF instructions that execute
> > > + on an eBPF processor.
> >
> > I wonder if we want to be a bit more concrete here. "Self-contained",
> > for example, is arguably a bit ambiguous in terms of what it means. What
> > do you think about this?
> >
> > "Program: A BPF Program is an ordered set of BPF instructions, with
> > exactly one entry instruction where the program begins, and one or more
> > BPF_EXIT instructions where program execution can end."
>
> This suggestion is fantastic and I have used it verbatim!
>
> >
> > > +#. Program Type: Every eBPF program has an associated type. The program type defines, among other things,
> > > + a program's possible attach types.
> > > +#. Attach Type: An attach type defines the set of BPF hook points to which an eBPF
> > > + program can attach.
> > > +#. BPF Hook Points: Places in a BPF-enabled component (e.g., the Linux Kernel, the Windows kernel) where
> > > + an eBPF program may be attached.
> >
> > Hmm, I'm not sure if having this vocabulary section at the beginning of
> > the document is optimal. Consider that the above 3 definitions are quite
> > sparse, and essentially do nothing other than reference each other, and
> > they're also leaving out a lot of detail that will be explored more
> > substantively later in the document (or in the framework / architecture
> > informational document described in [0]).
> >
> > [0]: https://datatracker.ietf.org/wg/bpf/about/
> >
> > It seems like it might make more sense to follow the approach taken by
> > the JVM specification [1], SysV ABI [2], and RISC-V psABI [3] (though
> > they do have a section that defines appreviations and a couple of
> > terms), and instead just have each chapter explain all of these concepts
> > in more detail without any kind of introduction. What do you think?
>
> I could go either way. Personally, when I read documents, I like
> having a vocabulary section to give me some bearing. That way, as I
> read the document, I know where to turn to see whether words with
> which I am unfamiliar are things that I "should know" (and therefore
> just Google) or are new terminology from this document. Again, I could
>
> absolutely go either way and certainly appreciate your references to
> other documents that work differently. When I wrote this section I
> envisioned it like the vocabulary section from the C++ standard where
> new terms of art are given basic definitions that are later expanded
> throughout the document.
>
> What if we did both -- we could keep the vocabulary section and
> include pointers to the places later in the specification where the
> terms are explained in additional detail?
If we did this, then the vocabulary section would become a combination
of a table of contents, and an index of sorts. I personally find that in
documents such as the C and C++ standard, that the terms section ends up
being arbitrarily chosen, and insufficiently defined (see all the Notes
sections peppered throughout these terms).
I'd again appreciate hearing other folks' thoughts here. I'm inclined to
say that the document would be better served by having a clear table of
contents where these terms are specified and defined in one place, but I
don't have a super strong opinion.
> > [1]: https://docs.oracle.com/javase/specs/jvms/se21/html/index.html
> > [2]: https://refspecs.linuxfoundation.org/elf/x86_64-abi-0.95.pdf
> > [3]: https://github.com/riscv-non-isa/riscv-elf-psabi-doc/releases/download/draft-20230929-e5c800e661a53efe3c2678d71a306323b60eb13b/riscv-abi.pdf
> >
> > > +#. eBPF Machine Instantiation:
> > > +#. ABI-conforming system: A computer system that provides the binary sys- tem interface for application
> > > + programs described in the System V ABI [SYSVABI]_.
> > > +#. ABI-conforming program: A program written to include only the system routines, commands, and other
> > > + resources included in the ABI, and a program compiled into an executable file that has the formats
> > > + and characteristics specified for such files in the ABI, and a program whose behavior complies with
> > > + the rules given in the ABI [SYSVABI]_.
> > > +#. ABI-nonconforming program: A program which has been written to include system routines, commands, or
> > > + other resources not included in the ABI, or a program which has been compiled into a format different
> > > + from those specified in the ABI, or a program which does not behave as specified in the ABI [SYSVABI]_.
> > > +#. Undefined Behavior: Behavior that may vary from instance to instance or may change at some time in the future.
> > > + Some undesirable programming practices are marked in the ABI as yielding undefined behavior [SYSVABI]_.
> > > +#. Unspecified Property: A property of an entity that is not explicitly included or referenced in this specification,
> > > + and may change at some time in the future. In general, it is not good practice to make a program depend
> > > + on an unspecified property [SYSVABI]_.
> > > +
> > > +Program Execution Environment
> > > +=============================
> > > +
> > > +A loaded eBPF program is executed on an eBPF machine. That machine, physical or virtual, runs in a freestanding
> > > +or hosted environment [#]_.
> > > +
> > > +eBPF Machine Freestanding Environment
> > > +-------------------------------------
> > > +
> > > +
> > > +eBPF Machine Hosted Environment
> > > +-------------------------------
> > > +
> > > +A loaded eBPF program can be attached to a BPF hook point in a BPF-enabled application
> > > +compatible with the attach type of its program type. When the BPF-enabled application's
> > > +execution reaches a BPF hook point to which an eBPF program is attached, that program
> > > +begins execution on the eBPF machine at its first instruction. The contents of eBPF machine's
> > > +registers and memory at the time it starts execution are defined by the eBPF program's
> > > +type and attach point.
> > > +
> > > +Processor Architecture
> > > +======================
> > > +
> > > +This section describes the processor architecture available
> > > +to programs. It also defines the reference language data types, giving the
> > > +foundation for system interface specifications [SYSVABI]_
> >
> > Why are we linking to the SYSVABI doc here?
>
> A great question -- in most places where I have referenced that
> document it is akin to an academic reference -- I am attempting to
> give the user the idea that the language used is not my own completely
> original thought. I am attempting to tell the reader that this concept
> or language has precedent in another document. I am very new to the
> standards-writing process and realize that utilization of citations
> may not be "how it works". Please let me know how to proceed!
I'm not sure how it works either, so folks who have more IETF experience
-- please weigh in. In similar fashion to above, this feels like we're
implicitly taking these other documents as dependencies. We certainly
don't want to plagiarize anything, but tagging a reference here to
function similar to a citation seems confusing as well.
> >
> > > +
> > > +Registers
> > > +---------
> > > +
> > > +General Purpose Registers
> > > +^^^^^^^^^^^^^^^^^^^^^^^^^
> > > +eBPF has 11 64-bit wide registers, `r0` - `r10`. The contents of the registers
> > > +at the beginning of an eBPF program's execution depend on the program's type.
> >
> > We should probably also mention the 32 bit subregisters (they can only
> > be accessed through special ALU operations), and that they zero-extend
> > into 64 bit on writes.
>
> I added a note on the subregisters. I decided to leave out the
> information about how they zero extend on writes. I thought that was
> something that should remain entirely within the scope of the ISA.
> Please let me know if I am wrong!
Sounds good
[...]
> > > +C Programming Language Support
> > > +==============================
> > > +
> > > +**NOTE** This section could be included in order to define the contents
> > > +of standardized processor-specific header files that would make it easier
> > > +for programmers to write programs.
> > > +
> > > +Notes
> > > +=====
> > > +.. [#] The eBPF machine does not need to be a physical instantiation of a processor. In fact, many instantiations of eBPF machines are virtual.
> > > +.. [#] See the [CSTD]_ for the inspiration for this distinction.
> > > +
> > > +References
> > > +==========
> > > +
> > > +.. [SYSVABI] System V Application Binary Interface - Edition 4.1. SCO Developer Specs. The Santa Cruz Operation. 1997. https://www.sco.com/developers/devspecs/gabi41.pdf
> > > +.. [POWERPCABI] Developing PowerPC Embedded Application Binary Interface (EABI) Compliant Programs. PowerPC Embedded Processors Application Note. IBM. 1998. http://class.ece.iastate.edu/arun/Cpre381_Sp06/lab/labw12a/eabi_app.pdf
> > > +.. [GOABI] Go internal ABI specification. Go Source Code. No authors. 2023. https://go.googlesource.com/go/+/refs/heads/master/src/cmd/compile/abi-internal.md
> > > +.. [JAVAABI] The Java (r) Language Specification - Java SE 7 Edition. Gosling, James et. al. Oracle. 2013. https://docs.oracle.com/javase/specs/jls/se7/html/index.html
> >
> > If we do share a link, it should probably be to the Java Virtual Machine
> > specification rather than the language specification. I believe the most
> > recent edition is 21.
>
> I checked and the binary compatibility piece of the specification is
> actually in the language spec. That said, it might make sense to just
> link to both? I am willing to do whatever you suggest!
Ah, fair enough. Let's still link the latest version though rather than
version 7.
> > > +.. [DALVIKABI] Dalvik Bytecode. Android Core Runtime Documentation. No authors. Google. 2022. https://source.android.com/docs/core/runtime/dalvik-bytecode
> > > +.. [CLRABI] CLR ABI. The Book of the Runtime. No authors. Microsoft. 2023. https://github.com/dotnet/coreclr/blob/master/Documentation/botr/clr-abi.md.
> > > +.. [CSTD] International Standard: Programming Languages - C. ISO/IEC. 2018. https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2310.pdf.
> > > +.. [RHELABI] Red Hat Enterprise Linux 8: Application Compatibility Guide. Red Hat. 2023. https://access.redhat.com/articles/rhel8-abi-compatibility
> > > +
> >
> > Everything else looks fine for now. Something I think we should figure
> > out though is what we want to put each of the following docs from the
> > charter:
>
> I reflowed the entire document to make sure that the text is at most 80 columns.
>
>
>
> >
> > - [I] one or more documents that recommend conventions and guidelines
> > for producing portable BPF program binaries,
> >
> > - [I] an architecture and framework document.
> >
> > It seems like some of what's going into this document (e.g. formally
> > defining a "Program", data types, etc) could arguably belong in an
> > architecture and framework document. Honestly, I think it would probably
> > be easier and make more sense to just have a single monolithic BPF
> > Machine informational document, though I'm not sure if that's viable at
> > this point given that we specified different documents in the charter.
>
> You make (as usual) an excellent point. I think that this question is
> something that would be good to discuss as a group? Because you are
> the chair, David, I will defer to you!
Discussing as a group is a great idea. Maybe this would be something to
discuss at IETF 118?
Thanks,
David
^ permalink raw reply [flat|nested] 42+ messages in thread* Re: [Bpf] [PATCH] bpf, docs: Add additional ABI working draft base text
2023-10-24 0:55 ` [PATCH] " David Vernet
@ 2023-10-24 0:55 ` David Vernet
2023-10-24 4:02 ` Christoph Hellwig
2023-11-03 21:14 ` Will Hawkins
2 siblings, 0 replies; 42+ messages in thread
From: David Vernet @ 2023-10-24 0:55 UTC (permalink / raw)
To: Will Hawkins; +Cc: bpf, bpf
On Sat, Oct 21, 2023 at 07:13:58PM -0400, Will Hawkins wrote:
[...]
> > > +instantiations of eBPF machines. In addition, it defines the details that must be specified by each
> > > +processor-specific ABI.
> > > +
> > > +These psABIs are the second part of the ABI. Each instantiation of an eBPF machine must
> > > +describe the mechanism through which binary interface compatibility is maintained with
> > > +respect to the issues highlighted by this document. However, the details that must be
> > > +defined by a psABI are a minimum -- a psABI may specify additional requirements for binary
> > > +interface compatibility on a platform.
> > > +
> > > +.. contents::
> > > +.. sectnum::
> > > +
> > > +How To Use This ABI
> > > +===================
> > > +
> > > +Conformance
> > > +===========
> > > +
> > > +Note: Red Hat specifies different levels of conformance over time [RHELABI]_.
> >
> > I don't think we should specify conformance guidelines for a
> > distribution as part of the standardization document. RHEL, Debian,
> > future distros, Windows, etc, can all decide what guidelines they give
> > developers for backward compatibility, etc with their release cycles,
> > but that's entirely separate from a standardization document that's
> > enumerating generic or psABIs.
>
> I agree 100%. The "Note:" here was more an author's "note to self"
> about where we could look for other existing language that we could
> appropriate to include in this document. I have updated the Note: to
> be an Author's Note (here and elsewhere) to make that more obvious. I
> hope that is okay!
Hmm, I think that could get confusing. Can we just add comments anywhere
that we want to be able to record places for us to use as a reference
for language later? Ideally anything going into the document should be
text that we're intending to eventually publish, perhaps with the
exception of things like XXX: Fill in later.
> > > +Related Work
> > > +============
> > > +eBPF programs are not unique for the way that they operate on a virtualized machine and processor.
> > > +There are many programming languages that compile to an ISA that is specific to a virtual machine.
> > > +Like the specification presented herein, those languages and virtual machines also have ABIs.
> > > +
> > > +For example, the Go programming language and the runtime included statically with each program compiled
> > > +from Go source code have a defined ABI [GOABI]_. Java programs compiled to bytecode follow a well-defined
> > > +ABI for interoperability with other compiled Java programs and libraries [JAVAABI]_. Programs compiled to
> > > +bytecode for execution as user applications on the Android operating system (OS) adhere to a bytecode
> > > +specification that shares much in common with an ABI [DALVIKABI]_. Finally, the Common Language Runtime (CLR)
> > > +designed to execute programs compiled to the Microsoft Intermediate Language (MSIL) has a fully specified
> > > +ABI [CLRABI]_.
> >
> > While this section is certainly useful background for the reader, I'm
> > also not sure it's necessary or appropriate to include. These ABIs are
> > independent of this one, and could change at any time. It's probably
> > best if we avoid referencing external documents that aren't actual
> > dependencies of this document. Feel free to disagree.
>
> You make an excellent point. Although v2 does not make this change, do
> you think that a reasonable adjustment would be to simply move this
> section to the end of the document?
My initial expectation is that it's not a great idea to reference
external documents that could change, no longer be valid links, etc, but
I'd like to hear what others think. Dave -- is this typical for an IETF
informational document? It seems like if we did this we'd basically be
taking implicit dependencies on documents we can't actually control
(because they're not IETF), but I have no idea if this is normal or not.
> >
> > > +Vocabulary
> > > +==========
> > > +
> > > +#. Program: An eBPF Program is a self-contained set of eBPF instructions that execute
> > > + on an eBPF processor.
> >
> > I wonder if we want to be a bit more concrete here. "Self-contained",
> > for example, is arguably a bit ambiguous in terms of what it means. What
> > do you think about this?
> >
> > "Program: A BPF Program is an ordered set of BPF instructions, with
> > exactly one entry instruction where the program begins, and one or more
> > BPF_EXIT instructions where program execution can end."
>
> This suggestion is fantastic and I have used it verbatim!
>
> >
> > > +#. Program Type: Every eBPF program has an associated type. The program type defines, among other things,
> > > + a program's possible attach types.
> > > +#. Attach Type: An attach type defines the set of BPF hook points to which an eBPF
> > > + program can attach.
> > > +#. BPF Hook Points: Places in a BPF-enabled component (e.g., the Linux Kernel, the Windows kernel) where
> > > + an eBPF program may be attached.
> >
> > Hmm, I'm not sure if having this vocabulary section at the beginning of
> > the document is optimal. Consider that the above 3 definitions are quite
> > sparse, and essentially do nothing other than reference each other, and
> > they're also leaving out a lot of detail that will be explored more
> > substantively later in the document (or in the framework / architecture
> > informational document described in [0]).
> >
> > [0]: https://datatracker.ietf.org/wg/bpf/about/
> >
> > It seems like it might make more sense to follow the approach taken by
> > the JVM specification [1], SysV ABI [2], and RISC-V psABI [3] (though
> > they do have a section that defines appreviations and a couple of
> > terms), and instead just have each chapter explain all of these concepts
> > in more detail without any kind of introduction. What do you think?
>
> I could go either way. Personally, when I read documents, I like
> having a vocabulary section to give me some bearing. That way, as I
> read the document, I know where to turn to see whether words with
> which I am unfamiliar are things that I "should know" (and therefore
> just Google) or are new terminology from this document. Again, I could
>
> absolutely go either way and certainly appreciate your references to
> other documents that work differently. When I wrote this section I
> envisioned it like the vocabulary section from the C++ standard where
> new terms of art are given basic definitions that are later expanded
> throughout the document.
>
> What if we did both -- we could keep the vocabulary section and
> include pointers to the places later in the specification where the
> terms are explained in additional detail?
If we did this, then the vocabulary section would become a combination
of a table of contents, and an index of sorts. I personally find that in
documents such as the C and C++ standard, that the terms section ends up
being arbitrarily chosen, and insufficiently defined (see all the Notes
sections peppered throughout these terms).
I'd again appreciate hearing other folks' thoughts here. I'm inclined to
say that the document would be better served by having a clear table of
contents where these terms are specified and defined in one place, but I
don't have a super strong opinion.
> > [1]: https://docs.oracle.com/javase/specs/jvms/se21/html/index.html
> > [2]: https://refspecs.linuxfoundation.org/elf/x86_64-abi-0.95.pdf
> > [3]: https://github.com/riscv-non-isa/riscv-elf-psabi-doc/releases/download/draft-20230929-e5c800e661a53efe3c2678d71a306323b60eb13b/riscv-abi.pdf
> >
> > > +#. eBPF Machine Instantiation:
> > > +#. ABI-conforming system: A computer system that provides the binary sys- tem interface for application
> > > + programs described in the System V ABI [SYSVABI]_.
> > > +#. ABI-conforming program: A program written to include only the system routines, commands, and other
> > > + resources included in the ABI, and a program compiled into an executable file that has the formats
> > > + and characteristics specified for such files in the ABI, and a program whose behavior complies with
> > > + the rules given in the ABI [SYSVABI]_.
> > > +#. ABI-nonconforming program: A program which has been written to include system routines, commands, or
> > > + other resources not included in the ABI, or a program which has been compiled into a format different
> > > + from those specified in the ABI, or a program which does not behave as specified in the ABI [SYSVABI]_.
> > > +#. Undefined Behavior: Behavior that may vary from instance to instance or may change at some time in the future.
> > > + Some undesirable programming practices are marked in the ABI as yielding undefined behavior [SYSVABI]_.
> > > +#. Unspecified Property: A property of an entity that is not explicitly included or referenced in this specification,
> > > + and may change at some time in the future. In general, it is not good practice to make a program depend
> > > + on an unspecified property [SYSVABI]_.
> > > +
> > > +Program Execution Environment
> > > +=============================
> > > +
> > > +A loaded eBPF program is executed on an eBPF machine. That machine, physical or virtual, runs in a freestanding
> > > +or hosted environment [#]_.
> > > +
> > > +eBPF Machine Freestanding Environment
> > > +-------------------------------------
> > > +
> > > +
> > > +eBPF Machine Hosted Environment
> > > +-------------------------------
> > > +
> > > +A loaded eBPF program can be attached to a BPF hook point in a BPF-enabled application
> > > +compatible with the attach type of its program type. When the BPF-enabled application's
> > > +execution reaches a BPF hook point to which an eBPF program is attached, that program
> > > +begins execution on the eBPF machine at its first instruction. The contents of eBPF machine's
> > > +registers and memory at the time it starts execution are defined by the eBPF program's
> > > +type and attach point.
> > > +
> > > +Processor Architecture
> > > +======================
> > > +
> > > +This section describes the processor architecture available
> > > +to programs. It also defines the reference language data types, giving the
> > > +foundation for system interface specifications [SYSVABI]_
> >
> > Why are we linking to the SYSVABI doc here?
>
> A great question -- in most places where I have referenced that
> document it is akin to an academic reference -- I am attempting to
> give the user the idea that the language used is not my own completely
> original thought. I am attempting to tell the reader that this concept
> or language has precedent in another document. I am very new to the
> standards-writing process and realize that utilization of citations
> may not be "how it works". Please let me know how to proceed!
I'm not sure how it works either, so folks who have more IETF experience
-- please weigh in. In similar fashion to above, this feels like we're
implicitly taking these other documents as dependencies. We certainly
don't want to plagiarize anything, but tagging a reference here to
function similar to a citation seems confusing as well.
> >
> > > +
> > > +Registers
> > > +---------
> > > +
> > > +General Purpose Registers
> > > +^^^^^^^^^^^^^^^^^^^^^^^^^
> > > +eBPF has 11 64-bit wide registers, `r0` - `r10`. The contents of the registers
> > > +at the beginning of an eBPF program's execution depend on the program's type.
> >
> > We should probably also mention the 32 bit subregisters (they can only
> > be accessed through special ALU operations), and that they zero-extend
> > into 64 bit on writes.
>
> I added a note on the subregisters. I decided to leave out the
> information about how they zero extend on writes. I thought that was
> something that should remain entirely within the scope of the ISA.
> Please let me know if I am wrong!
Sounds good
[...]
> > > +C Programming Language Support
> > > +==============================
> > > +
> > > +**NOTE** This section could be included in order to define the contents
> > > +of standardized processor-specific header files that would make it easier
> > > +for programmers to write programs.
> > > +
> > > +Notes
> > > +=====
> > > +.. [#] The eBPF machine does not need to be a physical instantiation of a processor. In fact, many instantiations of eBPF machines are virtual.
> > > +.. [#] See the [CSTD]_ for the inspiration for this distinction.
> > > +
> > > +References
> > > +==========
> > > +
> > > +.. [SYSVABI] System V Application Binary Interface - Edition 4.1. SCO Developer Specs. The Santa Cruz Operation. 1997. https://www.sco.com/developers/devspecs/gabi41.pdf
> > > +.. [POWERPCABI] Developing PowerPC Embedded Application Binary Interface (EABI) Compliant Programs. PowerPC Embedded Processors Application Note. IBM. 1998. http://class.ece.iastate.edu/arun/Cpre381_Sp06/lab/labw12a/eabi_app.pdf
> > > +.. [GOABI] Go internal ABI specification. Go Source Code. No authors. 2023. https://go.googlesource.com/go/+/refs/heads/master/src/cmd/compile/abi-internal.md
> > > +.. [JAVAABI] The Java (r) Language Specification - Java SE 7 Edition. Gosling, James et. al. Oracle. 2013. https://docs.oracle.com/javase/specs/jls/se7/html/index.html
> >
> > If we do share a link, it should probably be to the Java Virtual Machine
> > specification rather than the language specification. I believe the most
> > recent edition is 21.
>
> I checked and the binary compatibility piece of the specification is
> actually in the language spec. That said, it might make sense to just
> link to both? I am willing to do whatever you suggest!
Ah, fair enough. Let's still link the latest version though rather than
version 7.
> > > +.. [DALVIKABI] Dalvik Bytecode. Android Core Runtime Documentation. No authors. Google. 2022. https://source.android.com/docs/core/runtime/dalvik-bytecode
> > > +.. [CLRABI] CLR ABI. The Book of the Runtime. No authors. Microsoft. 2023. https://github.com/dotnet/coreclr/blob/master/Documentation/botr/clr-abi.md.
> > > +.. [CSTD] International Standard: Programming Languages - C. ISO/IEC. 2018. https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2310.pdf.
> > > +.. [RHELABI] Red Hat Enterprise Linux 8: Application Compatibility Guide. Red Hat. 2023. https://access.redhat.com/articles/rhel8-abi-compatibility
> > > +
> >
> > Everything else looks fine for now. Something I think we should figure
> > out though is what we want to put each of the following docs from the
> > charter:
>
> I reflowed the entire document to make sure that the text is at most 80 columns.
>
>
>
> >
> > - [I] one or more documents that recommend conventions and guidelines
> > for producing portable BPF program binaries,
> >
> > - [I] an architecture and framework document.
> >
> > It seems like some of what's going into this document (e.g. formally
> > defining a "Program", data types, etc) could arguably belong in an
> > architecture and framework document. Honestly, I think it would probably
> > be easier and make more sense to just have a single monolithic BPF
> > Machine informational document, though I'm not sure if that's viable at
> > this point given that we specified different documents in the charter.
>
> You make (as usual) an excellent point. I think that this question is
> something that would be good to discuss as a group? Because you are
> the chair, David, I will defer to you!
Discussing as a group is a great idea. Maybe this would be something to
discuss at IETF 118?
Thanks,
David
--
Bpf mailing list
Bpf@ietf.org
https://www.ietf.org/mailman/listinfo/bpf
^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [Bpf] [PATCH] bpf, docs: Add additional ABI working draft base text
2023-10-24 0:55 ` [PATCH] " David Vernet
2023-10-24 0:55 ` [Bpf] " David Vernet
@ 2023-10-24 4:02 ` Christoph Hellwig
2023-10-24 4:02 ` Christoph Hellwig
2023-11-03 21:14 ` Will Hawkins
2 siblings, 1 reply; 42+ messages in thread
From: Christoph Hellwig @ 2023-10-24 4:02 UTC (permalink / raw)
To: David Vernet; +Cc: Will Hawkins, bpf, bpf
On Mon, Oct 23, 2023 at 07:55:28PM -0500, David Vernet wrote:
> > You make an excellent point. Although v2 does not make this change, do
> > you think that a reasonable adjustment would be to simply move this
> > section to the end of the document?
>
> My initial expectation is that it's not a great idea to reference
> external documents that could change, no longer be valid links, etc, but
> I'd like to hear what others think. Dave -- is this typical for an IETF
> informational document? It seems like if we did this we'd basically be
> taking implicit dependencies on documents we can't actually control
> (because they're not IETF), but I have no idea if this is normal or not.
IETF prefers IETF references, and if not stable standards-like
documents. Even those will get careful review (talking as someone
with a draft that has normative SCSI and NVMe references right now).
For non-normative references this is a bit relaxed, but a random url
that can change is never acceptable.
^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [Bpf] [PATCH] bpf, docs: Add additional ABI working draft base text
2023-10-24 4:02 ` Christoph Hellwig
@ 2023-10-24 4:02 ` Christoph Hellwig
0 siblings, 0 replies; 42+ messages in thread
From: Christoph Hellwig @ 2023-10-24 4:02 UTC (permalink / raw)
To: David Vernet; +Cc: Will Hawkins, bpf, bpf
On Mon, Oct 23, 2023 at 07:55:28PM -0500, David Vernet wrote:
> > You make an excellent point. Although v2 does not make this change, do
> > you think that a reasonable adjustment would be to simply move this
> > section to the end of the document?
>
> My initial expectation is that it's not a great idea to reference
> external documents that could change, no longer be valid links, etc, but
> I'd like to hear what others think. Dave -- is this typical for an IETF
> informational document? It seems like if we did this we'd basically be
> taking implicit dependencies on documents we can't actually control
> (because they're not IETF), but I have no idea if this is normal or not.
IETF prefers IETF references, and if not stable standards-like
documents. Even those will get careful review (talking as someone
with a draft that has normative SCSI and NVMe references right now).
For non-normative references this is a bit relaxed, but a random url
that can change is never acceptable.
--
Bpf mailing list
Bpf@ietf.org
https://www.ietf.org/mailman/listinfo/bpf
^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [Bpf] [PATCH] bpf, docs: Add additional ABI working draft base text
2023-10-24 0:55 ` [PATCH] " David Vernet
2023-10-24 0:55 ` [Bpf] " David Vernet
2023-10-24 4:02 ` Christoph Hellwig
@ 2023-11-03 21:14 ` Will Hawkins
2023-11-03 21:14 ` Will Hawkins
2023-11-03 21:20 ` [PATCH v3] " Will Hawkins
2 siblings, 2 replies; 42+ messages in thread
From: Will Hawkins @ 2023-11-03 21:14 UTC (permalink / raw)
To: David Vernet; +Cc: bpf, bpf
On Mon, Oct 23, 2023 at 8:55 PM David Vernet <void@manifault.com> wrote:
>
> On Sat, Oct 21, 2023 at 07:13:58PM -0400, Will Hawkins wrote:
>
> [...]
>
> [...]
> > I agree 100%. The "Note:" here was more an author's "note to self"
> > about where we could look for other existing language that we could
> > appropriate to include in this document. I have updated the Note: to
> > be an Author's Note (here and elsewhere) to make that more obvious. I
> > hope that is okay!
>
> Hmm, I think that could get confusing. Can we just add comments anywhere
> that we want to be able to record places for us to use as a reference
> for language later? Ideally anything going into the document should be
> text that we're intending to eventually publish, perhaps with the
> exception of things like XXX: Fill in later.
Thank you for the feedback! I took out all the Author's Note sections
and simply made them rst comments. I agree with your opinion that
comments are the best way to communicate this information to one
another as we work on drafting out all the language.
>
> > > > +Related Work
> > > > +============
> > > > +eBPF programs are not unique for the way that they operate on a virtualized machine and processor.
> > > > +There are many programming languages that compile to an ISA that is specific to a virtual machine.
> > > > +Like the specification presented herein, those languages and virtual machines also have ABIs.
> > > > +
> > > > +For example, the Go programming language and the runtime included statically with each program compiled
> > > > +from Go source code have a defined ABI [GOABI]_. Java programs compiled to bytecode follow a well-defined
> > > > +ABI for interoperability with other compiled Java programs and libraries [JAVAABI]_. Programs compiled to
> > > > +bytecode for execution as user applications on the Android operating system (OS) adhere to a bytecode
> > > > +specification that shares much in common with an ABI [DALVIKABI]_. Finally, the Common Language Runtime (CLR)
> > > > +designed to execute programs compiled to the Microsoft Intermediate Language (MSIL) has a fully specified
> > > > +ABI [CLRABI]_.
> > >
> > > While this section is certainly useful background for the reader, I'm
> > > also not sure it's necessary or appropriate to include. These ABIs are
> > > independent of this one, and could change at any time. It's probably
> > > best if we avoid referencing external documents that aren't actual
> > > dependencies of this document. Feel free to disagree.
> >
> > You make an excellent point. Although v2 does not make this change, do
> > you think that a reasonable adjustment would be to simply move this
> > section to the end of the document?
>
> My initial expectation is that it's not a great idea to reference
> external documents that could change, no longer be valid links, etc, but
> I'd like to hear what others think. Dave -- is this typical for an IETF
> informational document? It seems like if we did this we'd basically be
> taking implicit dependencies on documents we can't actually control
> (because they're not IETF), but I have no idea if this is normal or not.
>
> > >
> > > > +Vocabulary
> > > > +==========
> > > > +
> > > > +#. Program: An eBPF Program is a self-contained set of eBPF instructions that execute
> > > > + on an eBPF processor.
> > >
> > > I wonder if we want to be a bit more concrete here. "Self-contained",
> > > for example, is arguably a bit ambiguous in terms of what it means. What
> > > do you think about this?
> > >
> > > "Program: A BPF Program is an ordered set of BPF instructions, with
> > > exactly one entry instruction where the program begins, and one or more
> > > BPF_EXIT instructions where program execution can end."
> >
> > This suggestion is fantastic and I have used it verbatim!
> >
> > >
> > > > +#. Program Type: Every eBPF program has an associated type. The program type defines, among other things,
> > > > + a program's possible attach types.
> > > > +#. Attach Type: An attach type defines the set of BPF hook points to which an eBPF
> > > > + program can attach.
> > > > +#. BPF Hook Points: Places in a BPF-enabled component (e.g., the Linux Kernel, the Windows kernel) where
> > > > + an eBPF program may be attached.
> > >
> > > Hmm, I'm not sure if having this vocabulary section at the beginning of
> > > the document is optimal. Consider that the above 3 definitions are quite
> > > sparse, and essentially do nothing other than reference each other, and
> > > they're also leaving out a lot of detail that will be explored more
> > > substantively later in the document (or in the framework / architecture
> > > informational document described in [0]).
> > >
> > > [0]: https://datatracker.ietf.org/wg/bpf/about/
> > >
> > > It seems like it might make more sense to follow the approach taken by
> > > the JVM specification [1], SysV ABI [2], and RISC-V psABI [3] (though
> > > they do have a section that defines appreviations and a couple of
> > > terms), and instead just have each chapter explain all of these concepts
> > > in more detail without any kind of introduction. What do you think?
> >
> > I could go either way. Personally, when I read documents, I like
> > having a vocabulary section to give me some bearing. That way, as I
> > read the document, I know where to turn to see whether words with
> > which I am unfamiliar are things that I "should know" (and therefore
> > just Google) or are new terminology from this document. Again, I could
> >
> > absolutely go either way and certainly appreciate your references to
> > other documents that work differently. When I wrote this section I
> > envisioned it like the vocabulary section from the C++ standard where
> > new terms of art are given basic definitions that are later expanded
> > throughout the document.
> >
> > What if we did both -- we could keep the vocabulary section and
> > include pointers to the places later in the specification where the
> > terms are explained in additional detail?
>
> If we did this, then the vocabulary section would become a combination
> of a table of contents, and an index of sorts. I personally find that in
> documents such as the C and C++ standard, that the terms section ends up
> being arbitrarily chosen, and insufficiently defined (see all the Notes
> sections peppered throughout these terms).
>
> I'd again appreciate hearing other folks' thoughts here. I'm inclined to
> say that the document would be better served by having a clear table of
> contents where these terms are specified and defined in one place, but I
> don't have a super strong opinion.
>
At the end of this email I will suggest a list of ABI-related topics
for the upcoming IETF meeting -- I believe that this discussion would
be worthwhile!
> > > [1]: https://docs.oracle.com/javase/specs/jvms/se21/html/index.html
> > > [2]: https://refspecs.linuxfoundation.org/elf/x86_64-abi-0.95.pdf
> > > [3]: https://github.com/riscv-non-isa/riscv-elf-psabi-doc/releases/download/draft-20230929-e5c800e661a53efe3c2678d71a306323b60eb13b/riscv-abi.pdf
> > >
> > > > +#. eBPF Machine Instantiation:
> > > > +#. ABI-conforming system: A computer system that provides the binary sys- tem interface for application
> > > > + programs described in the System V ABI [SYSVABI]_.
> > > > +#. ABI-conforming program: A program written to include only the system routines, commands, and other
> > > > + resources included in the ABI, and a program compiled into an executable file that has the formats
> > > > + and characteristics specified for such files in the ABI, and a program whose behavior complies with
> > > > + the rules given in the ABI [SYSVABI]_.
> > > > +#. ABI-nonconforming program: A program which has been written to include system routines, commands, or
> > > > + other resources not included in the ABI, or a program which has been compiled into a format different
> > > > + from those specified in the ABI, or a program which does not behave as specified in the ABI [SYSVABI]_.
> > > > +#. Undefined Behavior: Behavior that may vary from instance to instance or may change at some time in the future.
> > > > + Some undesirable programming practices are marked in the ABI as yielding undefined behavior [SYSVABI]_.
> > > > +#. Unspecified Property: A property of an entity that is not explicitly included or referenced in this specification,
> > > > + and may change at some time in the future. In general, it is not good practice to make a program depend
> > > > + on an unspecified property [SYSVABI]_.
> > > > +
> > > > +Program Execution Environment
> > > > +=============================
> > > > +
> > > > +A loaded eBPF program is executed on an eBPF machine. That machine, physical or virtual, runs in a freestanding
> > > > +or hosted environment [#]_.
> > > > +
> > > > +eBPF Machine Freestanding Environment
> > > > +-------------------------------------
> > > > +
> > > > +
> > > > +eBPF Machine Hosted Environment
> > > > +-------------------------------
> > > > +
> > > > +A loaded eBPF program can be attached to a BPF hook point in a BPF-enabled application
> > > > +compatible with the attach type of its program type. When the BPF-enabled application's
> > > > +execution reaches a BPF hook point to which an eBPF program is attached, that program
> > > > +begins execution on the eBPF machine at its first instruction. The contents of eBPF machine's
> > > > +registers and memory at the time it starts execution are defined by the eBPF program's
> > > > +type and attach point.
> > > > +
> > > > +Processor Architecture
> > > > +======================
> > > > +
> > > > +This section describes the processor architecture available
> > > > +to programs. It also defines the reference language data types, giving the
> > > > +foundation for system interface specifications [SYSVABI]_
> > >
> > > Why are we linking to the SYSVABI doc here?
> >
> > A great question -- in most places where I have referenced that
> > document it is akin to an academic reference -- I am attempting to
> > give the user the idea that the language used is not my own completely
> > original thought. I am attempting to tell the reader that this concept
> > or language has precedent in another document. I am very new to the
> > standards-writing process and realize that utilization of citations
> > may not be "how it works". Please let me know how to proceed!
>
> I'm not sure how it works either, so folks who have more IETF experience
> -- please weigh in. In similar fashion to above, this feels like we're
> implicitly taking these other documents as dependencies. We certainly
> don't want to plagiarize anything, but tagging a reference here to
> function similar to a citation seems confusing as well.
Adding to IETF the topic list (see below).
>
> > >
> > > > +
> > > > +Registers
> > > > +---------
> > > > +
> > > > +General Purpose Registers
> > > > +^^^^^^^^^^^^^^^^^^^^^^^^^
> > > > +eBPF has 11 64-bit wide registers, `r0` - `r10`. The contents of the registers
> > > > +at the beginning of an eBPF program's execution depend on the program's type.
> > >
> > > We should probably also mention the 32 bit subregisters (they can only
> > > be accessed through special ALU operations), and that they zero-extend
> > > into 64 bit on writes.
> >
> > I added a note on the subregisters. I decided to leave out the
> > information about how they zero extend on writes. I thought that was
> > something that should remain entirely within the scope of the ISA.
> > Please let me know if I am wrong!
>
> Sounds good
>
> [...]
>
> > > > +C Programming Language Support
> > > > +==============================
> > > > +
> > > > +**NOTE** This section could be included in order to define the contents
> > > > +of standardized processor-specific header files that would make it easier
> > > > +for programmers to write programs.
> > > > +
> > > > +Notes
> > > > +=====
> > > > +.. [#] The eBPF machine does not need to be a physical instantiation of a processor. In fact, many instantiations of eBPF machines are virtual.
> > > > +.. [#] See the [CSTD]_ for the inspiration for this distinction.
> > > > +
> > > > +References
> > > > +==========
> > > > +
> > > > +.. [SYSVABI] System V Application Binary Interface - Edition 4.1. SCO Developer Specs. The Santa Cruz Operation. 1997. https://www.sco.com/developers/devspecs/gabi41.pdf
> > > > +.. [POWERPCABI] Developing PowerPC Embedded Application Binary Interface (EABI) Compliant Programs. PowerPC Embedded Processors Application Note. IBM. 1998. http://class.ece.iastate.edu/arun/Cpre381_Sp06/lab/labw12a/eabi_app.pdf
> > > > +.. [GOABI] Go internal ABI specification. Go Source Code. No authors. 2023. https://go.googlesource.com/go/+/refs/heads/master/src/cmd/compile/abi-internal.md
> > > > +.. [JAVAABI] The Java (r) Language Specification - Java SE 7 Edition. Gosling, James et. al. Oracle. 2013. https://docs.oracle.com/javase/specs/jls/se7/html/index.html
> > >
> > > If we do share a link, it should probably be to the Java Virtual Machine
> > > specification rather than the language specification. I believe the most
> > > recent edition is 21.
> >
> > I checked and the binary compatibility piece of the specification is
> > actually in the language spec. That said, it might make sense to just
> > link to both? I am willing to do whatever you suggest!
>
> Ah, fair enough. Let's still link the latest version though rather than
> version 7.
This change is made in v3 of the patch -- thank you!
>
> > > > +.. [DALVIKABI] Dalvik Bytecode. Android Core Runtime Documentation. No authors. Google. 2022. https://source.android.com/docs/core/runtime/dalvik-bytecode
> > > > +.. [CLRABI] CLR ABI. The Book of the Runtime. No authors. Microsoft. 2023. https://github.com/dotnet/coreclr/blob/master/Documentation/botr/clr-abi.md.
> > > > +.. [CSTD] International Standard: Programming Languages - C. ISO/IEC. 2018. https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2310.pdf.
> > > > +.. [RHELABI] Red Hat Enterprise Linux 8: Application Compatibility Guide. Red Hat. 2023. https://access.redhat.com/articles/rhel8-abi-compatibility
> > > > +
> > >
> > > Everything else looks fine for now. Something I think we should figure
> > > out though is what we want to put each of the following docs from the
> > > charter:
> >
> > I reflowed the entire document to make sure that the text is at most 80 columns.
> >
> >
> >
> > >
> > > - [I] one or more documents that recommend conventions and guidelines
> > > for producing portable BPF program binaries,
> > >
> > > - [I] an architecture and framework document.
> > >
> > > It seems like some of what's going into this document (e.g. formally
> > > defining a "Program", data types, etc) could arguably belong in an
> > > architecture and framework document. Honestly, I think it would probably
> > > be easier and make more sense to just have a single monolithic BPF
> > > Machine informational document, though I'm not sure if that's viable at
> > > this point given that we specified different documents in the charter.
> >
> > You make (as usual) an excellent point. I think that this question is
> > something that would be good to discuss as a group? Because you are
> > the chair, David, I will defer to you!
>
> Discussing as a group is a great idea. Maybe this would be something to
> discuss at IETF 118?
I believe that we can have a great discussion at 118 on the following
ABI-related topics:
1. Can references in IETF standards documents be used like citations
in an academic article?
When I drafted the original version of the text, I added references to
other (ABI or general) documents because they were the source for
certain language or ideas. That is what an author would do in the
world of academic publishing to make sure that they did not give the
reader the impression that certain words or ideas were their original
writing or thought. I am not sure how IETF handles this situation but
I want to make sure that I am doing the right thing -- I don't want
anyone to get the idea that I am smarter than I am!
2. Related to 1: If we do need/want to make references to external,
non-IETF documents, what is the process for that?
3. Does the vocabulary section
- Stay roughly as it is now?
Basically a set of topic-specific words with introductory/brief definitions.
- Get replaced with a simple TOC?
That way the terms can be defined completely and fully in a single place.
- Turn into a combination of the prior two options?
The vocabulary definitions would be brief summaries of the more
complete definition and the text would include a reference to the
section of the document where the term is completely defined.
I unfortunately will not be able to be 118 in person but I do plan on
being present virtually! I am looking forward to talking to everyone!
Please have a great weekend!
Will
>
> Thanks,
> David
--
Bpf mailing list
Bpf@ietf.org
https://www.ietf.org/mailman/listinfo/bpf
^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [PATCH] bpf, docs: Add additional ABI working draft base text
2023-11-03 21:14 ` Will Hawkins
@ 2023-11-03 21:14 ` Will Hawkins
2023-11-03 21:20 ` [PATCH v3] " Will Hawkins
1 sibling, 0 replies; 42+ messages in thread
From: Will Hawkins @ 2023-11-03 21:14 UTC (permalink / raw)
To: David Vernet; +Cc: bpf, bpf
On Mon, Oct 23, 2023 at 8:55 PM David Vernet <void@manifault.com> wrote:
>
> On Sat, Oct 21, 2023 at 07:13:58PM -0400, Will Hawkins wrote:
>
> [...]
>
> [...]
> > I agree 100%. The "Note:" here was more an author's "note to self"
> > about where we could look for other existing language that we could
> > appropriate to include in this document. I have updated the Note: to
> > be an Author's Note (here and elsewhere) to make that more obvious. I
> > hope that is okay!
>
> Hmm, I think that could get confusing. Can we just add comments anywhere
> that we want to be able to record places for us to use as a reference
> for language later? Ideally anything going into the document should be
> text that we're intending to eventually publish, perhaps with the
> exception of things like XXX: Fill in later.
Thank you for the feedback! I took out all the Author's Note sections
and simply made them rst comments. I agree with your opinion that
comments are the best way to communicate this information to one
another as we work on drafting out all the language.
>
> > > > +Related Work
> > > > +============
> > > > +eBPF programs are not unique for the way that they operate on a virtualized machine and processor.
> > > > +There are many programming languages that compile to an ISA that is specific to a virtual machine.
> > > > +Like the specification presented herein, those languages and virtual machines also have ABIs.
> > > > +
> > > > +For example, the Go programming language and the runtime included statically with each program compiled
> > > > +from Go source code have a defined ABI [GOABI]_. Java programs compiled to bytecode follow a well-defined
> > > > +ABI for interoperability with other compiled Java programs and libraries [JAVAABI]_. Programs compiled to
> > > > +bytecode for execution as user applications on the Android operating system (OS) adhere to a bytecode
> > > > +specification that shares much in common with an ABI [DALVIKABI]_. Finally, the Common Language Runtime (CLR)
> > > > +designed to execute programs compiled to the Microsoft Intermediate Language (MSIL) has a fully specified
> > > > +ABI [CLRABI]_.
> > >
> > > While this section is certainly useful background for the reader, I'm
> > > also not sure it's necessary or appropriate to include. These ABIs are
> > > independent of this one, and could change at any time. It's probably
> > > best if we avoid referencing external documents that aren't actual
> > > dependencies of this document. Feel free to disagree.
> >
> > You make an excellent point. Although v2 does not make this change, do
> > you think that a reasonable adjustment would be to simply move this
> > section to the end of the document?
>
> My initial expectation is that it's not a great idea to reference
> external documents that could change, no longer be valid links, etc, but
> I'd like to hear what others think. Dave -- is this typical for an IETF
> informational document? It seems like if we did this we'd basically be
> taking implicit dependencies on documents we can't actually control
> (because they're not IETF), but I have no idea if this is normal or not.
>
> > >
> > > > +Vocabulary
> > > > +==========
> > > > +
> > > > +#. Program: An eBPF Program is a self-contained set of eBPF instructions that execute
> > > > + on an eBPF processor.
> > >
> > > I wonder if we want to be a bit more concrete here. "Self-contained",
> > > for example, is arguably a bit ambiguous in terms of what it means. What
> > > do you think about this?
> > >
> > > "Program: A BPF Program is an ordered set of BPF instructions, with
> > > exactly one entry instruction where the program begins, and one or more
> > > BPF_EXIT instructions where program execution can end."
> >
> > This suggestion is fantastic and I have used it verbatim!
> >
> > >
> > > > +#. Program Type: Every eBPF program has an associated type. The program type defines, among other things,
> > > > + a program's possible attach types.
> > > > +#. Attach Type: An attach type defines the set of BPF hook points to which an eBPF
> > > > + program can attach.
> > > > +#. BPF Hook Points: Places in a BPF-enabled component (e.g., the Linux Kernel, the Windows kernel) where
> > > > + an eBPF program may be attached.
> > >
> > > Hmm, I'm not sure if having this vocabulary section at the beginning of
> > > the document is optimal. Consider that the above 3 definitions are quite
> > > sparse, and essentially do nothing other than reference each other, and
> > > they're also leaving out a lot of detail that will be explored more
> > > substantively later in the document (or in the framework / architecture
> > > informational document described in [0]).
> > >
> > > [0]: https://datatracker.ietf.org/wg/bpf/about/
> > >
> > > It seems like it might make more sense to follow the approach taken by
> > > the JVM specification [1], SysV ABI [2], and RISC-V psABI [3] (though
> > > they do have a section that defines appreviations and a couple of
> > > terms), and instead just have each chapter explain all of these concepts
> > > in more detail without any kind of introduction. What do you think?
> >
> > I could go either way. Personally, when I read documents, I like
> > having a vocabulary section to give me some bearing. That way, as I
> > read the document, I know where to turn to see whether words with
> > which I am unfamiliar are things that I "should know" (and therefore
> > just Google) or are new terminology from this document. Again, I could
> >
> > absolutely go either way and certainly appreciate your references to
> > other documents that work differently. When I wrote this section I
> > envisioned it like the vocabulary section from the C++ standard where
> > new terms of art are given basic definitions that are later expanded
> > throughout the document.
> >
> > What if we did both -- we could keep the vocabulary section and
> > include pointers to the places later in the specification where the
> > terms are explained in additional detail?
>
> If we did this, then the vocabulary section would become a combination
> of a table of contents, and an index of sorts. I personally find that in
> documents such as the C and C++ standard, that the terms section ends up
> being arbitrarily chosen, and insufficiently defined (see all the Notes
> sections peppered throughout these terms).
>
> I'd again appreciate hearing other folks' thoughts here. I'm inclined to
> say that the document would be better served by having a clear table of
> contents where these terms are specified and defined in one place, but I
> don't have a super strong opinion.
>
At the end of this email I will suggest a list of ABI-related topics
for the upcoming IETF meeting -- I believe that this discussion would
be worthwhile!
> > > [1]: https://docs.oracle.com/javase/specs/jvms/se21/html/index.html
> > > [2]: https://refspecs.linuxfoundation.org/elf/x86_64-abi-0.95.pdf
> > > [3]: https://github.com/riscv-non-isa/riscv-elf-psabi-doc/releases/download/draft-20230929-e5c800e661a53efe3c2678d71a306323b60eb13b/riscv-abi.pdf
> > >
> > > > +#. eBPF Machine Instantiation:
> > > > +#. ABI-conforming system: A computer system that provides the binary sys- tem interface for application
> > > > + programs described in the System V ABI [SYSVABI]_.
> > > > +#. ABI-conforming program: A program written to include only the system routines, commands, and other
> > > > + resources included in the ABI, and a program compiled into an executable file that has the formats
> > > > + and characteristics specified for such files in the ABI, and a program whose behavior complies with
> > > > + the rules given in the ABI [SYSVABI]_.
> > > > +#. ABI-nonconforming program: A program which has been written to include system routines, commands, or
> > > > + other resources not included in the ABI, or a program which has been compiled into a format different
> > > > + from those specified in the ABI, or a program which does not behave as specified in the ABI [SYSVABI]_.
> > > > +#. Undefined Behavior: Behavior that may vary from instance to instance or may change at some time in the future.
> > > > + Some undesirable programming practices are marked in the ABI as yielding undefined behavior [SYSVABI]_.
> > > > +#. Unspecified Property: A property of an entity that is not explicitly included or referenced in this specification,
> > > > + and may change at some time in the future. In general, it is not good practice to make a program depend
> > > > + on an unspecified property [SYSVABI]_.
> > > > +
> > > > +Program Execution Environment
> > > > +=============================
> > > > +
> > > > +A loaded eBPF program is executed on an eBPF machine. That machine, physical or virtual, runs in a freestanding
> > > > +or hosted environment [#]_.
> > > > +
> > > > +eBPF Machine Freestanding Environment
> > > > +-------------------------------------
> > > > +
> > > > +
> > > > +eBPF Machine Hosted Environment
> > > > +-------------------------------
> > > > +
> > > > +A loaded eBPF program can be attached to a BPF hook point in a BPF-enabled application
> > > > +compatible with the attach type of its program type. When the BPF-enabled application's
> > > > +execution reaches a BPF hook point to which an eBPF program is attached, that program
> > > > +begins execution on the eBPF machine at its first instruction. The contents of eBPF machine's
> > > > +registers and memory at the time it starts execution are defined by the eBPF program's
> > > > +type and attach point.
> > > > +
> > > > +Processor Architecture
> > > > +======================
> > > > +
> > > > +This section describes the processor architecture available
> > > > +to programs. It also defines the reference language data types, giving the
> > > > +foundation for system interface specifications [SYSVABI]_
> > >
> > > Why are we linking to the SYSVABI doc here?
> >
> > A great question -- in most places where I have referenced that
> > document it is akin to an academic reference -- I am attempting to
> > give the user the idea that the language used is not my own completely
> > original thought. I am attempting to tell the reader that this concept
> > or language has precedent in another document. I am very new to the
> > standards-writing process and realize that utilization of citations
> > may not be "how it works". Please let me know how to proceed!
>
> I'm not sure how it works either, so folks who have more IETF experience
> -- please weigh in. In similar fashion to above, this feels like we're
> implicitly taking these other documents as dependencies. We certainly
> don't want to plagiarize anything, but tagging a reference here to
> function similar to a citation seems confusing as well.
Adding to IETF the topic list (see below).
>
> > >
> > > > +
> > > > +Registers
> > > > +---------
> > > > +
> > > > +General Purpose Registers
> > > > +^^^^^^^^^^^^^^^^^^^^^^^^^
> > > > +eBPF has 11 64-bit wide registers, `r0` - `r10`. The contents of the registers
> > > > +at the beginning of an eBPF program's execution depend on the program's type.
> > >
> > > We should probably also mention the 32 bit subregisters (they can only
> > > be accessed through special ALU operations), and that they zero-extend
> > > into 64 bit on writes.
> >
> > I added a note on the subregisters. I decided to leave out the
> > information about how they zero extend on writes. I thought that was
> > something that should remain entirely within the scope of the ISA.
> > Please let me know if I am wrong!
>
> Sounds good
>
> [...]
>
> > > > +C Programming Language Support
> > > > +==============================
> > > > +
> > > > +**NOTE** This section could be included in order to define the contents
> > > > +of standardized processor-specific header files that would make it easier
> > > > +for programmers to write programs.
> > > > +
> > > > +Notes
> > > > +=====
> > > > +.. [#] The eBPF machine does not need to be a physical instantiation of a processor. In fact, many instantiations of eBPF machines are virtual.
> > > > +.. [#] See the [CSTD]_ for the inspiration for this distinction.
> > > > +
> > > > +References
> > > > +==========
> > > > +
> > > > +.. [SYSVABI] System V Application Binary Interface - Edition 4.1. SCO Developer Specs. The Santa Cruz Operation. 1997. https://www.sco.com/developers/devspecs/gabi41.pdf
> > > > +.. [POWERPCABI] Developing PowerPC Embedded Application Binary Interface (EABI) Compliant Programs. PowerPC Embedded Processors Application Note. IBM. 1998. http://class.ece.iastate.edu/arun/Cpre381_Sp06/lab/labw12a/eabi_app.pdf
> > > > +.. [GOABI] Go internal ABI specification. Go Source Code. No authors. 2023. https://go.googlesource.com/go/+/refs/heads/master/src/cmd/compile/abi-internal.md
> > > > +.. [JAVAABI] The Java (r) Language Specification - Java SE 7 Edition. Gosling, James et. al. Oracle. 2013. https://docs.oracle.com/javase/specs/jls/se7/html/index.html
> > >
> > > If we do share a link, it should probably be to the Java Virtual Machine
> > > specification rather than the language specification. I believe the most
> > > recent edition is 21.
> >
> > I checked and the binary compatibility piece of the specification is
> > actually in the language spec. That said, it might make sense to just
> > link to both? I am willing to do whatever you suggest!
>
> Ah, fair enough. Let's still link the latest version though rather than
> version 7.
This change is made in v3 of the patch -- thank you!
>
> > > > +.. [DALVIKABI] Dalvik Bytecode. Android Core Runtime Documentation. No authors. Google. 2022. https://source.android.com/docs/core/runtime/dalvik-bytecode
> > > > +.. [CLRABI] CLR ABI. The Book of the Runtime. No authors. Microsoft. 2023. https://github.com/dotnet/coreclr/blob/master/Documentation/botr/clr-abi.md.
> > > > +.. [CSTD] International Standard: Programming Languages - C. ISO/IEC. 2018. https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2310.pdf.
> > > > +.. [RHELABI] Red Hat Enterprise Linux 8: Application Compatibility Guide. Red Hat. 2023. https://access.redhat.com/articles/rhel8-abi-compatibility
> > > > +
> > >
> > > Everything else looks fine for now. Something I think we should figure
> > > out though is what we want to put each of the following docs from the
> > > charter:
> >
> > I reflowed the entire document to make sure that the text is at most 80 columns.
> >
> >
> >
> > >
> > > - [I] one or more documents that recommend conventions and guidelines
> > > for producing portable BPF program binaries,
> > >
> > > - [I] an architecture and framework document.
> > >
> > > It seems like some of what's going into this document (e.g. formally
> > > defining a "Program", data types, etc) could arguably belong in an
> > > architecture and framework document. Honestly, I think it would probably
> > > be easier and make more sense to just have a single monolithic BPF
> > > Machine informational document, though I'm not sure if that's viable at
> > > this point given that we specified different documents in the charter.
> >
> > You make (as usual) an excellent point. I think that this question is
> > something that would be good to discuss as a group? Because you are
> > the chair, David, I will defer to you!
>
> Discussing as a group is a great idea. Maybe this would be something to
> discuss at IETF 118?
I believe that we can have a great discussion at 118 on the following
ABI-related topics:
1. Can references in IETF standards documents be used like citations
in an academic article?
When I drafted the original version of the text, I added references to
other (ABI or general) documents because they were the source for
certain language or ideas. That is what an author would do in the
world of academic publishing to make sure that they did not give the
reader the impression that certain words or ideas were their original
writing or thought. I am not sure how IETF handles this situation but
I want to make sure that I am doing the right thing -- I don't want
anyone to get the idea that I am smarter than I am!
2. Related to 1: If we do need/want to make references to external,
non-IETF documents, what is the process for that?
3. Does the vocabulary section
- Stay roughly as it is now?
Basically a set of topic-specific words with introductory/brief definitions.
- Get replaced with a simple TOC?
That way the terms can be defined completely and fully in a single place.
- Turn into a combination of the prior two options?
The vocabulary definitions would be brief summaries of the more
complete definition and the text would include a reference to the
section of the document where the term is completely defined.
I unfortunately will not be able to be 118 in person but I do plan on
being present virtually! I am looking forward to talking to everyone!
Please have a great weekend!
Will
>
> Thanks,
> David
^ permalink raw reply [flat|nested] 42+ messages in thread
* [PATCH v3] bpf, docs: Add additional ABI working draft base text
2023-11-03 21:14 ` Will Hawkins
2023-11-03 21:14 ` Will Hawkins
@ 2023-11-03 21:20 ` Will Hawkins
2023-11-03 21:20 ` [Bpf] " Will Hawkins
2023-11-05 9:51 ` Alexei Starovoitov
1 sibling, 2 replies; 42+ messages in thread
From: Will Hawkins @ 2023-11-03 21:20 UTC (permalink / raw)
To: bpf, bpf; +Cc: Will Hawkins
Per David's description of the IETF standardization process, this
document will form the basis for an informational eBPF ABI. The
work in this commit is a slightly more complete skeleton for the work
that we will do. Everything in this document (from formatting to topics
to details) is open for change and feedback.
---
Documentation/bpf/standardization/abi.rst | 259 +++++++++++++++++++++-
1 file changed, 250 insertions(+), 9 deletions(-)
Changelog:
v1 -> v2:
- Address David's comments
- Reflow to a max of 80 character lines (Christoph's feedback)
v2 -> v3:
- Update Java Language Specification reference to version 21
- Make author's notes into comments.
- Fix minor typographical errors in References section.
diff --git a/Documentation/bpf/standardization/abi.rst b/Documentation/bpf/standardization/abi.rst
index 0c2e10eeb89a..8bb7383688bc 100644
--- a/Documentation/bpf/standardization/abi.rst
+++ b/Documentation/bpf/standardization/abi.rst
@@ -1,18 +1,159 @@
-.. contents::
-.. sectnum::
-
===================================================
BPF ABI Recommended Conventions and Guidelines v1.0
===================================================
-This is version 1.0 of an informational document containing recommended
-conventions and guidelines for producing portable BPF program binaries.
+An application binary interface (ABI) defines the requirements that one or more
+binary software objects must meet in order to guarantee that they can
+interoperate and/or use the resources provided by operating systems/hardware
+combinations. (For alternate definitions of ABI, see [SYSVABI]_, [POWERPCABI]_)
+
+The purpose of this document is to define an ABI which will define the extent
+to which compiled BPF programs are compatible with each other and the BPF
+machine/processor [#]_ on which they are executing.
+
+The ABI is specified in two parts: a generic part and a processor-specific part.
+A pairing of generic ABI with the processor-specific ABI for a certain
+instantiation of a BPF machine represents a complete binary interface for BPF
+programs executing on that machine.
+
+This document is the generic ABI and specifies the parameters and behavior
+common to all instantiations of BPF machines. In addition, it defines the
+details that must be specified by each processor-specific ABI.
+
+These psABIs are the second part of the ABI. Each instantiation of a BPF
+machine must describe the mechanism through which binary interface
+compatibility is maintained with respect to the issues highlighted by this
+document. However, the details that must be defined by a psABI are a minimum --
+a psABI may specify additional requirements for binary interface compatibility
+on a platform.
+
+.. contents::
+.. sectnum::
+
+How To Use This ABI
+===================
+
+Conformance
+===========
+..
+ Red Hat specifies different levels of conformance over time [RHELABI]_. We
+ could use information from that document here, if we want.
+
+Related Work
+============
+BPF programs are not unique for the way that they operate on a virtualized
+machine and processor. There are many programming languages that compile to an
+ISA that is specific to a virtual machine. Like the specification presented
+herein, those languages and virtual machines also have ABIs.
+
+For example, the Go programming language and the runtime included statically
+with each program compiled from Go source code have a defined ABI [GOABI]_.
+Java programs compiled to bytecode follow a well-defined ABI for
+interoperability with other compiled Java programs and libraries [JAVAABI]_.
+Programs compiled to bytecode for execution as user applications on the Android
+operating system (OS) adhere to a bytecode specification that shares much in
+common with an ABI [DALVIKABI]_. Finally, the Common Language Runtime (CLR)
+designed to execute programs compiled to the Microsoft Intermediate Language
+(MSIL) has a fully specified ABI [CLRABI]_.
+
+Vocabulary
+==========
+
+#. Program: A BPF Program is an ordered set of BPF instructions, with exactly
+ one entry instruction where the program begins, and one or more exit
+ instructions where program execution can end.
+#. Program Type: Every BPF program has an associated type. The program type
+ defines, among other things, a program's possible attach types.
+#. Attach Type: An attach type defines the set of BPF hook points to which a BPF
+ program can attach.
+#. BPF Hook Points: Places in a BPF-enabled component (e.g., the Linux Kernel,
+ the Windows kernel) where a BPF program may be attached.
+#. ABI-conforming BPF Machine Instantiation: A physical or logical realization
+ of a computer system capable of executing BPF programs consistently with the
+ specifications outlined in this document.
+#. ABI-conforming BPF program: A BPF program written to include only the system
+ routines, commands, and other resources included in this ABI; or a BPF
+ program compiled into an executable file that has the formats and
+ characteristics specified for such files in this ABI; or a BPF program whose
+ behavior complies with the rules given in the ABI [SYSVABI]_.
+#. ABI-nonconforming program: A BPF program that is not ABI conforming.
+#. Undefined Behavior: Behavior that may vary from instance to instance or may
+ change at some time in the future. Some undesirable programming practices
+ are marked in this ABI as yielding undefined behavior [SYSVABI]_.
+#. Unspecified Property: A property of an entity defined in this document that
+ is not explicitly included, defined or referenced in this specification, and
+ may change at some time in the future. In general, it is not good practice
+ to make a program depend on an unspecified property [SYSVABI]_.
+
+Program Execution Environment
+=============================
+
+A loaded BPF program is executed in a freestanding or hosted environment. [#]_.
+
+BPF Program Freestanding Execution Environment
+----------------------------------------------
+
+BPF Program Hosted Execution Environment
+----------------------------------------
+
+A hosted execution environment is one in which a BPF machine instantiation is
+embedded within another computer system known as a BPF-enabled application
+(e.g., a user application or an operating system kernel). A loaded BPF program
+can be attached to a BPF hook point in such a BPF-enabled application
+compatible with the attach type of its program type. When the BPF-enabled
+application's execution reaches a BPF hook point to which a BPF program is
+attached, that BPF program begins execution on the embedded BPF machine at the
+program's first instruction. The contents of the embedded BPF machine's
+registers and memory at the time it starts execution of the BPF program are
+defined by the BPF program's type and attach point.
+
+Processor Architecture
+======================
+
+This section describes the processor architecture available
+to programs. It also defines the reference language data types, giving the
+foundation for system interface specifications [SYSVABI]_
+
+Registers
+---------
+
+General Purpose Registers
+^^^^^^^^^^^^^^^^^^^^^^^^^
+BPF has 11 64-bit wide registers, `r0` - `r10`. There exists a single
+32-bit wide subregister for each one of the 11 64-bit wide registers. Those
+registers do not have their own names -- they are accessible indirectly
+through the 32-bit ALU instructions.
+
+The contents of the registers at the beginning of a BPF program's
+execution depend on the program's type.
+
+Frame Pointer Register
+^^^^^^^^^^^^^^^^^^^^^^
+The use of a frame pointer by programs is not required. If, however, a BPF
+program does use a frame pointer, it must be stored in register `r10` and
+must be read only.
+
+Data Types
+----------
-Registers and calling convention
-================================
+Numeric Types
+^^^^^^^^^^^^^
-BPF has 10 general purpose registers and a read-only frame pointer register,
-all of which are 64-bits wide.
+The BPF machine supports 32- and 64-bit signed and unsigned integers. It does
+not support floating-point data types. All signed integers are represented in
+twos-complement format where the sign bit is stored in the most-significant bit.
+
+Pointers
+^^^^^^^^
+
+Function Calling Sequence
+=========================
+This section defines the standard function calling sequence in a way that
+accommodates exceptions, stack management, register (non)volatility, and access
+to capabilities of the hosting environment (where applicable).
+
+Functions in BPF may define between 0 and 5 parameters. Each of the arguments in
+a function call are passed in registers.
The BPF calling convention is defined as:
@@ -23,3 +164,103 @@ The BPF calling convention is defined as:
R0 - R5 are scratch registers and BPF programs needs to spill/fill them if
necessary across calls.
+
+Every function invocation proceeds as if it has exclusive access to an
+implementation-defined amount of stack space. R10 is a pointer to the byte of
+memory with the highest address in that stack space. The contents
+of a function invocation's stack space do not persist between invocations.
+
+..
+ Discuss manufactured prologue and epilogue. Take language from the design FAQ.
+
+Execution Environment Interface
+===============================
+
+When a BPF program executes in a hosted environment, the hosted environment
+may make available to BPF programs certain capabilities. This section
+describes those capabilities and the mechanism for accessing them.
+
+
+Program Execution
+=================
+
+Program Return Values
+---------------------
+
+..
+ libbpf currently defines the return value of a bpf program as a 32-bit unsigned
+ integer. ubpf currently defines the return value of a bpf program.
+
+Program Loading and Dynamic Linking
+-----------------------------------
+This section describes the object file information and system actions that
+create running programs. Some information here applies to all systems;
+information specific to one processor resides in sections marked accordingly
+[SYSVABI]_.
+
+BPF programs saved in ELF files must be loaded from storage and properly
+configured before they can be executed on a BPF machine.
+
+Program Loading (Processor-Specific)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Dynamic Linking
+^^^^^^^^^^^^^^^
+
+Global Offset Table (Processor-Specific)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Procedure Linkage Table (Processor-Specific)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Exception Handling
+==================
+
+BPF Program Types
+==================
+.. This information may end up as a subsection somewhere else.
+
+BPF Maps
+=========
+.. This information may end up as a subsection somewhere else.
+
+System Calls
+============
+
+**TODO**
+
+C Programming Language Support
+==============================
+
+..
+ This section could be included in order to define the contents of standardized
+ processor-specific header files that would make it easier for programmers to
+ write programs.
+
+Notes
+=====
+.. [#] The BPF machine does not need to be a physical instantiation of a processor.
+ In fact, many instantiations of BPF machines are virtual.
+.. [#] See the [CSTD]_ for the inspiration for this distinction.
+
+References
+==========
+
+.. [SYSVABI] System V Application Binary Interface - Edition 4.1. SCO Developer Specs.
+ The Santa Cruz Operation. 1997.
+ https://www.sco.com/developers/devspecs/gabi41.pdf.
+.. [POWERPCABI] Developing PowerPC Embedded Application Binary Interface (EABI)
+ Compliant Programs. PowerPC Embedded Processors Application Note. IBM. 1998.
+ http://class.ece.iastate.edu/arun/Cpre381_Sp06/lab/labw12a/eabi_app.pdf.
+.. [GOABI] Go internal ABI specification. Go Source Code. No authors. 2023.
+ https://go.googlesource.com/go/+/refs/heads/master/src/cmd/compile/abi-internal.md.
+.. [JAVAABI] The Java (r) Language Specification - Java SE 21 Edition. Gosling, James et. al.
+ Oracle. 2023. https://docs.oracle.com/javase/specs/jls/se21/html/index.html.
+.. [DALVIKABI] Dalvik Bytecode. Android Core Runtime Documentation. No authors. Google.
+ 2022. https://source.android.com/docs/core/runtime/dalvik-bytecode.
+.. [CLRABI] CLR ABI. The Book of the Runtime. No authors. Microsoft. 2023.
+ https://github.com/dotnet/coreclr/blob/master/Documentation/botr/clr-abi.md.
+.. [CSTD] International Standard: Programming Languages - C. ISO/IEC. 2018.
+ https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2310.pdf.
+.. [RHELABI] Red Hat Enterprise Linux 8: Application Compatibility Guide. Red Hat.
+ 2023. https://access.redhat.com/articles/rhel8-abi-compatibility.
--
2.41.0
^ permalink raw reply related [flat|nested] 42+ messages in thread* [Bpf] [PATCH v3] bpf, docs: Add additional ABI working draft base text
2023-11-03 21:20 ` [PATCH v3] " Will Hawkins
@ 2023-11-03 21:20 ` Will Hawkins
2023-11-05 9:51 ` Alexei Starovoitov
1 sibling, 0 replies; 42+ messages in thread
From: Will Hawkins @ 2023-11-03 21:20 UTC (permalink / raw)
To: bpf, bpf; +Cc: Will Hawkins
Per David's description of the IETF standardization process, this
document will form the basis for an informational eBPF ABI. The
work in this commit is a slightly more complete skeleton for the work
that we will do. Everything in this document (from formatting to topics
to details) is open for change and feedback.
---
Documentation/bpf/standardization/abi.rst | 259 +++++++++++++++++++++-
1 file changed, 250 insertions(+), 9 deletions(-)
Changelog:
v1 -> v2:
- Address David's comments
- Reflow to a max of 80 character lines (Christoph's feedback)
v2 -> v3:
- Update Java Language Specification reference to version 21
- Make author's notes into comments.
- Fix minor typographical errors in References section.
diff --git a/Documentation/bpf/standardization/abi.rst b/Documentation/bpf/standardization/abi.rst
index 0c2e10eeb89a..8bb7383688bc 100644
--- a/Documentation/bpf/standardization/abi.rst
+++ b/Documentation/bpf/standardization/abi.rst
@@ -1,18 +1,159 @@
-.. contents::
-.. sectnum::
-
===================================================
BPF ABI Recommended Conventions and Guidelines v1.0
===================================================
-This is version 1.0 of an informational document containing recommended
-conventions and guidelines for producing portable BPF program binaries.
+An application binary interface (ABI) defines the requirements that one or more
+binary software objects must meet in order to guarantee that they can
+interoperate and/or use the resources provided by operating systems/hardware
+combinations. (For alternate definitions of ABI, see [SYSVABI]_, [POWERPCABI]_)
+
+The purpose of this document is to define an ABI which will define the extent
+to which compiled BPF programs are compatible with each other and the BPF
+machine/processor [#]_ on which they are executing.
+
+The ABI is specified in two parts: a generic part and a processor-specific part.
+A pairing of generic ABI with the processor-specific ABI for a certain
+instantiation of a BPF machine represents a complete binary interface for BPF
+programs executing on that machine.
+
+This document is the generic ABI and specifies the parameters and behavior
+common to all instantiations of BPF machines. In addition, it defines the
+details that must be specified by each processor-specific ABI.
+
+These psABIs are the second part of the ABI. Each instantiation of a BPF
+machine must describe the mechanism through which binary interface
+compatibility is maintained with respect to the issues highlighted by this
+document. However, the details that must be defined by a psABI are a minimum --
+a psABI may specify additional requirements for binary interface compatibility
+on a platform.
+
+.. contents::
+.. sectnum::
+
+How To Use This ABI
+===================
+
+Conformance
+===========
+..
+ Red Hat specifies different levels of conformance over time [RHELABI]_. We
+ could use information from that document here, if we want.
+
+Related Work
+============
+BPF programs are not unique for the way that they operate on a virtualized
+machine and processor. There are many programming languages that compile to an
+ISA that is specific to a virtual machine. Like the specification presented
+herein, those languages and virtual machines also have ABIs.
+
+For example, the Go programming language and the runtime included statically
+with each program compiled from Go source code have a defined ABI [GOABI]_.
+Java programs compiled to bytecode follow a well-defined ABI for
+interoperability with other compiled Java programs and libraries [JAVAABI]_.
+Programs compiled to bytecode for execution as user applications on the Android
+operating system (OS) adhere to a bytecode specification that shares much in
+common with an ABI [DALVIKABI]_. Finally, the Common Language Runtime (CLR)
+designed to execute programs compiled to the Microsoft Intermediate Language
+(MSIL) has a fully specified ABI [CLRABI]_.
+
+Vocabulary
+==========
+
+#. Program: A BPF Program is an ordered set of BPF instructions, with exactly
+ one entry instruction where the program begins, and one or more exit
+ instructions where program execution can end.
+#. Program Type: Every BPF program has an associated type. The program type
+ defines, among other things, a program's possible attach types.
+#. Attach Type: An attach type defines the set of BPF hook points to which a BPF
+ program can attach.
+#. BPF Hook Points: Places in a BPF-enabled component (e.g., the Linux Kernel,
+ the Windows kernel) where a BPF program may be attached.
+#. ABI-conforming BPF Machine Instantiation: A physical or logical realization
+ of a computer system capable of executing BPF programs consistently with the
+ specifications outlined in this document.
+#. ABI-conforming BPF program: A BPF program written to include only the system
+ routines, commands, and other resources included in this ABI; or a BPF
+ program compiled into an executable file that has the formats and
+ characteristics specified for such files in this ABI; or a BPF program whose
+ behavior complies with the rules given in the ABI [SYSVABI]_.
+#. ABI-nonconforming program: A BPF program that is not ABI conforming.
+#. Undefined Behavior: Behavior that may vary from instance to instance or may
+ change at some time in the future. Some undesirable programming practices
+ are marked in this ABI as yielding undefined behavior [SYSVABI]_.
+#. Unspecified Property: A property of an entity defined in this document that
+ is not explicitly included, defined or referenced in this specification, and
+ may change at some time in the future. In general, it is not good practice
+ to make a program depend on an unspecified property [SYSVABI]_.
+
+Program Execution Environment
+=============================
+
+A loaded BPF program is executed in a freestanding or hosted environment. [#]_.
+
+BPF Program Freestanding Execution Environment
+----------------------------------------------
+
+BPF Program Hosted Execution Environment
+----------------------------------------
+
+A hosted execution environment is one in which a BPF machine instantiation is
+embedded within another computer system known as a BPF-enabled application
+(e.g., a user application or an operating system kernel). A loaded BPF program
+can be attached to a BPF hook point in such a BPF-enabled application
+compatible with the attach type of its program type. When the BPF-enabled
+application's execution reaches a BPF hook point to which a BPF program is
+attached, that BPF program begins execution on the embedded BPF machine at the
+program's first instruction. The contents of the embedded BPF machine's
+registers and memory at the time it starts execution of the BPF program are
+defined by the BPF program's type and attach point.
+
+Processor Architecture
+======================
+
+This section describes the processor architecture available
+to programs. It also defines the reference language data types, giving the
+foundation for system interface specifications [SYSVABI]_
+
+Registers
+---------
+
+General Purpose Registers
+^^^^^^^^^^^^^^^^^^^^^^^^^
+BPF has 11 64-bit wide registers, `r0` - `r10`. There exists a single
+32-bit wide subregister for each one of the 11 64-bit wide registers. Those
+registers do not have their own names -- they are accessible indirectly
+through the 32-bit ALU instructions.
+
+The contents of the registers at the beginning of a BPF program's
+execution depend on the program's type.
+
+Frame Pointer Register
+^^^^^^^^^^^^^^^^^^^^^^
+The use of a frame pointer by programs is not required. If, however, a BPF
+program does use a frame pointer, it must be stored in register `r10` and
+must be read only.
+
+Data Types
+----------
-Registers and calling convention
-================================
+Numeric Types
+^^^^^^^^^^^^^
-BPF has 10 general purpose registers and a read-only frame pointer register,
-all of which are 64-bits wide.
+The BPF machine supports 32- and 64-bit signed and unsigned integers. It does
+not support floating-point data types. All signed integers are represented in
+twos-complement format where the sign bit is stored in the most-significant bit.
+
+Pointers
+^^^^^^^^
+
+Function Calling Sequence
+=========================
+This section defines the standard function calling sequence in a way that
+accommodates exceptions, stack management, register (non)volatility, and access
+to capabilities of the hosting environment (where applicable).
+
+Functions in BPF may define between 0 and 5 parameters. Each of the arguments in
+a function call are passed in registers.
The BPF calling convention is defined as:
@@ -23,3 +164,103 @@ The BPF calling convention is defined as:
R0 - R5 are scratch registers and BPF programs needs to spill/fill them if
necessary across calls.
+
+Every function invocation proceeds as if it has exclusive access to an
+implementation-defined amount of stack space. R10 is a pointer to the byte of
+memory with the highest address in that stack space. The contents
+of a function invocation's stack space do not persist between invocations.
+
+..
+ Discuss manufactured prologue and epilogue. Take language from the design FAQ.
+
+Execution Environment Interface
+===============================
+
+When a BPF program executes in a hosted environment, the hosted environment
+may make available to BPF programs certain capabilities. This section
+describes those capabilities and the mechanism for accessing them.
+
+
+Program Execution
+=================
+
+Program Return Values
+---------------------
+
+..
+ libbpf currently defines the return value of a bpf program as a 32-bit unsigned
+ integer. ubpf currently defines the return value of a bpf program.
+
+Program Loading and Dynamic Linking
+-----------------------------------
+This section describes the object file information and system actions that
+create running programs. Some information here applies to all systems;
+information specific to one processor resides in sections marked accordingly
+[SYSVABI]_.
+
+BPF programs saved in ELF files must be loaded from storage and properly
+configured before they can be executed on a BPF machine.
+
+Program Loading (Processor-Specific)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Dynamic Linking
+^^^^^^^^^^^^^^^
+
+Global Offset Table (Processor-Specific)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Procedure Linkage Table (Processor-Specific)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Exception Handling
+==================
+
+BPF Program Types
+==================
+.. This information may end up as a subsection somewhere else.
+
+BPF Maps
+=========
+.. This information may end up as a subsection somewhere else.
+
+System Calls
+============
+
+**TODO**
+
+C Programming Language Support
+==============================
+
+..
+ This section could be included in order to define the contents of standardized
+ processor-specific header files that would make it easier for programmers to
+ write programs.
+
+Notes
+=====
+.. [#] The BPF machine does not need to be a physical instantiation of a processor.
+ In fact, many instantiations of BPF machines are virtual.
+.. [#] See the [CSTD]_ for the inspiration for this distinction.
+
+References
+==========
+
+.. [SYSVABI] System V Application Binary Interface - Edition 4.1. SCO Developer Specs.
+ The Santa Cruz Operation. 1997.
+ https://www.sco.com/developers/devspecs/gabi41.pdf.
+.. [POWERPCABI] Developing PowerPC Embedded Application Binary Interface (EABI)
+ Compliant Programs. PowerPC Embedded Processors Application Note. IBM. 1998.
+ http://class.ece.iastate.edu/arun/Cpre381_Sp06/lab/labw12a/eabi_app.pdf.
+.. [GOABI] Go internal ABI specification. Go Source Code. No authors. 2023.
+ https://go.googlesource.com/go/+/refs/heads/master/src/cmd/compile/abi-internal.md.
+.. [JAVAABI] The Java (r) Language Specification - Java SE 21 Edition. Gosling, James et. al.
+ Oracle. 2023. https://docs.oracle.com/javase/specs/jls/se21/html/index.html.
+.. [DALVIKABI] Dalvik Bytecode. Android Core Runtime Documentation. No authors. Google.
+ 2022. https://source.android.com/docs/core/runtime/dalvik-bytecode.
+.. [CLRABI] CLR ABI. The Book of the Runtime. No authors. Microsoft. 2023.
+ https://github.com/dotnet/coreclr/blob/master/Documentation/botr/clr-abi.md.
+.. [CSTD] International Standard: Programming Languages - C. ISO/IEC. 2018.
+ https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2310.pdf.
+.. [RHELABI] Red Hat Enterprise Linux 8: Application Compatibility Guide. Red Hat.
+ 2023. https://access.redhat.com/articles/rhel8-abi-compatibility.
--
2.41.0
--
Bpf mailing list
Bpf@ietf.org
https://www.ietf.org/mailman/listinfo/bpf
^ permalink raw reply related [flat|nested] 42+ messages in thread* Re: [Bpf] [PATCH v3] bpf, docs: Add additional ABI working draft base text
2023-11-03 21:20 ` [PATCH v3] " Will Hawkins
2023-11-03 21:20 ` [Bpf] " Will Hawkins
@ 2023-11-05 9:51 ` Alexei Starovoitov
2023-11-05 9:51 ` Alexei Starovoitov
2023-11-06 0:17 ` Will Hawkins
1 sibling, 2 replies; 42+ messages in thread
From: Alexei Starovoitov @ 2023-11-05 9:51 UTC (permalink / raw)
To: Will Hawkins; +Cc: bpf, bpf
On Fri, Nov 3, 2023 at 2:20 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> +
> +The ABI is specified in two parts: a generic part and a processor-specific part.
> +A pairing of generic ABI with the processor-specific ABI for a certain
> +instantiation of a BPF machine represents a complete binary interface for BPF
> +programs executing on that machine.
> +
> +This document is the generic ABI and specifies the parameters and behavior
> +common to all instantiations of BPF machines. In addition, it defines the
> +details that must be specified by each processor-specific ABI.
> +
> +These psABIs are the second part of the ABI. Each instantiation of a BPF
> +machine must describe the mechanism through which binary interface
> +compatibility is maintained with respect to the issues highlighted by this
> +document. However, the details that must be defined by a psABI are a minimum --
> +a psABI may specify additional requirements for binary interface compatibility
> +on a platform.
I don't understand what you are trying to say in the above.
In my mind there is only one BPF psABI and it doesn't have
generic and processor parts. There is only one "processor".
BPF is such a processor.
^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [Bpf] [PATCH v3] bpf, docs: Add additional ABI working draft base text
2023-11-05 9:51 ` Alexei Starovoitov
@ 2023-11-05 9:51 ` Alexei Starovoitov
2023-11-06 0:17 ` Will Hawkins
1 sibling, 0 replies; 42+ messages in thread
From: Alexei Starovoitov @ 2023-11-05 9:51 UTC (permalink / raw)
To: Will Hawkins; +Cc: bpf, bpf
On Fri, Nov 3, 2023 at 2:20 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> +
> +The ABI is specified in two parts: a generic part and a processor-specific part.
> +A pairing of generic ABI with the processor-specific ABI for a certain
> +instantiation of a BPF machine represents a complete binary interface for BPF
> +programs executing on that machine.
> +
> +This document is the generic ABI and specifies the parameters and behavior
> +common to all instantiations of BPF machines. In addition, it defines the
> +details that must be specified by each processor-specific ABI.
> +
> +These psABIs are the second part of the ABI. Each instantiation of a BPF
> +machine must describe the mechanism through which binary interface
> +compatibility is maintained with respect to the issues highlighted by this
> +document. However, the details that must be defined by a psABI are a minimum --
> +a psABI may specify additional requirements for binary interface compatibility
> +on a platform.
I don't understand what you are trying to say in the above.
In my mind there is only one BPF psABI and it doesn't have
generic and processor parts. There is only one "processor".
BPF is such a processor.
--
Bpf mailing list
Bpf@ietf.org
https://www.ietf.org/mailman/listinfo/bpf
^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [Bpf] [PATCH v3] bpf, docs: Add additional ABI working draft base text
2023-11-05 9:51 ` Alexei Starovoitov
2023-11-05 9:51 ` Alexei Starovoitov
@ 2023-11-06 0:17 ` Will Hawkins
2023-11-06 0:17 ` Will Hawkins
2023-11-06 8:38 ` Alexei Starovoitov
1 sibling, 2 replies; 42+ messages in thread
From: Will Hawkins @ 2023-11-06 0:17 UTC (permalink / raw)
To: Alexei Starovoitov; +Cc: bpf, bpf
On Sun, Nov 5, 2023 at 4:51 AM Alexei Starovoitov
<alexei.starovoitov@gmail.com> wrote:
>
> On Fri, Nov 3, 2023 at 2:20 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > +
> > +The ABI is specified in two parts: a generic part and a processor-specific part.
> > +A pairing of generic ABI with the processor-specific ABI for a certain
> > +instantiation of a BPF machine represents a complete binary interface for BPF
> > +programs executing on that machine.
> > +
> > +This document is the generic ABI and specifies the parameters and behavior
> > +common to all instantiations of BPF machines. In addition, it defines the
> > +details that must be specified by each processor-specific ABI.
> > +
> > +These psABIs are the second part of the ABI. Each instantiation of a BPF
> > +machine must describe the mechanism through which binary interface
> > +compatibility is maintained with respect to the issues highlighted by this
> > +document. However, the details that must be defined by a psABI are a minimum --
> > +a psABI may specify additional requirements for binary interface compatibility
> > +on a platform.
>
> I don't understand what you are trying to say in the above.
> In my mind there is only one BPF psABI and it doesn't have
> generic and processor parts. There is only one "processor".
> BPF is such a processor.
What I was trying to say was that the document here describes a
generic ABI. In this document there will be areas that are specific to
different implementations and those would be considered processor
specific. In other words, the ubpf runtime could define those things
differently than the rbpf runtime which, in turn, could define those
things differently than the kernel's implementation.
^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [Bpf] [PATCH v3] bpf, docs: Add additional ABI working draft base text
2023-11-06 0:17 ` Will Hawkins
@ 2023-11-06 0:17 ` Will Hawkins
2023-11-06 8:38 ` Alexei Starovoitov
1 sibling, 0 replies; 42+ messages in thread
From: Will Hawkins @ 2023-11-06 0:17 UTC (permalink / raw)
To: Alexei Starovoitov; +Cc: bpf, bpf
On Sun, Nov 5, 2023 at 4:51 AM Alexei Starovoitov
<alexei.starovoitov@gmail.com> wrote:
>
> On Fri, Nov 3, 2023 at 2:20 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > +
> > +The ABI is specified in two parts: a generic part and a processor-specific part.
> > +A pairing of generic ABI with the processor-specific ABI for a certain
> > +instantiation of a BPF machine represents a complete binary interface for BPF
> > +programs executing on that machine.
> > +
> > +This document is the generic ABI and specifies the parameters and behavior
> > +common to all instantiations of BPF machines. In addition, it defines the
> > +details that must be specified by each processor-specific ABI.
> > +
> > +These psABIs are the second part of the ABI. Each instantiation of a BPF
> > +machine must describe the mechanism through which binary interface
> > +compatibility is maintained with respect to the issues highlighted by this
> > +document. However, the details that must be defined by a psABI are a minimum --
> > +a psABI may specify additional requirements for binary interface compatibility
> > +on a platform.
>
> I don't understand what you are trying to say in the above.
> In my mind there is only one BPF psABI and it doesn't have
> generic and processor parts. There is only one "processor".
> BPF is such a processor.
What I was trying to say was that the document here describes a
generic ABI. In this document there will be areas that are specific to
different implementations and those would be considered processor
specific. In other words, the ubpf runtime could define those things
differently than the rbpf runtime which, in turn, could define those
things differently than the kernel's implementation.
--
Bpf mailing list
Bpf@ietf.org
https://www.ietf.org/mailman/listinfo/bpf
^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [Bpf] [PATCH v3] bpf, docs: Add additional ABI working draft base text
2023-11-06 0:17 ` Will Hawkins
2023-11-06 0:17 ` Will Hawkins
@ 2023-11-06 8:38 ` Alexei Starovoitov
2023-11-06 8:38 ` Alexei Starovoitov
2023-11-07 19:56 ` Will Hawkins
1 sibling, 2 replies; 42+ messages in thread
From: Alexei Starovoitov @ 2023-11-06 8:38 UTC (permalink / raw)
To: Will Hawkins; +Cc: bpf, bpf
On Sun, Nov 5, 2023 at 4:17 PM Will Hawkins <hawkinsw@obs.cr> wrote:
>
> On Sun, Nov 5, 2023 at 4:51 AM Alexei Starovoitov
> <alexei.starovoitov@gmail.com> wrote:
> >
> > On Fri, Nov 3, 2023 at 2:20 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > +
> > > +The ABI is specified in two parts: a generic part and a processor-specific part.
> > > +A pairing of generic ABI with the processor-specific ABI for a certain
> > > +instantiation of a BPF machine represents a complete binary interface for BPF
> > > +programs executing on that machine.
> > > +
> > > +This document is the generic ABI and specifies the parameters and behavior
> > > +common to all instantiations of BPF machines. In addition, it defines the
> > > +details that must be specified by each processor-specific ABI.
> > > +
> > > +These psABIs are the second part of the ABI. Each instantiation of a BPF
> > > +machine must describe the mechanism through which binary interface
> > > +compatibility is maintained with respect to the issues highlighted by this
> > > +document. However, the details that must be defined by a psABI are a minimum --
> > > +a psABI may specify additional requirements for binary interface compatibility
> > > +on a platform.
> >
> > I don't understand what you are trying to say in the above.
> > In my mind there is only one BPF psABI and it doesn't have
> > generic and processor parts. There is only one "processor".
> > BPF is such a processor.
>
> What I was trying to say was that the document here describes a
> generic ABI. In this document there will be areas that are specific to
> different implementations and those would be considered processor
> specific. In other words, the ubpf runtime could define those things
> differently than the rbpf runtime which, in turn, could define those
> things differently than the kernel's implementation.
I see what you mean. There is only one BPF psABI. There cannot be two.
ubpf can decide not to follow it, but it could only mean that
it's non conformant and not compatible.
^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [Bpf] [PATCH v3] bpf, docs: Add additional ABI working draft base text
2023-11-06 8:38 ` Alexei Starovoitov
@ 2023-11-06 8:38 ` Alexei Starovoitov
2023-11-07 19:56 ` Will Hawkins
1 sibling, 0 replies; 42+ messages in thread
From: Alexei Starovoitov @ 2023-11-06 8:38 UTC (permalink / raw)
To: Will Hawkins; +Cc: bpf, bpf
On Sun, Nov 5, 2023 at 4:17 PM Will Hawkins <hawkinsw@obs.cr> wrote:
>
> On Sun, Nov 5, 2023 at 4:51 AM Alexei Starovoitov
> <alexei.starovoitov@gmail.com> wrote:
> >
> > On Fri, Nov 3, 2023 at 2:20 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > +
> > > +The ABI is specified in two parts: a generic part and a processor-specific part.
> > > +A pairing of generic ABI with the processor-specific ABI for a certain
> > > +instantiation of a BPF machine represents a complete binary interface for BPF
> > > +programs executing on that machine.
> > > +
> > > +This document is the generic ABI and specifies the parameters and behavior
> > > +common to all instantiations of BPF machines. In addition, it defines the
> > > +details that must be specified by each processor-specific ABI.
> > > +
> > > +These psABIs are the second part of the ABI. Each instantiation of a BPF
> > > +machine must describe the mechanism through which binary interface
> > > +compatibility is maintained with respect to the issues highlighted by this
> > > +document. However, the details that must be defined by a psABI are a minimum --
> > > +a psABI may specify additional requirements for binary interface compatibility
> > > +on a platform.
> >
> > I don't understand what you are trying to say in the above.
> > In my mind there is only one BPF psABI and it doesn't have
> > generic and processor parts. There is only one "processor".
> > BPF is such a processor.
>
> What I was trying to say was that the document here describes a
> generic ABI. In this document there will be areas that are specific to
> different implementations and those would be considered processor
> specific. In other words, the ubpf runtime could define those things
> differently than the rbpf runtime which, in turn, could define those
> things differently than the kernel's implementation.
I see what you mean. There is only one BPF psABI. There cannot be two.
ubpf can decide not to follow it, but it could only mean that
it's non conformant and not compatible.
--
Bpf mailing list
Bpf@ietf.org
https://www.ietf.org/mailman/listinfo/bpf
^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [Bpf] [PATCH v3] bpf, docs: Add additional ABI working draft base text
2023-11-06 8:38 ` Alexei Starovoitov
2023-11-06 8:38 ` Alexei Starovoitov
@ 2023-11-07 19:56 ` Will Hawkins
2023-11-07 19:56 ` Will Hawkins
2023-11-08 1:17 ` Alexei Starovoitov
1 sibling, 2 replies; 42+ messages in thread
From: Will Hawkins @ 2023-11-07 19:56 UTC (permalink / raw)
To: Alexei Starovoitov; +Cc: bpf, bpf
On Mon, Nov 6, 2023 at 3:38 AM Alexei Starovoitov
<alexei.starovoitov@gmail.com> wrote:
>
> On Sun, Nov 5, 2023 at 4:17 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> >
> > On Sun, Nov 5, 2023 at 4:51 AM Alexei Starovoitov
> > <alexei.starovoitov@gmail.com> wrote:
> > >
> > > On Fri, Nov 3, 2023 at 2:20 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > +
> > > > +The ABI is specified in two parts: a generic part and a processor-specific part.
> > > > +A pairing of generic ABI with the processor-specific ABI for a certain
> > > > +instantiation of a BPF machine represents a complete binary interface for BPF
> > > > +programs executing on that machine.
> > > > +
> > > > +This document is the generic ABI and specifies the parameters and behavior
> > > > +common to all instantiations of BPF machines. In addition, it defines the
> > > > +details that must be specified by each processor-specific ABI.
> > > > +
> > > > +These psABIs are the second part of the ABI. Each instantiation of a BPF
> > > > +machine must describe the mechanism through which binary interface
> > > > +compatibility is maintained with respect to the issues highlighted by this
> > > > +document. However, the details that must be defined by a psABI are a minimum --
> > > > +a psABI may specify additional requirements for binary interface compatibility
> > > > +on a platform.
> > >
> > > I don't understand what you are trying to say in the above.
> > > In my mind there is only one BPF psABI and it doesn't have
> > > generic and processor parts. There is only one "processor".
> > > BPF is such a processor.
> >
> > What I was trying to say was that the document here describes a
> > generic ABI. In this document there will be areas that are specific to
> > different implementations and those would be considered processor
> > specific. In other words, the ubpf runtime could define those things
> > differently than the rbpf runtime which, in turn, could define those
> > things differently than the kernel's implementation.
>
> I see what you mean. There is only one BPF psABI. There cannot be two.
> ubpf can decide not to follow it, but it could only mean that
> it's non conformant and not compatible.
Okay. That was not how I was structuring the ABI. I thought we had
decided that, as the document said, an instantiation of a machine had
to
1. meet the gABI
2. specify its requirements vis a vis the psABI
3. (optionally) describe other requirements.
If that is not what we decided then we will have to restructure the document.
Will
^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [Bpf] [PATCH v3] bpf, docs: Add additional ABI working draft base text
2023-11-07 19:56 ` Will Hawkins
@ 2023-11-07 19:56 ` Will Hawkins
2023-11-08 1:17 ` Alexei Starovoitov
1 sibling, 0 replies; 42+ messages in thread
From: Will Hawkins @ 2023-11-07 19:56 UTC (permalink / raw)
To: Alexei Starovoitov; +Cc: bpf, bpf
On Mon, Nov 6, 2023 at 3:38 AM Alexei Starovoitov
<alexei.starovoitov@gmail.com> wrote:
>
> On Sun, Nov 5, 2023 at 4:17 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> >
> > On Sun, Nov 5, 2023 at 4:51 AM Alexei Starovoitov
> > <alexei.starovoitov@gmail.com> wrote:
> > >
> > > On Fri, Nov 3, 2023 at 2:20 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > +
> > > > +The ABI is specified in two parts: a generic part and a processor-specific part.
> > > > +A pairing of generic ABI with the processor-specific ABI for a certain
> > > > +instantiation of a BPF machine represents a complete binary interface for BPF
> > > > +programs executing on that machine.
> > > > +
> > > > +This document is the generic ABI and specifies the parameters and behavior
> > > > +common to all instantiations of BPF machines. In addition, it defines the
> > > > +details that must be specified by each processor-specific ABI.
> > > > +
> > > > +These psABIs are the second part of the ABI. Each instantiation of a BPF
> > > > +machine must describe the mechanism through which binary interface
> > > > +compatibility is maintained with respect to the issues highlighted by this
> > > > +document. However, the details that must be defined by a psABI are a minimum --
> > > > +a psABI may specify additional requirements for binary interface compatibility
> > > > +on a platform.
> > >
> > > I don't understand what you are trying to say in the above.
> > > In my mind there is only one BPF psABI and it doesn't have
> > > generic and processor parts. There is only one "processor".
> > > BPF is such a processor.
> >
> > What I was trying to say was that the document here describes a
> > generic ABI. In this document there will be areas that are specific to
> > different implementations and those would be considered processor
> > specific. In other words, the ubpf runtime could define those things
> > differently than the rbpf runtime which, in turn, could define those
> > things differently than the kernel's implementation.
>
> I see what you mean. There is only one BPF psABI. There cannot be two.
> ubpf can decide not to follow it, but it could only mean that
> it's non conformant and not compatible.
Okay. That was not how I was structuring the ABI. I thought we had
decided that, as the document said, an instantiation of a machine had
to
1. meet the gABI
2. specify its requirements vis a vis the psABI
3. (optionally) describe other requirements.
If that is not what we decided then we will have to restructure the document.
Will
--
Bpf mailing list
Bpf@ietf.org
https://www.ietf.org/mailman/listinfo/bpf
^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [Bpf] [PATCH v3] bpf, docs: Add additional ABI working draft base text
2023-11-07 19:56 ` Will Hawkins
2023-11-07 19:56 ` Will Hawkins
@ 2023-11-08 1:17 ` Alexei Starovoitov
2023-11-08 1:17 ` Alexei Starovoitov
2023-11-08 10:13 ` Will Hawkins
1 sibling, 2 replies; 42+ messages in thread
From: Alexei Starovoitov @ 2023-11-08 1:17 UTC (permalink / raw)
To: Will Hawkins; +Cc: bpf, bpf
On Tue, Nov 7, 2023 at 11:56 AM Will Hawkins <hawkinsw@obs.cr> wrote:
>
> On Mon, Nov 6, 2023 at 3:38 AM Alexei Starovoitov
> <alexei.starovoitov@gmail.com> wrote:
> >
> > On Sun, Nov 5, 2023 at 4:17 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > >
> > > On Sun, Nov 5, 2023 at 4:51 AM Alexei Starovoitov
> > > <alexei.starovoitov@gmail.com> wrote:
> > > >
> > > > On Fri, Nov 3, 2023 at 2:20 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > > +
> > > > > +The ABI is specified in two parts: a generic part and a processor-specific part.
> > > > > +A pairing of generic ABI with the processor-specific ABI for a certain
> > > > > +instantiation of a BPF machine represents a complete binary interface for BPF
> > > > > +programs executing on that machine.
> > > > > +
> > > > > +This document is the generic ABI and specifies the parameters and behavior
> > > > > +common to all instantiations of BPF machines. In addition, it defines the
> > > > > +details that must be specified by each processor-specific ABI.
> > > > > +
> > > > > +These psABIs are the second part of the ABI. Each instantiation of a BPF
> > > > > +machine must describe the mechanism through which binary interface
> > > > > +compatibility is maintained with respect to the issues highlighted by this
> > > > > +document. However, the details that must be defined by a psABI are a minimum --
> > > > > +a psABI may specify additional requirements for binary interface compatibility
> > > > > +on a platform.
> > > >
> > > > I don't understand what you are trying to say in the above.
> > > > In my mind there is only one BPF psABI and it doesn't have
> > > > generic and processor parts. There is only one "processor".
> > > > BPF is such a processor.
> > >
> > > What I was trying to say was that the document here describes a
> > > generic ABI. In this document there will be areas that are specific to
> > > different implementations and those would be considered processor
> > > specific. In other words, the ubpf runtime could define those things
> > > differently than the rbpf runtime which, in turn, could define those
> > > things differently than the kernel's implementation.
> >
> > I see what you mean. There is only one BPF psABI. There cannot be two.
> > ubpf can decide not to follow it, but it could only mean that
> > it's non conformant and not compatible.
>
> Okay. That was not how I was structuring the ABI. I thought we had
> decided that, as the document said, an instantiation of a machine had
> to
>
> 1. meet the gABI
> 2. specify its requirements vis a vis the psABI
> 3. (optionally) describe other requirements.
>
> If that is not what we decided then we will have to restructure the document.
This abi.rst file is the beginning of "BPF psABI" document.
We probably should rename it to psabi.rst to avoid confusion.
See my slides from IETF 118. I hope they explain what "BPF psABI" is for.
^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [Bpf] [PATCH v3] bpf, docs: Add additional ABI working draft base text
2023-11-08 1:17 ` Alexei Starovoitov
@ 2023-11-08 1:17 ` Alexei Starovoitov
2023-11-08 10:13 ` Will Hawkins
1 sibling, 0 replies; 42+ messages in thread
From: Alexei Starovoitov @ 2023-11-08 1:17 UTC (permalink / raw)
To: Will Hawkins; +Cc: bpf, bpf
On Tue, Nov 7, 2023 at 11:56 AM Will Hawkins <hawkinsw@obs.cr> wrote:
>
> On Mon, Nov 6, 2023 at 3:38 AM Alexei Starovoitov
> <alexei.starovoitov@gmail.com> wrote:
> >
> > On Sun, Nov 5, 2023 at 4:17 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > >
> > > On Sun, Nov 5, 2023 at 4:51 AM Alexei Starovoitov
> > > <alexei.starovoitov@gmail.com> wrote:
> > > >
> > > > On Fri, Nov 3, 2023 at 2:20 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > > +
> > > > > +The ABI is specified in two parts: a generic part and a processor-specific part.
> > > > > +A pairing of generic ABI with the processor-specific ABI for a certain
> > > > > +instantiation of a BPF machine represents a complete binary interface for BPF
> > > > > +programs executing on that machine.
> > > > > +
> > > > > +This document is the generic ABI and specifies the parameters and behavior
> > > > > +common to all instantiations of BPF machines. In addition, it defines the
> > > > > +details that must be specified by each processor-specific ABI.
> > > > > +
> > > > > +These psABIs are the second part of the ABI. Each instantiation of a BPF
> > > > > +machine must describe the mechanism through which binary interface
> > > > > +compatibility is maintained with respect to the issues highlighted by this
> > > > > +document. However, the details that must be defined by a psABI are a minimum --
> > > > > +a psABI may specify additional requirements for binary interface compatibility
> > > > > +on a platform.
> > > >
> > > > I don't understand what you are trying to say in the above.
> > > > In my mind there is only one BPF psABI and it doesn't have
> > > > generic and processor parts. There is only one "processor".
> > > > BPF is such a processor.
> > >
> > > What I was trying to say was that the document here describes a
> > > generic ABI. In this document there will be areas that are specific to
> > > different implementations and those would be considered processor
> > > specific. In other words, the ubpf runtime could define those things
> > > differently than the rbpf runtime which, in turn, could define those
> > > things differently than the kernel's implementation.
> >
> > I see what you mean. There is only one BPF psABI. There cannot be two.
> > ubpf can decide not to follow it, but it could only mean that
> > it's non conformant and not compatible.
>
> Okay. That was not how I was structuring the ABI. I thought we had
> decided that, as the document said, an instantiation of a machine had
> to
>
> 1. meet the gABI
> 2. specify its requirements vis a vis the psABI
> 3. (optionally) describe other requirements.
>
> If that is not what we decided then we will have to restructure the document.
This abi.rst file is the beginning of "BPF psABI" document.
We probably should rename it to psabi.rst to avoid confusion.
See my slides from IETF 118. I hope they explain what "BPF psABI" is for.
--
Bpf mailing list
Bpf@ietf.org
https://www.ietf.org/mailman/listinfo/bpf
^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [Bpf] [PATCH v3] bpf, docs: Add additional ABI working draft base text
2023-11-08 1:17 ` Alexei Starovoitov
2023-11-08 1:17 ` Alexei Starovoitov
@ 2023-11-08 10:13 ` Will Hawkins
2023-11-08 10:13 ` Will Hawkins
2023-11-08 19:51 ` Alexei Starovoitov
1 sibling, 2 replies; 42+ messages in thread
From: Will Hawkins @ 2023-11-08 10:13 UTC (permalink / raw)
To: Alexei Starovoitov; +Cc: bpf, bpf
On Tue, Nov 7, 2023 at 8:17 PM Alexei Starovoitov
<alexei.starovoitov@gmail.com> wrote:
>
> On Tue, Nov 7, 2023 at 11:56 AM Will Hawkins <hawkinsw@obs.cr> wrote:
> >
> > On Mon, Nov 6, 2023 at 3:38 AM Alexei Starovoitov
> > <alexei.starovoitov@gmail.com> wrote:
> > >
> > > On Sun, Nov 5, 2023 at 4:17 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > >
> > > > On Sun, Nov 5, 2023 at 4:51 AM Alexei Starovoitov
> > > > <alexei.starovoitov@gmail.com> wrote:
> > > > >
> > > > > On Fri, Nov 3, 2023 at 2:20 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > > > +
> > > > > > +The ABI is specified in two parts: a generic part and a processor-specific part.
> > > > > > +A pairing of generic ABI with the processor-specific ABI for a certain
> > > > > > +instantiation of a BPF machine represents a complete binary interface for BPF
> > > > > > +programs executing on that machine.
> > > > > > +
> > > > > > +This document is the generic ABI and specifies the parameters and behavior
> > > > > > +common to all instantiations of BPF machines. In addition, it defines the
> > > > > > +details that must be specified by each processor-specific ABI.
> > > > > > +
> > > > > > +These psABIs are the second part of the ABI. Each instantiation of a BPF
> > > > > > +machine must describe the mechanism through which binary interface
> > > > > > +compatibility is maintained with respect to the issues highlighted by this
> > > > > > +document. However, the details that must be defined by a psABI are a minimum --
> > > > > > +a psABI may specify additional requirements for binary interface compatibility
> > > > > > +on a platform.
> > > > >
> > > > > I don't understand what you are trying to say in the above.
> > > > > In my mind there is only one BPF psABI and it doesn't have
> > > > > generic and processor parts. There is only one "processor".
> > > > > BPF is such a processor.
> > > >
> > > > What I was trying to say was that the document here describes a
> > > > generic ABI. In this document there will be areas that are specific to
> > > > different implementations and those would be considered processor
> > > > specific. In other words, the ubpf runtime could define those things
> > > > differently than the rbpf runtime which, in turn, could define those
> > > > things differently than the kernel's implementation.
> > >
> > > I see what you mean. There is only one BPF psABI. There cannot be two.
> > > ubpf can decide not to follow it, but it could only mean that
> > > it's non conformant and not compatible.
> >
> > Okay. That was not how I was structuring the ABI. I thought we had
> > decided that, as the document said, an instantiation of a machine had
> > to
> >
> > 1. meet the gABI
> > 2. specify its requirements vis a vis the psABI
> > 3. (optionally) describe other requirements.
> >
> > If that is not what we decided then we will have to restructure the document.
>
> This abi.rst file is the beginning of "BPF psABI" document.
> We probably should rename it to psabi.rst to avoid confusion.
> See my slides from IETF 118. I hope they explain what "BPF psABI" is for.
Of course they do! Thank you! My only question: In the language I was
using, I was taking a cue from the System V world where there is a
Generic ABI and a psABI. The Generic ABI applies to all System V
compatible systems and defines certain processor-specific details that
each platform must specify to define a complete ABI. In particular, I
took this language as inspiration
"""
The System V ABI is composed of two basic parts: A generic part of the
specification describes those parts of the interface that remain
constant across all hardware implementations of System V, and a
processor-specific part of the specification describes the parts of
the specification that are specific to a particular processor
architecture. Together, the generic ABI (or gABI) and the processor
specific supplement (or psABI) provide a complete interface
specification for compiled application programs on systems that share
a common hardware architecture.
"""
See [1].
If you want this document to just be the psABI for Linux, then that is
what we will do -- you are the expert and I am just the drafter.
[1] https://www.sco.com/developers/gabi/
Will
^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [Bpf] [PATCH v3] bpf, docs: Add additional ABI working draft base text
2023-11-08 10:13 ` Will Hawkins
@ 2023-11-08 10:13 ` Will Hawkins
2023-11-08 19:51 ` Alexei Starovoitov
1 sibling, 0 replies; 42+ messages in thread
From: Will Hawkins @ 2023-11-08 10:13 UTC (permalink / raw)
To: Alexei Starovoitov; +Cc: bpf, bpf
On Tue, Nov 7, 2023 at 8:17 PM Alexei Starovoitov
<alexei.starovoitov@gmail.com> wrote:
>
> On Tue, Nov 7, 2023 at 11:56 AM Will Hawkins <hawkinsw@obs.cr> wrote:
> >
> > On Mon, Nov 6, 2023 at 3:38 AM Alexei Starovoitov
> > <alexei.starovoitov@gmail.com> wrote:
> > >
> > > On Sun, Nov 5, 2023 at 4:17 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > >
> > > > On Sun, Nov 5, 2023 at 4:51 AM Alexei Starovoitov
> > > > <alexei.starovoitov@gmail.com> wrote:
> > > > >
> > > > > On Fri, Nov 3, 2023 at 2:20 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > > > +
> > > > > > +The ABI is specified in two parts: a generic part and a processor-specific part.
> > > > > > +A pairing of generic ABI with the processor-specific ABI for a certain
> > > > > > +instantiation of a BPF machine represents a complete binary interface for BPF
> > > > > > +programs executing on that machine.
> > > > > > +
> > > > > > +This document is the generic ABI and specifies the parameters and behavior
> > > > > > +common to all instantiations of BPF machines. In addition, it defines the
> > > > > > +details that must be specified by each processor-specific ABI.
> > > > > > +
> > > > > > +These psABIs are the second part of the ABI. Each instantiation of a BPF
> > > > > > +machine must describe the mechanism through which binary interface
> > > > > > +compatibility is maintained with respect to the issues highlighted by this
> > > > > > +document. However, the details that must be defined by a psABI are a minimum --
> > > > > > +a psABI may specify additional requirements for binary interface compatibility
> > > > > > +on a platform.
> > > > >
> > > > > I don't understand what you are trying to say in the above.
> > > > > In my mind there is only one BPF psABI and it doesn't have
> > > > > generic and processor parts. There is only one "processor".
> > > > > BPF is such a processor.
> > > >
> > > > What I was trying to say was that the document here describes a
> > > > generic ABI. In this document there will be areas that are specific to
> > > > different implementations and those would be considered processor
> > > > specific. In other words, the ubpf runtime could define those things
> > > > differently than the rbpf runtime which, in turn, could define those
> > > > things differently than the kernel's implementation.
> > >
> > > I see what you mean. There is only one BPF psABI. There cannot be two.
> > > ubpf can decide not to follow it, but it could only mean that
> > > it's non conformant and not compatible.
> >
> > Okay. That was not how I was structuring the ABI. I thought we had
> > decided that, as the document said, an instantiation of a machine had
> > to
> >
> > 1. meet the gABI
> > 2. specify its requirements vis a vis the psABI
> > 3. (optionally) describe other requirements.
> >
> > If that is not what we decided then we will have to restructure the document.
>
> This abi.rst file is the beginning of "BPF psABI" document.
> We probably should rename it to psabi.rst to avoid confusion.
> See my slides from IETF 118. I hope they explain what "BPF psABI" is for.
Of course they do! Thank you! My only question: In the language I was
using, I was taking a cue from the System V world where there is a
Generic ABI and a psABI. The Generic ABI applies to all System V
compatible systems and defines certain processor-specific details that
each platform must specify to define a complete ABI. In particular, I
took this language as inspiration
"""
The System V ABI is composed of two basic parts: A generic part of the
specification describes those parts of the interface that remain
constant across all hardware implementations of System V, and a
processor-specific part of the specification describes the parts of
the specification that are specific to a particular processor
architecture. Together, the generic ABI (or gABI) and the processor
specific supplement (or psABI) provide a complete interface
specification for compiled application programs on systems that share
a common hardware architecture.
"""
See [1].
If you want this document to just be the psABI for Linux, then that is
what we will do -- you are the expert and I am just the drafter.
[1] https://www.sco.com/developers/gabi/
Will
--
Bpf mailing list
Bpf@ietf.org
https://www.ietf.org/mailman/listinfo/bpf
^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [Bpf] [PATCH v3] bpf, docs: Add additional ABI working draft base text
2023-11-08 10:13 ` Will Hawkins
2023-11-08 10:13 ` Will Hawkins
@ 2023-11-08 19:51 ` Alexei Starovoitov
2023-11-08 19:51 ` Alexei Starovoitov
2023-11-08 23:57 ` Will Hawkins
1 sibling, 2 replies; 42+ messages in thread
From: Alexei Starovoitov @ 2023-11-08 19:51 UTC (permalink / raw)
To: Will Hawkins; +Cc: bpf, bpf
On Wed, Nov 8, 2023 at 2:13 AM Will Hawkins <hawkinsw@obs.cr> wrote:
>
> On Tue, Nov 7, 2023 at 8:17 PM Alexei Starovoitov
> <alexei.starovoitov@gmail.com> wrote:
> >
> > On Tue, Nov 7, 2023 at 11:56 AM Will Hawkins <hawkinsw@obs.cr> wrote:
> > >
> > > On Mon, Nov 6, 2023 at 3:38 AM Alexei Starovoitov
> > > <alexei.starovoitov@gmail.com> wrote:
> > > >
> > > > On Sun, Nov 5, 2023 at 4:17 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > >
> > > > > On Sun, Nov 5, 2023 at 4:51 AM Alexei Starovoitov
> > > > > <alexei.starovoitov@gmail.com> wrote:
> > > > > >
> > > > > > On Fri, Nov 3, 2023 at 2:20 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > > > > +
> > > > > > > +The ABI is specified in two parts: a generic part and a processor-specific part.
> > > > > > > +A pairing of generic ABI with the processor-specific ABI for a certain
> > > > > > > +instantiation of a BPF machine represents a complete binary interface for BPF
> > > > > > > +programs executing on that machine.
> > > > > > > +
> > > > > > > +This document is the generic ABI and specifies the parameters and behavior
> > > > > > > +common to all instantiations of BPF machines. In addition, it defines the
> > > > > > > +details that must be specified by each processor-specific ABI.
> > > > > > > +
> > > > > > > +These psABIs are the second part of the ABI. Each instantiation of a BPF
> > > > > > > +machine must describe the mechanism through which binary interface
> > > > > > > +compatibility is maintained with respect to the issues highlighted by this
> > > > > > > +document. However, the details that must be defined by a psABI are a minimum --
> > > > > > > +a psABI may specify additional requirements for binary interface compatibility
> > > > > > > +on a platform.
> > > > > >
> > > > > > I don't understand what you are trying to say in the above.
> > > > > > In my mind there is only one BPF psABI and it doesn't have
> > > > > > generic and processor parts. There is only one "processor".
> > > > > > BPF is such a processor.
> > > > >
> > > > > What I was trying to say was that the document here describes a
> > > > > generic ABI. In this document there will be areas that are specific to
> > > > > different implementations and those would be considered processor
> > > > > specific. In other words, the ubpf runtime could define those things
> > > > > differently than the rbpf runtime which, in turn, could define those
> > > > > things differently than the kernel's implementation.
> > > >
> > > > I see what you mean. There is only one BPF psABI. There cannot be two.
> > > > ubpf can decide not to follow it, but it could only mean that
> > > > it's non conformant and not compatible.
> > >
> > > Okay. That was not how I was structuring the ABI. I thought we had
> > > decided that, as the document said, an instantiation of a machine had
> > > to
> > >
> > > 1. meet the gABI
> > > 2. specify its requirements vis a vis the psABI
> > > 3. (optionally) describe other requirements.
> > >
> > > If that is not what we decided then we will have to restructure the document.
> >
> > This abi.rst file is the beginning of "BPF psABI" document.
> > We probably should rename it to psabi.rst to avoid confusion.
> > See my slides from IETF 118. I hope they explain what "BPF psABI" is for.
>
> Of course they do! Thank you! My only question: In the language I was
> using, I was taking a cue from the System V world where there is a
> Generic ABI and a psABI. The Generic ABI applies to all System V
> compatible systems and defines certain processor-specific details that
> each platform must specify to define a complete ABI. In particular, I
> took this language as inspiration
>
> """
> The System V ABI is composed of two basic parts: A generic part of the
> specification describes those parts of the interface that remain
> constant across all hardware implementations of System V, and a
> processor-specific part of the specification describes the parts of
> the specification that are specific to a particular processor
> architecture. Together, the generic ABI (or gABI) and the processor
> specific supplement (or psABI) provide a complete interface
> specification for compiled application programs on systems that share
> a common hardware architecture.
> """
I see where you got the inspiration from, but it's not applicable
in the BPF case. BPF is such one and only processor.
We're not changing nor adding anything to Sys V generic parts.
^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [Bpf] [PATCH v3] bpf, docs: Add additional ABI working draft base text
2023-11-08 19:51 ` Alexei Starovoitov
@ 2023-11-08 19:51 ` Alexei Starovoitov
2023-11-08 23:57 ` Will Hawkins
1 sibling, 0 replies; 42+ messages in thread
From: Alexei Starovoitov @ 2023-11-08 19:51 UTC (permalink / raw)
To: Will Hawkins; +Cc: bpf, bpf
On Wed, Nov 8, 2023 at 2:13 AM Will Hawkins <hawkinsw@obs.cr> wrote:
>
> On Tue, Nov 7, 2023 at 8:17 PM Alexei Starovoitov
> <alexei.starovoitov@gmail.com> wrote:
> >
> > On Tue, Nov 7, 2023 at 11:56 AM Will Hawkins <hawkinsw@obs.cr> wrote:
> > >
> > > On Mon, Nov 6, 2023 at 3:38 AM Alexei Starovoitov
> > > <alexei.starovoitov@gmail.com> wrote:
> > > >
> > > > On Sun, Nov 5, 2023 at 4:17 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > >
> > > > > On Sun, Nov 5, 2023 at 4:51 AM Alexei Starovoitov
> > > > > <alexei.starovoitov@gmail.com> wrote:
> > > > > >
> > > > > > On Fri, Nov 3, 2023 at 2:20 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > > > > +
> > > > > > > +The ABI is specified in two parts: a generic part and a processor-specific part.
> > > > > > > +A pairing of generic ABI with the processor-specific ABI for a certain
> > > > > > > +instantiation of a BPF machine represents a complete binary interface for BPF
> > > > > > > +programs executing on that machine.
> > > > > > > +
> > > > > > > +This document is the generic ABI and specifies the parameters and behavior
> > > > > > > +common to all instantiations of BPF machines. In addition, it defines the
> > > > > > > +details that must be specified by each processor-specific ABI.
> > > > > > > +
> > > > > > > +These psABIs are the second part of the ABI. Each instantiation of a BPF
> > > > > > > +machine must describe the mechanism through which binary interface
> > > > > > > +compatibility is maintained with respect to the issues highlighted by this
> > > > > > > +document. However, the details that must be defined by a psABI are a minimum --
> > > > > > > +a psABI may specify additional requirements for binary interface compatibility
> > > > > > > +on a platform.
> > > > > >
> > > > > > I don't understand what you are trying to say in the above.
> > > > > > In my mind there is only one BPF psABI and it doesn't have
> > > > > > generic and processor parts. There is only one "processor".
> > > > > > BPF is such a processor.
> > > > >
> > > > > What I was trying to say was that the document here describes a
> > > > > generic ABI. In this document there will be areas that are specific to
> > > > > different implementations and those would be considered processor
> > > > > specific. In other words, the ubpf runtime could define those things
> > > > > differently than the rbpf runtime which, in turn, could define those
> > > > > things differently than the kernel's implementation.
> > > >
> > > > I see what you mean. There is only one BPF psABI. There cannot be two.
> > > > ubpf can decide not to follow it, but it could only mean that
> > > > it's non conformant and not compatible.
> > >
> > > Okay. That was not how I was structuring the ABI. I thought we had
> > > decided that, as the document said, an instantiation of a machine had
> > > to
> > >
> > > 1. meet the gABI
> > > 2. specify its requirements vis a vis the psABI
> > > 3. (optionally) describe other requirements.
> > >
> > > If that is not what we decided then we will have to restructure the document.
> >
> > This abi.rst file is the beginning of "BPF psABI" document.
> > We probably should rename it to psabi.rst to avoid confusion.
> > See my slides from IETF 118. I hope they explain what "BPF psABI" is for.
>
> Of course they do! Thank you! My only question: In the language I was
> using, I was taking a cue from the System V world where there is a
> Generic ABI and a psABI. The Generic ABI applies to all System V
> compatible systems and defines certain processor-specific details that
> each platform must specify to define a complete ABI. In particular, I
> took this language as inspiration
>
> """
> The System V ABI is composed of two basic parts: A generic part of the
> specification describes those parts of the interface that remain
> constant across all hardware implementations of System V, and a
> processor-specific part of the specification describes the parts of
> the specification that are specific to a particular processor
> architecture. Together, the generic ABI (or gABI) and the processor
> specific supplement (or psABI) provide a complete interface
> specification for compiled application programs on systems that share
> a common hardware architecture.
> """
I see where you got the inspiration from, but it's not applicable
in the BPF case. BPF is such one and only processor.
We're not changing nor adding anything to Sys V generic parts.
--
Bpf mailing list
Bpf@ietf.org
https://www.ietf.org/mailman/listinfo/bpf
^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [Bpf] [PATCH v3] bpf, docs: Add additional ABI working draft base text
2023-11-08 19:51 ` Alexei Starovoitov
2023-11-08 19:51 ` Alexei Starovoitov
@ 2023-11-08 23:57 ` Will Hawkins
2023-11-08 23:57 ` Will Hawkins
2023-11-09 18:31 ` Alexei Starovoitov
1 sibling, 2 replies; 42+ messages in thread
From: Will Hawkins @ 2023-11-08 23:57 UTC (permalink / raw)
To: Alexei Starovoitov; +Cc: bpf, bpf
On Wed, Nov 8, 2023 at 2:51 PM Alexei Starovoitov
<alexei.starovoitov@gmail.com> wrote:
>
> On Wed, Nov 8, 2023 at 2:13 AM Will Hawkins <hawkinsw@obs.cr> wrote:
> >
> > On Tue, Nov 7, 2023 at 8:17 PM Alexei Starovoitov
> > <alexei.starovoitov@gmail.com> wrote:
> > >
> > > On Tue, Nov 7, 2023 at 11:56 AM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > >
> > > > On Mon, Nov 6, 2023 at 3:38 AM Alexei Starovoitov
> > > > <alexei.starovoitov@gmail.com> wrote:
> > > > >
> > > > > On Sun, Nov 5, 2023 at 4:17 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > > >
> > > > > > On Sun, Nov 5, 2023 at 4:51 AM Alexei Starovoitov
> > > > > > <alexei.starovoitov@gmail.com> wrote:
> > > > > > >
> > > > > > > On Fri, Nov 3, 2023 at 2:20 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > > > > > +
> > > > > > > > +The ABI is specified in two parts: a generic part and a processor-specific part.
> > > > > > > > +A pairing of generic ABI with the processor-specific ABI for a certain
> > > > > > > > +instantiation of a BPF machine represents a complete binary interface for BPF
> > > > > > > > +programs executing on that machine.
> > > > > > > > +
> > > > > > > > +This document is the generic ABI and specifies the parameters and behavior
> > > > > > > > +common to all instantiations of BPF machines. In addition, it defines the
> > > > > > > > +details that must be specified by each processor-specific ABI.
> > > > > > > > +
> > > > > > > > +These psABIs are the second part of the ABI. Each instantiation of a BPF
> > > > > > > > +machine must describe the mechanism through which binary interface
> > > > > > > > +compatibility is maintained with respect to the issues highlighted by this
> > > > > > > > +document. However, the details that must be defined by a psABI are a minimum --
> > > > > > > > +a psABI may specify additional requirements for binary interface compatibility
> > > > > > > > +on a platform.
> > > > > > >
> > > > > > > I don't understand what you are trying to say in the above.
> > > > > > > In my mind there is only one BPF psABI and it doesn't have
> > > > > > > generic and processor parts. There is only one "processor".
> > > > > > > BPF is such a processor.
> > > > > >
> > > > > > What I was trying to say was that the document here describes a
> > > > > > generic ABI. In this document there will be areas that are specific to
> > > > > > different implementations and those would be considered processor
> > > > > > specific. In other words, the ubpf runtime could define those things
> > > > > > differently than the rbpf runtime which, in turn, could define those
> > > > > > things differently than the kernel's implementation.
> > > > >
> > > > > I see what you mean. There is only one BPF psABI. There cannot be two.
> > > > > ubpf can decide not to follow it, but it could only mean that
> > > > > it's non conformant and not compatible.
> > > >
> > > > Okay. That was not how I was structuring the ABI. I thought we had
> > > > decided that, as the document said, an instantiation of a machine had
> > > > to
> > > >
> > > > 1. meet the gABI
> > > > 2. specify its requirements vis a vis the psABI
> > > > 3. (optionally) describe other requirements.
> > > >
> > > > If that is not what we decided then we will have to restructure the document.
> > >
> > > This abi.rst file is the beginning of "BPF psABI" document.
> > > We probably should rename it to psabi.rst to avoid confusion.
> > > See my slides from IETF 118. I hope they explain what "BPF psABI" is for.
> >
> > Of course they do! Thank you! My only question: In the language I was
> > using, I was taking a cue from the System V world where there is a
> > Generic ABI and a psABI. The Generic ABI applies to all System V
> > compatible systems and defines certain processor-specific details that
> > each platform must specify to define a complete ABI. In particular, I
> > took this language as inspiration
> >
> > """
> > The System V ABI is composed of two basic parts: A generic part of the
> > specification describes those parts of the interface that remain
> > constant across all hardware implementations of System V, and a
> > processor-specific part of the specification describes the parts of
> > the specification that are specific to a particular processor
> > architecture. Together, the generic ABI (or gABI) and the processor
> > specific supplement (or psABI) provide a complete interface
> > specification for compiled application programs on systems that share
> > a common hardware architecture.
> > """
>
> I see where you got the inspiration from, but it's not applicable
> in the BPF case. BPF is such one and only processor.
> We're not changing nor adding anything to Sys V generic parts.
That was not quite what I was saying. What I started to draft is
something (yes, modeled after the Sys V (g/ps)ABI) but _brand new_ for
BPF. I think that is where I have been failing to communicate
correctly. What I was proposing was inspired by other ABIs but
completely separate and orthogonal. That is the reason for the
document speaking of a BPF Machine like:
ABI-conforming BPF Machine Instantiation: A physical or logical realization
of a computer system capable of executing BPF programs consistently with the
specifications outlined in this document.
because it is a (not necessarily physical) entity that executes BPF
programs (i.e. a "BPF CPU") for which we are specifying the binary
compatibility. In other words, the document as it stands is proposing
a gABI where
the kernel's "BPF CPU" would have its own psABI
ubpf's "BPF CPU" would have its own psABI
and others could do the same into the future so long as they met the
gABI guidelines and properly outlined the way that they handle the
processor-specific details.
My goal with writing was to give us the chance to build a whole
separate structure free and clear from Sys V so we could define our
own rules if/where there is misalignment between BPF programs and
programs that execute on a traditional CPU.
If you believe that we should just define a psABI for BPF and slot in
to the SysV ABI that is perfectly okay with me (again, you are the
expert) but that is very different than the way the currently proposed
document is written.
Will
^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [Bpf] [PATCH v3] bpf, docs: Add additional ABI working draft base text
2023-11-08 23:57 ` Will Hawkins
@ 2023-11-08 23:57 ` Will Hawkins
2023-11-09 18:31 ` Alexei Starovoitov
1 sibling, 0 replies; 42+ messages in thread
From: Will Hawkins @ 2023-11-08 23:57 UTC (permalink / raw)
To: Alexei Starovoitov; +Cc: bpf, bpf
On Wed, Nov 8, 2023 at 2:51 PM Alexei Starovoitov
<alexei.starovoitov@gmail.com> wrote:
>
> On Wed, Nov 8, 2023 at 2:13 AM Will Hawkins <hawkinsw@obs.cr> wrote:
> >
> > On Tue, Nov 7, 2023 at 8:17 PM Alexei Starovoitov
> > <alexei.starovoitov@gmail.com> wrote:
> > >
> > > On Tue, Nov 7, 2023 at 11:56 AM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > >
> > > > On Mon, Nov 6, 2023 at 3:38 AM Alexei Starovoitov
> > > > <alexei.starovoitov@gmail.com> wrote:
> > > > >
> > > > > On Sun, Nov 5, 2023 at 4:17 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > > >
> > > > > > On Sun, Nov 5, 2023 at 4:51 AM Alexei Starovoitov
> > > > > > <alexei.starovoitov@gmail.com> wrote:
> > > > > > >
> > > > > > > On Fri, Nov 3, 2023 at 2:20 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > > > > > +
> > > > > > > > +The ABI is specified in two parts: a generic part and a processor-specific part.
> > > > > > > > +A pairing of generic ABI with the processor-specific ABI for a certain
> > > > > > > > +instantiation of a BPF machine represents a complete binary interface for BPF
> > > > > > > > +programs executing on that machine.
> > > > > > > > +
> > > > > > > > +This document is the generic ABI and specifies the parameters and behavior
> > > > > > > > +common to all instantiations of BPF machines. In addition, it defines the
> > > > > > > > +details that must be specified by each processor-specific ABI.
> > > > > > > > +
> > > > > > > > +These psABIs are the second part of the ABI. Each instantiation of a BPF
> > > > > > > > +machine must describe the mechanism through which binary interface
> > > > > > > > +compatibility is maintained with respect to the issues highlighted by this
> > > > > > > > +document. However, the details that must be defined by a psABI are a minimum --
> > > > > > > > +a psABI may specify additional requirements for binary interface compatibility
> > > > > > > > +on a platform.
> > > > > > >
> > > > > > > I don't understand what you are trying to say in the above.
> > > > > > > In my mind there is only one BPF psABI and it doesn't have
> > > > > > > generic and processor parts. There is only one "processor".
> > > > > > > BPF is such a processor.
> > > > > >
> > > > > > What I was trying to say was that the document here describes a
> > > > > > generic ABI. In this document there will be areas that are specific to
> > > > > > different implementations and those would be considered processor
> > > > > > specific. In other words, the ubpf runtime could define those things
> > > > > > differently than the rbpf runtime which, in turn, could define those
> > > > > > things differently than the kernel's implementation.
> > > > >
> > > > > I see what you mean. There is only one BPF psABI. There cannot be two.
> > > > > ubpf can decide not to follow it, but it could only mean that
> > > > > it's non conformant and not compatible.
> > > >
> > > > Okay. That was not how I was structuring the ABI. I thought we had
> > > > decided that, as the document said, an instantiation of a machine had
> > > > to
> > > >
> > > > 1. meet the gABI
> > > > 2. specify its requirements vis a vis the psABI
> > > > 3. (optionally) describe other requirements.
> > > >
> > > > If that is not what we decided then we will have to restructure the document.
> > >
> > > This abi.rst file is the beginning of "BPF psABI" document.
> > > We probably should rename it to psabi.rst to avoid confusion.
> > > See my slides from IETF 118. I hope they explain what "BPF psABI" is for.
> >
> > Of course they do! Thank you! My only question: In the language I was
> > using, I was taking a cue from the System V world where there is a
> > Generic ABI and a psABI. The Generic ABI applies to all System V
> > compatible systems and defines certain processor-specific details that
> > each platform must specify to define a complete ABI. In particular, I
> > took this language as inspiration
> >
> > """
> > The System V ABI is composed of two basic parts: A generic part of the
> > specification describes those parts of the interface that remain
> > constant across all hardware implementations of System V, and a
> > processor-specific part of the specification describes the parts of
> > the specification that are specific to a particular processor
> > architecture. Together, the generic ABI (or gABI) and the processor
> > specific supplement (or psABI) provide a complete interface
> > specification for compiled application programs on systems that share
> > a common hardware architecture.
> > """
>
> I see where you got the inspiration from, but it's not applicable
> in the BPF case. BPF is such one and only processor.
> We're not changing nor adding anything to Sys V generic parts.
That was not quite what I was saying. What I started to draft is
something (yes, modeled after the Sys V (g/ps)ABI) but _brand new_ for
BPF. I think that is where I have been failing to communicate
correctly. What I was proposing was inspired by other ABIs but
completely separate and orthogonal. That is the reason for the
document speaking of a BPF Machine like:
ABI-conforming BPF Machine Instantiation: A physical or logical realization
of a computer system capable of executing BPF programs consistently with the
specifications outlined in this document.
because it is a (not necessarily physical) entity that executes BPF
programs (i.e. a "BPF CPU") for which we are specifying the binary
compatibility. In other words, the document as it stands is proposing
a gABI where
the kernel's "BPF CPU" would have its own psABI
ubpf's "BPF CPU" would have its own psABI
and others could do the same into the future so long as they met the
gABI guidelines and properly outlined the way that they handle the
processor-specific details.
My goal with writing was to give us the chance to build a whole
separate structure free and clear from Sys V so we could define our
own rules if/where there is misalignment between BPF programs and
programs that execute on a traditional CPU.
If you believe that we should just define a psABI for BPF and slot in
to the SysV ABI that is perfectly okay with me (again, you are the
expert) but that is very different than the way the currently proposed
document is written.
Will
--
Bpf mailing list
Bpf@ietf.org
https://www.ietf.org/mailman/listinfo/bpf
^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [Bpf] [PATCH v3] bpf, docs: Add additional ABI working draft base text
2023-11-08 23:57 ` Will Hawkins
2023-11-08 23:57 ` Will Hawkins
@ 2023-11-09 18:31 ` Alexei Starovoitov
2023-11-09 18:31 ` Alexei Starovoitov
2023-11-10 0:56 ` Will Hawkins
1 sibling, 2 replies; 42+ messages in thread
From: Alexei Starovoitov @ 2023-11-09 18:31 UTC (permalink / raw)
To: Will Hawkins; +Cc: bpf, bpf
On Wed, Nov 8, 2023 at 3:57 PM Will Hawkins <hawkinsw@obs.cr> wrote:
>
> On Wed, Nov 8, 2023 at 2:51 PM Alexei Starovoitov
> <alexei.starovoitov@gmail.com> wrote:
> >
> > On Wed, Nov 8, 2023 at 2:13 AM Will Hawkins <hawkinsw@obs.cr> wrote:
> > >
> > > On Tue, Nov 7, 2023 at 8:17 PM Alexei Starovoitov
> > > <alexei.starovoitov@gmail.com> wrote:
> > > >
> > > > On Tue, Nov 7, 2023 at 11:56 AM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > >
> > > > > On Mon, Nov 6, 2023 at 3:38 AM Alexei Starovoitov
> > > > > <alexei.starovoitov@gmail.com> wrote:
> > > > > >
> > > > > > On Sun, Nov 5, 2023 at 4:17 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > > > >
> > > > > > > On Sun, Nov 5, 2023 at 4:51 AM Alexei Starovoitov
> > > > > > > <alexei.starovoitov@gmail.com> wrote:
> > > > > > > >
> > > > > > > > On Fri, Nov 3, 2023 at 2:20 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > > > > > > +
> > > > > > > > > +The ABI is specified in two parts: a generic part and a processor-specific part.
> > > > > > > > > +A pairing of generic ABI with the processor-specific ABI for a certain
> > > > > > > > > +instantiation of a BPF machine represents a complete binary interface for BPF
> > > > > > > > > +programs executing on that machine.
> > > > > > > > > +
> > > > > > > > > +This document is the generic ABI and specifies the parameters and behavior
> > > > > > > > > +common to all instantiations of BPF machines. In addition, it defines the
> > > > > > > > > +details that must be specified by each processor-specific ABI.
> > > > > > > > > +
> > > > > > > > > +These psABIs are the second part of the ABI. Each instantiation of a BPF
> > > > > > > > > +machine must describe the mechanism through which binary interface
> > > > > > > > > +compatibility is maintained with respect to the issues highlighted by this
> > > > > > > > > +document. However, the details that must be defined by a psABI are a minimum --
> > > > > > > > > +a psABI may specify additional requirements for binary interface compatibility
> > > > > > > > > +on a platform.
> > > > > > > >
> > > > > > > > I don't understand what you are trying to say in the above.
> > > > > > > > In my mind there is only one BPF psABI and it doesn't have
> > > > > > > > generic and processor parts. There is only one "processor".
> > > > > > > > BPF is such a processor.
> > > > > > >
> > > > > > > What I was trying to say was that the document here describes a
> > > > > > > generic ABI. In this document there will be areas that are specific to
> > > > > > > different implementations and those would be considered processor
> > > > > > > specific. In other words, the ubpf runtime could define those things
> > > > > > > differently than the rbpf runtime which, in turn, could define those
> > > > > > > things differently than the kernel's implementation.
> > > > > >
> > > > > > I see what you mean. There is only one BPF psABI. There cannot be two.
> > > > > > ubpf can decide not to follow it, but it could only mean that
> > > > > > it's non conformant and not compatible.
> > > > >
> > > > > Okay. That was not how I was structuring the ABI. I thought we had
> > > > > decided that, as the document said, an instantiation of a machine had
> > > > > to
> > > > >
> > > > > 1. meet the gABI
> > > > > 2. specify its requirements vis a vis the psABI
> > > > > 3. (optionally) describe other requirements.
> > > > >
> > > > > If that is not what we decided then we will have to restructure the document.
> > > >
> > > > This abi.rst file is the beginning of "BPF psABI" document.
> > > > We probably should rename it to psabi.rst to avoid confusion.
> > > > See my slides from IETF 118. I hope they explain what "BPF psABI" is for.
> > >
> > > Of course they do! Thank you! My only question: In the language I was
> > > using, I was taking a cue from the System V world where there is a
> > > Generic ABI and a psABI. The Generic ABI applies to all System V
> > > compatible systems and defines certain processor-specific details that
> > > each platform must specify to define a complete ABI. In particular, I
> > > took this language as inspiration
> > >
> > > """
> > > The System V ABI is composed of two basic parts: A generic part of the
> > > specification describes those parts of the interface that remain
> > > constant across all hardware implementations of System V, and a
> > > processor-specific part of the specification describes the parts of
> > > the specification that are specific to a particular processor
> > > architecture. Together, the generic ABI (or gABI) and the processor
> > > specific supplement (or psABI) provide a complete interface
> > > specification for compiled application programs on systems that share
> > > a common hardware architecture.
> > > """
> >
> > I see where you got the inspiration from, but it's not applicable
> > in the BPF case. BPF is such one and only processor.
> > We're not changing nor adding anything to Sys V generic parts.
>
> That was not quite what I was saying. What I started to draft is
> something (yes, modeled after the Sys V (g/ps)ABI) but _brand new_ for
> BPF. I think that is where I have been failing to communicate
> correctly. What I was proposing was inspired by other ABIs but
> completely separate and orthogonal. That is the reason for the
> document speaking of a BPF Machine like:
>
> ABI-conforming BPF Machine Instantiation: A physical or logical realization
> of a computer system capable of executing BPF programs consistently with the
> specifications outlined in this document.
>
> because it is a (not necessarily physical) entity that executes BPF
> programs (i.e. a "BPF CPU") for which we are specifying the binary
> compatibility. In other words, the document as it stands is proposing
> a gABI where
>
> the kernel's "BPF CPU" would have its own psABI
> ubpf's "BPF CPU" would have its own psABI
and how would you expect that to work?
psABI is a compiler spec in the first place.
The user would use clang -O2 -target bpf_kernel vs -target bpf_ubpf ?
^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [Bpf] [PATCH v3] bpf, docs: Add additional ABI working draft base text
2023-11-09 18:31 ` Alexei Starovoitov
@ 2023-11-09 18:31 ` Alexei Starovoitov
2023-11-10 0:56 ` Will Hawkins
1 sibling, 0 replies; 42+ messages in thread
From: Alexei Starovoitov @ 2023-11-09 18:31 UTC (permalink / raw)
To: Will Hawkins; +Cc: bpf, bpf
On Wed, Nov 8, 2023 at 3:57 PM Will Hawkins <hawkinsw@obs.cr> wrote:
>
> On Wed, Nov 8, 2023 at 2:51 PM Alexei Starovoitov
> <alexei.starovoitov@gmail.com> wrote:
> >
> > On Wed, Nov 8, 2023 at 2:13 AM Will Hawkins <hawkinsw@obs.cr> wrote:
> > >
> > > On Tue, Nov 7, 2023 at 8:17 PM Alexei Starovoitov
> > > <alexei.starovoitov@gmail.com> wrote:
> > > >
> > > > On Tue, Nov 7, 2023 at 11:56 AM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > >
> > > > > On Mon, Nov 6, 2023 at 3:38 AM Alexei Starovoitov
> > > > > <alexei.starovoitov@gmail.com> wrote:
> > > > > >
> > > > > > On Sun, Nov 5, 2023 at 4:17 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > > > >
> > > > > > > On Sun, Nov 5, 2023 at 4:51 AM Alexei Starovoitov
> > > > > > > <alexei.starovoitov@gmail.com> wrote:
> > > > > > > >
> > > > > > > > On Fri, Nov 3, 2023 at 2:20 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > > > > > > +
> > > > > > > > > +The ABI is specified in two parts: a generic part and a processor-specific part.
> > > > > > > > > +A pairing of generic ABI with the processor-specific ABI for a certain
> > > > > > > > > +instantiation of a BPF machine represents a complete binary interface for BPF
> > > > > > > > > +programs executing on that machine.
> > > > > > > > > +
> > > > > > > > > +This document is the generic ABI and specifies the parameters and behavior
> > > > > > > > > +common to all instantiations of BPF machines. In addition, it defines the
> > > > > > > > > +details that must be specified by each processor-specific ABI.
> > > > > > > > > +
> > > > > > > > > +These psABIs are the second part of the ABI. Each instantiation of a BPF
> > > > > > > > > +machine must describe the mechanism through which binary interface
> > > > > > > > > +compatibility is maintained with respect to the issues highlighted by this
> > > > > > > > > +document. However, the details that must be defined by a psABI are a minimum --
> > > > > > > > > +a psABI may specify additional requirements for binary interface compatibility
> > > > > > > > > +on a platform.
> > > > > > > >
> > > > > > > > I don't understand what you are trying to say in the above.
> > > > > > > > In my mind there is only one BPF psABI and it doesn't have
> > > > > > > > generic and processor parts. There is only one "processor".
> > > > > > > > BPF is such a processor.
> > > > > > >
> > > > > > > What I was trying to say was that the document here describes a
> > > > > > > generic ABI. In this document there will be areas that are specific to
> > > > > > > different implementations and those would be considered processor
> > > > > > > specific. In other words, the ubpf runtime could define those things
> > > > > > > differently than the rbpf runtime which, in turn, could define those
> > > > > > > things differently than the kernel's implementation.
> > > > > >
> > > > > > I see what you mean. There is only one BPF psABI. There cannot be two.
> > > > > > ubpf can decide not to follow it, but it could only mean that
> > > > > > it's non conformant and not compatible.
> > > > >
> > > > > Okay. That was not how I was structuring the ABI. I thought we had
> > > > > decided that, as the document said, an instantiation of a machine had
> > > > > to
> > > > >
> > > > > 1. meet the gABI
> > > > > 2. specify its requirements vis a vis the psABI
> > > > > 3. (optionally) describe other requirements.
> > > > >
> > > > > If that is not what we decided then we will have to restructure the document.
> > > >
> > > > This abi.rst file is the beginning of "BPF psABI" document.
> > > > We probably should rename it to psabi.rst to avoid confusion.
> > > > See my slides from IETF 118. I hope they explain what "BPF psABI" is for.
> > >
> > > Of course they do! Thank you! My only question: In the language I was
> > > using, I was taking a cue from the System V world where there is a
> > > Generic ABI and a psABI. The Generic ABI applies to all System V
> > > compatible systems and defines certain processor-specific details that
> > > each platform must specify to define a complete ABI. In particular, I
> > > took this language as inspiration
> > >
> > > """
> > > The System V ABI is composed of two basic parts: A generic part of the
> > > specification describes those parts of the interface that remain
> > > constant across all hardware implementations of System V, and a
> > > processor-specific part of the specification describes the parts of
> > > the specification that are specific to a particular processor
> > > architecture. Together, the generic ABI (or gABI) and the processor
> > > specific supplement (or psABI) provide a complete interface
> > > specification for compiled application programs on systems that share
> > > a common hardware architecture.
> > > """
> >
> > I see where you got the inspiration from, but it's not applicable
> > in the BPF case. BPF is such one and only processor.
> > We're not changing nor adding anything to Sys V generic parts.
>
> That was not quite what I was saying. What I started to draft is
> something (yes, modeled after the Sys V (g/ps)ABI) but _brand new_ for
> BPF. I think that is where I have been failing to communicate
> correctly. What I was proposing was inspired by other ABIs but
> completely separate and orthogonal. That is the reason for the
> document speaking of a BPF Machine like:
>
> ABI-conforming BPF Machine Instantiation: A physical or logical realization
> of a computer system capable of executing BPF programs consistently with the
> specifications outlined in this document.
>
> because it is a (not necessarily physical) entity that executes BPF
> programs (i.e. a "BPF CPU") for which we are specifying the binary
> compatibility. In other words, the document as it stands is proposing
> a gABI where
>
> the kernel's "BPF CPU" would have its own psABI
> ubpf's "BPF CPU" would have its own psABI
and how would you expect that to work?
psABI is a compiler spec in the first place.
The user would use clang -O2 -target bpf_kernel vs -target bpf_ubpf ?
--
Bpf mailing list
Bpf@ietf.org
https://www.ietf.org/mailman/listinfo/bpf
^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [Bpf] [PATCH v3] bpf, docs: Add additional ABI working draft base text
2023-11-09 18:31 ` Alexei Starovoitov
2023-11-09 18:31 ` Alexei Starovoitov
@ 2023-11-10 0:56 ` Will Hawkins
2023-11-10 0:56 ` Will Hawkins
2023-11-10 1:35 ` Will Hawkins
1 sibling, 2 replies; 42+ messages in thread
From: Will Hawkins @ 2023-11-10 0:56 UTC (permalink / raw)
To: Alexei Starovoitov; +Cc: bpf, bpf
On Thu, Nov 9, 2023 at 1:31 PM Alexei Starovoitov
<alexei.starovoitov@gmail.com> wrote:
>
> On Wed, Nov 8, 2023 at 3:57 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> >
> > On Wed, Nov 8, 2023 at 2:51 PM Alexei Starovoitov
> > <alexei.starovoitov@gmail.com> wrote:
> > >
> > > On Wed, Nov 8, 2023 at 2:13 AM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > >
> > > > On Tue, Nov 7, 2023 at 8:17 PM Alexei Starovoitov
> > > > <alexei.starovoitov@gmail.com> wrote:
> > > > >
> > > > > On Tue, Nov 7, 2023 at 11:56 AM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > > >
> > > > > > On Mon, Nov 6, 2023 at 3:38 AM Alexei Starovoitov
> > > > > > <alexei.starovoitov@gmail.com> wrote:
> > > > > > >
> > > > > > > On Sun, Nov 5, 2023 at 4:17 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > > > > >
> > > > > > > > On Sun, Nov 5, 2023 at 4:51 AM Alexei Starovoitov
> > > > > > > > <alexei.starovoitov@gmail.com> wrote:
> > > > > > > > >
> > > > > > > > > On Fri, Nov 3, 2023 at 2:20 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > > > > > > > +
> > > > > > > > > > +The ABI is specified in two parts: a generic part and a processor-specific part.
> > > > > > > > > > +A pairing of generic ABI with the processor-specific ABI for a certain
> > > > > > > > > > +instantiation of a BPF machine represents a complete binary interface for BPF
> > > > > > > > > > +programs executing on that machine.
> > > > > > > > > > +
> > > > > > > > > > +This document is the generic ABI and specifies the parameters and behavior
> > > > > > > > > > +common to all instantiations of BPF machines. In addition, it defines the
> > > > > > > > > > +details that must be specified by each processor-specific ABI.
> > > > > > > > > > +
> > > > > > > > > > +These psABIs are the second part of the ABI. Each instantiation of a BPF
> > > > > > > > > > +machine must describe the mechanism through which binary interface
> > > > > > > > > > +compatibility is maintained with respect to the issues highlighted by this
> > > > > > > > > > +document. However, the details that must be defined by a psABI are a minimum --
> > > > > > > > > > +a psABI may specify additional requirements for binary interface compatibility
> > > > > > > > > > +on a platform.
> > > > > > > > >
> > > > > > > > > I don't understand what you are trying to say in the above.
> > > > > > > > > In my mind there is only one BPF psABI and it doesn't have
> > > > > > > > > generic and processor parts. There is only one "processor".
> > > > > > > > > BPF is such a processor.
> > > > > > > >
> > > > > > > > What I was trying to say was that the document here describes a
> > > > > > > > generic ABI. In this document there will be areas that are specific to
> > > > > > > > different implementations and those would be considered processor
> > > > > > > > specific. In other words, the ubpf runtime could define those things
> > > > > > > > differently than the rbpf runtime which, in turn, could define those
> > > > > > > > things differently than the kernel's implementation.
> > > > > > >
> > > > > > > I see what you mean. There is only one BPF psABI. There cannot be two.
> > > > > > > ubpf can decide not to follow it, but it could only mean that
> > > > > > > it's non conformant and not compatible.
> > > > > >
> > > > > > Okay. That was not how I was structuring the ABI. I thought we had
> > > > > > decided that, as the document said, an instantiation of a machine had
> > > > > > to
> > > > > >
> > > > > > 1. meet the gABI
> > > > > > 2. specify its requirements vis a vis the psABI
> > > > > > 3. (optionally) describe other requirements.
> > > > > >
> > > > > > If that is not what we decided then we will have to restructure the document.
> > > > >
> > > > > This abi.rst file is the beginning of "BPF psABI" document.
> > > > > We probably should rename it to psabi.rst to avoid confusion.
> > > > > See my slides from IETF 118. I hope they explain what "BPF psABI" is for.
> > > >
> > > > Of course they do! Thank you! My only question: In the language I was
> > > > using, I was taking a cue from the System V world where there is a
> > > > Generic ABI and a psABI. The Generic ABI applies to all System V
> > > > compatible systems and defines certain processor-specific details that
> > > > each platform must specify to define a complete ABI. In particular, I
> > > > took this language as inspiration
> > > >
> > > > """
> > > > The System V ABI is composed of two basic parts: A generic part of the
> > > > specification describes those parts of the interface that remain
> > > > constant across all hardware implementations of System V, and a
> > > > processor-specific part of the specification describes the parts of
> > > > the specification that are specific to a particular processor
> > > > architecture. Together, the generic ABI (or gABI) and the processor
> > > > specific supplement (or psABI) provide a complete interface
> > > > specification for compiled application programs on systems that share
> > > > a common hardware architecture.
> > > > """
> > >
> > > I see where you got the inspiration from, but it's not applicable
> > > in the BPF case. BPF is such one and only processor.
> > > We're not changing nor adding anything to Sys V generic parts.
> >
> > That was not quite what I was saying. What I started to draft is
> > something (yes, modeled after the Sys V (g/ps)ABI) but _brand new_ for
> > BPF. I think that is where I have been failing to communicate
> > correctly. What I was proposing was inspired by other ABIs but
> > completely separate and orthogonal. That is the reason for the
> > document speaking of a BPF Machine like:
> >
> > ABI-conforming BPF Machine Instantiation: A physical or logical realization
> > of a computer system capable of executing BPF programs consistently with the
> > specifications outlined in this document.
> >
> > because it is a (not necessarily physical) entity that executes BPF
> > programs (i.e. a "BPF CPU") for which we are specifying the binary
> > compatibility. In other words, the document as it stands is proposing
> > a gABI where
> >
> > the kernel's "BPF CPU" would have its own psABI
> > ubpf's "BPF CPU" would have its own psABI
>
> and how would you expect that to work?
> psABI is a compiler spec in the first place.
> The user would use clang -O2 -target bpf_kernel vs -target bpf_ubpf ?
They could use some other compiler, too.
^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [Bpf] [PATCH v3] bpf, docs: Add additional ABI working draft base text
2023-11-10 0:56 ` Will Hawkins
@ 2023-11-10 0:56 ` Will Hawkins
2023-11-10 1:35 ` Will Hawkins
1 sibling, 0 replies; 42+ messages in thread
From: Will Hawkins @ 2023-11-10 0:56 UTC (permalink / raw)
To: Alexei Starovoitov; +Cc: bpf, bpf
On Thu, Nov 9, 2023 at 1:31 PM Alexei Starovoitov
<alexei.starovoitov@gmail.com> wrote:
>
> On Wed, Nov 8, 2023 at 3:57 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> >
> > On Wed, Nov 8, 2023 at 2:51 PM Alexei Starovoitov
> > <alexei.starovoitov@gmail.com> wrote:
> > >
> > > On Wed, Nov 8, 2023 at 2:13 AM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > >
> > > > On Tue, Nov 7, 2023 at 8:17 PM Alexei Starovoitov
> > > > <alexei.starovoitov@gmail.com> wrote:
> > > > >
> > > > > On Tue, Nov 7, 2023 at 11:56 AM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > > >
> > > > > > On Mon, Nov 6, 2023 at 3:38 AM Alexei Starovoitov
> > > > > > <alexei.starovoitov@gmail.com> wrote:
> > > > > > >
> > > > > > > On Sun, Nov 5, 2023 at 4:17 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > > > > >
> > > > > > > > On Sun, Nov 5, 2023 at 4:51 AM Alexei Starovoitov
> > > > > > > > <alexei.starovoitov@gmail.com> wrote:
> > > > > > > > >
> > > > > > > > > On Fri, Nov 3, 2023 at 2:20 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > > > > > > > +
> > > > > > > > > > +The ABI is specified in two parts: a generic part and a processor-specific part.
> > > > > > > > > > +A pairing of generic ABI with the processor-specific ABI for a certain
> > > > > > > > > > +instantiation of a BPF machine represents a complete binary interface for BPF
> > > > > > > > > > +programs executing on that machine.
> > > > > > > > > > +
> > > > > > > > > > +This document is the generic ABI and specifies the parameters and behavior
> > > > > > > > > > +common to all instantiations of BPF machines. In addition, it defines the
> > > > > > > > > > +details that must be specified by each processor-specific ABI.
> > > > > > > > > > +
> > > > > > > > > > +These psABIs are the second part of the ABI. Each instantiation of a BPF
> > > > > > > > > > +machine must describe the mechanism through which binary interface
> > > > > > > > > > +compatibility is maintained with respect to the issues highlighted by this
> > > > > > > > > > +document. However, the details that must be defined by a psABI are a minimum --
> > > > > > > > > > +a psABI may specify additional requirements for binary interface compatibility
> > > > > > > > > > +on a platform.
> > > > > > > > >
> > > > > > > > > I don't understand what you are trying to say in the above.
> > > > > > > > > In my mind there is only one BPF psABI and it doesn't have
> > > > > > > > > generic and processor parts. There is only one "processor".
> > > > > > > > > BPF is such a processor.
> > > > > > > >
> > > > > > > > What I was trying to say was that the document here describes a
> > > > > > > > generic ABI. In this document there will be areas that are specific to
> > > > > > > > different implementations and those would be considered processor
> > > > > > > > specific. In other words, the ubpf runtime could define those things
> > > > > > > > differently than the rbpf runtime which, in turn, could define those
> > > > > > > > things differently than the kernel's implementation.
> > > > > > >
> > > > > > > I see what you mean. There is only one BPF psABI. There cannot be two.
> > > > > > > ubpf can decide not to follow it, but it could only mean that
> > > > > > > it's non conformant and not compatible.
> > > > > >
> > > > > > Okay. That was not how I was structuring the ABI. I thought we had
> > > > > > decided that, as the document said, an instantiation of a machine had
> > > > > > to
> > > > > >
> > > > > > 1. meet the gABI
> > > > > > 2. specify its requirements vis a vis the psABI
> > > > > > 3. (optionally) describe other requirements.
> > > > > >
> > > > > > If that is not what we decided then we will have to restructure the document.
> > > > >
> > > > > This abi.rst file is the beginning of "BPF psABI" document.
> > > > > We probably should rename it to psabi.rst to avoid confusion.
> > > > > See my slides from IETF 118. I hope they explain what "BPF psABI" is for.
> > > >
> > > > Of course they do! Thank you! My only question: In the language I was
> > > > using, I was taking a cue from the System V world where there is a
> > > > Generic ABI and a psABI. The Generic ABI applies to all System V
> > > > compatible systems and defines certain processor-specific details that
> > > > each platform must specify to define a complete ABI. In particular, I
> > > > took this language as inspiration
> > > >
> > > > """
> > > > The System V ABI is composed of two basic parts: A generic part of the
> > > > specification describes those parts of the interface that remain
> > > > constant across all hardware implementations of System V, and a
> > > > processor-specific part of the specification describes the parts of
> > > > the specification that are specific to a particular processor
> > > > architecture. Together, the generic ABI (or gABI) and the processor
> > > > specific supplement (or psABI) provide a complete interface
> > > > specification for compiled application programs on systems that share
> > > > a common hardware architecture.
> > > > """
> > >
> > > I see where you got the inspiration from, but it's not applicable
> > > in the BPF case. BPF is such one and only processor.
> > > We're not changing nor adding anything to Sys V generic parts.
> >
> > That was not quite what I was saying. What I started to draft is
> > something (yes, modeled after the Sys V (g/ps)ABI) but _brand new_ for
> > BPF. I think that is where I have been failing to communicate
> > correctly. What I was proposing was inspired by other ABIs but
> > completely separate and orthogonal. That is the reason for the
> > document speaking of a BPF Machine like:
> >
> > ABI-conforming BPF Machine Instantiation: A physical or logical realization
> > of a computer system capable of executing BPF programs consistently with the
> > specifications outlined in this document.
> >
> > because it is a (not necessarily physical) entity that executes BPF
> > programs (i.e. a "BPF CPU") for which we are specifying the binary
> > compatibility. In other words, the document as it stands is proposing
> > a gABI where
> >
> > the kernel's "BPF CPU" would have its own psABI
> > ubpf's "BPF CPU" would have its own psABI
>
> and how would you expect that to work?
> psABI is a compiler spec in the first place.
> The user would use clang -O2 -target bpf_kernel vs -target bpf_ubpf ?
They could use some other compiler, too.
--
Bpf mailing list
Bpf@ietf.org
https://www.ietf.org/mailman/listinfo/bpf
^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [Bpf] [PATCH v3] bpf, docs: Add additional ABI working draft base text
2023-11-10 0:56 ` Will Hawkins
2023-11-10 0:56 ` Will Hawkins
@ 2023-11-10 1:35 ` Will Hawkins
2023-11-10 1:35 ` Will Hawkins
1 sibling, 1 reply; 42+ messages in thread
From: Will Hawkins @ 2023-11-10 1:35 UTC (permalink / raw)
To: Alexei Starovoitov; +Cc: bpf, bpf
On Thu, Nov 9, 2023 at 7:56 PM Will Hawkins <hawkinsw@obs.cr> wrote:
>
> On Thu, Nov 9, 2023 at 1:31 PM Alexei Starovoitov
> <alexei.starovoitov@gmail.com> wrote:
> >
> > On Wed, Nov 8, 2023 at 3:57 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > >
> > > On Wed, Nov 8, 2023 at 2:51 PM Alexei Starovoitov
> > > <alexei.starovoitov@gmail.com> wrote:
> > > >
> > > > On Wed, Nov 8, 2023 at 2:13 AM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > >
> > > > > On Tue, Nov 7, 2023 at 8:17 PM Alexei Starovoitov
> > > > > <alexei.starovoitov@gmail.com> wrote:
> > > > > >
> > > > > > On Tue, Nov 7, 2023 at 11:56 AM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > > > >
> > > > > > > On Mon, Nov 6, 2023 at 3:38 AM Alexei Starovoitov
> > > > > > > <alexei.starovoitov@gmail.com> wrote:
> > > > > > > >
> > > > > > > > On Sun, Nov 5, 2023 at 4:17 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > > > > > >
> > > > > > > > > On Sun, Nov 5, 2023 at 4:51 AM Alexei Starovoitov
> > > > > > > > > <alexei.starovoitov@gmail.com> wrote:
> > > > > > > > > >
> > > > > > > > > > On Fri, Nov 3, 2023 at 2:20 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > > > > > > > > +
> > > > > > > > > > > +The ABI is specified in two parts: a generic part and a processor-specific part.
> > > > > > > > > > > +A pairing of generic ABI with the processor-specific ABI for a certain
> > > > > > > > > > > +instantiation of a BPF machine represents a complete binary interface for BPF
> > > > > > > > > > > +programs executing on that machine.
> > > > > > > > > > > +
> > > > > > > > > > > +This document is the generic ABI and specifies the parameters and behavior
> > > > > > > > > > > +common to all instantiations of BPF machines. In addition, it defines the
> > > > > > > > > > > +details that must be specified by each processor-specific ABI.
> > > > > > > > > > > +
> > > > > > > > > > > +These psABIs are the second part of the ABI. Each instantiation of a BPF
> > > > > > > > > > > +machine must describe the mechanism through which binary interface
> > > > > > > > > > > +compatibility is maintained with respect to the issues highlighted by this
> > > > > > > > > > > +document. However, the details that must be defined by a psABI are a minimum --
> > > > > > > > > > > +a psABI may specify additional requirements for binary interface compatibility
> > > > > > > > > > > +on a platform.
> > > > > > > > > >
> > > > > > > > > > I don't understand what you are trying to say in the above.
> > > > > > > > > > In my mind there is only one BPF psABI and it doesn't have
> > > > > > > > > > generic and processor parts. There is only one "processor".
> > > > > > > > > > BPF is such a processor.
> > > > > > > > >
> > > > > > > > > What I was trying to say was that the document here describes a
> > > > > > > > > generic ABI. In this document there will be areas that are specific to
> > > > > > > > > different implementations and those would be considered processor
> > > > > > > > > specific. In other words, the ubpf runtime could define those things
> > > > > > > > > differently than the rbpf runtime which, in turn, could define those
> > > > > > > > > things differently than the kernel's implementation.
> > > > > > > >
> > > > > > > > I see what you mean. There is only one BPF psABI. There cannot be two.
> > > > > > > > ubpf can decide not to follow it, but it could only mean that
> > > > > > > > it's non conformant and not compatible.
> > > > > > >
> > > > > > > Okay. That was not how I was structuring the ABI. I thought we had
> > > > > > > decided that, as the document said, an instantiation of a machine had
> > > > > > > to
> > > > > > >
> > > > > > > 1. meet the gABI
> > > > > > > 2. specify its requirements vis a vis the psABI
> > > > > > > 3. (optionally) describe other requirements.
> > > > > > >
> > > > > > > If that is not what we decided then we will have to restructure the document.
> > > > > >
> > > > > > This abi.rst file is the beginning of "BPF psABI" document.
> > > > > > We probably should rename it to psabi.rst to avoid confusion.
> > > > > > See my slides from IETF 118. I hope they explain what "BPF psABI" is for.
> > > > >
> > > > > Of course they do! Thank you! My only question: In the language I was
> > > > > using, I was taking a cue from the System V world where there is a
> > > > > Generic ABI and a psABI. The Generic ABI applies to all System V
> > > > > compatible systems and defines certain processor-specific details that
> > > > > each platform must specify to define a complete ABI. In particular, I
> > > > > took this language as inspiration
> > > > >
> > > > > """
> > > > > The System V ABI is composed of two basic parts: A generic part of the
> > > > > specification describes those parts of the interface that remain
> > > > > constant across all hardware implementations of System V, and a
> > > > > processor-specific part of the specification describes the parts of
> > > > > the specification that are specific to a particular processor
> > > > > architecture. Together, the generic ABI (or gABI) and the processor
> > > > > specific supplement (or psABI) provide a complete interface
> > > > > specification for compiled application programs on systems that share
> > > > > a common hardware architecture.
> > > > > """
> > > >
> > > > I see where you got the inspiration from, but it's not applicable
> > > > in the BPF case. BPF is such one and only processor.
> > > > We're not changing nor adding anything to Sys V generic parts.
> > >
> > > That was not quite what I was saying. What I started to draft is
> > > something (yes, modeled after the Sys V (g/ps)ABI) but _brand new_ for
> > > BPF. I think that is where I have been failing to communicate
> > > correctly. What I was proposing was inspired by other ABIs but
> > > completely separate and orthogonal. That is the reason for the
> > > document speaking of a BPF Machine like:
> > >
> > > ABI-conforming BPF Machine Instantiation: A physical or logical realization
> > > of a computer system capable of executing BPF programs consistently with the
> > > specifications outlined in this document.
> > >
> > > because it is a (not necessarily physical) entity that executes BPF
> > > programs (i.e. a "BPF CPU") for which we are specifying the binary
> > > compatibility. In other words, the document as it stands is proposing
> > > a gABI where
> > >
> > > the kernel's "BPF CPU" would have its own psABI
> > > ubpf's "BPF CPU" would have its own psABI
> >
> > and how would you expect that to work?
> > psABI is a compiler spec in the first place.
> > The user would use clang -O2 -target bpf_kernel vs -target bpf_ubpf ?
>
> They could use some other compiler, too.
I hit send too soon. Sorry.
To elaborate, it is my opinion that a (g/ps)ABI does more than just
specify a compiler. There are also aspects that have an impact on the
linker and the loader, among others. See, e.g., Chapter 3 Section 4 of
the x86-64 psABI describing process initialization. Or, 3.7 of the
same document describing a stack unwinding algorithm.
I think that we should write our documents with the *expectation* that
an ecosystem of tools will exist beyond the ones that exist now. That
way we won't end up in the "Perl is the only thing that can parse
Perl" conundrum. What's more, clang is even today not the only thing
that generates BPF machine code ([1], among others, I'm sure!).
[1] https://github.com/Alan-Jowett/bpf_conformance/
^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [Bpf] [PATCH v3] bpf, docs: Add additional ABI working draft base text
2023-11-10 1:35 ` Will Hawkins
@ 2023-11-10 1:35 ` Will Hawkins
0 siblings, 0 replies; 42+ messages in thread
From: Will Hawkins @ 2023-11-10 1:35 UTC (permalink / raw)
To: Alexei Starovoitov; +Cc: bpf, bpf
On Thu, Nov 9, 2023 at 7:56 PM Will Hawkins <hawkinsw@obs.cr> wrote:
>
> On Thu, Nov 9, 2023 at 1:31 PM Alexei Starovoitov
> <alexei.starovoitov@gmail.com> wrote:
> >
> > On Wed, Nov 8, 2023 at 3:57 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > >
> > > On Wed, Nov 8, 2023 at 2:51 PM Alexei Starovoitov
> > > <alexei.starovoitov@gmail.com> wrote:
> > > >
> > > > On Wed, Nov 8, 2023 at 2:13 AM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > >
> > > > > On Tue, Nov 7, 2023 at 8:17 PM Alexei Starovoitov
> > > > > <alexei.starovoitov@gmail.com> wrote:
> > > > > >
> > > > > > On Tue, Nov 7, 2023 at 11:56 AM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > > > >
> > > > > > > On Mon, Nov 6, 2023 at 3:38 AM Alexei Starovoitov
> > > > > > > <alexei.starovoitov@gmail.com> wrote:
> > > > > > > >
> > > > > > > > On Sun, Nov 5, 2023 at 4:17 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > > > > > >
> > > > > > > > > On Sun, Nov 5, 2023 at 4:51 AM Alexei Starovoitov
> > > > > > > > > <alexei.starovoitov@gmail.com> wrote:
> > > > > > > > > >
> > > > > > > > > > On Fri, Nov 3, 2023 at 2:20 PM Will Hawkins <hawkinsw@obs.cr> wrote:
> > > > > > > > > > > +
> > > > > > > > > > > +The ABI is specified in two parts: a generic part and a processor-specific part.
> > > > > > > > > > > +A pairing of generic ABI with the processor-specific ABI for a certain
> > > > > > > > > > > +instantiation of a BPF machine represents a complete binary interface for BPF
> > > > > > > > > > > +programs executing on that machine.
> > > > > > > > > > > +
> > > > > > > > > > > +This document is the generic ABI and specifies the parameters and behavior
> > > > > > > > > > > +common to all instantiations of BPF machines. In addition, it defines the
> > > > > > > > > > > +details that must be specified by each processor-specific ABI.
> > > > > > > > > > > +
> > > > > > > > > > > +These psABIs are the second part of the ABI. Each instantiation of a BPF
> > > > > > > > > > > +machine must describe the mechanism through which binary interface
> > > > > > > > > > > +compatibility is maintained with respect to the issues highlighted by this
> > > > > > > > > > > +document. However, the details that must be defined by a psABI are a minimum --
> > > > > > > > > > > +a psABI may specify additional requirements for binary interface compatibility
> > > > > > > > > > > +on a platform.
> > > > > > > > > >
> > > > > > > > > > I don't understand what you are trying to say in the above.
> > > > > > > > > > In my mind there is only one BPF psABI and it doesn't have
> > > > > > > > > > generic and processor parts. There is only one "processor".
> > > > > > > > > > BPF is such a processor.
> > > > > > > > >
> > > > > > > > > What I was trying to say was that the document here describes a
> > > > > > > > > generic ABI. In this document there will be areas that are specific to
> > > > > > > > > different implementations and those would be considered processor
> > > > > > > > > specific. In other words, the ubpf runtime could define those things
> > > > > > > > > differently than the rbpf runtime which, in turn, could define those
> > > > > > > > > things differently than the kernel's implementation.
> > > > > > > >
> > > > > > > > I see what you mean. There is only one BPF psABI. There cannot be two.
> > > > > > > > ubpf can decide not to follow it, but it could only mean that
> > > > > > > > it's non conformant and not compatible.
> > > > > > >
> > > > > > > Okay. That was not how I was structuring the ABI. I thought we had
> > > > > > > decided that, as the document said, an instantiation of a machine had
> > > > > > > to
> > > > > > >
> > > > > > > 1. meet the gABI
> > > > > > > 2. specify its requirements vis a vis the psABI
> > > > > > > 3. (optionally) describe other requirements.
> > > > > > >
> > > > > > > If that is not what we decided then we will have to restructure the document.
> > > > > >
> > > > > > This abi.rst file is the beginning of "BPF psABI" document.
> > > > > > We probably should rename it to psabi.rst to avoid confusion.
> > > > > > See my slides from IETF 118. I hope they explain what "BPF psABI" is for.
> > > > >
> > > > > Of course they do! Thank you! My only question: In the language I was
> > > > > using, I was taking a cue from the System V world where there is a
> > > > > Generic ABI and a psABI. The Generic ABI applies to all System V
> > > > > compatible systems and defines certain processor-specific details that
> > > > > each platform must specify to define a complete ABI. In particular, I
> > > > > took this language as inspiration
> > > > >
> > > > > """
> > > > > The System V ABI is composed of two basic parts: A generic part of the
> > > > > specification describes those parts of the interface that remain
> > > > > constant across all hardware implementations of System V, and a
> > > > > processor-specific part of the specification describes the parts of
> > > > > the specification that are specific to a particular processor
> > > > > architecture. Together, the generic ABI (or gABI) and the processor
> > > > > specific supplement (or psABI) provide a complete interface
> > > > > specification for compiled application programs on systems that share
> > > > > a common hardware architecture.
> > > > > """
> > > >
> > > > I see where you got the inspiration from, but it's not applicable
> > > > in the BPF case. BPF is such one and only processor.
> > > > We're not changing nor adding anything to Sys V generic parts.
> > >
> > > That was not quite what I was saying. What I started to draft is
> > > something (yes, modeled after the Sys V (g/ps)ABI) but _brand new_ for
> > > BPF. I think that is where I have been failing to communicate
> > > correctly. What I was proposing was inspired by other ABIs but
> > > completely separate and orthogonal. That is the reason for the
> > > document speaking of a BPF Machine like:
> > >
> > > ABI-conforming BPF Machine Instantiation: A physical or logical realization
> > > of a computer system capable of executing BPF programs consistently with the
> > > specifications outlined in this document.
> > >
> > > because it is a (not necessarily physical) entity that executes BPF
> > > programs (i.e. a "BPF CPU") for which we are specifying the binary
> > > compatibility. In other words, the document as it stands is proposing
> > > a gABI where
> > >
> > > the kernel's "BPF CPU" would have its own psABI
> > > ubpf's "BPF CPU" would have its own psABI
> >
> > and how would you expect that to work?
> > psABI is a compiler spec in the first place.
> > The user would use clang -O2 -target bpf_kernel vs -target bpf_ubpf ?
>
> They could use some other compiler, too.
I hit send too soon. Sorry.
To elaborate, it is my opinion that a (g/ps)ABI does more than just
specify a compiler. There are also aspects that have an impact on the
linker and the loader, among others. See, e.g., Chapter 3 Section 4 of
the x86-64 psABI describing process initialization. Or, 3.7 of the
same document describing a stack unwinding algorithm.
I think that we should write our documents with the *expectation* that
an ecosystem of tools will exist beyond the ones that exist now. That
way we won't end up in the "Perl is the only thing that can parse
Perl" conundrum. What's more, clang is even today not the only thing
that generates BPF machine code ([1], among others, I'm sure!).
[1] https://github.com/Alan-Jowett/bpf_conformance/
--
Bpf mailing list
Bpf@ietf.org
https://www.ietf.org/mailman/listinfo/bpf
^ permalink raw reply [flat|nested] 42+ messages in thread