mirror of
https://github.com/MobileGL-Dev/MobileGL
synced 2026-11-19 07:51:57 +09:00
[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:
@@ -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
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user