features

Documentation

Overview

Package features allows probing for BPF features available to the calling process.

In general, the error return values from feature probes in this package all have the following semantics unless otherwise specified:

err == nil: The feature is available.
errors.Is(err, ebpf.ErrNotSupported): The feature is not available.
err != nil: Any errors encountered during probe execution, wrapped.

Note that the latter case may include false negatives, and that resource creation may succeed despite an error being returned. For example, some map and program types cannot reliably be probed and will return an inconclusive error.

As a rule, only `nil` and `ebpf.ErrNotSupported` are conclusive.

Probe results are cached by the library and persist throughout any changes to the process' environment, like capability changes.

Index

• Constants
• Variables
• func HaveMapFlag(flag MapFlags) (err error)
• func HaveMapType(mt ebpf.MapType) error
• func HaveProgramHelper(pt ebpf.ProgramType, helper asm.BuiltinFunc) error
• func HaveProgramType(pt ebpf.ProgramType) (err error)
• func LinuxVersionCode() (uint32, error)
• type MapFlags

Constants

const (
	BPF_F_NO_PREALLOC = sys.BPF_F_NO_PREALLOC
	BPF_F_RDONLY_PROG = sys.BPF_F_RDONLY_PROG
	BPF_F_WRONLY_PROG = sys.BPF_F_WRONLY_PROG
	BPF_F_MMAPABLE    = sys.BPF_F_MMAPABLE
	BPF_F_INNER_MAP   = sys.BPF_F_INNER_MAP
)

Flags which may be feature probed.

Variables

var HaveBoundedLoops = internal.NewFeatureTest("bounded loops", "5.3", func() error {
	return probeProgram(&ebpf.ProgramSpec{
		Type: ebpf.SocketFilter,
		Instructions: asm.Instructions{
			asm.Mov.Imm(asm.R0, 10),
			asm.Sub.Imm(asm.R0, 1).WithSymbol("loop"),
			asm.JNE.Imm(asm.R0, 0, "loop"),
			asm.Return(),
		},
	})
})

HaveBoundedLoops probes the running kernel if bounded loops are supported.

Upstream commit 2589726d12a1 ("bpf: introduce bounded loops").

See the package documentation for the meaning of the error return value.

var HaveLargeInstructions = internal.NewFeatureTest(">4096 instructions", "5.2", func() error {
	const maxInsns = 4096

	insns := make(asm.Instructions, maxInsns, maxInsns+1)
	for i := range insns {
		insns[i] = asm.Mov.Imm(asm.R0, 1)
	}
	insns = append(insns, asm.Return())

	return probeProgram(&ebpf.ProgramSpec{
		Type:         ebpf.SocketFilter,
		Instructions: insns,
	})
})

HaveLargeInstructions probes the running kernel if more than 4096 instructions per program are supported.

Upstream commit c04c0d2b968a ("bpf: increase complexity limit and maximum program size").

See the package documentation for the meaning of the error return value.

var HaveProgType = HaveProgramType

HaveProgType probes the running kernel for the availability of the specified program type.

Deprecated: use HaveProgramType() instead.

var HaveV2ISA = internal.NewFeatureTest("v2 ISA", "4.14", func() error {
	return probeProgram(&ebpf.ProgramSpec{
		Type: ebpf.SocketFilter,
		Instructions: asm.Instructions{
			asm.Mov.Imm(asm.R0, 0),
			asm.JLT.Imm(asm.R0, 0, "exit"),
			asm.Mov.Imm(asm.R0, 1),
			asm.Return().WithSymbol("exit"),
		},
	})
})

HaveV2ISA probes the running kernel if instructions of the v2 ISA are supported.

Upstream commit 92b31a9af73b ("bpf: add BPF_J{LT,LE,SLT,SLE} instructions").

See the package documentation for the meaning of the error return value.

var HaveV3ISA = internal.NewFeatureTest("v3 ISA", "5.1", func() error {
	return probeProgram(&ebpf.ProgramSpec{
		Type: ebpf.SocketFilter,
		Instructions: asm.Instructions{
			asm.Mov.Imm(asm.R0, 0),
			asm.JLT.Imm32(asm.R0, 0, "exit"),
			asm.Mov.Imm(asm.R0, 1),
			asm.Return().WithSymbol("exit"),
		},
	})
})

HaveV3ISA probes the running kernel if instructions of the v3 ISA are supported.

Upstream commit 092ed0968bb6 ("bpf: verifier support JMP32").

See the package documentation for the meaning of the error return value.

Functions

func HaveMapFlag

func HaveMapFlag(flag MapFlags) (err error)

HaveMapFlag probes the running kernel for the availability of the specified map flag.

Returns an error if flag is not one of the flags declared in this package. See the package documentation for the meaning of the error return value.

func HaveMapType

func HaveMapType(mt ebpf.MapType) error

HaveMapType probes the running kernel for the availability of the specified map type.

See the package documentation for the meaning of the error return value.

func HaveProgramHelper

func HaveProgramHelper(pt ebpf.ProgramType, helper asm.BuiltinFunc) error

HaveProgramHelper probes the running kernel for the availability of the specified helper function to a specified program type. Return values have the following semantics:

err == nil: The feature is available.
errors.Is(err, ebpf.ErrNotSupported): The feature is not available.
err != nil: Any errors encountered during probe execution, wrapped.

Note that the latter case may include false negatives, and that program creation may succeed despite an error being returned. Only `nil` and `ebpf.ErrNotSupported` are conclusive.

Probe results are cached and persist throughout any process capability changes.

func HaveProgramType

func HaveProgramType(pt ebpf.ProgramType) (err error)

HaveProgramType probes the running kernel for the availability of the specified program type.

See the package documentation for the meaning of the error return value.

func LinuxVersionCode

func LinuxVersionCode() (uint32, error)

LinuxVersionCode returns the version of the currently running kernel as defined in the LINUX_VERSION_CODE compile-time macro. It is represented in the format described by the KERNEL_VERSION macro from linux/version.h.

Do not use the version to make assumptions about the presence of certain kernel features, always prefer feature probes in this package. Some distributions backport or disable eBPF features.

Types

type MapFlags

type MapFlags = sys.MapFlags

MapFlags document which flags may be feature probed.