diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 42cf448..1c6b183 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -171,6 +171,11 @@ jobs: # tests-only, not test: these tests ask the binaries what they contain. # Running the C suite is the `native` job's business. run: make -j"$(nproc)" tests-only + - name: Build the team-width observer + # Without it test_teamwidth.py skips, and a skipped check is not a + # check. Linux-only by nature: it interposes libgomp through + # LD_PRELOAD, so this is the one job that can run it. + run: make teamwidth - name: Tooling test suite run: python -m pytest verification/tests -q diff --git a/Makefile b/Makefile index df9bb78..ac0b778 100644 --- a/Makefile +++ b/Makefile @@ -243,8 +243,30 @@ tsan: @echo " running the binaries bare reports hundreds of races that are" @echo " not there -- see verification/tests/test_tsan.py)" +# ── The team-width observer ────────────────────────────────── +# +# Builds verification/teamwidth.c into an LD_PRELOAD library that records how +# wide every OpenMP team BEAM creates actually was. Every other thread check in +# this repository is static -- `thread counts` proves each of the 93 regions +# NAMES a count, the GIL scan proves each resolves a plan -- and neither can see +# what the runtime granted. The nesting defect lived in exactly that gap. +# +# Deliberately NOT built with $(OMPFLAG): the observer resolves libgomp through +# dlopen at run time, so linking a second OpenMP runtime into it would be both +# unnecessary and a way to end up measuring the wrong one. +$(BUILD)/teamwidth.so: verification/teamwidth.c + @mkdir -p $(dir $@) + $(CC) -O2 -Wall -Wextra -std=c11 -fPIC -shared -o $@ $< -ldl + +teamwidth: $(BUILD)/teamwidth.so + @echo + @echo "Built $(BUILD)/teamwidth.so" + @echo "Use it: LD_PRELOAD=$(BUILD)/teamwidth.so .venv/bin/python your_script.py" + @echo " (read the counters via ctypes.CDLL(None); see" + @echo " verification/tests/test_teamwidth.py)" + clean: rm -rf $(BUILD) -.PHONY: all clean test list-tests selftest tests-only tsan +.PHONY: all clean test list-tests selftest tests-only tsan teamwidth -include $(DEPS) diff --git a/verification/README.md b/verification/README.md index 84b0198..c8e0805 100644 --- a/verification/README.md +++ b/verification/README.md @@ -71,6 +71,42 @@ that set from the sources rather than listing it, and its last test is the one that matters: it runs a suite with Archer off and checks the reports appear, because a clean run is only evidence if a dirty one is reachable. +## Observing the teams that actually ran + +```bash +make teamwidth # build/teamwidth.so +python -m pytest verification/tests/test_teamwidth.py -q +``` + +Every other thread check here is static. `thread counts` proves each of the 93 +parallel regions *names* a thread count; `thread plan wiring` proves each +GIL-releasing region *resolves* a plan. Neither can see what the runtime +granted, and that is precisely where the nesting defect lived -- `thread +counts` was OK in the same gate run that the defect was live in, because the +clause was present and correct and only its value on a worker thread was wrong. + +`teamwidth.c` interposes the two libgomp entry points BEAM creates teams +through and records, for every region entry, the count requested and the width +that actually ran. One `entropy()` call creates **949 teams**, which is why +reading 93 pragmas could never have answered the question. It observes the +shipped extension through `LD_PRELOAD`, with no rebuild, so it measures the +same binary the gate hashes. + +Both numbers are recorded because the mutation says they are not +interchangeable. With the nested-region guard removed from `beam_threads()`, in +the **default** environment, BEAM asked for 16 threads against a plan of 8 and +every team that ran was still the correct width -- libgomp declines to widen a +nested region when nesting is off. A check on the width that ran passes on that +mutant; only the requested count catches it. The runtime's default policy was +the only thing between the plan and sixteen-way oversubscription, which is luck +rather than design, so the requested channel is the primary assertion. + +Two of the tests exist to stop the file lying to you. One reads the built +extension's imports and fails if BEAM ever grows a third way to create a team, +since the observer would then be blind *and* quiet. The other requires the +measurement to have reached a nested region, because a dead path and a +well-behaved one report the same zero. + ## Running the gate ```bash diff --git a/verification/teamwidth.c b/verification/teamwidth.c new file mode 100644 index 0000000..99a6bd0 --- /dev/null +++ b/verification/teamwidth.c @@ -0,0 +1,200 @@ +/* Observe the WIDTH of every OpenMP team BEAM actually creates. + * + * Every check BEAM had before this one was static. `check_lib.thread_count_clauses` + * proves all 93 parallel regions NAME a thread count, and the GIL scan proves + * every GIL-releasing region RESOLVES a plan. Neither can see what the runtime + * granted. That blind spot is not hypothetical: `beam_threads()` returned the + * configured cap to a worker thread for as long as the plan existed, so an + * 8-thread plan opened eight teams of sixteen under OMP_MAX_ACTIVE_LEVELS=2 -- + * and `thread counts` was OK in the same gate run, because the clause was + * present and correct and only its VALUE on a worker was wrong. + * + * This observes the shipped artifact rather than a special build. BEAM creates + * teams through exactly two libgomp entry points (`nm --undefined-only` on the + * extension: GOMP_parallel and the fused GOMP_parallel_loop_nonmonotonic_dynamic; + * the other eight GOMP imports are work-sharing, atomics and critical sections, + * which create no team). Interposing those two via LD_PRELOAD measures the real + * `_cbeam*.so` the gate hashes, with no recompilation -- a check that needed its + * own build would be checking a different binary. + * `test_teamwidth.py::test_the_observer_wraps_every_team_creating_entry_point` + * fails if a third ever appears, because the observer would then be blind and + * still report zero violations. + * + * REQUESTED vs ACTUAL, and why both. The `nthreads` argument is what BEAM's + * `num_threads(...)` clause evaluated to -- the plan's answer, which until now + * was only ever checked by reading the source. The team that runs can be + * narrower (the runtime is allowed to give less) but never wider, so the two + * numbers bracket the question: `requested` audits BEAM's arithmetic, `actual` + * audits the runtime's grant. Recording only one of them would leave either the + * plan or the runtime unexamined. + * + * Build: make teamwidth + * Use: LD_PRELOAD=build/teamwidth.so .venv/bin/python ... + * then read the counters through ctypes.CDLL(None) -- an LD_PRELOAD + * library is in the global symbol scope, so its exports resolve there. + */ +#define _GNU_SOURCE +#include +#include +#include +#include +#include + +/* Widths, split by whether the region ITSELF is nested. The split is the whole + * point: the defect that motivated this file was invisible in the outer team's + * width (a correct 8) and only showed in the inner one (16). */ +static atomic_uint_fast64_t w_outer = 0; /* widest depth-1 team */ +static atomic_uint_fast64_t w_nested = 0; /* widest team at depth >= 2 */ +static atomic_uint_fast64_t w_any = 0; /* widest team at any depth */ +static atomic_uint_fast64_t r_any = 0; /* largest `nthreads` requested */ +static atomic_uint_fast64_t n_unnamed = 0; /* entries with nthreads == 0 */ +static atomic_uint_fast64_t n_entries = 0; /* team creations observed */ +static atomic_uint_fast64_t d_max = 0; /* deepest level reached */ + +typedef int (*int_fn_t)(void); +typedef void (*fn_t)(void *); +typedef void (*plain_t)(fn_t, void *, unsigned, unsigned); +typedef void (*loop_t)(fn_t, void *, unsigned, long, long, long, long, unsigned); + +static plain_t real_plain; +static loop_t real_loop; +static int_fn_t omp_level; +static int_fn_t omp_width; + +/* + * RTLD_NEXT cannot find libgomp here: CPython dlopens extension modules with + * RTLD_LOCAL, so libgomp lands in a local scope RTLD_NEXT never searches and + * reports "undefined symbol". dlopen on the already-loaded library returns a + * handle to that same mapping, and dlsym through the handle works. + */ +static void *gomp(void) +{ + static void *h; + if (!h) { + h = dlopen("libgomp.so.1", RTLD_NOW | RTLD_NOLOAD); + if (!h) + h = dlopen("libgomp.so.1", RTLD_NOW); + if (!h) { + fprintf(stderr, "teamwidth: dlopen libgomp.so.1 failed: %s\n", + dlerror()); + _exit(96); + } + } + return h; +} + +static void *need(const char *sym, int code) +{ + void *p = dlsym(gomp(), sym); + if (!p) { + fprintf(stderr, "teamwidth: dlsym %s failed\n", sym); + _exit(code); + } + return p; +} + +static void resolve(void) +{ + if (!real_plain) real_plain = (plain_t)need("GOMP_parallel", 97); + if (!real_loop) + real_loop = (loop_t)need("GOMP_parallel_loop_nonmonotonic_dynamic", 98); + /* + * Both of these must come from libgomp, not from a thread-local counter of + * our own. A worker thread entering a region from inside its team sees its + * own TLS depth as 0 and would be charged as outermost -- the error that + * made an earlier shim report 755% of wall at 16 threads. + */ + if (!omp_level) omp_level = (int_fn_t)need("omp_get_level", 99); + if (!omp_width) omp_width = (int_fn_t)need("omp_get_num_threads", 95); +} + +static void bump_max(atomic_uint_fast64_t *slot, uint_fast64_t v) +{ + uint_fast64_t prev = atomic_load(slot); + while (v > prev && !atomic_compare_exchange_weak(slot, &prev, v)) + ; +} + +/* + * Runs as the team's body, once per thread. Every member of a team sees the + * same `omp_get_num_threads()`, so the atomic max collapses them to one + * observation per region and no count is needed. + */ +struct tramp { fn_t fn; void *data; }; + +static void observe(void *p) +{ + struct tramp *t = (struct tramp *)p; + /* + * Inside the region, so level 1 means this region is the outermost and + * level >= 2 means it is nested. An INACTIVE nested region -- the default, + * where OMP_MAX_ACTIVE_LEVELS is 1 -- still raises the level but has a + * width of 1, so it is recorded truthfully as a team of one and cannot + * look like a violation. + */ + const uint_fast64_t lvl = (uint_fast64_t)omp_level(); + const uint_fast64_t width = (uint_fast64_t)omp_width(); + + bump_max(&w_any, width); + bump_max(lvl >= 2 ? &w_nested : &w_outer, width); + bump_max(&d_max, lvl); + + t->fn(t->data); +} + +/* + * `t` lives on this frame, which is safe because GOMP_parallel is synchronous: + * it creates the team, runs the body on every member, joins, and only then + * returns. The trampoline cannot outlive the call that set it up. + */ +static void record_request(unsigned nthreads) +{ + atomic_fetch_add(&n_entries, 1); + if (nthreads == 0) + atomic_fetch_add(&n_unnamed, 1); + else + bump_max(&r_any, (uint_fast64_t)nthreads); +} + +void GOMP_parallel(fn_t fn, void *data, unsigned nthreads, unsigned flags) +{ + resolve(); + record_request(nthreads); + struct tramp t = { fn, data }; + real_plain(observe, &t, nthreads, flags); +} + +void GOMP_parallel_loop_nonmonotonic_dynamic(fn_t fn, void *data, + unsigned nthreads, long start, + long end, long incr, long chunk, + unsigned flags) +{ + resolve(); + record_request(nthreads); + struct tramp t = { fn, data }; + real_loop(observe, &t, nthreads, start, end, incr, chunk, flags); +} + +uint64_t beam_tw_outer(void) { return atomic_load(&w_outer); } +uint64_t beam_tw_nested(void) { return atomic_load(&w_nested); } +uint64_t beam_tw_widest(void) { return atomic_load(&w_any); } +uint64_t beam_tw_requested(void) { return atomic_load(&r_any); } +uint64_t beam_tw_unnamed(void) { return atomic_load(&n_unnamed); } +uint64_t beam_tw_entries(void) { return atomic_load(&n_entries); } +uint64_t beam_tw_depth(void) { return atomic_load(&d_max); } + +/* + * Reset before the call under test. Without this the counters would carry + * whatever `import BEAM` and the fixture build did, and the widest team in the + * process is not evidence about one API call. + */ +void beam_tw_reset(void) +{ + atomic_store(&w_outer, 0); + atomic_store(&w_nested, 0); + atomic_store(&w_any, 0); + atomic_store(&r_any, 0); + atomic_store(&n_unnamed, 0); + atomic_store(&n_entries, 0); + atomic_store(&d_max, 0); +} diff --git a/verification/tests/test_teamwidth.py b/verification/tests/test_teamwidth.py new file mode 100644 index 0000000..28bc864 --- /dev/null +++ b/verification/tests/test_teamwidth.py @@ -0,0 +1,207 @@ +"""The width of the teams BEAM actually creates, measured rather than read. + +Every thread check before this one was static. `check_lib.thread_count_clauses` +proves all 93 parallel regions NAME a thread count; the GIL scan proves every +GIL-releasing region RESOLVES a plan. Neither can see what the runtime granted, +and that gap is where the nesting defect lived: `beam_threads()` handed the +configured cap to a worker thread, so an 8-thread plan opened eight teams of +sixteen, while `thread counts` was OK in the very same gate run -- the clause +was present and correct and only its value on a worker was wrong. + +`verification/teamwidth.c` interposes the two libgomp entry points through which +BEAM creates teams and records, per region entry, the count REQUESTED and the +width that actually RAN. Measured on one `entropy()` call, plan pinned at 8: +**949 team creations**, which is why reading 93 pragmas was never going to +answer this. + +The two channels are not redundant, and the mutation that proves it is the +reason this file asserts on both. With the one-line guard removed from +`beam_threads()`: + + nesting ON (OMP_MAX_ACTIVE_LEVELS=2) requested 16, nested ran 16, plan 8 + nesting OFF (the default) requested 16, nested ran 1, plan 8 + +So in the environment every user actually gets, the defect was INVISIBLE in the +width that ran -- libgomp declines to widen a nested region when nesting is off, +so the actual teams were a blameless 8 and 1 -- and BEAM was still emitting +`num_threads(16)` on them. Only the runtime's default policy stood between the +plan and sixteen-way oversubscription. A check on the actual width alone would +have passed on the mutant; the requested channel catches it with no special +environment at all. That is why `test_no_region_asks_for_more_than_the_plan` is +the load-bearing test here and the actual-width tests back it up. + +`test_the_observer_wraps_every_team_creating_entry_point` is what keeps the +whole file honest: it reads the built extension's imports and fails if BEAM ever +grows a third way to create a team, because the observer would then be blind and +would go on reporting zero violations. And +`test_the_measurement_reached_a_nested_region` refuses to let a clean result +stand without evidence that the nested path ran at all -- a dead path and a +well-behaved one produce the same zero. +""" +import json +import os +import re +import subprocess +import sys +from pathlib import Path + +import pytest + +ROOT = Path(__file__).resolve().parents[1].parent +SHIM = ROOT / "build" / "teamwidth.so" +SHIM_SRC = ROOT / "verification" / "teamwidth.c" + +requires_shim = pytest.mark.skipif( + not SHIM.exists() or not sys.platform.startswith("linux"), + reason="needs Linux and build/teamwidth.so; run `make teamwidth` first") + + +# Builds a model, asks BEAM what it planned, resets the counters, makes ONE +# call, and reports. The reset matters: without it the widest team in the +# process would include the fixture's own build, and that is not evidence +# about the call under test. +_CHILD = """ +import ctypes, json, random +import BEAM +from BEAM import BeamModel + +lib = ctypes.CDLL(None) +NAMES = ("outer", "nested", "widest", "requested", "unnamed", "entries", "depth") +for n in NAMES: + f = getattr(lib, "beam_tw_" + n) + f.restype, f.argtypes = ctypes.c_uint64, [] +lib.beam_tw_reset.restype, lib.beam_tw_reset.argtypes = None, [] + +rng = random.Random(7) +seqs = ["TG" + "".join(rng.choice("ACGT") for _ in range(rng.randint(2, 20))) + "C" + for _ in range(800)] +m = BeamModel(seqs, abundances=[rng.randint(1, 40) for _ in seqs], + alphabet="nt", order=3, max_length=24) +plan = BEAM.parallel_plan()["plan"] + +lib.beam_tw_reset() +h = m.entropy() +out = {n: getattr(lib, "beam_tw_" + n)() for n in NAMES} +out["plan"] = plan +out["entropy"] = h +print(json.dumps(out)) +""" + +_CACHE: dict[bool, dict] = {} + + +def _observe(nesting: bool) -> dict: + """One child run, cached. `BEAM_AVAILABLE_CORES` pins the plan so the + assertions do not move with the load on the machine, and OMP_NUM_THREADS is + removed because setting it makes the policy stand aside entirely -- the plan + would then be the environment's number and the comparison vacuous. + + Attribution rests on where the reset goes. LD_PRELOAD interposes libgomp for + the whole process, so a counter read at exit would mix in anything else in + the process that uses OpenMP -- a BLAS built against libgomp, for instance. + The child resets immediately before the one call under test and reads + immediately after, and nothing else in that window calls out to another + library, so every region counted is BEAM's. The model is built BEFORE the + reset for the same reason.""" + if nesting in _CACHE: + return _CACHE[nesting] + env = dict(os.environ, BEAM_AVAILABLE_CORES="16", + LD_PRELOAD=str(SHIM)) + env.pop("OMP_NUM_THREADS", None) + if nesting: + env["OMP_MAX_ACTIVE_LEVELS"] = "2" + else: + env.pop("OMP_MAX_ACTIVE_LEVELS", None) + r = subprocess.run([sys.executable, "-c", _CHILD], capture_output=True, + text=True, encoding="utf-8", timeout=900, env=env) + assert r.returncode == 0, r.stderr[-3000:] + got = json.loads(r.stdout.strip().splitlines()[-1]) + if got["plan"] < 2: + pytest.skip(f"a plan of {got['plan']} cannot be exceeded by widening") + _CACHE[nesting] = got + return got + + +def test_the_observer_wraps_every_team_creating_entry_point(): + """The observer is only complete while BEAM creates teams through the entry + points it interposes. A third one would leave it blind AND quiet, which is + the worst failure a checking tool has: `nm` on the built extension is the + only thing that can tell the difference, so the set is derived from the + artifact and from the shim's own source, never written down here twice.""" + so = sorted(ROOT.glob("src/BEAM/_cbeam*.so")) + if not so: + pytest.skip("no built extension to read imports from") + out = subprocess.run(["nm", "--undefined-only", str(so[-1])], + capture_output=True, text=True, encoding="utf-8") + if out.returncode != 0: + pytest.skip("nm unavailable") + imported = {m.group(0) for m in + re.finditer(r"GOMP_parallel\w*", out.stdout)} + wrapped = set(re.findall(r"^void (GOMP_\w+)\(", SHIM_SRC.read_text( + encoding="utf-8"), re.MULTILINE)) + + missed = imported - wrapped + assert not missed, ( + f"BEAM creates teams through {sorted(missed)}, which the observer does " + f"not wrap: it would report zero violations while seeing none of them") + + +@requires_shim +def test_no_region_asks_for_more_than_the_plan(): + """The load-bearing one. A region's `num_threads(...)` is BEAM's own + arithmetic, and it is wrong independently of whether the runtime indulges + it: the mutant asks for 16 against a plan of 8 in the DEFAULT environment, + where every actual team is still the correct width. Catching that needs no + OMP_MAX_ACTIVE_LEVELS and no nesting -- only a count of what was asked.""" + got = _observe(nesting=False) + assert got["requested"] <= got["plan"], ( + f"a region asked for {got['requested']} threads against a plan of " + f"{got['plan']}; the runtime may have declined, which is luck, not " + f"design: {got}") + + +@requires_shim +def test_no_team_runs_wider_than_the_plan(): + got = _observe(nesting=False) + assert got["widest"] <= got["plan"], ( + f"a team ran {got['widest']} threads wide against a plan of " + f"{got['plan']}: {got}") + + +@requires_shim +def test_a_nesting_environment_widens_nothing(): + """`OMP_MAX_ACTIVE_LEVELS=2` is the environment the defect needed, and a + caller can set it: BEAM cannot pin it back without `omp_set_max_active_levels`, + process-global state that two calls on two threads would fight over. So the + guarantee has to hold under it rather than forbid it.""" + got = _observe(nesting=True) + assert got["nested"] <= got["plan"] and got["widest"] <= got["plan"], ( + f"nesting widened a team past the plan: {got}") + assert got["requested"] <= got["plan"], ( + f"nesting made a region ask past the plan: {got}") + + +@requires_shim +def test_every_region_that_ran_named_a_thread_count(): + """The runtime counterpart of `check_lib.thread_count_clauses`. That check + reads the sources and so covers regions whether or not they execute; this + one covers regions that executed whether or not the source scan understood + them. A zero here means no region reached libgomp with `nthreads == 0`, + which is what a missing clause looks like from the outside.""" + got = _observe(nesting=False) + assert got["unnamed"] == 0, ( + f"{got['unnamed']} of {got['entries']} regions ran without naming a " + f"thread count: {got}") + + +@requires_shim +def test_the_measurement_reached_a_nested_region(): + """Without this, every other assertion here could be passing because the + nested path never ran. A dead path and a well-behaved one both report + nothing, and the parallelism work has already been bitten once by a check + whose claim outran its evidence.""" + got = _observe(nesting=True) + assert got["entries"] > 0, f"the observer saw no teams at all: {got}" + assert got["depth"] >= 2, ( + f"no nested region was entered, so the nesting assertions prove " + f"nothing: {got}") diff --git a/verification/tests/test_tsan.py b/verification/tests/test_tsan.py index ddca8ba..cd2cfff 100644 --- a/verification/tests/test_tsan.py +++ b/verification/tests/test_tsan.py @@ -173,8 +173,13 @@ def test_the_instrumented_build_enables_avx(): warning should stand out.""" makefile = re.sub(r"\\\n\s*", " ", (ROOT / "Makefile").read_text(encoding="utf-8")) - recipe = re.search(r"^tsan:.*?(?=^\w|\Z)", makefile, - re.MULTILINE | re.DOTALL) + # Exactly one make recipe: the target line plus the tab-indented lines + # under it. An earlier version ran to the next line starting with a word + # character, which swallowed whatever target came next -- adding the + # teamwidth target between `tsan` and `clean` grew the match from 10 lines + # to 26, so this test would have passed on a Makefile where -mavx had + # drifted into a NEIGHBOURING recipe and out of this one. + recipe = re.search(r"^tsan:[^\n]*\n(?:\t[^\n]*\n)*", makefile, re.MULTILINE) assert recipe, "no tsan target in the Makefile" assert re.search(r"SANFLAGS=\"[^\"]*-mavx", recipe.group(0)), \ "the tsan recipe does not pass -mavx; vtrig.c will not compile"