[Docs] (.github/workflows, CMakeLists.txt, MG_Backend, MG_Backend/DirectGLES, MG_Backend/DirectVulkan, MG_Backend/MGPipe, MG_Backend/Record, MG_Impl/Pipe, MG_IntegrationTest, MG_IntegrationTest/Harness, MG_IntegrationTest/Scenarios, MG_Pipe, MG_Remote, MG_Remote/Client, MG_Remote/Server, MG_Remote/Transport, MG_Remote/Wire, MG_State/GLState, MG_Test, MG_Test/Buffer, MG_Test/Purity, MG_Test/Util, MG_Test/Wire, MG_Util/Metrics, MobileGL, scripts, tools/trace_replay): replace stale line-number citations with sections and symbols

This commit is contained in:
2026-10-15 10:15:35 -04:00
parent c4fb9397cb
commit 506ab1541d
55 changed files with 119 additions and 116 deletions
+1 -1
View File
@@ -2015,7 +2015,7 @@ else()
"PersistentCoherentMapScenario's membership assertion SKIPS")
endif()
# ARCHITECTURE.md:543 - every new ctest ENVIRONMENT and add_trace_replay_test's SPLIT branch
# ARCHITECTURE.md §15.1 - every new ctest ENVIRONMENT and add_trace_replay_test's SPLIT branch
# carries MOBILEGL_IPC_SERVER_PATH, because the dladdr fallback cannot find the server from a
# binary that links MobileGL_s statically. P5 is inproc-only and nothing reads the value yet; it
# is carried now so that an unparsed variable and a parsed-and-ignored one stop being
@@ -11,7 +11,7 @@
// no-op, hidden by the pre-handle program pass binding the same values) and F-2 / SD-4 (the
// shader-image window does not follow a program switch, hidden by the server's window/high-water
// union taking the pre-handle bind for the units outside it). Both are correct pictures over a
// permanent silent fallback, which is precisely the class ROADMAP.md:20 says a gate has to be
// permanent silent fallback, which is precisely the class ARCHITECTURE.md §13.2 says a gate has to be
// able to make red - and the only place the difference exists is inside.
//
// A SEPARATE TRANSLATION UNIT for PipeApplyPeek.h's reason, verbatim: this file includes
@@ -1760,7 +1760,7 @@ void main() { oColor = texture(uTex, vec2(4.0, 4.0)); }
//
// A sampler view is the RESOLVED (texture, sampler) pair - what the unit actually
// samples - and P4a addresses it by IDENTITY per texture object (D-F2, the deviation
// from ARCHITECTURE.md:63's content-addressed 4096-entry cache, which is P7's). So the
// from ARCHITECTURE.md §2.3's content-addressed 4096-entry cache, which is P7's). So the
// view's key names the texture; the case recycles the TEXTURE while an explicitly bound
// SAMPLER OBJECT stays alive and unchanged across the window, so what a stale view
// would inherit is the dead texture through a live sampler - which the texture case
@@ -30,7 +30,7 @@
// changes what the three above assert:
//
// * AnAdoptionCostsExactlyOneMapPersistentRoundtrip counts the acquisition.
// ARCHITECTURE.md:474 prices the adopted store at one round trip per STORAGE
// ARCHITECTURE.md §12 prices the adopted store at one round trip per STORAGE
// DEFINITION; `map-persistent-roundtrips` counts every map_persistent
// emission, mint or decline (D-B2), so one definition plus a frame of draws
// must publish exactly one. It reads the library's summary line, so it needs
@@ -602,7 +602,7 @@ void main() { word = 0xC0FFEEu; }
ASSERT_GE(roundtrips, 0) << "the summary line carries no mpr= field: " << window.line;
EXPECT_EQ(roundtrips, 1)
<< "one storage definition of an adopted arena is one map_persistent emission "
"(ARCHITECTURE.md:474, D-B2: mint OR decline, both need an answer from the resource "
"(ARCHITECTURE.md §12, D-B2: mint OR decline, both need an answer from the resource "
"owner). This window defined the arena once and drew from it "
<< kDrawsInTheWindow << " times, so 1 is the whole cost; " << kDrawsInTheWindow
<< " would mean the acquisition moved onto the draw path - the ~167 ms/arena hiccup this "
@@ -573,7 +573,7 @@ void main() { oColor = texture(uTex, vUv); }
// (texture resources). Every MGPBoundView::Texture and every MGPImageView::Res names a
// Texture handle, and only bit 10 populates the texture slot table, so with bit 11 alone
// every lookup would miss and the unit walk would `continue` without unbinding - a
// half-run subsystem, which ROADMAP.md:7 forbids as loudly as a dead switch. The bring-up
// half-run subsystem, which ARCHITECTURE.md §13.2 forbids as loudly as a dead switch. The bring-up
// logs ONE error naming both bits, refuses bit 11, and runs the legacy sampler arm.
//
// TWO ASSERTIONS, and the second is the one that stops this from being a log-scraping test:
@@ -54,7 +54,7 @@
// only ever sees whichever arm its driver and transport happen to give it.
//
// `mpr` (map-persistent-roundtrips) is counted per ACQUISITION ATTEMPT, mint or decline
// (ARCHITECTURE.md:492), so it is the SAME NUMBER on both arms and in both transports: that is
// (ARCHITECTURE.md §12), so it is the SAME NUMBER on both arms and in both transports: that is
// what makes exit gate E3(c)'s "mpr equal to the monolith arm's" checkable by one process. Both
// lanes assert the same constant against the same workload, so the equality holds by
// construction and each lane can fail on its own.
@@ -519,9 +519,8 @@ void main() { oColor = vec4(vColor, 1.0); }
ASSERT_GE(roundtrips, 0) << "the summary line carries no mpr= field: " << window.line;
EXPECT_EQ(roundtrips, kExpectedRoundtrips)
<< "one PERSISTENT|WRITE|COHERENT map of one freshly defined store is ONE acquisition "
"attempt, mint or decline (ARCHITECTURE.md:492). This window mapped once and drew "
<< kDrawsInTheWindow << " times, so " << kExpectedRoundtrips << " is the whole cost; "
<< kDrawsInTheWindow
"attempt, mint or decline (ARCHITECTURE.md §12). This window mapped once and drew "
<< kDrawsInTheWindow << " times, so " << kExpectedRoundtrips << " is the whole cost; " << kDrawsInTheWindow
<< " would mean the acquisition moved onto the draw path. The number is counted as "
"ATTEMPTS precisely so that it is the SAME on the adopted and the emulated arm and "
"under both transports - which is what makes exit gate E3(c)'s 'mpr equal to the "
@@ -102,7 +102,7 @@ namespace MGITest {
// as a hard SIGSEGV in the vertex fetch; that detour is what ID-9 supersedes.
//
// The COUNT is unaffected by the change: two storage definitions either way, which is
// what ARCHITECTURE.md:474 prices.
// what ARCHITECTURE.md §12 prices.
constexpr int kDefinitionsInTheWindow = 2;
constexpr int kDrawsPerDefinition = 3;
constexpr int kInset = 2;
@@ -20,7 +20,7 @@
// The assertion is deliberately on the WHOLE grown range, so a partial write names the byte the
// stale extent stopped at.
//
// P3a ADDS THE COST OF THAT REGROWTH (gate G10). ARCHITECTURE.md:474 prices a persistently mapped
// P3a ADDS THE COST OF THAT REGROWTH (gate G10). ARCHITECTURE.md §12 prices a persistently mapped
// store at "one round trip per STORAGE DEFINITION, not one per store" - and, emphatically, not one
// per draw. `map-persistent-roundtrips` (`mpr=` in the summary line) counts every map_persistent
// EMISSION, mint or decline (D-B2), so the claim is directly countable: N definitions of an
@@ -297,9 +297,9 @@ void main() {
"map-persistent-roundtrips counter to read: " << window.line;
EXPECT_EQ(roundtrips, static_cast<long long>(kAdoptedDefinitions))
<< "an adopted store costs ONE map_persistent per STORAGE DEFINITION "
"(ARCHITECTURE.md:474). This window defined the store " << kAdoptedDefinitions
<< " times and dispatched " << kDispatchesPerDefinition << " times against each of them, so "
<< kAdoptedDefinitions << " is the whole cost. "
"(ARCHITECTURE.md §12). This window defined the store "
<< kAdoptedDefinitions << " times and dispatched " << kDispatchesPerDefinition
<< " times against each of them, so " << kAdoptedDefinitions << " is the whole cost. "
<< (kAdoptedDefinitions * kDispatchesPerDefinition)
<< " would mean an acquisition per DRAW - the regression this counter exists to catch - and 0 "
"would mean nothing emitted map_persistent at all. It reported: "
@@ -7,9 +7,9 @@
// End of Source File Header
//
// Scenario - A TEXTURE'S PARAMETERS TAKE EFFECT EVEN WHEN IT HAS NO SAMPLER VIEW (gate G9), the
// one scenario ROADMAP.md:20 names by hand and requires to be RED before P4a lands.
// one scenario the acceptance gate names by hand and requires to be RED before P4a lands.
//
// THE DESIGN STATEMENT IT TESTS, ARCHITECTURE.md:100 (D10), verbatim: "SetTextureParams 按资源寻址、
// THE DESIGN STATEMENT IT TESTS, ARCHITECTURE.md §3.2 (D10), verbatim: "SetTextureParams 按资源寻址、
// 与 sampler view 分开(D10):只作 FBO attachment / image 单元 / glCopyImageSubData 端点的纹理没有
// sampler view,但 Espryt 对 attachment 也同步纹理参数,且 RequireImageBindableStorage 需要在前端参数
// 版本不动时强制重同步." A texture that is only an attachment, only an image-unit binding or only a
@@ -48,7 +48,7 @@
// in particular they would go RED if any of the four reachability paths were ever made to
// depend on the texture having a sampler VIEW - which is exactly the coupling P4a's
// resource-addressed set_texture_params removes and the thing a later phase could reintroduce;
// * the "落地前必须红" artefact ROADMAP.md:20 asks for is NOT produced by the public-GL half
// * the "must be red before landing" artefact the acceptance gate asks for is NOT produced by the public-GL half
// of this file, and no public-GL integration scenario on a monolith tree can produce it.
// Producing it needs an observation of the DRIVER's texture object taken while the texture is
// still read-attachment-only. ID-19 rules that G9 is therefore a WHITE-BOX assertion, and this
@@ -109,7 +109,7 @@
// (DirectGLES.cpp:1944), so a texture that is exclusively a READ attachment gets its STORAGE synced
// and its PARAMETERS never. P4a closes that gap deliberately (D-E3): the record is addressed by
// resource, and Espryt's SyncAttachmentObject applies parameters for ANY attachment, draw or read.
// It is a behaviour change and it is the deliverable, not a drive-by dev fix (ROADMAP.md:98).
// It is a behaviour change and it is the deliverable, not a drive-by dev fix (guide/discipline.md).
//
// HOW EACH CASE OBSERVES "REACHED THE DRIVER", and why the observation is always a LATER SAMPLE.
// A texture parameter is by definition a sampling parameter: nothing about an attachment, an image
@@ -524,7 +524,7 @@ void main() {
}
// ------------------------------------------------------------------------------------
// 2. READ ATTACHMENT ONLY - THE MANDATORY RED (ROADMAP.md:20, D-E3, G9).
// 2. READ ATTACHMENT ONLY - THE MANDATORY RED (D-E3, G9).
//
// The parameter is GL_DEPTH_STENCIL_TEXTURE_MODE and the texture is a packed
// depth/stencil one, because that is the parameter whose absence is not a mis-filtered
@@ -652,7 +652,7 @@ void main() {
"unsynced parameter (see this file's header: the unit sync list calls "
"SyncTextureParamsToBackend whenever the params version moved) - a red here means "
"something stronger than the D-E3 gap: a reachability path that does not sync "
"parameters AT ALL, i.e. the sampler-view coupling ARCHITECTURE.md:100 (D10) "
"parameters AT ALL, i.e. the sampler-view coupling ARCHITECTURE.md §3.2 (D10) "
"exists to remove. Read the case's own stdout line for the GL error the sample "
"raised before assuming an aspect-mode bug.";
@@ -11,7 +11,7 @@
// WHAT IT IS FOR. SSIM is completely blind to the difference between "one union box" and "N
// separate rects", and that difference is the Mali upload cliff: Mali prices an upload by the
// number of JOBS, and ~100 one-rect sprite jobs against one union box measured +6 ms/frame
// (ARCHITECTURE.md:249-251). Every gate in the phase can be green while the emission shape has
// (ARCHITECTURE.md §6). Every gate in the phase can be green while the emission shape has
// silently inverted, so the shape needs a number - and there are TWO numbers, deliberately:
//
// tex[emit= box= rect= jobs=] the SERVER's count, Espryt's own, which has existed since P2
@@ -633,10 +633,11 @@ void main() { oColor = texture(uTex, vUv); }
EXPECT_EQ(rect, kGold.RectEmissions)
<< "the BOX/RECT split moved: " << rect << " rect-list emissions against a gold of "
<< kGold.RectEmissions
<< ". This is the direction that costs ~+6 ms/frame on Mali (ARCHITECTURE.md:249-"
"251): the driver is handed N upload jobs where it used to be handed one, and no "
<< ". This is the direction that costs ~+6 ms/frame on Mali (ARCHITECTURE.md §6): "
"the driver is handed N upload jobs where it used to be handed one, and no "
"SSIM case can see it. If this is intended, re-measure the row and say so in "
"docs/Disaggregated/MEASUREMENTS.md. " << shapeWindow.line;
"docs/Disaggregated/MEASUREMENTS.md. "
<< shapeWindow.line;
EXPECT_EQ(jobs, kGold.Jobs)
<< "the JOB count moved: " << jobs << " against a gold of " << kGold.Jobs
<< ". Jobs are what Mali prices the upload by. " << shapeWindow.line;