[Chore, Docs] (...): drop the archived notes and move the skill under tools

- the archive freeze rule goes with the directory
- code comments lose citations to the removed notes
This commit is contained in:
BZLZHH
2026-10-31 19:29:06 +08:00
parent b5d64175a1
commit 6e36bf2c1b
1064 changed files with 1022 additions and 200727 deletions
+1 -1
View File
@@ -300,7 +300,7 @@ TEST_F(FieldOwnershipTest, VerbBoundaryOpsCoverEveryVerbShapedCall) {
EXPECT_EQ(MGPipeVerbForWireOp(MGPWireOp::ResumeStreamOutput), MGPipeVerb::ResumeTransformFeedback);
EXPECT_EQ(MGPipeVerbForWireOp(MGPWireOp::GenerateMipmap), MGPipeVerb::GenerateMipmap);
EXPECT_EQ(MGPipeVerbForWireOp(MGPWireOp::GetTextureImage), MGPipeVerb::GetTextureImage);
// P5b (docs/archive/contracts/CONTRACT-P5B.md): the renamed boundary the file left to "the phase that
// P5b: the renamed boundary the file left to "the phase that
// emits it" - resource_copy_region is glCopyImageSubData only - and the five appended verbs,
// each stamped as the GLFunctionsTable verb it reproduces. copy_framebuffer_to_texture also
// carries glCopyTexSubImage2D and stamps CopyTexImage2D for both: one kBlitOrCopy mask.
+16 -16
View File
@@ -137,10 +137,10 @@ TEST(PipeCatalogue, GeneratedTablesHoldTheWholeCatalogue) {
EXPECT_EQ(kMGPipeContextCallCount, kMGPipeCallCount - ClassCount<kScreen>());
// The per-class counts PipeCalls.def documents in its header.
// kScreen is 11 + P5c's applier_reset (docs/archive/contracts/CONTRACT-P5C.md §5.1); kCtxObject is
// kScreen is 11 + P5c's applier_reset (§5.1); kCtxObject is
// 9 + P5c's object_death (§5.2), the framebuffer family's first wire delete opcode.
// kCtxState is 17 + P5c rv's set_context_values (§5.3), the residual-value record, + P5e's
// set_program_bindings (docs/archive/contracts/CONTRACT-P5E.md §1), the post-link binding record.
// set_program_bindings (§1), the post-link binding record.
// + P14 S1's bind_context (docs/Disaggregated/design/11-state-ownership.md), the in-band
// context binding - a kScreen row for applier_reset's reason: a context switch is a
// whole-session edge, not a context-family verb.
@@ -148,9 +148,9 @@ TEST(PipeCatalogue, GeneratedTablesHoldTheWholeCatalogue) {
EXPECT_EQ(ClassCount<kCtxQuery>(), 8u);
EXPECT_EQ(ClassCount<kCtxCso>(), 13u);
EXPECT_EQ(ClassCount<kCtxState>(), 19u);
// + P9's get_texture_image_to_buffer (docs/archive/contracts/CONTRACT-P9.md §1), beside get_texture_image.
// + P9's get_texture_image_to_buffer (§1), beside get_texture_image.
EXPECT_EQ(ClassCount<kCtxObject>(), 11u);
// 13 + the five P5b-appended verbs (docs/archive/contracts/CONTRACT-P5B.md): bind_shader_image,
// 13 + the five P5b-appended verbs: bind_shader_image,
// patch_parameter, bind_stream_output, set_storage_block_binding,
// copy_framebuffer_to_texture; + delete_stream_output; + P9's read_pixels_to_buffer.
EXPECT_EQ(ClassCount<kCtxVerb>(), 20u);
@@ -588,7 +588,7 @@ TEST(PipeCatalogue, LateArrivalsAreAppendedWithoutRenumbering) {
EXPECT_EQ(static_cast<Uint16>(MGPWireOp::QueryTimestamp), 69);
EXPECT_EQ(static_cast<Uint16>(MGPWireOp::QueryCounter), 70);
EXPECT_EQ(static_cast<Uint16>(MGPWireOp::FenceWaitServer), 71);
// P5b (docs/archive/contracts/CONTRACT-P5B.md) appended five verbs AFTER P0's three late arrivals, by
// P5b appended five verbs AFTER P0's three late arrivals, by
// the same rule: opcodes 72..76, and nothing before them moved. The five are pinned by
// VALUE, because the pin is the protocol - a row inserted ahead of one would silently
// re-point every record a P5b package emits at the wrong arm.
@@ -597,7 +597,7 @@ TEST(PipeCatalogue, LateArrivalsAreAppendedWithoutRenumbering) {
EXPECT_EQ(static_cast<Uint16>(MGPWireOp::BindStreamOutput), 74);
EXPECT_EQ(static_cast<Uint16>(MGPWireOp::SetStorageBlockBinding), 75);
EXPECT_EQ(static_cast<Uint16>(MGPWireOp::CopyFramebufferToTexture), 76);
// P5c (docs/archive/contracts/CONTRACT-P5C.md §5) appended the two control records AFTER P5b's five, by
// P5c (§5) appended the two control records AFTER P5b's five, by
// the same rule: opcodes 77..78, and nothing before them moved. applier_reset is a kScreen
// row (a make-current is a whole-server edge, exactly as FenceWaitServer is a screen call)
// and object_death a kCtxObject one; both carry no blob, no reply and no tail.
@@ -608,13 +608,13 @@ TEST(PipeCatalogue, LateArrivalsAreAppendedWithoutRenumbering) {
// - fixed POD, no blob, no tail, no reply - with an MGPipeApply* entry point, which the two
// control records deliberately do not have.
EXPECT_EQ(static_cast<Uint16>(MGPWireOp::SetContextValues), 79);
// P5e (docs/archive/contracts/CONTRACT-P5E.md §1) appended ONE more, by the same rule: opcode 80, and
// P5e (§1) appended ONE more, by the same rule: opcode 80, and
// nothing before it moved. set_program_bindings is a kCtxState row with THREE tails and a
// host span in the third; it lands with a null route and a sink that refuses it by name,
// exactly as set_shader_buffers has sat catalogued-and-dead since P4a.
EXPECT_EQ(static_cast<Uint16>(MGPWireOp::SetProgramBindings), 80);
EXPECT_EQ(static_cast<Uint16>(MGPWireOp::DeleteStreamOutput), 81);
// P9 (docs/archive/contracts/CONTRACT-P9.md §1) appended the two pack-buffer readbacks, by the same rule:
// P9 (§1) appended the two pack-buffer readbacks, by the same rule:
// opcodes 82..83, one payload, no flag at all - no reply slot, no blob, no tail.
EXPECT_EQ(static_cast<Uint16>(MGPWireOp::ReadPixelsToBuffer), 82);
EXPECT_EQ(static_cast<Uint16>(MGPWireOp::GetTextureImageToBuffer), 83);
@@ -623,7 +623,7 @@ TEST(PipeCatalogue, LateArrivalsAreAppendedWithoutRenumbering) {
// kScreen control record with the applier_reset shape - one POD, no blob, no tail, no reply
// and no MGPipeApply* entry point - so the row beside it is pinned the same way.
EXPECT_EQ(static_cast<Uint16>(MGPWireOp::BindContext), 84);
// Shared images (docs/archive/notes/anland/plan-ahb-dmabuf.md) appended opcode 85 by the
// Shared images appended opcode 85 by the
// same rule: a kScreen row with a reply slot - every operation is answered.
EXPECT_EQ(static_cast<Uint16>(MGPWireOp::SharedImage), 85);
EXPECT_EQ(static_cast<Uint16>(MGPWireOp::kOpCount), 86);
@@ -729,7 +729,7 @@ TEST(PipeCatalogue, LateArrivalsAreAppendedWithoutRenumbering) {
EXPECT_EQ(kMGPipeClearValueClassUint + 1, kMGPipeClearValueClassCount);
}
// ---- P5e: the wait-class column (docs/archive/contracts/CONTRACT-P5E.md §2.2) --------------------------
// ---- P5e: the wait-class column (§2.2) --------------------------
//
// THE POINT OF THIS CASE IS THAT IT DOES NOT READ PipeCalls.def. Every other statement about
// the column - the generated table, the two gates in gen_pipe.py, the static_asserts in
@@ -1044,14 +1044,14 @@ TEST(PipeCatalogue, FloatVectorsCompareBitwise) {
// a cache that read the padding would mint a fresh CSO per call and the verify lane would
// abort at random.
TEST(PipeCatalogue, SixValueStructsHaveFieldLists) {
// 72 through P5; P5b appended five call payloads (docs/archive/contracts/CONTRACT-P5B.md: MGPImageBind,
// 72 through P5; P5b appended five call payloads (the contract: MGPImageBind,
// MGPPatchParameter, MGPStreamOutputBind, MGPStorageBlockBinding, MGPCopyFromFramebuffer),
// each with its own field list, so the comparator sees every one of them: 77. P5c appended
// applier_reset's MGPApplierReset (CONTRACT-P5C.md §5.1) - object_death reuses
// MGPHandleOnly, which has had a list since P0 - and rv added set_context_values'
// MGPContextValues (§5.3): 79. P5e appended set_program_bindings' MGPProgramBindings AND
// the two TAIL ELEMENT types beside it, MGPProgramSamplerUnit and MGPProgramStorageOverride
// (docs/archive/contracts/CONTRACT-P5E.md §1) - the tails are listed for the same reason MGPBufferRange
// (§1) - the tails are listed for the same reason MGPBufferRange
// and MGPVertexAttribWire are: the comparator has to see INTO an element whose members
// include an MGHostSpan and a pad word, or it would memcmp the padding: 82. P9 appended the
// pack-buffer readbacks' one payload, MGPReadbackToBuffer (CONTRACT-P9.md §1): 83. P14 S1
@@ -1138,7 +1138,7 @@ TEST(PipeCatalogue, PipelineSubsetMembersArePinned) {
// than a claim, since the static_assert beside kMGPipeCallbackCount only proves the two agree.
// P9 took two more, neither of which ever had a producer: W2 deleted OnTexturePullRequest (a
// texture re-mint never needs the client's texels - the server reads the GPU level and its own
// staged store, docs/archive/notes/p9/W2-REMINT.md), and W3 deleted OnLog (the server's log lines are LogLine
// staged store), and W3 deleted OnLog (the server's log lines are LogLine
// frames on the control plane, MG_Remote/Transport/LogForward.h, not reverse records).
//
// THE CASE NAME STAYS "…HasTenCallbacks" DELIBERATELY. G2/G14 say the ctest name set only ever
@@ -1457,18 +1457,18 @@ TEST(PipeCatalogue, EveryUnmigratedEmulationIsNamedOnce) {
// new stall class the design admitted. It went because the stall class did: under a transport
// the re-mint is the server's own (RequireImageBindableStorageByHandle reads the GPU level and
// replays the staged store), the frontend arm that carried the marker is monolith-only, and no
// pull protocol or ResourceSubDataComplete terminator exists (docs/archive/notes/p9/W2-REMINT.md).
// pull protocol or ResourceSubDataComplete terminator exists.
//
// AND THE LIST HAD DRIFTED BY ONE UNTIL P8-B. The tree carried a sixth name this list never
// had: "generate-mipmap-cpu-filter", the split arm's RGB16F/RGB32F refusal in
// GenerateMipmapByRecord. P8-B2 retired it (the server filters its own level,
// GenerateThreeChannelFloatMipmapOnServer), and P8-B1 retired the split arm's two
// "generate-mipmap-storage" sites (the record's plan is the window). Every name left is on a
// MONOLITH arm - the split arms no longer reach an unmigrated emulation (docs/archive/notes/p8/B.md).
// MONOLITH arm - the split arms no longer reach an unmigrated emulation.
//
// THREE, NOT FOUR (P8-SE). "copy-image-shadow-mirror" sat after the mirror's own
// `Transport != Monolith` return, so no transport ever reached it and on monolith it was a
// no-op; the call and the name went together (docs/archive/notes/p8/SE.md).
// no-op; the call and the name went together.
//
// NONE (P13 W6). "get-tex-image-shadow" sat in GetTexImageViaShadowConversion, the monolith
// frontend arm's shadow readback, and the two mipmap names in that arm's storage grow and CPU
@@ -7,7 +7,7 @@
// End of Source File Header
// P5e's set_shader_buffers - the INDEXED BUFFER BINDING POINTS - on both sides of the call
// (docs/archive/contracts/CONTRACT-P5E.md §5.6, rulings 10 and 11; package sb).
// (§5.6, rulings 10 and 11; package sb).
//
// WHAT THIS SUITE IS FOR. Three properties of this family are invisible in a picture and are
// exactly what an optimisation or a merge deletes:
+1 -1
View File
@@ -352,7 +352,7 @@ namespace {
// the loop above, because "these three, together" is the phase's own scope statement.
//
// set_stream_output_targets stays UNEMITTED for the whole of P5e (XFB is lockstep by
// escalation, docs/archive/contracts/CONTRACT-P5E.md §5.7) and still names the subsystem, for the
// escalation, the contract §5.7) and still names the subsystem, for the
// same reason: the bit answers "which A/B switch owns this family's legacy arm", not
// "is there a record on the wire for me today".
EXPECT_EQ(MGPipeSubsystemForDirty(MGPipeDirty::NewConstBuffers), kMGPipeSubsystemBufferBindings);
+1 -1
View File
@@ -568,7 +568,7 @@ namespace {
}
// P8-D: the Magma wire arm's indirect-draw bracket. Its short names are what the create
// fixtures' measurement (docs/archive/notes/p8/D.md) reads off the server's line, and its long names are
// fixtures' measurement reads off the server's line, and its long names are
// what Harness/WireIndirectPeek.cpp's readers expect in the JSON dump.
TEST_F(PipeStatsTest, WireIndirectCountersPrintInTheirOwnBracket) {
PS::AddCalls(PS::CallClass::WireIndirectNativeDraws, 3);
+1 -1
View File
@@ -6,7 +6,7 @@
// SPDX-License-Identifier: LGPL-3.0-only
// End of Source File Header
// P11 B2 (docs/archive/contracts/CONTRACT-P11.md B2). Server::AdoptInbox - T0's Offers matched to their
// P11 B2 (B2). Server::AdoptInbox - T0's Offers matched to their
// map_persistent records BY SEQ, never by arrival order - over both aux channels the product has:
// the in-process queue (inproc) and a real socket pair with SCM_RIGHTS (fork spawn / unix / fd:).
//
@@ -6,7 +6,7 @@
// SPDX-License-Identifier: LGPL-3.0-only
// End of Source File Header
// P11 A1 (docs/archive/contracts/CONTRACT-P11.md §1): MOBILEGL_IPC_ADOPT_TIER=0/1 ON A STREAM DATA PLANE.
// P11 A1 (§1): MOBILEGL_IPC_ADOPT_TIER=0/1 ON A STREAM DATA PLANE.
//
// Real servers on loopback TCP and forked peers (P12ServerRig.h), so the session is the product's
// two-process tcp session and each side reads its OWN knob, as on the tcp lane:
@@ -17,7 +17,7 @@
// EGL_EXT_image_dma_buf_import + _modifiers (dmabuf_capable), XRGB8888/ARGB8888 importable,
// eglCreateImageKHR(EGL_LINUX_DMA_BUF_EXT) of a shared image's descriptor.
//
// And the implicit-sync flush (docs/archive/notes/anland/plan-x11-gpu.md): the shared_image
// And the implicit-sync flush: the shared_image
// Flush verb the client sends from glFlush is answered by the server.
//
// Chrome's GPU process on the same kind of display (a GBM one) is the other dma-buf producer, and it
+5 -5
View File
@@ -1128,7 +1128,7 @@ TEST_F(PipeWireCodecTest, UserIndexSpanExactlyAtSegmentEndReachesTheSink) {
}
// =====================================================================================
// P5b (docs/archive/contracts/CONTRACT-P5B.md): one round trip per row the four migration packages consume
// P5b: one round trip per row the four migration packages consume
// =====================================================================================
//
// The shape is the one above: encode, pump one record through the ring and the decoder, and
@@ -1335,7 +1335,7 @@ TEST_F(PipeWireCodecTest, BindStreamOutputReachesTheSink) {
}
// =====================================================================================
// P5c ct (docs/archive/contracts/CONTRACT-P5C.md §5): the two control records round-trip
// P5c ct (§5): the two control records round-trip
// =====================================================================================
//
// Same shape as the P5b rows above: encode, pump, and assert the record reached the RIGHT
@@ -1398,7 +1398,7 @@ TEST_F(PipeWireCodecTest, ObjectDeathReachesTheSinkWithItsHandleAndKind) {
}
// =====================================================================================
// P5c rv (docs/archive/contracts/CONTRACT-P5C.md §5.3): the residual-value record round-trips
// P5c rv (§5.3): the residual-value record round-trips
// =====================================================================================
//
// Not a sink row: the decoder's arm runs the REAL applier (MGPipeApplySetContextValues), so
@@ -1443,7 +1443,7 @@ TEST_F(PipeWireCodecTest, SetContextValuesRoundTripsIntoPipeInputs) {
}
// =====================================================================================
// P5b t2 (docs/archive/contracts/CONTRACT-P5B.md §2 t2). c0b's cases above round-trip each row once; these
// P5b t2 (§2 t2). c0b's cases above round-trip each row once; these
// pin the fields t2's EMITTERS actually fill and the one ordering property the span family has.
// =====================================================================================
@@ -3271,7 +3271,7 @@ TEST(FenceWireRoundTrip, MissingConsumerDeclinesWithoutInventingASignaledAnswer)
}
// =====================================================================================
// P5c ct (docs/archive/contracts/CONTRACT-P5C.md §5): the two control records, through the REAL sink
// P5c ct (§5): the two control records, through the REAL sink
// =====================================================================================
//
// The codec cases above pin the bytes and the dispatch with a recording sink; these pin what
@@ -6,7 +6,7 @@
// SPDX-License-Identifier: LGPL-3.0-only
// End of Source File Header
// P11 B2 (docs/archive/contracts/CONTRACT-P11.md B2): T0'S PROTOCOL ON THE HOST, over a live inproc session.
// P11 B2 (B2): T0'S PROTOCOL ON THE HOST, over a live inproc session.
//
// A host has no AHardwareBuffer, so what these prove is the protocol, the negotiation and the
// fallback - never GPU correctness, which is the device's (B2's device gates). Two halves:
@@ -1559,7 +1559,7 @@ TEST(RemoteClientControls, ARefusedCreateUnlatchesItsObjectAndItsNextCreateBlock
//
// THE ASSERTIONS BELOW ARE THEREFORE A DEBT, NOT A SPEC, and they are written to be LOUD about it:
// they pin today's numbers so that whoever lands the signal sees THIS case go red and knows the
// repair started working. docs/archive/notes/p12/UNPUBLISH-GUARD-SIGNALS.md §4-§6 has the rest.
// repair started working. The phase notes §4-§6 have the rest.
TEST(RemoteClientControls, DroppedApplierRecordsAreNotRepairedTodayAndThisCaseIsTheDebt) {
const auto child = RunInChild([] {
::setenv("MOBILEGL_PIPE_STATS", "1", 1);
+3 -3
View File
@@ -387,7 +387,7 @@ TEST(RemoteEmitTable, SetSwapIntervalIsTheServerForwarderAndNotAFatal) {
#endif // MGTEST_HAVE_FORK
// ---- P5b package i1 (docs/archive/contracts/CONTRACT-P5B.md §2 i1) -------------------------------------
// ---- P5b package i1 (§2 i1) -------------------------------------
TEST(RemoteEmitTable, TheSevenI1SlotsAreClassBAndAreNotTheFatalThunk) {
// The census's five measured slots plus the two companions that share their rows. Named
@@ -899,7 +899,7 @@ TEST(CapsMirrorTest, TheConsumerBlockDoesNotCollideWithTheFeatureBits) {
}
// =====================================================================================
// P5b d1: the draw family's record plan (docs/archive/contracts/CONTRACT-P5B.md §2 d1). These drive the
// P5b d1: the draw family's record plan (§2 d1). These drive the
// PRODUCTION derivation the nineteen emitters call - PlanDrawInfo / PlanDrawRange /
// PlanDrawIndirect over a RemoteDrawBindings snapshot - so the fields on the wire are pinned
// here without a GL context (R-16: the production predicate, not a copy). The bindings' READ
@@ -2660,7 +2660,7 @@ TEST(RemoteGuards, ClientPipeInputsFillWithTheApplierIdleIsAllowed) {
// ===========================================================================================
// P5e (ra) - the wait rule, the present credit and gPipeInputs' ownership
// (docs/archive/contracts/CONTRACT-P5E.md §1, §2.3, §2.4, §3.1, §3.3, §3.5)
// (§1, §2.3, §2.4, §3.1, §3.3, §3.5)
// ===========================================================================================
//
// EVERY CASE BELOW ARMS RUN-AHEAD BY PUBLISHING THE CAP BIT, because that is the only thing
+1 -1
View File
@@ -2537,7 +2537,7 @@ TEST(StagedShadowProductionTest, TheStreamingIdiomThroughAPoolReuseIsUploadedNot
// =====================================================================================
// P5b d1: a draw_vbo record of every d1 shape crosses to the REAL ServerVerbSink with its
// fields intact (docs/archive/contracts/CONTRACT-P5B.md §2 d1). No backend object lives in this process,
// fields intact (§2 d1). No backend object lives in this process,
// so each record is DECLINED after the sink has witnessed it - which is exactly the point:
// the witness is taken before the backend is consulted, so these cases pin the wire's fields
// and not a backend call. The emitter half (GL args -> these fields) is RemoteClientTest's
+1 -1
View File
@@ -564,7 +564,7 @@ TEST(SessionTest, PresentAckSerialIsWaitedOnWithGreaterOrEqualAndWakesThroughThe
}
// ---------------------------------------------------------------------------
// P5e (ra) - SEG_EVENT flow control (docs/archive/contracts/CONTRACT-P5E.md §2.6)
// P5e (ra) - SEG_EVENT flow control (§2.6)
// ---------------------------------------------------------------------------
//
// THE DEADLOCK THE CONTRACT ARGUES AWAY HAS TWO HALVES AND THIS IS THE FIRST. A run-ahead
+1 -1
View File
@@ -6,7 +6,7 @@
// SPDX-License-Identifier: LGPL-3.0-only
// End of Source File Header
// Shared images (docs/archive/notes/anland/plan-ahb-dmabuf.md): the server's registry, a
// Shared images: the server's registry, a
// session's references, and the aux-socket inbox that carries an import's descriptor beside T0's
// Offers. On a host the image memory is a memfd, which is enough for everything here: what is
// under test is that a descriptor which travelled through SCM_RIGHTS still names its image.
@@ -397,7 +397,7 @@ TEST(StagedTextureStoreTest, TheGpuDirtyMarkIsTheServersOwnDirtyAnswer) {
EXPECT_EQ(monolithStore.TrackedResources(), 0u);
}
// ---- P8-E (docs/archive/notes/p8/E.md): the store follows glCopyImageSubData -----------
// ---- P8-E: the store follows glCopyImageSubData -----------
//
// Two 4x4 RGBA8 levels (four bytes a texel), each adopted whole with a distinct byte pattern so a
// mis-addressed row or a swapped endpoint shows as a wrong byte, not a coincidentally right one.