cilium: Index | Files | Directories

package bpf

import ""

Package bpf provides functions that allow golang programs to interact with bpf maps. +groupName=pkg


Package Files

bpf.go bpf_linux.go bpffs_linux.go doc.go endpoint.go map.go map_linux.go map_register_linux.go metrics.go prog.go rlimit_linux.go stats_linux.go zz_generated.deepcopy.go


const (
    // BPF syscall command constants. Must match enum bpf_cmd from linux/bpf.h
    BPF_MAP_CREATE          = 0
    BPF_PROG_LOAD           = 5
    BPF_OBJ_PIN             = 6
    BPF_OBJ_GET             = 7
    BPF_PROG_ATTACH         = 8
    BPF_PROG_DETACH         = 9
    BPF_PROG_TEST_RUN       = 10
    BPF_PROG_GET_NEXT_ID    = 11
    BPF_MAP_GET_NEXT_ID     = 12
    BPF_PROG_GET_FD_BY_ID   = 13
    BPF_MAP_GET_FD_BY_ID    = 14
    BPF_PROG_QUERY          = 16
    BPF_BTF_LOAD            = 18
    BPF_BTF_GET_FD_BY_ID    = 19
    BPF_TASK_FD_QUERY       = 20

    // BPF syscall attach types
    BPF_CGROUP_SOCK_OPS          = 3
    BPF_CGROUP_DEVICE            = 6
    BPF_SK_MSG_VERDICT           = 7
    BPF_CGROUP_INET4_BIND        = 8
    BPF_CGROUP_INET6_BIND        = 9
    BPF_LIRC_MODE2               = 16
    BPF_FLOW_DISSECTOR           = 17
    BPF_CGROUP_SYSCTL            = 18

    // Flags for BPF_MAP_UPDATE_ELEM. Must match values from linux/bpf.h
    BPF_ANY     = 0
    BPF_EXIST   = 2

    // Flags for BPF_MAP_CREATE. Must match values from linux/bpf.h
    BPF_F_NO_PREALLOC   = 1 << 0
    BPF_F_NO_COMMON_LRU = 1 << 1
    BPF_F_NUMA_NODE     = 1 << 2

    // Flags for BPF_PROG_QUERY

    // Flags for accessing BPF object
    BPF_F_RDONLY = 1 << 3
    BPF_F_WRONLY = 1 << 4

    // Flag for stack_map, store build_id+offset instead of pointer
    BPF_F_STACK_BUILD_ID = 1 << 5
const (
    EndpointKeyIPv4 uint8 = 1
    EndpointKeyIPv6 uint8 = 2

Must be in sync with ENDPOINT_KEY_* in <bpf/lib/common.h>


var ErrMaxLookup = errors.New("maximum number of lookups reached")

ErrMaxLookup is returned when the maximum number of map element lookups has been reached.

func CheckOrMountFS Uses

func CheckOrMountFS(bpfRoot string, printWarning bool)

CheckOrMountFS checks or mounts the BPF filesystem and then opens/creates/deletes all maps which have previously been scheduled to be opened/created/deleted.

If printWarning is set, will print a warning if bpffs has not previously been mounted.

func ConfigureResourceLimits Uses

func ConfigureResourceLimits() error

ConfigureResourceLimits configures the memory resource limits for the process to allow BPF syscall interactions.

func ConvertKeyValue Uses

func ConvertKeyValue(bKey []byte, bValue []byte, key MapKey, value MapValue) (MapKey, MapValue, error)

ConvertKeyValue converts key and value from bytes to given Golang struct pointers.

func CreateMap Uses

func CreateMap(mapType MapType, keySize, valueSize, maxEntries, flags, innerID uint32, path string) (int, error)

CreateMap creates a Map of type mapType, with key size keySize, a value size of valueSize and the maximum amount of entries of maxEntries. mapType should be one of the bpf_map_type in "uapi/linux/bpf.h" When mapType is the type HASH_OF_MAPS an innerID is required to point at a map fd which has the same type/keySize/valueSize/maxEntries as expected map entries. For all other mapTypes innerID is ignored and should be zeroed.

func DeleteElement Uses

func DeleteElement(fd int, key unsafe.Pointer) error

DeleteElement deletes the map element with the given key.

func DisableMapPreAllocation Uses

func DisableMapPreAllocation()

DisableMapPreAllocation disables BPF map pre-allocation as a default setting. Some map types enforces pre-alloc strategy so this does not take effect in that case. Also note that this does not take effect on existing map although could be recreated later when objCheck() runs.

func EnableMapPreAllocation Uses

func EnableMapPreAllocation()

EnableMapPreAllocation enables BPF map pre-allocation on map types that support it. This does not take effect on existing map although some map types could be recreated later when objCheck() runs.

func Environment Uses

func Environment() []string

Environment returns a list of environment variables which are needed to make BPF programs and tc aware of the actual BPFFS mount path.

func GetFirstKey Uses

func GetFirstKey(fd int, nextKey unsafe.Pointer) error

GetFirstKey fetches the first key in the map. If there are no keys in the map, io.EOF is returned.

func GetJtime Uses

func GetJtime() (uint64, error)

GetJtime returns a close-enough approximation of kernel jiffies that can be used to compare against jiffies BPF helper. We parse it from /proc/timer_list. GetJtime() should be invoked only at mid-low frequencies.

func GetMapRoot Uses

func GetMapRoot() string

func GetMtime Uses

func GetMtime() (uint64, error)

GetMtime returns monotonic time that can be used to compare values with ktime_get_ns() BPF helper, e.g. needed to check the timeout in sec for BPF entries. We return the raw nsec, although that is not quite usable for comparison. Go has runtime.nanotime() but doesn't expose it as API.

func GetNextKey Uses

func GetNextKey(fd int, key, nextKey unsafe.Pointer) error

GetNextKey stores, in nextKey, the next key after the key of the map in fd. Deprecated, use GetNextKeyFromPointers

func GetNextKeyFromPointers Uses

func GetNextKeyFromPointers(fd int, structPtr unsafe.Pointer, sizeOfStruct uintptr) error

GetNextKeyFromPointers stores, in nextKey, the next key after the key of the map in fd. When there are no more keys, io.EOF is returned.

func GetOpenMaps Uses

func GetOpenMaps() []*models.BPFMap

GetOpenMaps returns a slice of all open BPF maps. This is identical to calling GetMap() on all open maps.

func GetPreAllocateMapFlags Uses

func GetPreAllocateMapFlags(t MapType) uint32

GetPreAllocateMapFlags returns the map flags for map which use conditional pre-allocation.

func LocalMapName Uses

func LocalMapName(name string, id uint16) string

LocalMapName returns the name for a BPF map that is local to the specified ID.

func LocalMapPath Uses

func LocalMapPath(name string, id uint16) string

LocalMapPath returns the path for a BPF map that is local to the specified ID.

func LookupElement Uses

func LookupElement(fd int, key, value unsafe.Pointer) error

LookupElement looks up for the map value stored in fd with the given key. The value is stored in the value unsafe.Pointer. Deprecated, use LookupElementFromPointers

func LookupElementFromPointers Uses

func LookupElementFromPointers(fd int, structPtr unsafe.Pointer, sizeOfStruct uintptr) error

LookupElement looks up for the map value stored in fd with the given key. The value is stored in the value unsafe.Pointer.

func MapFdFromID Uses

func MapFdFromID(id int) (int, error)

MapFdFromID retrieves a file descriptor based on a map ID.

func MapPath Uses

func MapPath(name string) string

MapPath returns a path for a BPF map with a given name.

func MapPrefixPath Uses

func MapPrefixPath() string

func ObjClose Uses

func ObjClose(fd int) error

ObjClose closes the map's fd.

func ObjGet Uses

func ObjGet(pathname string) (int, error)

ObjGet reads the pathname and returns the map's fd read.

func ObjPin Uses

func ObjPin(fd int, pathname string) error

ObjPin stores the map's fd in pathname.

func OpenOrCreateMap Uses

func OpenOrCreateMap(path string, mapType MapType, keySize, valueSize, maxEntries, flags uint32, innerID uint32, pin bool) (int, bool, error)

func TestDummyProg Uses

func TestDummyProg(progType ProgType, attachType uint32) error

TestDummyProg loads a minimal BPF program into the kernel and probes whether it succeeds in doing so. This can be used to bail out early in the daemon when a given type is not supported.

func UnpinMapIfExists Uses

func UnpinMapIfExists(name string) error

UnpinMapIfExists unpins the given map identified by name. If the map doesn't exist, returns success.

func UpdateElement Uses

func UpdateElement(fd int, key, value unsafe.Pointer, flags uint64) error

UpdateElement updates the map in fd with the given value in the given key. The flags can have the following values: bpf.BPF_ANY to create new element or update existing; bpf.BPF_NOEXIST to create new element if it didn't exist; bpf.BPF_EXIST to update existing element. Deprecated, use UpdateElementFromPointers

func UpdateElementFromPointers Uses

func UpdateElementFromPointers(fd int, structPtr unsafe.Pointer, sizeOfStruct uintptr) error

UpdateElementFromPointers updates the map in fd with the given value in the given key.

type BpfMapInfo Uses

type BpfMapInfo struct {
    Type       uint32
    Id         uint32
    KeySize    uint32
    ValueSize  uint32
    MaxEntries uint32
    MapFlags   uint32

func GetMapInfoByFd Uses

func GetMapInfoByFd(fd uint32) (*BpfMapInfo, error)

GetMapInfoByFd returns map info for a map which is pointed by the given fd.

type DesiredAction Uses

type DesiredAction int

DesiredAction is the action to be performed on the BPF map

const (
    // OK indicates that to further action is required and the entry is in
    // sync
    OK  DesiredAction = iota

    // Insert indicates that the entry needs to be created or updated

    // Delete indicates that the entry needs to be deleted

func (DesiredAction) String Uses

func (d DesiredAction) String() string

type DumpCallback Uses

type DumpCallback func(key MapKey, value MapValue)

type DumpParser Uses

type DumpParser func(key []byte, value []byte, mapKey MapKey, mapValue MapValue) (MapKey, MapValue, error)

type DumpStats Uses

type DumpStats struct {
    // Started is the timestamp when the gc run was started.
    Started time.Time

    // Finished is the timestamp when the gc run completed.
    Finished time.Time

    // Lookup is the number of key lookups performed.
    Lookup uint32

    // LookupFailed is the number of key lookups that failed.
    LookupFailed uint32

    // PrevKeyUnavailable is the number of times the previous key was not
    // available.
    PrevKeyUnavailable uint32

    // KeyFallback is the number of times the current key became invalid
    // while traversing and we had to fall back to the previous key.
    KeyFallback uint32

    // MaxEntries is the maximum number of entries in the gc table.
    MaxEntries uint32

    // Interrupted is the number of times the gc run was interrupted and
    // had to start from scratch.
    Interrupted uint32

    // Completed is true when the gc run has been completed.
    Completed bool

DumpStats tracks statistics over the dump of a map.

func NewDumpStats Uses

func NewDumpStats(m *Map) *DumpStats

NewDumpStats returns a new stats structure for collecting dump statistics.

func (*DumpStats) Duration Uses

func (d *DumpStats) Duration() time.Duration

Duration returns the duration of the dump.

type EndpointKey Uses

type EndpointKey struct {
    // represents both IPv6 and IPv4 (in the lowest four bytes)
    IP     types.IPv6 `align:"$union0"`
    Family uint8      `align:"family"`
    Key    uint8      `align:"key"`
    Pad2   uint16     `align:"pad5"`

EndpointKey represents the key value of the endpoints BPF map

Must be in sync with struct endpoint_key in <bpf/lib/common.h> +k8s:deepcopy-gen=true

func NewEndpointKey Uses

func NewEndpointKey(ip net.IP) EndpointKey

NewEndpointKey returns an EndpointKey based on the provided IP address. The address family is automatically detected.

func (*EndpointKey) DeepCopy Uses

func (in *EndpointKey) DeepCopy() *EndpointKey

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new EndpointKey.

func (*EndpointKey) DeepCopyInto Uses

func (in *EndpointKey) DeepCopyInto(out *EndpointKey)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*EndpointKey) GetKeyPtr Uses

func (k *EndpointKey) GetKeyPtr() unsafe.Pointer

GetKeyPtr returns the unsafe pointer to the BPF key

func (*EndpointKey) GetValuePtr Uses

func (k *EndpointKey) GetValuePtr() unsafe.Pointer

GetValuePtr returns the unsafe pointer to the BPF key for users that use EndpointKey as a value in bpf maps

func (EndpointKey) String Uses

func (k EndpointKey) String() string

String provides a string representation of the EndpointKey.

func (EndpointKey) ToIP Uses

func (k EndpointKey) ToIP() net.IP

ToIP converts the EndpointKey into a net.IP structure.

type Map Uses

type Map struct {

    // NonPersistent is true if the map does not contain persistent data
    // and should be removed on startup.
    NonPersistent bool

    // DumpParser is a function for parsing keys and values from BPF maps
    DumpParser DumpParser
    // contains filtered or unexported fields

func GetMap Uses

func GetMap(name string) *Map

GetMap returns the registered map with the given name or absolute path

func NewMap Uses

func NewMap(name string, mapType MapType, mapKey MapKey, keySize int,
    mapValue MapValue, valueSize, maxEntries int, flags uint32, innerID uint32,
    dumpParser DumpParser) *Map

NewMap creates a new Map instance - object representing a BPF map

func NewMapWithOpts Uses

func NewMapWithOpts(name string, mapType MapType, mapKey MapKey, keySize int,
    mapValue MapValue, valueSize, maxEntries int, flags uint32, innerID uint32,
    dumpParser DumpParser, opts *NewMapOpts) *Map

NewMapWithOpts creates a new Map instance - object representing a BPF map

func NewPerCPUHashMap Uses

func NewPerCPUHashMap(name string, mapKey MapKey, keySize int, mapValue MapValue, valueSize, cpus, maxEntries int, flags uint32, innerID uint32, dumpParser DumpParser) *Map

NewPerCPUHashMap creates a new Map type of "per CPU hash" - object representing a BPF map The number of cpus is used to have the size representation of a value when a lookup is made on this map types.

func OpenMap Uses

func OpenMap(name string) (*Map, error)

OpenMap opens the given bpf map and generates the Map info based in the information stored in the bpf map. *Warning*: Calling this function requires the caller to properly setup the MapInfo.MapKey and MapInfo.MapValues fields as those structures are not stored in the bpf map.

func (*Map) CheckAndUpgrade Uses

func (m *Map) CheckAndUpgrade(desired *MapInfo) bool

CheckAndUpgrade checks the received map's properties (for the map currently loaded into the kernel) against the desired properties, and if they do not match, deletes the map.

Returns true if the map was upgraded.

func (*Map) Close Uses

func (m *Map) Close() error

func (*Map) Create Uses

func (m *Map) Create() (bool, error)

Create is similar to OpenOrCreate, but closes the map after creating or opening it.

func (*Map) DeepEquals Uses

func (m *Map) DeepEquals(other *Map) bool

DeepEquals compares the current map against another map to see that the attributes of the two maps are the same.

func (*Map) Delete Uses

func (m *Map) Delete(key MapKey) error

Delete deletes the map entry corresponding to the given key.

func (*Map) DeleteAll Uses

func (m *Map) DeleteAll() error

DeleteAll deletes all entries of a map by traversing the map and deleting individual entries. Note that if entries are added while the taversal is in progress, such entries may survive the deletion process.

func (*Map) Dump Uses

func (m *Map) Dump(hash map[string][]string) error

Dump returns the map (type map[string][]string) which contains all data stored in BPF map.

func (*Map) DumpIfExists Uses

func (m *Map) DumpIfExists(hash map[string][]string) error

DumpIfExists dumps the contents of the map into hash via Dump() if the map file exists

func (*Map) DumpReliablyWithCallback Uses

func (m *Map) DumpReliablyWithCallback(cb DumpCallback, stats *DumpStats) error

DumpReliablyWithCallback is similar to DumpWithCallback, but performs additional tracking of the current and recently seen keys, so that if an element is removed from the underlying kernel map during the dump, the dump can continue from a recently seen key rather than restarting from scratch. In addition, it caps the maximum number of map entry iterations at 4 times the maximum map size. If this limit is reached, ErrMaxLookup is returned.

The caller must provide a callback for handling each entry, and a stats object initialized via a call to NewDumpStats().

func (*Map) DumpWithCallback Uses

func (m *Map) DumpWithCallback(cb DumpCallback) error

DumpWithCallback iterates over the Map and calls the given callback function on each iteration. That callback function is receiving the actual key and value. The callback function should consider creating a deepcopy of the key and value on between each iterations to avoid memory corruption.

func (*Map) DumpWithCallbackIfExists Uses

func (m *Map) DumpWithCallbackIfExists(cb DumpCallback) error

DumpWithCallbackIfExists is similar to DumpWithCallback, but returns earlier if the given map does not exist.

func (*Map) EndParallelMode Uses

func (m *Map) EndParallelMode()

EndParallelMode ends the parallel mode of a map

func (*Map) GetFd Uses

func (m *Map) GetFd() int

func (*Map) GetModel Uses

func (m *Map) GetModel() *models.BPFMap

GetModel returns a BPF map in the representation served via the API

func (*Map) GetNextKey Uses

func (m *Map) GetNextKey(key MapKey, nextKey MapKey) error

GetNextKey returns the next key in the Map after key.

func (*Map) Lookup Uses

func (m *Map) Lookup(key MapKey) (MapValue, error)

func (*Map) Name Uses

func (m *Map) Name() string

Name returns the basename of this map.

func (*Map) Open Uses

func (m *Map) Open() error

Open opens the BPF map. All calls to Open() are serialized due to acquiring m.lock

func (*Map) OpenOrCreate Uses

func (m *Map) OpenOrCreate() (bool, error)

OpenOrCreate attempts to open the Map, or if it does not yet exist, create the Map. If the existing map's attributes such as map type, key/value size, capacity, etc. do not match the Map's attributes, then the map will be deleted and reopened without any attempt to retain its previous contents. If the map is marked as non-persistent, it will always be recreated.

If the map type is MapTypeLRUHash or MapTypeLPMTrie and the kernel lacks support for this map type, then the map will be opened as MapTypeHash instead. Note that the BPF code that interacts with this map *MUST* be structured in such a way that the map is declared as the same type based on the same probe logic (eg HAVE_LRU_HASH_MAP_TYPE, HAVE_LPM_TRIE_MAP_TYPE).

For code that uses an LPMTrie, the BPF code must also use macros to retain the "longest prefix match" behaviour on top of the hash maps, for example via LPM_LOOKUP_FN() (see bpf/lib/maps.h).

Returns whether the map was deleted and recreated, or an optional error.

func (*Map) OpenOrCreateUnpinned Uses

func (m *Map) OpenOrCreateUnpinned() (bool, error)

OpenOrCreateUnpinned is similar to OpenOrCreate (see above) but without pinning the map to the file system if it had to be created.

func (*Map) OpenParallel Uses

func (m *Map) OpenParallel() (bool, error)

OpenParallel is similar to OpenOrCreate() but prepares the existing map to be faded out while a new map is taking over. This can be used if a map is shared between multiple consumers and the context of the shared map is changing. Any update to the shared map would impact all consumers and consumers can only be updated one by one. Parallel mode allows for consumers to continue using the old version of the map until the consumer is updated to use the new version.

func (*Map) Path Uses

func (m *Map) Path() (string, error)

Path returns the path to this map on the filesystem.

func (*Map) Reopen Uses

func (m *Map) Reopen() error

Reopen attempts to close and re-open the received map.

func (*Map) Unpin Uses

func (m *Map) Unpin() error

Unpin attempts to unpin (remove) the map from the filesystem.

func (*Map) UnpinIfExists Uses

func (m *Map) UnpinIfExists() error

UnpinIfExists tries to unpin (remove) the map only if it exists.

func (*Map) Update Uses

func (m *Map) Update(key MapKey, value MapValue) error

func (*Map) WithCache Uses

func (m *Map) WithCache() *Map

WithCache enables use of a cache. This will store all entries inserted from user space in a local cache (map) and will indicate the status of each individual entry.

func (*Map) WithNonPersistent Uses

func (m *Map) WithNonPersistent() *Map

WithNonPersistent turns the map non-persistent and returns the map

type MapInfo Uses

type MapInfo struct {
    MapType  MapType
    MapKey   MapKey
    KeySize  uint32
    MapValue MapValue
    // ReadValueSize is the value size that is used to read from the BPF maps
    // this value and the ValueSize values can be different for MapTypePerCPUHash.
    ReadValueSize uint32
    ValueSize     uint32
    MaxEntries    uint32
    Flags         uint32
    InnerID       uint32
    OwnerProgType ProgType

func GetMapInfo Uses

func GetMapInfo(pid int, fd int) (*MapInfo, error)

type MapKey Uses

type MapKey interface {

    // Returns pointer to start of key
    GetKeyPtr() unsafe.Pointer

    // Allocates a new value matching the key type
    NewValue() MapValue

    // DeepCopyMapKey returns a deep copy of the map key
    DeepCopyMapKey() MapKey

type MapType Uses

type MapType int

MapType is an enumeration for valid BPF map types

const (
    MapTypeUnspec MapType = iota
    // MapTypeMaximum is the maximum supported known map type.

This enumeration must be in sync with enum bpf_map_type in <linux/bpf.h>

func GetMapType Uses

func GetMapType(t MapType) MapType

GetMapType determines whether the specified map type is supported by the kernel (as determined by bpftool feature checks), and if the map type is not supported, returns a more primitive map type that may be used to implement the map on older implementations. Otherwise, returns the specified map type.

func (MapType) String Uses

func (t MapType) String() string

type MapValidator Uses

type MapValidator func(path string) (bool, error)

type MapValue Uses

type MapValue interface {

    // Returns pointer to start of value
    GetValuePtr() unsafe.Pointer

    // DeepCopyMapValue returns a deep copy of the map value
    DeepCopyMapValue() MapValue

type NewMapOpts Uses

type NewMapOpts struct {
    CheckValueSize bool // Enable mapValue and valueSize size check

type ProgType Uses

type ProgType int

ProgType is an enumeration for valid BPF program types

const (
    ProgTypeUnspec ProgType = iota

This enumeration must be in sync with enum bpf_prog_type in <linux/bpf.h>

func (ProgType) String Uses

func (t ProgType) String() string


binaryPackage binary is a fork of the upstream golang library.

Package bpf imports 33 packages (graph) and is imported by 154 packages. Updated 2020-09-12. Refresh now. Tools for package owners.