[Docs] (.claude/skills, .github/workflows, CMakeLists.txt, docs/archive, docs/Disaggregated, docs/MobileVA, docs/Performance, MG_Backend, MG_Backend/DirectGLES, MG_Backend/DirectVulkan, MG_Backend/Record, MG_Gbm, MG_Impl, MG_Impl/EGLImpl, MG_Impl/GLImpl, MG_Impl/GLXImpl, MG_Impl/Pipe, MG_IntegrationTest, MG_IntegrationTest/Harness, MG_IntegrationTest/Scenarios, MG_Pipe, MG_Pipe/generated, MG_Remote, MG_Remote/Client, MG_Remote/Server, MG_Remote/Transport, MG_Remote/Wire, MG_State/GLState, MG_Test/Pipe, MG_Test/Util, MG_Test/Wire, MobileGL, scripts, scripts/data, tools/device_bench, userguide): archive the planning notes and agent contracts under docs/archive

- DEBTS.md and OPEN-QUESTIONS.md stay maintained, now in docs/Disaggregated.
This commit is contained in:
2026-10-15 20:01:45 -04:00
parent 0e3e2b7761
commit aabca3c171
1035 changed files with 410 additions and 398 deletions
+20
View File
@@ -0,0 +1,20 @@
# P13 W5 S3, round 1: the record arm's declarations (headers).
# Magma renderer: progress markers and the wire render-pass table are the record arm's; the shared-image
# registry is the transport's.
nest | MobileGL/MG_Backend/DirectVulkan/Renderer/VulkanRenderer.h | #include <MG_Remote/Server/SharedImageRegistry.h> | #include <MG_Remote/Server/SharedImageRegistry.h>
open | MobileGL/MG_Backend/DirectVulkan/Renderer/VulkanRenderer.h | #include "GpuProgressMarkers.h"
open | MobileGL/MG_Backend/DirectVulkan/Renderer/VulkanRenderer.h | VkBufferManager& GetWireBufferManager()
open | MobileGL/MG_Backend/DirectVulkan/Renderer/VulkanRenderer.h | GpuProgressMarkers m_progressMarkers;
nest | MobileGL/MG_Backend/DirectVulkan/Renderer/VulkanRenderer.h | MG_Remote::Server::SharedImages::ReadTracker m_sharedImageReads; | MG_Remote::Server::SharedImages::ReadTracker m_sharedImageReads;
open | MobileGL/MG_Backend/DirectVulkan/Renderer/VkTextureManager.h | Bool ReadUnbackedWireLevel(
open | MobileGL/MG_Backend/DirectVulkan/Renderer/VkTextureManager.h | Bool SyncWireTextureShape(
open | MobileGL/MG_Backend/DirectVulkan/Renderer/VkBufferObject.h | VkDeviceMemory m_externalMemory
open | MobileGL/MG_Backend/DirectVulkan/Renderer/UniformManager.h | struct WireImageViewKey {
open | MobileGL/MG_Backend/DirectVulkan/Renderer/UniformManager.h | Uint64 wireStoreDestroyEpoch = 0;
# Espryt managers: the record-keyed twin tables, the draw-input requests, the buffer twin's record fields,
# and the per-object death release (the monolith port drops its twins through it too).
open | MobileGL/MG_Backend/DirectGLES/Managers.h | "MGPipe: Fatal{ProtocolCorruption, \"BackendSlotTable.HandleSlot\"} - "
open | MobileGL/MG_Backend/DirectGLES/Managers.h | "MGPipe: Fatal{ProtocolCorruption, \"BackendSlotTable.Generation\"} - "
open | MobileGL/MG_Backend/DirectGLES/Managers.h | Uint64 BufferMutationEpochBumpsOffTheApplyThread();
open | MobileGL/MG_Backend/DirectGLES/Managers.h | Bool serverGpuWritten = false;
open | MobileGL/MG_Backend/DirectGLES/Managers.h | Bool ReleaseTwinsForWireObjectDeath(
+21
View File
@@ -0,0 +1,21 @@
# P13 W5 S3, round 2: the definitions the record arm links against (from the trial flip's undefined symbols).
open | MobileGL/MG_Backend/DirectGLES/Managers.cpp | Bool ResourceContentIsDeclared(
open | MobileGL/MG_Backend/DirectGLES/Utils.cpp | ActiveBackendFormatCaps()
open | MobileGL/MG_Backend/DirectVulkan/Renderer/VkBufferObject.cpp | ::MoveExternalFrom(
open | MobileGL/MG_Backend/DirectVulkan/Renderer/VulkanRenderer.cpp | ::LatchIfGpuHung(
open | MobileGL/MG_Backend/DirectVulkan/Renderer/VulkanRenderer.cpp | ::LatchWireDeviceLoss(
open | MobileGL/MG_Backend/DirectVulkan/Renderer/VkBufferManager.cpp | ::AcquireWireSlice(
open | MobileGL/MG_Backend/DirectVulkan/Renderer/VkBufferManager.cpp | ::RegisterWireResourceOps(
open | MobileGL/MG_Backend/DirectVulkan/Renderer/VkBufferManager.cpp | ::MarkWireBufferGpuWritten(
open | MobileGL/MG_Backend/DirectVulkan/Renderer/VkBufferManager.cpp | ::SweepDeferredWireReleases(
open | MobileGL/MG_Backend/DirectVulkan/Renderer/VkBufferManager.cpp | ::DestroyAllDeferredWireReleases(
open | MobileGL/MG_Backend/DirectVulkan/Renderer/VkTextureManager.cpp | ::ReadUnbackedWireLevel(
open | MobileGL/MG_Backend/DirectVulkan/Renderer/VkTextureManager.cpp | ::GrowWireTextureMipChain(
open | MobileGL/MG_Backend/DirectVulkan/Renderer/VkTextureManager.cpp | ::MarkWireTextureGpuWritten(
open | MobileGL/MG_Backend/DirectVulkan/Renderer/VkTextureManager.cpp | ::ResolveWireTextureStorage(
open | MobileGL/MG_Backend/DirectVulkan/Renderer/VkTextureManager.cpp | ::SyncTextureResourceByHandle(
open | MobileGL/MG_Backend/DirectVulkan/DirectVulkan.cpp | void InstallStateObjectDeathOps()
open | MobileGL/MG_Backend/MGPipe/PipeInputs.cpp | MGPipeStickyForwardPull(
open | MobileGL/MG_State/GLState/BufferState/BufferObject.cpp | ::NotePersistentMapStateChanged(
open | MobileGL/MG_State/GLState/BufferState/BufferObject.cpp | ::HasLiveHostWritesForWire(
open | MobileGL/MG_Backend/DirectVulkan/Renderer/UniformManager.cpp | ::ResolveWireUniformBufferPayload(
@@ -0,0 +1,3 @@
open | MobileGL/MG_Backend/DirectVulkan/Renderer/UniformManager.cpp | Bool UniformManager::PrepareWireTextureResources(
open | MobileGL/MG_Backend/DirectVulkan/Renderer/VertexInputStateFactory.cpp | Bool VertexInputStateFactory::BuildWireVertexInput(
open | MobileGL/MG_State/GLState/BufferState/BufferObject.cpp | SizeT BufferObject::ShadowAllocationBytes() const {
+156
View File
@@ -0,0 +1,156 @@
#!/usr/bin/env python3
"""P13 W5 inventory: every preprocessor group whose condition names MOBILEGL_BUILD_DISAGGREGATED,
classified by what its DISAGG-taken branch talks about.
w5_classify.py [--root DIR] [--csv OUT] [--summary]
Classes (W5 design §3.1):
A record terms, no transport token, no MG_Remote name -> becomes MOBILEGL_BUILD_RECORD_ARM
B names MG_Remote, no record term -> stays DISAGG
C names MG_Remote and record terms -> hand split
D transport token and record terms, no MG_Remote name -> hand split
E transport token, no record term, no MG_Remote name -> stays DISAGG
F none of the three -> reviewed, biased to record
N negated (`#if !MOBILEGL_BUILD_DISAGGREGATED`) or compound condition -> listed for the hand pass
Comments are stripped before matching. Nested DISAGG groups are listed with their depth; a rewrite
touches the outermost of a run and leaves inner transport groups as they are.
"""
import argparse
import csv
import pathlib
import re
import sys
SCAN = ['MobileGL']
SKIP_PARTS = {'MG_Remote', 'generated', '3rdparty'}
EXTS = {'.h', '.hpp', '.cpp', '.cc', '.inc', '.def'}
MACRO = 'MOBILEGL_BUILD_DISAGGREGATED'
DIRECTIVE = re.compile(r'^\s*#\s*(if|ifdef|ifndef|elif|else|endif)\b(.*)$')
TRANSPORT = [r'ClientSession', r'ServerSession', r'ServerLoop', r'Transport::', r'MG_Config::Ipc\b', r'Ipc\.',
r'SharedImage', r'AdoptT0', r'\bT0\b', r'externalAhb', r'RunsAsTheServerRole', r'CapsMirror',
r'SessionLatch', r'ServerRole', r'SplitRoles', r'TransportMode::Spawn', r'TransportMode::InProcess',
r'ServerOwnedWindow', r'ServerSetContextLive', r'DeviceLost', r'RoleSplit', r'ApplyThread',
r'MGPipeServerArm', r'MGPipeSessionLive', r'ClientBlock', r'EndedServerSession', r'OnApplyThread',
r'Transport\s*!=', r'Transport\s*==',
# Second pass (S2): transport-shaped words that name no MG_Remote symbol.
r'Window', r'SwapInterval', r'ContextLive', r'Ahb', r'AHardwareBuffer', r'HardwareBuffer', r'[Dd]ma[Bb]uf',
r'Gbm', r'SyncFile', r'sync_file', r'Session', r'Peer', r'Spawn', r'Tcp', r'Socket',
# Device loss and its recovery are a session's (the session ends, not the process).
r'Lost', r'Epoch', r'ResetNotif', r'Recover', r'StreamGate', r'ReplacementShare', r'ReplaceProcessDefault']
RECORD = [r'DataArmIsRecord', r'RecordArm', r'Staged', r'\bWire', r'MGPipe', r'Handle', r'Record\b', r'Twin',
r'Respecif', r'Readback', r'Verb', r'PersistentMap', r'GpuWrite', r'Emit', r'Applier', r'Slot',
r'Residual', r'ContextValues', r'Cso\b', r'CSO', r'Placeholder', r'Mipmap', r'Shadow']
TRANSPORT_RE = re.compile('|'.join(TRANSPORT))
RECORD_RE = re.compile('|'.join(RECORD))
REMOTE_RE = re.compile(r'MG_Remote')
def strip_comments(text):
text = re.sub(r'/\*.*?\*/', ' ', text, flags=re.S)
return re.sub(r'//[^\n]*', '', text)
def groups(lines):
"""Yield dicts for each #if group naming MACRO: open/else/close lines, condition, depth, body."""
stack = [] # entries: {'open', 'cond', 'kind', 'names', 'branches': [(line, kind)], 'depth'}
out = []
for no, raw in enumerate(lines, 1):
m = DIRECTIVE.match(raw)
if not m:
continue
kind, rest = m.group(1), strip_comments(m.group(2)).strip()
if kind in ('if', 'ifdef', 'ifndef'):
names = MACRO in rest
depth = sum(1 for s in stack if s['names'])
stack.append({'open': no, 'cond': (kind + ' ' + rest).strip(), 'names': names,
'branches': [(no, kind)], 'depth': depth})
elif kind in ('elif', 'else'):
if stack:
stack[-1]['branches'].append((no, kind))
elif kind == 'endif':
if not stack:
continue
g = stack.pop()
g['close'] = no
if g['names']:
out.append(g)
return out
def classify(path, lines):
rows = []
for g in groups(lines):
cond = g['cond']
plain = re.fullmatch(r'(if\s+' + MACRO + r'|ifdef\s+' + MACRO + r'|if\s+defined\s*\(?\s*' + MACRO +
r'\s*\)?)', cond) is not None
# The DISAGG-taken branch: first branch for a plain condition.
first_end = g['branches'][1][0] if len(g['branches']) > 1 else g['close']
body = strip_comments(''.join(lines[g['open']:first_end - 1]))
remote = bool(REMOTE_RE.search(body))
transport = sorted(set(t.group(0) for t in TRANSPORT_RE.finditer(body)))
record = bool(RECORD_RE.search(body))
if not plain:
cls = 'N'
elif remote and record:
cls = 'C'
elif remote:
cls = 'B'
elif transport and record:
cls = 'D'
elif transport:
cls = 'E'
elif record:
cls = 'A'
else:
cls = 'F'
rows.append({'file': path, 'open': g['open'], 'close': g['close'], 'lines': g['close'] - g['open'] + 1,
'depth': g['depth'], 'class': cls, 'cond': cond, 'has_else': len(g['branches']) > 1,
'transport': ' '.join(transport)[:120]})
return rows
def main():
ap = argparse.ArgumentParser()
ap.add_argument('--root', default='.')
ap.add_argument('--csv')
ap.add_argument('--summary', action='store_true')
args = ap.parse_args()
root = pathlib.Path(args.root)
rows = []
for top in SCAN:
for p in sorted((root / top).rglob('*')):
if p.suffix not in EXTS or not p.is_file():
continue
rel = p.relative_to(root)
if SKIP_PARTS & set(rel.parts):
continue
lines = p.read_text(encoding='utf-8', errors='replace').splitlines(keepends=True)
rows.extend(classify(rel.as_posix(), lines))
if args.csv:
with open(args.csv, 'w', newline='', encoding='utf-8') as f:
w = csv.DictWriter(f, fieldnames=list(rows[0].keys()) if rows else ['file'])
w.writeheader()
w.writerows(rows)
if args.summary or not args.csv:
by = {}
for r in rows:
top = r['file'].split('/')[1] if '/' in r['file'] else r['file']
if top.startswith('MG_Backend') and len(r['file'].split('/')) > 2:
top = '/'.join(r['file'].split('/')[1:3])
key = (top, r['class'])
n, l = by.get(key, (0, 0))
by[key] = (n + 1, l + r['lines'])
classes = 'ABCDEFN'
print('%-28s' % 'dir' + ''.join('%14s' % c for c in classes))
for top in sorted(set(k[0] for k in by)):
print('%-28s' % top + ''.join('%14s' % ('%d/%d' % by.get((top, c), (0, 0))) for c in classes))
tot = {c: (sum(by[k][0] for k in by if k[1] == c), sum(by[k][1] for k in by if k[1] == c)) for c in classes}
print('%-28s' % 'TOTAL blocks/lines' + ''.join('%14s' % ('%d/%d' % tot[c]) for c in classes))
return 0
if __name__ == '__main__':
sys.exit(main())
+117
View File
@@ -0,0 +1,117 @@
#!/usr/bin/env python3
"""P13 W5 S3: hand-directed guard edits, by content rather than line number.
w5_regate.py <ops-file>
Each non-comment line of the ops file is one operation (fields separated by ' | '):
open | <path> | <text> the `#if MOBILEGL_BUILD_DISAGGREGATED` group whose first body line
contains <text> becomes `#if MOBILEGL_BUILD_RECORD_ARM`
(with its #else / #endif comments)
nest | <path> | <first> | <last> wrap the lines from the one containing <first> through the one
containing <last> (searched after <first>) in
`#if MOBILEGL_BUILD_DISAGGREGATED` / `#endif`
line | <path> | <text> | <new> replace the one line containing <text> with <new> verbatim
Every <text> must match exactly one place (for `open`: exactly one group).
"""
import pathlib
import re
import sys
OLD = 'MOBILEGL_BUILD_DISAGGREGATED'
NEW = 'MOBILEGL_BUILD_RECORD_ARM'
DIRECTIVE = re.compile(r'^\s*#\s*(if|ifdef|ifndef|elif|else|endif)\b(.*)$')
def load(path):
raw = pathlib.Path(path).read_bytes().decode('utf-8')
return '\r\n' in raw, raw.replace('\r\n', '\n').split('\n')
def save(path, crlf, lines):
text = '\n'.join(lines)
pathlib.Path(path).write_bytes((text.replace('\n', '\r\n') if crlf else text).encode('utf-8'))
def groups(lines):
stack, out = [], []
for i, line in enumerate(lines):
m = DIRECTIVE.match(line)
if not m:
continue
kind = m.group(1)
if kind in ('if', 'ifdef', 'ifndef'):
stack.append({'open': i, 'branches': []})
elif kind in ('elif', 'else'):
if stack:
stack[-1]['branches'].append(i)
elif stack:
g = stack.pop()
g['close'] = i
out.append(g)
return out
def op_open(lines, text):
hits = []
for g in groups(lines):
if not re.match(r'^\s*#\s*if\s+' + OLD + r'\s*(//.*)?$', lines[g['open']]):
continue
end = g['branches'][0] if g['branches'] else g['close']
if any(text in l for l in lines[g['open'] + 1:end]):
hits.append(g)
# The innermost group that contains the text: drop any group that contains another hit.
hits = [g for g in hits if not any(h is not g and g['open'] < h['open'] and h['close'] < g['close'] for h in hits)]
if len(hits) != 1:
raise SystemExit('open: %d groups contain %r' % (len(hits), text))
g = hits[0]
for i in [g['open']] + g['branches'] + [g['close']]:
lines[i] = lines[i].replace(OLD, NEW)
def find_one(lines, text, start=0):
idx = [i for i in range(start, len(lines)) if text in lines[i]]
if not idx:
raise SystemExit('no line contains %r' % text)
if start == 0 and len(idx) != 1:
raise SystemExit('%d lines contain %r' % (len(idx), text))
return idx[0]
def main():
ops = [l for l in pathlib.Path(sys.argv[1]).read_text(encoding='utf-8').splitlines()
if l.strip() and not l.lstrip().startswith('#')]
files = {}
failed = 0
for op in ops:
parts = [p.strip() for p in op.split(' | ')]
kind, path = parts[0], parts[1]
if path not in files:
files[path] = load(path)
crlf, lines = files[path]
try:
apply_one(kind, lines, parts)
except SystemExit as failure:
print('FAILED:', op, '->', failure)
failed += 1
for path, (crlf, lines) in files.items():
save(path, crlf, lines)
print('applied', len(ops) - failed, 'of', len(ops), 'op(s) to', len(files), 'file(s)')
def apply_one(kind, lines, parts):
if kind == 'open':
op_open(lines, parts[2])
elif kind == 'nest':
a = find_one(lines, parts[2])
b = find_one(lines, parts[3], a)
lines[b + 1:b + 1] = ['#endif']
lines[a:a] = ['#if ' + OLD]
elif kind == 'line':
a = find_one(lines, parts[2])
lines[a] = parts[3]
else:
raise SystemExit('unknown op ' + kind)
if __name__ == '__main__':
main()
@@ -0,0 +1,94 @@
#!/usr/bin/env python3
"""P13 W5 S2: move the record arm's guards from MOBILEGL_BUILD_DISAGGREGATED to
MOBILEGL_BUILD_RECORD_ARM, by w5_classify.py's classes.
w5_rewrite.py [--root DIR] [--dir PREFIX ...] [--dry-run]
Rewritten (the macro on the opening line, and on its #else / #endif comment if it names it):
* a plain `#if MOBILEGL_BUILD_DISAGGREGATED` group of class A or F (record terms or nothing, no
transport word, no MG_Remote name);
* every plain `#if !MOBILEGL_BUILD_DISAGGREGATED` (the frontend arm of a build without the record arm);
* `#if MOBILEGL_PIPE_VERIFY && !MOBILEGL_BUILD_DISAGGREGATED` (the verify tree's frontend pins).
Left for the hand pass (S3): B, C, D, E and the compound guards; the MOBILEGL_PIPE_POISON arm in
PipeInputs.h stays on DISAGG on purpose (the FCL library must not pay a per-read poison check).
Tests (MG_Test, MG_IntegrationTest) are S6's.
While MOBILEGL_BUILD_RECORD_ARM equals MOBILEGL_BUILD_DISAGGREGATED (until S7) every rewrite is a
no-op for the compiler: both trees keep byte-identical code.
"""
import argparse
import pathlib
import re
import sys
sys.path.insert(0, str(pathlib.Path(__file__).parent))
import w5_classify as wc # noqa: E402
OLD = 'MOBILEGL_BUILD_DISAGGREGATED'
NEW = 'MOBILEGL_BUILD_RECORD_ARM'
SKIP_TOP = ('MobileGL/MG_Test/', 'MobileGL/MG_IntegrationTest/')
# S2 touches only the trees the record core lives in. The EGL layer, the GL context's device-loss
# state, the logger's role files and the stats dump paths are session machinery whose guards the
# token classes cannot tell apart from record code; they are S3's hand pass.
RECORD_DIRS = ('MobileGL/MG_Backend/DirectGLES/', 'MobileGL/MG_Backend/DirectVulkan/', 'MobileGL/MG_Backend/MGPipe/',
'MobileGL/MG_Pipe/', 'MobileGL/MG_Impl/Pipe/', 'MobileGL/MG_Impl/GLImpl/',
'MobileGL/MG_State/GLState/BufferState/', 'MobileGL/MG_State/GLState/ProgramState/',
'MobileGL/MG_State/GLState/FramebufferState/', 'MobileGL/MG_Util/SelfTest/')
def rewrite_file(path, rel, lines):
rows = wc.classify(rel, lines)
changed = []
for g in wc.groups(lines):
cond = g['cond']
plain = re.fullmatch(r'if\s+' + OLD, cond) is not None
negated = re.fullmatch(r'if\s+!\s*' + OLD, cond) is not None
verify_pin = re.fullmatch(r'if\s+MOBILEGL_PIPE_VERIFY\s*&&\s*!\s*' + OLD, cond) is not None
if plain:
cls = next(r['class'] for r in rows if r['open'] == g['open'])
if cls not in ('A', 'F'):
continue
elif not (negated or verify_pin):
continue
targets = [g['open']] + [no for no, kind in g['branches'][1:]] + [g['close']]
for no in targets:
line = lines[no - 1]
if no == g['open'] or OLD in line:
lines[no - 1] = line.replace(OLD, NEW)
changed.append((g['open'], 'plain' if plain else 'negated' if negated else 'verify-pin'))
return changed
def main():
ap = argparse.ArgumentParser()
ap.add_argument('--root', default='.')
ap.add_argument('--dir', action='append', default=[])
ap.add_argument('--dry-run', action='store_true')
args = ap.parse_args()
root = pathlib.Path(args.root)
total = 0
for p in sorted((root / 'MobileGL').rglob('*')):
if p.suffix not in wc.EXTS or not p.is_file():
continue
rel = p.relative_to(root).as_posix()
if wc.SKIP_PARTS & set(pathlib.PurePosixPath(rel).parts) or rel.startswith(SKIP_TOP) or not rel.startswith(RECORD_DIRS):
continue
if args.dir and not any(rel.startswith(d) for d in args.dir):
continue
raw = p.read_bytes().decode('utf-8')
crlf = '\r\n' in raw
lines = raw.replace('\r\n', '\n').splitlines(keepends=True)
changed = rewrite_file(p, rel, lines)
if not changed:
continue
total += len(changed)
print('%-70s %3d' % (rel, len(changed)))
if not args.dry_run:
text = ''.join(lines)
p.write_bytes((text.replace('\n', '\r\n') if crlf else text).encode('utf-8'))
print('groups rewritten:', total)
return 0
if __name__ == '__main__':
sys.exit(main())