The NetBSD Project

CVS log for src/share/man/man9/atomic_loadstore.9

[BACK] Up to [cvs.NetBSD.org] / src / share / man / man9

Request diff between arbitrary revisions


Default branch: MAIN


Revision 1.7 / (download) - annotate - [select for diffs], Sat Apr 9 23:32:53 2022 UTC (9 months, 3 weeks ago) by riastradh
Branch: MAIN
CVS Tags: netbsd-10-base, netbsd-10, HEAD
Changes since 1.6: +19 -17 lines
Diff to previous 1.6 (colored)

Introduce membar_acquire/release.  Deprecate membar_enter/exit.

The names membar_enter/exit were unclear, and the documentation of
membar_enter has disagreed with the implementations on sparc,
powerpc, and even x86(!) for the entire time it has been in NetBSD.

The terms `acquire' and `release' are ubiquitous in the literature
today, and have been adopted in the C and C++ standards to mean
load-before-load/store and load/store-before-store, respectively,
which are exactly the orderings required by acquiring and releasing a
mutex, as well as other useful applications like decrementing a
reference count and then freeing the underlying object if it went to
zero.

Originally I proposed changing one word in the documentation for
membar_enter to make it load-before-load/store instead of
store-before-load/store, i.e., to make it an acquire barrier.  I
proposed this on the grounds that

(a) all implementations guarantee load-before-load/store,
(b) some implementations fail to guarantee store-before-load/store,
and
(c) all uses in-tree assume load-before-load/store.

I verified parts (a) and (b) (except, for (a), powerpc didn't even
guarantee load-before-load/store -- isync isn't necessarily enough;
need lwsync in general -- but it _almost_ did, and it certainly didn't
guarantee store-before-load/store).

Part (c) might not be correct, however: under the mistaken assumption
that atomic-r/m/w then membar-w/rw is equivalent to atomic-r/m/w then
membar-r/rw, I only audited the cases of membar_enter that _aren't_
immediately after an atomic-r/m/w.  All of those cases assume
load-before-load/store.  But my assumption was wrong -- there are
cases of atomic-r/m/w then membar-w/rw that would be broken by
changing to atomic-r/m/w then membar-r/rw:

https://mail-index.netbsd.org/tech-kern/2022/03/29/msg028044.html

Furthermore, the name membar_enter has been adopted in other places
like OpenBSD where it actually does follow the documentation and
guarantee store-before-load/store, even if that order is not useful.
So the name membar_enter currently lives in a bad place where it
means either of two things -- r/rw or w/rw.

With this change, we deprecate membar_enter/exit, introduce
membar_acquire/release as better names for the useful pair (r/rw and
rw/w), and make sure the implementation of membar_enter guarantees
both what was documented _and_ what was implemented, making it an
alias for membar_sync.

While here, rework all of the membar_* definitions and aliases.  The
new logic follows a rule to make it easier to audit:

	membar_X is defined as an alias for membar_Y iff membar_X is
	guaranteed by membar_Y.

