Assert each syscall flag set and clear, and fix what it finds

Makefile

@@ -114,6 +114,11 @@ DISPATCH_HEADER := $(BUILD_DIR)/dispatch.h
 DEPARTED_MANIFEST := tests/usbdev-ioctl-departed.tbl
 DEPARTED_GENERATOR := scripts/gen-usbdev-ioctl-departed.py
 DEPARTED_HEADER := $(BUILD_DIR)/usbdev-ioctl-departed-vectors.h
+# The per-flag rows tests/test-flag-matrix.c runs. Generated under build/ for
+# the same reason the departed-device vectors are.
+FLAG_MATRIX_MANIFEST := tests/flag-matrix.tbl
+FLAG_MATRIX_GENERATOR := scripts/gen-flag-matrix.py
+FLAG_MATRIX_HEADER := $(BUILD_DIR)/flag-matrix-vectors.h
 HVF_LDFLAGS := -framework Hypervisor -framework IOKit -framework CoreFoundation -arch arm64
 
 # Generated headers under build/ that must exist before compiling sources that
@@ -155,6 +160,11 @@ $(DISPATCH_HEADER): $(DISPATCH_MANIFEST) $(DISPATCH_GENERATOR) src/syscall/abi.h
 
 $(BUILD_DIR)/syscall/syscall.o: $(DISPATCH_HEADER)
 
+$(FLAG_MATRIX_HEADER): $(FLAG_MATRIX_MANIFEST) $(FLAG_MATRIX_GENERATOR) \
+		$(DISPATCH_MANIFEST) | $(BUILD_DIR)
+	@echo "  GEN     $@"
+	$(Q)python3 $(FLAG_MATRIX_GENERATOR) --output $@
+
 $(DEPARTED_HEADER): $(DEPARTED_MANIFEST) $(DEPARTED_GENERATOR) \
 		src/syscall/usbdev.c | $(BUILD_DIR)
 	@echo "  GEN     $@"
@@ -402,6 +412,12 @@ $(BUILD_DIR)/test-usbdev-ioctl-departed: tests/test-usbdev-ioctl-departed.c \
 	@echo "  CROSS   $<"
 	$(Q)$(CROSS_COMPILE)gcc $(CROSS_TEST_CFLAGS) -I$(BUILD_DIR) -o $@ $<
 
+# test-flag-matrix includes its generated rows the same way.
+$(BUILD_DIR)/test-flag-matrix: tests/test-flag-matrix.c \
+		$(FLAG_MATRIX_HEADER) | $(BUILD_DIR)
+	@echo "  CROSS   $<"
+	$(Q)$(CROSS_COMPILE)gcc $(CROSS_TEST_CFLAGS) -I$(BUILD_DIR) -o $@ $<
+
 # test-usbdev-ioctl churns open/read/close on one usbdevfs node from four
 # threads, so a close and a sibling's open contend for the same fd number.
 $(BUILD_DIR)/test-usbdev-ioctl: tests/test-usbdev-ioctl.c | $(BUILD_DIR)

docs/testing.md

@@ -92,6 +92,8 @@ What they do:
 - `make check`: fast elfuse-internal gate. Runs, in order:
   - `scripts/check-syscall-coverage.py` so any new `dispatch.tbl`
     entry without a direct or aliased test reference fails the build
+    (the same script also requires the syscalls it lists as flag-taking to
+    keep their rows in `tests/flag-matrix.tbl`)
   - `scripts/check-eintr-contract.py` so a new interruptible wait fails
     the build until it states whether it may be restarted (`forbids`,
     `restartable`, or `not-a-wait`), with the `forbids` claims checked
@@ -116,6 +118,9 @@ What they do:
     asks make for the target list, which is the point: a `VERIFY_<T>_SRC`
     block written below the `:=` that builds `VERIFY_TARGETS` parses fine
     and generates no rule
