Skip to content

Helper function bpf_perf_event_output

v4.4

This helper writes a raw data blob into a special BPF perf event held by map of type BPF_MAP_TYPE_PERF_EVENT_ARRAY.

Definition

Copyright (c) 2015 The Libbpf Authors. All rights reserved.

Returns 0 on success, or a negative error in case of failure.

static long (* const bpf_perf_event_output)(void *ctx, void *map, __u64 flags, void *data, __u64 size) = (void *) 25;

Usage

The perf event in map must have the following attributes: PERF_SAMPLE_RAW as sample_type, PERF_TYPE_SOFTWARE as type, and PERF_COUNT_SW_BPF_OUTPUT as config.

The flags are used to indicate the index in map for which the value must be put, masked with BPF_F_INDEX_MASK. Alternatively, flags can be set to BPF_F_CURRENT_CPU to indicate that the index of the current CPU core should be used.

Warning

Each perf event is created on a specific CPU. This helper can only write to perf events on the same CPU as the eBPF program is running. Manually picking an index containing a perf event on a different CPU will result in a -EOPNOTSUPP error at runtime. So unless there is a good reason to do so, its recommended to use BPF_F_CURRENT_CPU and to populate the BPF_MAP_TYPE_PERF_EVENT_ARRAY map in such a way where the CPU indices and map indices are the same.

The value to write, of size, is passed through eBPF stack and pointed by data.

The context of the program ctx needs also be passed to the helper.

On user space, a program willing to read the values needs to call perf_event_open on the perf event (either for one or for all CPUs) and to store the file descriptor into the map. This must be done before the eBPF program can send data into it. An example is available in file samples/bpf/trace_output_user.c in the Linux kernel source tree (the eBPF program counterpart is in samples/bpf/trace_output_kern.c).

bpf_perf_event_output achieves better performance than bpf_trace_printk for sharing data with user space, and is much better suitable for streaming data from eBPF programs.

Note that this helper is not restricted to tracing use cases and can be used with programs attached to TC or XDP as well, where it allows for passing data to user space listeners. Data can be:

  • Only custom structs,
  • Only the packet payload, or
  • A combination of both.

Program types

This helper call can be used in the following program types:

Map types

This helper call can be used with the following map types:

Example

Docs could be improved

This part of the docs is incomplete, contributions are very welcome