[MG_Backend, MG_Impl, MG_Util, MG_Test, MG_IntegrationTest, docs] (P7): the server publishes kCapResidentSubData off its own wire resource table

CONTRACT-P7 §5.4, OQ-10. InitServerRoleCommon computes the whole capability mask and
never ORed this bit, so MGPipeResourceOpsHaveSubDataResident answered false under every
transport and BOTH backends were pinned to the ordered in-place host memcpy - which made
Magma's SubDataResident arm (VkBufferManager.cpp's g_vulkanWireResourceOps) dead code on
the wire even though the arm has been there since P5f.

The bit is derived from g_resourceOpsAtStep2->SubDataResident, i.e. from the pointer this
function already pinned at step 2 and that step 5 already refuses to see swapped - never
from ActiveBackendType. That is ID-39's lesson and not a style preference: a mask is a
statement about THIS backend's registered table, and a bit derived from the enum would
keep claiming the capability for a build, a flavour or a future backend whose table does
not carry the arm.

`rsd=` joins the emit[] bracket on the PipeStats summary line, counted at the emitter once
per buffer_subdata_resident record rather than once per call, because a write past the
content chunk cap is cut into several records. It is the only observable that separates
the resident arm from the memcpy beside it: the bytes in the buffer are identical either
way, which is exactly how the capability stayed unpublished for a phase with every lane
green.

