wut/group__coreinit__cache.html
2020-03-26 16:49:18 +11:00

427 lines
23 KiB
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">
<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.17"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>wut: Cache</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">wut
&#160;<span id="projectnumber">1.0.0-beta9</span>
</div>
<div id="projectbrief">Wii U Toolchain</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.17 -->
<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');
/* @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:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- 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 class="header">
<div class="summary">
<a href="#func-members">Functions</a> </div>
<div class="headertitle">
<div class="title">Cache<div class="ingroups"><a class="el" href="group__coreinit.html">coreinit</a></div></div> </div>
</div><!--header-->
<div class="contents">
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:ga7c3fc6a7f6dc2765f58683e210af4123"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__coreinit__cache.html#ga7c3fc6a7f6dc2765f58683e210af4123">DCInvalidateRange</a> (void *addr, uint32_t size)</td></tr>
<tr class="memdesc:ga7c3fc6a7f6dc2765f58683e210af4123"><td class="mdescLeft">&#160;</td><td class="mdescRight">Invalidates a range of cached data, in blocks. <a href="group__coreinit__cache.html#ga7c3fc6a7f6dc2765f58683e210af4123">More...</a><br /></td></tr>
<tr class="separator:ga7c3fc6a7f6dc2765f58683e210af4123"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga3189eaf014ed0ec62c6ecfc5f25d658a"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__coreinit__cache.html#ga3189eaf014ed0ec62c6ecfc5f25d658a">DCFlushRange</a> (void *addr, uint32_t size)</td></tr>
<tr class="memdesc:ga3189eaf014ed0ec62c6ecfc5f25d658a"><td class="mdescLeft">&#160;</td><td class="mdescRight">Flushes a range of cached data, in blocks. <a href="group__coreinit__cache.html#ga3189eaf014ed0ec62c6ecfc5f25d658a">More...</a><br /></td></tr>
<tr class="separator:ga3189eaf014ed0ec62c6ecfc5f25d658a"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga9fea18f15291b8f6a3e0f57b7459d8ca"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__coreinit__cache.html#ga9fea18f15291b8f6a3e0f57b7459d8ca">DCStoreRange</a> (void *addr, uint32_t size)</td></tr>
<tr class="memdesc:ga9fea18f15291b8f6a3e0f57b7459d8ca"><td class="mdescLeft">&#160;</td><td class="mdescRight">Stores a range of cached data, in blocks. <a href="group__coreinit__cache.html#ga9fea18f15291b8f6a3e0f57b7459d8ca">More...</a><br /></td></tr>
<tr class="separator:ga9fea18f15291b8f6a3e0f57b7459d8ca"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gac08282add83d813b7a5a857da9e62e48"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__coreinit__cache.html#gac08282add83d813b7a5a857da9e62e48">DCFlushRangeNoSync</a> (void *addr, uint32_t size)</td></tr>
<tr class="memdesc:gac08282add83d813b7a5a857da9e62e48"><td class="mdescLeft">&#160;</td><td class="mdescRight">Similar to <a class="el" href="group__coreinit__cache.html#ga3189eaf014ed0ec62c6ecfc5f25d658a">DCFlushRange</a>, though this function will <em>not</em> run PowerPC <code>sync</code> and <code>eieio</code> instructions after flushing. <a href="group__coreinit__cache.html#gac08282add83d813b7a5a857da9e62e48">More...</a><br /></td></tr>
<tr class="separator:gac08282add83d813b7a5a857da9e62e48"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gafc3075da855050f179b741e2888adb1e"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__coreinit__cache.html#gafc3075da855050f179b741e2888adb1e">DCStoreRangeNoSync</a> (void *addr, uint32_t size)</td></tr>
<tr class="memdesc:gafc3075da855050f179b741e2888adb1e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Similar to <a class="el" href="group__coreinit__cache.html#ga9fea18f15291b8f6a3e0f57b7459d8ca">DCStoreRange</a>, though this function will <em>not</em> run PowerPC <code>sync</code> and <code>eieio</code> instructions after storing. <a href="group__coreinit__cache.html#gafc3075da855050f179b741e2888adb1e">More...</a><br /></td></tr>
<tr class="separator:gafc3075da855050f179b741e2888adb1e"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gaebca39f1de5bbd3b3d46d87894e56b9d"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__coreinit__cache.html#gaebca39f1de5bbd3b3d46d87894e56b9d">DCZeroRange</a> (void *addr, uint32_t size)</td></tr>
<tr class="memdesc:gaebca39f1de5bbd3b3d46d87894e56b9d"><td class="mdescLeft">&#160;</td><td class="mdescRight">Zeroes the given area of the data cache (to the nearest block) with a loop of PowerPC <code>dcbz</code> instructions. <a href="group__coreinit__cache.html#gaebca39f1de5bbd3b3d46d87894e56b9d">More...</a><br /></td></tr>
<tr class="separator:gaebca39f1de5bbd3b3d46d87894e56b9d"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga5dba3ef0e22806579a099412bced0561"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__coreinit__cache.html#ga5dba3ef0e22806579a099412bced0561">DCTouchRange</a> (void *addr, uint32_t size)</td></tr>
<tr class="memdesc:ga5dba3ef0e22806579a099412bced0561"><td class="mdescLeft">&#160;</td><td class="mdescRight">Gives the processor a hint that the given range of memory is likely to be accessed soon, and that performance would be improved if it were cached. <a href="group__coreinit__cache.html#ga5dba3ef0e22806579a099412bced0561">More...</a><br /></td></tr>
<tr class="separator:ga5dba3ef0e22806579a099412bced0561"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga4ec28f7c716274c7197a560d09312a08"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__coreinit__cache.html#ga4ec28f7c716274c7197a560d09312a08">ICInvalidateRange</a> (void *addr, uint32_t size)</td></tr>
<tr class="memdesc:ga4ec28f7c716274c7197a560d09312a08"><td class="mdescLeft">&#160;</td><td class="mdescRight">Invalidates a range of cached instructions, in blocks. <a href="group__coreinit__cache.html#ga4ec28f7c716274c7197a560d09312a08">More...</a><br /></td></tr>
<tr class="separator:ga4ec28f7c716274c7197a560d09312a08"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<p>Interface to the low-level caching system of the PowerPC processor.</p>
<p>The cache acts as a middleman between main memory and the processor, speeding up access to frequently-used data. However, the Wii U is not cache-coherent - written data may be cached without updating main memory, and data read from the cache may be out of date with respect to memory. While this isn't a problem for most code, certain hardware accesses may require manual synchronisation of the cache. This is achieved with coreinit's Cache group of functions.</p>
<p>Since the PowerPC has a seperate cache for data and instructions, any data written with the intent of executing it as instructions requires manual flushing and invalidation of the data and instruction caches. </p>
<h2 class="groupheader">Function Documentation</h2>
<a id="ga7c3fc6a7f6dc2765f58683e210af4123"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga7c3fc6a7f6dc2765f58683e210af4123">&#9670;&nbsp;</a></span>DCInvalidateRange()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void DCInvalidateRange </td>
<td>(</td>
<td class="paramtype">void *&#160;</td>
<td class="paramname"><em>addr</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint32_t&#160;</td>
<td class="paramname"><em>size</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Invalidates a range of cached data, in blocks. </p>
<p>Equivalent to a loop of PowerPC <code>dcbi</code> instructions.</p>
<p>This function forces the next reads from the given address to bypass the the cache and go straight to memory, resulting in slower reads that are guaranteed to reflect main memory.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">addr</td><td>The effective address of the data to invalidate.</td></tr>
<tr><td class="paramname">size</td><td>The size of the range to invalidate. Will be rounded up to the next 0x20.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Unnecessary use of caching functions can have an adverse performance impact. They should only be used when needed while interfacing with hardware. </dd></dl>
</div>
</div>
<a id="ga3189eaf014ed0ec62c6ecfc5f25d658a"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga3189eaf014ed0ec62c6ecfc5f25d658a">&#9670;&nbsp;</a></span>DCFlushRange()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void DCFlushRange </td>
<td>(</td>
<td class="paramtype">void *&#160;</td>
<td class="paramname"><em>addr</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint32_t&#160;</td>
<td class="paramname"><em>size</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Flushes a range of cached data, in blocks. </p>
<p>Equivalent to a loop of PowerPC <code>dcbf</code> instructions, followed by a <code>sync</code> and <code>eieio</code>.</p>
<p>This function flushes any recently cached data into main memory. This allows other hardware in the console to read the data without worry of main memory being outdated. It will also invalidate cached data.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">addr</td><td>The effective address of the data to flush.</td></tr>
<tr><td class="paramname">size</td><td>The size of the range to flush. Will be rounded up to the next 0x20.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Unnecessary use of caching functions can have an adverse performance impact. They should only be used when needed while interfacing with hardware. </dd></dl>
</div>
</div>
<a id="ga9fea18f15291b8f6a3e0f57b7459d8ca"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga9fea18f15291b8f6a3e0f57b7459d8ca">&#9670;&nbsp;</a></span>DCStoreRange()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void DCStoreRange </td>
<td>(</td>
<td class="paramtype">void *&#160;</td>
<td class="paramname"><em>addr</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint32_t&#160;</td>
<td class="paramname"><em>size</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Stores a range of cached data, in blocks. </p>
<p>Equivalent to a loop of PowerPC <code>dcbst</code> instructions, followed by a <code>sync</code> and <code>eieio</code>.</p>
<p>This function writes any recently cached data into main memory. This allows other hardware in the console to read the data without worry of main memory being outdated. This function does <em>not</em> invalidate the cached data.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">addr</td><td>The effective address of the data to store.</td></tr>
<tr><td class="paramname">size</td><td>The size of the range to store. Will be rounded up to the next 0x20.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Unnecessary use of caching functions can have an adverse performance impact. They should only be used when needed while interfacing with hardware. </dd></dl>
</div>
</div>
<a id="gac08282add83d813b7a5a857da9e62e48"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gac08282add83d813b7a5a857da9e62e48">&#9670;&nbsp;</a></span>DCFlushRangeNoSync()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void DCFlushRangeNoSync </td>
<td>(</td>
<td class="paramtype">void *&#160;</td>
<td class="paramname"><em>addr</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint32_t&#160;</td>
<td class="paramname"><em>size</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Similar to <a class="el" href="group__coreinit__cache.html#ga3189eaf014ed0ec62c6ecfc5f25d658a">DCFlushRange</a>, though this function will <em>not</em> run PowerPC <code>sync</code> and <code>eieio</code> instructions after flushing. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">addr</td><td>The effective address of the data to flush.</td></tr>
<tr><td class="paramname">size</td><td>The size of the range to flush. Will be rounded up to the next 0x20.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Unnecessary use of caching functions can have an adverse performance impact. They should only be used when needed while interfacing with hardware. </dd></dl>
</div>
</div>
<a id="gafc3075da855050f179b741e2888adb1e"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gafc3075da855050f179b741e2888adb1e">&#9670;&nbsp;</a></span>DCStoreRangeNoSync()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void DCStoreRangeNoSync </td>
<td>(</td>
<td class="paramtype">void *&#160;</td>
<td class="paramname"><em>addr</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint32_t&#160;</td>
<td class="paramname"><em>size</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Similar to <a class="el" href="group__coreinit__cache.html#ga9fea18f15291b8f6a3e0f57b7459d8ca">DCStoreRange</a>, though this function will <em>not</em> run PowerPC <code>sync</code> and <code>eieio</code> instructions after storing. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">addr</td><td>The effective address of the data to store.</td></tr>
<tr><td class="paramname">size</td><td>The size of the range to store. Will be rounded up to the next 0x20.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Unnecessary use of caching functions can have an adverse performance impact. They should only be used when needed while interfacing with hardware. </dd></dl>
</div>
</div>
<a id="gaebca39f1de5bbd3b3d46d87894e56b9d"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gaebca39f1de5bbd3b3d46d87894e56b9d">&#9670;&nbsp;</a></span>DCZeroRange()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void DCZeroRange </td>
<td>(</td>
<td class="paramtype">void *&#160;</td>
<td class="paramname"><em>addr</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint32_t&#160;</td>
<td class="paramname"><em>size</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Zeroes the given area of the data cache (to the nearest block) with a loop of PowerPC <code>dcbz</code> instructions. </p>
<p>This will not affect main memory immediately, though it will eventually trickle down. Can be combined with <a class="el" href="group__coreinit__cache.html#ga3189eaf014ed0ec62c6ecfc5f25d658a">DCFlushRange</a> or <a class="el" href="group__coreinit__cache.html#ga9fea18f15291b8f6a3e0f57b7459d8ca">DCStoreRange</a> to efficiently set memory to 0.</p>
<dl class="section warning"><dt>Warning</dt><dd>The size of the range passed into this function will be internally rounded up to the next multiple of 0x20. Failing to account for this could result in delayed, hard-to-diagnose memory corruption.</dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">addr</td><td>The effective address of the data to zero.</td></tr>
<tr><td class="paramname">size</td><td>The size of the range to zero. Will be rounded up to the next 0x20. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="ga5dba3ef0e22806579a099412bced0561"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga5dba3ef0e22806579a099412bced0561">&#9670;&nbsp;</a></span>DCTouchRange()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void DCTouchRange </td>
<td>(</td>
<td class="paramtype">void *&#160;</td>
<td class="paramname"><em>addr</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint32_t&#160;</td>
<td class="paramname"><em>size</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Gives the processor a hint that the given range of memory is likely to be accessed soon, and that performance would be improved if it were cached. </p>
<p>The processor does not have to cache the requested area, but it may do so in response to this function. This function is equvalent to a loop of PowerPC <code>dcbt</code> instructions.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">addr</td><td>The effective address of the data to cache.</td></tr>
<tr><td class="paramname">size</td><td>The size of the range to cache. Will be rounded up to the next 0x20. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="ga4ec28f7c716274c7197a560d09312a08"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga4ec28f7c716274c7197a560d09312a08">&#9670;&nbsp;</a></span>ICInvalidateRange()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void ICInvalidateRange </td>
<td>(</td>
<td class="paramtype">void *&#160;</td>
<td class="paramname"><em>addr</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint32_t&#160;</td>
<td class="paramname"><em>size</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Invalidates a range of cached instructions, in blocks. </p>
<p>Equivalent to a loop of PowerPC <code>icbi</code> instructions.</p>
<p>This function forces the next instruction fetches from the given address to bypass the the cache and go straight to memory, resulting in slower fetches that are guaranteed to reflect main memory.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">addr</td><td>The effective address of the instructions to invalidate.</td></tr>
<tr><td class="paramname">size</td><td>The size of the range to invalidate. Will be rounded up to the next 0x20.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Unnecessary use of caching functions can have an adverse performance impact. They should only be used when needed while interfacing with hardware. </dd></dl>
</div>
</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.17
</small></address>
</body>
</html>