[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
@@ -1,125 +0,0 @@
// MobileGL - MobileGL/MG_Remote/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
+8 -32
View File
@@ -10,23 +10,21 @@
// wire FatalCode, both generated from FatalFamilies.def so a family, its name and its wire code
// cannot drift apart: adding a family is one row, and a row that forgets its code does not
// compile.
//
// P13 W5: the vocabulary itself (the enum, its names, its count) lives in MG_Pipe/PipeFatalFamily.h
// so the record arm can die by name in a library without MG_Remote; this header adds the wire
// projection and re-exports the vocabulary under its old names.
#pragma once
#include <MG_Pipe/PipeFatalFamily.h>
#include <MG_Remote/Protocol/generated/protocol_generated.h>
#include "FatalFamilies.def"
namespace MobileGL::MG_Remote {
// 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
};
using ::MobileGL::MG_Pipe::FatalFamilyName;
using ::MobileGL::MG_Pipe::MGFatalFamily;
using ::MobileGL::MG_Pipe::MGFatalFamilyCount;
// THE PROJECTION, AS A TOTAL TABLE. Not a switch with a default arm: this build has no
// -Werror, so a default would silently swallow a family added without a code. Every family
@@ -43,26 +41,4 @@ namespace MobileGL::MG_Remote {
return ::MobileGL::Wire::FatalCode::ProtocolCorruption;
}
// 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_Remote
+19
View File
@@ -307,4 +307,23 @@ namespace MobileGL::MG_Remote {
}
} // namespace
// P13 W5: THE RECORD ARM'S DEATHS GO THROUGH THIS FUNNEL WHEREVER MG_Remote IS LINKED.
// Registered at static init rather than at role init: both roles, and unit cases that never
// run one, call into the record arm, and each of its deaths must count, publish and latch
// exactly as the direct SessionFail / SessionLatch call it replaced did. The line arrives
// formatted, so it is passed through "%s" - the same bytes reach the log and the frame.
namespace {
[[noreturn]] void RecordFailThroughFunnel(MGFatalFamily family, const char* line) {
SessionFail(family, "%s", line);
}
bool RecordLatchThroughFunnel(MGFatalFamily family, const char* line) {
return SessionLatch(family, "%s", line);
}
[[maybe_unused]] const bool g_recordFailHooksRegistered = [] {
MG_Pipe::MGPipeInstallRecordFailHooks(&RecordFailThroughFunnel, &RecordLatchThroughFunnel,
&SessionLatched);
return true;
}();
} // namespace
} // namespace MobileGL::MG_Remote