[MG_Remote, MG_Pipe, MG_Test, CI, tools, docs] (P6.5): the first wave completed and reviewed - archive v2, publication boundary, half-close, AcceptPair/role fixes, device re-validation

This commit is contained in:
2026-09-22 10:56:19 -04:00
parent 018fab0f5b
commit fe28bdb5f3
75 changed files with 4887 additions and 254 deletions
@@ -413,9 +413,9 @@ namespace MobileGL::MG_State::GLState {
// {h,cpp}, beside this header rather than inside it so the check_include_closure.py
// "artifacts-header" probe stays untouched. It is two visitors over the tables below - a
// writer that appends to a Vector<Uint8> and a reader that consumes one - length-prefixed,
// little-endian, with a format-version word first and a MGL_LINKARTIFACTS_SIZE echo
// second, so a struct that gained a field and a codec that did not is a mismatch at READ
// time rather than a silent truncation. Adding a member to any struct above therefore
// little-endian, with a format-version word and (for disaggregated v2) a recursive
// wire-schema digest of these tables. Native container sizes are local maintenance
// assertions below, never cross-standard-library wire facts. Adding a member to any struct above therefore
// means: add its VisitFields row here, update the sizeof number below, and bump
// kProgramArtifactsCodecVersion. `LinkArtifacts::program` stays the one deliberate
// omission, and the codec has no arm for it.
@@ -13,6 +13,7 @@
#include <bit>
#include <cstring>
#include <set>
#include <limits>
#include <string>
#include <type_traits>
#include <vector>
@@ -70,6 +71,88 @@ namespace MobileGL::MG_State::GLState {
template <class T>
concept ArchiveUniformInitializer = std::same_as<T, UniformInitializer>;
// glslang supplies no VisitFields table for this aggregate. Keep its one explicit
// table shared by the payload writer, reader and wire-schema walk.
template <class Self, class Visitor>
void VisitUniformInitializer(Self& value, Visitor&& visit) {
visit("name", value.name);
visit("basicType", value.basicType);
visit("vectorSize", value.vectorSize);
visit("matrixCols", value.matrixCols);
visit("matrixRows", value.matrixRows);
visit("arraySize", value.arraySize);
visit("intValues", value.intValues);
visit("floatValues", value.floatValues);
}
#if MOBILEGL_BUILD_DISAGGREGATED
void SchemaWord(Uint64& hash, Uint64 word) {
for (unsigned i = 0; i < 8; ++i) {
hash ^= (word >> (i * 8)) & 255u;
hash *= 1099511628211ull;
}
}
void SchemaName(Uint64& hash, const char* text) {
do {
hash ^= static_cast<unsigned char>(*text);
hash *= 1099511628211ull;
} while (*text++ != '\0');
}
template <class Value>
void DescribeWireType(Uint64& hash) {
using T = std::remove_cv_t<Value>;
if constexpr (ArchiveScalar<T>) {
// These are the bytes PutRaw/TakeRaw actually carry, not the surrounding
// C++ object's layout. Equal-width signed/unsigned or float/int differ.
if constexpr (std::is_enum_v<T>) {
SchemaName(hash, "enum");
DescribeWireType<std::underlying_type_t<T>>(hash);
} else {
SchemaName(hash, std::is_same_v<T, bool> ? "bool" :
std::is_floating_point_v<T> ? "ieee-float" :
std::is_signed_v<T> ? "signed" : "unsigned");
SchemaWord(hash, sizeof(T));
if constexpr (std::is_floating_point_v<T>) {
static_assert(std::numeric_limits<T>::is_iec559);
SchemaWord(hash, std::numeric_limits<T>::digits);
SchemaWord(hash, std::numeric_limits<T>::max_exponent);
}
}
} else if constexpr (ArchiveString<T>) {
SchemaName(hash, "string-u64-count-byte-content");
} else if constexpr (ArchiveMap<T>) {
SchemaName(hash, "map-u64-count");
DescribeWireType<typename T::key_type>(hash);
DescribeWireType<typename T::mapped_type>(hash);
} else if constexpr (ArchiveSet<T>) {
SchemaName(hash, "set-u64-count");
DescribeWireType<typename T::value_type>(hash);
} else if constexpr (ArchiveFixedArray<T>) {
SchemaName(hash, "fixed-array");
SchemaWord(hash, std::tuple_size<T>::value);
DescribeWireType<typename T::value_type>(hash);
} else if constexpr (ArchiveVector<T>) {
SchemaName(hash, "vector-u64-count");
DescribeWireType<typename T::value_type>(hash);
} else {
SchemaName(hash, ArchiveUniformInitializer<T> ? "uniform-initializer" : "record");
// Visit only types/names from default records. Container contents are never
// traversed, and no sizeof(string/vector/map), offset or allocator enters it.
T value{};
Uint64 fields = 0;
const auto field = [&](const char* name, const auto& member) {
++fields;
SchemaName(hash, name);
DescribeWireType<std::remove_cvref_t<decltype(member)>>(hash);
};
if constexpr (ArchiveUniformInitializer<T>) VisitUniformInitializer(value, field);
else VisitFields(value, field);
SchemaWord(hash, fields);
SchemaName(hash, "end-record");
}
}
#endif
// ---- the writer ----
template <class T>
@@ -117,6 +200,11 @@ namespace MobileGL::MG_State::GLState {
} else if constexpr (ArchiveVector<T>) {
WriteSequence(out, value);
} else if constexpr (ArchiveUniformInitializer<T>) {
#if MOBILEGL_BUILD_DISAGGREGATED
VisitUniformInitializer(value, [&out](const char*, const auto& member) {
WriteValue(out, member);
});
#else
WriteValue(out, value.name);
WriteValue(out, value.basicType);
WriteValue(out, value.vectorSize);
@@ -125,6 +213,7 @@ namespace MobileGL::MG_State::GLState {
WriteValue(out, value.arraySize);
WriteValue(out, value.intValues);
WriteValue(out, value.floatValues);
#endif
} else {
// The archive's own structs: TypeFacts, ResourceReflection, XfbVarying. ONE
// table serves both directions, so a member added to any of them is carried by
@@ -223,6 +312,11 @@ namespace MobileGL::MG_State::GLState {
if (!in.Ok) return;
}
} else if constexpr (ArchiveUniformInitializer<T>) {
#if MOBILEGL_BUILD_DISAGGREGATED
VisitUniformInitializer(value, [&in](const char*, auto& member) {
if (in.Ok) ReadValue(in, member);
});
#else
ReadValue(in, value.name);
ReadValue(in, value.basicType);
ReadValue(in, value.vectorSize);
@@ -231,6 +325,7 @@ namespace MobileGL::MG_State::GLState {
ReadValue(in, value.arraySize);
ReadValue(in, value.intValues);
ReadValue(in, value.floatValues);
#endif
} else {
VisitFields(value, [&in](const char*, auto& field) {
if (in.Ok) ReadValue(in, field);
@@ -238,29 +333,41 @@ namespace MobileGL::MG_State::GLState {
}
}
// The struct-size echo. Under a toolchain whose sizes are not pinned yet
// (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.
// v1 is retained for local monolith verification. Its native size echo is not a
// wire compatibility fact: libstdc++ writes 1056 while unpinned libc++ writes zero.
#if !MOBILEGL_BUILD_DISAGGREGATED
#ifdef MGL_LINKARTIFACTS_SIZE
inline constexpr Uint64 kLinkArtifactsSizeEcho = MGL_LINKARTIFACTS_SIZE;
#else
inline constexpr Uint64 kLinkArtifactsSizeEcho = 0;
#endif
#endif
} // namespace
#if MOBILEGL_BUILD_DISAGGREGATED
Uint64 ProgramArtifactsSchemaFingerprint() {
static const Uint64 fingerprint = [] {
Uint64 hash = 1469598103934665603ull;
SchemaName(hash, "MobileGL.ProgramArchive.v2.little-endian");
// The outer stage framing is part of the same wire contract.
SchemaName(hash, "stage-list-u32-count-u32-elements");
SchemaWord(hash, kProgramArchiveMaxStages);
DescribeWireType<LinkArtifacts>(hash);
DescribeWireType<SpirvArtifacts>(hash);
return hash == 0 ? Uint64{1} : hash;
}();
return fingerprint;
}
#endif
void EncodeProgramArtifacts(const LinkArtifacts& link, const SpirvArtifacts& spirv,
Vector<Uint8>& out) {
PutRaw(out, kProgramArtifactsCodecVersion);
#if MOBILEGL_BUILD_DISAGGREGATED
PutRaw(out, ProgramArtifactsSchemaFingerprint());
#else
PutRaw(out, kLinkArtifactsSizeEcho);
#endif
// `link` is walked through its own VisitFields table, which omits the live
// SharedPtr<glslang::TProgram>: 57 of the 58 members. There is no arm here for it and
// there must not be one - it points into a glslang arena that no archived instance
@@ -280,14 +387,16 @@ namespace MobileGL::MG_State::GLState {
ReadCursor in{bytes, size, 0, true};
Uint32 version = 0;
Uint64 sizeEcho = 0;
if (!TakeRaw(in, version) || !TakeRaw(in, sizeEcho)) return false;
// REFUSED, NOT GUESSED. A different version word or a struct that changed width means
// the bytes describe a layout this build does not have; deserialising them anyway
// writes garbage into the tail of a reflection table, which is exactly the failure the
// two words exist to turn into a clean false.
Uint64 schema = 0;
if (!TakeRaw(in, version) || !TakeRaw(in, schema)) return false;
// Refuse the declared wire shape before reading any field. In v2 the second word
// follows serialization types/order; C++ container object sizes are irrelevant.
if (version != kProgramArtifactsCodecVersion) return false;
if (sizeEcho != kLinkArtifactsSizeEcho) return false;
#if MOBILEGL_BUILD_DISAGGREGATED
if (schema != ProgramArtifactsSchemaFingerprint()) return false;
#else
if (schema != kLinkArtifactsSizeEcho) return false;
#endif
ReadValue(in, link);
ReadValue(in, spirv);
@@ -32,9 +32,9 @@
// path.
//
// THE FORMAT, and every part of it is a refusal rather than a guess:
// * a VERSION word first, and a MGL_LINKARTIFACTS_SIZE echo second, so a struct that gained
// a field and a codec that did not is a MISMATCH AT READ TIME rather than a silent
// truncation that deserialises garbage into the tail of a reflection table;
// * a VERSION word first, and a wire-schema fingerprint second (v2), so member order,
// type or count-layout drift is a MISMATCH before decoding. The local-only v1 form
// retains its legacy native-size echo;
// * length-prefixed everything - strings, vectors, maps, sets - with the count checked
// against the bytes that remain before a single element is allocated, so a corrupt count
// cannot turn into a four-billion-element resize;
@@ -54,19 +54,20 @@
// 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.
// P6.5: native STL object sizes never describe this field-wise byte stream. Disaggregated
// peers use v2's recursive wire-schema fingerprint; monolith verification retains v1.
namespace MobileGL::MG_State::GLState {
// Bumped whenever the byte format changes in a way a previous reader would misread. A
// reader that sees a different word REFUSES; it never tries to guess a layout.
#if MOBILEGL_BUILD_DISAGGREGATED
inline constexpr Uint32 kProgramArtifactsCodecVersion = 2;
// Derived from the actual VisitFields order/names, container element schemas and scalar
// representations. No native container size/offset is included. Also checked in Hello.
Uint64 ProgramArtifactsSchemaFingerprint();
#else
inline constexpr Uint32 kProgramArtifactsCodecVersion = 1;
#endif
// Appends the archive to `out` (which is not cleared, so a caller may frame it). Never
// fails: everything it walks is owned plain data.
@@ -75,7 +76,7 @@ namespace MobileGL::MG_State::GLState {
// Replaces `link` and `spirv` with what `bytes` describes. Returns false - with both
// outputs left in a defined, default state - for a truncated stream, a version mismatch, a
// struct-size mismatch, or trailing bytes the format does not account for. `link.program`
// wire-schema mismatch (native-size echo for local v1), or trailing bytes. `link.program`
// is always null on return.
Bool DecodeProgramArtifacts(const Uint8* bytes, SizeT size, LinkArtifacts& link,
SpirvArtifacts& spirv);