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

Commit Message

Dave Thaler April 26, 2024, 11:11 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

v2->v3: reword per feedback from David Vernet

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

Comments

David Vernet April 28, 2024, 10:01 p.m. UTC | #1

On Fri, Apr 26, 2024 at 04:11:26PM -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
> 
> v2->v3: reword per feedback from David Vernet
> 
> Signed-off-by: Dave Thaler <[e-mail]>

Reviewed-by: David Vernet <[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..997560aba 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 or results in undefined behavior
> +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``.
>  
> -- 
> 2.40.1
> 
> -- 
> Bpf mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/bpf

[e-mail] April 29, 2024, 10 a.m. UTC | #2

Hello:

This patch was applied to bpf/bpf-next.git (master)
by Daniel Borkmann <[e-mail]>:

On Fri, 26 Apr 2024 16:11:26 -0700 you 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
> 
> v2->v3: reword per feedback from David Vernet
> 
> [...]

Here is the summary with links:
  - [bpf-next,v3] bpf, docs: Clarify PC use in instruction-set.rst
    https://git.kernel.org/bpf/bpf-next/c/07801a24e2f1

You are awesome, thank you!

Patch

diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst
index b44bdacd0..997560aba 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 or results in undefined behavior
+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``.