uBPF should support global variables in BPF programs (aka platform variables) as defined in 5.4 of BPF ISA

[Alan-Jowett]

The BPF ISA defines additional 64bit immediate load instructions. uBPF should add support for type 3 at a minimum.

5.4.  64-bit immediate instructions

   Instructions with the IMM 'mode' modifier use the wide instruction
   encoding defined in Instruction encoding (Section 3), and use the
   'src_reg' field of the basic instruction to hold an opcode subtype.

   The following table defines a set of {IMM, DW, LD} instructions with
   opcode subtypes in the 'src_reg' field, using new terms such as "map"
   defined further below:

    +=========+================================+==========+==========+
    | src_reg | pseudocode                     | imm type | dst type |
    +=========+================================+==========+==========+
    | 0x0     | dst = (next_imm << 32) | imm   | integer  | integer  |
    +---------+--------------------------------+----------+----------+
    | 0x1     | dst = map_by_fd(imm)           | map fd   | map      |
    +---------+--------------------------------+----------+----------+
    | 0x2     | dst = map_val(map_by_fd(imm))  | map fd   | data     |
    |         | + next_imm                     |          | address  |
    +---------+--------------------------------+----------+----------+
    | 0x3     | dst = var_addr(imm)            | variable | data     |
    |         |                                | id       | address  |
    +---------+--------------------------------+----------+----------+
    | 0x4     | dst = code_addr(imm)           | integer  | code     |
    |         |                                |          | address  |
    +---------+--------------------------------+----------+----------+
    | 0x5     | dst = map_by_idx(imm)          | map      | map      |
    |         |                                | index    |          |
    +---------+--------------------------------+----------+----------+
    | 0x6     | dst = map_val(map_by_idx(imm)) | map      | data     |
    |         | + next_imm                     | index    | address  |
    +---------+--------------------------------+----------+----------+

                 Table 12: 64-bit immediate instructions

[Alan-Jowett]

microsoft/ebpf-for-windows#3958

[Alan-Jowett]

vbpf/prevail#763

[Alan-Jowett]

Feature Specification: Platform Variables (LDDW src_reg=3) per BPF ISA Section 5.4

Problem Statement

The BPF ISA (RFC 9669) Section 5.4 defines 64-bit immediate load instructions with different src_reg subtypes. uBPF currently only fully implements src_reg=0 (standard 64-bit immediate):

src_reg	Pseudocode	Current Status
0x0	dst = (next_imm << 32) | imm	✅ Implemented
0x1	dst = map_by_fd(imm)	⚠️ Via relocation callback
0x2	dst = map_val(map_by_fd(imm)) + next_imm	⚠️ Via relocation callback
0x3	dst = var_addr(imm)	❌ Not implemented
0x4	dst = code_addr(imm)	❌ Not implemented
0x5	dst = map_by_idx(imm)	❌ Not implemented
0x6	dst = map_val(map_by_idx(imm)) + next_imm	❌ Not implemented

Priority: src_reg=3 (platform/global variables) is needed by ebpf-for-windows.

---

Use Case: Platform Variables

Platform variables are global variables exposed by the BPF runtime to programs:

// In BPF program
extern uint64_t bpf_get_current_pid_tgid __attribute__((section(".bss")));
extern uint64_t bpf_ktime_ns __attribute__((section(".bss")));

// Compiled to:
// lddw r0, var_addr(0)   ; src_reg=3, imm=variable_id

The runtime provides the address of these variables, allowing BPF programs to read platform-specific data without helper calls.

---

Goals

1. Implement src_reg=3 (var_addr) for platform variable access
2. Add callback API for host to provide variable addresses
3. Support in interpreter and both JIT backends
4. Validate variable IDs during load

---

Proposed API

/**
 * @brief Callback to resolve platform variable ID to address.
 * @param context User-provided context
 * @param var_id Variable identifier from instruction immediate
 * @param[out] address Resolved address of the variable
 * @return true if variable exists, false otherwise
 */
typedef bool (*ubpf_var_resolver_t)(
    void* context,
    uint32_t var_id,
    uint64_t* address);

/**
 * @brief Register a platform variable resolver.
 * @param vm The VM instance
 * @param context User context passed to resolver
 * @param resolver Callback function
 * @return 0 on success, -1 on error
 */
int ubpf_register_variable_resolver(
    struct ubpf_vm* vm,
    void* context,
    ubpf_var_resolver_t resolver);

