package internal

import "github.com/cilium/ebpf/internal"

Index ¶

• Constants
• Variables
• func Align[I Integer](n, alignment I) I
• func Between[I Integer](val, a, b I) I
• func GoTypeName(t any) string
• func Identifier(str string) string
• func IsPow[I Integer](n I) bool
• func NewBuffer(buf []byte) *bytes.Buffer
• func NewBufferedSectionReader(ra io.ReaderAt, off, n int64) *bufio.Reader
• func NewFeatureTest(name string, fn FeatureTestFn, versions ...string) func() error
• func PutBuffer(buf *bytes.Buffer)
• func ReadAllCompressed(file string) ([]byte, error)
• func ReadUint64FromFile(format string, path ...string) (uint64, error)
• func ReadUint64FromFileOnce(format string, path ...string) (uint64, error)
• func WriteFormatted(src []byte, out io.Writer) error
• type Deque
• func (dq *Deque[T]) Empty() bool
• func (dq *Deque[T]) Grow(n int)
• func (dq *Deque[T]) Pop() T
• func (dq *Deque[T]) Push(e T)
• func (dq *Deque[T]) Reset()
• func (dq *Deque[T]) Shift() T
• type DiscardZeroes
• func (DiscardZeroes) Write(p []byte) (int, error)
• type FeatureCache
• func NewFeatureCache[K comparable](newTest func(K) *FeatureTest) *FeatureCache[K]
• func (fc *FeatureCache[K]) Result(key K) error
• type FeatureMatrix
• func (fm FeatureMatrix[K]) Result(key K) error
• type FeatureTest
• type FeatureTestFn
• type Integer
• type SafeELFFile
• func NewSafeELFFile(r io.ReaderAt) (safe *SafeELFFile, err error)
• func OpenSafeELFFile(path string) (safe *SafeELFFile, err error)
• func (se *SafeELFFile) DynamicSymbols() (syms []elf.Symbol, err error)
• func (se *SafeELFFile) SectionsByType(typ elf.SectionType) []*elf.Section
• func (se *SafeELFFile) Symbols() (syms []elf.Symbol, err error)
• type UnsupportedFeatureError
• func (ufe *UnsupportedFeatureError) Error() string
• func (ufe *UnsupportedFeatureError) Is(target error) bool
• type VerifierError
• func ErrorWithLog(source string, err error, log []byte) *VerifierError
• func (le *VerifierError) Error() string
• func (le *VerifierError) Format(f fmt.State, verb rune)
• func (le *VerifierError) Unwrap() error
• type Version
• func NewVersion(ver string) (Version, error)
• func NewVersionFromCode(code uint32) Version
• func (v Version) Kernel() uint32
• func (v Version) Less(other Version) bool
• func (v Version) String() string
• func (v Version) Unspecified() bool

Constants ¶

const (
	// Version constant used in ELF binaries indicating that the loader needs to
	// substitute the eBPF program's version with the value of the kernel's
	// KERNEL_VERSION compile-time macro. Used for compatibility with BCC, gobpf
	// and RedSift.
	MagicKernelVersion = 0xFFFFFFFE
)

Variables ¶

var EmptyBPFContext = make([]byte, 15)

EmptyBPFContext is the smallest-possible BPF input context to be used for invoking `Program.{Run,Benchmark,Test}`.

Programs require a context input buffer of at least 15 bytes. Looking in net/bpf/test_run.c, bpf_test_init() requires that the input is at least ETH_HLEN (14) bytes. As of Linux commit fd18942 ("bpf: Don't redirect packets with invalid pkt_len"), it also requires the skb to be non-empty after removing the Layer 2 header.

var ErrNotSupported = errors.New("not supported")

ErrNotSupported indicates that a feature is not supported.

var ErrNotSupportedOnOS = fmt.Errorf("%w on %s", ErrNotSupported, runtime.GOOS)

ErrNotSupportedOnOS indicates that a feature is not supported on the current operating system.

var NativeEndian = binary.LittleEndian

NativeEndian is set to either binary.BigEndian or binary.LittleEndian, depending on the host's endianness.

Functions ¶

func Align ¶

func Align[I Integer](n, alignment I) I

Align returns 'n' updated to 'alignment' boundary.

func Between ¶

func Between[I Integer](val, a, b I) I

Between returns the value clamped between a and b.

func GoTypeName ¶

func GoTypeName(t any) string

GoTypeName is like %T, but elides the package name.

Pointers to a type are peeled off.

func Identifier ¶

func Identifier(str string) string

Identifier turns a C style type or field name into an exportable Go equivalent.

func IsPow ¶

func IsPow[I Integer](n I) bool

