# VM Interface Definition in bpftime: Header Location and API Reference

> Locate the bpftime VM interface definition in ebpf-vm.h to manage eBPF program creation, configuration, and execution across pluggable backends. Find the API reference here.

- Repository: [eunomia-bpf/bpftime](https://github.com/eunomia-bpf/bpftime)
- Tags: api-reference
- Published: 2026-03-01

---

**The core VM interface definition in bpftime is located in [`vm/vm-core/include/ebpf-vm.h`](https://github.com/eunomia-bpf/bpftime/blob/main/vm/vm-core/include/ebpf-vm.h), which declares the opaque `struct ebpf_vm` type and all API functions for creating, configuring, and executing eBPF programs across pluggable backends.**

The bpftime project provides a high-performance userspace eBPF runtime with pluggable VM backends. Understanding the **VM interface definition in bpftime** is essential for developers integrating custom VM implementations or extending the runtime functionality. This guide identifies the exact header location and explains the stable C API contract used by LLVM-JIT, ubpf, and other backends.

## Location of the VM Interface Header and Implementation Files

The primary **VM interface definition** resides in the public header file [`vm/vm-core/include/ebpf-vm.h`](https://github.com/eunomia-bpf/bpftime/blob/main/vm/vm-core/include/ebpf-vm.h) within the `eunomia-bpf/bpftime` repository. This header defines the opaque `struct ebpf_vm` type and serves as the stable contract between VM implementations and the rest of the system.

The corresponding implementation is found in [`vm/vm-core/src/ebpf-vm.cpp`](https://github.com/eunomia-bpf/bpftime/blob/main/vm/vm-core/src/ebpf-vm.cpp), which contains the concrete logic for VM lifecycle management, bytecode loading, and execution. For legacy code compatibility, a thin wrapper is provided in [`vm/compat/include/bpftime_vm_compat.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/vm/compat/include/bpftime_vm_compat.hpp). Additional reference material is available in [`vm/README.md`](https://github.com/eunomia-bpf/bpftime/blob/main/vm/README.md), and a minimal working example is located at [`vm/example/main.c`](https://github.com/eunomia-bpf/bpftime/blob/main/vm/example/main.c).

## Core API Functions and Data Structures

The header exposes a C-based API that abstracts different VM backends. All functions operate on the opaque `struct ebpf_vm` pointer, allowing the runtime to switch between implementations like the LLVM-JIT or ubpf without changing calling code.

### VM Lifecycle Management

- **`struct ebpf_vm *ebpf_create(const char *vm_name);`** — Allocates a new VM instance. Pass `"llvm"` for the LLVM-JIT backend or `"ubpf"` for the interpreter.
- **`void ebpf_destroy(struct ebpf_vm *vm);`** — Releases all resources associated with a VM instance.

### Program Loading and Execution

- **`int ebpf_load(struct ebpf_vm *vm, const void *code, uint32_t code_len, char **errmsg);`** — Loads raw eBPF bytecode into the VM.
- **`int ebpf_exec(const struct ebpf_vm *vm, void *mem, size_t mem_len, uint64_t *bpf_return_value);`** — Interprets and executes the loaded program against the provided memory region.

### JIT Compilation and Helper Registration

- **`ebpf_jit_fn ebpf_compile(struct ebpf_vm *vm, char **errmsg);`** — JIT-compiles the loaded program to native machine code, returning a function pointer of type `ebpf_jit_fn`.
- **`int ebpf_register(struct ebpf_vm *vm, unsigned int index, const char *name, void *fn);`** — Registers external helper functions accessible from eBPF programs.
- **`int ebpf_load_aot_object(struct ebpf_vm *vm, const void *buf, size_t buf_len);`** — Loads ahead-of-time compiled objects.
- **`void ebpf_set_lddw_helpers(...);`** — Attaches helpers required for the `lddw` instruction.
- **`int ebpf_set_pointer_secret(struct ebpf_vm *vm, uint64_t secret);`** — Sets an optional secret for return-oriented programming mitigation.

## Practical Code Examples

The following examples demonstrate how to use the **VM interface definition in bpftime** to create a VM, load bytecode, and execute programs.

### Interpreter Mode Execution

```c
#include "vm/vm-core/include/ebpf-vm.h"

int main() {
    /* Create a VM instance using the LLVM-JIT backend */
    struct ebpf_vm *vm = ebpf_create("llvm");
    if (!vm) return 1;

    /* Register helper functions */
    ebpf_register(vm, 1, "my_print", (void *)my_print);

    /* Load raw eBPF bytecode */
    const void *code = ...;          /* pointer to bytecode buffer */
    uint32_t code_len = ...;         /* length in bytes */
    char *errmsg = NULL;
    if (ebpf_load(vm, code, code_len, &errmsg) < 0) {
        fprintf(stderr, "load error: %s\n", errmsg);
        free(errmsg);
        ebpf_destroy(vm);
        return 1;
    }

    /* Execute with a memory region */
    uint8_t mem[EBPF_STACK_SIZE] = {0};
    uint64_t ret_val;
    if (ebpf_exec(vm, mem, sizeof(mem), &ret_val) < 0) {
        fprintf(stderr, "execution failed\n");
    } else {
        printf("program returned: %llu\n", (unsigned long long)ret_val);
    }

    ebpf_destroy(vm);
    return 0;
}

```

### JIT Compilation and Native Execution

```c
#include "vm/vm-core/include/ebpf-vm.h"

int main() {
    struct ebpf_vm *vm = ebpf_create("llvm");
    
    /* Load bytecode as shown in previous example */
    /* ... loading code ... */
    
    char *errmsg = NULL;
    ebpf_jit_fn fn = ebpf_compile(vm, &errmsg);
    if (!fn) {
        fprintf(stderr, "jit compile error: %s\n", errmsg);
        free(errmsg);
        ebpf_destroy(vm);
        return 1;
    }

    /* Call the JIT-compiled function directly */
    uint8_t mem[EBPF_STACK_SIZE] = {0};
    uint64_t result = fn(mem, sizeof(mem));
    printf("JIT result = %llu\n", (unsigned long long)result);

    ebpf_destroy(vm);
    return 0;
}

```

## Summary

- The **VM interface definition in bpftime** is declared in [`vm/vm-core/include/ebpf-vm.h`](https://github.com/eunomia-bpf/bpftime/blob/main/vm/vm-core/include/ebpf-vm.h), with implementation in [`vm/vm-core/src/ebpf-vm.cpp`](https://github.com/eunomia-bpf/bpftime/blob/main/vm/vm-core/src/ebpf-vm.cpp).
- The interface uses an opaque `struct ebpf_vm` type to abstract multiple backends (LLVM-JIT, ubpf).
- Key functions include `ebpf_create()`, `ebpf_load()`, `ebpf_exec()`, and `ebpf_compile()` for JIT.
- A compatibility wrapper exists in [`vm/compat/include/bpftime_vm_compat.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/vm/compat/include/bpftime_vm_compat.hpp) for legacy integrations.

## Frequently Asked Questions

### Where is the VM interface definition located in bpftime?

The core definition is in [`vm/vm-core/include/ebpf-vm.h`](https://github.com/eunomia-bpf/bpftime/blob/main/vm/vm-core/include/ebpf-vm.h). This header declares the `struct ebpf_vm` type and all public API functions. The implementation resides in [`vm/vm-core/src/ebpf-vm.cpp`](https://github.com/eunomia-bpf/bpftime/blob/main/vm/vm-core/src/ebpf-vm.cpp), while [`vm/compat/include/bpftime_vm_compat.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/vm/compat/include/bpftime_vm_compat.hpp) provides backward compatibility.

### What functions are defined in the bpftime VM interface?

The interface defines lifecycle functions (`ebpf_create`, `ebpf_destroy`), loading functions (`ebpf_load`, `ebpf_load_aot_object`), execution functions (`ebpf_exec`, `ebpf_compile`), and helper management (`ebpf_register`, `ebpf_set_lddw_helpers`).

### How do I JIT compile an eBPF program using bpftime?

First create a VM with `ebpf_create()`, load bytecode with `ebpf_load()`, then call `ebpf_compile()` to obtain an `ebpf_jit_fn` function pointer. You can then call this pointer directly with your memory buffer to execute native code.

### Is there a compatibility layer for older bpftime VM APIs?

Yes. The file [`vm/compat/include/bpftime_vm_compat.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/vm/compat/include/bpftime_vm_compat.hpp) provides a thin wrapper that exposes the modern [`ebpf-vm.h`](https://github.com/eunomia-bpf/bpftime/blob/main/ebpf-vm.h) interface to legacy code written against older bpftime VM APIs, ensuring backward compatibility during migrations.