qemu-e2k/docs/devel
Paolo Bonzini ff00bed189 qatomic: add smp_mb__before/after_rmw()
On ARM, seqcst loads and stores (which QEMU does not use) are compiled
respectively as LDAR and STLR instructions.  Even though LDAR is
also used for load-acquire operations, it also waits for all STLRs to
leave the store buffer.  Thus, LDAR and STLR alone are load-acquire
and store-release operations, but LDAR also provides store-against-load
ordering as long as the previous store is a STLR.

Compare this to ARMv7, where store-release is DMB+STR and load-acquire
is LDR+DMB, but an additional DMB is needed between store-seqcst and
load-seqcst (e.g. DMB+STR+DMB+LDR+DMB); or with x86, where MOV provides
load-acquire and store-release semantics and the two can be reordered.

Likewise, on ARM sequentially consistent read-modify-write operations only
need to use LDAXR and STLXR respectively for the load and the store, while
on x86 they need to use the stronger LOCK prefix.

In a strange twist of events, however, the _stronger_ semantics
of the ARM instructions can end up causing bugs on ARM, not on x86.
The problems occur when seqcst atomics are mixed with relaxed atomics.

QEMU's atomics try to bridge the Linux API (that most of the developers
are familiar with) and the C11 API, and the two have a substantial
difference:

- in Linux, strongly-ordered atomics such as atomic_add_return() affect
  the global ordering of _all_ memory operations, including for example
  READ_ONCE()/WRITE_ONCE()

- in C11, sequentially consistent atomics (except for seq-cst fences)
  only affect the ordering of sequentially consistent operations.
  In particular, since relaxed loads are done with LDR on ARM, they are
  not ordered against seqcst stores (which are done with STLR).

QEMU implements high-level synchronization primitives with the idea that
the primitives contain the necessary memory barriers, and the callers can
use relaxed atomics (qatomic_read/qatomic_set) or even regular accesses.
This is very much incompatible with the C11 view that seqcst accesses
are only ordered against other seqcst accesses, and requires using seqcst
fences as in the following example:

   qatomic_set(&y, 1);            qatomic_set(&x, 1);
   smp_mb();                      smp_mb();
   ... qatomic_read(&x) ...       ... qatomic_read(&y) ...

When a qatomic_*() read-modify write operation is used instead of one
or both stores, developers that are more familiar with the Linux API may
be tempted to omit the smp_mb(), which will work on x86 but not on ARM.

This nasty difference between Linux and C11 read-modify-write operations
has already caused issues in util/async.c and more are being found.
Provide something similar to Linux smp_mb__before/after_atomic(); this
has the double function of documenting clearly why there is a memory
barrier, and avoiding a double barrier on x86 and s390x systems.

