docs_toolchain.html (21054B)
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 Toolchain</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('docs_toolchain.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="PageDoc"><div class="header"> 89 <div class="headertitle"> 90<div class="title">GBDK Toolchain </div> </div> 91</div><!--header--> 92<div class="contents"> 93<div class="textblock"><p><a class="anchor" id="toolchain_overview"></a></p> 94<h1><a class="anchor" id="autotoc_md95"></a> 95Overview</h1> 96<p>GBDK 2020 uses the SDCC compiler along with some custom tools to build Game Boy ROMs.</p><ul> 97<li>All tools are located under <code>bin/</code></li> 98<li>The typical order of tools called is as follows. (When using lcc these steps are usually performed automatically.)<ol type="1"> 99<li>Compile and assemble source files (.c, .s, .asm) with <a class="el" href="docs_toolchain.html#sdcc">sdcc</a> and <a class="el" href="docs_toolchain.html#sdasgb">sdasgb</a></li> 100<li>Optional: perform auto banking with <a class="el" href="docs_toolchain.html#bankpack">bankpack</a> on the object files</li> 101<li>Link the object files into .ihx file with <a class="el" href="docs_toolchain.html#sdldgb">sdldgb</a></li> 102<li>Validate the .ihx file with <a class="el" href="docs_toolchain.html#ihxcheck">ihxcheck</a></li> 103<li>Convert the .ihx file to a ROM file (.gb, .gbc) with <a class="el" href="docs_toolchain.html#makebin">makebin</a></li> 104</ol> 105</li> 106</ul> 107<p>To see individual arguments and options for a tool, run that tool from the command line with either no arguments or with <code>-h</code>.</p> 108<h1><a class="anchor" id="autotoc_md96"></a> 109Data Types</h1> 110<p>For data types and special C keywords, see <a class="el" href="asm_2gbz80_2types_8h.html#file_asm_gbz80_types_h">asm/gbz80/types.h</a> and <a class="el" href="asm_2types_8h.html#file_asm_types_h">asm/types.h</a>.</p> 111<p>Also see the SDCC manual (scroll down a little on the linked page): <a href="http://sdcc.sourceforge.net/doc/sdccman.pdf#section.1.1">http://sdcc.sourceforge.net/doc/sdccman.pdf#section.1.1</a></p> 112<p><a class="anchor" id="toolchain_changing_important_addresses"></a> </p> 113<h1><a class="anchor" id="autotoc_md97"></a> 114Changing Important Addresses</h1> 115<p>It is possible to change some of the important addresses used by the toolchain at link time using the -Wl-g XXX=YYY and =Wl-b XXX=YYY flags (where XXX is the name of the data, and YYY is the new address).</p> 116<p><a class="el" href="docs_toolchain.html#lcc">lcc</a> will include the following linker defaults for <a class="el" href="docs_toolchain.html#sdldgb">sdldgb</a> if they are not defined by the user.</p> 117<ul> 118<li><code>_shadow_OAM</code><ul> 119<li>Location of sprite ram (requires 0xA0 bytes).</li> 120<li>Default <code>-Wl-g _shadow_OAM=0xC000</code></li> 121</ul> 122</li> 123<li><code>.STACK</code><ul> 124<li>Initial stack address</li> 125<li>Default <code>-Wl-g .STACK=0xE000</code></li> 126</ul> 127</li> 128<li><code>.refresh_OAM</code><ul> 129<li>Address to which the routine for refreshing OAM will be copied (must be in HIRAM). Default</li> 130<li>Default <code>-Wl-g .refresh_OAM=0xFF80</code></li> 131</ul> 132</li> 133<li><code>_DATA</code><ul> 134<li>Start of RAM section (starts after Shadow OAM)</li> 135<li>Default <code>-Wl-b _DATA=0xc0A0</code></li> 136</ul> 137</li> 138<li><code>_CODE</code><ul> 139<li>Start of ROM section</li> 140<li>Default <code>-Wl-b _CODE=0x0200</code></li> 141</ul> 142</li> 143</ul> 144<p><a class="anchor" id="toolchain_compiling_programs"></a></p> 145<h1><a class="anchor" id="autotoc_md98"></a> 146Compiling programs</h1> 147<p>The <a class="el" href="docs_toolchain.html#lcc">lcc</a> program is the front end compiler driver for the actual compiler, assembler and linker. It works out what you want to do based on command line options and the extensions of the files you give it, computes the order in which the various programs must be called and then executes them in order. Some examples are:</p> 148<ul> 149<li>Compile the C source 'source.c', assemble and link it producing the Gameboy image 'image.gb' <pre class="fragment">lcc -o image.gb source.c 150</pre></li> 151<li>Assemble the file 'source.s' and link it producing the Gameboy image 'image.gb' <pre class="fragment">lcc -o image.gb source.s 152</pre></li> 153<li>Compile the C program 'source1.c' and assemble it producing the object file 'object1.o' for later linking. <pre class="fragment">lcc -c -o object1.o source1.c 154</pre></li> 155<li>Assemble the file 'source2.s' producing the object file 'object2.o' for later linking <pre class="fragment">lcc -c -o object2.o source2.s 156</pre></li> 157<li>Link the two object files 'object1.o' and 'object2.o' and produce the Gameboy image 'image.gb' <pre class="fragment">lcc -o image.gb object1.o object2.o 158</pre></li> 159<li>Do all sorts of clever stuff by compiling then assembling source1.c, assembling source2.s and then linking them together to produce image.gb. <pre class="fragment">lcc -o image.gb source1.c source2.s 160</pre></li> 161</ul> 162<p>Arguments to the assembler etc can be passed via lcc using -Wp..., -Wf..., -Wa... and -Wl... to pass options to the pre-processor, compiler, assembler and linker respectivly. Some common options are:</p> 163<ul> 164<li>To generate an assembler listing file. <pre class="fragment">-Wa-l 165</pre></li> 166<li>To generate a linker map file. <pre class="fragment">-Wl-m 167</pre></li> 168<li>To bind var to address 'addr' at link time. <pre class="fragment">-Wl-gvar=addr 169</pre></li> 170</ul> 171<p>For example, to compile the example in the memory section and to generate a listing and map file you would use the following. Note the leading underscore that C adds to symbol names. </p><pre class="fragment">lcc -Wa-l -Wl-m -Wl-g_snd_stat=0xff26 -o image.gb hardware.c 172</pre><h2><a class="anchor" id="Makefiles"></a> 173Makefiles</h2> 174<p>Using Makefiles</p> 175<p>Please see the sample projects included with GBDK-2020 for a couple different examples of how to use Makefiles.</p> 176<p>You may also want to read a tutorial on Makefiles. For example: <br /> 177 <a href="https://makefiletutorial.com/">https://makefiletutorial.com/</a> <a href="https://www.tutorialspoint.com/makefile/index.htm">https://www.tutorialspoint.com/makefile/index.htm</a></p> 178<p><a class="anchor" id="build_tools"></a></p> 179<h1><a class="anchor" id="autotoc_md99"></a> 180Build Tools</h1> 181<p><a class="anchor" id="lcc"></a></p> 182<h2><a class="anchor" id="autotoc_md100"></a> 183lcc</h2> 184<p>lcc is the compiler driver (front end) for the GBDK/sdcc toolchain.</p> 185<p>For detailed settings see <a class="el" href="docs_toolchain_settings.html#lcc-settings">lcc-settings</a></p> 186<p>It can be used to invoke all the tools needed for building a rom. If preferred, the individual tools can be called directly.</p><ul> 187<li>the <code>-v</code> flag can be used to show the exact steps lcc executes for a build</li> 188<li>lcc can compile, link and generate a binary in a single pass: <code>lcc -o somerom.gb somesource.c</code></li> 189<li><a class="anchor" id="lcc_debug"></a> lcc now has a <code>-debug</code> flag that will turn on the following recommended flags for debugging<ul> 190<li><code>--debug</code> for sdcc (lcc equiv: <code>-Wf-debug</code>)</li> 191<li><code>-y</code> enables .cdb output for <a class="el" href="docs_toolchain.html#sdldgb">sdldgb</a> (lcc equiv: <code>-Wl-y</code>)</li> 192<li><code>-j</code> enables .noi output for <a class="el" href="docs_toolchain.html#sdldgb">sdldgb</a> (lcc equiv: <code>-Wl-j</code>)</li> 193</ul> 194</li> 195</ul> 196<p><a class="anchor" id="sdcc"></a></p> 197<h2><a class="anchor" id="autotoc_md101"></a> 198sdcc</h2> 199<p>SDCC C Source compiler</p> 200<p>For detailed settings see <a class="el" href="docs_toolchain_settings.html#sdcc-settings">sdcc-settings</a></p> 201<ul> 202<li>Arguments can be passed to it through <a class="el" href="docs_toolchain.html#lcc">lcc</a> using <code>-Wf-<argument></code> and <code>-Wp-<argument></code> (pre-processor)</li> 203</ul> 204<p><a class="anchor" id="sdasgb"></a></p> 205<h2><a class="anchor" id="autotoc_md102"></a> 206sdasgb</h2> 207<p>SDCC Assembler for the gameboy</p> 208<p>For detailed settings see <a class="el" href="docs_toolchain_settings.html#sdasgb-settings">sdasgb-settings</a></p> 209<ul> 210<li>Arguments can be passed to it through <a class="el" href="docs_toolchain.html#lcc">lcc</a> using <code>-Wa-<argument></code></li> 211</ul> 212<p><a class="anchor" id="bankpack"></a></p> 213<h2><a class="anchor" id="autotoc_md103"></a> 214bankpack</h2> 215<p>Automatic Bank packer</p> 216<p>For detailed settings see <a class="el" href="docs_toolchain_settings.html#bankpack-settings">bankpack-settings</a></p> 217<p>When enabled, automatically assigns banks for object files where bank has been set to <code>255</code>, see <a class="el" href="docs_rombanking_mbcs.html#rom_autobanking">rom_autobanking</a>. Unless an alternative output is specified the given object files are updated with the new bank numbers.</p><ul> 218<li>Can be enabled by using the <code>-autobank</code> argument with <a class="el" href="docs_toolchain.html#lcc">lcc</a>.</li> 219<li>Must be called after compiling/assembling and before linking</li> 220<li>Arguments can be passed to it through <a class="el" href="docs_toolchain.html#lcc">lcc</a> using <code>-Wb-<argument></code></li> 221</ul> 222<p><a class="anchor" id="sdldgb"></a></p> 223<h2><a class="anchor" id="autotoc_md104"></a> 224sdldgb</h2> 225<p>The SDCC linker for the gameboy.</p> 226<p>For detailed settings see <a class="el" href="docs_toolchain_settings.html#sdldgb-settings">sdldgb-settings</a></p> 227<p>Links object files (.o) into a .ihx file which can be processed by <a class="el" href="docs_toolchain.html#makebin">makebin</a></p><ul> 228<li>Arguments can be passed to it through <a class="el" href="docs_toolchain.html#lcc">lcc</a> using <code>-Wl-<argument></code></li> 229</ul> 230<p><a class="anchor" id="ihxcheck"></a></p> 231<h2><a class="anchor" id="autotoc_md105"></a> 232ihxcheck</h2> 233<p>IHX file validator</p> 234<p>For detailed settings see <a class="el" href="docs_toolchain_settings.html#ihxcheck-settings">ihxcheck-settings</a></p> 235<p>Checks .ihx files produced by <a class="el" href="docs_toolchain.html#sdldgb">sdldgb</a> for correctness.</p><ul> 236<li>It will warn if there are multiple writes to the same ROM address. This may indicate mistakes in the code or ROM bank overflows</li> 237<li>Arguments can be passed to it through <a class="el" href="docs_toolchain.html#lcc">lcc</a> using <code>-Wi-<argument></code></li> 238</ul> 239<p><a class="anchor" id="makebin"></a></p> 240<h2><a class="anchor" id="autotoc_md106"></a> 241makebin</h2> 242<p>IHX to ROM converter</p> 243<ul> 244<li>For detailed settings see <a class="el" href="docs_toolchain_settings.html#makebin-settings">makebin-settings</a></li> 245<li>For makebin <code>-yt</code> MBC values see <a class="el" href="docs_rombanking_mbcs.html#setting_mbc_and_rom_ram_banks">setting_mbc_and_rom_ram_banks</a></li> 246</ul> 247<p>Converts .ihx files produced by <a class="el" href="docs_toolchain.html#sdldgb">sdldgb</a> into ROM files (.gb, .gbc). Also used for setting some ROM header data.</p><ul> 248<li>Arguments can be passed to it through <a class="el" href="docs_toolchain.html#lcc">lcc</a> using <code>-Wm-<argument></code></li> 249</ul> 250<p><a class="anchor" id="gbdk_utilities"></a></p> 251<h1><a class="anchor" id="autotoc_md107"></a> 252GBDK Utilities</h1> 253<p><a class="anchor" id="utility_gbcompress"></a></p> 254<h2><a class="anchor" id="autotoc_md108"></a> 255GBCompress</h2> 256<p>Compresssion utility</p> 257<p>For detailed settings see <a class="el" href="docs_toolchain_settings.html#gbcompress-settings">gbcompress-settings</a></p> 258<p>Compresses (and decompresses) binary file data with the gbcompress algorithm (also used in GBTD/GBMB). Decompression support is available in GBDK, see <a class="el" href="gb_2gbdecompress_8h.html#a3370eefd9a88fdefed71eeb92e6861f2">gb_decompress()</a>.</p> 259<p>Can also compress (and decompress) using block style rle encoding with the <code>--alg=rle</code> flag. Decompression support is available in GBDK, see <a class="el" href="rledecompress_8h.html#ad60bf95ddad142d8d81e5e1f0a0bb6e0">rle_decompress()</a>.</p> 260<p><a class="anchor" id="utility_png2asset"></a></p> 261<h2><a class="anchor" id="autotoc_md109"></a> 262png2asset</h2> 263<p>Tool for converting PNGs into GBDK format MetaSprites and Tile Maps</p> 264<ul> 265<li>Convert single or multiple frames of graphics into metasprite structured data for use with the ...metasprite...() functions.</li> 266<li>When <code>-map</code> is used, converts images into Tile Maps and matching Tile Sets</li> 267<li>Supports Game Boy 2bpp, GBC 4bpp, SGB 4bpp, and SMS/GG 4bpp</li> 268</ul> 269<p>For detailed settings see <a class="el" href="docs_toolchain_settings.html#png2asset-settings">png2asset-settings</a> <br /> 270 For working with sprite properties (including cgb palettes), see <a class="el" href="gb_2metasprites_8h.html#metasprite_and_sprite_properties">metasprite_and_sprite_properties</a> <br /> 271 For API support see <a class="el" href="gb_2metasprites_8h.html#a77475e913bf0a19df28bdbf9d1cf392b">move_metasprite()</a> and related functions in <a class="el" href="sms_2metasprites_8h.html">metasprites.h</a> <br /> 272</p> 273<h3><a class="anchor" id="autotoc_md110"></a> 274Working with png2asset</h3> 275<ul> 276<li>The origin (pivot) for the metasprite is not required to be in the upper left-hand corner as with regular hardware sprites. See <code>-px</code> and <code>-py</code>.</li> 277<li>The conversion process supports using both SPRITES_8x8 (<code>-spr8x8</code>) and SPRITES_8x16 mode (<code>-spr8x16</code>). If 8x16 mode is used then the height of the metasprite must be a multiple of 16.</li> 278</ul> 279<h4><a class="anchor" id="autotoc_md111"></a> 280Terminology</h4> 281<p>The following abbreviations are used in this section:</p><ul> 282<li>Original Game Boy and Game Boy Pocket style hardware: <code>DMG</code></li> 283<li>Game Boy Color: <code>CGB</code></li> 284</ul> 285<h4><a class="anchor" id="autotoc_md112"></a> 286Conversion Process</h4> 287<p>png2asset accepts any png as input, although that does not mean any image will be valid. The program will follow the next steps:</p><ul> 288<li>The image will be subdivided into tiles of 8x8 or 8x16</li> 289<li>For each tile a palette will be generated</li> 290<li>If there are more than 4 colors in the palette it will throw an error</li> 291<li>The palette will be sorted from darkest to lightest. If there is a transparent color that will be the first one (this will create a palette that will also work with <code>DMG</code> devices)</li> 292<li>If there are more than 8 palettes the program will throw an error</li> 293</ul> 294<p>With all this, the program will generate a new indexed image (with palette), where each 4 colors define a palette and all colors within a tile can only have colors from one of these palettes</p> 295<p>It is also posible to pass a indexed 8-bit png with the palette properly sorted out, using <code>-keep_palette_order</code></p><ul> 296<li>Palettes will be extracted from the image palette in groups of 4 colors.</li> 297<li>Each tile can only have colors from one of these palettes per tile</li> 298<li>The maximum number of colors is 32</li> 299</ul> 300<p>Using this image a tileset will be created</p><ul> 301<li>Duplicated tiles will be removed</li> 302<li>Tiles will be matched without mirror, using vertical mirror, horizontal mirror or both (use <code>-noflip</code> to turn off matching mirrored tiles)</li> 303<li>The palette won't be taken into account for matching, only the pixel color order, meaning there will be a match between tiles using different palettes but looking identical on grayscale</li> 304</ul> 305<h4><a class="anchor" id="autotoc_md113"></a> 306Maps</h4> 307<p>Passing <code>-map</code> the png can be converted to a map that can be used in both the background and the window. In this case, png2asset will generate:</p><ul> 308<li>The palettes</li> 309<li>The tileset</li> 310<li>The map</li> 311<li>The color info<ul> 312<li>By default, an array of palette index for each tile. This is not the way the hardware works but it takes less space and will create maps compatibles with both <code>DMG</code> and <code>CGB</code> devices.</li> 313<li>Passing <code>-use_map_attributes</code> will create an array of map attributes. It will also add mirroring info for each tile and because of that maps created with this won't be compatible with.<ul> 314<li>Use <code>-noflip</code> to make background maps which are compatible with <code>DMG</code> devices.</li> 315</ul> 316</li> 317</ul> 318</li> 319</ul> 320<h4><a class="anchor" id="autotoc_md114"></a> 321Meta sprites</h4> 322<p>By default the png will be converted to metasprites. The image will be subdivided into meta sprites of <code>-sw</code> x <code>-sh</code>. In this case png2asset will generate:</p><ul> 323<li>The metasprites, containing an array of:<ul> 324<li>tile index</li> 325<li>y offset</li> 326<li>x offset</li> 327<li>flags, containing the mirror info, the palettes for both DMG and GBC and the sprite priority</li> 328</ul> 329</li> 330<li>The metasprites array</li> 331</ul> 332<h4><a class="anchor" id="autotoc_md115"></a> 333Super Game Boy Borders (SGB)</h4> 334<p>Screen border assets for the Super Game Boy can be generated using png2asset.</p> 335<p>The following flags should be used to perform the conversion:</p><ul> 336<li><code><input_border_file.png> -map -bpp 4 -max_palettes 4 -pack_mode sgb -use_map_attributes -c <output_border_data.c></code></li> 337<li>Where <code><input_border_file.png></code> is the image of the SGB border (256x224) and <code><output_border_data.c></code> is the name of the source file to write the assets out to.</li> 338</ul> 339<p>See the <code>sgb_border</code> example project for more details. </p> 340</div></div><!-- contents --> 341</div><!-- PageDoc --> 342</div><!-- doc-content --> 343<!-- HTML footer for doxygen 1.8.14--> 344<!-- start footer part --> 345<div id="nav-path" class="navpath"><!-- id is needed for treeview function! --> 346</div> 347</body> 348</html>