+  - `scripts/gen-flag-matrix.py --check` so the generated rows of
+    `test-flag-matrix` match `tests/flag-matrix.tbl`, and so a row naming a
+    syscall `dispatch.tbl` no longer serves fails the build
   - the two harness self-tests, `test-config` (that `tests/test-config.sh`
     keeps its CLI mode separate from its sourced mode) and `test-runner`
     (the shared shell runner's output matching and exit-status checks), so
@@ -535,6 +540,29 @@ answers with its primary alone, because the backing half belongs to a stream
 that has gone. Both rows are load-bearing in pairs -- neither number alone
 separates the answers the site could give -- so both are printed.
 
+`test-flag-matrix` records what Linux answers for one flag of one syscall,
+with the flag set and with it clear, one row each in `tests/flag-matrix.tbl`.
+Both answers are asserted. Where they differ, the row passes only when the flag
+is what changes the result; a row whose last field is `=` records that Linux
+answers the same either way, and passes only when it does. The qemu lane runs
+the binary with `strict`, which is what keeps
+the recorded answers true; a row it refuses is a wrong row, not a kernel
+difference to skip. Two marks exist for elfuse. `pending` is a divergence still
+to be fixed: its mismatch is reported and not failed, and the lane fails once
+the row passes, until the mark is removed. `unsupported:ANSWER` is a flag
+elfuse declines on purpose, and ANSWER has to be one Linux documents for a
+kernel or filesystem without the feature. One row is pending by decision
+rather than by backlog: `pipe2 O_DIRECT@packets`. The host pipe is a byte
+stream, so an `O_DIRECT` pipe here delivers two writes in one read where Linux
+delivers the first alone. Giving the pipe a framed backing would fix `pipe2`
+and could not fix `F_SETFL` on a pipe that already exists; refusing the flag
+with `EINVAL`, which `pipe2(2)` documents for kernels that predate it, would
+undo the acceptance `test-negative` and `test-fcntl-flags` assert. Until one
+of those is chosen the row reports the difference on every run. To add a
+syscall, add rows; the
+driver has no code for any one call. A new kind of argument or answer goes
+into `scripts/gen-flag-matrix.py` and `tests/test-flag-matrix.c` together.
+
 `test-usbdev-ioctl-departed` is the same idea with the recording moved out of
 the lane and into data. Its rows are generated from
 `tests/usbdev-ioctl-departed.tbl`, one per usbdevfs ioctl, and a row that

mk/tests.mk

@@ -7,7 +7,7 @@
 # src/elfuse-limits.h.
 ELFUSE_HOST_NOFILE_MIN ?= $(shell bash "$(CURDIR)/tests/test-config.sh" --host-nofile)
 
-.PHONY: test-hello test-all check check-syscall-coverage check-eintr-contract check-lock-order check-atomics check-ascii check-usbdev-departed check-svc-tails check-skill-refs check-proof-targets test-gdbstub test-coreutils test-busybox test-shim-futex-stats test-vcpu-watchdog \
+.PHONY: test-hello test-all check check-syscall-coverage check-eintr-contract check-lock-order check-atomics check-ascii check-usbdev-departed check-flag-matrix check-svc-tails check-skill-refs check-proof-targets test-gdbstub test-coreutils test-busybox test-shim-futex-stats test-vcpu-watchdog \
         test-static-bins \
         test-dynamic test-dynamic-coreutils test-glibc-dynamic \
         test-glibc-coreutils test-perf \
@@ -309,7 +309,7 @@ check-sanitizer: $(ELFUSE_BIN) $(TEST_DEPS) $(CHECK_HOST_UNIT_BINS)
 	$(CHECK_SHARED_LANES)
 
 ## Run the unit test suite plus busybox applet validation
-check: $(ELFUSE_BIN) $(TEST_DEPS) check-syscall-coverage check-eintr-contract check-lock-order check-atomics check-ascii check-svc-tails check-skill-refs check-proof-targets check-usbdev-departed check-usb-fixture-bin test-config test-runner \
+check: $(ELFUSE_BIN) $(TEST_DEPS) check-syscall-coverage check-eintr-contract check-lock-order check-atomics check-ascii check-svc-tails check-skill-refs check-proof-targets check-usbdev-departed check-flag-matrix check-usb-fixture-bin test-config test-runner \
 		$(CHECK_HOST_UNIT_BINS)
 	@bash tests/driver.sh -e $(ELFUSE_BIN) -d $(TEST_DIR) -v
 	$(CHECK_SHARED_LANES)
@@ -1829,6 +1829,13 @@ check-usb-fixture-bin:
 check-usbdev-departed: $(DEPARTED_HEADER)
 	@python3 $(DEPARTED_GENERATOR) --check --output $(DEPARTED_HEADER)
 
+## Verify the generated flag-matrix rows still match tests/flag-matrix.tbl
+#
+# The generator also joins the table against dispatch.tbl, so a row for a
+# syscall the dispatcher no longer serves fails here.
+check-flag-matrix: $(FLAG_MATRIX_HEADER)
+	@python3 $(FLAG_MATRIX_GENERATOR) --check --output $(FLAG_MATRIX_HEADER)
+
 ## Build the fixture-enabled binary the two loopback lanes run
 #
 # The loopback fixture is not in the default build (USB_LOOPBACK_FIXTURE in

scripts/check-eintr-contract.py

@@ -352,7 +352,7 @@
         "not-a-wait",
         "Refuses the overlay because an execve is reaping this thread.",
     ),