The new macro can already be put to use in qatomic_mb_set().

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Reviewed-by: David Hildenbrand <david@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2023-03-07 12:38:40 +01:00
..
acpi-bits.rst docs/acpi/bits: document BITS_DEBUG environment variable 2022-12-21 07:32:24 -05:00
atomics.rst qatomic: add smp_mb__before/after_rmw() 2023-03-07 12:38:40 +01:00
bitops.rst docs: Create bitops.rst as example of kernel-docs 2019-12-17 19:36:57 +01:00
blkdebug.txt docs/: fix some comment spelling errors 2020-09-17 20:37:13 +02:00
blkverify.txt meson: link emulators without Makefile.target 2020-08-21 06:30:40 -04:00
block-coroutine-wrapper.rst block-coroutine-wrapper.py: introduce co_wrapper 2022-12-15 16:07:43 +01:00
build-system.rst configure: improve error for ucontext coroutine backend 2022-09-01 07:42:37 +02:00
ci-definitions.rst.inc tests/acceptance: rename tests acceptance to tests avocado 2021-11-08 17:00:22 +01:00
ci-jobs.rst.inc docs/devel: clean-up the CI links in the docs 2022-06-01 18:55:04 +01:00
ci-runners.rst.inc docs: name included files ".rst.inc" 2021-10-01 19:04:45 +02:00
ci.rst docs/devel: clean-up the CI links in the docs 2022-06-01 18:55:04 +01:00
clocks.rst clock: Provide builtin multiplier/divider 2021-09-01 11:08:19 +01:00
code-of-conduct.rst docs/devel: add a maintainers section to development process 2022-11-22 09:49:07 +00:00
conflict-resolution.rst docs: Add a QEMU Code of Conduct and Conflict Resolution Policy document 2021-04-01 13:21:02 +02:00
control-flow-integrity.rst Fix typo in CFI build documentation 2021-05-02 17:24:50 +02:00
decodetree.rst decodetree: Extend argument set syntax to allow types 2021-05-01 11:45:35 -07:00
ebpf_rss.rst docs/devel/ebpf_rss.rst: Format literals correctly 2021-08-02 11:42:38 +01:00
fuzzing.rst docs/fuzz: remove mentions of fork-based fuzzing 2023-02-16 23:02:46 -05:00
index-api.rst docs/devel: drop :hidden: and :includehidden: tags 2022-04-20 16:04:20 +01:00
index-build.rst acpi/tests/avocado/bits/doc: add a doc file to describe the acpi bits test 2022-11-02 06:56:32 -04:00
index-internals.rst docs/devel: start documenting writing VirtIO devices 2022-05-16 04:38:40 -04:00
index-process.rst docs/devel: add a maintainers section to development process 2022-11-22 09:49:07 +00:00
index-tcg.rst tcg: convert tcg/README to rst 2023-01-04 16:20:01 -08:00
index.rst docs/devel: drop :hidden: and :includehidden: tags 2022-04-20 16:04:20 +01:00
kconfig.rst meson: fix dependency on qemu-keymap 2023-02-27 09:15:39 +01:00
loads-stores.rst Replace TARGET_WORDS_BIGENDIAN 2022-04-06 10:50:37 +02:00
lockcnt.txt docs: fix references to docs/devel/atomics.rst 2021-06-02 06:51:09 +02:00
maintainers.rst docs/devel: add a maintainers section to development process 2022-11-22 09:49:07 +00:00
memory.rst docs/devel: add some clarifying text for aliases 2022-01-18 12:56:29 +01:00
migration.rst migration: Split save_live_pending() into state_pending_* 2023-02-06 19:22:56 +01:00
modules.rst docs: Spell QEMU all caps 2021-11-19 10:16:58 +01:00
multi-process.rst docs: Render binary names as monospaced text 2021-11-22 15:02:38 +01:00
multi-thread-tcg.rst docs: Spell QEMU all caps 2021-11-19 10:16:58 +01:00
multiple-iothreads.txt block: remove bdrv_try_set_aio_context and replace it with bdrv_try_change_aio_context 2022-10-27 20:14:11 +02:00
qapi-code-gen.rst docs/devel/qapi-code-gen: Fix a missing 'may', clarify SchemaInfo 2023-02-23 12:49:09 +01:00
qgraph.rst Fix some typos in documentation (found by codespell) 2021-11-22 15:02:38 +01:00
qom.rst misc: fix commonly doubled up words 2022-08-01 11:58:02 +02:00
qtest.rst tests: move libqtest.h back under qtest/ 2022-05-03 15:16:51 +04:00
rcu.txt Docs/RCU: Correct sample code of qatomic_rcu_set 2021-01-12 12:38:03 +01:00
replay.rst docs: move replay docs to docs/system/replay.rst 2022-06-06 09:26:54 +02:00
reset.rst hw/core/resettable: fix reset level counting 2022-10-27 10:27:23 +01:00
s390-dasd-ipl.rst docs: rstfy s390 dasd ipl documentation 2020-02-26 18:57:07 +01:00
secure-coding-practices.rst docs/secure-coding-practices: Describe how to use 'null-co' block driver 2021-06-02 14:29:14 +02:00
stable-process.rst docs: Fix botched rST conversion of 'submitting-a-patch.rst' 2021-11-22 15:02:38 +01:00
style.rst docs/devel: Rules on #include in headers 2023-01-08 01:54:22 -05:00
submitting-a-patch.rst docs/devel: try and improve the language around patch review 2022-11-22 09:52:23 +00:00
submitting-a-pull-request.rst docs/devel: add a maintainers section to development process 2022-11-22 09:49:07 +00:00
tcg-icount.rst tcg: Drop gen_io_end() 2021-09-08 11:09:45 +01:00
tcg-ops.rst tcg: Update docs/devel/tcg-ops.rst for temporary changes 2023-03-01 07:33:28 -10:00
tcg-plugins.rst docs: add a new section to outline emulation support 2023-02-02 10:44:23 +00:00
tcg.rst tcg: add perfmap and jitdump 2023-01-16 10:14:12 -10:00
testing.rst testing: update ubuntu2004 to ubuntu2204 2023-03-01 10:31:46 +00:00
tracing.rst docs: trace-events-all is installed without renaming 2022-04-21 17:03:51 +04:00
trivial-patches.rst docs: Fix botched rST conversion of 'submitting-a-patch.rst' 2021-11-22 15:02:38 +01:00
ui.rst docs: Spell QEMU all caps 2021-11-19 10:16:58 +01:00
vfio-migration.rst docs/devel: Align VFIO migration docs to v2 protocol 2023-02-16 12:13:46 -07:00
virtio-backends.rst docs/devel: start documenting writing VirtIO devices 2022-05-16 04:38:40 -04:00
virtio-migration.txt
writing-monitor-commands.rst qapi: Start to elide redundant has_FOO in generated C 2022-12-13 18:31:37 +01:00