Support configurable instruction limits beyond 65,536

[Copilot]

Summary

This PR implements support for configurable instruction count limits in ubpf, allowing programs with more than 65,536 instructions to be loaded and executed.

Implementation Complete ✅

Phase 1: Type Changes (ABI-Breaking) ✅

• Changed num_insts from uint16_t to uint32_t in struct ubpf_vm
• Added max_insts field to struct ubpf_vm for runtime configuration
• Updated all functions using uint16_t for instruction counts/PC to uint32_t
• Updated stack_usage_calculator_t typedef to use uint32_t for PC parameter
• Updated all test files using stack_usage_calculator

Phase 2: Runtime Configuration API ✅

• Added ubpf_set_max_instructions() function to allow runtime configuration
• Default limit remains 65,536 for backward compatibility
• Function fails if called after code is already loaded
• Passing 0 resets to default limit

Phase 3: Dynamic Memory Management ✅

• Updated JIT state initialization to allocate arrays based on actual program size
• Arrays sized at 2x instruction count + 64 to account for extra JIT relocations
• Added overflow checks to prevent integer overflow in all calloc operations
• Reduces memory usage for small programs while supporting larger programs

Phase 4: Testing ✅

• Added ubpf_test_large_program: Validates loading, JIT compilation, and execution of 66,000 instruction programs
• Added ubpf_test_max_insts_api: Tests boundary conditions (65,535/65,536), API behavior, and limit enforcement
• All 23 tests passing (21 existing + 2 new)

Phase 5: Code Review ✅

• Completed code review and addressed all feedback:
  • Added overflow checks for 32-bit systems in all calloc operations
  • Improved large program test to actually JIT compile and execute programs
  • Fixed documentation to match implementation
  • Added result verification to test

Key Features

1. Programs > 65,536 instructions now supported with ubpf_set_max_instructions()
2. Backward compatible - default limit unchanged at 65,536
3. Memory efficient - dynamic sizing reduces waste for small programs
4. Safe - includes comprehensive overflow checks and validation
5. Tested - large programs validated through JIT compilation and execution

Testing

# All tests pass
ctest --test-dir build
# 100% tests passed, 0 tests failed out of 23

Backward Compatibility

• Default instruction limit remains 65,536
• No changes to existing API signatures (only additions)
• Compile-time UBPF_MAX_INSTS can still be overridden

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Maximum ebpf instruction count</issue_title>
<issue_description>Linux apparently has a limit of INT_MAX instructions since 5.2.
Earlier versions had a limit of 4096 instructions.

The ubpf jitter is currently capped at 64k of machine code.
The ubpf interpreter is currently capped at UINT32_MAX of bytes (i.e., UINT32_MAX / 8 instructions).
These are higher than the old Linux limit of 4096, but lower than the newer limit of INT_MAX instructions.</issue_description>

Comments on the Issue (you are @copilot in this section)

@Alan-Jowett ## Feature Specification: Configurable Instruction Count Limits

Problem Statement

The current ubpf implementation has several hardcoded limits related to instruction counts that may not align with Linux kernel BPF limits or user requirements:

Limit	Current Value	Linux 5.2+	Issue
Max BPF instructions	65,536 (UBPF_MAX_INSTS)	~1 million (INT_MAX)	Programs > 64K fail
JIT buffer size	64KB (DEFAULT_JITTER_BUFFER_SIZE)	Dynamic	Large programs fail JIT
num_insts field	uint16_t (max 65,535)	N/A	Cannot store > 64K

Key Limitation: The num_insts field in struct ubpf_vm is a uint16_t, which fundamentally caps the instruction count at 65,535 regardless of other settings.

---

Background: Linux Kernel Limits

Version	Instruction Limit	Notes
< 4.15	4,096	Original limit
4.15-5.1	1,000,000	Increased for complex programs
5.2+	~2.1 billion (INT_MAX)	Effectively unlimited

Real-world BPF programs:

