docs/html/debugging_memory_usage.html - external/github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
 <head>
 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
 <meta http-equiv="X-UA-Compatible" content="IE=11"/>
 <meta name="generator" content="Doxygen 1.10.0"/>
 <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"/>
 <script type="text/javascript" src="jquery.js"></script>
 <script type="text/javascript" src="dynsections.js"></script>
 <script type="text/javascript" src="clipboard.js"></script>
 <script type="text/javascript" src="cookie.js"></script>
 <link href="search/search.css" rel="stylesheet" type="text/css"/>
 <script type="text/javascript" src="search/searchdata.js"></script>
 <script type="text/javascript" src="search/search.js"></script>
 <link href="doxygen.css" rel="stylesheet" type="text/css" />
 </head>
 <body>
 <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
 <div id="titlearea">
 <table cellspacing="0" cellpadding="0">
  <tbody>
  <tr id="projectrow">
   <td id="projectalign">
    <div id="projectname">Vulkan Memory Allocator
    </div>
   </td>
  </tr>
  </tbody>
 </table>
 </div>
 <!-- end header part -->
 <!-- Generated by Doxygen 1.10.0 -->
 <script type="text/javascript">
 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
 var searchBox = new SearchBox("searchBox", "search/",'.html');
 /* @license-end */
 </script>
 <script type="text/javascript" src="menudata.js"></script>
 <script type="text/javascript" src="menu.js"></script>
 <script type="text/javascript">
 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
 $(function() {
   initMenu('',true,false,'search.php','Search');
   $(function() { init_search(); });
 });
 /* @license-end */
 </script>
 <div id="main-nav"></div>
 <!-- window showing the filter options -->
 <div id="MSearchSelectWindow"
      onmouseover="return searchBox.OnSearchSelectShow()"
      onmouseout="return searchBox.OnSearchSelectHide()"
      onkeydown="return searchBox.OnSearchSelectKey(event)">
 </div>

 <!-- iframe showing the search results (closed by default) -->
 <div id="MSearchResultsWindow">
 <div id="MSearchResults">
 <div class="SRPage">
 <div id="SRIndex">
 <div id="SRResults"></div>
 <div class="SRStatus" id="Loading">Loading...</div>
 <div class="SRStatus" id="Searching">Searching...</div>
 <div class="SRStatus" id="NoMatches">No Matches</div>
 </div>
 </div>
 </div>
 </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><div class="header">
   <div class="headertitle"><div class="title">Debugging incorrect memory usage</div></div>
 </div><!--header-->
 <div class="contents">
 <div class="textblock"><p>If you suspect a bug with memory usage, like usage of uninitialized memory or memory being overwritten out of bounds of an allocation, you can use debug features of this library to verify this.</p>
 <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;<a class="code" href="vk__mem__alloc_8h.html">vk_mem_alloc.h</a>&quot;</span></div>
 <div class="ttc" id="avk__mem__alloc_8h_html"><div class="ttname"><a href="vk__mem__alloc_8h.html">vk_mem_alloc.h</a></div></div>
 </div><!-- fragment --><p>It makes memory of 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> and with allocations that can be mapped. It works also with dedicated allocations.</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>
 <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 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;<a class="code" href="vk__mem__alloc_8h.html">vk_mem_alloc.h</a>&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>Margins work with all types of memory.</p>
 <p>Margin is applied only to allocations made out of memory blocks and not to dedicated allocations, which have their own memory block of specific size. It is thus not applied to allocations made using <a class="el" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a3fc311d855c2ff53f1090ef5c722b38f" title="Set this flag if the allocation should have its own memory block.">VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT</a> flag or those automatically decided to put into dedicated allocations, e.g. due to its large size or recommended by VK_KHR_dedicated_allocation extension.</p>
 <p>Margins appear in <a class="el" href="statistics.html#statistics_json_dump">JSON dump</a> as part of free space.</p>
 <p>Note that enabling margins increases memory usage and fragmentation.</p>
 <p>Margins do not apply to <a class="el" href="virtual_allocator.html">Virtual allocator</a>.</p>
 <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;<a class="code" href="vk__mem__alloc_8h.html">vk_mem_alloc.h</a>&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) 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 is 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="group__group__alloc.html#ga49329a7f030dafcf82f7b73334c22e98" 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="group__group__alloc.html#gad535935619c7a549bf837e1bb0068f89" 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>
 <h1><a class="anchor" id="debugging_memory_usage_leak_detection"></a>
 Leak detection features</h1>
 <p>At allocation and allocator destruction time VMA checks for unfreed and unmapped blocks using <code>VMA_ASSERT_LEAK()</code>. This macro defaults to an assertion, triggering a typically fatal error in Debug builds, and doing nothing in Release builds. You can provide your own definition of <code>VMA_ASSERT_LEAK()</code> to change this behavior.</p>
 <p>At memory block destruction time VMA lists out all unfreed allocations using the <code>VMA_LEAK_LOG_FORMAT()</code> macro, which defaults to <code>VMA_DEBUG_LOG_FORMAT</code>, which in turn defaults to a no-op. If you're having trouble with leaks - for example, the aforementioned assertion triggers, but you don't quite know <em>why</em> -, overriding this macro to print out the the leaking blocks, combined with assigning individual names to allocations using <a class="el" href="group__group__alloc.html#gabe02cbb0cd913b3f125958179f2020fc" title="Sets pName in given allocation to new value.">vmaSetAllocationName()</a>, can greatly aid in fixing them. </p>
 </div></div><!-- contents -->
 </div><!-- PageDoc -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
 Generated by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.10.0
 </small></address>
 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
	<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
	<head>
	<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
	<meta http-equiv="X-UA-Compatible" content="IE=11"/>
	<meta name="generator" content="Doxygen 1.10.0"/>
	<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"/>
	<script type="text/javascript" src="jquery.js"></script>
	<script type="text/javascript" src="dynsections.js"></script>
	<script type="text/javascript" src="clipboard.js"></script>
	<script type="text/javascript" src="cookie.js"></script>
	<link href="search/search.css" rel="stylesheet" type="text/css"/>
	<script type="text/javascript" src="search/searchdata.js"></script>
	<script type="text/javascript" src="search/search.js"></script>
	<link href="doxygen.css" rel="stylesheet" type="text/css" />
	</head>
	<body>
	<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
	<div id="titlearea">
	<table cellspacing="0" cellpadding="0">
	<tbody>
	<tr id="projectrow">
	<td id="projectalign">
	<div id="projectname">Vulkan Memory Allocator
	</div>
	</td>
	</tr>
	</tbody>
	</table>
	</div>
	<!-- end header part -->
	<!-- Generated by Doxygen 1.10.0 -->
	<script type="text/javascript">
	/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
	var searchBox = new SearchBox("searchBox", "search/",'.html');
	/* @license-end */
	</script>
	<script type="text/javascript" src="menudata.js"></script>
	<script type="text/javascript" src="menu.js"></script>
	<script type="text/javascript">
	/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
	$(function() {
	initMenu('',true,false,'search.php','Search');
	$(function() { init_search(); });
	});
	/* @license-end */
	</script>
	<div id="main-nav"></div>
	<!-- window showing the filter options -->
	<div id="MSearchSelectWindow"
	onmouseover="return searchBox.OnSearchSelectShow()"
	onmouseout="return searchBox.OnSearchSelectHide()"
	onkeydown="return searchBox.OnSearchSelectKey(event)">
	</div>

	<!-- iframe showing the search results (closed by default) -->
	<div id="MSearchResultsWindow">
	<div id="MSearchResults">
	<div class="SRPage">
	<div id="SRIndex">
	<div id="SRResults"></div>
	<div class="SRStatus" id="Loading">Loading...</div>
	<div class="SRStatus" id="Searching">Searching...</div>
	<div class="SRStatus" id="NoMatches">No Matches</div>
	</div>
	</div>
	</div>
	</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><div class="header">
	<div class="headertitle"><div class="title">Debugging incorrect memory usage</div></div>
	</div><!--header-->
	<div class="contents">
	<div class="textblock"><p>If you suspect a bug with memory usage, like usage of uninitialized memory or memory being overwritten out of bounds of an allocation, you can use debug features of this library to verify this.</p>
	<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 "<a class="code" href="vk__mem__alloc_8h.html">vk_mem_alloc.h</a>"</span></div>
	<div class="ttc" id="avk__mem__alloc_8h_html"><div class="ttname"><a href="vk__mem__alloc_8h.html">vk_mem_alloc.h</a></div></div>
	</div><!-- fragment --><p>It makes memory of 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> and with allocations that can be mapped. It works also with dedicated allocations.</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>
	<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 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 "<a class="code" href="vk__mem__alloc_8h.html">vk_mem_alloc.h</a>"</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>Margins work with all types of memory.</p>
	<p>Margin is applied only to allocations made out of memory blocks and not to dedicated allocations, which have their own memory block of specific size. It is thus not applied to allocations made using <a class="el" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a3fc311d855c2ff53f1090ef5c722b38f" title="Set this flag if the allocation should have its own memory block.">VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT</a> flag or those automatically decided to put into dedicated allocations, e.g. due to its large size or recommended by VK_KHR_dedicated_allocation extension.</p>
	<p>Margins appear in <a class="el" href="statistics.html#statistics_json_dump">JSON dump</a> as part of free space.</p>
	<p>Note that enabling margins increases memory usage and fragmentation.</p>
	<p>Margins do not apply to <a class="el" href="virtual_allocator.html">Virtual allocator</a>.</p>
	<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 "<a class="code" href="vk__mem__alloc_8h.html">vk_mem_alloc.h</a>"</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) 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 is 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="group__group__alloc.html#ga49329a7f030dafcf82f7b73334c22e98" 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="group__group__alloc.html#gad535935619c7a549bf837e1bb0068f89" 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>
	<h1><a class="anchor" id="debugging_memory_usage_leak_detection"></a>
	Leak detection features</h1>
	<p>At allocation and allocator destruction time VMA checks for unfreed and unmapped blocks using <code>VMA_ASSERT_LEAK()</code>. This macro defaults to an assertion, triggering a typically fatal error in Debug builds, and doing nothing in Release builds. You can provide your own definition of <code>VMA_ASSERT_LEAK()</code> to change this behavior.</p>
	<p>At memory block destruction time VMA lists out all unfreed allocations using the <code>VMA_LEAK_LOG_FORMAT()</code> macro, which defaults to <code>VMA_DEBUG_LOG_FORMAT</code>, which in turn defaults to a no-op. If you're having trouble with leaks - for example, the aforementioned assertion triggers, but you don't quite know <em>why</em> -, overriding this macro to print out the the leaking blocks, combined with assigning individual names to allocations using <a class="el" href="group__group__alloc.html#gabe02cbb0cd913b3f125958179f2020fc" title="Sets pName in given allocation to new value.">vmaSetAllocationName()</a>, can greatly aid in fixing them. </p>
	</div></div><!-- contents -->
	</div><!-- PageDoc -->
	<!-- start footer part -->
	<hr class="footer"/><address class="footer"><small>
	Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.10.0
	</small></address>
	</body>
	</html>