RFC 9669: LDDW (LD | IMM | DW) subtypes via src_reg not supported (map/var/code addr)

[Alan-Jowett]

RFC 9669 Section 5.4 defines {IMM, DW, LD} (LDDW) as a family of wide-immediate instructions where src_reg selects a subtype.

In addition to the plain 64-bit immediate (src_reg == 0), RFC 9669 defines subtypes such as:

• src_reg == 0x1: dst = map_by_fd(imm)
• src_reg == 0x2: dst = map_val(map_by_fd(imm)) + next_imm
• src_reg == 0x3: dst = var_addr(imm)
• src_reg == 0x4: dst = code_addr(imm)
• src_reg == 0x5: dst = map_by_idx(imm)
• src_reg == 0x6: dst = map_val(map_by_idx(imm)) + next_imm

Current uBPF behavior:

• Appears to only accept/execute the plain 64-bit immediate form (src_reg == 0).
• RFC 9669 LDDW subtypes with src_reg != 0 are rejected and/or not executed.

Expected behavior:

• Either implement the RFC 9669 LDDW subtypes, or document uBPF’s conformance claims/limitations clearly (since these are in RFC 9669 base64).

RFC reference:

• RFC 9669 Section 5.4 and Appendix A opcode registry entries for opcode 0x18 subtypes.

[Alan-Jowett]

Feature Specification: Complete RFC 9669 LDDW Subtypes Implementation

Problem Statement

RFC 9669 Section 5.4 defines LDDW (opcode 0x18) as a family of instructions where src_reg selects the subtype. uBPF currently only implements src_reg=0 and partially supports src_reg=1,2 via the data relocation callback.

src_reg	Pseudocode	Status	Notes
0x0	dst = (next_imm << 32) | imm	✅ Full	Standard 64-bit immediate
0x1	dst = map_by_fd(imm)	⚠️ Partial	Via ubpf_register_data_relocation
0x2	dst = map_val(map_by_fd(imm)) + next_imm	⚠️ Partial	Via ubpf_register_data_relocation
0x3	dst = var_addr(imm)	❌ None	See #590
0x4	dst = code_addr(imm)	❌ None	Function pointers
0x5	dst = map_by_idx(imm)	❌ None	Index-based map lookup
0x6	dst = map_val(map_by_idx(imm)) + next_imm	❌ None	Index-based map value

---

Goals

1. Implement all RFC 9669 LDDW subtypes
2. Provide unified callback API for address resolution
3. Support in interpreter and both JIT backends
4. Clear error messages for unsupported/unresolved addresses
5. Document conformance status

---

Proposed Unified API

Rather than separate callbacks for each subtype, provide a unified resolver:

/**
 * @brief LDDW address type for resolution callback
 */
typedef enum {
    UBPF_ADDR_MAP_BY_FD = 1,      // src_reg=1: map_by_fd(imm)
    UBPF_ADDR_MAP_VAL_BY_FD = 2,  // src_reg=2: map_val(map_by_fd(imm))
    UBPF_ADDR_VARIABLE = 3,       // src_reg=3: var_addr(imm)
    UBPF_ADDR_CODE = 4,           // src_reg=4: code_addr(imm)
    UBPF_ADDR_MAP_BY_IDX = 5,     // src_reg=5: map_by_idx(imm)
    UBPF_ADDR_MAP_VAL_BY_IDX = 6, // src_reg=6: map_val(map_by_idx(imm))
} ubpf_address_type_t;

/**
 * @brief Callback to resolve LDDW addresses
 * @param context User-provided context
 * @param type Address type (from src_reg)
 * @param imm First immediate value
 * @param next_imm Second immediate value (for types 2,6)
 * @param[out] result Resolved 64-bit value to load
 * @return true if resolved, false if unknown
 */
typedef bool (*ubpf_address_resolver_t)(
    void* context,
    ubpf_address_type_t type,
    uint32_t imm,
    uint32_t next_imm,
    uint64_t* result);

/**
 * @brief Register an address resolver for LDDW subtypes
 */
int ubpf_register_address_resolver(
    struct ubpf_vm* vm,
    void* context,
    ubpf_address_resolver_t resolver);

---

Subtype Details

src_reg=1: map_by_fd(imm)

• imm contains a map file descriptor
• Result is an opaque map handle/pointer
• Used for map operations (lookup, update, delete)

src_reg=2: map_val(map_by_fd(imm)) + next_imm

• imm contains map fd, next_imm contains offset
• Result is address of map value area + offset
• Used for global data sections (.data, .rodata, .bss)

src_reg=3: var_addr(imm)

• imm contains platform variable ID
• Result is address of runtime variable
• See uBPF should support global variables in BPF programs (aka platform variables) as defined in 5.4 of BPF ISA #590 for detailed specification

src_reg=4: code_addr(imm)

• imm contains function/code identifier
• Result is address of executable code
• Used for indirect calls, function pointers

