Merge branch 'p5e/pg' into feat/disaggregated (P5e pg)

# Conflicts:
#	MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp
#	MobileGL/MG_Test/Pipe/PipeCatalogueTest.cpp
This commit is contained in:
2026-09-18 08:40:39 -04:00
18 changed files with 2072 additions and 317 deletions
@@ -242,6 +242,14 @@ namespace MobileGL::MG_State::GLState {
// (ProgramArtifacts.h's libc++ branch until the integrator fills it in) this is 0,
// which still round-trips within one build - the echo compares what THIS build wrote
// against what THIS build expects - and stops mattering the moment the pin lands.
//
// P5e (pg) READ THIS LINE AS THE CONTRACT ASKED (CONTRACT-P5E §5.5) and its verdict is
// in ProgramArtifactsCodec.h's header comment: the caveat is about the ECHO WORD, not
// about a member the codec skips - the one member VisitFields omits is
// `LinkArtifacts::program`, and no backend twin reads it. A 0 echo is exact for an
// in-process split, where the writer and the reader are one build, and becomes a real
// cross-toolchain check when P6 puts a client and a server in different processes
// built by different compilers.
#ifdef MGL_LINKARTIFACTS_SIZE
inline constexpr Uint64 kLinkArtifactsSizeEcho = MGL_LINKARTIFACTS_SIZE;
#else
@@ -300,4 +308,55 @@ namespace MobileGL::MG_State::GLState {
link.program = nullptr;
return true;
}
// ---- P5e (pg): the frame -------------------------------------------------------------
//
// ONE MORE LENGTH-PREFIXED RUN IN FRONT, and deliberately in front rather than behind:
// DecodeProgramArtifacts refuses trailing bytes ("the format accounts for every byte it
// writes"), which is a rule worth keeping, so the stage list is consumed BEFORE the
// codec's own stream is handed the exact remainder. The version word inside that stream
// still governs the archive proper; the frame has no version of its own because it is one
// count and one run of Uint32 and there is nothing about it a future reader could
// misinterpret without the count already disagreeing.
void EncodeProgramArchive(const LinkArtifacts& link, const SpirvArtifacts& spirv,
const Vector<Uint32>& linkedStages, Vector<Uint8>& out) {
PutRaw(out, static_cast<Uint32>(linkedStages.size()));
for (const Uint32 stage : linkedStages) PutRaw(out, stage);
EncodeProgramArtifacts(link, spirv, out);
}
Bool DecodeProgramArchive(const Uint8* bytes, SizeT size, ProgramArchive& out) {
out = ProgramArchive{};
if (bytes == nullptr) return false;
if (size < sizeof(Uint32)) return false;
Uint32 stageCount = 0;
std::memcpy(&stageCount, bytes, sizeof(stageCount));
// BOUNDED BEFORE IT IS MULTIPLIED, the same rule the codec's own TakeCount keeps: a
// corrupt count must not become a four-billion-element resize, and a count past the
// declared maximum is a program this frame cannot describe rather than one to truncate.
if (static_cast<SizeT>(stageCount) > kProgramArchiveMaxStages) return false;
const SizeT framed = sizeof(Uint32) + static_cast<SizeT>(stageCount) * sizeof(Uint32);
if (size < framed) return false;
out.LinkedStages.resize(stageCount);
for (Uint32 i = 0; i < stageCount; ++i) {
std::memcpy(&out.LinkedStages[i], bytes + sizeof(Uint32) + i * sizeof(Uint32),
sizeof(Uint32));
}
if (!DecodeProgramArtifacts(bytes + framed, size - framed, out.Link, out.Spirv)) {
out = ProgramArchive{};
return false;
}
// THE TWO HALVES MUST AGREE, and this is the only place that can say so: the backend
// pairs linkedStages[i] with generatedSpirv[i] and indexes both by one running index,
// so a frame whose count disagrees with the decoded module count would read off the
// end of one of them. The frontend builds both from one snapshot loop, so a mismatch
// here is a wire fault and not a program shape.
if (out.LinkedStages.size() != out.Spirv.generatedSpirv.size()) {
out = ProgramArchive{};
return false;
}
return true;
}
} // namespace MobileGL::MG_State::GLState
@@ -42,6 +42,26 @@
// * and `LinkArtifacts::program` is NEVER visited. It is the live glslang TProgram, it is
// null for every archived instance by construction, and VisitFields deliberately omits it
// (57 of the 58 members). Decode leaves it null.
//
// P5e (pg), CONTRACT-P5E §5.5 "codec completeness": THE SKIPPED MEMBER IS NAMED, AND IT IS
// `LinkArtifacts::program`. The contract asks this package either to carry it or to prove the
// twin never reads it, and the proof is a closed grep rather than an argument: every read of
// that member in the tree is inside `ProgramLinkTask.cpp` (`DoReflection`, which is the only
// code that may dereference it at all) and the three sites that `reset()` it -
// `ProgramLinkTask.cpp:678,764,877` and `ProgramObject::ResetLinkArtifacts`. `MG_Backend/`
// contains NO read of it, in either backend; `ProgramTranslationCache` asserts it is null at
// insert. So the archive answers every reflection question the program twin asks, and the one
// member it does not carry is one no twin has ever asked for. It could not be carried in any
// case: it points into a glslang arena that no archived instance owns.
//
// AND THE OTHER HALF OF THAT CONTRACT LINE - `ProgramArtifactsCodec.cpp`'s libc++ caveat - is
// about the STRUCT-SIZE ECHO, not about a member: under a toolchain whose `MGL_LINKARTIFACTS_SIZE`
// is not pinned yet (the NDK's libc++ branch of `ProgramArtifacts.h`, inert until the integrator
// fills it in) the echo word is 0. That is SAFE FOR P5e AND NOT A GAP: the echo compares what
// this build wrote against what this build expects, so a round trip within one build is exact,
// and P5e is an in-process split where the writer and the reader ARE one build. It becomes a
// real check the day a client and a server built by different toolchains share a wire, which is
// P6's boundary and P6's problem - stated here so it cannot be discovered instead.
namespace MobileGL::MG_State::GLState {
// Bumped whenever the byte format changes in a way a previous reader would misread. A
@@ -60,6 +80,45 @@ namespace MobileGL::MG_State::GLState {
Bool DecodeProgramArtifacts(const Uint8* bytes, SizeT size, LinkArtifacts& link,
SpirvArtifacts& spirv);
// ---- P5e (pg): the archive as the SERVER OWNS it -------------------------------------
//
// WHAT THE TWO STRUCTS ABOVE DO NOT CARRY, and why a package that makes the server answer
// every reflection question out of them had to notice: THE STAGE OF EACH MODULE.
// `SpirvArtifacts::generatedSpirv` is one module per SHADER OBJECT the link consumed, in
// snapshot order, and the stage of each lives in `ProgramObject::m_linkedShaderSnapshot` -
// GL-thread state, not an artifact. `MGPProgramDesc::StageMask` cannot stand in for it: it
// is a bit SET, and GL lets two shader objects of the same stage be attached to one
// program, so a list rebuilt from the mask would be shorter than `generatedSpirv` and the
// backend's "linked stages and modules must agree" refusal would fire on a perfectly good
// program.
//
// So the frame is [stage count][stage words][the codec's own bytes], written and read by
// this package on both sides, and `ProgramArchive` is what a decode produces: the record's
// OWN copy, with the lifetime of the record rather than of the staged run that carried it
// (rule C). Stages travel as Uint32 rather than as `ShaderStage` so this header keeps its
// include closure - `ProgramArtifacts.h` beside it may not reach `ShaderStage.h`.
struct ProgramArchive {
LinkArtifacts Link;
SpirvArtifacts Spirv;
// ShaderStage, one per Spirv.generatedSpirv entry, at the same index.
Vector<Uint32> LinkedStages;
};
// The bound a decode refuses past: six is what MGPProgramDesc::Spirv[] can name and what
// ProgramEmit.h's own truncation counter already watches, doubled so that a program this
// stack can build is never refused here for a reason the emitter did not already count.
inline constexpr SizeT kProgramArchiveMaxStages = 12;
// Appends the framed archive to `out` (not cleared, so a caller may frame it further).
// `linkedStages` must be index-aligned with `spirv.generatedSpirv`.
void EncodeProgramArchive(const LinkArtifacts& link, const SpirvArtifacts& spirv,
const Vector<Uint32>& linkedStages, Vector<Uint8>& out);
// Replaces `out` with what `bytes` describes. Same refusal terms as
// DecodeProgramArtifacts, plus: a stage count past kProgramArchiveMaxStages, and a stage
// count that does not match the decoded module count.
Bool DecodeProgramArchive(const Uint8* bytes, SizeT size, ProgramArchive& out);
// How many fields a type's VisitFields table actually visits. The codec walks exactly that
// table, so this is what pins "the codec did not quietly grow an arm of its own" - most of
// all for LinkArtifacts, whose 58th member is the live TProgram the table omits. It is a