[PATCH bpf-next 13/13] Documentation/bpf: describe CONFIG_DEBUG_INFO_BTF_LAZY

[Jay Wang <wanjay@amazon.com>]

Describe what the option does, where it is available, when the
vmlinux BTF gets parsed, and what changes for users: registrations and
module BTF that wait for the first use, the BTF id, the missing
__start_BTF/__stop_BTF symbols, and what still parses it at boot.

Signed-off-by: Jay Wang <wanjay@amazon.com>
---
 Documentation/bpf/btf.rst | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/Documentation/bpf/btf.rst b/Documentation/bpf/btf.rst
index 29de1222c3e7..1ebce5cf5783 100644
--- a/Documentation/bpf/btf.rst
+++ b/Documentation/bpf/btf.rst
@@ -1276,6 +1276,36 @@ format.::
             .long   58
             .long   8206                    # Line 8 Col 14
 
+6.1 Compressed vmlinux BTF
+--------------------------
+
+With ``CONFIG_DEBUG_INFO_BTF_LAZY``, the kernel image carries the vmlinux BTF
+zstd-compressed, at about a quarter of its size, and the kernel decompresses
+and parses it when something first needs it: a BPF program or map that uses
+kernel types, ``BPF_BTF_GET_NEXT_ID``, tracing options that print arguments or
+return values by their BTF types.
+``/sys/kernel/btf/vmlinux`` has its full size from the start; reading or
+mapping it decompresses the BTF but does not parse it. Systems that never use
+BTF keep only the compressed copy in memory. The vmlinux file keeps the
+uncompressed ``.BTF`` section, not loaded, for tools and module builds.
+The option is available on x86 and arm64.
+
+Kernel function, destructor kfunc and struct_ops registrations made before the
+first use, and the BTF of modules loaded before it, are kept and applied by the
+task that parses the vmlinux BTF, before anyone else can see it. Errors of
+those registrations then only show in the kernel log, and a module whose BTF
+fails validation at that point stays loaded without BTF and without its files
+in ``/sys/kernel/btf``. A first use that runs out of memory fails with
+``-ENOMEM`` and leaves all of this as it was, for the next one to start over.
+The vmlinux BTF gets the next free BTF id, not necessarily 1, and the image has
+no ``__start_BTF``/``__stop_BTF`` symbols. The inline BTF
+(``CONFIG_DEBUG_INFO_BTF_INLINE``) is not compressed.
+
+Users of kernel types during boot still parse it during boot, for example BPF
+LSM programs, the iterators of ``CONFIG_BPF_PRELOAD`` (loaded at boot, or at the
+first bpffs mount if ``bpf_preload`` is a module), or a module with a
+``.BTF.base`` section.
+
 7. Testing
 ==========
 
-- 
2.47.3