[PATCH bpf 1/2] bpf: Update bpf_design_QA.rst to clarify that kprobes is not ABI

[PATCH bpf 1/2] bpf: Update bpf_design_QA.rst to clarify that kprobes is not ABI

[Paul E. McKenney]

This patch updates bpf_design_QA.rst to clarify that the ability to
attach a BPF program to a given point in the kernel code via kprobes
does not make that attachment point be part of the Linux kernel's ABI.

Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
---
 Documentation/bpf/bpf_design_QA.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst
index 437de2a7a5de7..2ed9128cfbec8 100644
--- a/Documentation/bpf/bpf_design_QA.rst
+++ b/Documentation/bpf/bpf_design_QA.rst
@@ -214,6 +214,12 @@ A: NO. Tracepoints are tied to internal implementation details hence they are
 subject to change and can break with newer kernels. BPF programs need to change
 accordingly when this happens.
 
+Q: Are places where kprobes can attach part of the stable ABI?
+--------------------------------------------------------------
+A: NO. The places to which kprobes can attach are internal implementation
+details, which means that they are subject to change and can break with
+newer kernels. BPF programs need to change accordingly when this happens.
+
 Q: How much stack space a BPF program uses?
 -------------------------------------------
 A: Currently all program types are limited to 512 bytes of stack
-- 
2.31.1.189.g2e36527f23

[PATCH bpf 2/2] bpf: Update bpf_design_QA.rst to clarify that attaching to functions is not ABI

[Paul E. McKenney]

This patch updates bpf_design_QA.rst to clarify that the ability to
attach a BPF program to a given function in the kernel does not make
that function become part of the Linux kernel's ABI.

Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
---
 Documentation/bpf/bpf_design_QA.rst | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst
index 2ed9128cfbec8..46337a60255e9 100644
--- a/Documentation/bpf/bpf_design_QA.rst
+++ b/Documentation/bpf/bpf_design_QA.rst
@@ -279,3 +279,15 @@ cc (congestion-control) implementations.  If any of these kernel
 functions has changed, both the in-tree and out-of-tree kernel tcp cc
 implementations have to be changed.  The same goes for the bpf
 programs and they have to be adjusted accordingly.
+
+Q: Attaching to kernel functions is an ABI?
+-------------------------------------------
+Q: BPF programs can be attached to many kernel functions.  Do these
+kernel functions become part of the ABI?
+
+A: NO.
+
+The kernel function prototypes will change, and BPF programs attaching to
+them will need to change.  The BPF compile-once-run-everywhere (CO-RE)
+should be used in order to make it easier to adapt your BPF programs to
+different versions of the kernel.
-- 
2.31.1.189.g2e36527f23

Re: [PATCH bpf 2/2] bpf: Update bpf_design_QA.rst to clarify that attaching to functions is not ABI

[Daniel Borkmann]

On 7/22/22 8:06 PM, Paul E. McKenney wrote:
> This patch updates bpf_design_QA.rst to clarify that the ability to
> attach a BPF program to a given function in the kernel does not make
> that function become part of the Linux kernel's ABI.
> 
> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
> ---
>   Documentation/bpf/bpf_design_QA.rst | 12 ++++++++++++
>   1 file changed, 12 insertions(+)
> 
> diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst
> index 2ed9128cfbec8..46337a60255e9 100644
> --- a/Documentation/bpf/bpf_design_QA.rst
> +++ b/Documentation/bpf/bpf_design_QA.rst
> @@ -279,3 +279,15 @@ cc (congestion-control) implementations.  If any of these kernel
>   functions has changed, both the in-tree and out-of-tree kernel tcp cc
>   implementations have to be changed.  The same goes for the bpf
>   programs and they have to be adjusted accordingly.
> +
> +Q: Attaching to kernel functions is an ABI?

small nit, I'd change to: Attaching to arbitrary kernel functions [...]

Otherwise I think this could be a bit misunderstood, e.g. most of the networking
programs (e.g. XDP, tc, sock_addr) have a fixed framework around them where
attaching programs is part of ABI.

Rest looks good, thanks for writing this up, Paul!