IsPow returns true if n is a power of two.

func NewBuffer ¶

func NewBuffer(buf []byte) *bytes.Buffer

NewBuffer retrieves a bytes.Buffer from a pool an re-initialises it.

The returned buffer should be passed to PutBuffer.

func NewBufferedSectionReader ¶

func NewBufferedSectionReader(ra io.ReaderAt, off, n int64) *bufio.Reader

NewBufferedSectionReader wraps an io.ReaderAt in an appropriately-sized buffered reader. It is a convenience function for reading subsections of ELF sections while minimizing the amount of read() syscalls made.

Syscall overhead is non-negligible in continuous integration context where ELFs might be accessed over virtual filesystems with poor random access performance. Buffering reads makes sense because (sub)sections end up being read completely anyway.

Use instead of the r.Seek() + io.LimitReader() pattern.

func NewFeatureTest ¶

func NewFeatureTest(name string, fn FeatureTestFn, versions ...string) func() error

NewFeatureTest is a convenient way to create a single FeatureTest.

versions specifies in which version of a BPF runtime a feature appeared. The format is "GOOS:Major.Minor[.Patch]". GOOS may be omitted when targeting Linux. Returns ErrNotSupportedOnOS if there is no version specified for the current OS.

func PutBuffer ¶

func PutBuffer(buf *bytes.Buffer)

PutBuffer releases a buffer to the pool.

func ReadAllCompressed ¶

func ReadAllCompressed(file string) ([]byte, error)

ReadAllCompressed decompresses a gzipped file into memory.

func ReadUint64FromFile ¶

func ReadUint64FromFile(format string, path ...string) (uint64, error)

ReadUint64FromFile reads a uint64 from a file.

format specifies the contents of the file in fmt.Scanf syntax.

func ReadUint64FromFileOnce ¶

func ReadUint64FromFileOnce(format string, path ...string) (uint64, error)

ReadUint64FromFileOnce is like readUint64FromFile but memoizes the result.

func WriteFormatted ¶

func WriteFormatted(src []byte, out io.Writer) error

WriteFormatted outputs a formatted src into out.

If formatting fails it returns an informative error message.

Types ¶

type Deque ¶

type Deque[T any] struct {
	// contains filtered or unexported fields
}

Deque implements a double ended queue.

func (*Deque[T]) Empty ¶

func (dq *Deque[T]) Empty() bool

func (*Deque[T]) Grow ¶

func (dq *Deque[T]) Grow(n int)

Grow the deque's capacity, if necessary, to guarantee space for another n elements.

func (*Deque[T]) Pop ¶

func (dq *Deque[T]) Pop() T

Pop returns the last element or the zero value.

func (*Deque[T]) Push ¶

func (dq *Deque[T]) Push(e T)

Push adds an element to the end.

func (*Deque[T]) Reset ¶

func (dq *Deque[T]) Reset()

Reset clears the contents of the deque while retaining the backing buffer.

func (*Deque[T]) Shift ¶

func (dq *Deque[T]) Shift() T

Shift returns the first element or the zero value.

type DiscardZeroes ¶

type DiscardZeroes struct{}

DiscardZeroes makes sure that all written bytes are zero before discarding them.

func (DiscardZeroes) Write ¶

func (DiscardZeroes) Write(p []byte) (int, error)

type FeatureCache ¶

type FeatureCache[K comparable] struct {
	// contains filtered or unexported fields
}

FeatureCache caches a potentially unlimited number of feature probes.

Useful when there is a high cardinality for a feature test.

func NewFeatureCache ¶

func NewFeatureCache[K comparable](newTest func(K) *FeatureTest) *FeatureCache[K]

func (*FeatureCache[K]) Result ¶

func (fc *FeatureCache[K]) Result(key K) error

type FeatureMatrix ¶

type FeatureMatrix[K comparable] map[K]*FeatureTest

FeatureMatrix groups multiple related feature tests into a map.

Useful when there is a small number of discrete features which are known at compile time.

It must not be modified concurrently with calling FeatureMatrix.Result.

func (FeatureMatrix[K]) Result ¶

func (fm FeatureMatrix[K]) Result(key K) error

Result returns the outcome of the feature test for the given key.

It's safe to call this function concurrently.

Always returns ErrNotSupportedOnOS on Windows.

type FeatureTest ¶

type FeatureTest struct {
	// The name of the feature being detected.
	Name string
	// Version in the form Major.Minor[.Patch].
	Version string
	// The feature test itself.
	Fn FeatureTestFn
	// contains filtered or unexported fields
}

FeatureTest caches the result of a FeatureTestFn.

Fields should not be modified after creation.

