[bpf-next,v2] bpf, docs: Clarify PC use in instruction-set.rst

Commit Message

Dave Thaler April 26, 2024, 8:18 p.m. UTC

This patch elaborates on the use of PC by expanding the PC acronym,
explaining the units, and the relative position to which the offset
applies.

v1->v2: reword per feedback from Alexei

Signed-off-by: Dave Thaler <[e-mail]>
---
 Documentation/bpf/standardization/instruction-set.rst | 6 ++++++
 1 file changed, 6 insertions(+)

Comments

David Vernet April 26, 2024, 8:58 p.m. UTC | #1

On Fri, Apr 26, 2024 at 01:18:28PM -0700, Dave Thaler wrote:
> This patch elaborates on the use of PC by expanding the PC acronym,
> explaining the units, and the relative position to which the offset
> applies.
> 
> v1->v2: reword per feedback from Alexei
> 
> Signed-off-by: Dave Thaler <[e-mail]>
> ---
>  Documentation/bpf/standardization/instruction-set.rst | 6 ++++++
>  1 file changed, 6 insertions(+)
> 
> diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst
> index b44bdacd0..766f57636 100644
> --- a/Documentation/bpf/standardization/instruction-set.rst
> +++ b/Documentation/bpf/standardization/instruction-set.rst
> @@ -469,6 +469,12 @@ JSLT      0xc    any      PC += offset if dst < src          signed
>  JSLE      0xd    any      PC += offset if dst <= src         signed
>  ========  =====  =======  =================================  ===================================================
>  
> +where 'PC' denotes the program counter, and the offset to increment by
> +is in units of 64-bit instructions relative to the instruction following
> +the jump instruction.  Thus 'PC += 1' skips execution of the next
> +instruction if it's a basic instruction and fails verification if the
> +next instruction is a 128-bit wide instruction.

Should we say "results in undefined behavior" rather than "fails
verification"? I'm not sure if we should be dictating verifier semantics
in the ISA document.

> +
>  The BPF program needs to store the return value into register R0 before doing an
>  ``EXIT``.
>  
> -- 
> 2.40.1
> 
> -- 
> Bpf mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/bpf

Patch

diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst
index b44bdacd0..766f57636 100644
--- a/Documentation/bpf/standardization/instruction-set.rst
+++ b/Documentation/bpf/standardization/instruction-set.rst
@@ -469,6 +469,12 @@  JSLT      0xc    any      PC += offset if dst < src          signed
 JSLE      0xd    any      PC += offset if dst <= src         signed
 ========  =====  =======  =================================  ===================================================
 
+where 'PC' denotes the program counter, and the offset to increment by
+is in units of 64-bit instructions relative to the instruction following
+the jump instruction.  Thus 'PC += 1' skips execution of the next
+instruction if it's a basic instruction and fails verification if the
+next instruction is a 128-bit wide instruction.
+
 The BPF program needs to store the return value into register R0 before doing an
 ``EXIT``.