Skip to content
Français
Account: not signed in, sync available My learning
Select theme
Français

eBPF maps: communicating between kernel and user space

By updated

Improve this page

An eBPF map is a kernel data structure, shared with user space: it is how your program remembers a state and passes on what it observes. Without maps, an eBPF program would be mute and memoryless. This page explains what they are, the main types (hash table, array, ring buffer), and shows on a real example the kernel writing and user space reading the same map. Audience: anyone who reads or writes eBPF programs beyond simple display. Outputs captured on an Ubuntu 24.04 VM (kernel 6.8).

What you will learn

  • Understand why maps are indispensable
  • Distinguish the main types of maps and their use
  • Read and write the same map from the kernel and from user space
  • Choose between storing a state and streaming events
  • Avoid the classic pitfalls (NULL test, contention, size)

Why does an eBPF program need maps?

An eBPF program has two strong limits. First, it keeps no memory from one trigger to the next: its local variables disappear at the end of each execution. Second, it cannot talk directly to a user-space program to deliver a result. The helper bpf_trace_printk (a function that the kernel makes available to eBPF programs) helps out for debugging, but it writes to a single shared channel, unsuitable for real work.

Maps lift both limits at once. They are memory areas managed by the kernel, persistent (they survive between triggers) and shared: the kernel program accesses them through helpers, user space through system calls. The map is the meeting point of the two worlds.

What is a map, concretely?

A map associates a key with a value, both of a fixed type defined at creation. You choose at declaration: the map type (which determines its behavior), the key size, the value size, and the maximum number of entries. From there, the program reads, writes and updates entries; user space does the same on its side.

The kernel catalog has many map types. The following table lists the most common and what they are for; choosing the type is the first decision when reading or writing a program.

Map typeWhat it is for
HashAssociation key -> arbitrary value (counters per process, per IP...)
ArrayArray indexed by integer, fixed size, very fast access
Per-CPU hash / arrayOne copy per core, to count without contention between processors
LRU hashHash table that automatically evicts the least recently used entries
Ring bufferQueue to stream a flow of events to user space
Stack traceStorage of call stacks, the basis of profiling

How does the kernel write and user space read a map?

Nothing beats seeing both sides of the map. The following program counts system calls per process. The kernel accumulates in a hash map; the Python script then reads it. We use BCC, where the C program is embedded in Python. You do not need to know how to write this C: read it to spot where the map is declared, filled, then read.

from bcc import BPF
from time import sleep
program = r"""
struct key_t { char name[16]; };
BPF_HASH(counter, struct key_t, u64); // the map: process name -> count
TRACEPOINT_PROBE(raw_syscalls, sys_enter) { // on every system call
struct key_t key = {};
bpf_get_current_comm(&key.name, sizeof(key.name));
u64 zero = 0, *value;
value = counter.lookup_or_try_init(&key, &zero); // fetch the entry, or create it
if (value) // NULL test required by the verifier
(*value)++;
return 0;
}
"""
b = BPF(text=program)
print("Counting system calls for 5 seconds...\n")
sleep(5)
print(f"{'PROCESS':<16} {'CALLS':>8}")
items = sorted(b["counter"].items(), key=lambda kv: kv[1].value)
for key, value in items[-8:]: # the 8 most active
print(f"{key.name.decode():<16} {value.value:>8}")

The listing and the output below use the same names, so you can follow a value from the kernel program to what the terminal prints. Two key mechanisms in the kernel program:

  • BPF_HASH(counter, struct key_t, u64) declares the map: its name, the key type (a structure containing the process name), the value type (a 64-bit integer).
  • lookup_or_try_init looks for the entry for the key; if it does not exist, it creates it at zero. The returned value may be null, hence the if (value) that the verifier requires.

On the Python side, b["counter"].items() reads the same map from user space. Real output:

PROCESS CALLS
systemd 19
multipathd 30
sleep 5376
uname 5520
cat 5808
bash 6430
ls 7104
id 10560

The kernel filled the map in real time; Python read it at the end. That is exactly the role of a map: a state shared between the two sides of the boundary, without the kernel having to send each system call one by one to user space.

Should you store a state or stream a flow?

The previous example illustrates the first use. There are two, not to be confused, and the choice between them determines the map type to use.

Store a state, then read it (as above). The kernel aggregates in a hash or an array; user space periodically reads the result. Ideal for counters, statistics, lookup tables. The volume stays under control: whatever the number of events, the map only holds the summary.

Stream a flow of events. When you want to receive each event with its detail (a new process, a network connection), you use a ring buffer (literally a circular buffer). The program pushes a record into it at each event, user space consumes them as they come. It is the right structure for a flow, where direct display would not scale.

How do you inspect maps with bpftool?

As with programs, bpftool shows the maps actually present in the kernel, regardless of the tool that created them. It is the administrator's reflex when wanting to know what an eBPF tool consumes:

Terminal window
sudo bpftool map show

Each map appears there with its identifier, its type, the size of its key and of its value, its maximum number of entries. You can also dump its content with bpftool map dump. This is precious for debugging: checking that a map fills up, or reading its state without writing code.

Security and pitfalls

Maps are shared memory, and their classic flaws come down to five points.

  • Always test the return of a lookup against NULL. The verifier imposes it; forgetting it is a classic cause of rejection, detailed in the eBPF verifier.
  • Heavily used counters: prefer a per-CPU map. When several cores increment the same entry, they get in each other's way (contention). A per-CPU map gives each core its copy; user space adds them up on reading. Throughput gains a lot.
  • Size is bounded. A map has a maximum number of entries fixed at creation. A full hash refuses new keys; an LRU hash evicts the oldest instead. Choose according to the need.
  • Maps consume locked memory. They occupy non-swappable RAM; on a constrained system, watch the consumption (visible in the memlock field of bpftool).
  • A map can be "pinned". Pinning a map in /sys/fs/bpf makes it survive the end of the program that created it, and makes it accessible to others. Handy, but it is data sharing to secure.

Key takeaways

  • A map is a kernel structure, persistent and shared with user space: the memory and the voice of the eBPF program.
  • You choose its type according to use: hash/array for a state, ring buffer for a flow of events, per-CPU to count without contention.
  • The kernel writes through helpers, user space reads through system calls: it is the bridge between the two worlds.
  • Storing a state (counters, stats) and streaming a flow (each event) are two distinct uses.
  • Always test NULL after a lookup, and watch size and locked memory.
  • bpftool inspects and dumps maps without writing a line of code.

Knowledge check

Check that the essentials of this lesson are in place. The questions only cover what has just been explained here.

Knowledge check

Check what you have learned with this interactive quiz

6 questions
6 min
70% to pass

How it works

  • The timer starts when you click Start
  • Multiple choice, true/false and short answer questions
  • You can move between questions
  • Detailed results are shown at the end

Starts the quiz and the timer