qemu/docs
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
..
_templates docs: Add QEMU version information to HTML footer 2021-07-18 10:59:47 +01:00
about Deprecate the "-no-acpi" command line switch 2023-02-27 09:23:21 +01:00
config docs: Grammar and spelling fixes 2018-07-13 10:16:04 +01:00
devel qatomic: add smp_mb__before/after_rmw() 2023-03-07 12:38:40 +01:00
interop docs: add an introduction to the system docs 2023-02-02 11:48:18 +00:00
specs pci-ids: drop list of modern virtio devices 2022-10-12 12:01:11 +02:00
sphinx docs/sphinx: fix compatibility with sphinx < 1.8 2022-01-05 11:10:13 +01:00
sphinx-static docs/sphinx: add 's' keyboard binding to focus search 2021-11-08 12:27:23 +04:00
spin docs: create config/, devel/ and spin/ subdirectories 2017-06-07 18:22:03 +02:00
system i386/xen: Document Xen HVM emulation 2023-03-01 09:09:22 +00:00
tools virtiofsd: Remove source 2023-02-16 18:15:08 +00:00
user docs: add hotlinks to about preface text 2023-02-02 10:44:23 +00:00
block-replication.txt docs/block-replication.txt: Fix replication top-id command demo 2021-12-17 11:35:00 +01:00
bypass-iommu.txt docs: Add documentation for iommu bypass 2021-07-16 11:10:45 -04:00
COLO-FT.txt docs: Use double quotes instead of single quotes for COLO 2021-11-22 15:02:38 +01:00
colo-proxy.txt docs: update to show preferred boolean syntax for -chardev 2021-02-25 14:14:33 +01:00
conf.py virtiofsd: Remove build and docs glue 2023-02-16 18:15:08 +00:00
defs.rst.inc docs: Fix typo in the default name of the qemu-system-x86_64 binary 2021-04-01 14:28:39 +02:00
igd-assign.txt vfio/pci: Add IGD documentation 2016-05-26 11:12:05 -06:00
image-fuzzer.txt docs: Render binary names as monospaced text 2021-11-22 15:02:38 +01:00
index.rst docs: standardize book titles to === with overline 2021-09-13 13:56:26 +02:00
memory-hotplug.txt docs: Grammar and spelling fixes 2018-07-13 10:16:04 +01:00
meson.build meson: stop looking for 'sphinx-build-3' 2023-02-27 11:01:30 +01:00
multi-thread-compression.txt Replace '-enable-kvm' with '-accel kvm' in docs and help texts 2018-06-28 19:05:32 +02:00
multiseat.txt docs: Spell QEMU all caps 2021-11-19 10:16:58 +01:00
nvdimm.txt docs/nvdimm: Update nvdimm option value in machine example 2021-09-27 10:57:21 +02:00
pci_expander_bridge.txt pxb: cleanup 2016-03-11 16:59:12 +02:00
pcie_pci_bridge.txt docs: add slot when adding new PCIe root port 2021-07-03 03:12:35 -04:00
pcie_sriov.txt docs: Replace Qemu -> QEMU 2022-04-26 12:38:44 +02:00
pcie.txt docs/pcie.txt: Replace ioh3420 with pcie-root-port 2023-01-28 06:21:30 -05:00
pvrdma.txt docs: Fix broken links 2020-09-01 09:31:33 +02:00
qcow2-cache.txt qcow2: Document the Extended L2 Entries feature 2020-08-25 08:33:20 +02:00
qdev-device-use.txt util: remove support -chardev tty and -chardev parport 2023-01-06 00:51:02 +01:00
qemu-option-trace.rst.inc qemu-option-trace.rst.inc: Don't use option:: markup 2020-11-02 16:52:18 +00:00
qemupciserial.inf docs: Grammar and spelling fixes 2018-07-13 10:16:04 +01:00
rdma.txt migrate: remove QMP/HMP commands for speed, downtime and cache size 2021-03-18 09:22:55 +00:00
spice-port-fqdn.txt docs: add spice-port-fqdn.txt 2012-12-17 14:01:41 +01:00
throttle.txt docs: Drop deprecated 'props' from object-add 2021-11-22 15:02:38 +01:00
u2f.txt docs: Spell QEMU all caps 2021-11-19 10:16:58 +01:00
xbzrle.txt migrate: remove QMP/HMP commands for speed, downtime and cache size 2021-03-18 09:22:55 +00:00
xen-save-devices-state.txt Fix up dangling references to qmp-commands.* in comment and doc 2018-03-02 13:48:26 -06:00