The `no stronger than' relation is (the transitive closure of):

- membar_consumer (r/r) is guaranteed by membar_acquire (r/rw)
- membar_producer (w/w) is guaranteed by membar_release (rw/w)
- membar_acquire (r/rw) is guaranteed by membar_sync (rw/rw)
- membar_release (rw/w) is guaranteed by membar_sync (rw/rw)

And, for the deprecated membars:

- membar_enter (whether r/rw, w/rw, or rw/rw) is guaranteed by
  membar_sync (rw/rw)
- membar_exit (rw/w) is guaranteed by membar_release (rw/w)

(membar_exit is identical to membar_release, but the name is
deprecated.)

Finally, while here, annotate some of the instructions with their
semantics.  For powerpc, leave an essay with citations on the
unfortunate but -- as far as I can tell -- necessary decision to use
lwsync, not isync, for membar_acquire and membar_consumer.

Also add membar(3) and atomic(3) man page links.

Revision 1.5.2.3 / (download) - annotate - [select for diffs], Sun Sep 13 12:20:22 2020 UTC (2 years, 4 months ago) by martin
Branch: netbsd-9
CVS Tags: netbsd-9-3-RELEASE, netbsd-9-2-RELEASE, netbsd-9-1-RELEASE
Changes since 1.5.2.2: +2 -2 lines
Diff to previous 1.5.2.2 (colored) to branchpoint 1.5 (colored) next main 1.6 (colored)

Pull up following revision(s) (requested by riastradh in ticket #1082):

	share/man/man9/atomic_loadstore.9: revision 1.6
	share/man/man9/ipi.9: revision 1.5
	lib/libc/atomic/membar_ops.3: revision 1.6

Spell out acronyms in title for clarity.

Update membar_ops(3) man page with examples and relation to C11.

Add exhortation to always always always document how membars come in
pairs for synchronization between two CPUs when you use them.

atomic_load/store_* appeared in NetBSD 9, not 10.

Pullup preceded release of 9.0.

Revision 1.6 / (download) - annotate - [select for diffs], Thu Sep 3 00:23:57 2020 UTC (2 years, 5 months ago) by riastradh
Branch: MAIN
CVS Tags: cjep_sun2x-base1, cjep_sun2x-base, cjep_sun2x, cjep_staticlib_x-base1, cjep_staticlib_x-base, cjep_staticlib_x
Changes since 1.5: +2 -2 lines
Diff to previous 1.5 (colored)

atomic_load/store_* appeared in NetBSD 9, not 10.

Pullup preceded release of 9.0.

Revision 1.5.6.2 / (download) - annotate - [select for diffs], Wed Apr 8 14:07:22 2020 UTC (2 years, 9 months ago) by martin
Branch: phil-wifi
Changes since 1.5.6.1: +806 -0 lines
Diff to previous 1.5.6.1 (colored) to branchpoint 1.5 (colored) next main 1.6 (colored)

Merge changes from current as of 20200406

Revision 1.5.2.2 / (download) - annotate - [select for diffs], Sun Dec 8 14:26:38 2019 UTC (3 years, 1 month ago) by martin
Branch: netbsd-9
CVS Tags: netbsd-9-0-RELEASE, netbsd-9-0-RC2
Changes since 1.5.2.1: +798 -0 lines
Diff to previous 1.5.2.1 (colored) to branchpoint 1.5 (colored)

Pull up following revision(s) (requested by riastradh in ticket #508):

	distrib/sets/lists/comp/mi: revision 1.2294
	share/man/man9/Makefile: revision 1.443
	sys/sys/atomic.h: revision 1.18
	share/man/man9/atomic_loadstore.9: revision 1.1
	share/man/man9/atomic_loadstore.9: revision 1.2

New atomic load/store operations for the kernel.

Guarantee no fusing and no tearing, and can optionally impose
ordering relative to other memory operations.

Unordered:
- atomic_load_relaxed
- atomic_store_relaxed

Ordered:
- atomic_load_acquire
- atomic_load_consume
- atomic_store_release

These are intended to match C11 semantics, and can be defined in
terms of the C11 atomic API when ready.

Document relation to atomic_ops(3) and membar_ops(3).

Revision 1.5.6.1, Sun Dec 8 00:00:59 2019 UTC (3 years, 1 month ago) by martin
Branch: phil-wifi
Changes since 1.5: +0 -806 lines
FILE REMOVED

file atomic_loadstore.9 was added on branch phil-wifi on 2020-04-08 14:07:22 +0000

Revision 1.5.2.1, Sun Dec 8 00:00:59 2019 UTC (3 years, 1 month ago) by martin
Branch: netbsd-9
Changes since 1.5: +0 -806 lines
FILE REMOVED

file atomic_loadstore.9 was added on branch netbsd-9 on 2019-12-08 14:26:38 +0000

Revision 1.5 / (download) - annotate - [select for diffs], Sun Dec 8 00:00:59 2019 UTC (3 years, 1 month ago) by uwe
Branch: MAIN
CVS Tags: phil-wifi-20200421, phil-wifi-20200411, phil-wifi-20200406, is-mlppp-base, is-mlppp
Branch point for: phil-wifi, netbsd-9
Changes since 1.4: +44 -36 lines
Diff to previous 1.4 (colored)

Simplify markup for inline code to plain .Li in most places.

Use backslashes to protetect embedded spaces in inline code to prevent
filling from stretching them.

Use .Fn and .Fa to refer only to things this manual page documents,
they are not to be used for "a function" or "a function argument" in
general.

In code examples drop the empty line at the beginning of a function
(mandated by the KNF when there are no variables) - it doesn't help
readability here.

Revision 1.4 / (download) - annotate - [select for diffs], Sat Dec 7 12:22:19 2019 UTC (3 years, 1 month ago) by wiz
Branch: MAIN
Changes since 1.3: +7 -7 lines
Diff to previous 1.3 (colored)

Simplify macro usage.

Revision 1.3 / (download) - annotate - [select for diffs], Sat Nov 30 02:47:14 2019 UTC (3 years, 2 months ago) by riastradh
Branch: MAIN
Changes since 1.2: +2 -2 lines
Diff to previous 1.2 (colored)

Use .Sy, not .Em, for bold-faced WARNING of impending doom.

Underline and, worse, italic aren't as good at catching the eye.

Revision 1.2 / (download) - annotate - [select for diffs], Sat Nov 30 02:38:44 2019 UTC (3 years, 2 months ago) by riastradh
Branch: MAIN
Changes since 1.1: +55 -1 lines
Diff to previous 1.1 (colored)

Document relation to atomic_ops(3) and membar_ops(3).

Revision 1.1 / (download) - annotate - [select for diffs], Fri Nov 29 22:17:23 2019 UTC (3 years, 2 months ago) by riastradh
Branch: MAIN

New atomic load/store operations for the kernel.

Guarantee no fusing and no tearing, and can optionally impose
ordering relative to other memory operations.

Unordered:
- atomic_load_relaxed
- atomic_store_relaxed

Ordered:
- atomic_load_acquire
- atomic_load_consume
- atomic_store_release

These are intended to match C11 semantics, and can be defined in
terms of the C11 atomic API when ready.

This form allows you to request diff's between any two revisions of a file. You may select a symbolic revision name using the selection box or you may type in a numeric name using the type-in text box.




CVSweb <webmaster@jp.NetBSD.org>