support

README

This directory is intended for non-Go support functionality. For example, the eBPF code and supporting Python scripts for bytecode offsets to line number translation.

Testing eBPF code on different kernel version

Via the following commands, you can run the eBPF loading tests on kernel version 4.9.198, 4.19.81 or 5.4.5 respectively.

$ ./run-tests.sh 4.9.198
$ ./run-tests.sh 4.19.81
$ ./run-tests.sh 5.4.5

The script loads the provided eBPF code into the kernel in a virtual environment so that it does not affect your local environment.

Requirements

The tests are built on top of the following dependencies. Make sure you have them installed beforehand.

• qemu-system-x86
• statically linked busybox

Building a Custom Kernel Image

Kernel images can be build with the script provided in ci-kernels. This directory contains also the basic configuration settings needed to enable eBPF features for the kernel image.

Test a Custom Kernel Image

By default run-tests.sh takes only the kernel version as argument. The script looks for the kernel image with the specified version in ci-kernels. As an alternative one can provide a directory to look for this kernel image via KERN_DIR.

$ KERN_DIR=my-other-kernels/ ./run-tests.sh 5.4.31

Manually Debugging a Custom Kernel Image

1. Compile eBPF and Go code

$ make ebpf
$ cd support
$ go test -c -tags integration ./...

1. Get virtme to run the environment

$ tmp_virtme="$(mktemp -d --suffix=-virtme)"
$ git clone -q https://git.kernel.org/pub/scm/utils/kernel/virtme/virtme.git "${tmp_virtme}"

1. Start the virtual environment for debugging with gdb:

$ ${tmp_virtme}/virtme-run --kimg  ci-kernels/linux-5.4.31.bz \
    --memory 4096M \
    --pwd \
    --script-sh "mount -t bpf bpf /sys/fs/bpf ; ./support.test -test.v" \
    --qemu-opts -append nokaslr -s

1. Start gdb in a second shell:

$ cd support
$ gdb
# Attach gdb to the running qemu process in the same directory:
(gdb) target remote localhost:1234
# Load source code:
(gdb) directory ./ci-kernels/_build/linux-5.4.31
# Load symbols for debugging:
(gdb) sym ./ci-kernels/_build/linux-5.4.31/vmlinux
# Set breakpoint at entry of eBPF verifier:
(gdb) break do_check
Breakpoint 1 at 0xffffffff81184460: file kernel/bpf/verifier.c, line 4105.

Documentation

Overview

support maps the definitions from headers in the C world into a nice go way

Index

• Constants
• func DecodeBiasAndUnwindProgram(biasAndUnwindProgram uint64) (bias uint64, unwindProgram uint8)
• func EncodeBiasAndUnwindProgram(bias uint64, unwindProgram uint8) (uint64, error)
• func LoadCollectionSpec(debugTracer bool) (*cebpf.CollectionSpec, error)

Constants

const (
	FrameMarkerUnknown  = C.FRAME_MARKER_UNKNOWN
	FrameMarkerErrorBit = C.FRAME_MARKER_ERROR_BIT
	FrameMarkerPython   = C.FRAME_MARKER_PYTHON
	FrameMarkerNative   = C.FRAME_MARKER_NATIVE
	FrameMarkerPHP      = C.FRAME_MARKER_PHP
	FrameMarkerPHPJIT   = C.FRAME_MARKER_PHP_JIT
	FrameMarkerKernel   = C.FRAME_MARKER_KERNEL
	FrameMarkerHotSpot  = C.FRAME_MARKER_HOTSPOT
	FrameMarkerRuby     = C.FRAME_MARKER_RUBY
	FrameMarkerPerl     = C.FRAME_MARKER_PERL
	FrameMarkerV8       = C.FRAME_MARKER_V8
	FrameMarkerDotnet   = C.FRAME_MARKER_DOTNET
	FrameMarkerAbort    = C.FRAME_MARKER_ABORT
)

const (
	ProgUnwindStop    = C.PROG_UNWIND_STOP
	ProgUnwindNative  = C.PROG_UNWIND_NATIVE
	ProgUnwindHotspot = C.PROG_UNWIND_HOTSPOT
	ProgUnwindPython  = C.PROG_UNWIND_PYTHON
	ProgUnwindPHP     = C.PROG_UNWIND_PHP
	ProgUnwindRuby    = C.PROG_UNWIND_RUBY
	ProgUnwindPerl    = C.PROG_UNWIND_PERL
	ProgUnwindV8      = C.PROG_UNWIND_V8
	ProgUnwindDotnet  = C.PROG_UNWIND_DOTNET
)

const (
	DeltaCommandFlag = C.STACK_DELTA_COMMAND_FLAG

	MergeOpcodeNegative = C.MERGEOPCODE_NEGATIVE
)

const (
	BitWidthPID  = C.BIT_WIDTH_PID
	BitWidthPage = C.BIT_WIDTH_PAGE
)

const (
	// StackDeltaBucket[Smallest|Largest] define the boundaries of the bucket sizes of the various
	// nested stack delta maps.
	StackDeltaBucketSmallest = C.STACK_DELTA_BUCKET_SMALLEST
	StackDeltaBucketLargest  = C.STACK_DELTA_BUCKET_LARGEST

	// StackDeltaPage[Bits|Mask] determine the paging size of stack delta map information
	StackDeltaPageBits = C.STACK_DELTA_PAGE_BITS
	StackDeltaPageMask = C.STACK_DELTA_PAGE_MASK
)

const (
	HSTSIDIsStubBit       = C.HS_TSID_IS_STUB_BIT
	HSTSIDHasFrameBit     = C.HS_TSID_HAS_FRAME_BIT
	HSTSIDStackDeltaBit   = C.HS_TSID_STACK_DELTA_BIT
	HSTSIDStackDeltaMask  = C.HS_TSID_STACK_DELTA_MASK
	HSTSIDStackDeltaScale = C.HS_TSID_STACK_DELTA_SCALE
	HSTSIDSegMapBit       = C.HS_TSID_SEG_MAP_BIT
	HSTSIDSegMapMask      = C.HS_TSID_SEG_MAP_MASK
)

const (
	EventTypeGenericPID = C.EVENT_TYPE_GENERIC_PID
)

const MaxFrameUnwinds = C.MAX_FRAME_UNWINDS

const (
	MetricIDBeginCumulative = C.metricID_BeginCumulative
)

const (
	// PerfMaxStackDepth is the bpf map data array length for BPF_MAP_TYPE_STACK_TRACE traces
	PerfMaxStackDepth = C.PERF_MAX_STACK_DEPTH
)

Functions

func DecodeBiasAndUnwindProgram

func DecodeBiasAndUnwindProgram(biasAndUnwindProgram uint64) (bias uint64, unwindProgram uint8)

DecodeBiasAndUnwindProgram decodes the contents of the `bias_and_unwind_program` field in C.PIDPageMappingInfo and returns the corresponding bias and unwind program.

func EncodeBiasAndUnwindProgram

func EncodeBiasAndUnwindProgram(bias uint64,
	unwindProgram uint8) (uint64, error)

EncodeBiasAndUnwindProgram encodes a bias_and_unwind_program value (for C.PIDPageMappingInfo) from a bias and unwind program values. This currently assumes a non-negative bias: this encoding may have to be changed if bias can be negative.

func LoadCollectionSpec

func LoadCollectionSpec(debugTracer bool) (*cebpf.CollectionSpec, error)

LoadCollectionSpec is a wrapper around ebpf.LoadCollectionSpecFromReader and loads the eBPF Spec from the embedded file. We expect tracerData to hold all possible eBPF maps and programs.