ref: 17192ea6f07c2697bd87bc28df015a66f6e97fc3
dir: /doc/link.htm/
<!DOCTYPE HTML PUBliC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>xLink</title>
<link rel="stylesheet" type="text/css" href="./style.css">
</head>
<body>
<h1>xLink Documentation</h1>
<h2>Table of Contents</h2>
<ul>
<li><a href="#history"> History</a>
<li><a href="#usage"> Usage</a>
<li><a href="#linkfile"> The Linkfile</a>
<li><a href="#operationtg"> Operation for Gameboy</a>
<li><a href="#smallmode"> Operation for Gameboy small mode</a>
<li><a href="#psion2"> Operation for Psion2 relocatable modules</a>
</ul>
<hr>
<h2 id="history">History</h2>
<table>
<caption>The history of xLink</caption>
<thead>
<tr>
<th scope="col">Version</th>
<th scope="col">Dated</th>
<th scope="col">Release notes</th>
</tr>
</thead>
<tr>
<td>1.0</td>
<td>1 Oct. 96</td>
<td>First release (RGBDS)</td>
</tr>
<tr>
<td>1.01</td>
<td>3 Dec. 96</td>
<td>
<ul>
<li>BANK() didn't work. Fixed.</li>
<li>Sections were quite often output in the wrong order. Fixed.</li>
</ul>
</tr>
<tr>
<td>1.02</td>
<td>12 Feb. 97</td>
<td><a href="#usage">-s switch and mapfile option</A> added</td>
</tr>
<tr>
<td>1.03</td>
<td>23 Mar. 97</td>
<td>
<ul>
<li><a href="#usage">Mapfile</A> now shows BSS, VRAM and HRAM areas</li>
<li>There was a bug regarding <a href="#operation">fixed HOME sections.</a>
</ul></td>
</tr>
<tr>
<td>1.04</td>
<td>03 July 1997</td>
<td>First ASMotor release. Supports big-endian CPUs as well. <a href="#usage">Usage</a> changed to allow for different output fileformats</td>
</tr>
<tr>
<td>1.05</td>
<td>20 July 1997</td>
<td>
<ul>
<li>We can now do range checking on intermediate results in an expression. This is necessary to support different types of CPUs.</li>
<li>RGBLink DIDN’T know about the special PC symbol "@" so if you used it more than once per sourcefile in an expression the linker had to resolve, things would go horribly wrong.</li>
</ul>
</td>
<tr>
<td>1.06</td>
<td>21 September 1997</td>
<td><ul><li>Smart linking and library support added
<li>Program renamed to xLink
</ul>
</td>
</table>
<h2 id="usage">Usage</h2>
<pre> xlink [options] linkfile</pre>
<p>Options are preceded by a hyphen (-) and go as follows:
<pre> h : Short help text
m<b>mapfile</b> : Write a mapfile
t : Output target:
tg : Gameboy <a href="#operationtg">ROM image</a> (default)
ts : Gameboy <a href="#smallmode">Small mode (32kB)</a> ROM image
tp : <a href="#psion2">Psion2</a> relocatable module
z<b>HX</b> : Set the byte value (hex format) used for uninitialised data (default is ? for random)
</pre>
<h2 id="linkfile">The Linkfile</h2>
<p>A linkfile is used to tell <B>xLink</B> which objects to include and what the outputname should be. It is in plain ASCII-format.
<pre> # Linkfile for foobar.gb
[Objects]
foo.obj
bar.obj
[Libraries]
mylib.lib
[Output]
foobar.gb</pre>
<p>A line starting with # is ignored.
<p>If you use libraries they will only be included if one of the objects actually reference them. This works on a SECTION level and not on a module level. This means that when you write libraries you can put each subroutine in its own SECTION so only the relevant bits are included.
<h2 id="operationtg">Operation for Gameboy (-tg)</h2>
<p><a href="asm.htm#sections">Sections</a> created with <b>ROM0</b> in the assembler are placed in the GB bank #0 (the fixed bank $0000-$3FFF) in the order they are loaded from the objectfiles specified in the linkfile. So you want the first file in the linkfile to contain your header. <b>ROMX</b> sections are placed in <em>any bank other than #0</em>. This means you have absolutely <em>no</em> control over which sections goes where. This insures minimal slack (unused bytes) at the end of each bank in the image.
<p>Currently the linker doesn't calculate the GB checksums.
You must use <a href="fix.htm">RGBFix</a> to do this.
<h3 id="smallmode">Operation for Gameboy small mode (-ts)</h3>
<p>Small mode forces all <b>ROMX</b> sections to be of type <b>ROM0</b> and increases the <b>ROM0</b> section size from 16kB to 32kB. This also means that <b>ROM0/ROMX</b> sections are written to the final image in the order you have specified on the command line.
<p>Currently the linker doesn't calculate the GB checksums. You must use <a href="fix.htm">RGBFix</a> to do this.
<hr>
<p>Last updated 08 October 1997 by <a href="mailto:[email protected]">Carsten Sorensen</a></p>
</body>
</html>