Document the new gdb-like validation debugger API, outlining how it can be used to set breakpoints and inspect register states during validation.
Highlight its primary use case: writing robust tests for the eBPF verifier using the harness in app/test/test_bpf_validate.c. Signed-off-by: Marat Khalili <[email protected]> --- doc/guides/prog_guide/bpf_lib.rst | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/doc/guides/prog_guide/bpf_lib.rst b/doc/guides/prog_guide/bpf_lib.rst index df3782508829..08ea1876875a 100644 --- a/doc/guides/prog_guide/bpf_lib.rst +++ b/doc/guides/prog_guide/bpf_lib.rst @@ -118,6 +118,37 @@ For example, ``(BPF_IND | BPF_W | BPF_LD)`` means: and ``R1-R5`` were scratched. +Validation Debugger +------------------- + +The DPDK BPF library includes a validation debugger API designed primarily for +writing comprehensive unit tests for the eBPF verifier. It allows developers +to introspect the abstract interpretation process step-by-step to guarantee +that the verifier correctly models the semantics of eBPF instructions. + +The debugger operates using a gdb-like approach: + +1. **Initialization:** Create a debug session using + ``rte_bpf_validate_debug_create()`` and pass it to the loader via the + ``debug`` field in ``struct rte_bpf_prm_ex``. +2. **Breakpoints and Catchpoints:** Before loading, use + ``rte_bpf_validate_debug_break()`` or ``rte_bpf_validate_debug_catch()`` + to register callback functions that trigger at specific instruction indices + (program counters) or upon specific validation events. +3. **State Introspection:** Within the callbacks, the API provides functions + like ``rte_bpf_validate_debug_can_access()``, + ``rte_bpf_validate_debug_may_jump()``, and various formatting functions + to safely inspect the verifier's internal belief about register bounds + and memory states at that specific execution point. + +When adding a test for a new eBPF instruction or fixing a validator bug, +developers should utilize the harness provided in +``app/test/test_bpf_validate.c``. This harness encapsulates the debugger API, +allowing you to define the expected abstract domains (signed and unsigned +intervals) for registers before and after a tested instruction, generating +the necessary eBPF bytecode and breakpoints automatically. + + Not currently supported eBPF features ------------------------------------- -- 2.43.0
