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 5.4.276 or 6.12.16 respectively.

$ ./run-tests.sh 5.4.276
$ ./run-tests.sh 6.12.16

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.276

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.276.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.276
# Load symbols for debugging:
(gdb) sym ./ci-kernels/_build/linux-5.4.276/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() (*cebpf.CollectionSpec, error)
• type ApmIntProcInfo
• type DotnetProcInfo
• type PHPProcInfo
• type RubyProcInfo

Constants

const (
	FrameMarkerUnknown  = 0x0
	FrameMarkerErrorBit = 0x80
	FrameMarkerPython   = 0x1
	FrameMarkerNative   = 0x3
	FrameMarkerPHP      = 0x2
	FrameMarkerPHPJIT   = 0x9
	FrameMarkerKernel   = 0x4
	FrameMarkerHotSpot  = 0x5
	FrameMarkerRuby     = 0x6
	FrameMarkerPerl     = 0x7
	FrameMarkerV8       = 0x8
	FrameMarkerDotnet   = 0xa
	FrameMarkerGo       = 0xb
	FrameMarkerAbort    = 0xff
)

const (
	ProgUnwindStop    = 0x0
	ProgUnwindNative  = 0x1
	ProgUnwindHotspot = 0x2
	ProgUnwindPython  = 0x4
	ProgUnwindPHP     = 0x5
	ProgUnwindRuby    = 0x6
	ProgUnwindPerl    = 0x3
	ProgUnwindV8      = 0x7
	ProgUnwindDotnet  = 0x8
	ProgGoLabels      = 0x9
)

const (
	DeltaCommandFlag = 0x8000

	MergeOpcodeNegative = 0x80
)

const (
	BitWidthPID  = 0x20
	BitWidthPage = 0x40
)

const (
	StackDeltaBucketSmallest = 0x8
	StackDeltaBucketLargest  = 0x17

	StackDeltaPageBits = 0x10
	StackDeltaPageMask = 0xffff
)

const (
	HSTSIDIsStubBit       = 0x3f
	HSTSIDHasFrameBit     = 0x3e
	HSTSIDStackDeltaBit   = 0x38
	HSTSIDStackDeltaMask  = 0x3f
	HSTSIDStackDeltaScale = 0x8
	HSTSIDSegMapBit       = 0x0
	HSTSIDSegMapMask      = 0xffffffffffffff
)

const (
	TraceOriginUnknown  = 0x0
	TraceOriginSampling = 0x1
	TraceOriginOffCPU   = 0x2
)

const (
	UnwindOpcodeCommand   uint8 = 0x0
	UnwindOpcodeBaseCFA   uint8 = 0x1
	UnwindOpcodeBaseSP    uint8 = 0x2
	UnwindOpcodeBaseFP    uint8 = 0x3
	UnwindOpcodeBaseLR    uint8 = 0x4
	UnwindOpcodeBaseReg   uint8 = 0x5
	UnwindOpcodeFlagDeref uint8 = 0x80

	UnwindCommandInvalid      int32 = 0x0
	UnwindCommandStop         int32 = 0x1
	UnwindCommandPLT          int32 = 0x2
	UnwindCommandSignal       int32 = 0x3
	UnwindCommandFramePointer int32 = 0x4

	UnwindDerefMask       int32 = 0x7
	UnwindDerefMultiplier int32 = 0x8
)

const (
	EventTypeGenericPID = 0x1
)

const MaxFrameUnwinds = 0x80

const (
	MetricIDBeginCumulative = 0x62
)

const (
	PerfMaxStackDepth = 0x7f
)

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() (*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.

Types

type ApmIntProcInfo

type ApmIntProcInfo struct {
	Offset uint64
}

type DotnetProcInfo

type DotnetProcInfo struct {
	Version uint32
}

type PHPProcInfo

type PHPProcInfo struct {
	Current_execute_data                uint64
	Jit_return_address                  uint64
	Zend_execute_data_function          uint8
	Zend_execute_data_opline            uint8
	Zend_execute_data_prev_execute_data uint8
	Zend_execute_data_this_type_info    uint8
	Zend_function_type                  uint8
	Zend_op_lineno                      uint8
	Pad_cgo_0                           [2]byte
}

type RubyProcInfo

type RubyProcInfo struct {
	Version                      uint32
	Current_ctx_ptr              uint64
	Vm_stack                     uint8
	Vm_stack_size                uint8
	Cfp                          uint8
	Pc                           uint8
	Iseq                         uint8
	Ep                           uint8
	Size_of_control_frame_struct uint8
	Body                         uint8
	Iseq_type                    uint8
	Iseq_encoded                 uint8
	Iseq_size                    uint8
	Size_of_value                uint8
	Running_ec                   uint16
	Pad_cgo_0                    [2]byte
}