From d2e04b9dd617ceaebf4f0ce6a3daf039bc08895e Mon Sep 17 00:00:00 2001 From: Lukas Bulwahn Date: Mon, 18 Jan 2021 09:00:04 +0100 Subject: docs, bpf: Add minimal markup to address doc warning Commit 91c960b00566 ("bpf: Rename BPF_XADD and prepare to encode other atomics in .imm") modified the BPF documentation, but missed some ReST markup. Hence, make htmldocs warns on Documentation/networking/filter.rst:1053: WARNING: Inline emphasis start-string without end-string. Add some minimal markup to address this warning. Fixes: 91c960b00566 ("bpf: Rename BPF_XADD and prepare to encode other atomics in .imm") Signed-off-by: Lukas Bulwahn Signed-off-by: Daniel Borkmann Acked-by: Brendan Jackman Link: https://lore.kernel.org/bpf/20210118080004.6367-1-lukas.bulwahn@gmail.com Signed-off-by: Alexei Starovoitov --- Documentation/networking/filter.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/networking') diff --git a/Documentation/networking/filter.rst b/Documentation/networking/filter.rst index f6d8f90e9a56..45f6fde1776c 100644 --- a/Documentation/networking/filter.rst +++ b/Documentation/networking/filter.rst @@ -1048,12 +1048,12 @@ Unlike classic BPF instruction set, eBPF has generic load/store operations:: Where size is one of: BPF_B or BPF_H or BPF_W or BPF_DW. It also includes atomic operations, which use the immediate field for extra -encoding. +encoding:: .imm = BPF_ADD, .code = BPF_ATOMIC | BPF_W | BPF_STX: lock xadd *(u32 *)(dst_reg + off16) += src_reg .imm = BPF_ADD, .code = BPF_ATOMIC | BPF_DW | BPF_STX: lock xadd *(u64 *)(dst_reg + off16) += src_reg -The basic atomic operations supported are: +The basic atomic operations supported are:: BPF_ADD BPF_AND -- cgit v1.2.3 From 53fe5418fe3f286ddb28fc0f0862923a9c94d671 Mon Sep 17 00:00:00 2001 From: Brendan Jackman Date: Wed, 20 Jan 2021 13:39:45 +0000 Subject: docs: bpf: Fixup atomics markup This fixes up the markup to fix a warning, be more consistent with use of monospace, and use the correct .rst syntax for (* instead of _). Signed-off-by: Brendan Jackman Signed-off-by: Alexei Starovoitov Reviewed-by: Lukas Bulwahn Link: https://lore.kernel.org/bpf/20210120133946.2107897-2-jackmanb@google.com --- Documentation/networking/filter.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) (limited to 'Documentation/networking') diff --git a/Documentation/networking/filter.rst b/Documentation/networking/filter.rst index 45f6fde1776c..4c2bb4c6364d 100644 --- a/Documentation/networking/filter.rst +++ b/Documentation/networking/filter.rst @@ -1066,12 +1066,12 @@ memory location addresed by ``dst_reg + off`` is atomically modified, with immediate, then these operations also overwrite ``src_reg`` with the value that was in memory before it was modified. -The more special operations are: +The more special operations are:: BPF_XCHG This atomically exchanges ``src_reg`` with the value addressed by ``dst_reg + -off``. +off``. :: BPF_CMPXCHG @@ -1081,18 +1081,19 @@ before is loaded back to ``R0``. Note that 1 and 2 byte atomic operations are not supported. -Except ``BPF_ADD`` _without_ ``BPF_FETCH`` (for legacy reasons), all 4 byte +Except ``BPF_ADD`` *without* ``BPF_FETCH`` (for legacy reasons), all 4 byte atomic operations require alu32 mode. Clang enables this mode by default in architecture v3 (``-mcpu=v3``). For older versions it can be enabled with ``-Xclang -target-feature -Xclang +alu32``. -You may encounter BPF_XADD - this is a legacy name for BPF_ATOMIC, referring to -the exclusive-add operation encoded when the immediate field is zero. +You may encounter ``BPF_XADD`` - this is a legacy name for ``BPF_ATOMIC``, +referring to the exclusive-add operation encoded when the immediate field is +zero. -eBPF has one 16-byte instruction: BPF_LD | BPF_DW | BPF_IMM which consists +eBPF has one 16-byte instruction: ``BPF_LD | BPF_DW | BPF_IMM`` which consists of two consecutive ``struct bpf_insn`` 8-byte blocks and interpreted as single instruction that loads 64-bit immediate value into a dst_reg. -Classic BPF has similar instruction: BPF_LD | BPF_W | BPF_IMM which loads +Classic BPF has similar instruction: ``BPF_LD | BPF_W | BPF_IMM`` which loads 32-bit immediate value into a register. eBPF verifier -- cgit v1.2.3 From b452ee005a9135ed89fc8c9dff14e042770eb4f1 Mon Sep 17 00:00:00 2001 From: Brendan Jackman Date: Wed, 20 Jan 2021 13:39:46 +0000 Subject: docs: bpf: Clarify -mcpu=v3 requirement for atomic ops Alexei pointed out [1] that this wording is pretty confusing. Here's an attempt to be more explicit and clear. [1] https://lore.kernel.org/bpf/CAADnVQJVvwoZsE1K+6qRxzF7+6CvZNzygnoBW9tZNWJELk5c=Q@mail.gmail.com/ Signed-off-by: Brendan Jackman Signed-off-by: Alexei Starovoitov Link: https://lore.kernel.org/bpf/20210120133946.2107897-3-jackmanb@google.com --- Documentation/networking/filter.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'Documentation/networking') diff --git a/Documentation/networking/filter.rst b/Documentation/networking/filter.rst index 4c2bb4c6364d..b3f457802836 100644 --- a/Documentation/networking/filter.rst +++ b/Documentation/networking/filter.rst @@ -1081,9 +1081,10 @@ before is loaded back to ``R0``. Note that 1 and 2 byte atomic operations are not supported. -Except ``BPF_ADD`` *without* ``BPF_FETCH`` (for legacy reasons), all 4 byte -atomic operations require alu32 mode. Clang enables this mode by default in -architecture v3 (``-mcpu=v3``). For older versions it can be enabled with +Clang can generate atomic instructions by default when ``-mcpu=v3`` is +enabled. If a lower version for ``-mcpu`` is set, the only atomic instruction +Clang can generate is ``BPF_ADD`` *without* ``BPF_FETCH``. If you need to enable +the atomics features, while keeping a lower ``-mcpu`` version, you can use ``-Xclang -target-feature -Xclang +alu32``. You may encounter ``BPF_XADD`` - this is a legacy name for ``BPF_ATOMIC``, -- cgit v1.2.3 From 6a5df969ff80c1589ba9fd9136b77a4fb93371d0 Mon Sep 17 00:00:00 2001 From: Ilya Leoshkevich Date: Wed, 10 Feb 2021 15:28:52 +0100 Subject: docs: bpf: Clarify BPF_CMPXCHG wording Based on [1], BPF_CMPXCHG should always load the old value into R0. The phrasing in bpf.rst is somewhat ambiguous in this regard, improve it to make this aspect crystal clear. [1] https://lore.kernel.org/bpf/CAADnVQJFcFwxEz=wnV=hkie-EDwa8s5JGbBQeFt1TGux1OihJw@mail.gmail.com/ Signed-off-by: Ilya Leoshkevich Signed-off-by: Alexei Starovoitov Link: https://lore.kernel.org/bpf/20210210142853.82203-1-iii@linux.ibm.com --- Documentation/networking/filter.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/networking') diff --git a/Documentation/networking/filter.rst b/Documentation/networking/filter.rst index b3f457802836..251c6bd73d15 100644 --- a/Documentation/networking/filter.rst +++ b/Documentation/networking/filter.rst @@ -1076,8 +1076,8 @@ off``. :: BPF_CMPXCHG This atomically compares the value addressed by ``dst_reg + off`` with -``R0``. If they match it is replaced with ``src_reg``, The value that was there -before is loaded back to ``R0``. +``R0``. If they match it is replaced with ``src_reg``. In either case, the +value that was there before is zero-extended and loaded back to ``R0``. Note that 1 and 2 byte atomic operations are not supported. -- cgit v1.2.3