WHAT THIS DOES NOT YET PROVE, and R-6 is the reason rather than an omission. §5.4 asks for
a white-box case showing opcode 49 on the wire. None can exist at this tree: the resident
arm is reached only from a GPU-RESIDENT store, residency comes only from
AdoptPersistentMap, and every persistent-map acquisition declines under split by R-6
(PipeApply.cpp:2331 "A SPLIT BUILD RUNS AT TIER T2 AND DECLINES EVERY ACQUISITION,
ALWAYS"; T0/T1 are P11's and AdoptTierIsEmulate is a named Fatal for them). So the
capability is wired AHEAD of its consumer, deliberately, and `rsd=` is what will show the
records the day P11 lands a tier that adopts. Filed for the integrator in
notes/p7/magma-c.md.

What IS proved is both halves of the bit itself. RemoteClientTest's Magma bootstrap case
now asserts the published bit EQUALS `ops->SubDataResident != nullptr` - the two compared
to each other rather than both to true, so the case also covers a backend without the arm
on the day one exists - and a new CtWireScenario case reads the bit out of the client's
own caps mirror, through the same accessor the frontend reads, on both backends and all
three transports.

RED-ONCE, both levels. Deleting the OR reds
CapsMirrorTest.MagmaTransportPublishesRealBufferConsumersWithoutRunAhead
(RemoteClientTest.cpp:692, "Which is: false / Which is: true") and all SIX arms of
DirectGLES/DirectVulkan x {Split,Spawn,Tcp} Ct.TheServerPublishesTheResidentSubData
CapabilityFromItsOwnTable ("the client's caps mirror did not receive
kCapResidentSubData"). Restored: green.

Also carries the P4a death-helper comment from the previous commit's sweep: it no longer
says Magma installs no death table, because it now does and still frees no slot.
This commit is contained in:
2026-09-22 16:07:58 -04:00
parent dce9953d36
commit 1255caa2fb
10 changed files with 251 additions and 2 deletions
@@ -2833,9 +2833,15 @@ endif()
# case's child truncates whatever path it inherits.
if (MOBILEGL_BUILD_DISAGGREGATED)
target_sources(MobileGLIntegrationTest PRIVATE Scenarios/CtWireScenario.cpp)
# P7 wave 2 package C adds the fifth: the OQ-10 capability read. It belongs in THIS list
# rather than in a buffer lane because the thing it reads is a property of the SESSION -
# what the server published at handshake and the client's mirror received - and this list
# is the one that is replayed on DirectVulkan by tier 2, so one name here gives the bit a
# reading on both backends and all three transports.
foreach(ctCase ApplierResetCrossesAtThePrimedEdgeInSerialOrder
TextureDeathCrossesAndTheRecycledSlotAnswersTheNewObject
FramebufferDeathCrossesAndTheRecycledSlotAnswersTheNewObject
TheServerPublishesTheResidentSubDataCapabilityFromItsOwnTable
TheDirectApplierResetCallOnTheGLThreadIsRoleViolation)
mgl_itest_register_split_arms("CtWireScenario.${ctCase}" "Ct.")
endforeach()
@@ -17,6 +17,7 @@
#if defined(MGITEST_SPLIT_RUNTIME_PEEK) && !defined(__ANDROID__)
#include <Config.h>
#include <MG_Remote/Client/CapsMirror.h>
#include <MG_Remote/Client/ClientSession.h>
#include <MG_Remote/Client/EmitTables.h>
#include <MG_Remote/Server/ServerLoop.h>
@@ -140,6 +141,12 @@ namespace MGITest {
const MobileGL::MG_Remote::Wire::PipeWireEncoder& encoder = session->Encoder();
state.emitSeq = encoder.EmitSeq();
state.runAheadArmed = session->RunAheadArmed();
// P7 wave 2 package C, OQ-10: read through the SAME accessor the frontend's own
// MGPipeResourceOpsHaveSubDataResident reads (MG_Impl/Pipe/PipeFill.cpp), so a
// green case here and a resident emission there cannot disagree about the bit.
state.residentSubDataCap =
MobileGL::MG_Remote::Client::CapsMirrorInstance().HasCap(
MobileGL::MG_Pipe::kCapResidentSubData);
state.presentCredit = MobileGL::MG_Config::Ipc.PresentCredit;
state.presentCreditWaits = session->PresentCreditWaits();
if (const auto* control = session->Control()) {
@@ -73,6 +73,16 @@ namespace MGITest {
// Real session state/watermarks. Only the client thread reads this snapshot;
// the scheduling observer below reads producerParked separately.
bool runAheadArmed = false;
// P7 wave 2 package C, OQ-10 (CONTRACT-P7 §5.4): kCapResidentSubData, as the CLIENT's
// caps mirror received it. This is the wire-level half of the bit's proof - the unit
// pair asserts that the SERVER derives it from its own resource table, and this says
// the client got what the server published, which is the only thing the frontend's
// MGPipeResourceOpsHaveSubDataResident can read under a transport.
//
// FALSE where the peek cannot look, like every field here, so a reader must have
// passed SplitRuntimeSkipReason() first: "no mirror" and "the bit was withheld" are
// the same false and completely different facts.
bool residentSubDataCap = false;
unsigned int presentCredit = 0;
unsigned long long appliedSeq = 0;
unsigned long long retiredSeq = 0;
@@ -206,6 +206,67 @@ namespace {
<< "Ct.TextureDeath.pixels - the recycled texture read back the dead twin's content";
}
// ------------------------------------------------------------------------------------
// P7 wave 2 package C, OQ-10 (CONTRACT-P7 §5.4): the resident-sub-data capability, read
// on the CLIENT, on a real session, on both backends and all three transports.
//
// WHAT IT PINS AND WHY IT IS HERE RATHER THAN IN A BUFFER SCENARIO. `kCapResidentSubData`
// is the one thing the frontend can ask, under a transport, about whether the side that
// will APPLY a write implements the resident arm: the client has no op table of its own
// to probe (MGPipeResourceOpsHaveSubDataResident says so in as many words) and reads this
// bit instead. Until this package nothing ever ORed it into the server's mask, so the
// answer was permanently "no" - which silently pinned BOTH backends to the ordered
// in-place host memcpy and made Magma's own SubDataResident arm
// (VkBufferManager.cpp's g_vulkanWireResourceOps) dead code on the wire. A capability
// that is never published is indistinguishable from one that does not exist, and no
// pixel, GL query or error can tell the two apart - so the bit itself is the assertion.
//
// THE SERVER HALF IS ASSERTED ELSEWHERE, deliberately: RemoteClientTest's
// MagmaTransportPublishesRealBufferConsumersWithoutRunAhead pins that the bit is DERIVED
// FROM THE SERVER'S OWN RESOURCE TABLE (`ops->SubDataResident != nullptr`) and never from
// a backend enum, which is ID-39's lesson. This case pins the other half - that what the
// server published actually reached the client - and the two together are what make the
// frontend's read of it mean anything.
//
// WHAT IT DOES NOT PIN, AND THE REASON IS R-6 RATHER THAN AN OMISSION. This does not
// assert that a `buffer_subdata_resident` record (opcode 49) crossed, because under a
// transport none can yet: the resident arm is reached only from a store that is GPU
// RESIDENT, residency comes only from AdoptPersistentMap, and every persistent-map
// acquisition declines under split by R-6 (PipeApply.cpp's MGPipeApplyMapPersistent:
// "A SPLIT BUILD RUNS AT TIER T2 AND DECLINES EVERY ACQUISITION, ALWAYS"; T0/T1 are
// P11's and AdoptTierIsEmulate is a named Fatal for them). So the capability is wired
// AHEAD of its consumer on purpose, and `rsd=` on the PipeStats line is the counter that
// will show the records the day P11 lands a tier that adopts. See notes/p7/magma-c.md.
TEST_F(CtWireScenario, TheServerPublishesTheResidentSubDataCapabilityFromItsOwnTable) {
if (!Ready()) return;
// A REAL WORKLOAD FIRST, and it is not decoration: ScenarioFixture's arming rule
// (ScenarioFixture.h:90) fails a case that runs in an armed split lane without moving
// the client encoder's record ordinal, because a case that emits nothing cannot tell
// "the transport resolved and carried this session" from "the emit table resolved and
// then put nothing on the wire". The bit below is a property OF that session, so the
// session has to have carried something before the reading means anything.
glClearColor(0.25f, 0.5f, 0.75f, 1.0f);
glClear(GL_COLOR_BUFFER_BIT);
GLubyte pixel[4]{};
glReadPixels(1, 1, 1, 1, GL_RGBA, GL_UNSIGNED_BYTE, pixel);
ASSERT_EQ(FirstGLError(), GLenum(GL_NO_ERROR)) << "Ct.ResidentSubDataCap.workload";
const int expected[4] = {64, 128, 191, 255};
for (int i = 0; i < 4; ++i) EXPECT_NEAR(pixel[i], expected[i], 1)
<< "Ct.ResidentSubDataCap.pixels";
const auto runtime = PeekSplitRuntime();
if (!runtime.peekAvailable || !runtime.sessionActive) {
GTEST_SKIP() << "no split runtime peek or no live client session: 'could not look' "
"and 'the bit was withheld' are the same false";
}
EXPECT_TRUE(runtime.residentSubDataCap)
<< "the client's caps mirror did not receive kCapResidentSubData on a "
<< runtime.transportName << " session with backend " << Gl().BackendName()
<< ". The server publishes it in MG_Backend/Init.cpp's InitServerRoleCommon from "
"its own wire resource table; without it every resident write falls back to "
"the in-place memcpy and opcode 49 never crosses on either backend";
}
TEST_F(CtWireScenario, FramebufferDeathCrossesAndTheRecycledSlotAnswersTheNewObject) {
if (!Ready()) return;
// Backend-agnostic for the texture case's reason (P7 wave 2 package C): both