Add support for .maps section

[dthaler]

Regarding the doc in progress at ietf-wg-bpf/ebpf-docs#4, Quentin wrote:

libbpf v1.0 (see dropping support for maps section in favour of .maps (Andrii's blog)

cilium/ebpf seems to read both types (and also data sections), which seems reasonable behavior:
https://github.com/cilium/ebpf/blob/master/elf_reader.go#L125

Aya also seems to read both types:
https://github.com/aya-rs/aya/blob/main/aya/src/obj/mod.rs#L1024

redbpf (which unlike Aya is listed as Major) only supports "maps":
https://github.com/foniod/redbpf/blob/main/redbpf/src/lib.rs#L1544

[Alan-Jowett]

Feature Specification: Support for .maps Section (BTF Map Definitions)

Problem Statement

The ubpf ELF loader currently handles data relocations via a user-provided callback (ubpf_register_data_relocation), but does not natively understand map definitions. Modern BPF toolchains (libbpf v1.0+, cilium/ebpf, Aya) use a BTF-based map definition format in the .maps section that replaces the legacy SEC("maps") approach.

Legacy format (deprecated in libbpf v1.0+):

struct bpf_map_def SEC("maps") my_map = {
    .type = BPF_MAP_TYPE_HASH,
    .key_size = sizeof(int),
    .value_size = sizeof(long),
    .max_entries = 1024,
};

Modern BTF format:

struct {
    __uint(type, BPF_MAP_TYPE_HASH);
    __type(key, int);
    __type(value, long);
    __uint(max_entries, 1024);
} my_map SEC(".maps");

---

Background

Loader	Legacy maps	BTF .maps	Notes
libbpf v1.0+	❌ Rejected	✅ Required	Breaking change
cilium/ebpf	✅ Supported	✅ Supported	Both work
Aya (Rust)	✅ Supported	✅ Supported	Both work
redbpf	✅ Supported	❌	Legacy only
ubpf	⚠️ Callback	❌	Needs implementation

---

Goals

1. Parse .maps ELF section containing BTF-defined maps
2. Extract map metadata (type, key/value size, max_entries, flags)
3. Provide map information to the host application via callback or data structure
4. Support both legacy maps section and modern .maps section
5. Optional: Parse BTF section for full type information

---

Proposed Design

Option A: Enhanced Data Relocation Callback (Minimal Change)

Extend the existing ubpf_data_relocation callback to include map definition info:

typedef struct ubpf_map_def {
    uint32_t type;
    uint32_t key_size;
    uint32_t value_size;
    uint32_t max_entries;
    uint32_t map_flags;
} ubpf_map_def;

typedef uint64_t (*ubpf_map_relocation)(
    void* user_context,
    const char* map_name,
    const ubpf_map_def* map_def,  // NULL if not parseable
    uint64_t symbol_offset);

int ubpf_register_map_relocation(
    struct ubpf_vm* vm, 
    void* user_context, 
    ubpf_map_relocation relocation);

Pros: Minimal API change, backward compatible
Cons: Host still needs to create/manage maps

---

Option B: Map Enumeration API (Recommended)

Add API to enumerate maps after loading:

// Map definition structure
typedef struct ubpf_map_info {
    const char* name;
    uint32_t type;
    uint32_t key_size;
    uint32_t value_size;
    uint32_t max_entries;
    uint32_t map_flags;
    uint64_t section_offset;  // For linking
} ubpf_map_info;

// Get number of maps in loaded program
int ubpf_get_map_count(struct ubpf_vm* vm);

// Get map info by index
int ubpf_get_map_info(struct ubpf_vm* vm, int index, ubpf_map_info* info);

// Set map file descriptor/handle after host creates map
int ubpf_set_map_fd(struct ubpf_vm* vm, int index, uint64_t fd_or_handle);

Workflow:

1. Load ELF with ubpf_load_elf()
2. Enumerate maps with ubpf_get_map_count() / ubpf_get_map_info()
3. Host creates maps based on info
4. Host calls ubpf_set_map_fd() to link
5. Run program

Pros: Clean separation, host has full control
Cons: More API surface

---

Option C: Map Callback During Load

Callback invoked during ELF loading for each map:

typedef uint64_t (*ubpf_map_create_fn)(
    void* context,
    const char* name,
    uint32_t type,
    uint32_t key_size,
    uint32_t value_size,
    uint32_t max_entries,
    uint32_t flags);

int ubpf_set_map_creator(struct ubpf_vm* vm, void* ctx, ubpf_map_create_fn fn);

Pros: Simple, single callback
Cons: Less flexible than enumeration

---

Implementation Details

Parsing .maps Section

The .maps section in BTF format contains structs where field names encode map properties:

.maps section layout:
  - Contains variable-sized map definition structs
  - Each struct is a global variable with SEC(".maps") attribute
  - BTF section contains type info for each struct

Without BTF parsing (simpler):

• Use symbol table to find map names
• Use bpf_map_def struct size to iterate (legacy format)
• Fall back to data relocation callback for modern format

With BTF parsing (complete):

• Parse .BTF section
• Find map struct types
• Extract __uint(type, ...), __type(key, ...), etc. from BTF

---

Section Detection

// In ubpf_loader.c
for (i = 0; i < section_count; i++) {
    const char* section_name = strtab_data + sections[i].shdr->sh_name;
    
    if (strcmp(section_name, ".maps") == 0) {
        // Modern BTF-style maps
        parse_btf_maps(vm, &sections[i], ...);
    } else if (strcmp(section_name, "maps") == 0) {
        // Legacy bpf_map_def style
        parse_legacy_maps(vm, &sections[i], ...);
    }
}

---

API Changes

// New types
typedef struct ubpf_map_info {
    const char* name;
    uint32_t type;
    uint32_t key_size;
    uint32_t value_size;
    uint32_t max_entries;
    uint32_t map_flags;
} ubpf_map_info;

// New functions
int ubpf_get_map_count(struct ubpf_vm* vm);
int ubpf_get_map_info(struct ubpf_vm* vm, int index, ubpf_map_info* info);
int ubpf_set_map_value(struct ubpf_vm* vm, int index, uint64_t value);

---

Files to Modify

File	Changes
vm/ubpf_loader.c	Add .maps section parsing
vm/ubpf_int.h	Add map storage to struct ubpf_vm
vm/inc/ubpf.h	Add new API declarations
vm/ubpf_vm.c	Implement new API functions

---

Acceptance Criteria

• .maps section is detected and parsed during ELF load
• Legacy maps section continues to work
• Map definitions can be enumerated via API
• Map values can be set for relocation resolution
• Existing ubpf_register_data_relocation still works
• Tests cover:
  • Legacy SEC("maps") format
  • Modern SEC(".maps") format
  • Mixed sections
  • Maps with various types (HASH, ARRAY, etc.)
  • Maps referenced via LDDW instructions

---

Test Cases

// Test: Enumerate maps from .maps section
void test_maps_section() {
    struct ubpf_vm* vm = ubpf_create();
    
    // Load ELF with .maps section
    ubpf_load_elf(vm, elf_data, elf_size, &errmsg);
    
    int count = ubpf_get_map_count(vm);
    assert(count == 2);  // Expected 2 maps
    
    ubpf_map_info info;
    ubpf_get_map_info(vm, 0, &info);
    assert(strcmp(info.name, "my_hash") == 0);
    assert(info.type == BPF_MAP_TYPE_HASH);
    assert(info.key_size == 4);
    assert(info.value_size == 8);
    assert(info.max_entries == 1024);
    
    // Set map handle
    ubpf_set_map_value(vm, 0, (uint64_t)my_map_handle);
    
    ubpf_destroy(vm);
}

---

BTF Parsing (Future Enhancement)

Full BTF support would enable:

• Accurate key/value type information
• CO-RE (Compile Once, Run Everywhere) support
• Function prototype validation
• Map-in-map support

This could be a follow-up issue as it's a significant undertaking.

---

References

• BTF-defined BPF map definitions (LWN)
• libbpf v1.0 migration notes
• cilium/ebpf ELF reader
• Aya map parsing
• Current ubpf loader: vm/ubpf_loader.c
• Data relocation API: vm/inc/ubpf.h lines 493-521