luaebpf

bpf.mapModule

Declares a map in a program file.

The compile-time twin of the kernel bpf.map: constructors of the same names and the same spec vocabulary, producing a BTF-defined map in the object instead of opening a pinned one.

Usage

local map = require("bpf.map")

local flows = map.hash("flows", {key = "I4", value = "I4", entries = 65536})
local hits  = map.array("hits", {key = "I4", value = "I8", entries = 1})

Declaring a map in a program file

bpf.map.array (name, spec) Declares an array map in a program file, whose keys are its u32 indices.
bpf.map.hash (name, spec) Declares a hash map in a program file, which lunatik bpf compiles.
bpf.map.lru_hash (name, spec) Declares an LRU hash map in a program file.

Declaring a map in a program file in detail

These constructors run in the body of a program file, under lunatik bpf, and declare a map the object carries. A map needs a name whether or not a compiled function references it: lunatik run creates the map and pins it at /sys/fs/bpf/lunatik/<script>/<name>, where a kernel script opens it with the kernel’s constructor of the same name, which takes the path and the two specs, map.hash(path, keyspec, valuespec). The name luaebpf_errors is the compiler’s, the map it counts a program’s errors in.

In a compiled function a map reads as a table: m[k] gives the value or nil, m[k] = v inserts or replaces, m[k] = nil deletes. A lookup’s value is used only after if v then tests it, which is what the verifier requires of the pointer underneath; any other use is refused, “‘’ may be nil here; test it first”. A lookup in an array within its entries always finds a value, 0 where nothing was written. A key or a value its spec cannot pack, and an update or a delete the map refuses, a full hash map, an index past an array, a delete from an array, stop the program, which returns XDP_ABORTED or TC_ACT_SHOT. A struct value spec gives a read-only value read by field name, v.ttl, as the kernel module decodes such a value into a table keyed by the layout’s names, and a bitfield, v.ihl, as the codec’s view reads it; an index into it is refused, and so is a field wider than a byte on a kernel without efficient unaligned access, as a packet read is.

bpf.map.array (name, spec)
Declares an array map in a program file, whose keys are its u32 indices.

Parameters

  • name string what the object calls it, and what the loader pins it under
  • spec table {key, value, entries}, as hash takes, the key four bytes wide

Returns

    table the declared map

Raises

as hash raises, plus an array map is keyed by 4 bytes, not <n>
bpf.map.hash (name, spec)
Declares a hash map in a program file, which lunatik bpf compiles.

Parameters

  • name string what the object calls it, and what the loader pins it under
  • spec table {key, value, entries}; key is a string.pack format of one fixed-size integer, value is one of those or a struct codec, and entries is the map’s capacity

Returns

    table the declared map, a table proxy inside a compiled function

Raises

map.hash takes a name and a spec, a map name is a C identifier, not '<name>', a map key spec packs one value, a map value spec packs one value or is a struct codec, a map is read in the kernel's byte order, not '<spec>', a map reads 1, 2, 4 or 8 bytes at a time, not <n>, a map holds between 1 and 4294967295 entries, not <n>, '<name>' is declared twice, or 'luaebpf_errors' is the map a program's errors are counted in
bpf.map.lru_hash (name, spec)
Declares an LRU hash map in a program file.

Parameters

  • name string what the object calls it, and what the loader pins it under
  • spec table {key, value, entries}, as hash takes

Returns

    table the declared map

Raises

as hash raises