Skip to contentSkip to conversation

bpf: Update bpf_design_QA.rst to clarify that kprobes is not ABI

PATCH Superseded Paul E. McKenney 4 participants 10 messages Jul 22, 2022 – Aug 2, 2022

Subsystems (4)

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

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

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.

---
 Documentation/bpf/bpf_design_QA.rst | 6 ++++++
 1 file changed, 6 insertions(+)
Documentation/bpf/bpf_design_QA.rst +6 -0
index 437de2a7a5de7..2ed9128cfbec8 100644
@@ -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
Signature · 1 line
2.31.1.189.g2e36527f23
#1 lore raw

PATCH 2/2 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 a given function in the kernel does not make that function become part of the Linux kernel's ABI.

---
 Documentation/bpf/bpf_design_QA.rst | 12 ++++++++++++
 1 file changed, 12 insertions(+)
Documentation/bpf/bpf_design_QA.rst +12 -0
index 2ed9128cfbec8..46337a60255e9 100644
@@ -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.
Signature · 1 line
2.31.1.189.g2e36527f23
maintainer
#2 lore raw

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

Quoted 14 lines · 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.

---
  Documentation/bpf/bpf_design_QA.rst | 12 ++++++++++++
  1 file changed, 12 insertions(+)
Documentation/bpf/bpf_design_QA.rst +0 -0
index 2ed9128cfbec8..46337a60255e9 100644

Documentation/bpf/bpf_design_QA.rst cc (congestion-control) implementations. If any of these kernel · line 283

Quoted 5 lines
Documentation/bpf/bpf_design_QA.rst +2 -0
@@ -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!

Quoted 11 lines
Documentation/bpf/bpf_design_QA.rst +10 -0
+-------------------------------------------
+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.
#3 lore raw

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

Quoted 23 lines · Daniel Borkmann
Quoted 14 lines · 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.

---
  Documentation/bpf/bpf_design_QA.rst | 12 ++++++++++++
  1 file changed, 12 insertions(+)
Documentation/bpf/bpf_design_QA.rst +0 -0
index 2ed9128cfbec8..46337a60255e9 100644

Documentation/bpf/bpf_design_QA.rst cc (congestion-control) implementations. If any of these kernel · line 283

Quoted 5 lines
Documentation/bpf/bpf_design_QA.rst +2 -0
@@ -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 [...]

Quoted 3 lines

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 <[email protected]>
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. ]

Documentation/bpf/bpf_design_QA.rst +12 -0
index 2ed9128cfbec8..a06ae8a828e3d 100644
@@ -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.
#4 lore raw

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

Quoted 11 lines · Paul E. McKenney
Quoted 3 lines · Daniel Borkmann

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).

Quoted 40 lines

The updated patch below just adds the "arbitrary".

Thanx, Paul

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

commit 89659e20d11fc1350f5881ff7c9687289806b2ba

Author: Paul E. McKenney <[email protected]>
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. ]

Documentation/bpf/bpf_design_QA.rst +12 -0
index 2ed9128cfbec8..a06ae8a828e3d 100644
@@ -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.
#5 lore raw

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

Quoted 8 lines · Matthew Wilcox
Quoted 7 lines · Paul E. McKenney
Quoted 3 lines · Daniel Borkmann

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!

Quoted 7 lines
Quoted 4 lines

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

Quoted 40 lines
Quoted 40 lines

The updated patch below just adds the "arbitrary".

Thanx, Paul

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

commit 89659e20d11fc1350f5881ff7c9687289806b2ba

Author: Paul E. McKenney <[email protected]>
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. ]

Documentation/bpf/bpf_design_QA.rst +12 -0
index 2ed9128cfbec8..a06ae8a828e3d 100644
@@ -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.
#6 lore raw

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

Quoted 15 lines · Paul E. McKenney
Quoted 13 lines · Matthew Wilcox
Quoted 11 lines · Paul E. McKenney
Quoted 3 lines · Daniel Borkmann

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?

Quoted 4 lines
Quoted 2 lines

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.

#7 lore raw

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

Quoted 19 lines · Alexei Starovoitov
Quoted 18 lines · Paul E. McKenney
Quoted 15 lines · Matthew Wilcox
Quoted 11 lines · Paul E. McKenney
Quoted 3 lines · Daniel Borkmann

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).

Quoted 6 lines
Quoted 1 line

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 <[email protected]>
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.

Documentation/bpf/bpf_design_QA.rst +7 -0
index a06ae8a828e3d..a210b8a4df005 100644
@@ -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.
#8 lore raw

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

In reply to 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.

---
 Documentation/bpf/bpf_design_QA.rst | 6 ++++++
 1 file changed, 6 insertions(+)
Documentation/bpf/bpf_design_QA.rst +6 -0
index 437de2a7a5de7..2ed9128cfbec8 100644
@@ -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
Signature · 1 line
2.31.1.189.g2e36527f23
#9 lore raw

PATCH v2 2/2 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. ]

---
 Documentation/bpf/bpf_design_QA.rst | 12 ++++++++++++
 1 file changed, 12 insertions(+)
Documentation/bpf/bpf_design_QA.rst +12 -0
index 2ed9128cfbec8..a06ae8a828e3d 100644
@@ -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.
Signature · 1 line
2.31.1.189.g2e36527f23