• Simple XDP: ~100-500 instructions
• Complex networking: 5,000-50,000 instructions
• Cilium/eBPF-based CNI: Can exceed 100,000 instructions
• BPF CO-RE with BTF: Often 10,000+ instructions

---

Goals

1. Allow programs with > 65,536 instructions
2. Make instruction limit configurable at compile time and/or runtime
3. Dynamically size JIT buffer based on program size
4. Maintain backward compatibility (default 64K limit)
5. Allow users to set lower limits for resource-constrained environments

---

Proposed Changes

1. Change num_insts to uint32_t

File: vm/ubpf_int.h

struct ubpf_vm
{
    struct ebpf_inst* insts;
    uint32_t num_insts;  // Changed from uint16_t
    // ...
};

Impact: This is an ABI-breaking change but necessary to support > 64K instructions.

---

2. Make UBPF_MAX_INSTS Configurable

File: vm/inc/ubpf.h (already partially done)

#if !defined(UBPF_MAX_INSTS)
#define UBPF_MAX_INSTS 65536  // Can be overridden at compile time
#endif

Add runtime configuration:

/**
 * @brief Set the maximum number of instructions allowed in a program.
 * @param vm The VM instance
 * @param max_insts Maximum instruction count (0 = use compile-time default)
 * @return 0 on success, -1 on error
 */
int ubpf_set_max_instructions(struct ubpf_vm* vm, uint32_t max_insts);

---

3. Dynamic JIT Buffer Sizing

Current code: vm/ubpf_vm.c:125

vm->jitter_buffer_size = DEFAULT_JITTER_BUFFER_SIZE;  // Fixed 64KB

Proposed approach:

// Estimate: ~20-50 bytes of x86 code per BPF instruction (conservative)
#define JIT_BYTES_PER_INST 50

size_t estimate_jit_buffer_size(uint32_t num_insts) {
    size_t estimated = (size_t)num_insts * JIT_BYTES_PER_INST;
    // Add overhead for prologue/epilogue/helper table
    estimated += 4096;
    // Round up to page size
    size_t page_size = 4096;
    return (estimated + page_size - 1) & ~(page_size - 1);
}

Alternative: Allow retry with larger buffer if initial allocation fails.

---

4. Update Data Structures Using UBPF_MAX_INSTS

Several arrays are sized based on UBPF_MAX_INSTS:

File: vm/ubpf_jit_support.c

state->pc_locs = calloc(UBPF_MAX_INSTS + 1, sizeof(state->pc_locs[0]));
state->jumps = calloc(UBPF_MAX_INSTS, sizeof(state->jumps[0]));
state->loads = calloc(UBPF_MAX_INSTS, sizeof(state->loads[0]));
state->leas = calloc(UBPF_MAX_INSTS, sizeof(state->leas[0]));
state->local_calls = calloc(UBPF_MAX_INSTS, sizeof(state->local_calls[0]));

Proposed: Size based on actual num_insts from loaded program:

state->pc_locs = calloc(vm->num_insts + 1, sizeof(state->pc_locs[0]));
// etc.

File: vm/ubpf_vm.c

vm->local_func_stack_usage = calloc(UBPF_MAX_INSTS, sizeof(struct ubpf_stack_usage));

Proposed: Size based on actual program, or use sparse storage.

---

API Changes

// New configuration function
int ubpf_set_max_instructions(struct ubpf_vm* vm, uint32_t max_insts);

// Existing (already implemented for JIT buffer)
int ubpf_set_jit_code_size(struct ubpf_vm* vm, size_t code_size);