---

Implementation Details

Interpreter (ubpf_vm.c)

case EBPF_OP_LDDW:
    if (inst.src == 0) {
        // Standard 64-bit immediate
        reg[inst.dst] = u32(inst.imm) | ((uint64_t)next_inst.imm << 32);
    } else if (inst.src == 3) {
        // Platform variable
        uint64_t var_addr;
        if (!vm->var_resolver || 
            !vm->var_resolver(vm->var_resolver_context, inst.imm, &var_addr)) {
            vm->error_printf(stderr, "Unknown variable ID %d at PC %u\n", inst.imm, pc);
            return -1;
        }
        reg[inst.dst] = var_addr;
    } else if (inst.src == 1 || inst.src == 2) {
        // Map relocations - already handled by loader
        reg[inst.dst] = u32(inst.imm) | ((uint64_t)next_inst.imm << 32);
    } else {
        vm->error_printf(stderr, "Unsupported LDDW src_reg %d at PC %u\n", inst.src, pc);
        return -1;
    }
    break;

JIT Backends

For JIT, variable addresses can be resolved at compile time:

// In ubpf_jit_x86_64.c
case EBPF_OP_LDDW:
    if (inst.src == 3) {
        uint64_t var_addr;
        if (!vm->var_resolver(vm->var_resolver_context, inst.imm, &var_addr)) {
            *errmsg = ubpf_error("Unknown variable ID %d", inst.imm);
            return -1;
        }
        emit_load_imm(state, dst, var_addr);
    }
    // ...

Loader (ubpf_loader.c)

For ELF loading, variable relocations may come through the relocation section:

// In relocation handling
if (applies_to_inst->src == 3) {
    // Variable relocation
    // The immediate contains the variable ID
    // Call var_resolver to get address and patch instruction
}

---

VM Structure Changes

// In ubpf_int.h
struct ubpf_vm {
    // ... existing fields ...
    
    // Platform variable support
    ubpf_var_resolver_t var_resolver;
    void* var_resolver_context;
};

---

Files to Modify

File	Changes
vm/inc/ubpf.h	Add ubpf_register_variable_resolver() API
vm/ubpf_int.h	Add resolver fields to struct
vm/ubpf_vm.c	Implement resolver registration, update LDDW handling
vm/ubpf_jit_x86_64.c	Update LDDW for src_reg=3
vm/ubpf_jit_arm64.c	Update LDDW for src_reg=3
vm/ubpf_loader.c	Handle variable relocations in ELF

---

Acceptance Criteria

• ubpf_register_variable_resolver() API implemented
• Interpreter handles src_reg=3 LDDW instructions
• x86_64 JIT handles src_reg=3 LDDW instructions
• ARM64 JIT handles src_reg=3 LDDW instructions
• Unknown variable ID produces clear error
• ELF loader handles variable relocations
• Tests cover variable resolution
• Documentation updated

---

Test Cases

// Test: Basic variable resolution
void test_variable_resolution() {
    uint64_t my_var = 0x1234567890ABCDEF;
    
    bool resolver(void* ctx, uint32_t id, uint64_t* addr) {
        if (id == 0) {
            *addr = (uint64_t)&my_var;
            return true;
        }
        return false;
    }
    
    struct ubpf_vm* vm = ubpf_create();
    ubpf_register_variable_resolver(vm, NULL, resolver);
    
    // Program: lddw r0, var_addr(0); ldxdw r0, [r0]; exit
    // Expected: Returns value of my_var
}

// Test: Unknown variable ID
void test_unknown_variable() {
    struct ubpf_vm* vm = ubpf_create();
    // No resolver registered
    
    // Program with var_addr(0) should fail
}

---

Future Work

After src_reg=3, consider implementing:

• src_reg=4 (code_addr) - For function pointers
• src_reg=5,6 (map_by_idx) - Alternative map addressing

---

Related Issues

• ebpf-for-windows: bpf2c and eBPF-for-Windows should support global variables in BPF programs (aka platform variables) as defined in 5.4 of BPF ISA microsoft/ebpf-for-windows#3958
• ebpf-verifier: Support additional 64bit immediate instruction modes vbpf/prevail#763

---

References

• BPF ISA Section 5.4: https://www.rfc-editor.org/rfc/rfc9669.html#section-5.4
• Current LDDW handling: vm/ubpf_vm.c:1191-1192
• Instruction validation: vm/ubpf_instruction_valid.c:562-570