Documentation
¶
Index ¶
- Constants
- Variables
- func Align(n, alignment int) int
- func Identifier(str string) string
- func KernelRelease() (string, error)
- func Memoize[T any](fn func() (T, error)) func() (T, error)
- func NewBufferedSectionReader(ra io.ReaderAt, off, n int64) *bufio.Reader
- func NewFeatureTest(name, version string, fn FeatureTestFn) func() error
- func Pin(currentPath, newPath string, fd *sys.FD) error
- func ReadAllCompressed(file string) ([]byte, error)
- func Unpin(pinnedPath string) error
- func WriteFormatted(src []byte, out io.Writer) error
- type Deque
- type DiscardZeroes
- type FeatureCache
- type FeatureMatrix
- type FeatureTest
- type FeatureTestFn
- type SafeELFFile
- type UnsupportedFeatureError
- type VerifierError
- type Version
Examples ¶
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 KernelVersion = Memoize(func() (Version, error) {
return detectKernelVersion()
})
KernelVersion returns the version of the currently running kernel.
var NativeEndian binary.ByteOrder = binary.LittleEndian
NativeEndian is set to either binary.BigEndian or binary.LittleEndian, depending on the host's endianness.
var PossibleCPUs = Memoize(func() (int, error) {
return parseCPUsFromFile("/sys/devices/system/cpu/possible")
})
PossibleCPUs returns the max number of CPUs a system may possibly have Logical CPU numbers must be of the form 0-n
Functions ¶
func Identifier ¶
Identifier turns a C style type or field name into an exportable Go equivalent.
func KernelRelease ¶
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 Memoize ¶
Memoize the result of a function call.
fn is only ever called once, even if it returns an error.
func NewBufferedSectionReader ¶
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 ReadAllCompressed ¶
ReadAllCompressed decompresses a gzipped file into memory.
Types ¶
type Deque ¶
type Deque[T any] struct { // contains filtered or unexported fields }
Deque implements a double ended queue.
func (*Deque[T]) Grow ¶
Grow the deque's capacity, if necessary, to guarantee space for another n elements.
type DiscardZeroes ¶
type DiscardZeroes struct{}
DiscardZeroes makes sure that all written bytes are zero before discarding them.
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 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 ¶
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.
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 eBPF verifier.
It summarises the log output, see Format if you want to output the full contents.
Example ¶
err := &VerifierError{
source: "catastrophe",
Cause: syscall.ENOSPC,
Log: []string{"first", "second", "third"},
Truncated: 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: catastrophe: no space left on device: third (2 line(s) omitted) With %v and a truncated log: catastrophe: no space left on device: second: third (truncated, 1 line(s) omitted) All log lines: catastrophe: no space left on device: first second third (truncated) First line: catastrophe: no space left on device: first (2 line(s) omitted) (truncated) Last two lines: catastrophe: no space left on device: (1 line(s) omitted) second third (truncated)
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 ¶
NewVersion creates a version from a string like "Major.Minor.Patch".
Patch is optional.
func NewVersionFromCode ¶
NewVersionFromCode creates a version from a LINUX_VERSION_CODE.
func (Version) Kernel ¶
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) Unspecified ¶
Unspecified returns true if the version is all zero.
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 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. |