bpftimetool

Command-line tool for inspecting and managing bpftime shared memory state.

Overview

bpftimetool provides utilities to: - Export shared memory state to JSON for inspection or backup - Import eBPF objects from JSON into shared memory - Run eBPF programs with performance benchmarking - Remove shared memory segments system-wide

Installation

After building bpftime, the tool is available at:

~/.bpftime/bpftimetool
# Or add to PATH
export PATH=$PATH:~/.bpftime/

Command Reference

export - Dump Shared Memory to JSON

Export all eBPF objects (programs, maps, links) from shared memory to a JSON file:

bpftimetool export <filename>

Example:

$ bpftimetool export state.json
[info] Global shm constructed. shm_open_type 1 for bpftime_maps_shm
[info] bpf_map_handler name=.rodata.str1.1 found at 3
[info] find prog fd=4 name=do_uprobe_trace
[info] bpf_perf_event_handler found at 5

The JSON file contains: - eBPF program bytecode and metadata - Map definitions and attributes - Perf event attachments - Handler file descriptors

Use cases: - Debugging runtime state - Backup before modifications - Analysis and reverse engineering - Sharing test cases

import - Load JSON into Shared Memory

Import eBPF objects from a JSON file into bpftime shared memory:

bpftimetool import <filename>

Example:

$ SPDLOG_LEVEL=Debug bpftimetool import minimal.json
[info] Global shm constructed. shm_open_type 3 for bpftime_maps_shm
[info] import handler fd 3 {"attr":{...},"name":".rodata.str1.1","type":"bpf_map_handler"}
[info] import handler type bpf_prog_handler fd 4
[info] import handler type bpf_perf_event_handler fd 5

Use cases: - Restore previous state - Load pre-configured environments - Testing and CI/CD pipelines - Cross-system deployment

run - Execute and Benchmark Programs

Run an eBPF program from shared memory with performance measurement:

bpftimetool run <id> <data_file> [repeat N] [type RUN_TYPE]

Arguments:
  id          Program ID in shared memory
  data_file   Input data file (program context)

Options:
  repeat N           Run N times and report average (default: 1)
  type RUN_TYPE      Execution mode: JIT | AOT | INTERPRET (default: JIT)

Examples:

# Run program once with JIT
bpftimetool run 4 input.bin

# Benchmark with 10000 iterations
bpftimetool run 4 input.bin repeat 10000

# Compare execution modes
bpftimetool run 4 input.bin repeat 1000 type JIT
bpftimetool run 4 input.bin repeat 1000 type AOT
bpftimetool run 4 input.bin repeat 1000 type INTERPRET

Output:

Running eBPF program with id 4 and data in file input.bin
Repeat N: 10000 with run type JIT
Time taken: 1250 ns
Return value: 0

Execution modes: - JIT: LLVM JIT compilation (fast compilation, good performance) - AOT: Pre-compiled native code (best performance, requires prior compilation) - INTERPRET: Bytecode interpreter (slowest, no compilation overhead)

remove - Clean Up Shared Memory

Remove bpftime shared memory segments system-wide:

bpftimetool remove

Warning: This destroys all loaded eBPF programs, maps, and state for all processes using bpftime.

Use cases: - Clean up after crashes - Reset test environment - Free system resources

Common Workflows

Debugging Workflow

Capture current state:
```
bpftimetool export debug_state.json
```

Inspect JSON to find program IDs and understand state:

cat debug_state.json | jq '.handlers[] | select(.type=="bpf_prog_handler")'

Test specific program:
```
bpftimetool run 4 test_input.bin
```

Performance Analysis Workflow

Compare execution modes for a program:

# Create test data
echo -n "test data" > input.bin

# Benchmark different modes
echo "=== Interpreter ==="
bpftimetool run 4 input.bin repeat 10000 type INTERPRET

echo "=== JIT ==="
bpftimetool run 4 input.bin repeat 10000 type JIT

echo "=== AOT (after compilation) ==="
bpftime-aot compile  # Compile first
bpftimetool run 4 input.bin repeat 10000 type AOT

Backup and Restore

# Backup before making changes
bpftimetool export backup_$(date +%Y%m%d_%H%M%S).json

# ... make changes ...

# Restore if needed
bpftimetool remove
bpftimetool import backup_20250930_120000.json

Cross-System Testing

Export on development machine, import on test machine:

# On dev machine
bpftimetool export production_config.json
scp production_config.json test-server:~/

# On test machine
bpftimetool import production_config.json

JSON Format

The exported JSON contains an array of handlers with this structure:

{
  "handlers": [
    {
      "fd": 3,
      "type": "bpf_map_handler",
      "name": ".rodata.str1.1",
      "attr": {
        "map_type": 2,
        "key_size": 4,
        "value_size": 21,
        "max_entries": 1,
        "flags": 128
      }
    },
    {
      "fd": 4,
      "type": "bpf_prog_handler",
      "name": "do_uprobe_trace",
      "attr": {
        "type": 0,
        "cnt": 16,
        "insns": "<hex-encoded-bytecode>",
        "attach_fds": [5]
      }
    },
    {
      "fd": 5,
      "type": "bpf_perf_event_handler",
      "attr": {
        "type": 6,
        "pid": -1,
        "_module_name": "example/minimal/victim",
        "offset": 4457
      }
    }
  ]
}

Handler Types

bpf_map_handler: eBPF maps (hash, array, ringbuf, etc.)
bpf_prog_handler: eBPF programs with bytecode
bpf_perf_event_handler: Uprobe/kprobe/tracepoint attachments
bpf_link_handler: BPF links connecting programs to hooks

Environment Variables

SPDLOG_LEVEL: Set logging level (trace, debug, info, warn, error, critical)
```
SPDLOG_LEVEL=debug bpftimetool import state.json
```

Troubleshooting

Q: "Global shm not found" error A: No bpftime processes are running. Start a process with bpftime first:

LD_PRELOAD=~/.bpftime/libbpftime-syscall-server.so your_program

Q: "Invalid id not exist" when running A: Use export to see available program IDs. The ID may have been destroyed or never created.

Q: "AOT instructions not found" error A: The program hasn't been AOT-compiled yet. Run bpftime-aot compile first.

Q: JSON import fails A: Ensure the JSON format matches the expected schema. Use export to see correct format.

Performance Notes

Export: Fast, reads shared memory without copying large data
Import: Creates all objects in shared memory, may take time for large programs
Run: Performance depends on execution mode:
INTERPRET: ~100-500ns per iteration overhead
JIT: ~10-50ns per iteration overhead (first run includes compilation)
AOT: ~5-20ns per iteration overhead (pre-compiled)

Integration with bpftime

bpftimetool works with the bpftime runtime's shared memory:

# Terminal 1: Start target with bpftime
LD_PRELOAD=~/.bpftime/libbpftime-syscall-server.so ./my_app

# Terminal 2: Inspect state
bpftimetool export current_state.json

# Terminal 3: Run benchmarks
bpftimetool run 4 test_data.bin repeat 100000 type JIT