// Optional: Query current limits
int ubpf_get_max_instructions(struct ubpf_vm* vm, uint32_t* max_i...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

- Fixes iovisor/ubpf#108

<!-- START COPILOT CODING AGENT TIPS -->
---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs.

[Copilot]

Pull request overview

This pull request adds support for configurable instruction limits beyond the previous hard limit of 65,536 instructions. The changes address a hard-coded limitation where the num_insts field was a uint16_t, preventing programs with more than 65,535 instructions from being loaded.

Changes:

• Changed num_insts from uint16_t to uint32_t in struct ubpf_vm and added a configurable max_insts field
• Updated function signatures to use uint32_t for program counter parameters (fetch/store instructions, stack usage calculator)
• Added new API ubpf_set_max_instructions() to configure limits at runtime
• Modified JIT array allocations to be dynamically sized based on program size (2x + 64) instead of fixed UBPF_MAX_INSTS
• Added overflow protection for large program JIT compilation
• Added comprehensive tests for API boundary conditions and large program loading

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
vm/ubpf_vm.c	Updated allocations to use vm->max_insts; changed validation to check vm->max_insts; updated fetch/store/stack function signatures
vm/ubpf_jit.c	Added ubpf_set_max_instructions() API implementation with reallocation logic
vm/ubpf_int.h	Changed num_insts to uint32_t, added max_insts field; updated internal function signatures
vm/inc/ubpf.h	Updated stack_usage_calculator_t signature; added ubpf_set_max_instructions() API documentation
vm/ubpf_jit_support.c	Implemented dynamic JIT array sizing with overflow checks; added vm parameter to initialize_jit_state_result
vm/ubpf_jit_support.h	Added max_insts field to jit_state; updated initialize_jit_state_result signature
vm/ubpf_jit_x86_64.c	Updated comparisons to use state->max_insts; passed vm to initialize_jit_state_result
vm/ubpf_jit_arm64.c	Passed vm to initialize_jit_state_result
vm/test.c	Updated stack_usage_calculator signature to use uint32_t pc
custom_tests/srcs/ubpf_test_large_program.cc	New test validating loading of 66,000 instruction programs
custom_tests/srcs/ubpf_test_max_insts_api.cc	New test validating API boundary conditions and behavior
custom_tests/srcs/ubpf_test_*.cc	Updated stack_usage_calculator signatures in existing tests
custom_tests/descrs/*.md	Added test descriptions for new tests

[Alan-Jowett]

@copilot address and reply to each comment with what you fixed

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 3 comments.

[Copilot]

Potential NULL pointer dereference after code unload. If the calloc fails or if the overflow check prevents allocation, vm->local_func_stack_usage will be NULL. If code is subsequently loaded, the validate function will attempt to access vm->local_func_stack_usage[pc] causing a crash.

The overflow check should prevent ubpf_unload_code from succeeding if max_insts is too large. Additionally, the allocation failure should be checked. Consider either:

1. Failing ubpf_unload_code if allocation fails (but this changes API behavior)
2. Checking for NULL in validation and reporting an error
3. Deferring allocation until next ubpf_load call

Note that if max_insts is so large that it would overflow, this VM is already in an invalid state and should probably not be reused.

[Copilot]

Missing overflow checks for calloc on 32-bit systems. On 32-bit platforms where size_t is 32 bits, the multiplication array_size * sizeof(struct patchable_relative) could overflow size_t, causing calloc to allocate less memory than expected. This could lead to buffer overflows when the arrays are accessed later.

Add checks before each calloc to ensure array_size <= SIZE_MAX / sizeof(...). For example:

if (array_size > SIZE_MAX / sizeof(state->jumps[0])) {
    *errmsg = ubpf_error("Program too large for JIT compilation");
    return -1;
}

Apply similar checks for jumps, loads, leas, and local_calls allocations.

[Copilot]

Missing overflow check for pc_locs calloc on 32-bit systems. On 32-bit platforms where size_t is 32 bits, the multiplication (vm->num_insts + 1) * sizeof(uint32_t) could overflow size_t if num_insts is large enough.

While the check at line 98 prevents num_insts from being UINT32_MAX, this doesn't prevent the calloc overflow. Add a check:

if (vm->num_insts + 1 > SIZE_MAX / sizeof(state->pc_locs[0])) {
    *errmsg = ubpf_error("Program too large for JIT compilation");
    return -1;
}