-    "runtime/forkipc.c::sys_clone": (
+    "runtime/forkipc.c::clone_dispatch": (
         "not-a-wait",
         "Refuses the fork because an execve is reaping this thread.",
     ),

scripts/check-syscall-coverage.py

@@ -50,6 +50,53 @@
 }
 
 
+FLAG_MATRIX = TESTS / "flag-matrix.tbl"
+
+# Syscalls whose flags argument must have rows in tests/flag-matrix.tbl. A name
+# mentioned in a test says the call was made; a row says each flag was asserted
+# set and clear against a real kernel. Dropping the rows for one of these fails
+# the audit, and so does listing a syscall the dispatcher no longer serves.
+FLAG_MATRIX_REQUIRED: set[str] = {
+    "accept4",
+    "clone",
+    "dup3",
+    "epoll_create1",
+    "eventfd2",
+    "faccessat2",
+    "fchmodat",
+    "fchmodat2",
+    "fchownat",
+    "fcntl",
+    "inotify_init1",
+    "linkat",
+    "memfd_create",
+    "mmap",
+    "mprotect",
+    "newfstatat",
+    "openat",
+    "pipe2",
+    "renameat2",
+    "signalfd4",
+    "socket",
+    "socketpair",
+    "statx",
+    "timerfd_create",
+    "unlinkat",
+    "utimensat",
+}
+
+_ROW_PREFIX = re.compile(r"^(?:pending |unsupported:\S+ )?([a-z][a-z0-9_]*) \| ")
+
+
+def load_flag_matrix_names() -> set[str]:
+    names: set[str] = set()
+    for line in FLAG_MATRIX.read_text(encoding="utf-8").splitlines():
+        match = _ROW_PREFIX.match(line.strip())
+        if match:
+            names.add(match.group(1))
+    return names
+
+
 def load_dispatch_names() -> list[str]:
     names: list[str] = []
     for line in DISPATCH.read_text(encoding="utf-8").splitlines():
@@ -135,8 +182,28 @@ def main() -> int:
             continue
         missing.append(name)
 
+    matrix = load_flag_matrix_names()
+    no_rows = sorted(FLAG_MATRIX_REQUIRED - matrix)
+    not_dispatched = sorted(FLAG_MATRIX_REQUIRED - set(load_dispatch_names()))
+    unlisted = sorted(matrix - FLAG_MATRIX_REQUIRED)
+
     stale_indirect = sorted(set(INDIRECT_COVERAGE) - set(used_indirect))
+    failed = False
+    if no_rows or not_dispatched or unlisted:
+        failed = True
+        for label, names in (
+            ("Syscalls with no row left in tests/flag-matrix.tbl:", no_rows),
+            ("FLAG_MATRIX_REQUIRED entries absent from dispatch.tbl:",
+             not_dispatched),
+            ("Syscalls with rows but missing from FLAG_MATRIX_REQUIRED:",
+             unlisted),
+        ):
+            if names:
+                print(label, file=sys.stderr)
+                for name in names:
+                    print(f"  - {name}", file=sys.stderr)
     if missing or stale_indirect:
+        failed = True
         if missing:
             print("Uncovered syscalls in dispatch.tbl:", file=sys.stderr)
             for name in missing:
@@ -149,9 +216,11 @@ def main() -> int:
             )
             for name in stale_indirect:
                 print(f"  - {name}", file=sys.stderr)
+    if failed:
         return 1
 
     print("syscall coverage audit: PASS")
+    print(f"  flag matrix: {len(matrix)} syscalls have per-flag rows")
     for name, reason in sorted(used_indirect.items()):
         print(f"  indirect {name}: {reason}")
     return 0