MobileGL/docs/archive/notes/p5e/reports/fix1-v1.md

P5e fix1 — the by-handle attachment sync on the monolith arm (report v1)

Branch p5e/fix1, head 66621767, base 44f91c74 (P5e wave-2 integration). Tree ~/w7/p5e-fix1. One commit. Three files: MG_Backend/DirectGLES/Managers.cpp, MG_IntegrationTest/CMakeLists.txt, and a new MG_IntegrationTest/Scenarios/MonolithAttachmentClearScenario.cpp.

1 Root cause

The push build has TWO server arms and P5e only repaired one of them at this seam. Since P4a (D-C2) the push build resolves framebuffer ATTACHMENTS from the applier record in both arms — BackendFramebufferObject::SyncToBackend(const SharedPtr<FramebufferObject>&, target) computes pushedRecord gated on FramebufferSubsystemEnabled() alone, with no transport test — and under Transport == Monolith that object overload is what SyncCurrentFBO → SyncCurrentFBOByRecord reaches (DirectGLES.cpp:4304, the arm below FramebufferRecordArmIsMandatory()), which is exactly the frame the hs_err names. Package fb then dropped SyncAttachmentSurface's frontend attachment parameter and pointed its storage sync at tx2's SyncMipmapsToBackendByHandle, whose contract is "the noted handle routes the body onto the record arm". That contract is false on the monolith arm: the record arm inside SyncMipmapsToBackend is itself selected by MG_Config::Transport != Monolith (the texture-VIEW test at Managers.cpp:7397-7412 and RequireImageBindableStorage's re-dirty transition at :7458, both tx2's ruling-1 arms), so with a null SharedPtr and monolith transport control fell through to stateTextureObject->IsTextureView() and dereferenced null — the SIGSEGV at libMobileGL.so+0x80b57c in Lightmap.<init> → clearColorTexture → glClear. fb's report §7 enumerates the push-monolith deltas it took deliberately (the two cross-checks, the N-6 refusal) and this one — the storage sync itself — is not among them; it is an unnamed delta, and a fatal one. The renderbuffer half of the same function has the same arm error with a milder symptom (§3.2). Everything in the task brief's diagnosis is confirmed, with one correction: the governing arm selection that is missing is not "the monolith arm must not use the record-shaped attachment sync" (that is P4a's design and predates ID-81) but "the monolith arm must not use the by-handle STORAGE sync", which is the thing ID-81 actually governs.

2 The fix, and why this one

Three edits, all in Managers.cpp.

(a) SyncAttachmentSurface selects the storage sync by transport, and the monolith arm keeps its frontend object (Managers.cpp:10068-10230). The frontend attachment comes back as a const FramebufferAttachmentObject* parameter — null on the handle arm, &attachmentObject from the object-form walk — used for nothing but the storage sync: Transport != Monolith → SyncMipmapsToBackendByHandle(surface.Res) / RBO SyncToBackendByHandle(surface.Res) exactly as §5.4 prescribes; Transport == Monolith → SyncMipmapsToBackend(attachment->GetTexture()) / SyncToBackend(attachment->GetRenderbuffer()), which is f6cfcbd3's text token for token. Which arm is taken is decided by MG_Config::Transport and never inferred from the pointer, so the two statements cannot drift.

This is candidate (a) of the brief, narrowed to the seam ID-81 owns, plus candidate (c) as its backstop. I did not take (a) at the FBO sync site (gating pushedRecord itself on the transport): that would revert P4a's record-driven attach shape in the push-monolith build, silently moving draw-buffer decode, the four cross-object masks and the empty-point test back onto the frontend for the arm the phone ships on — a far larger behaviour change than the defect, and one that would reopen review N-6's hole (attach decided by the record, detach by the frontend). I did not take (b) (resolve the frontend object from the registry inside SyncMipmapsToBackendByHandle) because the registry cannot reliably answer: Entry::stateRef is written only by the minting GetOrCreate(StatePtr), and this path adopts its twin through AdoptTwinByHandle, which sets no stateRef — a texture that reaches the driver first as an attachment would get a null from StateForHandle and we would be back where we started, one indirection later. The caller has the object; asking it is honest and total.

(b) The null-frontend contract is named and enforced (Managers.cpp:6972-7017). RefuseNullFrontendTextureOffTheHandleArm(entry, notedHandle) is one shared check behind the new MGB_TEXTURE_NULL_FRONTEND_REFUSED macro, spelled by all three sync bodies (SyncMipmapsToBackend, SyncTextureParamsToBackend, SyncBuiltinSamplerToBackend) in place of the bare !obj && MGB_TEXTURE_HANDLE_ARM_OFF(*this) test. Semantics: no handle noted → decline as before; handle noted and (Transport != Monolith and TextureResourceSubsystemEnabled()) → proceed onto the record arm; handle noted on any other arm → Fatal{RoleViolation, "texture-handle-arm"} and std::abort(). So the shape becomes loudly named wherever it is not impossible, which is what the brief asked for and what makes the red-once below a named abort rather than a SIGSEGV. G1: the #else branch defines the macro to (true), so the pull build's preprocessed text is (!obj && true) — identical to before, no call added (the D-P rule MGB_TEXTURE_HANDLE_ARM_OFF was written for).

(c) The renderbuffer arm is arm-selected too, for a reason that is a behaviour delta rather than a crash: BackendRenderbufferObject::SyncToBackendByHandle dereferences nothing, but it deliberately drops the MGB_CTX->RecordError(OutOfMemory, …) the object form raises, "because on this arm there is no application on this side of the wire to report it to". On the push-monolith arm there is one, so the monolith arm keeps the object form.

3 The audit of the same class

The class: a by-handle seam that passes a null/empty frontend object and relies on a record arm being selected. I walked every one in MG_Backend/DirectGLES and checked each call site's arm selector by hand.

3.1 Defective, fixed. BackendTextureObject::SyncMipmapsToBackendByHandle, single call site SyncAttachmentSurface (Managers.cpp:10102) — the crash.

3.2 Same arm error, milder, fixed. BackendRenderbufferObject::SyncToBackendByHandle, single call site the same function (Managers.cpp:10201) — §2(c) above.

3.3 Checked and correct (transport-gated at every call site).

seam	call sites	selector
TextureImpl::SyncTextureToBackendByHandle (passes kNoFrontendTexture to all three sync bodies)	DirectGLES.cpp:2950, 2958 (fb's two attachment lists)	FramebufferRecordArmIsMandatory() at :3333
	:3230, 3243 (the unit work list)	UnitTexturesByHandle() at :2821
	:3669 (image bind)	reached only from the record overload, selected at :3824
	:10242, 10249 (blit expressed as a copy)	the record overload, selected at :10303 / :10378
	:11453, 11570, 11801 (CopyTex ×2, GenerateMipmap)	each its own Transport != Monolith
	Managers.cpp:7125 (a view's storage owner)	inside SyncTextureViewToBackendByRecord, itself behind :7397
BackendFramebufferObject::SyncToBackendByHandle / SyncReadBufferToBackendByHandle	DirectGLES.cpp:4265, 4267, 5905	FramebufferRecordArmIsMandatory(); bodies are record-only and hold no frontend object
BackendProgramObjectImpl::SyncToBackendByHandle	DirectGLES.cpp:5692 via SyncCurrentProgramByHandle	ProgramHandleArm(); it is a SEPARATE body from the object head, not the object body fed a null
RequireImageBindableStorageByHandle	Managers.cpp:7459	:7458, record-only body
SyncTextureViewToBackendByRecord	Managers.cpp:7450	takes a possibly-null object and guards it: if (stateTextureObject) SyncTextureViewToBackend(...)

3.4 Checked and correct by a different construction — null-tolerant AND transport-aware bodies. vi's and sb's buffer seams are the model this fix follows and they got it right: IsBufferDrawCleanByHandle(res, resource, nullptr) makes its one frontend read conditional on askTheObjectWhetherItIsMapped = (Transport == Monolith) and on frontend != nullptr, and EnsureBufferResourceForHandle(nullptr, res) returns resource->hostBytes under a transport and bufferObject->MappedData() only when it has an object. The record-arm callers are VertexInputReadsRecords()-gated and the push-monolith arm passes the real object (DirectGLES.cpp:1172 vs :1386); sb's whole walk is behind ResolveBufferBindingSubsystemArm(), which returns false under monolith.

3.5 One case named rather than changed. Managers.cpp:8650's kNoFrontendBuffer (the buffer-texture backing on the texBufferByRecord arm) is keyed on pushedStorage != nullptr && !MGB_TEXTURE_HANDLE_ARM_OFF(*this) — on a NOTED HANDLE, not on the transport. It is unreachable under monolith only because every writer of that note is transport-gated (§3.3), i.e. it is safe by a chain rather than by a statement. It does not crash (the callee is null-tolerant); what it would lose on the monolith arm is the live MappedData() base for a mapped buffer texture. I left it alone rather than widen this fix's blast radius. Ruling wanted: whether the handle-note should be re-stated as a transport test there, or whether "a handle is only ever noted under a transport" is to be made an invariant with a check of its own.

3.6 Not in this class, checked anyway. ScopedDetachedTextureFramebufferAttachments' handle arm and ForEachLive+StateForHandle (DirectGLES.cpp:11078) hold no null across a sync; Magma's VulkanRenderer.cpp is out of scope (ID-90 keeps it lockstep) and untouched.

4 The coverage hole, and what closes it

The hole is bigger than "no lane entry clears a texture-attached FBO" (ID-107), and it is structural. The gate runs -L unit and -L integration-split. Every integration-split entry exports MOBILEGL_TRANSPORT=inproc, which selects FramebufferRecordArmIsMandatory() and therefore SyncToBackendByHandle — the arm that never enters the object overload at all. And every P5-era scenario that does clear a texture-attached framebuffer (F1WireScenario and its family) calls SplitRuntimeSkipReason() in SetUp and skips itself the moment the runtime is not split, so the ambient monolith registration of those files runs zero cases. The push build's second runtime arm — the one the phone ships on — had no gated entry at all.

Measured on this tree, at HEAD's behaviour: ctest -L integration-gpu (the ungated monolith lane) is 1157 passed / 137 failed of 1294, every failure a DirectGLES SEGFAULT. The information was there; nothing the gate runs looked at it.

What I added. Scenarios/MonolithAttachmentClearScenario.cpp, three cases in the shape the existing scenarios use (fixture + attach + glClear + glReadPixels against pinned channel values): a mutable 2D texture attachment (glTexImage2D, the Lightmap shape, the arm that crashed), an immutable one (glTexStorage2D, so a regression confined to level definition cannot account for a green), and a renderbuffer (the sibling arm of §2(c)). The assertion is the pixel, not "it did not crash": a clear against a driver framebuffer whose attachment point was never filled raises GL_INVALID_FRAMEBUFFER_OPERATION and writes nothing, which is the silent form of the same defect and fails here too.

How it reaches the gate. A new DirectGLES.PushMonolithArm. block in MG_IntegrationTest/CMakeLists.txt, registered inside if (MOBILEGL_BUILD_DISAGGREGATED), with MOBILEGL_TRANSPORT=monolith as a ctest ENVIRONMENT property (review N-6's reason, the PersistentMapArm pair's precedent: a job-level inproc export must not be able to turn the other-arm lane into a fourth copy of the split one) and LABELS "integration-gpu;integration-split". The integration-split label on a monolith entry is a deliberate reading and the one thing in this package an integrator may want to overrule: that label does not mean "runs inproc", it means "the set the disaggregation gate runs", which is why the block above it argues that a build without -DMOBILEGL_BUILD_DISAGGREGATED=ON must match nothing under it — still true, since my block is inside that if. ID-81 gives the push build two arms; if only one of them is in the gated set, "the gate is green" keeps meaning "one of the two arms is green". The alternative, which I did not take because it edits shared tooling outside this tree, is to add -L integration-gpu (or a third label) to ~/w7/notes/tools/p5e_gate.sh.

integration-split is now 116 entries (113 + 3). The scenario is also registered ambiently, so DirectGLES.MonolithAttachmentClearScenario.* and DirectVulkan.MonolithAttachmentClearScenario.* exist in integration-gpu (9 entries in total, all green).

4.1 Red-once, executed and quoted verbatim

R1 — the arm selection reverted, the named refusal kept. SyncAttachmentSurface's if (MG_Config::Transport != Monolith) replaced by if (true); rebuilt. ctest -R 'PushMonolithArm.MonolithAttachmentClearScenario' → 33% tests passed, 2 tests failed out of 3:

	3457 - DirectGLES.PushMonolithArm.MonolithAttachmentClearScenario.AClearOfAMutableTextureAttachmentReachesItsPixels (Subprocess aborted) integration-gpu integration-split
	3458 - DirectGLES.PushMonolithArm.MonolithAttachmentClearScenario.AClearOfAnImmutableTextureAttachmentReachesItsPixels (Subprocess aborted) integration-gpu integration-split

and the abort is named, from the entry's own log (MOBILEGL_LOG_FILE_PATH, because MGLOG_F does not reach ctest's captured stdout):

[09:41:35] [Linux MobileGLIntegra/FATAL]: MGPipe: Fatal{RoleViolation, "texture-handle-arm"} - SyncMipmapsToBackend was handed a NULL frontend texture for handle {15, 0} on an arm that cannot answer without one. The by-handle entries pass null on the strength of a noted handle, and the record arm they rely on is selected by Transport != Monolith AND the texture-resource subsystem bit (CONTRACT-P5E §5.8, ID-81); neither holds here, so the body below would read a frontend object that does not exist

The renderbuffer case stays green, which is the control: that arm's by-handle form dereferences nothing.

R2 — both halves reverted (= HEAD's behaviour), the device's own crash. The refusal macro additionally reverted to MGB_TEXTURE_HANDLE_ARM_OFF; rebuilt. Running the case directly:

2258 Segmentation fault         ./MobileGLIntegrationTest --gtest_filter=MonolithAttachmentClearScenario.AClearOfAMutableTextureAttachmentReachesItsPixels
direct-run exit=139 (139 = SIGSEGV, 134 = SIGABRT)

and through ctest:

	3457 - DirectGLES.PushMonolithArm.MonolithAttachmentClearScenario.AClearOfAMutableTextureAttachmentReachesItsPixels (SEGFAULT) integration-gpu integration-split
	3458 - DirectGLES.PushMonolithArm.MonolithAttachmentClearScenario.AClearOfAnImmutableTextureAttachmentReachesItsPixels (SEGFAULT) integration-gpu integration-split

R3 — the whole monolith lane, before and after. Taken at R2's state and again at the restored head, same build flags, same machine:

ctest -L integration-gpu	result
HEAD's behaviour (R2)	1157 / 1294, 137 failed — 137 SEGFAULT, 0 Failed, 0 aborted, 0 timeout, all DirectGLES.
with the fix	1294 / 1294

The 137 span 38 distinct scenarios (36 pre-existing plus my two new prefixes) — OrientationScenario, PrimitiveRestartScenario, DepthStencilReadbackMatrixScenario, SnormAttachmentScenario, ThreeChannelAttachmentScenario, SampledSetStalenessScenario, PixelStoreSweepScenario, FramebufferChurnScenario, P4aSeamAuditScenario, CopyImageLayeredScenario, GuiBatchScenario, … — every one of them a case that renders to or clears a framebuffer holding a texture attachment. So the regression was never confined to the Lightmap path; it broke the monolith arm wholesale, and no gated lane entry touched it.

R4 — restored, markers clean. No RED-ONCE marker survives in the tree (grep, checked before the commit); the committed diff is the three files in §0.

5 Gate

step	result
build	rc=0
unit	2250 / 2250
isplit (integration-split)	116 / 116 (113 + the 3 new entries)
gens	all seven rc=0; the one doc-citation line (CONTRACT-P5.md:524 Core.cpp:39 ambiguous) is the pre-existing one every package has reported
one (the new entries)	9 / 9 on MonolithAttachmentClearScenario (3 DirectGLES., 3 DirectVulkan., 3 DirectGLES.PushMonolithArm.)
integration-gpu (not a gate step; measured for §4.1 R3)	1294 / 1294
strict	7 passed / 109 failed of 116. The 3 new entries pass (they are monolith, so no BARRIER-PULLED row is reachable); the 113 pre-existing entries are unchanged, and cannot be otherwise — every edit in this commit either selects the monolith arm or, under a transport, returns exactly what the pre-fix expression returned. No Fatal{UnmigratedPipeInput, …} marker moved.

6 What I could not settle

1. The integration-split label on a monolith lane (§4). My reading is that the label names the gate's set, not the transport, and that ID-81's second arm has nowhere else to live. The clean alternative is a gate-script change (-L integration-gpu, or a new integration-arms label) in ~/w7/notes/tools/p5e_gate.sh, which is outside this worktree and shared with every other package, so I did not touch it. Integrator's call.
2. The 137 monolith SEGFAULTs were latent for the whole of wave 2 and no package's gate could have seen them, because none of build/unit/isplit/strict/gens runs the monolith integration lane. Whether the phase should adopt integration-gpu as a standing gate step — it is ~10 minutes at -j 4 — is a phase-level decision, not fix1's.
3. Managers.cpp:8650's handle-note-keyed arm (§3.5): safe by a chain of transport-gated writers rather than by its own statement. Left alone deliberately.
4. No pull-build (G1) compile. The gate configures the split flavour only, as fb also reported. The argument that the pull build's bytes do not move is textual and I state it rather than measure it: SyncAttachmentSurface lives inside #if MOBILEGL_PIPE_PUSH and is not compiled there at all; the new refusal is inside the same #if, and its #else macro is (true), so the three guards' preprocessed text in the pull build is the pre-fix1 text token for token. A -DMOBILEGL_PIPE_PUSH=OFF configure would settle it.
5. No device run. I have no adb and did not take one. Request: one push-monolith run of Minecraft 26.3-rc-3 on the Redmi at 66621767 to confirm the startup crash is gone and the frame is correct, and — if it is cheap — one inproc run to confirm the split arm is still the 140-145 fps / 852-draws-per-frame shape ID-107 recorded, since this commit touches a line that both arms read (the arm selection itself).