docs: add overview for package features

This commit adds an overview page for the concept of feature detection
in package `features`. It explains the differences of the provided API
to `bpftool`, describes the returned error semantics and highlights a
few of its limitations.

Signed-off-by: Robin Gögge <r.goegge@isovalent.com>

docs/ebpf/concepts/features.md

@@ -1,4 +1,48 @@
-!!! incomplete
-    On this page, we want to document package `features/`, a bit of its
-    background, and how it can be used. Comparison to `bpftool feature probe`
-    would be useful.
+# Feature Detection
+
+Feature detection allows applications to see which eBPF-related features are
+supported by the Linux kernel. This is useful for software that wants to be
+compatible with multiple kernel versions and lets developers tailor their code
+to use different eBPF features depending on which features are supported by the
+running kernel.
+
+## Usage
+
+In the `features` package, API calls follow a consistent pattern. The returned
+errors mean the following:
+
+- `nil` means the feature is supported.
+- {{ godoc('ErrNotSupported') }} means the feature is not supported.
+- Any other error suggests inconclusive detection, which could include false
+  negatives.
+
+For example, here's using {{ godoc('features/HaveProgramType') }}:
+
+{{ go_example('DocFeatures', title="Detect XDP program support") }}
+
+!!! note "" Feature detection results are cached to minimize overhead, except
+for inconclusive results. Multiple calls for conclusive results will be
+consistent.
+
+## Limitations
+
+For certain program types, like {{ godoc('StructOps') }}, feature probes don't
+rely on resource creation success. Instead, they use specific kernel errors,
+such as `ENOTSUPP`, to indicate the program type's presence. This approach
+doesn't support detecting available helper functions for these program types,
+as it relies on successfully loading a program that calls a specific helper.
+
+Additionally, {{ godoc('features/HaveProgramHelper') }} only confirms the
+existence of a helper. In cases where helper functionality has expanded in
+subsequent kernel releases, a custom feature probe is required to identify
+specific helper function capabilities.
+
+## Compared to `bpftool`
+
+Linux's command-line utility `bpftool` offers the `bpftool feature probe`
+subcommand for feature detection, inspiring the `features` package in {{ proj }}.
+That subcommand provides an extensive overview of eBPF-related features,
+issuing thousands of feature probes to identify kernel configuration options,
+and detect map types, program types, and helper functions. {{ proj }} aims to
+provide an equivalent set of feature probes, implemented in pure Go, to avoid a
+`bpftool` runtime dependency.

docs/examples/features_test.go

@@ -0,0 +1,28 @@
+package examples
+
+// DocFeatures {
+import (
+	"errors"
+	"fmt"
+
+	"github.com/cilium/ebpf"
+	"github.com/cilium/ebpf/features"
+)
+
+func DetectXDP() {
+	err := features.HaveProgramType(ebpf.XDP)
+	if errors.Is(err, ebpf.ErrNotSupported) {
+		// The feature detection was conclusive
+		fmt.Println("XDP program type is not available")
+		return
+	}
+	if err != nil {
+		// The feature detection was inconclusive
+		panic(err)
+	}
+
+	// The feature detection was conclusive
+	fmt.Println("XDP program type is available")
+}
+
+// }