AuroraMiddleware/VulkanMemoryAllocator
1
0
Fork 0
mirror of https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator synced 2024-11-05 12:20:07 +00:00
Code Issues Projects Releases Wiki Activity

Added documentation of the whole "Record and replay" feature to Doxygen docs and README.md.

Browse Source
This commit is contained in:
Adam Sawicki 2018-08-21 11:38:32 +02:00
parent 6ea177877a
commit fd64a60957
8 changed files with 268 additions and 120 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
README.md
View File

@ -51,6 +51,7 @@ Additional features:
- JSON dump: Obtain a string in JSON format with detailed map of internal state, including list of allocations and gaps between them.
- Convert this JSON dump into a picture to visualize your memory. See [tools/VmaDumpVis](tools/VmaDumpVis/README.md).
- Debugging incorrect memory usage: Enable initialization of all allocated memory with a bit pattern to detect usage of uninitialized or freed memory. Enable validation of a magic number before and after every allocation to detect out-of-bounds memory corruption.
- Record and replay sequence of calls to library functions to a file to check correctness, measure performance, and gather statistics.
# Prequisites

2
docs/html/general_considerations.html
View File

@ -107,7 +107,7 @@ Allocation algorithm</h1>
Features not supported</h1>
<p>Features deliberately excluded from the scope of this library:</p>
<ul>
<li>Data transfer - issuing commands that transfer data between buffers or images, any usage of <code>VkCommandList</code> or <code>VkCommandQueue</code> and related synchronization is responsibility of the user.</li>
<li>Data transfer - issuing commands that transfer data between buffers or images, any usage of <code>VkCommandList</code> or <code>VkQueue</code> and related synchronization is responsibility of the user.</li>
<li>Allocations for imported/exported external memory. They tend to require explicit memory type index and dedicated allocation anyway, so they don't interact with main features of this library. Such special purpose allocations should be made manually, using <code>vkCreateBuffer()</code> and <code>vkAllocateMemory()</code>.</li>
<li>Support for any programming languages other than C/C++. Bindings to other languages are welcomed as external projects. </li>
</ul>

1
docs/html/index.html
View File

@ -112,6 +112,7 @@ Table of contents</h1>
<li><a class="el" href="debugging_memory_usage.html#debugging_memory_usage_corruption_detection">Corruption detection</a></li>
</ul>
</li>
<li><a class="el" href="record_and_replay.html">Record and replay</a></li>
</ul>
</li>
<li><a class="el" href="usage_patterns.html">Recommended usage patterns</a><ul>

97
docs/html/record_and_replay.html Normal file
View File

@ -0,0 +1,97 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<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.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Vulkan Memory Allocator: Record and replay</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>
<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 style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">Vulkan Memory Allocator
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
</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">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</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="header">
<div class="headertitle">
<div class="title">Record and replay </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="record_and_replay_introduction"></a>
Introduction</h1>
<p>While using the library, sequence of calls to its functions together with their parameters can be recorded to a file and later replayed using standalone player application. It can be useful to:</p>
<ul>
<li>Test correctness - check if same sequence of calls will not cause crash or failures on a target platform.</li>
<li>Gather statistics - see number of allocations, peak memory usage, number of calls etc.</li>
<li>Benchmark performance - see how much time it takes to replay the whole sequence.</li>
</ul>
<h1><a class="anchor" id="record_and_replay_usage"></a>
Usage</h1>
<p><b>To record sequence of calls to a file:</b> Fill in <a class="el" href="struct_vma_allocator_create_info.html#ace2aa4877b16a42b0b7673d4e26000ee" title="Parameters for recording of VMA calls. Can be null. ">VmaAllocatorCreateInfo::pRecordSettings</a> member while creating <a class="el" href="struct_vma_allocator.html" title="Represents main object of this library initialized. ">VmaAllocator</a> object. File is opened and written during whole lifetime of the allocator.</p>
<p><b>To replay file:</b> Use VmaReplay - standalone command-line program. Precompiled binary can be found in "bin" directory. Its source can be found in "src/VmaReplay" directory. Its project is generated by Premake. Command line syntax is printed when the program is launched without parameters. Basic usage: </p><pre class="fragment">VmaReplay.exe MyRecording.csv
</pre><p><b>Documentation of file format</b> can be found in file: "docs/Recording file format.md". It's a human-readable, text file in CSV format (Comma Separated Values).</p>
<h1><a class="anchor" id="record_and_replay_additional_considerations"></a>
Additional considerations</h1>
<ul>
<li>Replaying file that was recorded on a different GPU (with different parameters like <code>bufferImageGranularity</code>, <code>nonCoherentAtomSize</code>, and especially different set of memory heaps and types) may give different performance and memory usage results, as well as issue some warnings and errors.</li>
<li>Current implementation of recording in VMA, as well as VmaReplay application, is coded and tested only on Windows. Inclusion of recording code is driven by <code>VMA_RECORDING_ENABLED</code> macro. Support for other platforms should be easy to add. Contributions are welcomed.</li>
<li>Currently calls to <a class="el" href="vk__mem__alloc_8h.html#a6aced90fcc7b39882b6654a740a0b9bb" title="Compacts memory by moving allocations. ">vmaDefragment()</a> function are not recorded. </li>
</ul>
</div></div><!-- contents -->
<!-- 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.13
</small></address>
</body>
</html>

