package ebpf // import "github.com/newtools/ebpf"

Package ebpf is a toolkit for working with eBPF programs.

eBPF programs are small snippets of code which are executed directly in a VM
in the Linux kernel, which makes them very fast and flexible. Many Linux
subsystems now accept eBPF programs. This makes it possible to implement
highly application specific logic inside the kernel, without having to
modify the actual kernel itself.

Since eBPF is a relatively young concept, documentation and user space
support is still lacking. Most of the available tools are written in C, and
reside in the kernel's source tree. The more mature external projects like
libbcc focus on using eBPF for instrumentation and debugging. This leads to
certain trade-offs which are not acceptable when writing production
services.

This package is instead designed for long-running processes which want to
use eBPF to implement part of their application logic. It has no run-time
dependencies outside of the library and the Linux kernel itself. eBPF code
should be compiled ahead of time using clang, and shipped with your
application as any other resource.

The two main parts are an ELF loader, which reads object files emitted by
clang, and facilities to modify and load eBPF programs into the kernel.

This package doesn't include code required to attach eBPF to Linux
subsystems, since this varies per subsystem. See the examples for possible
solutions.

FUNCTIONS

func SanitizeName(name string, replacement rune) string
    SanitizeName replaces all invalid characters in name.

    Use this to automatically generate valid names for maps and programs at run
    time.

    Passing a negative value for replacement will delete characters instead of
    replacing them.


TYPES

type Map struct {
	// Has unexported fields.
}
    Map represents a Map file descriptor.

    Methods which take interface{} arguments by default encode them using
    binary.Read/Write in the machine's native endianness.

    Implement Marshaler on the arguments if you need custom encoding.

func LoadPinnedMap(fileName string) (*Map, error)
    LoadPinnedMap load a Map from a BPF file.

    Requires at least Linux 4.13, and is not compatible with nested maps. Use
    LoadPinnedMapExplicit in these situations.

func LoadPinnedMapExplicit(fileName string, abi *MapABI) (*Map, error)
    LoadPinnedMapExplicit loads a map with explicit parameters.

func NewMap(spec *MapSpec) (*Map, error)
    NewMap creates a new Map.

    Creating a map for the first time will perform feature detection by creating
    small, temporary maps.

func (m *Map) ABI() MapABI
    ABI gets the ABI of the Map

func (m *Map) Clone() (*Map, error)
    Clone creates a duplicate of the Map.

    Closing the duplicate does not affect the original, and vice versa. Changes
    made to the map are reflected by both instances however.

    Cloning a nil Map returns nil.

func (m *Map) Close() error
    Close removes a Map

func (m *Map) Create(key, value interface{}) error
    Create creates a new value in a map, failing if the key exists already

func (m *Map) Delete(key interface{}) error
    Delete removes a value.

    Use DeleteStrict if you desire an error if key does not exist.

func (m *Map) DeleteStrict(key interface{}) error
    DeleteStrict removes a key and returns an error if the key doesn't exist.

func (m *Map) FD() int
    FD gets the raw fd value of Map

func (m *Map) Get(key, valueOut interface{}) (bool, error)
    Get retrieves a value from a Map.

    Calls Close() on valueOut if it is of type **Map or **Program, and *valueOut
    is not nil.

func (m *Map) GetBytes(key interface{}) ([]byte, error)
    GetBytes gets a value from Map

func (m *Map) Iterate() *MapIterator
    Iterate traverses a map.

    It's safe to create multiple iterators at the same time.

    It's not possible to guarantee that all keys in a map will be returned if
    there are concurrent modifications to the map.

func (m *Map) MarshalBinary() ([]byte, error)
    MarshalBinary implements BinaryMarshaler.

func (m *Map) NextKey(key, nextKeyOut interface{}) (bool, error)
    NextKey finds the key following an initial key.

    See NextKeyBytes for details.

func (m *Map) NextKeyBytes(key interface{}) ([]byte, error)
    NextKeyBytes returns the key following an initial key as a byte slice.

    Passing nil will return the first key.

    Use Iterate if you want to traverse all entries in the map.

func (m *Map) Pin(fileName string) error
    Pin persists the map past the lifetime of the process that created it.

    This requires bpffs to be mounted above fileName. See
    http://cilium.readthedocs.io/en/doc-1.0/kubernetes/install/#mounting-the-bpf-fs-optional

func (m *Map) Put(key, value interface{}) error
    Put replaces or creates a value in map

func (m *Map) Replace(key, value interface{}) error
    Replace replaces a value in a map, failing if the value did not exist

func (m *Map) String() string
type MapABI struct {
	Type       MapType
	KeySize    uint32
	ValueSize  uint32
	MaxEntries uint32
	InnerMap   *MapABI
}
    MapABI describes a Map.

    Members which have the zero value of their type are not checked.

func (abi *MapABI) Check(m *Map) error
    Check verifies that a Map conforms to the ABI.

type MapIterator struct {
	// Has unexported fields.
}
    MapIterator iterates a Map.

    See Map.Iterate.

func (mi *MapIterator) Err() error
    Err returns any encountered error.

    The method must be called after Next returns nil.

