bpf: Add some comments to stack representation

Add comments to the datastructure tracking the stack state, as the
mapping between each stack slot and where its state is stored is not
entirely obvious.

Signed-off-by: Andrei Matei <andreimatei1@gmail.com>
Signed-off-by: Andrii Nakryiko <andrii@kernel.org>
Acked-by: Eduard Zingerman <eddyz87@gmail.com>
Link: https://lore.kernel.org/bpf/20231208032519.260451-2-andreimatei1@gmail.com

diff --git a/include/linux/bpf_verifier.h b/include/linux/bpf_verifier.h
index bada59812e003466a0cbf961c43d12b829adfe4c..314b679fb4940307e123a2bfba5da55120079958 100644 (file)
--- a/include/linux/bpf_verifier.h
+++ b/include/linux/bpf_verifier.h
@@ -321,7 +321,17 @@ struct bpf_func_state {
        /* The following fields should be last. See copy_func_state() */
        int acquired_refs;
        struct bpf_reference_state *refs;
+       /* The state of the stack. Each element of the array describes BPF_REG_SIZE
+        * (i.e. 8) bytes worth of stack memory.
+        * stack[0] represents bytes [*(r10-8)..*(r10-1)]
+        * stack[1] represents bytes [*(r10-16)..*(r10-9)]
+        * ...
+        * stack[allocated_stack/8 - 1] represents [*(r10-allocated_stack)..*(r10-allocated_stack+7)]
+        */
        struct bpf_stack_state *stack;
+       /* Size of the current stack, in bytes. The stack state is tracked below, in
+        * `stack`. allocated_stack is always a multiple of BPF_REG_SIZE.
+        */
        int allocated_stack;
 };
 
@@ -658,6 +668,10 @@ struct bpf_verifier_env {
        int exception_callback_subprog;
        bool explore_alu_limits;
        bool allow_ptr_leaks;
+       /* Allow access to uninitialized stack memory. Writes with fixed offset are
+        * always allowed, so this refers to reads (with fixed or variable offset),
+        * to writes with variable offset and to indirect (helper) accesses.
+        */
        bool allow_uninit_stack;
        bool bpf_capable;
        bool bypass_spec_v1;