swung0x48/MobileGL
1
0
Fork 0
mirror of https://github.com/MobileGL-Dev/MobileGL synced 2026-09-09 04:38:30 +09:00
Code Issues Packages Projects Releases Wiki Activity

[Feat] (Pipe): map every frontend mutator onto the aggregate generation that publishes it, and make the dirty-surface scanner a gate

Browse Source 
- MG_Pipe/DirtySurface.def: 73 rows, one per distinct mutator the scanner finds, each answering
  "what publishes this". The answer vocabulary is a MGPipeDirty bit name or one of five
  non-bit answers, and each of the five is documented in the file's header rather than left to
  be inferred: kImmediate, kReverseChannel, kNoBackendRead, kExplicitDestroy and
  kPulledEveryVerb. Where a mutator has more than one true answer the row carries the COARSER
  one - the one that cannot under-fire.
- gen_pipe_dirty_surface.py --check is the gate and it fails in BOTH directions: an unmapped
  mutator renders stale, and a row naming a mutator the scan no longer finds keeps a real hole
  looking covered. It also rejects an answer that is neither a documented non-bit answer nor a
  bit name read out of Tracker.h's own kMGPipeDirtyNames, so a renamed bit cannot leave a row
  silently pointing at nothing.
- --self-test runs three canned negative controls - a withheld mutator, a stale row, a bad
  answer - and each must trip; trips == 0 is itself an error, the shape
  check_include_closure.py and gen_pipe.py --self-test already use. ROADMAP.md's rule is that
  every gate must be able to go red for the reason it exists.
- --summary keeps working unchanged, because the CI file that still calls it belongs to
  another package until it lands.
