Files
MobileGL/MobileGL/MG_Pipe/FieldOwnership.def
T

188 lines
15 KiB
Modula-2

// MobileGL - MobileGL/MG_Pipe/FieldOwnership.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
// P5f exit classification. This table describes SERVER reads, not monolith storage.
// RECORD_SUPPLIED is still derived from Coverage.def minus the whole-field refusal set.
// A handle record does not supply a legacy pointer-valued getter: those getters are FATAL,
// while their migrated consumers read the server record directly. Never relabel a pointer
// RECORD_SUPPLIED merely to make the debt count zero.
//
// APPLIER_DERIVED accessors answer server state. FATAL accessors must abort on any server
// read, including barriered/escalated records and non-strict/shared-block configurations.
// BARRIER_PULLED remains a schema class so generator controls can test debt admission,
// but no production row may use it after P5f. Monolith getter/fill behavior is unchanged.
//
// EmittedCallSuppliesTheWholeField retains its eight refusals: seven legacy pointer
// representations plus the two-sided pixel-store field. Deleting those refusals would
// falsely derive RECORD_SUPPLIED for the retired getters; server consumers bypass them.
//
// clang-format off
// X(Field, Class, RetiringPhase, Why)
#define MGP_FIELD_OWNERSHIP_LIST(X) \
X(GetBoundVertexArray, FATAL, "-", "server reads vertex-element handles; the legacy SharedPtr is not a wire value") \
X(GetBufferBindingSlot, FATAL, "-", "server reads verb buffer handles/reply scratch; legacy binding-slot pointers are forbidden") \
X(GetBufferBindingPoint, FATAL, "-", "server reads indexed buffer ranges or XFB Begin targets; never a client table base") \
X(GetFramebufferBindingSlot, FATAL, "-", "server reads framebuffer records; never a client BindingSlot") \
X(GetImageTextureBinding, FATAL, "-", "server reads shader-image records; never the client image-unit array") \
X(GetTextureUnitObject, FATAL, "-", "server reads sampler/view records or verb texture handles; never a client TextureUnit") \
X(GetProgramForDraw, FATAL, "-", "server reads draw-program handles and its owned ProgramArchive") \
X(GetProgramForDispatch, FATAL, "-", "server reads dispatch-program handles and its owned ProgramArchive") \
X(GetTransformFeedbackProgram, FATAL, "-", "server reads the capture-program archive retained by the Begin snapshot") \
X(GetBoundTransformFeedbackName, FATAL, "-", "no backend reader; XFB identity crosses as a lifetime value") \
X(GetTransformFeedbackPausedPrimitiveCounter, FATAL, "-", "query-only legacy accessor; transport entry is a named class-C refusal") \
X(GetProgramObject, FATAL, "-", "program identity is resolved on the client and crosses as a shader-CSO handle") \
X(GetTextureObject, FATAL, "-", "texture identity crosses as a handle; no server GL-name lookup into the client") \
X(ValidateProgramName, FATAL, "-", "validation belongs to the client; the server validates the carried handle") \
X(InvalidateCompileEnv, FATAL, "-", "transport caps republication replaces direct frontend invalidation") \
X(RecordError, FATAL, "-", "transport OnGlError posts an event before the legacy frontend-error-queue arm") \
X(GetPixelStoreParameters, APPLIER_DERIVED, "-", "set_pixel_pack_state writes the pack half; unpack is forbidden below") \
X(GetSamplingResolutionGeneration, APPLIER_DERIVED, "-", "server-owned applier texture shutter serial") \
X(GetTextureBindGeneration, APPLIER_DERIVED, "-", "server-owned applier texture shutter serial") \
X(GetTextureContextId, APPLIER_DERIVED, "-", "server-owned applier context serial") \
X(GetBufferBindingPointCount, APPLIER_DERIVED, "-", "fixed indexed binding-point capacity; no client lookup") \
X(HasOpenTransformFeedbackSpan, APPLIER_DERIVED, "-", "server Begin/End snapshot table keyed by XFB lifetime id")
// The seven sticky forwards carry the same verdict as their field rows.
#define MGP_FIELD_OWNERSHIP_FORWARD_LIST(X) \
X(GetBufferBindingPointCount, APPLIER_DERIVED, "-", "fixed indexed binding-point capacity; no client lookup") \
X(GetProgramObject, FATAL, "-", "program identity is resolved on the client and crosses as a shader-CSO handle") \
X(GetTextureObject, FATAL, "-", "texture identity crosses as a handle; no server GL-name lookup into the client") \
X(HasOpenTransformFeedbackSpan, APPLIER_DERIVED, "-", "server Begin/End snapshot table keyed by XFB lifetime id") \
X(ValidateProgramName, FATAL, "-", "validation belongs to the client; the server validates the carried handle") \
X(InvalidateCompileEnv, FATAL, "-", "transport caps republication replaces direct frontend invalidation") \
X(RecordError, FATAL, "-", "transport OnGlError posts an event before the legacy frontend-error-queue arm")
// X(Field, Arg0, Class, Why) - ARGUMENT-KEYED EXCEPTIONS.
//
// A row here narrows ONE argument value of ONE field to a different class. The field keeps
// its single row above; this is the same shape Coverage.def:62-69 already rules for
// GetBufferBindingSlot - "THE ROW STAYS ONE ROW, and that is structural rather than a
// shortcut: this list IS the MGPipeInputField enum and the PipeInputs field set, and the
// field is ONE array that a second row of the same name could only duplicate".
//
// GetPixelStoreParameters is m_pixelStore[2] indexed by its own `isUnpack` argument, exactly
// as GetBufferBindingSlot is m_bufferBindingSlot[15] indexed by its BufferTarget. Only [0]
// (pack) has a carrier, and the applier writes it.
//
// AND THE UNPACK HALF HAS NO BACKEND READER AT ALL. Every MGB_CTX->GetPixelStoreParameters
// call site in the tree passes `false`: DirectGLES.cpp:7924, :9399, :10893, :11272,
// Utils.cpp:2302 and VulkanRenderer.cpp:10980 - six, not the five the scout named, and the
// scout did not open them. PipeFill.cpp's own EmitPixelPackState says the same thing from
// the other side: "PACK only, deliberately: nothing on the far side of the boundary reads
// unpack state". So the honest class for the unpack half is FATAL, not BARRIER_PULLED: a
// future backend read of it would otherwise be served a stale struct in silence, and this
// way it is a named abort on the first read.
#define MGP_FIELD_OWNERSHIP_ARG_LIST(X) \
X(GetPixelStoreParameters, 1, FATAL, \
"the unpack half has no carrier AND no backend reader; all six MGB_CTX sites pass false")
// X(WireOp, Verb) - WHERE THE SERVER STAMPS.
//
// The stamp rule needs one thing the wire does not carry: which MGPipeVerb a record belongs
// to. The two name spaces are not the same and do not line up by name - the DRAW verb is
// `DrawArrays` and its record is `draw_vbo`, the BLIT verb is `BlitFramebuffer` and its record
// is `blit` - so the map is written here and checked against both sources (PipeCalls.def for
// the op, FillPoints.def for the verb) rather than believed.
//
// EXACTLY THE OPS THAT ARE VERB BOUNDARIES. CONTRACT-P5.md section 7 puts five slots in class
// B (emitted in P5): Clear, DrawArrays, ReadPixels, BlitFramebuffer and Present. FOUR OF THEM
// ARE HERE AND PRESENT IS NOT, and that is a ruling rather than an omission: FillPoints.def:21
// says in so many words that "Present and SetSwapInterval go through BackendObject virtuals
// and read no frontend state, so they are not verbs here". There is no MGPipeVerb::Present to
// stamp for, MGPipeValidateForVerb is never called for it, and stamping at Present would
// retire the previous verb's answers with nothing to put in their place.
//
// An op that is not in this list is NOT a verb boundary and the applier must not stamp on it:
// a set_dynamic_state between two draws is part of the draw's verb, not a new one.
//
// THE GENERATOR REFUSES AN OMISSION, NOT ONLY A TYPO, and that is the half the first version of
// this file did not have. Every call that is VERB-SHAPED must have a row here or an exemption
// row below with a reason. "Verb-shaped" is the union of two mechanical tests, both derived:
// (a) PipeCalls.def gives the call kind kCtxVerb - the catalogue's own word for it;
// (b) the call's name is also an MGPipeVerb name in FillPoints.def.
// Eighteen rows and three exemptions cover all twenty-one (P5: twelve and three; P5b appended
// the five kCtxVerb rows 72..76 and settled ResourceCopyRegion). Only four of the rows could
// arrive in P5 (CONTRACT §7 class B minus Present); the rest are Fatal{UnmigratedVerb} on the
// client until a P5b migration package flips them and are mapped ANYWAY, because the failure
// mode of an absent row is silent: the applier would run the record under the PREVIOUS verb's
// serial, mask and name, and a field inside that mask would read FRESH while holding the
// previous verb's value.
//
// NOT MECHANICALLY DETECTABLE, and so not claimed: a call that is a verb boundary, is not
// kCtxVerb, and whose name differs from its verb's. `ResourceCopyRegion` WAS the one in the
// tree (its verbs could have been CopyImageSubData / CopyTexSubImage2D / CopyTexImage2D). P5b
// decided: resource_copy_region is glCopyImageSubData only, and the two framebuffer-sourced
// copies have their own row (copy_framebuffer_to_texture), so the choice is a row here rather
// than a rule in a reader's head.
#define MGP_VERB_OP_LIST(X) \
/* CONTRACT §7 class B - the four that can actually arrive in P5. */ \
X(Clear, Clear) \
X(DrawVbo, DrawArrays) \
X(ReadPixels, ReadPixels) \
X(Blit, BlitFramebuffer) \
/* Class C today (Fatal{UnmigratedVerb}); mapped so the phase that emits one cannot get NO */ \
/* stamp by omission. DrawVbo above has the same shape and a worse case: it stands for all */ \
/* twenty draw verbs, which share the kDraw mask but not the NAME a Fatal prints. */ \
X(LaunchGrid, DispatchCompute) \
X(MemoryBarrier, MemoryBarrier) \
X(BeginStreamOutput, BeginTransformFeedback) \
X(EndStreamOutput, EndTransformFeedback) \
X(PauseStreamOutput, PauseTransformFeedback) \
X(ResumeStreamOutput, ResumeTransformFeedback) \
X(GenerateMipmap, GenerateMipmap) \
X(GetTextureImage, GetTextureImage) \
/* P5b (MG_Remote/CONTRACT-P5B.md). The ONE renamed, non-kCtxVerb boundary the file above */ \
/* said "the phase that emits it adds its row and decides which verb it is": P5b rules */ \
/* resource_copy_region = glCopyImageSubData ONLY; the two framebuffer-sourced copies */ \
/* (CopyTexImage2D / CopyTexSubImage2D) are copy_framebuffer_to_texture below, stamped as */ \
/* CopyTexImage2D - both are kBlitOrCopy, one mask, and a row can name one verb. */ \
X(ResourceCopyRegion, CopyImageSubData) \
/* The five P5b-appended verbs, opcodes 72..76, each stamped as the GLFunctionsTable verb */ \
/* it reproduces. */ \
X(BindShaderImage, BindImageTexture) \
X(PatchParameter, PatchParameteri) \
X(BindStreamOutput, BindTransformFeedback) \
X(SetStorageBlockBinding, ShaderStorageBlockBinding) \
X(CopyFramebufferToTexture, CopyTexImage2D) \
X(FenceCreate, FenceSync) \
X(FenceStatus, GetSyncStatus) \
X(FenceWait, ClientWaitSync) \
X(FenceDestroy, DeleteSync) \
X(FenceWaitServer, WaitSync) \
X(QueryCreate, BeginXfbPrimitivesQuery) \
X(QueryBegin, BeginXfbPrimitivesQuery) \
X(QueryEnd, EndXfbPrimitivesQuery) \
X(QueryAvailable, IsQueryResultAvailable) \
X(QueryResult, GetQueryResult64) \
X(QueryDestroy, DeleteBackendQuery) \
X(QueryCounter, QueryCounterTimestamp) \
X(QueryTimestamp, GetGpuTimestampNs) \
X(DeleteStreamOutput, DeleteTransformFeedback) \
/* P9 (CONTRACT-P9.md §1): the pack-buffer halves stamp as the verb they reproduce. */ \
X(ReadPixelsToBuffer, ReadPixels) \
X(GetTextureImageToBuffer, GetTextureImage)
// X(Op, Why) - verb-shaped calls that are deliberately NOT stamp points.
//
// An exemption is a ROW, not an absence, so that the reason is in the file rather than in a
// reviewer's head and so that the generator's completeness check has something to accept.
#define MGP_VERB_OP_EXEMPT_LIST(X) \
X(Present, \
"FillPoints.def:21 - Present and SetSwapInterval go through BackendObject virtuals and " \
"read no frontend state, so they are not verbs here. There is no MGPipeVerb::Present, " \
"MGPipeValidateForVerb is never called for it, and stamping would retire the previous " \
"verb's answers with nothing to put in their place. It is class B all the same.") \
X(SetSwapInterval, \
"the same sentence of FillPoints.def:21, and it is class C besides") \
X(Flush, \
"not a verb at all: the verb census (BRIEF §12 C-3) found Flush is not a GLFunctionsTable " \
"slot and glFlush/glFinish are empty function bodies (Definitions.cpp:111-112), so there " \
"is no MGPipeVerb::Flush for a row to name")
// clang-format on