[Feat] (P13 W5 S1): the fatal vocabulary moves to MG_Pipe and the record arm gets its own fail / latch seam.

This commit is contained in:
2026-10-06 09:48:58 -04:00
parent ec92ae4d08
commit 534f14e3f2
10 changed files with 294 additions and 38 deletions
+125
View File
@@ -0,0 +1,125 @@
// MobileGL - MobileGL/MG_Pipe/FatalFamilies.def
// Copyright (c) 2025-2026 MobileGL-Dev
// Licensed under the GNU Lesser General Public License v3.0:
// https://www.gnu.org/licenses/gpl-3.0.txt
// https://www.gnu.org/licenses/lgpl-3.0.txt
// SPDX-License-Identifier: LGPL-3.0-only
// End of Source File Header
// P6 `dl` (CONTRACT-P6 5.2, D2 ruling). THE INTERNAL FATAL VOCABULARY, and its projection onto
// the SEVEN-value wire FatalCode.
//
// a6 censused 30 distinct family words against a 7-value wire enum, so Session::Fail(FatalCode,
// detail) cannot carry the vocabulary in its first argument - the word would collapse to one of
// seven and the log would say "ProtocolCorruption" where the code said "UnmigratedVerb". So the
// family is an INTERNAL enum, generated from this file, and the wire keeps FatalCode. Each row
// carries the coarse code the PEER is told when this family kills the session; the rich word
// stays in the local log and in the SessionFault frame's `family` string.
//
// THE PROJECTION IS A TOTAL TABLE, NOT A SWITCH WITH A DEFAULT. This build has no -Werror
// anywhere (measured: CMakeLists, every *.cmake, both workflows), so a gate premised on -Wswitch
// catching a missing arm is fiction. A row here IS the arm; a family with no row does not
// compile a call that names it.
//
// WHY EACH CODE. The wire FatalCode answers one question for the peer: what KIND of end was
// this. The buckets:
// ProtocolCorruption - the peer sent, or the session reached, something that cannot be
// honoured correctly: a malformed record, an unimplemented verb/surface,
// an invariant the roles must hold, a reply that does not fit its
// contract. The peer's takeaway is "we disagree about the protocol".
// RingOverrun - a shared ring or event channel overran. A transport-capacity fact.
// SegmentMismatch - a shared SEGMENT's geometry could not hold what a role needed to put
// in it. Distinct from a ring overrun: the segment is the wrong SIZE,
// not merely full this instant.
// AbiMismatch - the two builds do not agree on layout or protocol version.
// ServerCrashed - a liveness end the WAITING side attributes to the other: a drain that
// never completed, an apply thread that is gone or never started, a native
// resource the server had to have and could not obtain. The device-lost
// latch is armed from the doorbell, never from these, but the peer that
// was waiting is told the server is gone.
// DeviceLost - reserved: set by the latch (5.3), never raised as a Fatal family, so no
// row projects onto it.
//
// P7 WAVE 0 ADDED ELEVEN ROWS, for the eleven words the widened census gate found in the server
// image outside MG_Remote/ (scripts/ci/fatal_census.py rule 3). Ten are ProtocolCorruption for
// the reason that bucket already states - a record, a mask or a reply that cannot be honoured
// correctly. The eleventh, ResourceUnavailable (Managers.cpp's three image-promotion sites and
// VkBufferManager.cpp's eight), is ServerCrashed rather than SegmentMismatch: SegmentMismatch
// means a SHARED SEGMENT was the wrong size, and telling a peer that when a VkBuffer allocation
// or a native readback failed would be a lie about whose geometry was wrong. The honest thing to
// tell a waiting peer is the one ServerCrashed already says. The wire enum has no "the server
// could not obtain a resource" value and adding one would move `wireFingerprint`, which is a
// protocol change no wave-0 instrument is entitled to make (recorded for the integrator).
//
// P12 (on-screen server window) ADDED ONE ROW, ServerWindowLost: the display server's window was
// destroyed (surfaceDestroyed) under a live on-screen session. The session latches by name after
// its surface is released, and the WAITING client is told what ServerCrashed already says - the
// server-side resource its session had to have is gone - so it reads a clean device loss. Not
// DeviceLost: that code is the latch's own, never a family's projection (see its bucket above).
//
// BackendDeviceLost: the GPU device (Magma's VkDevice, Espryt's EGL context) a session renders
// with was lost to a GPU fault or hang. It is only ever LATCHED (MGPipeSessionLatch), so the one
// session ends and the display server's other sessions keep running; the waiting client is told
// what ServerCrashed says and reads a lost context. Not DeviceLost, for ServerWindowLost's reason.
//
// Two words were NOT given rows, they were collapsed instead: `InitialBytesNotCarried`
// (MG_Impl/Pipe/PipeFill.cpp) said the same thing as `UncarriedInitialBytes` (Client/
// WireTables.cpp) about the same record - a respecify that crossed with no initial bytes - and
// two words for one family is exactly the drift a6 censused. PipeFill now uses the older word.
//
// clang-format off
// X(Family, WireFatalCode, Why)
#define MGL_FATAL_FAMILY_LIST(X) \
X(ProtocolCorruption, ProtocolCorruption, "a record's bounds or self-describing length was violated") \
X(UnmigratedVerb, ProtocolCorruption, "a wire verb slot P5/P6 does not implement was reached") \
X(UnmigratedSurface, ProtocolCorruption, "a surface op named a client-process handle that means nothing here (P12)") \
X(UnmigratedPipeInput, ProtocolCorruption, "a PipeInputs field with no field-ownership row was read across the boundary") \
X(UnmigratedEmulation, ProtocolCorruption, "an emulation path the applier has no migrated arm for was reached") \
X(RoleViolation, ProtocolCorruption, "a call ran on the wrong role/thread - an invariant the two roles must hold") \
X(UnsetCallMask, ProtocolCorruption, "the CallMask was consulted before either half was published") \
X(CapsBeforeFirstSnapshot, ProtocolCorruption, "a record family's liveness was asked of a placeholder caps mirror (F1)") \
X(ConsumerMaskLie, ProtocolCorruption, "the server published a consumer bit for a family whose op table is absent") \
X(ClientTablesUninstalled, ProtocolCorruption, "the applier ran before the client installed its tables") \
X(NoClientSession, ProtocolCorruption, "a path that needs the client session ran without one") \
X(UnnamedIdentity, ProtocolCorruption, "a per-context memo was consulted with a null context identity") \
X(PipeLegacyMemosDisabled, ProtocolCorruption, "a subsystem bit is clear and this build compiles no legacy arm to fall back to (unreachable since P13 W3b fixed bits 0-13 on)") \
X(PipeSubsystemsFixedOn, ProtocolCorruption, "MOBILEGL_PIPE_PUSH cleared one of subsystem bits 0-13, which P13 fixed on") \
X(PipeVerifyBadKnob, ProtocolCorruption, "a MOBILEGL_PIPE_VERIFY/POISON knob named a verb or field that does not exist") \
X(PipeVerifyDiffer, ProtocolCorruption, "the verify comparator found a pushed field differing from the live one") \
X(UnexpectedMapAccept, ProtocolCorruption, "a persistent-map accept arrived where the protocol permits none") \
X(UncarriedInitialBytes, ProtocolCorruption, "a producer's initial bytes were required on the wire and absent") \
X(ReplyStatusInvalid, ProtocolCorruption, "a reply carried a status outside the defined set") \
X(ReplyError, ProtocolCorruption, "a reply-owning verb saw an error status it cannot represent") \
X(ReplyMissing, ProtocolCorruption, "a reply slot the protocol requires was empty") \
X(ReplyMismatched, ProtocolCorruption, "the reply mailbox held an answer for a different slot than the one waited on") \
X(ReplyOverrun, ProtocolCorruption, "an answer was posted while a previous one was still unread") \
X(ReplyToNoSlot, ProtocolCorruption, "an answer was posted against reply slot 0, which means \"no record\"") \
X(ReplyTooLarge, ProtocolCorruption, "an answer exceeded the size its verb's contract allows") \
X(ResidualBlockSize, ProtocolCorruption, "a fixed-size residual block arrived at a size that is not its own") \
X(ReadbackDeclined, ProtocolCorruption, "a readback that cannot return without complete pixels was declined") \
X(ReadbackReplyShort, ProtocolCorruption, "a readback reply carried fewer bytes than its shape requires") \
X(UnsizedReadback, ProtocolCorruption, "a readback arrived with no declared size") \
X(BlobMissing, ProtocolCorruption, "a record named a blob that was never staged") \
X(BlobNotStaged, ProtocolCorruption, "a blob was referenced before its staging completed") \
X(ArtefactsMissing, ProtocolCorruption, "a program create arrived with no artefacts") \
X(ArchiveEmpty, ProtocolCorruption, "a create_*_state archive carried no payload") \
X(BarrierViolation, ProtocolCorruption, "a field was pulled across a verb boundary the barrier forbids") \
X(UnimplementedAdoptTier, ProtocolCorruption, "MOBILEGL_IPC_ADOPT_TIER named a tier P5 does not implement") \
X(UnimplementedWritebackWait, ProtocolCorruption, "a writeback wait shape P5 does not implement was requested") \
X(UnimplementedRemoteBackendObject, ProtocolCorruption, "a BackendObject_Remote entry point P5 does not implement was called") \
X(UnimplementedClientSession, ProtocolCorruption, "a ClientSession entry point P5 does not implement was called") \
X(RingOverrun, RingOverrun, "a shared ring refused a record after sufficient space had retired") \
X(EventRingOverflow, RingOverrun, "the reverse event ring overflowed") \
X(StageSnapshotTooNarrow, SegmentMismatch, "SEG_STAGE was too small for a snapshot a verb had to place in it") \
X(AbiMismatch, AbiMismatch, "the two builds disagree on struct layout or protocol version") \
X(BarrierTimeout, ServerCrashed, "appliedSeq did not reach the target within the bounded wait") \
X(PresentCreditTimeout, ServerCrashed, "a present credit did not return within the bounded wait") \
X(RetirementWaitFailed, ServerCrashed, "a wait for the server to retire staging did not complete") \
X(ApplyThreadJoinTimeout, ServerCrashed, "the apply thread did not join within its bound at teardown") \
X(ApplyThreadNotRunning, ServerCrashed, "an operation needed the apply thread and it was not running") \
X(ResourceUnavailable, ServerCrashed, "the server could not obtain a native GL/Vulkan resource it had to have") \
X(ServerWindowLost, ServerCrashed, "the server's own display window was destroyed under a live on-screen session (P12)") \
X(BackendDeviceLost, ServerCrashed, "the GPU device a session's backend renders with was lost (fault or hang reset)")
// clang-format on
+60
View File
@@ -119,6 +119,66 @@
namespace MobileGL::MG_Pipe {
// ----------------------------------------------------------------------------
// P13 W5: THE RECORD ARM'S FAIL / LATCH SEAM (PipeSessionFail.h). Constant-initialized
// pointers, so a registration made during another translation unit's static init (FatalFunnel.cpp)
// is never overwritten by this one's.
namespace {
constinit MGPipeRecordFailHook g_recordFailHook = nullptr;
constinit MGPipeRecordLatchHook g_recordLatchHook = nullptr;
constinit MGPipeRecordLatchedHook g_recordLatchedHook = nullptr;
void FormatRecordLine(char (&line)[512], const char* fmt, va_list args) {
const int written = std::vsnprintf(line, sizeof(line), fmt, args);
if (written < 0) {
std::snprintf(line, sizeof(line), "MGPipe: unformattable Fatal diagnostic (format=%s)", fmt);
}
}
[[noreturn]] void RecordDeath(MGFatalFamily family, const char* line) {
if (g_recordFailHook != nullptr) g_recordFailHook(family, line);
// NO HOOK (no MG_Remote in this library): the line, its stderr echo - the logger's
// console sink is off and a gtest death matcher reads the child's stderr - and the abort.
MGLOG_F("%s", line);
std::fputs(line, stderr);
std::fputc('\n', stderr);
std::fflush(stderr);
std::abort();
}
} // namespace
void MGPipeInstallRecordFailHooks(MGPipeRecordFailHook fail, MGPipeRecordLatchHook latch,
MGPipeRecordLatchedHook latched) {
g_recordFailHook = fail;
g_recordLatchHook = latch;
g_recordLatchedHook = latched;
}
void MGPipeRecordFail(MGFatalFamily family, const char* fmt, ...) {
char line[512];
va_list args;
va_start(args, fmt);
FormatRecordLine(line, fmt, args);
va_end(args);
RecordDeath(family, line);
}
bool MGPipeRecordLatch(MGFatalFamily family, const char* fmt, ...) {
char line[512];
va_list args;
va_start(args, fmt);
FormatRecordLine(line, fmt, args);
va_end(args);
if (g_recordLatchHook != nullptr) return g_recordLatchHook(family, line);
RecordDeath(family, line);
}
bool MGPipeRecordLatched() { return g_recordLatchedHook != nullptr && g_recordLatchedHook(); }
MGPipeRecordFailHook MGPipeRecordFailHookInstalled() { return g_recordFailHook; }
MGPipeRecordLatchHook MGPipeRecordLatchHookInstalled() { return g_recordLatchHook; }
MGPipeRecordLatchedHook MGPipeRecordLatchedHookInstalled() { return g_recordLatchedHook; }
#if MOBILEGL_BUILD_DISAGGREGATED
// ----------------------------------------------------------------------------
// THE BACKEND-SIDE SESSION-FAIL SEAM (P7 wave 0). PipeSessionFail.h holds the argument;
+55
View File
@@ -0,0 +1,55 @@
// MobileGL - MobileGL/MG_Pipe/PipeFatalFamily.h
// Copyright (c) 2025-2026 MobileGL-Dev
// Licensed under the GNU Lesser General Public License v3.0:
// https://www.gnu.org/licenses/gpl-3.0.txt
// https://www.gnu.org/licenses/lgpl-3.0.txt
// SPDX-License-Identifier: LGPL-3.0-only
// End of Source File Header
// P13 W5: THE FATAL VOCABULARY WITHOUT THE WIRE. The record arm runs in a library that has no
// MG_Remote (the FCL shape), and its deaths still need their family words: a staged store that
// cannot answer, a record whose bounds are wrong. So the enum and its names are generated here
// from FatalFamilies.def, and MG_Remote/FatalFamily.h keeps only what needs the protocol - the
// projection of a family onto the seven-value wire FatalCode - and re-exports these names.
#pragma once
#include <cstddef>
#include <cstdint>
#include "FatalFamilies.def"
namespace MobileGL::MG_Pipe {
// One value per row of FatalFamilies.def, in file order. The names ARE the family words that
// appear in every `Fatal{...}` log line, which is what lets FatalFamilyName round-trip
// against the string a site passes.
enum class MGFatalFamily : ::std::uint32_t {
#define X(Family, WireCode, Why) Family,
MGL_FATAL_FAMILY_LIST(X)
#undef X
};
// The family's own word, byte-for-byte what appears inside `Fatal{<name>, ...}`. A death
// site passes both the enum and its full message string; a test asserts this name is present
// in that string, which is what keeps the two from diverging.
inline const char* FatalFamilyName(MGFatalFamily family) {
switch (family) {
#define X(Family, WireCode, Why) \
case MGFatalFamily::Family: return #Family;
MGL_FATAL_FAMILY_LIST(X)
#undef X
}
return "<unknown>";
}
// The count, for a test that walks every family.
inline constexpr ::std::size_t MGFatalFamilyCount() {
::std::size_t n = 0;
#define X(Family, WireCode, Why) ++n;
MGL_FATAL_FAMILY_LIST(X)
#undef X
return n;
}
} // namespace MobileGL::MG_Pipe
+40
View File
@@ -39,6 +39,8 @@
#pragma once
#include <MG_Pipe/PipeFatalFamily.h>
namespace MobileGL::MG_Pipe {
// THE FAMILIES THAT CROSS THIS BOUNDARY, AND ONLY THOSE. Not `MGFatalFamily` cast to an
@@ -85,6 +87,44 @@ namespace MobileGL::MG_Pipe {
#endif
void MGPipeSessionFail(MGPipeFatalFamily family, const char* fmt, ...);
// ---- P13 W5: THE RECORD ARM'S DEATHS, IN EVERY BUILD -------------------------------------
//
// The record arm's own code - the staged stores, the verb sink, the verb port - dies by
// family word (MG_Pipe::MGFatalFamily, the whole FatalFamilies.def vocabulary) and, where a
// session can be ended instead of the process, latches. With MG_Remote linked, FatalFunnel.cpp
// registers SessionFail / SessionLatch / SessionLatched here at static init, so every DISAGG
// process - unit cases with no role init included - counts, publishes and latches exactly as
// a direct call did. Without MG_Remote (the FCL shape) the defaults are the monolith answer:
// log the line, echo it to stderr (a death test reads the child's stderr), abort; latching is
// dying; nothing is ever latched.
//
// `line` is the FULLY FORMATTED message, family word and all, as for MGPipeSessionFail.
using MGPipeRecordFailHook = void (*)(MGFatalFamily family, const char* line);
using MGPipeRecordLatchHook = bool (*)(MGFatalFamily family, const char* line);
using MGPipeRecordLatchedHook = bool (*)();
// Last writer wins; a null leaves that half on its default.
void MGPipeInstallRecordFailHooks(MGPipeRecordFailHook fail, MGPipeRecordLatchHook latch,
MGPipeRecordLatchedHook latched);
// The installed hooks, or nullptr - so a test proves the registration happened (and restores
// what it replaced) without having to die to find out.
MGPipeRecordFailHook MGPipeRecordFailHookInstalled();
MGPipeRecordLatchHook MGPipeRecordLatchHookInstalled();
MGPipeRecordLatchedHook MGPipeRecordLatchedHookInstalled();
[[noreturn]]
#if defined(__GNUC__) || defined(__clang__)
__attribute__((format(printf, 2, 3)))
#endif
void MGPipeRecordFail(MGFatalFamily family, const char* fmt, ...);
// Returns false (a Bool site reads `return MGPipeRecordLatch(...);`) when the hook latched the
// calling session; with no latch to raise it dies as MGPipeRecordFail does.
bool
#if defined(__GNUC__) || defined(__clang__)
__attribute__((format(printf, 2, 3)))
#endif
MGPipeRecordLatch(MGFatalFamily family, const char* fmt, ...);
// Whether the calling session already latched (false with no hook).
bool MGPipeRecordLatched();
#if MOBILEGL_BUILD_DISAGGREGATED
// ---- THE LATCH TWIN: A LOST GPU DEVICE ENDS ITS SESSION, NOT THE PROCESS ----------------
//