[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
@@ -8,7 +8,7 @@
#pragma once
// WHEN glFlush IS A SHARED-IMAGE BOUNDARY (docs/Disaggregated/notes/anland/plan-x11-gpu.md).
// WHEN glFlush IS A SHARED-IMAGE BOUNDARY (docs/archive/notes/anland/plan-x11-gpu.md).
//
// A dma-buf producer that renders into its buffers and hands them on after a glFlush (an X
// server's glamor committing a window pixmap) relies on implicit sync: whoever samples the buffer
@@ -44,7 +44,7 @@
// call sites below are declarations only, exactly as the frontend's mutators are.
#include <MG_Pipe/PipeMutation.h>
// P9 (W1, MG_Remote/CONTRACT-P9.md §1): AN UNPACK SOURCE IS READ FROM THE BUFFER'S CLIENT SHADOW,
// P9 (W1, docs/archive/contracts/CONTRACT-P9.md §1): AN UNPACK SOURCE IS READ FROM THE BUFFER'S CLIENT SHADOW,
// and under a transport a GPU write into that buffer - a read_pixels_to_buffer, which is how a
// glReadPixels into a pack buffer now crosses, or a shader store - reaches the shadow only through
// SyncGpuWrites, exactly as glMapBufferRange and glGetBufferSubData already do. Monolith keeps its
+1 -1
View File
@@ -8,7 +8,7 @@
#pragma once
// GLX WINDOWS PRESENTED THROUGH DRI3 + PRESENT (docs/Disaggregated/notes/anland/plan-x11-gpu.md).
// GLX WINDOWS PRESENTED THROUGH DRI3 + PRESENT (docs/archive/notes/anland/plan-x11-gpu.md).
//
// A GLX window's frames are drawn by the server into a pbuffer. Instead of reading each frame back
// and putting it on the window, the frame is copied GPU-side into one of a few server-allocated
+2 -2
View File
@@ -2407,7 +2407,7 @@ namespace MobileGL::MG_Pipe {
// emission gate is the subsystem bit plus the whole-record hash and nothing else.
case MGPipeFieldEmitter::SetContextValues:
return kMGPipeSubsystemResidualValues;
// P5e's one emitted row (MG_Remote/CONTRACT-P5E.md §5.6): the indexed buffer
// P5e's one emitted row (docs/archive/contracts/CONTRACT-P5E.md §5.6): the indexed buffer
// binding points. Written HERE at the contract commit, with the Coverage.def row
// and EmittedCallSuppliesTheWholeField's arm beside it, for the reason
// kMGPipeWiredSubsystems' block states one paragraph down - this file belongs to
@@ -2484,7 +2484,7 @@ namespace MobileGL::MG_Pipe {
MG_State::GLState::VertexArrayObject::MAX_VERTEX_ATTRIBS,
"the MGPipe vertex-attribute capacity and the frontend's have drifted");
// P5e (MG_Remote/CONTRACT-P5E.md §1, ruling 10), pinned here for the same reason and in
// P5e (docs/archive/contracts/CONTRACT-P5E.md §1, ruling 10), pinned here for the same reason and in
// the same place: this translation unit sees the frontend constant and the MG_Pipe one,
// and nothing else does. 84 is what the emitter may describe and what the wire carries;
// the BACKEND clamps to the device's real GL_MAX_UNIFORM_BUFFER_BINDINGS, as it does
+1 -1
View File
@@ -135,7 +135,7 @@ namespace MobileGL::MG_Pipe {
// published ahead of it are wiped by the create that follows. What the draft was
// protecting - "a rebuild inside the verb must already see the bindings" - is
// satisfied by both records going out at the SAME validate point, ahead of the verb,
// which is what this ordering does. See MG_Remote/CONTRACT-P5E.md §5.5 and the
// which is what this ordering does. See docs/archive/contracts/CONTRACT-P5E.md §5.5 and the
// record's own comment in PipeApply.h.
if (drawProgram) bytes += EmitProgramBindings(*drawProgram, drawCso);
// THE COMPOSITE'S SECOND RELEASE PATH is spoken here, not in a destructor: when the
+1 -1
View File
@@ -61,7 +61,7 @@ namespace MobileGL::MG_Pipe {
SetSamplerViews, // P4a - wired (backend debounce deletion: P3b/P4b)
BindSamplerStates, // P4a - wired (backend debounce deletion: P3b/P4b)
SetShaderImages, // P4a - wired (backend debounce deletion: P3b/P4b)
// P5e (MG_Remote/CONTRACT-P5E.md §1, ruling 11): THREE SLOTS, ONE PER CLASS, not one
// P5e (docs/archive/contracts/CONTRACT-P5E.md §1, ruling 11): THREE SLOTS, ONE PER CLASS, not one
// for the call. set_shader_buffers is emitted per Class (Uniform / ShaderStorage /
// AtomicCounter) because the record's own Class field says which binding-point array
// it describes - so a single slot would make every emission of one class cancel the
+1 -1
View File
@@ -10,7 +10,7 @@
#include <Includes.h>
// The CLIENT side of set_shader_buffers - the INDEXED BUFFER BINDING POINTS (P5e package sb,
// MG_Remote/CONTRACT-P5E.md §5.6, rulings 10 and 11). The call has been in the catalogue since
// docs/archive/contracts/CONTRACT-P5E.md §5.6, rulings 10 and 11). The call has been in the catalogue since
// P4a with no emitter, no route and no applier; this file is the emitter half.
//
// ONE RECORD PER CLASS, THREE CLASSES. MGPShaderBuffers::Class names which binding-point array
+2 -2
View File
@@ -210,7 +210,7 @@ namespace MobileGL::MG_Pipe {
case MGPipeDirty::NewSamplers:
case MGPipeDirty::NewShaderImages:
return kMGPipeSubsystemSamplers;
// P5e's three, one subsystem (MG_Remote/CONTRACT-P5E.md §1): the indexed buffer
// P5e's three, one subsystem (docs/archive/contracts/CONTRACT-P5E.md §1): the indexed buffer
// binding points. Bits 15/16/17 have been computed and counted since P2 and have named
// no subsystem since - "the remaining bits have no call of their own until P4b", which
// the default arm below used to say for them. set_shader_buffers is the call, and
@@ -690,7 +690,7 @@ namespace MobileGL::MG_Pipe {
now[Index(MGPipeDirty::NewShaderImages)] = MGPipeMixShutter(
MGPipeMixShutter(MGPipeMixShutter(textureContent, textureParams), programImages),
ctx.GetTextureBindGeneration());
// ---- bits 15/16/17, REWRITTEN AT P5e (sb, MG_Remote/CONTRACT-P5E.md §5.6) ----
// ---- bits 15/16/17, REWRITTEN AT P5e (sb, docs/archive/contracts/CONTRACT-P5E.md §5.6) ----
//
// ALL THREE USED TO READ `buffers` - the buffer CONTENT aggregate - AND THAT WAS
// WRONG IN BOTH DIRECTIONS AT ONCE. Over: any glBufferSubData anywhere fired all
@@ -52,7 +52,7 @@
"Pixel packing exceeds the destination or its addressable range."));
}
// P9 (W1, MG_Remote/CONTRACT-P9.md §1): MAY A READ INTO THIS PACK BUFFER GO WITHOUT A
// P9 (W1, docs/archive/contracts/CONTRACT-P9.md §1): MAY A READ INTO THIS PACK BUFFER GO WITHOUT A
// REPLY? The answer is the buffer's handle when it may - the read then crosses as
// read_pixels_to_buffer / get_texture_image_to_buffer, lands server-side, and the buffer
// is marked GPU-written - and the null handle when the reply-slot form has to carry it.
+3 -3
View File
@@ -593,7 +593,7 @@ namespace MobileGL::MG_Record {
// =============================================================================
// P5b d1 - the nineteen indexed / instanced / multi-draw / indirect draw slots
// (MG_Remote/CONTRACT-P5B.md §2 d1). ONE ROW, draw_vbo (59): the record carries the GL
// (docs/archive/contracts/CONTRACT-P5B.md §2 d1). ONE ROW, draw_vbo (59): the record carries the GL
// call verbatim (rule D) beside the handle the P8 form will dispatch on, and the sink
// reproduces the backend call the monolith makes.
// =============================================================================
@@ -1286,7 +1286,7 @@ namespace MobileGL::MG_Record {
// =============================================================================
// CLASS B - P5b package i1: image bind, compute, barriers, copy-image, SSBO block
// (MG_Remote/CONTRACT-P5B.md §2 i1). Seven slots, five wire rows.
// (docs/archive/contracts/CONTRACT-P5B.md §2 i1). Seven slots, five wire rows.
// =============================================================================
//
// RULE D, WHICH IS WHY THESE ARE SHORT. A P5b verb crosses AS THE CALL: the record
@@ -1513,7 +1513,7 @@ namespace MobileGL::MG_Record {
}
// CLASS B - P5b package t2: the transform-feedback spans, the XFB object bind and the
// tessellation patch parameter (MG_Remote/CONTRACT-P5B.md §2 t2).
// tessellation patch parameter (docs/archive/contracts/CONTRACT-P5B.md §2 t2).
// =============================================================================
//
// SIX SLOTS, SIX ROWS, AND NOT ONE OF THEM STARTS A SHADER. Every one of the six is a
+1 -1
View File
@@ -200,7 +200,7 @@ namespace MobileGL::MG_Record {
Bool ReadbackReplyIsComplete(Int32 status, Uint64 replySize, Uint64 expected);
// =============================================================================
// P5b d1 - the draw family's record plan (MG_Remote/CONTRACT-P5B.md §2 d1)
// P5b d1 - the draw family's record plan (docs/archive/contracts/CONTRACT-P5B.md §2 d1)
// =============================================================================
//
// The nineteen indexed / instanced / multi-draw / indirect entry points all ride draw_vbo
+1 -1
View File
@@ -6,7 +6,7 @@
* SPDX-License-Identifier: LGPL-3.0-only
* End of Source File Header */
/* SHARED IMAGES, AS A C ABI (docs/Disaggregated/notes/anland/plan-ahb-dmabuf.md).
/* SHARED IMAGES, AS A C ABI (docs/archive/notes/anland/plan-ahb-dmabuf.md).
*
* libMobileGL.so exports these on Linux (not Android) in split builds, so a component that is not
* a GL entry point - the GBM backend (MG_Gbm), above all - can ask the server for an image and