mirror of
https://github.com/MobileGL-Dev/MobileGL
synced 2026-11-16 22:43:24 +09:00
notes/p7/magma-a.md: the per-site table (retired / declined / kept-fatal with the
reason), every red-once with its captured output, the gate readings, and what is
handed on.
The three places package A's own prose still named `uniform-buffer-byte-tail@P7`
lose the marker. They are comments, not refusal sites, and leaving the marker in
would have made a tree-wide `grep @P7` count them against packages B and C. The
census now reads 15 -> 7, and all seven are real: WireFramebuffer.inc x4 and
VulkanRenderer.cpp x1 (package B), WireDraw.inc x2 (package C).
Three findings worth the integrator's attention, all in the note:
1. Most of this cluster was unreachable, and that is provable rather than
assumed. The frontend validates buffer-range offsets against the very caps the
backend then re-checks - GL_{UNIFORM,SHADER_STORAGE,TEXTURE}_BUFFER_OFFSET_ALIGNMENT
and GL_MAX_UNIFORM_BLOCK_SIZE are all published from the same Vulkan limits -
so five of the eight sites could only ever have fired on a malformed peer. The
two that CAN fire are `uniform-buffer-byte-tail` (GL constrains a range's
offset but not its size) and `unaligned-atomic-buffer-range` (GL gives
GL_ATOMIC_COUNTER_BUFFER no queryable alignment, so the frontend only enforces
offset % 4 while the backend needs minStorageBufferOffsetAlignment).
2. fatal_census does not move for any of this, and no re-baseline is due. Wave 0
already routed these funnels through MGPipeSessionFailHook, so the abort lives
in FatalFunnel.cpp and retiring a WireDescriptorFatal call site changes no
census number: 79 abort sites / 43 family words, unchanged, RC=0. The brief
expected the count to fall because the sites were bare aborts before wave 0.
3. DirectVulkan.Split.Full.IterationRPProgram203Scenario.FixedCompleteInputProducesFixedCompleteGoldenOutput
is red on this worktree's build-split and is NOT ours: it reproduces 3/3 with
package A's backend diff fully reverted, and the mismatch bits are identical
to the S1 exposure texel in magma-two-process-first-run.md. The contract books
that one against the tcp arm, and ~/w7/pipe's own build-split passes it, so
whether it is a split-arm regression between 460a3a72 and 610fa281 or a
configure-dependent S1 needs the integrator.
Gates on the finished branch: integration-magma-split 75/75, -spawn 54/54, -tcp
56/56, -buffers 21/21, full-split 512 entries 454 PASS / 57 SKIP / 1 red (the
pre-existing one above; base was 453/57), ctest -L unit 2408/2408,
spawn_lane_parity RC=0, link_ratchet unchanged at 186, fatal_census RC=0, and G1
pull .text = a52203 with nm --defined-only identical to p7-before/pull-syms.txt
(added=0 removed=0).
289 lines
17 KiB
C++
289 lines
17 KiB
C++
// MobileGL - MobileGL/MG_Backend/DirectVulkan/Renderer/VkBufferManager.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
|
|
|
|
#pragma once
|
|
|
|
#include "BufferArena.h"
|
|
#include "MG_State/GLState/BufferState/BufferObject.h"
|
|
#include "../VkIncludes.h"
|
|
#include <Includes.h>
|
|
#include <vk_mem_alloc.h>
|
|
#if MOBILEGL_BUILD_DISAGGREGATED
|
|
#include "MG_Pipe/MGPipeTypes.h"
|
|
#include <unordered_map>
|
|
#endif
|
|
|
|
namespace MobileGL::MG_Backend::DirectVulkan {
|
|
enum class BufferKind : Uint8 {
|
|
Vertex,
|
|
Index,
|
|
Uniform,
|
|
TextureBuffer,
|
|
ShaderStorage,
|
|
Indirect,
|
|
};
|
|
|
|
struct VkBufferManagerInitInfo {
|
|
VmaAllocator allocator = nullptr;
|
|
Uint32 frameCount = 0;
|
|
VkDeviceSize minUploadBytes = 4 * 1024 * 1024;
|
|
VmaMemoryUsage transientMemoryUsage = VMA_MEMORY_USAGE_AUTO;
|
|
VmaAllocationCreateFlags transientAllocationFlags = VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT;
|
|
Bool transientPersistentMapping = false;
|
|
// VK_EXT_transform_feedback is enabled: persistent-map storage additionally
|
|
// carries the transform feedback usage so capture targets can bind directly.
|
|
Bool transformFeedbackUsageEnabled = false;
|
|
};
|
|
|
|
// The DirectVulkan storage behind one frontend buffer (pipe_resource analogue).
|
|
// Owned (refcounted) by the frontend BufferObject; the manager holds only weak
|
|
// references (for shutdown) plus strong references on deferred-release lists.
|
|
class VkBufferResource : public MG_State::GLState::BackendBufferResource {
|
|
public:
|
|
~VkBufferResource() override = default;
|
|
|
|
// Resident storage (may be invalid for streaming-only buffers).
|
|
VkBufferObject buffer;
|
|
VkDeviceSize storageSize = 0;
|
|
VkBufferUsageFlags usageFlags = 0;
|
|
// Frame serial of the last GPU reference; drives busy tracking.
|
|
Uint64 lastUseSerial = 0;
|
|
// Set when an immediate op could not be applied; forces a full re-upload
|
|
// on the next AcquireResidentSlice.
|
|
Bool pendingFullUpload = false;
|
|
// Backs a zero-copy coherent persistent map (PipeResource GPU residency): the
|
|
// buffer is HOST_VISIBLE+COHERENT, persistently mapped, carries every usage and is
|
|
// never orphaned or recreated. Draw-time acquire binds it directly, no re-upload.
|
|
Bool persistentMapped = false;
|
|
|
|
// Bumped from a manager-wide counter every time anything that decides which
|
|
// BufferSlice an Acquire*Slice call hands back changes: storage created or
|
|
// released, a full re-upload becoming due, a promotion/demotion between
|
|
// resident and streamed storage, or a new per-frame arena slice. Callers that
|
|
// memoise a resolved slice compare this to prove the memo still describes the
|
|
// buffer. The counter is manager-wide (never per-resource) so a freshly
|
|
// created resource - including one that replaces a destroyed resource at the
|
|
// same address - can never reproduce a value some memo already holds. 0 means
|
|
// "no slice has ever been handed out", which no memo can match.
|
|
Uint64 sliceEpoch = 0;
|
|
|
|
// Cached transient (streaming) slice for the current frame.
|
|
BufferSlice transientSlice{};
|
|
Uint64 transientFrameSerial = 0;
|
|
Uint64 transientChangeSerial = 0;
|
|
VkDeviceSize transientSize = 0;
|
|
|
|
// Streaming re-copies the whole store into the per-frame arena on every
|
|
// frame, which is right for genuinely per-frame data but pure waste for a
|
|
// Dynamic-hinted buffer the app stopped touching. After the content
|
|
// survives kStreamedPromotionStreak frame boundaries unchanged it is
|
|
// promoted to resident storage (one final upload, then zero per-frame
|
|
// cost); the first content change demotes it back to streaming, and the
|
|
// streaming path's existing downgrade releases the resident store.
|
|
Uint32 unchangedStreak = 0;
|
|
Bool promotedResident = false;
|
|
Uint64 promotedChangeSerial = 0;
|
|
};
|
|
|
|
// Supplies a command buffer that is recording and outside any render pass,
|
|
// for staged buffer-range copies. Implemented by VulkanRenderer.
|
|
class IBufferCopyCommandProvider {
|
|
public:
|
|
virtual ~IBufferCopyCommandProvider() = default;
|
|
virtual VkCommandBuffer AcquireBufferCopyCommandBuffer() = 0;
|
|
};
|
|
|
|
class VkBufferManager {
|
|
public:
|
|
Bool Initialize(const VkBufferManagerInitInfo& initInfo);
|
|
void Shutdown();
|
|
|
|
#if MOBILEGL_BUILD_DISAGGREGATED
|
|
// Registered before caps publication; the initialized renderer owns the storage.
|
|
static void RegisterWireResourceOps();
|
|
// Transport resources are owned by their complete wire handle, never by a
|
|
// frontend BufferObject. Acquires expose the full GPU store, without a CPU
|
|
// pointer: CPU consumers must use ReadWireBuffer for ordered, current bytes.
|
|
Bool AcquireWireSlice(BufferKind kind, MG_Pipe::MGPipeHandle res, BufferSlice& outSlice);
|
|
Bool ReadWireBuffer(MG_Pipe::MGPipeHandle res, Uint64 offset, Uint64 size, void* dst);
|
|
Bool CopyWireBufferRangeToSlice(MG_Pipe::MGPipeHandle res, Uint64 offset, Uint64 size,
|
|
const BufferSlice& dst);
|
|
// P7 A.1, the sub-word half of the one above: the same copy for a window whose start
|
|
// or end does not land on a four-byte boundary. The read of the APPLICATION's store is
|
|
// rounded OUT to whole words and clamped to the store's end, so the widened window can
|
|
// never touch a byte the application does not own; it lands in a transient staging
|
|
// slice, and only the staging -> dst shift is sub-word - inside our own arena, where an
|
|
// unaligned region cannot alias anything else. vkCmdCopyBuffer places no alignment rule
|
|
// on a region's offsets or size (unlike vkCmdUpdateBuffer / vkCmdFillBuffer), so the
|
|
// shift is a plain legal copy. `dstSkip` is the byte inside `dst` the window starts at.
|
|
// This retires `uniform-buffer-byte-tail`.
|
|
Bool CopyWireBufferSubWordRangeToSlice(MG_Pipe::MGPipeHandle res, Uint64 offset, Uint64 size,
|
|
Uint32 frameIndex, const BufferSlice& dst, Uint64 dstSkip);
|
|
void MarkWireBufferGpuWritten(MG_Pipe::MGPipeHandle res, Uint64 offset, Uint64 size);
|
|
|
|
// Resource-op entry points. All run on the server apply owner.
|
|
void CreateWireBuffer(MG_Pipe::MGPipeHandle res, const MG_Pipe::MGPResourceDesc& desc);
|
|
void RespecifyWireBuffer(MG_Pipe::MGPipeHandle res, const MG_Pipe::MGPResourceDesc& desc,
|
|
const void* initialBytes);
|
|
void WriteWireBuffer(MG_Pipe::MGPipeHandle res, Uint64 offset, Uint64 size, const void* bytes);
|
|
void FlushWireBuffer(MG_Pipe::MGPipeHandle res, Uint64 offset, Uint64 size, const void* bytes);
|
|
void ReadbackWireBuffer(MG_Pipe::MGPipeHandle res, Uint64 offset, Uint64 size);
|
|
void DestroyWireBuffer(MG_Pipe::MGPipeHandle res);
|
|
#endif
|
|
|
|
// Recreate all per-frame transient arenas
|
|
Bool RecreateTransientArenas(Uint32 frameCount);
|
|
void BeginFrame(Uint32 frameIndex);
|
|
// Drains every frame slot's deferred buffer/resource releases. Only valid when
|
|
// the caller has proven every queue submission complete; used by the present-less
|
|
// frame-boundary drain. Deliberately does NOT touch the transient arena's parked
|
|
// superseded blocks: those are still named by this frame's slices (see the
|
|
// definition), and only a frame rewind retires them.
|
|
void CollectAllDeferredReleases();
|
|
// All previously submitted GPU work has completed (vkDeviceWaitIdle).
|
|
void NotifyDeviceIdle();
|
|
// A frame slot's submission fence has been waited: every serial up to
|
|
// and including `serial` is complete. Raises the completed floor so
|
|
// GetCompletedSerial reflects real fence progress instead of only the
|
|
// frameSerial-minus-frameCount inference.
|
|
void NotifyFrameSerialComplete(Uint64 serial);
|
|
void SetCopyCommandProvider(IBufferCopyCommandProvider* provider);
|
|
|
|
Bool UploadTransient(BufferKind kind, Uint32 frameIndex, const void* data, VkDeviceSize size,
|
|
VkDeviceSize alignment, BufferSlice& outSlice);
|
|
|
|
// The descriptor a shader storage block gets when the program declares it and the
|
|
// application bound no buffer at its GL binding point. GL 4.6 core 7.8 makes that a
|
|
// legal state - the block simply has no store, so reads are undefined and writes go
|
|
// nowhere - whereas Vulkan has no such thing as an unwritten descriptor, so something
|
|
// real has to sit in the set or the whole draw/dispatch is lost. One zero-filled
|
|
// buffer, created once and shared by every unbound binding: bindings that are only
|
|
// declared (the case this exists for) never touch it, and one that is actually read
|
|
// sees zeros, which is inside GL's "undefined". robustBufferAccess bounds anything
|
|
// that indexes past it.
|
|
BufferSlice AcquireUnboundStorageDescriptor();
|
|
|
|
// The store a texel-buffer descriptor - `samplerBuffer` or `imageBuffer` - gets when the
|
|
// unit the program's uniform names has no buffer texture on it, or the buffer texture on
|
|
// it has no GL buffer attached. Both are legal GL states that make a fetch return
|
|
// undefined values (GL 4.6 core 8.9: a buffer texture with no attached buffer object is
|
|
// incomplete, and sampling an incomplete texture is undefined - not a lost draw), and both
|
|
// used to take the whole draw or dispatch with them. The VIEW over this - one per format,
|
|
// and the descriptor is a VkBufferView, not a buffer - is built by
|
|
// UniformManager::AcquireUnboundTexelBufferView.
|
|
BufferSlice AcquireUnboundTexelBufferDescriptor();
|
|
|
|
// Draw-time acquire for resident (device-storage) buffers: ensures the
|
|
// resource exists and is fully uploaded, marks it used this frame.
|
|
Bool AcquireResidentSlice(BufferKind kind, const SharedPtr<MG_State::GLState::BufferObject>& bufferObject,
|
|
BufferSlice& outSlice);
|
|
// Draw-time acquire for streamed buffers: uploads the whole shadow into
|
|
// the per-frame arena (cached by change serial), releasing any resident
|
|
// storage the buffer may still own.
|
|
Bool AcquireStreamedSlice(BufferKind kind, const SharedPtr<MG_State::GLState::BufferObject>& bufferObject,
|
|
BufferSlice& outSlice);
|
|
|
|
// Zero-copy persistent map (PipeResource GPU residency): create (once) a
|
|
// HOST_VISIBLE+COHERENT, persistently mapped resident buffer carrying every usage,
|
|
// seed it from the shadow, and return its mapped base for the app to write into
|
|
// directly. Idempotent. Returns nullptr on failure (frontend keeps its shadow).
|
|
void* AcquirePersistentMap(MG_State::GLState::BufferObject& bufferObject);
|
|
|
|
// Immediate ops, dispatched from the frontend BufferBackendOps table.
|
|
void OnRespecify(MG_State::GLState::BufferObject& bufferObject);
|
|
void OnSubData(MG_State::GLState::BufferObject& bufferObject, SizeT offset, SizeT size);
|
|
void OnResidentSubData(MG_State::GLState::BufferObject& bufferObject, SizeT offset, DataPtr data);
|
|
void OnFlushMappedRange(MG_State::GLState::BufferObject& bufferObject, Range1D range,
|
|
Flags<BufferMappingAccessBit> appAccess);
|
|
void OnResourceDestroyed(SharedPtr<MG_State::GLState::BackendBufferResource>&& resource);
|
|
|
|
Uint64 GetFrameSerial() const { return m_frameSerial; }
|
|
// Highest value handed to any VkBufferResource::sliceEpoch. Unchanged since a
|
|
// memo was taken means no buffer this manager owns changed which slice it hands
|
|
// back, and none was persistently mapped, in between - so a memo of resolved
|
|
// slices needs no per-buffer re-check. See AcquirePersistentMap for the mapping half.
|
|
Uint64 GetSliceEpochCounter() const { return m_sliceEpochCounter; }
|
|
// Highest frame serial whose GPU work is known complete; serials at or
|
|
// below it may be considered signaled. Drives IsResourceBusy and the
|
|
// backend GL fence objects.
|
|
Uint64 GetCompletedSerial() const;
|
|
// Busy = potentially referenced by GPU work that has not been fenced yet
|
|
// (including commands recorded for the current, unsubmitted frame).
|
|
Bool IsResourceBusy(const VkBufferResource& resource) const;
|
|
// Hand the manager a buffer to destroy once the frame that recorded commands
|
|
// naming it has completed. The renderer's blit path needs a device-local
|
|
// scratch store for one recorded operation, which cannot be a stack local:
|
|
// the glBlitFramebuffer that records the commands returns long before the
|
|
// command buffer is submitted.
|
|
void DeferRelease(VkBufferObject&& buffer);
|
|
|
|
private:
|
|
#if MOBILEGL_BUILD_DISAGGREGATED
|
|
struct WireBufferResource {
|
|
VkBufferObject buffer;
|
|
Uint64 size = 0;
|
|
Uint64 lastUseSerial = 0;
|
|
Bool gpuWritesPending = false;
|
|
// Only ranges actually submitted by resource_subdata are covered. No
|
|
// shadow is retained: flush cannot replay stale bytes over GPU writes.
|
|
Vector<Range1D> stagedCoverage;
|
|
};
|
|
static Uint64 WireBufferKey(MG_Pipe::MGPipeHandle res) {
|
|
return (static_cast<Uint64>(res.Gen) << 32) | res.Slot;
|
|
}
|
|
WireBufferResource* FindWireBuffer(MG_Pipe::MGPipeHandle res);
|
|
Bool WaitForWireBufferHostAccess(WireBufferResource& resource);
|
|
#endif
|
|
Bool InitializeTransientArenas();
|
|
static VkBufferUsageFlags GetVkBufferUsage(BufferKind kind);
|
|
VkBufferResource* GetOrCreateResource(const SharedPtr<MG_State::GLState::BufferObject>& bufferObject);
|
|
static VkBufferResource* ResourceOf(MG_State::GLState::BufferObject& bufferObject);
|
|
Bool CreateResidentStorage(VkBufferResource& resource, VkDeviceSize size, VkBufferUsageFlags usage,
|
|
VkMemoryPropertyFlags requiredFlags = 0);
|
|
// Swap storage (conditional orphan) and refill it from the shadow copy.
|
|
Bool SwapStorageAndUploadAll(VkBufferResource& resource, MG_State::GLState::BufferObject& bufferObject);
|
|
// Record a staging-slice copy into the resident storage, ordered against
|
|
// in-flight and already-recorded GPU work.
|
|
Bool StagedRangeCopy(VkBufferResource& resource, const void* data,
|
|
SizeT offset, SizeT size);
|
|
#if MOBILEGL_BUILD_DISAGGREGATED
|
|
Bool StagedWireRangeCopy(WireBufferResource& resource, const void* data, SizeT offset, SizeT size);
|
|
#endif
|
|
void CollectDeferredReleases(Uint32 frameIndex);
|
|
void DestroyAllDeferredReleases();
|
|
void TrackLiveResource(const SharedPtr<VkBufferResource>& resource);
|
|
void ReleaseAllLiveResources();
|
|
// See VkBufferResource::sliceEpoch.
|
|
void BumpSliceEpoch(VkBufferResource& resource) { resource.sliceEpoch = ++m_sliceEpochCounter; }
|
|
|
|
VkBufferManagerInitInfo m_initInfo{};
|
|
BufferArena m_transientUploadArena;
|
|
// See AcquireUnboundStorageDescriptor. Lazily created, never re-created, torn down
|
|
// with the manager.
|
|
VkBufferObject m_unboundStorageBuffer;
|
|
// See AcquireUnboundTexelBufferDescriptor. Same lifetime rules.
|
|
VkBufferObject m_unboundTexelBuffer;
|
|
IBufferCopyCommandProvider* m_copyProvider = nullptr;
|
|
Vector<Vector<VkBufferObject>> m_deferredBufferReleases;
|
|
Vector<Vector<SharedPtr<VkBufferResource>>> m_deferredResourceReleases;
|
|
Vector<WeakPtr<VkBufferResource>> m_liveResources;
|
|
#if MOBILEGL_BUILD_DISAGGREGATED
|
|
std::unordered_map<Uint64, WireBufferResource> m_wireBuffers;
|
|
#endif
|
|
// Size m_liveResources had just after the last sweep; the next sweep waits for it to double.
|
|
SizeT m_liveResourcesLastPruned = 0;
|
|
Uint32 m_currentFrameIndex = 0;
|
|
Uint64 m_frameSerial = 1;
|
|
Uint64 m_completedSerialFloor = 0;
|
|
// Never reset (not even by Shutdown): a value handed to a resource must stay
|
|
// unique for the process, or a memo taken before a re-initialize could match
|
|
// a different resource's state after it.
|
|
Uint64 m_sliceEpochCounter = 0;
|
|
};
|
|
} // namespace MobileGL::MG_Backend::DirectVulkan
|