docs: document helper function stability

Document stability guarantees of the helper functions being coupled to
the same stability guarantees of the Linux Kernel (Userspace) API.

Also document that these guarantees do not apply to KFuncs.

Signed-off-by: Silvano Cirujano Cuesta <[email protected]>

docs/linux/concepts/kfuncs.md

@@ -8,7 +8,7 @@ description: This page explains the concept of kfunc in eBPF. It explains what k
 
 KFunc also known as a kernel function is a function within the kernel that has been annotated and specifically designated as being callable from eBPF programs. KFuncs are an alternative to [helper functions](../helper-function/index.md), a new method to provide similar functionality. 
 
-Officially KFuncs are unstable, unlike helper functions, kfuncs have no UAPI guarantees. In practice this might mean that kfuncs can change or be removed between kernel versions. Though as with all features, the kernel community will try to avoid breaking changes, and will provide deprecation warnings when possible. Users of kfuncs might need to be more vigilant about changes in the kernel, and be prepared to update their programs more frequently or write more complex code to handle different kernel versions.
+Officially KFuncs are unstable, unlike [helper functions](../helper-function/index.md#stability-guarantees), kfuncs have no UAPI guarantees. In practice this might mean that kfuncs can change or be removed between kernel versions. Though as with all features, the kernel community will try to avoid breaking changes, and will provide deprecation warnings when possible. Users of kfuncs might need to be more vigilant about changes in the kernel, and be prepared to update their programs more frequently or write more complex code to handle different kernel versions.
 
 ## Usage
 

docs/linux/helper-function/index.md

@@ -9,6 +9,17 @@ Helper functions are functions defined by the kernel which can be invoked from e
 
 Helper functions can have a large variety of purposes. This page attempts to categorize them by function.
 
+## Stability guarantees
+
+Although helper functions are not to be used from userspace, but from eBPF programs, they are declared as part of the UAPI (the userspace API): [`include/uapi/linux/bpf.h`](https://github.com/torvalds/linux/blob/67784a74e258a467225f0e68335df77acd67b7ab/include/uapi/linux/bpf.h#L1828).
+
+As a consequence, helper functions enjoy the well-known stability guarantees of the Linux Kernel (userspace) API.
+Meaning that you can rely on helper functions not disappearing or changing across kernel versions.
+
+If the stability of the interaction between the eBPF program and the kernel (across different versions) is a concern, then usage of [KFuncs](../index.md#kfuncs) should be avoided whenever feasible.
+KFuncs are considered though the future API of the kernel for eBPF programs and therefore they will slowly become unavoidable.
+They can be expected to become more stable over time.
+
 ## Map helpers
 
 These are helpers with the primary purpose involves the interaction with a map.

docs/linux/index.md

@@ -28,11 +28,14 @@ These helper functions, take up to 5 arguments and return a single return value.
 
 Helper functions have a large variety of purposes ranging from simply getting some additional information like what CPU core we are executing on to invoking major side effects like redirecting packets. For a complete overview checkout the [helper functions](./helper-function/index.md) page.
 
+Helper functions are declared as part of the UAPI (the userspace API), therefore they enjoy its well-known stability guarantees.
+Check the [helper functions](./helper-function/index.md#stability-guarantees) for more details.
+
 ## KFuncs
 
 KFuncs are the kernel functions that have been annotated so that they can be called from eBPF programs. Its essentially an alternative mechanism to helper functions. The upstream kernel in principle doesn't accept new helper functions anymore, so any new functionality that needs to be exposed to eBPF programs should be done through KFuncs.
 
-KFuncs are not considered UAPI (User-space API) and are not subject to the same stability guarantees as the UAPI. Users of KFuncs are advised to use defensive programming techniques to handle the case where a KFunc is not available or has changed.
+KFuncs are not considered UAPI (User-space API) and are not subject to the same stability guarantees as the UAPI (see contrast with [helper functions](helper-function/index.md#stability-guarantees)). Users of KFuncs are advised to use defensive programming techniques to handle the case where a KFunc is not available or has changed.
 
 For more details checkout the [KFuncs](../linux/concepts/kfuncs.md) page.
 

docs/linux/kfuncs/index.md

@@ -6,6 +6,14 @@ hide: toc
 
 # KFuncs (Linux)
 
+## Stability guarantees
+
+Helper functions enjoy the stability guarantee offered by the user API, as explained in [documentation about stability guarantees of the helper functions](../helper-function/index.md#stability-guarantees).
+But KFuncs do not enjoy those same guarantees.
+
+Although KFuncs are not expected to be very volatile, still defensive programming techniques are advised.
+Otherwise helper functions should be preferred over KFuncs.
+
 ## cGroup resource statistic KFuncs
 
 These KFuncs are used to update or flush cGroup resource statistics efficiently.