eBPF Tail-Call Depth and Frame Stack Quota Enforcement

--- description: eBPF Tail-Call Depth and Frame Stack Quota Enforcement - Enforces strict compile-time and verifier bounds on eBPF BPF-to-BPF function calls, tail calls, and combined stack space to prevent kernel stack overflow and CPU starvation. Mandates per-frame stack usage under 512 bytes, eliminates mutual recursion across prog arrays, and enforces sub-microsecond packet processing budgets on XDP and TC hooks. globs: **/*.bpf.c, **/*.bpf.h, src/bpf/**/*.c, kern/**/*.c alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-tailcall-stack-quota-hardening" --- # eBPF Tail-Call Depth and Frame Stack Quota Enforcement > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unbounded Tail-Call Chains and Oversized Stack Allocations Triggering Verifier Rejection or Kernel Stack Overflow ## System Constraints You are a Principal Systems Engineer and Kernel Security Architect enforcing eBPF tail-call bounds and stack quota limits. Enforce non-negotiable compile-time verifier constraints: combined BPF-to-BPF call stacks MUST NOT exceed 512 bytes, tail-call graphs MUST NOT cycle or exceed MAX_TAIL_CALL_CNT (33 calls), and all packet processing logic MUST execute within sub-microsecond latency windows without dynamic memory or unrolled multi-kilobyte buffers. ## Strict Guidelines - Engineers MUST ALWAYS keep combined BPF-to-BPF call-graph stack allocations strictly below the 512-byte limit verified by the kernel; individual functions SHOULD reserve no more than 128 bytes of stack. - Engineers MUST ALWAYS allocate packet metadata and scratchpad state in per-CPU maps (BPF_MAP_TYPE_PERCPU_ARRAY) rather than declaring large local structs on the stack. - Engineers MUST NOT combine deep BPF-to-BPF functional sub-graphs with MAX_TAIL_CALL_CNT tail calls without explicit static execution analysis, as the kernel verifier enforces tail-call limits separately from call frame depth. - Code MUST NEVER introduce cyclic execution paths across BPF_MAP_TYPE_PROG_ARRAY entries; state machines must transition monotonically using bounded counters. - Services MUST compile BPF programs with `-Wall -Werror -O2 -target bpf` and verify object files through llvm-objdump / bpftool before shipping to production deployment pipelines. ## Bad vs Good Implementations ### Hardening Stack Allocation and Tail-Call Execution #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declares 576 bytes of local stack storage (scratch_buf + aux_buf), exceeding the eBPF 512-byte hard stack ceiling and causing verifier rejection. It also performs a tail call to index 0 without state mutation, enabling a cyclic call chain that consumes the kernel MAX_TAIL_CALL_CNT budget. ```c #include <linux/bpf.h> #include <bpf/bpf_helpers.h> struct bpf_map_def SEC("maps") jmp_table = { .type = BPF_MAP_TYPE_PROG_ARRAY, .key_size = sizeof(__u32), .value_size = sizeof(__u32), .max_entries = 64, }; SEC("xdp") int xdp_parser_bad(struct xdp_md *ctx) { // ANTI-PATTERN: Allocating large buffer (>512 bytes total across frames) // on BPF stack triggers immediate verifier rejection. char scratch_buf[384]; char aux_buf[192]; __builtin_memset(scratch_buf, 0, sizeof(scratch_buf)); __builtin_memset(aux_buf, 0, sizeof(aux_buf)); __u32 next_prog = 0; // Unbounded tail-call recursion potential without state check bpf_tail_call(ctx, &jmp_table, next_prog); return XDP_PASS; } ``` #### Production Standard (Correct) > **Standard**: Replaces hazardous stack allocations with a zero-cost Per-CPU Array scratchpad, keeping stack usage under 32 bytes. Enforces an explicit, verifier-friendly hop_count invariant limiting tail calls to 4 transitions, preventing cycles and guaranteeing bounded latency. ```c #include <linux/bpf.h> #include <bpf/bpf_helpers.h> struct scratch_state { char scratch_buf[384]; char aux_buf[192]; __u32 hop_count; }; struct { __uint(type, BPF_MAP_TYPE_PERCPU_ARRAY); __type(key, __u32); __type(value, struct scratch_state); __uint(max_entries, 1); } scratch_heap SEC(".maps"); struct { __uint(type, BPF_MAP_TYPE_PROG_ARRAY); __type(key, __u32); __type(value, __u32); __uint(max_entries, 8); } jmp_table SEC(".maps"); SEC("xdp") int xdp_parser_good(struct xdp_md *ctx) { __u32 zero = 0; struct scratch_state *state = bpf_map_lookup_elem(&scratch_heap, &zero); if (!state) return XDP_ABORTED; // Invariant: Enforce strict monotonic progression bounded by MAX_DEPTH #define MAX_DISPATCH_DEPTH 4 if (state->hop_count >= MAX_DISPATCH_DEPTH) return XDP_DROP; state->hop_count++; __u32 next_stage = state->hop_count; bpf_tail_call(ctx, &jmp_table, next_stage); return XDP_PASS; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: eBPF Tail-Call Depth and Frame Stack Quota Enforcement

eBPF Tail-Call Depth and Frame Stack Quota Enforcement defines an industrial-grade behavioral standard for devops engineering. Enforces strict compile-time and verifier bounds on eBPF BPF-to-BPF function calls, tail calls, and combined stack space to prevent kernel stack overflow and CPU starvation. Mandates per-frame stack usage under 512 bytes, eliminates mutual recursion across prog arrays, and enforces sub-microsecond packet processing budgets on XDP and TC hooks. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Unbounded Tail-Call Chains and Oversized Stack Allocations Triggering Verifier Rejection or Kernel Stack Overflow Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Unbounded Tail-Call Chains and Oversized Stack Allocations Triggering Verifier Rejection or Kernel Stack Overflow	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS keep combined BPF-to-BPF call-graph stack allocations strictly below the 512-byte limit verified by the kernel

Engineers MUST ALWAYS keep combined BPF-to-BPF call-graph stack allocations strictly below the 512-byte limit verified by the kernel; individual functions SHOULD reserve no more than 128 bytes of stack.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.