github.com/cilium/ebpf@v0.15.1-0.20240517100537-8079b37aa138/docs/ebpf/concepts/features.md (about)

     1  # Feature Detection
     2  
     3  Feature detection allows applications to check which eBPF-related features are
     4  supported by the Linux kernel. This is useful for software that wants to be
     5  compatible with multiple kernel versions and lets developers tailor their code
     6  to use different eBPF features depending on what is supported by the running
     7  kernel.
     8  
     9  ## Usage
    10  
    11  In the `features` package, API calls follow a consistent pattern. The returned
    12  errors mean the following:
    13  
    14  - `nil` means the feature is supported.
    15  - {{ godoc('ErrNotSupported') }} means the feature is not supported.
    16  - Any other error suggests inconclusive detection, which could include false
    17    negatives.
    18  
    19  For example, here's using {{ godoc('features/HaveProgramType') }}:
    20  
    21  {{ go_example('DocDetectXDP', title="Detect kernel support for XDP programs") }}
    22  
    23  !!! note ""
    24      Feature detection results are cached to minimize overhead, except for
    25      inconclusive results. Subsequent calls to a conclusive probe will
    26      consistently return the same result without rerunning the probe logic.
    27  
    28  ## Limitations
    29  
    30  ### {{ godoc ('features/HaveProgramHelper') }}
    31  
    32  1. Not all combinations of program types and helpers can be probed. Conclusively
    33     probing a BPF helper means successfully loading a generated BPF program.
    34     Certain program types like `LSM`, `StructOps` and `Tracing` are difficult to
    35     generate on-the-fly, as they depend on other components or symbols being
    36     present in the kernel, making the probes fragile. Instead, for these types,
    37     we don't rely on successfully loading a program, but we look for specific
    38     kernel error responses instead, such as `ENOTSUPP`. This indicates the
    39     program type is known, but our generated program  was invalid (which is
    40     fine!).
    41  
    42  2. This function only confirms the presence of the given BPF helper in the
    43     kernel. In cases where helpers themselves gain extra features in subsequent
    44     kernel releases, you'll have to write your own feature probe to test the
    45     particular combination of helper inputs you're looking for. Feel free to look
    46     at the implementation of package `features` for inspiration.
    47  
    48  ## Compared to `bpftool`
    49  
    50  Linux's command-line utility `bpftool` offers the `bpftool feature probe`
    51  subcommand for feature detection, inspiring the `features` package in {{ proj }}.
    52  That subcommand provides an extensive overview of eBPF-related features,
    53  issuing thousands of feature probes to identify kernel configuration options,
    54  and detect map types, program types, and helper functions. {{ proj }} aims to
    55  provide an equivalent set of feature probes, implemented in pure Go, to avoid a
    56  `bpftool` runtime dependency, and to allow users to probe only the exact
    57  features they need.