bpf, docs: Document BPF insn encoding in term of stored bytes
authorJose E. Marchesi <jose.marchesi@oracle.com>
Tue, 28 Feb 2023 09:51:29 +0000 (10:51 +0100)
committerAlexei Starovoitov <ast@kernel.org>
Tue, 28 Feb 2023 17:55:18 +0000 (09:55 -0800)
commitae256f95478e07d49dae5036bb83c09dfbd686d4
treed98045d67f1a689bdea9a5cec15ecb9a5df83e63
parent30a2d8328d8ac1bb0a6bf73f4f4cf03f4f5977cc
bpf, docs: Document BPF insn encoding in term of stored bytes

[Changes from V4:
- s/regs:16/regs:8 in figure.]

[Changes from V3:
- Back to src_reg and dst_reg, since they denote register numbers
  as opposed to the values stored in these registers.]

[Changes from V2:
- Use src and dst consistently in the document.
- Use a more graphical depiction of the 128-bit instruction.
- Remove `Where:' fragment.
- Clarify that unused bits are reserved and shall be zeroed.]

[Changes from V1:
- Use rst literal blocks for figures.
- Avoid using | in the basic instruction/pseudo instruction figure.
- Rebased to today's bpf-next master branch.]

This patch modifies instruction-set.rst so it documents the encoding
of BPF instructions in terms of how the bytes are stored (be it in an
ELF file or as bytes in a memory buffer to be loaded into the kernel
or some other BPF consumer) as opposed to how the instruction looks
like once loaded.

This is hopefully easier to understand by implementors looking to
generate and/or consume bytes conforming BPF instructions.

The patch also clarifies that the unused bytes in a pseudo-instruction
shall be cleared with zeros.

Signed-off-by: Jose E. Marchesi <jose.marchesi@oracle.com>
Acked-by: Yonghong Song <yhs@fb.com>
Acked-by: David Vernet <void@manifault.com>
Link: https://lore.kernel.org/r/87h6v6i0da.fsf_-_@oracle.com
Signed-off-by: Alexei Starovoitov <ast@kernel.org>
Documentation/bpf/instruction-set.rst