// 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 #include #if MOBILEGL_BUILD_DISAGGREGATED #include "MG_Pipe/MGPipeTypes.h" #include #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& 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& 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 appAccess); void OnResourceDestroyed(SharedPtr&& 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; // P7 wave 2 package B3: the submission expected to carry the most recent GPU use // of this buffer - the busy predicate's DEFENCE term, not its guarantee (see // WriteWireBuffer). IsSubmitIndexComplete polls the real fence and reports an // unsubmitted index as incomplete, but the stamp is taken before the draw is // recorded and a mid-draw flush can submit it without the draw. Uint64 lastUseSubmitIndex = 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 stagedCoverage; }; static Uint64 WireBufferKey(MG_Pipe::MGPipeHandle res) { return (static_cast(res.Gen) << 32) | res.Slot; } WireBufferResource* FindWireBuffer(MG_Pipe::MGPipeHandle res); Bool WaitForWireBufferHostAccess(WireBufferResource& resource); // P7 wave 4 (M2), ID-P7-27: THE WIRE ARM'S ORPHANS NEED A RECLAIM THAT IS NOT A FRAME // BOUNDARY. // // RespecifyWireBuffer - which is every glBufferData that crosses the wire - orphans the // old store unconditionally, because unlike OnRespecify it has no shadow to upload in // place from and no cheap way to know the client is re-sending the same size. The orphan // is legitimate (M1 measured the conditional-orphan mirror: 6701 live against 6702). // What was missing is the RECLAIM. DeferRelease parks into m_deferredBufferReleases, // whose only sweep is CollectDeferredReleases from a frame boundary, and on a pbuffer // replay the server sees ONE present record for the whole run - so on // minecraft-1.21.4-fabric-iris-bsl-esc-menu-854 the buckets held 25,923 dead stores // against 28 live wire buffers, one memfd mapping each, and the server died in scudo's // secondary allocator. // // So a wire store is parked HERE instead, with the facts that say when it is dead, and // THE DEFER PATH ITSELF RECLAIMS - every park sweeps, and the frame boundary is only one // more sweep point (CollectDeferredReleases), never the one this depends on: // // * `lastUseSerial == 0` - read BEFORE RespecifyWireBuffer zeroes it. Zero means no // GPU command has named the store since it was minted or since the last host-access // wait proved every recorded command complete (WaitForWireBufferHostAccess); every // path that hands the store to the GPU stamps m_frameSerial, which starts at 1. Such // a store is destroyed at the park and never enters the list. // * `submitIndex` - the renderer's GetSyncPointSubmitIndex() at park time, which is by // construction the LAST submission that can name this store: every command that // names it was recorded before the park (the record left behind a bumped slice // epoch, so no memo can hand it out again), and a recorded command is either already // submitted (<= m_submitCounter) or in the batch that becomes m_submitCounter + 1. // IsSubmitIndexComplete(submitIndex) is a fence observation, so this is the gate // that empties the set MID-FRAME - the shape CollectWireObjects already uses for // the wire image/view tables. // * THE RENDERER IS IDLE - IsSubmitIndexComplete(GetSyncPointSubmitIndex()): nothing // is recorded and every submission has retired. Then every parked store is dead, // including one tagged for a batch that was abandoned rather than submitted (a // minimized Present drops its recording), whose own index may never complete. // // THE FRAME-SERIAL FLOOR IS DELIBERATELY NOT A PROOF HERE. It cannot move inside a // frame (NotifyFrameSerialComplete refuses the current serial), so it frees nothing in // the one-present replay this exists for, and on this package's base it is the floor // B3 found unsound (a serial with two submissions was declared complete on the first // fence, 6a92a10dd): a free on that floor is a GPU use-after-free, not a wrong pixel. struct DeferredWireRelease { VkBufferObject buffer; Uint64 lastUseSerial = 0; Uint64 submitIndex = 0; // Cached: GetSize() is gone once the object is destroyed, and the watermark's // running total has to stay exact as entries leave. Uint64 bytes = 0; }; // Park a wire store, sweep, then hold the watermark. `lastUseSerial` is the releasing // resource's, captured before the caller resets it. void DeferWireRelease(VkBufferObject&& buffer, Uint64 lastUseSerial); // Destroy every parked store proven dead by the rules above. Returns how many. SizeT SweepDeferredWireReleases(); // MOBILEGL_IPC_WIRE_DEFERRED_MB (Config.h has the semantics): when the parked bytes // still exceed the budget after a sweep, take the sync point WaitForWireBufferHostAccess // takes - flush what is recorded, wait for it - and sweep again, which retires every // parked store, because none can be tagged past the sync point it just waited out. void EnforceWireDeferredWatermark(); // Teardown: the caller has proven the device idle (Shutdown / RecreateTransientArenas). void DestroyAllDeferredWireReleases(); // THE one Fatal{ResourceUnavailable, "buffer-write-sync"} site (rule I: no second abort // for the census to count), shared by the host write that cannot wait for the GPU and // the watermark that cannot. `site` says which. [[noreturn]] static void WireBufferSyncFatal(const char* site); // The wbuf[] gauges (PipeStats.h, Gauge::WireBuffers..WireDeferredSyncs). The peaks are // taken at the two points the numbers can rise - a park and a mint - and published when // the stats channel is on; MagmaWireReclaimScenario reads them off the server's line. void NoteWireStorePeaks(); void PublishWireReclaimGauges(); #endif Bool InitializeTransientArenas(); static VkBufferUsageFlags GetVkBufferUsage(BufferKind kind); VkBufferResource* GetOrCreateResource(const SharedPtr& 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& 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> m_deferredBufferReleases; Vector>> m_deferredResourceReleases; Vector> m_liveResources; #if MOBILEGL_BUILD_DISAGGREGATED std::unordered_map m_wireBuffers; // See DeferredWireRelease. ONE FLAT LIST rather than the per-frame-slot buckets above: // the whole point is that these entries do not wait for a frame slot to come round. Vector m_deferredWireReleases; // Bytes currently parked in that list, kept exact so the watermark needs no walk. Uint64 m_deferredWireBytes = 0; // Live VkBuffers this arm owns: the stores held by m_wireBuffers plus the parked ones. // Maintained rather than counted, because the publish runs on every park. Uint64 m_wireStoreCount = 0; // Run maxima of the two numbers above and the watermark's sync count, for the gauges. Uint64 m_wireStoreCountPeak = 0; Uint64 m_deferredWireBytesPeak = 0; Uint64 m_wireDeferredSyncs = 0; #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