type FeatureTestFn ¶

type FeatureTestFn func() error

FeatureTestFn is used to determine whether the kernel supports a certain feature.

The return values have the following semantics:

err == ErrNotSupported: the feature is not available
err == nil: the feature is available
err != nil: the test couldn't be executed

type Integer ¶

type Integer interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr
}

Integer represents all possible integer types. Remove when x/exp/constraints is moved to the standard library.

type SafeELFFile ¶

type SafeELFFile struct {
	*elf.File
}

func NewSafeELFFile ¶

func NewSafeELFFile(r io.ReaderAt) (safe *SafeELFFile, err error)

NewSafeELFFile reads an ELF safely.

Any panic during parsing is turned into an error. This is necessary since there are a bunch of unfixed bugs in debug/elf.

https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+debug%2Felf+in%3Atitle

func OpenSafeELFFile ¶

func OpenSafeELFFile(path string) (safe *SafeELFFile, err error)

OpenSafeELFFile reads an ELF from a file.

It works like NewSafeELFFile, with the exception that safe.Close will close the underlying file.

func (*SafeELFFile) DynamicSymbols ¶

func (se *SafeELFFile) DynamicSymbols() (syms []elf.Symbol, err error)

DynamicSymbols is the safe version of elf.File.DynamicSymbols.

func (*SafeELFFile) SectionsByType ¶

func (se *SafeELFFile) SectionsByType(typ elf.SectionType) []*elf.Section

SectionsByType returns all sections in the file with the specified section type.

func (*SafeELFFile) Symbols ¶

func (se *SafeELFFile) Symbols() (syms []elf.Symbol, err error)

Symbols is the safe version of elf.File.Symbols.

type UnsupportedFeatureError ¶

type UnsupportedFeatureError struct {
	// The minimum version required for this feature.
	//
	// On Linux this refers to the mainline kernel version, on other platforms
	// to the version of the runtime.
	//
	// Used for the error string, and for sanity checking during testing.
	MinimumVersion Version

	// The name of the feature that isn't supported.
	Name string
}

UnsupportedFeatureError is returned by FeatureTest() functions.

func (*UnsupportedFeatureError) Error ¶

func (ufe *UnsupportedFeatureError) Error() string

func (*UnsupportedFeatureError) Is ¶

func (ufe *UnsupportedFeatureError) Is(target error) bool

Is indicates that UnsupportedFeatureError is ErrNotSupported.

type VerifierError ¶

type VerifierError struct {

	// The error which caused this error.
	Cause error
	// The verifier output split into lines.
	Log []string
	// contains filtered or unexported fields
}

VerifierError includes information from the eBPF verifier.

It summarises the log output, see Format if you want to output the full contents.

func ErrorWithLog ¶

func ErrorWithLog(source string, err error, log []byte) *VerifierError

ErrorWithLog wraps err in a VerifierError that includes the parsed verifier log buffer.

The default error output is a summary of the full log. The latter can be accessed via VerifierError.Log or by formatting the error, see Format.

func (*VerifierError) Error ¶

func (le *VerifierError) Error() string

func (*VerifierError) Format ¶

func (le *VerifierError) Format(f fmt.State, verb rune)

Format the error.

Understood verbs are %s and %v, which are equivalent to calling Error(). %v allows outputting additional information using the following flags:

%+<width>v: Output the first <width> lines, or all lines if no width is given.
%-<width>v: Output the last <width> lines, or all lines if no width is given.

Use width to specify how many lines to output. Use the '-' flag to output lines from the end of the log instead of the beginning.

func (*VerifierError) Unwrap ¶

func (le *VerifierError) Unwrap() error

type Version ¶

type Version [3]uint16

A Version in the form Major.Minor.Patch.

func NewVersion ¶

func NewVersion(ver string) (Version, error)

NewVersion creates a version from a string like "Major.Minor.Patch".

Patch is optional.

func NewVersionFromCode ¶

func NewVersionFromCode(code uint32) Version

NewVersionFromCode creates a version from a LINUX_VERSION_CODE.

func (Version) Kernel ¶

func (v Version) Kernel() uint32

Kernel implements the kernel's KERNEL_VERSION macro from linux/version.h. It represents the kernel version and patch level as a single value.

func (Version) Less ¶

func (v Version) Less(other Version) bool

Less returns true if the version is less than another version.

func (Version) String ¶

func (v Version) String() string

func (Version) Unspecified ¶

func (v Version) Unspecified() bool

Unspecified returns true if the version is all zero.

Source Files ¶

buffer.go deque.go elf.go endian_le.go errors.go feature.go io.go math.go output.go prog.go version.go

Directories ¶