From 538cd52347094a620599f521d28edde7b622560d Mon Sep 17 00:00:00 2001 From: antono2 Date: Wed, 7 Oct 2026 10:23:51 +0200 Subject: [PATCH] docs: map Vulkan allocator layers and example responsibilities --- README.md | 16 ++++++++++++++++ block_pool.v | 2 ++ block_pool_stress_test.v | 2 ++ block_pool_test.v | 2 ++ diagnostics.v | 2 ++ diagnostics_test.v | 2 ++ examples/buffer_suballocation/main.v | 2 ++ examples/image_suballocation/main.v | 2 ++ examples/stress/main.v | 2 ++ mapped_memory.v | 2 ++ mapped_memory_test.v | 2 ++ memory_policy.v | 2 ++ memory_policy_test.v | 2 ++ upload_ring.v | 2 ++ upload_ring_test.v | 2 ++ vulkan_memory_allocator.v | 2 ++ vulkan_memory_allocator_test.v | 2 ++ 17 files changed, 48 insertions(+) diff --git a/README.md b/README.md index 1fb7a5e..e0f06b4 100644 --- a/README.md +++ b/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 diff --git a/block_pool.v b/block_pool.v index b8b3bea..50f22c4 100644 --- a/block_pool.v +++ b/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 diff --git a/block_pool_stress_test.v b/block_pool_stress_test.v index ab95cae..9fcfb5d 100644 --- a/block_pool_stress_test.v +++ b/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) { diff --git a/block_pool_test.v b/block_pool_test.v index 06e560e..8c82ace 100644 --- a/block_pool_test.v +++ b/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() { diff --git a/diagnostics.v b/diagnostics.v index e769138..626d882 100644 --- a/diagnostics.v +++ b/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 diff --git a/diagnostics_test.v b/diagnostics_test.v index 6181138..cd2bab4 100644 --- a/diagnostics_test.v +++ b/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 diff --git a/examples/buffer_suballocation/main.v b/examples/buffer_suballocation/main.v index 20e6de5..d917369 100644 --- a/examples/buffer_suballocation/main.v +++ b/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 diff --git a/examples/image_suballocation/main.v b/examples/image_suballocation/main.v index 15cfe8b..5c9c03c 100644 --- a/examples/image_suballocation/main.v +++ b/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 diff --git a/examples/stress/main.v b/examples/stress/main.v index 60f9c75..777acf9 100644 --- a/examples/stress/main.v +++ b/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 diff --git a/mapped_memory.v b/mapped_memory.v index 0693074..61dc6b4 100644 --- a/mapped_memory.v +++ b/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 diff --git a/mapped_memory_test.v b/mapped_memory_test.v index 786aa2f..b4303aa 100644 --- a/mapped_memory_test.v +++ b/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 diff --git a/memory_policy.v b/memory_policy.v index 222954f..df96bb3 100644 --- a/memory_policy.v +++ b/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 diff --git a/memory_policy_test.v b/memory_policy_test.v index 8a8fef2..5e11ccb 100644 --- a/memory_policy_test.v +++ b/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 diff --git a/upload_ring.v b/upload_ring.v index c41d1c5..c2156ba 100644 --- a/upload_ring.v +++ b/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 diff --git a/upload_ring_test.v b/upload_ring_test.v index 40230d7..b7315ec 100644 --- a/upload_ring_test.v +++ b/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 diff --git a/vulkan_memory_allocator.v b/vulkan_memory_allocator.v index 8d95f8a..fb58a95 100644 --- a/vulkan_memory_allocator.v +++ b/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 diff --git a/vulkan_memory_allocator_test.v b/vulkan_memory_allocator_test.v index 488c728..c1107e4 100644 --- a/vulkan_memory_allocator_test.v +++ b/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