src_reg=5,6: map_by_idx / map_val(map_by_idx)

• Like 1,2 but uses map index instead of fd
• Index is into program's map table
• Useful when fds aren't stable

---

Implementation

Interpreter (ubpf_vm.c)

case EBPF_OP_LDDW: {
    struct ebpf_inst next = ubpf_fetch_instruction(vm, pc++);
    
    if (inst.src == 0) {
        // Standard 64-bit immediate
        reg[inst.dst] = u32(inst.imm) | ((uint64_t)next.imm << 32);
    } else if (inst.src >= 1 && inst.src <= 6) {
        // RFC 9669 address subtypes
        uint64_t result;
        if (!vm->address_resolver ||
            !vm->address_resolver(
                vm->address_resolver_context,
                (ubpf_address_type_t)inst.src,
                inst.imm,
                next.imm,
                &result)) {
            vm->error_printf(stderr, 
                "Failed to resolve LDDW type %d, imm=%d at PC %u\n",
                inst.src, inst.imm, cur_pc);
            return -1;
        }
        reg[inst.dst] = result;
    } else {
        vm->error_printf(stderr,
            "Unsupported LDDW src_reg %d at PC %u\n", inst.src, cur_pc);
        return -1;
    }
    break;
}

JIT Backends

For JIT, addresses are resolved at compile time and embedded as immediates:

case EBPF_OP_LDDW: {
    struct ebpf_inst inst2 = ubpf_fetch_instruction(vm, ++i);
    
    if (inst.src == 0) {
        uint64_t imm = (uint32_t)inst.imm | ((uint64_t)inst2.imm << 32);
        emit_load_imm(state, dst, imm);
    } else if (inst.src >= 1 && inst.src <= 6) {
        uint64_t result;
        if (!vm->address_resolver(...)) {
            *errmsg = ubpf_error("Failed to resolve LDDW type %d", inst.src);
            return -1;
        }
        emit_load_imm(state, dst, result);
    }
    break;
}

---

Backward Compatibility

The existing ubpf_register_data_relocation API should continue to work:

1. If address_resolver is set, use it for all subtypes
2. If only data_relocation_function is set, use it for src_reg=1,2 (legacy)
3. Both can coexist - new resolver takes precedence

---

Files to Modify

File	Changes
vm/inc/ubpf.h	Add address type enum and resolver API
vm/ubpf_int.h	Add resolver fields to VM struct
vm/ubpf_vm.c	Implement resolver, update LDDW handling
vm/ubpf_jit_x86_64.c	Update LDDW for all subtypes
vm/ubpf_jit_arm64.c	Update LDDW for all subtypes
vm/ubpf_loader.c	Handle relocations via resolver

---

Acceptance Criteria

• All 7 LDDW subtypes (0-6) handled
• Unified address resolver API implemented
• Interpreter supports all subtypes
• x86_64 JIT supports all subtypes
• ARM64 JIT supports all subtypes
• Backward compatible with ubpf_register_data_relocation
• Clear error messages for unresolved addresses
• Tests for each subtype
• RFC 9669 conformance documented

---

Test Cases

// Test: Map by fd (src_reg=1)
bool resolver(void* ctx, ubpf_address_type_t type, 
              uint32_t imm, uint32_t next_imm, uint64_t* result) {
    if (type == UBPF_ADDR_MAP_BY_FD && imm == 1) {
        *result = (uint64_t)&my_map;
        return true;
    }
    return false;
}

// Test: Variable address (src_reg=3)
// ... (see #590)

// Test: Code address (src_reg=4)
bool resolver(...) {
    if (type == UBPF_ADDR_CODE && imm == 0) {
        *result = (uint64_t)&my_function;
        return true;
    }
    return false;
}

---

Conformance Documentation

Add to README or docs:

## RFC 9669 Conformance

### LDDW Subtypes (Section 5.4)
| src_reg | Name | Status |
|---------|------|--------|
| 0 | 64-bit immediate | Supported |
| 1 | map_by_fd | Supported via address_resolver |
| 2 | map_val(map_by_fd) | Supported via address_resolver |
| 3 | var_addr | Supported via address_resolver |
| 4 | code_addr | Supported via address_resolver |
| 5 | map_by_idx | Supported via address_resolver |
| 6 | map_val(map_by_idx) | Supported via address_resolver |

Note: Subtypes 1-6 require the host to register an address resolver
via `ubpf_register_address_resolver()`.

---

Related Issues

• uBPF should support global variables in BPF programs (aka platform variables) as defined in 5.4 of BPF ISA #590: Platform variables (src_reg=3) - Subset of this issue
• Add support for .maps section #130: .maps section support - Related to map addressing

---

References

• RFC 9669 Section 5.4: https://www.rfc-editor.org/rfc/rfc9669.html#section-5.4
• RFC 9669 Appendix A: Opcode registry
• Current implementation: vm/ubpf_vm.c:1191-1192