incbin_8h.html (13630B)
1<!-- HTML header for doxygen 1.8.14--> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4<head> 5<meta http-equiv="cache-control" content="max-age=86400"/> 6<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> 7<meta http-equiv="X-UA-Compatible" content="IE=9"/> 8<meta name="generator" content="Doxygen 1.8.20"/> 9<meta name="viewport" content="width=device-width, initial-scale=1"/> 10<title>GBDK 2020 Docs: gbdk/incbin.h File Reference</title> 11<link href="tabs.css" rel="stylesheet" type="text/css"/> 12<script type="text/javascript" src="jquery.js"></script> 13<script type="text/javascript" src="dynsections.js"></script> 14<link href="navtree.css" rel="stylesheet" type="text/css"/> 15<script type="text/javascript" src="resize.js"></script> 16<script type="text/javascript" src="navtreedata.js"></script> 17<script type="text/javascript" src="navtree.js"></script> 18<link href="search/search.css" rel="stylesheet" type="text/css"/> 19<script type="text/javascript" src="search/searchdata.js"></script> 20<script type="text/javascript" src="search/search.js"></script> 21<link href="doxygen.css" rel="stylesheet" type="text/css" /> 22<link href="doxygen_extra.css" rel="stylesheet" type="text/css"/> 23</head> 24<body> 25<div id="top"><!-- do not remove this div, it is closed by doxygen! --> 26<div id="titlearea"> 27<table cellspacing="0" cellpadding="0"> 28 <tbody> 29 <tr style="height: 56px;"> 30 <td id="projectalign" style="padding-left: 0.5em;"> 31 <div id="projectname">GBDK 2020 Docs 32  <span id="projectnumber">4.0.6</span> 33 </div> 34 <div id="projectbrief">API Documentation for GBDK 2020</div> 35 </td> 36 </tr> 37 </tbody> 38</table> 39</div> 40<!-- end header part --> 41<!-- Generated by Doxygen 1.8.20 --> 42<script type="text/javascript"> 43/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ 44var searchBox = new SearchBox("searchBox", "search",false,'Search'); 45/* @license-end */ 46</script> 47<script type="text/javascript" src="menudata.js"></script> 48<script type="text/javascript" src="menu.js"></script> 49<script type="text/javascript"> 50/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ 51$(function() { 52 initMenu('',true,false,'search.php','Search'); 53 $(document).ready(function() { init_search(); }); 54}); 55/* @license-end */</script> 56<div id="main-nav"></div> 57</div><!-- top --> 58<div id="side-nav" class="ui-resizable side-nav-resizable"> 59 <div id="nav-tree"> 60 <div id="nav-tree-contents"> 61 <div id="nav-sync" class="sync"></div> 62 </div> 63 </div> 64 <div id="splitbar" style="-moz-user-select:none;" 65 class="ui-resizable-handle"> 66 </div> 67</div> 68<script type="text/javascript"> 69/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ 70$(document).ready(function(){initNavTree('incbin_8h.html',''); initResizable(); }); 71/* @license-end */ 72</script> 73<div id="doc-content"> 74<!-- window showing the filter options --> 75<div id="MSearchSelectWindow" 76 onmouseover="return searchBox.OnSearchSelectShow()" 77 onmouseout="return searchBox.OnSearchSelectHide()" 78 onkeydown="return searchBox.OnSearchSelectKey(event)"> 79</div> 80 81<!-- iframe showing the search results (closed by default) --> 82<div id="MSearchResultsWindow"> 83<iframe src="javascript:void(0)" frameborder="0" 84 name="MSearchResults" id="MSearchResults"> 85</iframe> 86</div> 87 88<div class="header"> 89 <div class="summary"> 90<a href="#define-members">Macros</a> </div> 91 <div class="headertitle"> 92<div class="title">incbin.h File Reference</div> </div> 93</div><!--header--> 94<div class="contents"> 95<div class="textblock"><code>#include <<a class="el" href="stdint_8h_source.html">stdint.h</a>></code><br /> 96</div> 97<p><a href="incbin_8h_source.html">Go to the source code of this file.</a></p> 98<table class="memberdecls"> 99<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="define-members"></a> 100Macros</h2></td></tr> 101<tr class="memitem:a51ab79f8ee37368158b1887b65ef97ec"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="incbin_8h.html#a51ab79f8ee37368158b1887b65ef97ec">INCBIN_EXTERN</a>(VARNAME)</td></tr> 102<tr class="separator:a51ab79f8ee37368158b1887b65ef97ec"><td class="memSeparator" colspan="2"> </td></tr> 103<tr class="memitem:aeacb5370285c0d4308d0fe5f29da8d15"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="incbin_8h.html#aeacb5370285c0d4308d0fe5f29da8d15">INCBIN_SIZE</a>(VARNAME)   ( (<a class="el" href="stdint_8h.html#adf4d876453337156dde61095e1f20223">uint16_t</a>) & __size_ ## VARNAME )</td></tr> 104<tr class="separator:aeacb5370285c0d4308d0fe5f29da8d15"><td class="memSeparator" colspan="2"> </td></tr> 105<tr class="memitem:a42705001e2b9897f5167b67fb36c69dd"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="incbin_8h.html#a42705001e2b9897f5167b67fb36c69dd">BANK</a>(VARNAME)   ( (<a class="el" href="stdint_8h.html#aba7bc1797add20fe3efdf37ced1182c5">uint8_t</a>) & __bank_ ## VARNAME )</td></tr> 106<tr class="separator:a42705001e2b9897f5167b67fb36c69dd"><td class="memSeparator" colspan="2"> </td></tr> 107<tr class="memitem:af34047ed60abd6453f819c2a5230cd2b"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="incbin_8h.html#af34047ed60abd6453f819c2a5230cd2b">INCBIN</a>(VARNAME, FILEPATH)</td></tr> 108<tr class="separator:af34047ed60abd6453f819c2a5230cd2b"><td class="memSeparator" colspan="2"> </td></tr> 109</table> 110<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2> 111<div class="textblock"><p>Allows binary data from other files to be included into a C source file.</p> 112<p>It is implemented using asm .incbin and macros.</p> 113<p>See the <code>incbin</code> example project for a demo of how to use it. </p> 114</div><h2 class="groupheader">Macro Definition Documentation</h2> 115<a id="a51ab79f8ee37368158b1887b65ef97ec"></a> 116<h2 class="memtitle"><span class="permalink"><a href="#a51ab79f8ee37368158b1887b65ef97ec">◆ </a></span>INCBIN_EXTERN</h2> 117 118<div class="memitem"> 119<div class="memproto"> 120 <table class="memname"> 121 <tr> 122 <td class="memname">#define INCBIN_EXTERN</td> 123 <td>(</td> 124 <td class="paramtype"> </td> 125 <td class="paramname">VARNAME</td><td>)</td> 126 <td></td> 127 </tr> 128 </table> 129</div><div class="memdoc"> 130<b>Value:</b><div class="fragment"><div class="line"><span class="keyword">extern</span> <span class="keyword">const</span> <a class="code" href="stdint_8h.html#aba7bc1797add20fe3efdf37ced1182c5">uint8_t</a> VARNAME[]; \</div> 131<div class="line">extern <span class="keyword">const</span> <span class="keywordtype">void</span> __size_ ## VARNAME; \</div> 132<div class="line">extern <span class="keyword">const</span> <span class="keywordtype">void</span> __bank_ ## VARNAME;</div> 133</div><!-- fragment --><p>Creates extern entries for accessing a <a class="el" href="incbin_8h.html#af34047ed60abd6453f819c2a5230cd2b">INCBIN()</a> generated variable and it's size in another source file.</p> 134<dl class="params"><dt>Parameters</dt><dd> 135 <table class="params"> 136 <tr><td class="paramname">VARNAME</td><td>Name of the variable used with INCBIN</td></tr> 137 </table> 138 </dd> 139</dl> 140<p>An entry is created for the variable and it's size variable.</p> 141<p><a class="el" href="incbin_8h.html#af34047ed60abd6453f819c2a5230cd2b">INCBIN()</a>, <a class="el" href="incbin_8h.html#aeacb5370285c0d4308d0fe5f29da8d15">INCBIN_SIZE()</a> </p> 142 143</div> 144</div> 145<a id="aeacb5370285c0d4308d0fe5f29da8d15"></a> 146<h2 class="memtitle"><span class="permalink"><a href="#aeacb5370285c0d4308d0fe5f29da8d15">◆ </a></span>INCBIN_SIZE</h2> 147 148<div class="memitem"> 149<div class="memproto"> 150 <table class="memname"> 151 <tr> 152 <td class="memname">#define INCBIN_SIZE</td> 153 <td>(</td> 154 <td class="paramtype"> </td> 155 <td class="paramname">VARNAME</td><td>)</td> 156 <td>   ( (<a class="el" href="stdint_8h.html#adf4d876453337156dde61095e1f20223">uint16_t</a>) & __size_ ## VARNAME )</td> 157 </tr> 158 </table> 159</div><div class="memdoc"> 160<p>Obtains the <b>size in bytes</b> of the <a class="el" href="incbin_8h.html#af34047ed60abd6453f819c2a5230cd2b">INCBIN()</a> generated data</p> 161<dl class="params"><dt>Parameters</dt><dd> 162 <table class="params"> 163 <tr><td class="paramname">VARNAME</td><td>Name of the variable used with INCBIN</td></tr> 164 </table> 165 </dd> 166</dl> 167<p>Requires <a class="el" href="incbin_8h.html#a51ab79f8ee37368158b1887b65ef97ec">INCBIN_EXTERN()</a> to have been called earlier in the source file</p> 168<p><a class="el" href="incbin_8h.html#af34047ed60abd6453f819c2a5230cd2b">INCBIN()</a>, <a class="el" href="incbin_8h.html#a51ab79f8ee37368158b1887b65ef97ec">INCBIN_EXTERN()</a> </p> 169 170</div> 171</div> 172<a id="a42705001e2b9897f5167b67fb36c69dd"></a> 173<h2 class="memtitle"><span class="permalink"><a href="#a42705001e2b9897f5167b67fb36c69dd">◆ </a></span>BANK</h2> 174 175<div class="memitem"> 176<div class="memproto"> 177 <table class="memname"> 178 <tr> 179 <td class="memname">#define BANK</td> 180 <td>(</td> 181 <td class="paramtype"> </td> 182 <td class="paramname">VARNAME</td><td>)</td> 183 <td>   ( (<a class="el" href="stdint_8h.html#aba7bc1797add20fe3efdf37ced1182c5">uint8_t</a>) & __bank_ ## VARNAME )</td> 184 </tr> 185 </table> 186</div><div class="memdoc"> 187<p>Obtains the <b>bank number</b> of the <a class="el" href="incbin_8h.html#af34047ed60abd6453f819c2a5230cd2b">INCBIN()</a> generated data</p> 188<dl class="params"><dt>Parameters</dt><dd> 189 <table class="params"> 190 <tr><td class="paramname">VARNAME</td><td>Name of the variable used with INCBIN</td></tr> 191 </table> 192 </dd> 193</dl> 194<p>Requires <a class="el" href="incbin_8h.html#a51ab79f8ee37368158b1887b65ef97ec">INCBIN_EXTERN()</a> to have been called earlier in the source file</p> 195<p><a class="el" href="incbin_8h.html#af34047ed60abd6453f819c2a5230cd2b">INCBIN()</a>, <a class="el" href="incbin_8h.html#a51ab79f8ee37368158b1887b65ef97ec">INCBIN_EXTERN()</a> </p> 196 197</div> 198</div> 199<a id="af34047ed60abd6453f819c2a5230cd2b"></a> 200<h2 class="memtitle"><span class="permalink"><a href="#af34047ed60abd6453f819c2a5230cd2b">◆ </a></span>INCBIN</h2> 201 202<div class="memitem"> 203<div class="memproto"> 204 <table class="memname"> 205 <tr> 206 <td class="memname">#define INCBIN</td> 207 <td>(</td> 208 <td class="paramtype"> </td> 209 <td class="paramname">VARNAME, </td> 210 </tr> 211 <tr> 212 <td class="paramkey"></td> 213 <td></td> 214 <td class="paramtype"> </td> 215 <td class="paramname">FILEPATH </td> 216 </tr> 217 <tr> 218 <td></td> 219 <td>)</td> 220 <td></td><td></td> 221 </tr> 222 </table> 223</div><div class="memdoc"> 224<b>Value:</b><div class="fragment"><div class="line"><span class="keywordtype">void</span> __func_ ## VARNAME() __banked __naked { \</div> 225<div class="line">__asm \</div> 226<div class="line">_ ## VARNAME:: \</div> 227<div class="line">1$: \</div> 228<div class="line"> .incbin FILEPATH \</div> 229<div class="line">2$: \</div> 230<div class="line"> ___size_ ## VARNAME = (2$-1$) \</div> 231<div class="line"> .globl ___size_ ## VARNAME \</div> 232<div class="line"> .local b___func_ ## VARNAME \</div> 233<div class="line"> ___bank_ ## VARNAME = b___func_ ## VARNAME \</div> 234<div class="line"> .globl ___bank_ ## VARNAME \</div> 235<div class="line">__endasm; \</div> 236<div class="line">}</div> 237</div><!-- fragment --><p>Includes binary data into a C source file</p> 238<dl class="params"><dt>Parameters</dt><dd> 239 <table class="params"> 240 <tr><td class="paramname">VARNAME</td><td>Variable name to use </td></tr> 241 <tr><td class="paramname">FILEPATH</td><td>Path to the file which will be binary included into the C source file</td></tr> 242 </table> 243 </dd> 244</dl> 245<p><b>filepath</b> is relative to the working directory of the tool that is calling it (often a makefile's working directory), <b>NOT</b> to the file it's being included into.</p> 246<p>The variable name is not modified and can be used as-is.</p> 247<dl class="section see"><dt>See also</dt><dd><a class="el" href="incbin_8h.html#aeacb5370285c0d4308d0fe5f29da8d15">INCBIN_SIZE()</a> for obtaining the size of the included data. </dd> 248<dd> 249<a class="el" href="incbin_8h.html#a42705001e2b9897f5167b67fb36c69dd">BANK()</a> for obtaining the bank number of the included data.</dd></dl> 250<p>Use <a class="el" href="incbin_8h.html#a51ab79f8ee37368158b1887b65ef97ec">INCBIN_EXTERN()</a> within another source file to make the variable and it's data accesible there. </p> 251 252</div> 253</div> 254</div><!-- contents --> 255</div><!-- doc-content --> 256<div class="ttc" id="astdint_8h_html_aba7bc1797add20fe3efdf37ced1182c5"><div class="ttname"><a href="stdint_8h.html#aba7bc1797add20fe3efdf37ced1182c5">uint8_t</a></div><div class="ttdeci">unsigned char uint8_t</div><div class="ttdef"><b>Definition:</b> stdint.h:51</div></div> 257<!-- HTML footer for doxygen 1.8.14--> 258<!-- start footer part --> 259<div id="nav-path" class="navpath"><!-- id is needed for treeview function! --> 260</div> 261</body> 262</html>