> +-------------------------------------------
> +Q: BPF programs can be attached to many kernel functions.  Do these
> +kernel functions become part of the ABI?
> +
> +A: NO.
> +
> +The kernel function prototypes will change, and BPF programs attaching to
> +them will need to change.  The BPF compile-once-run-everywhere (CO-RE)
> +should be used in order to make it easier to adapt your BPF programs to
> +different versions of the kernel.
> 

Re: [PATCH bpf 2/2] bpf: Update bpf_design_QA.rst to clarify that attaching to functions is not ABI

[Paul E. McKenney]

On Fri, Jul 22, 2022 at 10:17:57PM +0200, Daniel Borkmann wrote:
> On 7/22/22 8:06 PM, Paul E. McKenney wrote:
> > This patch updates bpf_design_QA.rst to clarify that the ability to
> > attach a BPF program to a given function in the kernel does not make
> > that function become part of the Linux kernel's ABI.
> > 
> > Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
> > ---
> >   Documentation/bpf/bpf_design_QA.rst | 12 ++++++++++++
> >   1 file changed, 12 insertions(+)
> > 
> > diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst
> > index 2ed9128cfbec8..46337a60255e9 100644
> > --- a/Documentation/bpf/bpf_design_QA.rst
> > +++ b/Documentation/bpf/bpf_design_QA.rst
> > @@ -279,3 +279,15 @@ cc (congestion-control) implementations.  If any of these kernel
> >   functions has changed, both the in-tree and out-of-tree kernel tcp cc
> >   implementations have to be changed.  The same goes for the bpf
> >   programs and they have to be adjusted accordingly.
> > +
> > +Q: Attaching to kernel functions is an ABI?
> 
> small nit, I'd change to: Attaching to arbitrary kernel functions [...]
> 
> Otherwise I think this could be a bit misunderstood, e.g. most of the networking
> programs (e.g. XDP, tc, sock_addr) have a fixed framework around them where
> attaching programs is part of ABI.

Excellent point, thank you!

Apologies for the newbie question, but does BTF_ID() mark a function as
ABI from the viewpoing of a BPF program calling that function, attaching
to that function, or both?  Either way, is it worth mentioning this
in this QA entry?

The updated patch below just adds the "arbitrary".

							Thanx, Paul

------------------------------------------------------------------------

commit 89659e20d11fc1350f5881ff7c9687289806b2ba
Author: Paul E. McKenney <paulmck@kernel.org>
Date:   Fri Jul 22 10:52:05 2022 -0700

    bpf: Update bpf_design_QA.rst to clarify that attaching to functions is not ABI
    
    This patch updates bpf_design_QA.rst to clarify that the ability to
    attach a BPF program to an arbitrary function in the kernel does not
    make that function become part of the Linux kernel's ABI.
    
    [ paulmck: Apply Daniel Borkmann feedback. ]
    
    Signed-off-by: Paul E. McKenney <paulmck@kernel.org>

diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst
index 2ed9128cfbec8..a06ae8a828e3d 100644
--- a/Documentation/bpf/bpf_design_QA.rst
+++ b/Documentation/bpf/bpf_design_QA.rst
@@ -279,3 +279,15 @@ cc (congestion-control) implementations.  If any of these kernel
 functions has changed, both the in-tree and out-of-tree kernel tcp cc
 implementations have to be changed.  The same goes for the bpf
 programs and they have to be adjusted accordingly.
+
+Q: Attaching to arbitrary kernel functions is an ABI?
+-----------------------------------------------------
+Q: BPF programs can be attached to many kernel functions.  Do these
+kernel functions become part of the ABI?
+
+A: NO.
+
+The kernel function prototypes will change, and BPF programs attaching to
+them will need to change.  The BPF compile-once-run-everywhere (CO-RE)
+should be used in order to make it easier to adapt your BPF programs to
+different versions of the kernel.

Re: [PATCH bpf 2/2] bpf: Update bpf_design_QA.rst to clarify that attaching to functions is not ABI

[Matthew Wilcox]

