[PATCH v2 0/9] bpf: clean up and document ethdev callback synchronization

[Marat Khalili <qm2k21@gmail.com>]

The DPDK BPF library provides mechanisms to attach BPF programs to
ethdev Rx/Tx callbacks (rte_bpf_eth_rx_elf_load and
rte_bpf_eth_tx_elf_load). Safe unloading of these callbacks relies on
a synchronization protocol between the control plane and datapath
threads, built upon the assumption that each port/queue callback is
serviced by at most one datapath thread.

This patch series improves the documentation, safety, and implementation
of the callback synchronization mechanism:

1. Documentation:
   - Add an ASCII sequence diagram and comprehensive documentation in
     bpf_pkt.c explaining the synchronization protocol between the
     control plane and datapath during callback unload.
   - Document the single-thread-per-queue datapath requirement in
     public API headers.

2. Safety and Validation:
   - Enforce the single-threaded datapath assumption by rejecting Tx
     callback installation when the device advertises
     RTE_ETH_TX_OFFLOAD_MT_LOCKFREE.
   - Add a new flag (RTE_BPF_ETH_F_SKIP_MT_CHECK) allowing applications
     to override this check when application architecture guarantees
     thread exclusivity.
   - Add automated unit test test_bpf_elf_tx_mt_lockfree.

3. Synchronization Cleanups:
   - Remove a redundant control plane memory barrier (rte_smp_mb) on
     callback unload.
   - Simplify datapath inuse tracking (cbi->use) from an even/odd
     counter to a boolean flag (true and false), simplifying
     bpf_eth_cbi_wait().
   - Switch cbi->use stores and control plane wait loop loads to
     explicit rte_atomic_store_explicit() and rte_atomic_load_explicit()
     with relaxed memory order, avoiding implicit seq_cst operations
     in C11.
   - Make cbi->cb atomic with relaxed atomic load/store operations,
     eliminating C11 data-race undefined behavior while compiling to
     identical machine code, and making it self-evident that cb is an
     integral part of the synchronization mechanism on par with use.

Patches 4 and 7 were originally proposed by Stephen Hemminger as part
of a larger series replacing deprecated SMP barriers with C11 fences,
and are carried here with his authorship.

Note that a full rework of the synchronization protocol (e.g. replacing
standalone memory barriers entirely with acquire/release semantics
across variables) was intentionally avoided to keep each commit simple,
localized, and non-controversial. More substantial architectural
changes, such as that or extending the library to support concurrent
multi-threaded dataplane execution, can be cleanly built on top of this
work in the future.

v2:
- Reordered the series so that the patch adding
  RTE_BPF_ETH_F_SKIP_MT_CHECK is last, allowing it to be easily dropped
  if no agreement is reached.
- Added release note in release_26_11.rst documenting the MT_LOCKFREE
  Tx callback rejection and the RTE_BPF_ETH_F_SKIP_MT_CHECK override
  flag.
- Credited Stephen Hemminger for earlier authorship of patches 4 and 7
  ("remove redundant memory barrier on unload" and "use relaxed accesses
  for callback inuse tracking").
- Changed callback usage tracking variable `use` to type `bool` with
  `true`/`false` values instead of uint32_t with 1/0.
- Replaced RTE_WAIT_UNTIL_MASKED with an explicit pause loop in
  bpf_eth_cbi_wait(), eliminating macro and type casts.

Marat Khalili (9):
  bpf: document packet callback unload sequence
  bpf: document ethdev callback threading limitations
  bpf: reject Tx callback installation with MT_LOCKFREE
  bpf: remove redundant memory barrier on unload
  bpf: simplify callback inuse tracking to boolean flag
  bpf: reformat packet callback unload diagram
  bpf: use relaxed accesses for callback inuse tracking
  bpf: make callback handle atomic with relaxed access
  bpf: add callback flag to skip multi-thread check

 app/test/test_bpf.c                    | 123 +++++++++++++++++
 doc/guides/rel_notes/release_26_11.rst |   5 +
 lib/bpf/bpf_pkt.c                      | 175 +++++++++++++++++++------
 lib/bpf/rte_bpf_ethdev.h               |  11 +-
 4 files changed, 275 insertions(+), 39 deletions(-)

-- 
2.43.0