internal

Documentation

Index

• Constants
• Variables
• func Align(n, alignment int) int
• func FeatureTest(name, version string, fn FeatureTestFn) func() error
• func Identifier(str string) string
• func KernelRelease() (string, error)
• func NewBufferedSectionReader(ra io.ReaderAt, off, n int64) *bufio.Reader
• func Pin(currentPath, newPath string, fd *sys.FD) error
• func PossibleCPUs() (int, error)
• func ReadAllCompressed(file string) ([]byte, error)
• func Unpin(pinnedPath string) error
• func WriteFormatted(src []byte, out io.Writer) error
• type Deque
  • func (dq *Deque[T]) Empty() bool
  • func (dq *Deque[T]) Pop() T
  • func (dq *Deque[T]) Push(e T)
  • func (dq *Deque[T]) Shift() T
• type DiscardZeroes
  • func (DiscardZeroes) Write(p []byte) (int, error)
• type FeatureTestFn
• 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(err error, log []byte, truncated bool) *VerifierError
  • func (le *VerifierError) Error() string
  • func (le *VerifierError) Format(f fmt.State, verb rune)
  • func (le *VerifierError) Unwrap() error
• type Version
  • func KernelVersion() (Version, error)
  • 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

Examples

• VerifierError

Constants

const ClangEndian = "el"

ClangEndian is set to either "el" or "eb" depending on the host's endianness.

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 by the current kernel.

var NativeEndian binary.ByteOrder = binary.LittleEndian

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

Functions

func Align

func Align(n, alignment int) int

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

func FeatureTest

func FeatureTest(name, version string, fn FeatureTestFn) func() error

FeatureTest wraps a function so that it is run at most once.

name should identify the tested feature, while version must be in the form Major.Minor[.Patch].

Returns an error wrapping ErrNotSupported if the feature is not supported.

func Identifier

func Identifier(str string) string

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

func KernelRelease

func KernelRelease() (string, error)

KernelRelease returns the release string of the running kernel. Its format depends on the Linux distribution and corresponds to directory names in /lib/modules by convention. Some examples are 5.15.17-1-lts and 4.19.0-16-amd64.

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 Pin

func Pin(currentPath, newPath string, fd *sys.FD) error

func PossibleCPUs

func PossibleCPUs() (int, error)

PossibleCPUs returns the max number of CPUs a system may possibly have Logical CPU numbers must be of the form 0-n

func ReadAllCompressed

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

ReadAllCompressed decompresses a gzipped file into memory.

func Unpin

func Unpin(pinnedPath string) error

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]) 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]) 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 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 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 Linux mainline version required for this feature.
	// 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
	// Whether the log output is truncated, based on several heuristics.
	Truncated bool
}

VerifierError includes information from the eBPF verifier.

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

Example

err := &VerifierError{
	syscall.ENOSPC,
	[]string{"first", "second", "third"},
	false,
}

fmt.Printf("With %%s: %s\n", err)
err.Truncated = true
fmt.Printf("With %%v and a truncated log: %v\n", err)
fmt.Printf("All log lines: %+v\n", err)
fmt.Printf("First line: %+1v\n", err)
fmt.Printf("Last two lines: %-2v\n", err)

Output:

With %s: no space left on device: third (2 line(s) omitted)
With %v and a truncated log: no space left on device: second: third (truncated, 1 line(s) omitted)
All log lines: no space left on device:
	first
	second
	third
	(truncated)
First line: no space left on device:
	first
	(2 line(s) omitted)
	(truncated)
Last two lines: no space left on device:
	(1 line(s) omitted)
	second
	third
	(truncated)

func ErrorWithLog

func ErrorWithLog(err error, log []byte, truncated bool) *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 KernelVersion

func KernelVersion() (Version, error)

KernelVersion returns the version of the currently running kernel.

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.