shithub: rgbds

ref: 240fca0861d6924403b39ba8c2752a67137fb45a
dir: /docs/rgblink.5.html/

View raw version
<!DOCTYPE html>
<html>
<!-- This is an automatically generated file.  Do not edit.
   This file is part of RGBDS.
  
   Copyright (c) 2017-2018, Antonio Nino Diaz and RGBDS contributors.
  
   SPDX-License-Identifier: MIT
   -->
<head>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <meta charset="utf-8"/>
  <link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
  <link rel="stylesheet" href="rgbds.css" type="text/css" media="all"/>
  <title>RGBLINK(5)</title>
</head>
<body>
<table class="head">
  <tr>
    <td class="head-ltitle">RGBLINK(5)</td>
    <td class="head-vol">File Formats Manual</td>
    <td class="head-rtitle">RGBLINK(5)</td>
  </tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<code class="Nm">rgblink</code> &#x2014;
<span class="Nd">linker script file format</span>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
The linker script is an external file that allows the user to specify the order
  of sections at link time and in a centralized manner.
<p class="Pp">A linker script consists on a series of banks followed by a list
    of sections and, optionally, commands. They can be lowercase or uppercase,
    it is ignored. Any line can contain a comment starting with
    &#x2018;<code class="Li">;</code>&#x2019; that ends at the end of the
  line:</p>
<div class="Bd Pp Bd-indent">
<pre>
ROMX $F ; This is a comment
  &quot;Functions to read array&quot;
  ALIGN 8
  &quot;Array aligned to 256 bytes&quot;

WRAMX 2
  &quot;Some variables&quot;
</pre>
</div>
<p class="Pp">Numbers can be in decimal or hexadecimal format (the prefix is
    &#x2018;<code class="Li">$</code>&#x2019;). It is an error if any section
    name or command is found before setting a bank.</p>
<p class="Pp">Files can be included by using the <code class="Ic">INCLUDE</code>
    keyword, followed by a string with the path of the file that has to be
    included.</p>
<p class="Pp">The possible bank types are: <code class="Cm">ROM0</code>,
    <code class="Cm">ROMX</code>, <code class="Cm">VRAM</code>,
    <code class="Cm">SRAM</code>, <code class="Cm">WRAM0</code>,
    <code class="Cm">WRAMX</code>, <code class="Cm">OAM</code> and
    <code class="Cm">HRAM</code>. Unless there is a single bank, which can occur
    with types <code class="Cm">ROMX</code>, <code class="Cm">VRAM</code>,
    <code class="Cm">SRAM</code> and <code class="Cm">WRAMX</code>, it is needed
    to specify a bank number after the type.</p>
<p class="Pp">When a new bank statement is found, sections found after it will
    be placed right from the beginning of that bank. If the linker script
    switches to a different bank and then comes back to a previous one, it will
    continue from the last address that was used.</p>
<p class="Pp">The only two commands are <code class="Ic">ORG</code> and
    <code class="Ic">ALIGN</code>:</p>
<ul class="Bl-bullet">
  <li><a class="permalink" href="#ORG"><code class="Ic" id="ORG">ORG</code></a>
      sets the address in which new sections will be placed. It can not be lower
      than the current address.</li>
  <li><a class="permalink" href="#ALIGN"><code class="Ic" id="ALIGN">ALIGN</code></a>
      will increase the address until it is aligned to the specified boundary
      (it tries to set to 0 the number of bits specified after the command:
      &#x2018;<code class="Li">ALIGN 8</code>&#x2019; will align to $100).</li>
</ul>
<p class="Pp"><b class="Sy">Note:</b> The bank, alignment, address and type of
    sections can be specified both in the source code and in the linker script.
    For a section to be able to be placed with the linker script, the bank,
    address and alignment must be left unassigned in the source code or be
    compatible with what is specified in the linker script. For example,
    &#x2018;<code class="Li">ALIGN[8]</code>&#x2019; in the source code is
    compatible with &#x2018;<code class="Li">ORG $F00</code>&#x2019; in the
    linker script.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
  ALSO</a></h1>
<a class="Xr" href="rgbasm.1.html">rgbasm(1)</a>, <a class="Xr" href="rgblink.1.html">rgblink(1)</a>,
  <a class="Xr" href="rgbfix.1.html">rgbfix(1)</a>, <a class="Xr" href="rgbds.5.html">rgbds(5)</a>,
  <a class="Xr" href="rgbds.7.html">rgbds(7)</a>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<code class="Nm">rgblink</code> was originally written by Carsten
  S&#x00F8;rensen as part of the ASMotor package, and was later packaged in
  RGBDS by Justin Lloyd. It is now maintained by a number of contributors at
  <a class="Lk" href="https://github.com/rednex/rgbds">https://github.com/rednex/rgbds</a>.
</section>
</div>
<table class="foot">
  <tr>
    <td class="foot-date">November 26, 2019</td>
    <td class="foot-os">General</td>
  </tr>
</table>
</body>
</html>