On Fri, Jul 22, 2022 at 02:23:46PM -0700, Paul E. McKenney wrote:
> On Fri, Jul 22, 2022 at 10:17:57PM +0200, Daniel Borkmann wrote:
> > Otherwise I think this could be a bit misunderstood, e.g. most of the networking
> > programs (e.g. XDP, tc, sock_addr) have a fixed framework around them where
> > attaching programs is part of ABI.
> 
> Excellent point, thank you!
> 
> Apologies for the newbie question, but does BTF_ID() mark a function as
> ABI from the viewpoing of a BPF program calling that function, attaching
> to that function, or both?  Either way, is it worth mentioning this
> in this QA entry?

Not necessarily.  For example, __filemap_add_folio has a BTF_ID(), but
it is not ABI (it's error injection).

> The updated patch below just adds the "arbitrary".
> 
> 							Thanx, Paul
> 
> ------------------------------------------------------------------------
> 
> commit 89659e20d11fc1350f5881ff7c9687289806b2ba
> Author: Paul E. McKenney <paulmck@kernel.org>
> Date:   Fri Jul 22 10:52:05 2022 -0700
> 
>     bpf: Update bpf_design_QA.rst to clarify that attaching to functions is not ABI
>     
>     This patch updates bpf_design_QA.rst to clarify that the ability to
>     attach a BPF program to an arbitrary function in the kernel does not
>     make that function become part of the Linux kernel's ABI.
>     
>     [ paulmck: Apply Daniel Borkmann feedback. ]
>     
>     Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
> 
> diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst
> index 2ed9128cfbec8..a06ae8a828e3d 100644
> --- a/Documentation/bpf/bpf_design_QA.rst
> +++ b/Documentation/bpf/bpf_design_QA.rst
> @@ -279,3 +279,15 @@ cc (congestion-control) implementations.  If any of these kernel
>  functions has changed, both the in-tree and out-of-tree kernel tcp cc
>  implementations have to be changed.  The same goes for the bpf
>  programs and they have to be adjusted accordingly.
> +
> +Q: Attaching to arbitrary kernel functions is an ABI?
> +-----------------------------------------------------
> +Q: BPF programs can be attached to many kernel functions.  Do these
> +kernel functions become part of the ABI?
> +
> +A: NO.
> +
> +The kernel function prototypes will change, and BPF programs attaching to
> +them will need to change.  The BPF compile-once-run-everywhere (CO-RE)
> +should be used in order to make it easier to adapt your BPF programs to
> +different versions of the kernel.

Re: [PATCH bpf 2/2] bpf: Update bpf_design_QA.rst to clarify that attaching to functions is not ABI

[Paul E. McKenney]

On Mon, Jul 25, 2022 at 01:15:49PM +0100, Matthew Wilcox wrote:
> On Fri, Jul 22, 2022 at 02:23:46PM -0700, Paul E. McKenney wrote:
> > On Fri, Jul 22, 2022 at 10:17:57PM +0200, Daniel Borkmann wrote:
> > > Otherwise I think this could be a bit misunderstood, e.g. most of the networking
> > > programs (e.g. XDP, tc, sock_addr) have a fixed framework around them where
> > > attaching programs is part of ABI.
> > 
> > Excellent point, thank you!
> > 
> > Apologies for the newbie question, but does BTF_ID() mark a function as
> > ABI from the viewpoing of a BPF program calling that function, attaching
> > to that function, or both?  Either way, is it worth mentioning this
> > in this QA entry?
> 
> Not necessarily.  For example, __filemap_add_folio has a BTF_ID(), but
> it is not ABI (it's error injection).

OK, sounds like something to leave out of the QA, then.

							Thanx, Paul

> > The updated patch below just adds the "arbitrary".
> > 
> > 							Thanx, Paul
> > 
> > ------------------------------------------------------------------------
> > 
> > commit 89659e20d11fc1350f5881ff7c9687289806b2ba
> > Author: Paul E. McKenney <paulmck@kernel.org>
> > Date:   Fri Jul 22 10:52:05 2022 -0700
> > 
> >     bpf: Update bpf_design_QA.rst to clarify that attaching to functions is not ABI
> >     
> >     This patch updates bpf_design_QA.rst to clarify that the ability to
> >     attach a BPF program to an arbitrary function in the kernel does not
> >     make that function become part of the Linux kernel's ABI.
> >     
> >     [ paulmck: Apply Daniel Borkmann feedback. ]
> >     
> >     Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
> > 
> > diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst
> > index 2ed9128cfbec8..a06ae8a828e3d 100644
> > --- a/Documentation/bpf/bpf_design_QA.rst
> > +++ b/Documentation/bpf/bpf_design_QA.rst
> > @@ -279,3 +279,15 @@ cc (congestion-control) implementations.  If any of these kernel
> >  functions has changed, both the in-tree and out-of-tree kernel tcp cc
> >  implementations have to be changed.  The same goes for the bpf
> >  programs and they have to be adjusted accordingly.
> > +
> > +Q: Attaching to arbitrary kernel functions is an ABI?
> > +-----------------------------------------------------
> > +Q: BPF programs can be attached to many kernel functions.  Do these
> > +kernel functions become part of the ABI?
> > +
> > +A: NO.
> > +
> > +The kernel function prototypes will change, and BPF programs attaching to
> > +them will need to change.  The BPF compile-once-run-everywhere (CO-RE)
> > +should be used in order to make it easier to adapt your BPF programs to
> > +different versions of the kernel.

[PATCH v2 bpf 1/2] bpf: Update bpf_design_QA.rst to clarify that kprobes is not ABI

[Paul E. McKenney]

This patch updates bpf_design_QA.rst to clarify that the ability to
attach a BPF program to a given point in the kernel code via kprobes
does not make that attachment point be part of the Linux kernel's ABI.

Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
---
 Documentation/bpf/bpf_design_QA.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst
index 437de2a7a5de7..2ed9128cfbec8 100644
--- a/Documentation/bpf/bpf_design_QA.rst
+++ b/Documentation/bpf/bpf_design_QA.rst
@@ -214,6 +214,12 @@ A: NO. Tracepoints are tied to internal implementation details hence they are
 subject to change and can break with newer kernels. BPF programs need to change
 accordingly when this happens.
 
+Q: Are places where kprobes can attach part of the stable ABI?
+--------------------------------------------------------------
+A: NO. The places to which kprobes can attach are internal implementation
+details, which means that they are subject to change and can break with
+newer kernels. BPF programs need to change accordingly when this happens.
+
 Q: How much stack space a BPF program uses?
 -------------------------------------------
 A: Currently all program types are limited to 512 bytes of stack
-- 
2.31.1.189.g2e36527f23

[PATCH v2 bpf 2/2] bpf: Update bpf_design_QA.rst to clarify that attaching to functions is not ABI

[Paul E. McKenney]

This patch updates bpf_design_QA.rst to clarify that the ability to
attach a BPF program to an arbitrary function in the kernel does not
make that function become part of the Linux kernel's ABI.

[ paulmck: Apply Daniel Borkmann feedback. ]

Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
---
 Documentation/bpf/bpf_design_QA.rst | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst
index 2ed9128cfbec8..a06ae8a828e3d 100644
--- a/Documentation/bpf/bpf_design_QA.rst
+++ b/Documentation/bpf/bpf_design_QA.rst
@@ -279,3 +279,15 @@ cc (congestion-control) implementations.  If any of these kernel
 functions has changed, both the in-tree and out-of-tree kernel tcp cc
 implementations have to be changed.  The same goes for the bpf
 programs and they have to be adjusted accordingly.
+
+Q: Attaching to arbitrary kernel functions is an ABI?
+-----------------------------------------------------
+Q: BPF programs can be attached to many kernel functions.  Do these
+kernel functions become part of the ABI?
+
+A: NO.
+
+The kernel function prototypes will change, and BPF programs attaching to
+them will need to change.  The BPF compile-once-run-everywhere (CO-RE)
+should be used in order to make it easier to adapt your BPF programs to
+different versions of the kernel.
-- 
2.31.1.189.g2e36527f23

Re: [PATCH bpf 2/2] bpf: Update bpf_design_QA.rst to clarify that attaching to functions is not ABI

[Alexei Starovoitov]

On Mon, Jul 25, 2022 at 9:40 AM Paul E. McKenney <paulmck@kernel.org> wrote:
>
> On Mon, Jul 25, 2022 at 01:15:49PM +0100, Matthew Wilcox wrote:
> > On Fri, Jul 22, 2022 at 02:23:46PM -0700, Paul E. McKenney wrote:
> > > On Fri, Jul 22, 2022 at 10:17:57PM +0200, Daniel Borkmann wrote:
> > > > Otherwise I think this could be a bit misunderstood, e.g. most of the networking
> > > > programs (e.g. XDP, tc, sock_addr) have a fixed framework around them where
> > > > attaching programs is part of ABI.
> > >
> > > Excellent point, thank you!
> > >
> > > Apologies for the newbie question, but does BTF_ID() mark a function as
> > > ABI from the viewpoing of a BPF program calling that function, attaching
> > > to that function, or both?  Either way, is it worth mentioning this
> > > in this QA entry?
> >
> > Not necessarily.  For example, __filemap_add_folio has a BTF_ID(), but
> > it is not ABI (it's error injection).
>
> OK, sounds like something to leave out of the QA, then.

Obviously, BTF_ID marking doesn't make the kernel function an abi
in any way. Just like EXPORT_SYMBOL_GPL doesn't do it.
Documentation/bpf/kfuncs.rst already explains it.
Probably worth repeating in the QA part of the doc.

Re: [PATCH bpf 2/2] bpf: Update bpf_design_QA.rst to clarify that attaching to functions is not ABI

[Paul E. McKenney]

On Mon, Aug 01, 2022 at 10:34:16PM -0700, Alexei Starovoitov wrote:
> On Mon, Jul 25, 2022 at 9:40 AM Paul E. McKenney <paulmck@kernel.org> wrote:
> >
> > On Mon, Jul 25, 2022 at 01:15:49PM +0100, Matthew Wilcox wrote:
> > > On Fri, Jul 22, 2022 at 02:23:46PM -0700, Paul E. McKenney wrote:
> > > > On Fri, Jul 22, 2022 at 10:17:57PM +0200, Daniel Borkmann wrote:
> > > > > Otherwise I think this could be a bit misunderstood, e.g. most of the networking
> > > > > programs (e.g. XDP, tc, sock_addr) have a fixed framework around them where
> > > > > attaching programs is part of ABI.
> > > >
> > > > Excellent point, thank you!
> > > >
> > > > Apologies for the newbie question, but does BTF_ID() mark a function as
> > > > ABI from the viewpoing of a BPF program calling that function, attaching
> > > > to that function, or both?  Either way, is it worth mentioning this
> > > > in this QA entry?
> > >
> > > Not necessarily.  For example, __filemap_add_folio has a BTF_ID(), but
> > > it is not ABI (it's error injection).
> >
> > OK, sounds like something to leave out of the QA, then.
> 
> Obviously, BTF_ID marking doesn't make the kernel function an abi
> in any way. Just like EXPORT_SYMBOL_GPL doesn't do it.
> Documentation/bpf/kfuncs.rst already explains it.
> Probably worth repeating in the QA part of the doc.

Like this?

							Thanx, Paul

------------------------------------------------------------------------

commit 9346b452b92fc520a59da655b55d6bc40f9d1d14
Author: Paul E. McKenney <paulmck@kernel.org>
Date:   Tue Aug 2 10:31:17 2022 -0700

    bpf: Update bpf_design_QA.rst to clarify that BTF_ID does not ABIify a function
    
    This patch updates bpf_design_QA.rst to clarify that mentioning a function
    to the BTF_ID macro does not make that function become part of the Linux
    kernel's ABI.
    
    Suggested-by: Alexei Starovoitov <alexei.starovoitov@gmail.com>
    Signed-off-by: Paul E. McKenney <paulmck@kernel.org>

diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst
index a06ae8a828e3d..a210b8a4df005 100644
--- a/Documentation/bpf/bpf_design_QA.rst
+++ b/Documentation/bpf/bpf_design_QA.rst
@@ -291,3 +291,10 @@ The kernel function prototypes will change, and BPF programs attaching to
 them will need to change.  The BPF compile-once-run-everywhere (CO-RE)
 should be used in order to make it easier to adapt your BPF programs to
 different versions of the kernel.
+
+Q: Marking a function with BTF_ID makes that function an ABI?
+-------------------------------------------------------------
+A: NO.
+
+The BTF_ID macro does not cause a function to become part of the ABI
+any more than does the EXPORT_SYMBOL_GPL macro.