mirror of
https://github.com/gbdk-2020/gbdk-2020.git
synced 2026-03-04 06:24:37 +01:00
304 lines
18 KiB
HTML
304 lines
18 KiB
HTML
<!-- HTML header for doxygen 1.8.14-->
|
||
<!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="cache-control" content="max-age=86400"/>
|
||
<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.20"/>
|
||
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
||
<title>GBDK 2020 Docs: GBDK Toolchain</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="navtree.css" rel="stylesheet" type="text/css"/>
|
||
<script type="text/javascript" src="resize.js"></script>
|
||
<script type="text/javascript" src="navtreedata.js"></script>
|
||
<script type="text/javascript" src="navtree.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" />
|
||
<link href="doxygen_extra.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">GBDK 2020 Docs
|
||
</div>
|
||
<div id="projectbrief">API Documentation for GBDK 2020</div>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
<!-- end header part -->
|
||
<!-- Generated by Doxygen 1.8.20 -->
|
||
<script type="text/javascript">
|
||
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&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&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 -->
|
||
<div id="side-nav" class="ui-resizable side-nav-resizable">
|
||
<div id="nav-tree">
|
||
<div id="nav-tree-contents">
|
||
<div id="nav-sync" class="sync"></div>
|
||
</div>
|
||
</div>
|
||
<div id="splitbar" style="-moz-user-select:none;"
|
||
class="ui-resizable-handle">
|
||
</div>
|
||
</div>
|
||
<script type="text/javascript">
|
||
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
|
||
$(document).ready(function(){initNavTree('docs_toolchain.html',''); initResizable(); });
|
||
/* @license-end */
|
||
</script>
|
||
<div id="doc-content">
|
||
<!-- 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="PageDoc"><div class="header">
|
||
<div class="headertitle">
|
||
<div class="title">GBDK Toolchain </div> </div>
|
||
</div><!--header-->
|
||
<div class="contents">
|
||
<div class="textblock"><p><a class="anchor" id="toolchain_overview"></a></p>
|
||
<h1><a class="anchor" id="autotoc_md72"></a>
|
||
Overview</h1>
|
||
<p>GBDK 2020 uses the SDCC compiler along with some custom tools to build Game Boy ROMs.</p><ul>
|
||
<li>All tools are located under <code>bin/</code></li>
|
||
<li>The typical order of tools called is as follows. (When using lcc these steps are usually performed automatically.)<ol type="1">
|
||
<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>
|
||
<li>Optional: perform auto banking with <a class="el" href="docs_toolchain.html#bankpack">bankpack</a> on the object files</li>
|
||
<li>Link the object files into .ihx file with <a class="el" href="docs_toolchain.html#sdldgb">sdldgb</a></li>
|
||
<li>Validate the .ihx file with <a class="el" href="docs_toolchain.html#ihxcheck">ihxcheck</a></li>
|
||
<li>Convert the .ihx file to a ROM file (.gb, .gbc) with <a class="el" href="docs_toolchain.html#makebin">makebin</a></li>
|
||
</ol>
|
||
</li>
|
||
</ul>
|
||
<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>
|
||
<h1><a class="anchor" id="autotoc_md73"></a>
|
||
Data Types</h1>
|
||
<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>
|
||
<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>
|
||
<p><a class="anchor" id="toolchain_changing_important_addresses"></a> </p>
|
||
<h1><a class="anchor" id="autotoc_md74"></a>
|
||
Changing Important Addresses</h1>
|
||
<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>
|
||
<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>
|
||
<ul>
|
||
<li><code>_shadow_OAM</code><ul>
|
||
<li>Location of sprite ram (requires 0xA0 bytes).</li>
|
||
<li>Default <code>-Wl-g _shadow_OAM=0xC000</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><code>.STACK</code><ul>
|
||
<li>Initial stack address</li>
|
||
<li>Default <code>-Wl-g .STACK=0xE000</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><code>.refresh_OAM</code><ul>
|
||
<li>Address to which the routine for refreshing OAM will be copied (must be in HIRAM). Default</li>
|
||
<li>Default <code>-Wl-g .refresh_OAM=0xFF80</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><code>_DATA</code><ul>
|
||
<li>Start of RAM section (starts after Shadow OAM)</li>
|
||
<li>Default <code>-Wl-b _DATA=0xc0A0</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><code>_CODE</code><ul>
|
||
<li>Start of ROM section</li>
|
||
<li>Default <code>-Wl-b _CODE=0x0200</code></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p><a class="anchor" id="toolchain_compiling_programs"></a></p>
|
||
<h1><a class="anchor" id="autotoc_md75"></a>
|
||
Compiling programs</h1>
|
||
<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>
|
||
<ul>
|
||
<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
|
||
</pre></li>
|
||
<li>Assemble the file 'source.s' and link it producing the Gameboy image 'image.gb' <pre class="fragment">lcc -o image.gb source.s
|
||
</pre></li>
|
||
<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
|
||
</pre></li>
|
||
<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
|
||
</pre></li>
|
||
<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
|
||
</pre></li>
|
||
<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
|
||
</pre></li>
|
||
</ul>
|
||
<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>
|
||
<ul>
|
||
<li>To generate an assembler listing file. <pre class="fragment">-Wa-l
|
||
</pre></li>
|
||
<li>To generate a linker map file. <pre class="fragment">-Wl-m
|
||
</pre></li>
|
||
<li>To bind var to address 'addr' at link time. <pre class="fragment">-Wl-gvar=addr
|
||
</pre></li>
|
||
</ul>
|
||
<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
|
||
</pre><h2><a class="anchor" id="Makefiles"></a>
|
||
Makefiles</h2>
|
||
<p>Using Makefiles</p>
|
||
<p>Please see the sample projects included with GBDK-2020 for a couple different examples of how to use Makefiles.</p>
|
||
<p>You may also want to read a tutorial on Makefiles. For example: <br />
|
||
<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>
|
||
<p><a class="anchor" id="build_tools"></a></p>
|
||
<h1><a class="anchor" id="autotoc_md76"></a>
|
||
Build Tools</h1>
|
||
<p><a class="anchor" id="lcc"></a></p>
|
||
<h2><a class="anchor" id="autotoc_md77"></a>
|
||
lcc</h2>
|
||
<p>lcc is the compiler driver (front end) for the GBDK/sdcc toolchain.</p>
|
||
<p>For detailed settings see <a class="el" href="docs_toolchain_settings.html#lcc-settings">lcc-settings</a></p>
|
||
<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>
|
||
<li>the <code>-v</code> flag can be used to show the exact steps lcc executes for a build</li>
|
||
<li>lcc can compile, link and generate a binary in a single pass: <code>lcc -o somerom.gb somesource.c</code></li>
|
||
<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>
|
||
<li><code>--debug</code> for sdcc (lcc equiv: <code>-Wf-debug</code>)</li>
|
||
<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>
|
||
<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>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p><a class="anchor" id="sdcc"></a></p>
|
||
<h2><a class="anchor" id="autotoc_md78"></a>
|
||
sdcc</h2>
|
||
<p>SDCC C Source compiler</p>
|
||
<p>For detailed settings see <a class="el" href="docs_toolchain_settings.html#sdcc-settings">sdcc-settings</a></p>
|
||
<ul>
|
||
<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>
|
||
</ul>
|
||
<p><a class="anchor" id="sdasgb"></a></p>
|
||
<h2><a class="anchor" id="autotoc_md79"></a>
|
||
sdasgb</h2>
|
||
<p>SDCC Assembler for the gameboy</p>
|
||
<p>For detailed settings see <a class="el" href="docs_toolchain_settings.html#sdasgb-settings">sdasgb-settings</a></p>
|
||
<ul>
|
||
<li>Arguments can be passed to it through <a class="el" href="docs_toolchain.html#lcc">lcc</a> using <code>-Wa-<argument></code></li>
|
||
</ul>
|
||
<p><a class="anchor" id="bankpack"></a></p>
|
||
<h2><a class="anchor" id="autotoc_md80"></a>
|
||
bankpack</h2>
|
||
<p>Automatic Bank packer</p>
|
||
<p>For detailed settings see <a class="el" href="docs_toolchain_settings.html#bankpack-settings">bankpack-settings</a></p>
|
||
<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>
|
||
<li>Can be enabled by using the <code>-autobank</code> argument with <a class="el" href="docs_toolchain.html#lcc">lcc</a>.</li>
|
||
<li>Must be called after compiling/assembling and before linking</li>
|
||
<li>Arguments can be passed to it through <a class="el" href="docs_toolchain.html#lcc">lcc</a> using <code>-Wb-<argument></code></li>
|
||
</ul>
|
||
<p>Limitations</p><ul>
|
||
<li><code>__banked</code> functions cannot be called from within the same source file they are declared in.</li>
|
||
<li>With data it is easier, because if you access data from the code in the same bank you don’t need to switch the bank (access to <code>__bank_*</code> symbol).</li>
|
||
</ul>
|
||
<p><a class="anchor" id="sdldgb"></a></p>
|
||
<h2><a class="anchor" id="autotoc_md81"></a>
|
||
sdldgb</h2>
|
||
<p>The SDCC linker for the gameboy.</p>
|
||
<p>For detailed settings see <a class="el" href="docs_toolchain_settings.html#sdldgb-settings">sdldgb-settings</a></p>
|
||
<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>
|
||
<li>Arguments can be passed to it through <a class="el" href="docs_toolchain.html#lcc">lcc</a> using <code>-Wl-<argument></code></li>
|
||
</ul>
|
||
<p><a class="anchor" id="ihxcheck"></a></p>
|
||
<h2><a class="anchor" id="autotoc_md82"></a>
|
||
ihxcheck</h2>
|
||
<p>IHX file validator</p>
|
||
<p>For detailed settings see <a class="el" href="docs_toolchain_settings.html#ihxcheck-settings">ihxcheck-settings</a></p>
|
||
<p>Checks .ihx files produced by <a class="el" href="docs_toolchain.html#sdldgb">sdldgb</a> for correctness.</p><ul>
|
||
<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>
|
||
<li>Arguments can be passed to it through <a class="el" href="docs_toolchain.html#lcc">lcc</a> using <code>-Wi-<argument></code></li>
|
||
</ul>
|
||
<p><a class="anchor" id="makebin"></a></p>
|
||
<h2><a class="anchor" id="autotoc_md83"></a>
|
||
makebin</h2>
|
||
<p>IHX to ROM converter</p>
|
||
<p>For detailed settings see <a class="el" href="docs_toolchain_settings.html#makebin-settings">makebin-settings</a></p>
|
||
<p>Converts .ihx files produced by <a class="el" href="docs_toolchain.html#sdldgb">sdldgb</a> into ROM files (.gb, .gbc).</p><ul>
|
||
<li>Arguments can be passed to it through <a class="el" href="docs_toolchain.html#lcc">lcc</a> using <code>-Wm-<argument></code></li>
|
||
</ul>
|
||
<p><a class="anchor" id="gbdk_utilities"></a></p>
|
||
<h1><a class="anchor" id="autotoc_md84"></a>
|
||
GBDK Utilities</h1>
|
||
<p><a class="anchor" id="utility_gbcompress"></a></p>
|
||
<h2><a class="anchor" id="autotoc_md85"></a>
|
||
GBCompress</h2>
|
||
<p>Compresssion utility</p>
|
||
<p>For detailed settings see <a class="el" href="docs_toolchain_settings.html#gbcompress-settings">gbcompress-settings</a></p>
|
||
<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="gbdecompress_8h.html#a197fa96ce7ac20d44d0c1a40e38283db">gb_decompress()</a>.</p>
|
||
<p><a class="anchor" id="utility_png2mtspr"></a></p>
|
||
<h2><a class="anchor" id="autotoc_md86"></a>
|
||
PNG to Metasprite</h2>
|
||
<p>Tool for converting PNGs into GBDK format MetaSprites</p>
|
||
<p>Convert single or multiple frames of graphics into metasprite structured data for use with the ...metasprite...() functions.</p>
|
||
<p>For detailed settings see <a class="el" href="docs_toolchain_settings.html#png2mtspr-settings">png2mtspr-settings</a> <br />
|
||
For working with sprite properties (including cgb palettes), see <a class="el" href="metasprites_8h.html#metasprite_and_sprite_properties">metasprite_and_sprite_properties</a> <br />
|
||
For API support see <a class="el" href="metasprites_8h.html#ab994d938fa79cd7265b51953f5485b14">move_metasprite()</a> and related functions in <a class="el" href="metasprites_8h.html">metasprites.h</a> <br />
|
||
</p>
|
||
<h3><a class="anchor" id="autotoc_md87"></a>
|
||
Working with png2mtspr</h3>
|
||
<ul>
|
||
<li>The origin (pivot) for the metasprite is not required to be in the upper left-hand corner as with regular hardware sprites.</li>
|
||
<li>The conversion process supports using both SPRITES_8x8 and SPRITES_8x16 mode. If 8x16 mode is used then the height of the metasprite must be a multiple of 16.</li>
|
||
<li>It will attempt to deduplicate/re-use as many tiles as possible (including ones flipping on the X and Y axis) when building the tile set to be used by the convterted metasprite. This does mean that minor changes to the input graphics may change the numer and order of tiles in the resulting tile set.</li>
|
||
<li>While the tool supports both indexed and full color images as inputs, it only exports as a fixed 3 color + transparent palette per metasprite.<ul>
|
||
<li>The input images are first converted to 32 bit RGBA color, then to greyscale (using <code>255 - ((R * 0.3f) + (G * 0.59f) + (B * 0.11f))</code>) and then to grouped into the 3 colors based on their brightness.</li>
|
||
<li>The brightness mapping is approximately as follows: <pre class="fragment"> Alpha 100% transparent pixels : Transparent
|
||
~78% - ~100% : Lightest/White
|
||
~26% - ~77% : Medium
|
||
0% - ~25% : Darkest/Black
|
||
</pre></li>
|
||
<li>A fixed palette is used for export, the order of colors will get re-arranged to map onto this fixed palette. It is arranged/assumed as follows (An example would be <code>OBP0_REG = 0xE4</code> or <code>=0xE0</code>). <pre class="fragment"> OBP Index 0: Transparent
|
||
OBP Index 1: Lightest/White
|
||
OBP Index 2: Medium
|
||
OBP Index 3: Darkest/Black
|
||
</pre></li>
|
||
<li>If you want to assign different colors then you can either change the settings in <a class="el" href="hardware_8h.html#a13f3e89f7b92258d825292e5058815c7">OBP0_REG</a> / <a class="el" href="hardware_8h.html#a9da545164e049ef773128f869daece13">OBP1_REG</a> in your <em>source code</em> or change the colors of your <em>input image</em> to produce different output, but the output of the png2mtspr tool itself cannot be altered (for now).</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>For best graphics conversion results:</p><ul>
|
||
<li>Input images should only have 3 colors + transparent and which are spaced along the brightness spectrum based on the mapping described above.</li>
|
||
<li>For optimal deduplication, try to align the graphics so that tiles used multiple times align on the same 8 pixel boundaries.</li>
|
||
</ul>
|
||
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000008">Todo:</a></b></dt><dd>Support indexed color (non-remapped) for source images to bypass the brightness binning and palette mapping.</dd></dl>
|
||
</div></div><!-- contents -->
|
||
</div><!-- PageDoc -->
|
||
</div><!-- doc-content -->
|
||
<!-- HTML footer for doxygen 1.8.14-->
|
||
<!-- start footer part -->
|
||
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
|
||
</div>
|
||
</body>
|
||
</html>
|