func (mi *MapIterator) Next(keyOut, valueOut interface{}) bool
    Next decodes the next key and value.

    Returns false if there are no more entries.

    See Map.Get for further caveats around valueOut.

type MapSpec struct {
	// Name is passed to the kernel as a debug aid. Must only contain
	// alpha numeric and '_' characters.
	Name       string
	Type       MapType
	KeySize    uint32
	ValueSize  uint32
	MaxEntries uint32
	Flags      uint32
	// InnerMap is used as a template for ArrayOfMaps and HashOfMaps
	InnerMap *MapSpec
}
    MapSpec defines a Map.

func (ms *MapSpec) Copy() *MapSpec
    Copy returns a copy of the spec.

func (ms *MapSpec) String() string
type MapType uint32
    MapType indicates the type map structure that will be initialized in the
    kernel.

const (
	UnspecifiedMap MapType = iota
	// Hash is a hash map
	Hash
	// Array is an array map
	Array
	// ProgramArray - A program array map is a special kind of array map whose map
	// values contain only file descriptors referring to other eBPF
	// programs.  Thus, both the key_size and value_size must be
	// exactly four bytes.  This map is used in conjunction with the
	// TailCall helper.
	ProgramArray
	// PerfEventArray - A perf event array is used in conjunction with PerfEventRead
	// and PerfEventOutput calls, to read the raw bpf_perf_data from the registers.
	PerfEventArray
	// PerCPUHash - This data structure is useful for people who have high performance
	// network needs and can reconcile adds at the end of some cycle, so that
	// hashes can be lock free without the use of XAdd, which can be costly.
	PerCPUHash
	// PerCPUArray - This data structure is useful for people who have high performance
	// network needs and can reconcile adds at the end of some cycle, so that
	// hashes can be lock free without the use of XAdd, which can be costly.
	// Each CPU gets a copy of this hash, the contents of all of which can be reconciled
	// later.
	PerCPUArray
	// StackTrace - This holds whole user and kernel stack traces, it can be retrieved with
	// GetStackID
	StackTrace
	// CGroupArray - This is a very niche structure used to help SKBInCGroup determine
	// if an skb is from a socket belonging to a specific cgroup
	CGroupArray
	// LRUHash - This allows you to create a small hash structure that will purge the
	// least recently used items rather than thow an error when you run out of memory
	LRUHash
	// LRUCPUHash - This is NOT like PerCPUHash, this structure is shared among the CPUs,
	// it has more to do with including the CPU id with the LRU calculation so that if a
	// particular CPU is using a value over-and-over again, then it will be saved, but if
	// a value is being retrieved a lot but sparsely across CPUs it is not as important, basically
	// giving weight to CPU locality over overall usage.
	LRUCPUHash
	// LPMTrie - This is an implementation of Longest-Prefix-Match Trie structure. It is useful,
	// for storing things like IP addresses which can be bit masked allowing for keys of differing
	// values to refer to the same reference based on their masks. See wikipedia for more details.
	LPMTrie
	// ArrayOfMaps - Each item in the array is another map. The inner map mustn't be a map of maps
	// itself.
	ArrayOfMaps
	// HashOfMaps - Each item in the hash map is another map. The inner map mustn't be a map of maps
	// itself.
	HashOfMaps
)
    All the various map types that can be created

func (i MapType) String() string
type Marshaler interface {
	encoding.BinaryMarshaler
	encoding.BinaryUnmarshaler
}
    Marshaler allows controlling the binary representation used for getting and
    setting keys on a map.

type PerfReader struct {

	// Error receives a write if the reader exits
	// due to an error.
	Error <-chan error

	// Samples is closed when the Reader exits.
	Samples <-chan *PerfSample
	// Has unexported fields.
}
    PerfReader allows reading bpf_perf_event_output from user space.

func NewPerfReader(opts PerfReaderOptions) (out *PerfReader, err error)
    NewPerfReader creates a new reader with the given options.

    The value returned by LostSamples() will increase if the buffer isn't large
    enough to contain all incoming samples.

func (pr *PerfReader) Close() (err error)
    Close stops the reader, discarding any samples not yet written to 'Samples'.

    Calls to perf_event_output from eBPF programs will return ENOENT after
    calling this method.

func (pr *PerfReader) FlushAndClose() error
    FlushAndClose stops the reader, flushing any samples to 'Samples'. Will
    block if no consumer reads from 'Samples'.

    Calls to perf_event_output from eBPF programs will return ENOENT after
    calling this method.

func (pr *PerfReader) LostSamples() uint64
    LostSamples returns the number of samples dropped by the perf subsystem.

type PerfReaderOptions struct {
	// A map of type PerfEventArray. The reader takes ownership of the
	// map and takes care of closing it.
	Map *Map
	// Controls the size of the per CPU buffer in bytes. LostSamples() will
	// increase if the buffer is too small.
	PerCPUBuffer int
	// The reader will start processing samples once the per CPU buffer
	// exceeds this value. Must be smaller than PerCPUBuffer.
	Watermark int
}
    PerfReaderOptions control the behaviour of the user space reader.

type PerfSample struct {
	// Data are padded with 0 to have a 64-bit alignment.
	// If you are using variable length samples you need to take
	// this into account.
	Data []byte
}
    PerfSample is read from the kernel by PerfReader.