internal

package
v0.0.0-...-a55c778 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 6, 2024 License: MIT Imports: 23 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// Version constant used in ELF binaries indicating that the loader needs to
	// substitute the gBPF 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

View Source 
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.

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

ErrNotSupported indicates that a feature is not supported by the current kernel.

View Source 
var KernelVersion = sync.OnceValues(func() (Version, error) {
	return detectKernelVersion()
})

KernelVersion returns the version of the currently running kernel.

View Source 
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 constraints.Integer](n, alignment I) I

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

func FSType 

func FSType(path string) (int64, error)

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 constraints.Integer](n I) bool

IsPow returns true if n is a power of two.

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 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, version string, fn FeatureTestFn) func() error

NewFeatureTest is a convenient way to create a single FeatureTest.

func Pin 

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

func PlatformPrefix 

func PlatformPrefix() string

PlatformPrefix returns the platform-dependent syscall wrapper prefix used by the linux kernel.

Based on https://github.com/golang/go/blob/master/src/go/build/syslist.go and https://github.com/libbpf/libbpf/blob/master/src/libbpf.c#L10047

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 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]) 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.

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 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
	// contains filtered or unexported fields
}

VerifierError includes information from the gBPF 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, 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 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

View all Source files

Directories

Path Synopsis
cmd
gentypes
Program gentypes reads a compressed vmlinux .BTF section and generates syscall bindings from it.
 Program gentypes reads a compressed vmlinux .BTF section and generates syscall bindings from it.
Package sys contains bindings for the BPF syscall.
 Package sys contains bindings for the BPF syscall.
Package sysenc provides efficient conversion of Go values to system call interfaces.
 Package sysenc provides efficient conversion of Go values to system call interfaces.
fdtrace
Package unix re-exports Linux specific parts of golang.org/x/sys/unix.
 Package unix re-exports Linux specific parts of golang.org/x/sys/unix.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.