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

Commit Message

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

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

Comments

Alexei Starovoitov April 26, 2024, 7:21 p.m. UTC | #1

On Fri, Apr 26, 2024 at 10:11 AM Dave Thaler <[e-mail]> 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.
>
> Signed-off-by: Dave Thaler <[e-mail]>
> ---
>  Documentation/bpf/standardization/instruction-set.rst | 5 +++++
>  1 file changed, 5 insertions(+)
>
> diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst
> index b44bdacd0..5592620cf 100644
> --- a/Documentation/bpf/standardization/instruction-set.rst
> +++ b/Documentation/bpf/standardization/instruction-set.rst
> @@ -469,6 +469,11 @@ 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' results in the next instruction
> +to execute being two 64-bit instructions later.

The last part is confusing.
"two 64-bit instructions later"
I'm struggling to understand that.
Maybe say that 'PC += 1' skips execution of the next insn?

Dave Thaler April 26, 2024, 7:30 p.m. UTC | #2

> -----Original Message-----
> From: Alexei Starovoitov <[e-mail]>
> Sent: Friday, April 26, 2024 12:22 PM
> To: Dave Thaler <[e-mail]>
> Cc: bpf <[e-mail]>; [e-mail]; Dave Thaler
> <[e-mail]>
> Subject: Re: [PATCH bpf-next] bpf, docs: Clarify PC use in instruction-set.rst
> 
> On Fri, Apr 26, 2024 at 10:11 AM Dave Thaler <[e-mail]>
> 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.
> >
> > Signed-off-by: Dave Thaler <[e-mail]>
> > ---
> >  Documentation/bpf/standardization/instruction-set.rst | 5 +++++
> >  1 file changed, 5 insertions(+)
> >
> > diff --git a/Documentation/bpf/standardization/instruction-set.rst
> > b/Documentation/bpf/standardization/instruction-set.rst
> > index b44bdacd0..5592620cf 100644
> > --- a/Documentation/bpf/standardization/instruction-set.rst
> > +++ b/Documentation/bpf/standardization/instruction-set.rst
> > @@ -469,6 +469,11 @@ 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' results in the next
> > +instruction to execute being two 64-bit instructions later.
> 
> The last part is confusing.
> "two 64-bit instructions later"
> I'm struggling to understand that.
> Maybe say that 'PC += 1' skips execution of the next insn?

If the next instruction is a 64-bit immediate instruction
that spans 128 bits, do you need PC += 1 or PC += 2 to skip it?
I assumed you'd need PC += 2, in which case "PC += 1" would
not skip execution of "the next instruction" but would try to jump 
into mid instruction, and fail verification.
Hence my attempt at "64-bit instruction" wording.

Alternate wording suggestions welcome.

Dave

Alexei Starovoitov April 26, 2024, 7:36 p.m. UTC | #3

On Fri, Apr 26, 2024 at 12:30 PM <[e-mail]> wrote:
>
> > -----Original Message-----
> > From: Alexei Starovoitov <[e-mail]>
> > Sent: Friday, April 26, 2024 12:22 PM
> > To: Dave Thaler <[e-mail]>
> > Cc: bpf <[e-mail]>; [e-mail]; Dave Thaler
> > <[e-mail]>
> > Subject: Re: [PATCH bpf-next] bpf, docs: Clarify PC use in instruction-set.rst
> >
> > On Fri, Apr 26, 2024 at 10:11 AM Dave Thaler <[e-mail]>
> > 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.
> > >
> > > Signed-off-by: Dave Thaler <[e-mail]>
> > > ---
> > >  Documentation/bpf/standardization/instruction-set.rst | 5 +++++
> > >  1 file changed, 5 insertions(+)
> > >
> > > diff --git a/Documentation/bpf/standardization/instruction-set.rst
> > > b/Documentation/bpf/standardization/instruction-set.rst
> > > index b44bdacd0..5592620cf 100644
> > > --- a/Documentation/bpf/standardization/instruction-set.rst
> > > +++ b/Documentation/bpf/standardization/instruction-set.rst
> > > @@ -469,6 +469,11 @@ 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' results in the next
> > > +instruction to execute being two 64-bit instructions later.
> >
> > The last part is confusing.
> > "two 64-bit instructions later"
> > I'm struggling to understand that.
> > Maybe say that 'PC += 1' skips execution of the next insn?
>
> If the next instruction is a 64-bit immediate instruction
> that spans 128 bits, do you need PC += 1 or PC += 2 to skip it?
> I assumed you'd need PC += 2, in which case "PC += 1" would
> not skip execution of "the next instruction" but would try to jump
> into mid instruction, and fail verification.

Correct.

> Hence my attempt at "64-bit instruction" wording.
>
> Alternate wording suggestions welcome.

This "jump in the middle" issue is not obvious at all from
"two 64-bit instructions" part.
Say that PC +=1 skips execution of the next insn if it's a 64-bit insn
and fails verification if the next insn is 128-bit.

Patch

diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst
index b44bdacd0..5592620cf 100644
--- a/Documentation/bpf/standardization/instruction-set.rst
+++ b/Documentation/bpf/standardization/instruction-set.rst
@@ -469,6 +469,11 @@  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' results in the next instruction
+to execute being two 64-bit instructions later.
+
 The BPF program needs to store the return value into register R0 before doing an
 ``EXIT``.