eden-emu/VulkanMemoryAllocator
14
0
Fork 0
mirror of https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator.git synced 2025-05-15 01:08:31 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Fixes and adjustments for budget, regenerate documentation

Browse source
This commit is contained in:
Adam Sawicki 2019-11-02 15:24:33 +01:00
parent 27c84e2464
commit 48b8a33869
172 changed files with 17358 additions and 1706 deletions
Download patch file Download diff file Expand all files Collapse all files

31
docs/html/debugging_memory_usage.html
View file

@ -3,7 +3,7 @@
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.15"/>
<meta name="generator" content="Doxygen 1.8.16"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Vulkan Memory Allocator: Debugging incorrect memory usage</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
@ -29,7 +29,7 @@
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.15 -->
<!-- Generated by Doxygen 1.8.16 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
@ -59,10 +59,6 @@ $(function() {
</iframe>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="index.html">Vulkan Memory Allocator</a></li> </ul>
</div>
</div><!-- top -->
<div class="PageDoc"><div class="header">
<div class="headertitle">
@ -73,15 +69,19 @@ $(function() {
<h1><a class="anchor" id="debugging_memory_usage_initialization"></a>
Memory initialization</h1>
<p>If you experience a bug with incorrect and nondeterministic data in your program and you suspect uninitialized memory to be used, you can enable automatic memory initialization to verify this. To do it, define macro <code>VMA_DEBUG_INITIALIZE_ALLOCATIONS</code> to 1.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#define VMA_DEBUG_INITIALIZE_ALLOCATIONS 1</span></div><div class="line"><span class="preprocessor">#include &quot;vk_mem_alloc.h&quot;</span></div></div><!-- fragment --><p>It makes memory of all new allocations initialized to bit pattern <code>0xDCDCDCDC</code>. Before an allocation is destroyed, its memory is filled with bit pattern <code>0xEFEFEFEF</code>. Memory is automatically mapped and unmapped if necessary.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#define VMA_DEBUG_INITIALIZE_ALLOCATIONS 1</span></div>
<div class="line"><span class="preprocessor">#include &quot;vk_mem_alloc.h&quot;</span></div>
</div><!-- fragment --><p>It makes memory of all new allocations initialized to bit pattern <code>0xDCDCDCDC</code>. Before an allocation is destroyed, its memory is filled with bit pattern <code>0xEFEFEFEF</code>. Memory is automatically mapped and unmapped if necessary.</p>
<p>If you find these values while debugging your program, good chances are that you incorrectly read Vulkan memory that is allocated but not initialized, or already freed, respectively.</p>
<p>Memory initialization works only with memory types that are <code>HOST_VISIBLE</code>. It works also with dedicated allocations. It doesn't work with allocations created with <a class="el" href="vk__mem__alloc_8h.html#ad9889c10c798b040d59c92f257cae597a5f436af6c8fe8540573a6d22627a6fd2">VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT</a> flag, as they cannot be mapped.</p>
<h1><a class="anchor" id="debugging_memory_usage_margins"></a>
Margins</h1>
<p>By default, allocations are laid out in memory blocks next to each other if possible (considering required alignment, <code>bufferImageGranularity</code>, and <code>nonCoherentAtomSize</code>).</p>
<img src="../gfx/Margins_1.png" alt="Allocations without margin" class="inline"/>
<p><img src="../gfx/Margins_1.png" alt="Allocations without margin" class="inline"/></p>
<p>Define macro <code>VMA_DEBUG_MARGIN</code> to some non-zero value (e.g. 16) to enforce specified number of bytes as a margin before and after every allocation.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#define VMA_DEBUG_MARGIN 16</span></div><div class="line"><span class="preprocessor">#include &quot;vk_mem_alloc.h&quot;</span></div></div><!-- fragment --><img src="../gfx/Margins_2.png" alt="Allocations with margin" class="inline"/>
<div class="fragment"><div class="line"><span class="preprocessor">#define VMA_DEBUG_MARGIN 16</span></div>
<div class="line"><span class="preprocessor">#include &quot;vk_mem_alloc.h&quot;</span></div>
</div><!-- fragment --><p><img src="../gfx/Margins_2.png" alt="Allocations with margin" class="inline"/></p>
<p>If your bug goes away after enabling margins, it means it may be caused by memory being overwritten outside of allocation boundaries. It is not 100% certain though. Change in application behavior may also be caused by different order and distribution of allocations across memory blocks after margins are applied.</p>
<p>The margin is applied also before first and after last allocation in a block. It may occur only once between two adjacent allocations.</p>
<p>Margins work with all types of memory.</p>
@ -91,17 +91,20 @@ Margins</h1>
<h1><a class="anchor" id="debugging_memory_usage_corruption_detection"></a>
Corruption detection</h1>
<p>You can additionally define macro <code>VMA_DEBUG_DETECT_CORRUPTION</code> to 1 to enable validation of contents of the margins.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#define VMA_DEBUG_MARGIN 16</span></div><div class="line"><span class="preprocessor">#define VMA_DEBUG_DETECT_CORRUPTION 1</span></div><div class="line"><span class="preprocessor">#include &quot;vk_mem_alloc.h&quot;</span></div></div><!-- fragment --><p>When this feature is enabled, number of bytes specified as <code>VMA_DEBUG_MARGIN</code> (it must be multiply of 4) before and after every allocation is filled with a magic number. This idea is also know as "canary". Memory is automatically mapped and unmapped if necessary.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#define VMA_DEBUG_MARGIN 16</span></div>
<div class="line"><span class="preprocessor">#define VMA_DEBUG_DETECT_CORRUPTION 1</span></div>
<div class="line"><span class="preprocessor">#include &quot;vk_mem_alloc.h&quot;</span></div>
</div><!-- fragment --><p>When this feature is enabled, number of bytes specified as <code>VMA_DEBUG_MARGIN</code> (it must be multiply of 4) before and after every allocation is filled with a magic number. This idea is also know as "canary". Memory is automatically mapped and unmapped if necessary.</p>
<p>This number is validated automatically when the allocation is destroyed. If it's not equal to the expected value, <code>VMA_ASSERT()</code> is executed. It clearly means that either CPU or GPU overwritten the memory outside of boundaries of the allocation, which indicates a serious bug.</p>
<p>You can also explicitly request checking margins of all allocations in all memory blocks that belong to specified memory types by using function <a class="el" href="vk__mem__alloc_8h.html#a49329a7f030dafcf82f7b73334c22e98" title="Checks magic number in margins around all allocations in given memory types (in both default and cust...">vmaCheckCorruption()</a>, or in memory blocks that belong to specified custom pool, by using function <a class="el" href="vk__mem__alloc_8h.html#ad535935619c7a549bf837e1bb0068f89" title="Checks magic number in margins around all allocations in given memory pool in search for corruptions.">vmaCheckPoolCorruption()</a>.</p>
<p>You can also explicitly request checking margins of all allocations in all memory blocks that belong to specified memory types by using function <a class="el" href="vk__mem__alloc_8h.html#a6e53d9caa4368576cf351300b64ef8f4" title="Checks magic number in margins around all allocations in given memory types (in both default and cust...">vmaCheckCorruption()</a>, or in memory blocks that belong to specified custom pool, by using function <a class="el" href="vk__mem__alloc_8h.html#a6bdc403637fe34c4dbb7f7de39357e02" title="Checks magic number in margins around all allocations in given memory pool in search for corruptions.">vmaCheckPoolCorruption()</a>.</p>
<p>Margin validation (corruption detection) works only for memory types that are <code>HOST_VISIBLE</code> and <code>HOST_COHERENT</code>. </p>
</div></div><!-- PageDoc -->
</div><!-- contents -->
</div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.15
</a> 1.8.16
</small></address>
</body>
</html>