docs: map Vulkan allocator layers and example responsibilities

README.md

@@ -37,6 +37,22 @@ optimal-tiling images within their own class and honor driver requests for
 dedicated memory. Existing `MemType` APIs remain available for short examples;
 new applications should normally use `AllocationOptions`.
 
+## Source map
+
+| File | Responsibility |
+| --- | --- |
+| [memory_policy.v](memory_policy.v) | Memory-type ranking and heap-budget policy |
+| [block_pool.v](block_pool.v) | CPU-only placement, ownership, and resource-class isolation |
+| [vulkan_memory_allocator.v](vulkan_memory_allocator.v) | Vulkan block lifetime, resource creation/binding, mapping, and release |
+| [mapped_memory.v](mapped_memory.v) | Non-coherent flush/invalidate range validation |
+| [upload_ring.v](upload_ring.v) | Persistent staging storage and FIFO slice retirement |
+| [diagnostics.v](diagnostics.v) | Activity counters and bounded lifecycle events |
+
+The root `*_test.v` files exercise policy and bookkeeping with synthetic handles
+or host storage. The three programs under `examples/` exercise the Vulkan driver
+and require a hardware or software device. Use those examples to check resource
+integration in addition to the CPU tests.
+
 ## Install
 ```sh
 v install antono2.vkmemalloc

block_pool.v

@@ -1,3 +1,5 @@
+// Plans aligned suballocations by memory type and resource class without driver calls.
+// Tracks ownership tokens and dedicated blocks using antono2.memory range allocators.
 module vkmemalloc
 
 import antono2.memory

block_pool_stress_test.v

@@ -1,3 +1,5 @@
+// Runs sustained mixed allocation/release workloads across memory blocks.
+// Checks non-overlap, accounting, and per-memory-type invariants after each operation.
 module vkmemalloc
 
 fn assert_block_pool_invariants(pool &MemoryBlockPool, active []BlockReservation, committed u64) {

block_pool_test.v

@@ -1,3 +1,5 @@
+// Checks block selection, alignment, dedicated isolation, and release coalescing.
+// Rejects stale or forged reservations using CPU-only allocation metadata.
 module vkmemalloc
 
 fn test_block_pool_validates_configuration() {

diagnostics.v

@@ -1,3 +1,5 @@
+// Collects allocator activity counters and an optional bounded lifecycle trace.
+// Snapshots describe allocation outcomes and block usage without reserving future capacity.
 module vkmemalloc
 
 import antono2.vulkan as vk

diagnostics_test.v

@@ -1,3 +1,5 @@
+// Checks lifecycle counters and bounded trace retention with synthetic allocations.
+// Also verifies diagnostics when event tracing is disabled.
 module vkmemalloc
 
 import antono2.vulkan as vk

examples/buffer_suballocation/main.v

@@ -1,3 +1,5 @@
+// Runs real Vulkan buffer suballocation and mapped-upload smoke checks.
+// Requires a Vulkan device, including a software implementation such as Lavapipe.
 module main
 
 import antono2.vkmemalloc as vma

examples/image_suballocation/main.v

@@ -1,3 +1,5 @@
+// Exercises real Vulkan image sharing and resource-class isolation.
+// Requires a Vulkan device; checks separate buffer/image blocks and allocator cleanup.
 module main
 
 import antono2.vkmemalloc as vma

examples/stress/main.v

@@ -1,3 +1,5 @@
+// Runs repeated buffer, image, and upload-ring workloads on a Vulkan device.
+// Checks allocation cleanup and diagnostics across sustained resource churn.
 module main
 
 import antono2.vkmemalloc as vma

mapped_memory.v

@@ -1,3 +1,5 @@
+// Normalizes flush/invalidate ranges to Vulkan non-coherent atom boundaries.
+// Validates allocation ownership before issuing mapped-memory operations.
 module vkmemalloc
 
 import antono2.vulkan as vk

mapped_memory_test.v

@@ -1,3 +1,5 @@
+// Checks atom-aligned mapped ranges, bounds rejection, and ownership validation.
+// Uses synthetic allocations for coherent-memory cases that need no driver calls.
 module vkmemalloc
 
 import antono2.vulkan as vk

memory_policy.v

@@ -1,3 +1,5 @@
+// Ranks Vulkan memory types using usage hints, required properties, and heap budgets.
+// Keeps selection policy separate from driver allocation and block reuse.
 module vkmemalloc
 
 import antono2.vulkan as vk

memory_policy_test.v

@@ -1,3 +1,5 @@
+// Checks memory-type ranking and budget behavior with synthetic device properties.
+// Includes reuse of already committed blocks when a heap is over budget.
 module vkmemalloc
 
 import antono2.vulkan as vk

upload_ring.v

@@ -1,3 +1,5 @@
+// Provides persistently mapped staging slices backed by a FIFO range allocator.
+// Callers flush as needed and retire slices only after GPU reads have completed.
 module vkmemalloc
 
 import antono2.memory

upload_ring_test.v

@@ -1,3 +1,5 @@
+// Checks staging-slice alignment, wraparound, FIFO retirement, and ownership.
+// Uses host byte storage instead of a real mapped Vulkan buffer.
 module vkmemalloc
 
 import antono2.memory

vulkan_memory_allocator.v

@@ -1,3 +1,5 @@
+// Owns Vulkan memory blocks and binds buffers and images to tracked allocations.
+// Combines placement policy with block planning; callers synchronize use and resource teardown.
 module vkmemalloc
 
 import antono2.vulkan as vk

vulkan_memory_allocator_test.v

@@ -1,3 +1,5 @@
+// Checks allocator slot reuse, allocation ownership, and resource-class selection.
+// Uses synthetic handles to exercise bookkeeping without creating a Vulkan device.
 module vkmemalloc
 
 import antono2.vulkan as vk