Skip to contentSkip to conversation

docs: bpf: Fixup atomics documentation

PATCH In review Brendan Jackman 2 participants 3 messages Jan 18, 2021

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 docs: bpf: Fixup atomics documentation

This fixues up the markup to fix a warning, be more consistent with use of monospace, and use the correct .rst syntax for <em> (* instead of _). It also clarifies the explanation of Clang's -mcpu requirements for this feature, Alexei pointed out that use of the word "version" was confusing here.

NB this conflicts with Lukas' patch at [1], here where I've added :: to fix the warning, I also kept the original ':' which appears in the output text.

[1] https://lore.kernel.org/bpf/CA+i-1C3cEXqxcXfD4sibQfx+dtmmzvOzruhk8J5pAw3g5v=KgA@mail.gmail.com/T/#t

---
 Documentation/networking/filter.rst | 30 +++++++++++++++--------------
 1 file changed, 16 insertions(+), 14 deletions(-)
Documentation/networking/filter.rst +16 -14
index f6d8f90e9a56..ba03e90a9163 100644
@@ -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
@@ -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,19 +1081,21 @@ 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
-``-Xclang -target-feature -Xclang +alu32``.
+Clang can generate atomic instructions when ``-mcpu=v3`` is enabled (this is the
+default). 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, 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
-32-bit immediate value into a register.
+instruction that loads 64-bit immediate value into a dst_reg.  Classic BPF has
+similar instruction: ``BPF_LD | BPF_W | BPF_IMM`` which loads 32-bit immediate
+value into a register.
 
 eBPF verifier
 -------------

base-commit: 232164e041e925a920bfd28e63d5233cfad90b73

Signature · 1 line
2.30.0.284.gd98b1dd5eaa7-goog
maintainer
#1 lore raw
Quoted 5 lines · On Mon, 18 Jan 2021 11:36:43 +0000 Brendan Jackman <[email protected]> wrote:

This fixues up the markup to fix a warning, be more consistent with use of monospace, and use the correct .rst syntax for <em> (* instead of _). It also clarifies the explanation of Clang's -mcpu requirements for this feature, Alexei pointed out that use of the word "version" was confusing here.

This starts to sound like material for more than one patch...?

Quoted 3 lines

NB this conflicts with Lukas' patch at [1], here where I've added :: to fix the warning, I also kept the original ':' which appears in the output text.

And why did you do that?

Quoted 12 lines

[1] https://lore.kernel.org/bpf/CA+i-1C3cEXqxcXfD4sibQfx+dtmmzvOzruhk8J5pAw3g5v=KgA@mail.gmail.com/T/#t

---
 Documentation/networking/filter.rst | 30 +++++++++++++++--------------
 1 file changed, 16 insertions(+), 14 deletions(-)
Documentation/networking/filter.rst +0 -0
index f6d8f90e9a56..ba03e90a9163 100644

Documentation/networking/filter.rst Unlike classic BPF instruction set, eBPF has generic load/store operations:: · line 1051

Quoted 5 lines
Documentation/networking/filter.rst +1 -1
@@ -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: ::

Things like this read really strangely. Just say "encoding::" and be done with it, please.

Thanks,

jon

#2 lore raw

Thanks for the review :)

Quoted 11 lines · Jonathan Corbet
Quoted 5 lines · On Mon, 18 Jan 2021 11:36:43 +0000 Brendan Jackman <[email protected]> wrote:

This fixues up the markup to fix a warning, be more consistent with use of monospace, and use the correct .rst syntax for <em> (* instead of _). It also clarifies the explanation of Clang's -mcpu requirements for this feature, Alexei pointed out that use of the word "version" was confusing here.

This starts to sound like material for more than one patch...?

Good point, I'll split the markup fixups and actual content change into separate patches.

Quoted 5 lines
Quoted 3 lines

NB this conflicts with Lukas' patch at [1], here where I've added :: to fix the warning, I also kept the original ':' which appears in the output text.

And why did you do that?

Hmm, indeed looks like that isn't necessary as long as there are no spaces between the previous character and the '::'.

v2 incoming...

Quoted 24 lines
Quoted 12 lines

[1] https://lore.kernel.org/bpf/CA+i-1C3cEXqxcXfD4sibQfx+dtmmzvOzruhk8J5pAw3g5v=KgA@mail.gmail.com/T/#t

---
 Documentation/networking/filter.rst | 30 +++++++++++++++--------------
 1 file changed, 16 insertions(+), 14 deletions(-)
Documentation/networking/filter.rst +0 -0
index f6d8f90e9a56..ba03e90a9163 100644

Documentation/networking/filter.rst Unlike classic BPF instruction set, eBPF has generic load/store operations:: · line 1051

Quoted 5 lines
Documentation/networking/filter.rst +1 -1
@@ -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: ::

Things like this read really strangely. Just say "encoding::" and be done with it, please.

Thanks,

jon