- The human report prints the mapped answer where it printed UNMAPPED.
- FillPoints.def: the verdict on the eight statically over-approximated rows, recorded per
  group in the def's own comment. All eight are KEPT and the reason is the same in all three
  groups - each row names a concrete backend path (the depth/stencil read emulation's paused
  capture, VkClearManager::PreCompensateSrgbClearColor's GL_FRAMEBUFFER_SRGB read, the shader
  blit's viewport / provoking vertex / binding-point reads), and the only evidence that could
  retire one is dynamic. A corpus that never reaches a path proves nothing about it, and a row
  dropped on that basis turns a rare path into Fatal{UnmigratedPipeInput} in a shipped build.
  The contract's new FramebufferSrgb storage in fact makes one of the eight MORE load-bearing
  than it was, not less: it used to read a compile-time constant.
This commit is contained in:
swung0x48
2026-09-07 23:18:09 -04:00
parent 7dec32a574
commit 3302ee82b5
3 changed files with 363 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
scripts/gen_pipe_dirty_surface.py
+174 -18
View File
@@ -21,8 +21,10 @@ publish points, the ones that must map onto an aggregate generation.
P0 is the skeleton: it reports. P1 adds the mapping file and CI regenerates it with
`git diff --exit-code` and zero unmapped mutators, the same shape as gen_pipe.py's G6.
python3 scripts/gen_pipe_dirty_surface.py # human-readable report
python3 scripts/gen_pipe_dirty_surface.py --summary # counts only
python3 scripts/gen_pipe_dirty_surface.py # human-readable report
python3 scripts/gen_pipe_dirty_surface.py --summary # counts only
python3 scripts/gen_pipe_dirty_surface.py --check # THE GATE: rc 1 on any hole
python3 scripts/gen_pipe_dirty_surface.py --self-test # the gate's own negative controls
"""
import argparse
@@ -135,14 +137,76 @@ def scan_file(path):
return findings, all_mutators
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--summary", action="store_true", help="print the counts only")
args = parser.parse_args()
DEF_PATH = os.path.join(REPO_ROOT, "MobileGL", "MG_Pipe", "DirtySurface.def")
TRACKER_PATH = os.path.join(REPO_ROOT, "MobileGL", "MG_Impl", "Pipe", "Tracker.h")
if not os.path.isdir(SCAN_ROOT):
sys.exit("missing %s" % SCAN_ROOT)
ROW_RE = re.compile(r"^[ \t]*X\((\w+),\s*(\w+)\)\s*\\?\s*$", re.M)
DIRTY_NAME_RE = re.compile(r'^\s*"(NEW_[A-Z0-9_]+)",\s*$', re.M)
# The answers that are not a dirty-bit name. Each one is documented in DirtySurface.def's
# header; a row that uses anything else is a typo, and a typo that read as "mapped" would be
# exactly the silent hole this gate exists to close.
NON_BIT_ANSWERS = ("kImmediate", "kReverseChannel", "kNoBackendRead", "kExplicitDestroy",
"kPulledEveryVerb")
def dirty_bit_names():
"""The MGPipeDirty bit names, read out of Tracker.h's kMGPipeDirtyNames so a row cannot
name a bit that does not exist and a bit cannot be renamed out from under a row. Read
from the RAW text on purpose: the names are string literals, which is exactly what
mask_comments_and_strings blanks."""
with open(TRACKER_PATH, "r", encoding="utf-8", errors="replace") as handle:
return set(DIRTY_NAME_RE.findall(handle.read()))
def load_mapping(text=None):
"""{mutator: answer} from DirtySurface.def, or from `text` for the self-test."""
if text is None:
with open(DEF_PATH, "r", encoding="utf-8", errors="replace") as handle:
text = handle.read()
rows = {}
duplicates = []
for match in ROW_RE.finditer(mask_comments_and_strings(text)):
mutator, answer = match.group(1), match.group(2)
if mutator in rows:
duplicates.append(mutator)
rows[mutator] = answer
return rows, duplicates
def check_mapping(mapping, duplicates, scanned, bits):
"""Every problem the gate fails on, as a list of human-readable lines. BOTH directions:
an unmapped mutator renders stale, and a row naming a mutator the scan no longer finds is
a stale row that would keep a real hole looking covered."""
problems = []
for mutator in sorted(set(scanned) - set(mapping)):
problems.append("UNMAPPED mutator %s - add a row to MG_Pipe/DirtySurface.def" % mutator)
for mutator in sorted(set(mapping) - set(scanned)):
problems.append("STALE row %s - the scan no longer finds this mutator; delete the row"
% mutator)
for mutator in sorted(duplicates):
problems.append("DUPLICATE row %s" % mutator)
for mutator in sorted(mapping):
answer = mapping[mutator]
if answer in NON_BIT_ANSWERS:
continue
if answer in bits:
continue
problems.append("BAD answer %s for %s - not a MGPipeDirty bit name and not one of %s"
% (answer, mutator, ", ".join(NON_BIT_ANSWERS)))
return problems
SELF_TEST_WITHHELD = """
#define MGP_DIRTY_SURFACE_LIST(X) \\
X(RecordError, kReverseChannel)
"""
SELF_TEST_STALE = None # built from the real def at run time
def scan_all():
"""(findings-per-file, {mutator: call count}) over the whole scan root."""
sources = []
for root, _, files in os.walk(SCAN_ROOT):
for name in sorted(files):
@@ -150,15 +214,102 @@ def main():
sources.append(os.path.join(root, name))
sources.sort()
total_functions = 0
total_mutators = 0
deferred_mutators = 0
distinct_mutators = {}
per_file = []
distinct_all = {}
for path in sources:
findings, all_mutators = scan_file(path)
for mutator, _ in all_mutators:
distinct_all[mutator] = distinct_all.get(mutator, 0) + 1
per_file.append((path, findings, all_mutators))
return sources, per_file, distinct_all
def self_test(scanned, bits):
"""Canned negative controls. Each MUST trip; trips == 0 is an error, which is the shape
check_include_closure.py and gen_pipe.py --self-test already use."""
trips = 0
failures = []
# 1. a mutator withheld from the def.
mapping, duplicates = load_mapping(SELF_TEST_WITHHELD)
problems = check_mapping(mapping, duplicates, scanned, bits)
if any(p.startswith("UNMAPPED") for p in problems):
trips += 1
else:
failures.append("negative control 1 (a withheld mutator) did NOT trip")
# 2. a row naming a mutator the scan does not find.
real, real_duplicates = load_mapping()
with_ghost = dict(real)
with_ghost["SetSomethingThatDoesNotExist"] = "kImmediate"
problems = check_mapping(with_ghost, real_duplicates, scanned, bits)
if any(p.startswith("STALE") for p in problems):
trips += 1
else:
failures.append("negative control 2 (a stale row) did NOT trip")
# 3. a row whose answer is neither a dirty bit nor one of the documented non-bit answers.
with_typo = dict(real)
with_typo["RecordError"] = "NEW_TYPO_THAT_IS_NOT_A_BIT"
problems = check_mapping(with_typo, real_duplicates, scanned, bits)
if any(p.startswith("BAD answer") for p in problems):
trips += 1
else:
failures.append("negative control 3 (a bad answer) did NOT trip")
for failure in failures:
print("dirty-surface self-test: %s" % failure)
if trips == 0:
print("dirty-surface self-test: NOTHING tripped - the gate cannot fail, which is worse "
"than a red gate")
return 1
if failures:
return 1
print("dirty-surface self-test: %d negative controls, all tripped" % trips)
return 0
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--summary", action="store_true", help="print the counts only")
parser.add_argument("--check", action="store_true",
help="fail when a scanned mutator has no row in DirtySurface.def, or a "
"row names a mutator the scan no longer finds")
parser.add_argument("--self-test", action="store_true",
help="run the canned negative controls; each must trip")
args = parser.parse_args()
if not os.path.isdir(SCAN_ROOT):
sys.exit("missing %s" % SCAN_ROOT)
if not os.path.isfile(DEF_PATH):
sys.exit("missing %s" % DEF_PATH)
sources, per_file, distinct_all = scan_all()
bits = dirty_bit_names()
if not bits:
sys.exit("could not read the MGPipeDirty bit names out of %s" % TRACKER_PATH)
if args.self_test:
return self_test(distinct_all, bits)
mapping, duplicates = load_mapping()
if args.check:
problems = check_mapping(mapping, duplicates, distinct_all, bits)
for problem in problems:
print("dirty-surface: %s" % problem)
if problems:
print("dirty-surface: %d problem(s); the mapping must cover every mutator the scan "
"finds, in both directions" % len(problems))
return 1
print("dirty-surface: %d mutators, all mapped, no stale rows" % len(mapping))
return 0
total_functions = 0
total_mutators = 0
deferred_mutators = 0
distinct_mutators = {}
for path, findings, all_mutators in per_file:
deferred_mutators += len(all_mutators)
if not findings:
continue
@@ -175,7 +326,7 @@ def main():
print(" %s (line %d) -> backend: %s" % (finding["function"], finding["line"],
", ".join(finding["backend"][:4])))
for mutator, line in finding["mutators"]:
print(" %-44s :%d UNMAPPED" % (mutator, line))
print(" %-44s :%d %s" % (mutator, line, mapping.get(mutator, "UNMAPPED")))
print("\ndirty-surface: %d files scanned under MG_Impl/GLImpl" % len(sources))
print("dirty-surface: %d mutator calls in total, %d distinct mutators" % (deferred_mutators,
@@ -186,12 +337,17 @@ def main():
print("dirty-surface: the remaining %d are DEFERRED: nothing reaches the backend in the same "
"function, so the next verb publishes them, and each one needs an aggregate generation"
% (deferred_mutators - total_mutators))
print("dirty-surface: distinct mutators, by call count")
print("dirty-surface: distinct mutators, by call count, with what publishes each")
for mutator in sorted(distinct_all, key=lambda k: (-distinct_all[k], k)):
print(" %5d %s%s" % (distinct_all[mutator], mutator,
" (immediate)" if mutator in distinct_mutators else ""))
print("dirty-surface: every mutator above is UNMAPPED - the aggregate-generation mapping file "
"lands in P1, and this report is what it has to cover.")
print(" %5d %-42s %s%s" % (distinct_all[mutator], mutator,
mapping.get(mutator, "UNMAPPED"),
" (immediate)" if mutator in distinct_mutators else ""))
unmapped = sorted(set(distinct_all) - set(mapping))
if unmapped:
print("dirty-surface: %d UNMAPPED - run --check, which is a gate since P2" % len(unmapped))
else:
print("dirty-surface: every mutator above is mapped (MG_Pipe/DirtySurface.def); --check "
"is a gate and --self-test proves it can fail")
print("dirty-surface: known limits of this scanner - it matches braced function bodies "
"textually, so a mutator inside a lambda is attributed to the enclosing function, and a "
"mutation published through a helper the entry point calls reads as deferred here.")