1
docs/html/search/all_b.js
View File

@ -1,5 +1,6 @@
var searchData=
[
['record_20and_20replay',['Record and replay',['../record_and_replay.html',1,'index']]],
['requiredflags',['requiredFlags',['../struct_vma_allocation_create_info.html#a9166390303ff42d783305bc31c2b6b90',1,'VmaAllocationCreateInfo']]],
['recommended_20usage_20patterns',['Recommended usage patterns',['../usage_patterns.html',1,'index']]]
];

1
docs/html/search/pages_7.js
View File

@ -1,4 +1,5 @@
var searchData=
[
['record_20and_20replay',['Record and replay',['../record_and_replay.html',1,'index']]],
['recommended_20usage_20patterns',['Recommended usage patterns',['../usage_patterns.html',1,'index']]]
];

236
docs/html/vk__mem__alloc_8h_source.html
View File

File diff suppressed because one or more lines are too long

49
src/vk_mem_alloc.h
View File

@ -67,6 +67,7 @@ Documentation of all members: vk_mem_alloc.h
- [Memory initialization](@ref debugging_memory_usage_initialization)
- [Margins](@ref debugging_memory_usage_margins)
- [Corruption detection](@ref debugging_memory_usage_corruption_detection)
- \subpage record_and_replay
- \subpage usage_patterns
- [Simple patterns](@ref usage_patterns_simple)
- [Advanced patterns](@ref usage_patterns_advanced)
@ -920,6 +921,52 @@ Margin validation (corruption detection) works only for memory types that are
`HOST_VISIBLE` and `HOST_COHERENT`.
\page record_and_replay Record and replay
\section record_and_replay_introduction Introduction
While using the library, sequence of calls to its functions together with their
parameters can be recorded to a file and later replayed using standalone player
application. It can be useful to:
- Test correctness - check if same sequence of calls will not cause crash or
failures on a target platform.
- Gather statistics - see number of allocations, peak memory usage, number of
calls etc.
- Benchmark performance - see how much time it takes to replay the whole
sequence.
\section record_and_replay_usage Usage
<b>To record sequence of calls to a file:</b> Fill in
VmaAllocatorCreateInfo::pRecordSettings member while creating #VmaAllocator
object. File is opened and written during whole lifetime of the allocator.
<b>To replay file:</b> Use VmaReplay - standalone command-line program.
Precompiled binary can be found in "bin" directory.
Its source can be found in "src/VmaReplay" directory.
Its project is generated by Premake.
Command line syntax is printed when the program is launched without parameters.
Basic usage:
VmaReplay.exe MyRecording.csv
<b>Documentation of file format</b> can be found in file: "docs/Recording file format.md".
It's a human-readable, text file in CSV format (Comma Separated Values).
\section record_and_replay_additional_considerations Additional considerations
- Replaying file that was recorded on a different GPU (with different parameters
like `bufferImageGranularity`, `nonCoherentAtomSize`, and especially different
set of memory heaps and types) may give different performance and memory usage
results, as well as issue some warnings and errors.
- Current implementation of recording in VMA, as well as VmaReplay application, is
coded and tested only on Windows. Inclusion of recording code is driven by
`VMA_RECORDING_ENABLED` macro. Support for other platforms should be easy to
add. Contributions are welcomed.
- Currently calls to vmaDefragment() function are not recorded.
\page usage_patterns Recommended usage patterns
See also slides from talk:
@ -1198,7 +1245,7 @@ The library uses following algorithm for allocation, in order:
Features deliberately excluded from the scope of this library:
- Data transfer - issuing commands that transfer data between buffers or images, any usage of
`VkCommandList` or `VkCommandQueue` and related synchronization is responsibility of the user.
`VkCommandList` or `VkQueue` and related synchronization is responsibility of the user.
- Allocations for imported/exported external memory. They tend to require
explicit memory type index and dedicated allocation anyway, so they don't
interact with main features of this library. Such special purpose allocations