ref: 6355d0598b86987a607795e1e083aac2cbc28d10
parent: 1145d1099689a8a65e035756aa1ba726d7816351
author: ISSOtm <[email protected]>
date: Tue Jul 21 19:10:14 EDT 2020
Regenerate docs for 0.4.1
--- a/docs/gbz80.7.html
+++ b/docs/gbz80.7.html
@@ -1064,10 +1064,10 @@
the following <i class="Em">imaginary</i> instructions:
<div class="Bd Pp Bd-indent">
<pre>
+ld f, [sp] ; See below for individual flags
inc sp
ld a, [sp]
inc sp
-ld f, [sp] ; See below for individual flags
</pre>
</div>
<p class="Pp">Cycles: 3</p>
--- a/docs/rgbasm.1.html
+++ b/docs/rgbasm.1.html
@@ -39,6 +39,9 @@
[<code class="Fl"><a href="#g">-g</a></code> <var class="Ar">chars</var>]
[<code class="Fl"><a href="#i">-i</a></code> <var class="Ar">path</var>]
[<code class="Fl"><a href="#M">-M</a></code> <var class="Ar">depend_file</var>]
+ [<code class="Fl"><a href="#M">-M</a><a href="#G">G</a></code>] [<code class="Fl"><a href="#M">-M</a><a href="#P">P</a></code>]
+ [<code class="Fl"><a href="#M">-M</a><a href="#T">T</a></code> <var class="Ar">target_file</var>]
+ [<code class="Fl"><a href="#M">-M</a><a href="#Q">Q</a></code> <var class="Ar">target_file</var>]
[<code class="Fl"><a href="#o">-o</a></code> <var class="Ar">out_file</var>]
[<code class="Fl"><a href="#p">-p</a></code> <var class="Ar">pad_value</var>]
[<code class="Fl"><a href="#r">-r</a></code> <var class="Ar">recursion_depth</var>]
@@ -107,6 +110,35 @@
<var class="Ar">depend_file</var></dt>
<dd>Print <a class="Xr">make(1)</a> dependencies to
<var class="Ar">depend_file</var>.</dd>
+ <dt><a class="permalink" href="#MG"><code class="Fl" id="MG">-MG</code></a></dt>
+ <dd>To be used in conjunction with <code class="Fl">-M</code>. This makes
+ <code class="Nm">rgbasm</code> assume that missing files are
+ auto-generated: when <code class="Ic">INCLUDE</code> or
+ <code class="Ic">INCBIN</code> is attempted on a non-existent file, it is
+ added as a dependency, then <code class="Nm">rgbasm</code> exits normally
+ instead of erroring out. This feature is used in automatic updating of
+ makefiles.</dd>
+ <dt><a class="permalink" href="#MP"><code class="Fl" id="MP">-MP</code></a></dt>
+ <dd>When enabled, this causes a phony target to be added for each dependency
+ other than the main file. This prevents <a class="Xr">make(1)</a> from
+ erroring out when dependency files are deleted.</dd>
+ <dt><a class="permalink" href="#MT"><code class="Fl" id="MT">-MT</code></a>
+ <var class="Ar">target_file</var></dt>
+ <dd>Add a target to the rules emitted by <code class="Fl">-M</code>. The exact
+ string provided will be written, including spaces and special characters.
+ <div class="Bd Bd-indent"><code class="Li"><code class="Fl">-MT</code>
+ <code class="Fl">-fileA</code> <code class="Fl">-MT</code>
+ <code class="Fl">-fileB</code></code></div>
+ is equivalent to
+ <div class="Bd Bd-indent"><code class="Li"><code class="Fl">-MT</code>
+ <code class="Fl">-'fileA</code>
+ <code class="Fl">-fileB'</code>.</code></div>
+ If neither this nor <code class="Fl">-MQ</code> is specified, the output
+ file name is used.</dd>
+ <dt><a class="permalink" href="#MQ"><code class="Fl" id="MQ">-MQ</code></a>
+ <var class="Ar">target_file</var></dt>
+ <dd>Same as <code class="Fl">-MT</code>, but additionally escapes any special
+ <a class="Xr">make(1)</a> characters, essentially ‘$’.</dd>
<dt><a class="permalink" href="#o"><code class="Fl" id="o">-o</code></a>
<var class="Ar">out_file</var>,
<code class="Fl">--output</code>
@@ -200,10 +232,10 @@
<dt><a class="permalink" href="#Wlong-string"><code class="Fl" id="Wlong-string">-Wlong-string</code></a></dt>
<dd>Warn when a string too long to fit in internal buffers is encountered.
This warning is enabled by <code class="Fl">-Wall</code>.</dd>
- <dt><a class="permalink" href="#Wobsolete"><code class="Fl" id="Wobsolete">-Wobsolete</code></a></dt>
+ <dt><a class="permalink" href="#Wno-obsolete"><code class="Fl" id="Wno-obsolete">-Wno-obsolete</code></a></dt>
<dd>Warn when obsolete constructs such as the <code class="Ic">jp [hl]</code>
- instruction or <code class="Ic">HOME</code> section type are encountered.
- This warning is enabled by <code class="Fl">-Wextra</code>.</dd>
+ instruction or <code class="Ic">HOME</code> section type are
+ encountered.</dd>
<dt><a class="permalink" href="#Wshift"><code class="Fl" id="Wshift">-Wshift</code></a></dt>
<dd>Warn when shifting right a negative value. Use a division by 2^N
instead.</dd>
--- a/docs/rgbasm.5.html
+++ b/docs/rgbasm.5.html
@@ -232,7 +232,7 @@
<p class="Pp">Unlike in a lot of languages, and for technical reasons,
<code class="Nm">rgbasm</code> still evaluates both operands of
‘&&’ and ‘||’.</p>
-<p class="Pp">! returns 1 if the operand was 0, and 1 otherwise.</p>
+<p class="Pp">! returns 1 if the operand was 0, and 0 otherwise.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Fixed__u2010_point_Expressions"><a class="permalink" href="#Fixed__u2010_point_Expressions">Fixed‐point
@@ -639,12 +639,9 @@
<var class="Ar">type</var>[<var class="Ar">addr</var>],
<var class="Ar">options</var></code></div>
<p class="Pp"><var class="Ar">name</var> is a string enclosed in double quotes,
- and can be a new name or the name of an existing section. All sections
- assembled at the same time that have the same name are considered to be the
- same section, and their code is put together in the object file generated by
- the assembler. If the type doesn't match, an error occurs. All other
- sections must have a unique name, even in different source files, or the
- linker will treat it as an error.</p>
+ and can be a new name or the name of an existing section. If the type
+ doesn't match, an error occurs. All other sections must have a unique name,
+ even in different source files, or the linker will treat it as an error.</p>
<p class="Pp">Possible section <var class="Ar">type</var>s are as follows:</p>
<dl class="Bl-tag">
<dt><a class="permalink" href="#ROM0"><code class="Ic" id="ROM0">ROM0</code></a></dt>
@@ -703,11 +700,17 @@
<dd>Specify which <var class="Ar">bank</var> for the linker to place the
section in. See above for possible values for <var class="Ar">bank</var>,
depending on <var class="Ar">type</var>.</dd>
- <dt><a class="permalink" href="#ALIGN"><code class="Ic" id="ALIGN">ALIGN</code></a>[<var class="Ar">align</var>]</dt>
+ <dt><a class="permalink" href="#ALIGN"><code class="Ic" id="ALIGN">ALIGN</code></a>[<var class="Ar">align</var>,
+ <var class="Ar">offset</var>]</dt>
<dd>Place the section at an address whose <var class="Ar">align</var>
- least‐significant bits are zero. This option can be used with
- <var class="Ar">addr</var>, as long as they don't contradict
- eachother.</dd>
+ least‐significant bits are equal to <var class="Ar">offset</var>.
+ (Note that <code class="Ic">ALIGN</code>[<var class="Ar">align</var>] is a
+ shorthand for <code class="Ic">ALIGN</code>[<var class="Ar">align</var>,
+ <span class="No">0</span>]). This option can be used with
+ [<var class="Ar">addr</var>], as long as they don't contradict eachother.
+ It's also possible to request alignment in the middle of a section, see
+ <a class="Sx" href="#Requesting_alignment">Requesting alignment</a>
+ below.</dd>
</dl>
<p class="Pp">If [<var class="Ar">addr</var>] is not specified, the section is
considered “floating”; the linker will automatically calculate
@@ -724,7 +727,7 @@
<li>
<div class="Bd Pp Bd-indent">
<pre>
-SECTION "CoolStuff",ROMX
+SECTION "Cool Stuff",ROMX
</pre>
</div>
This switches to the section called “CoolStuff”, creating it
@@ -733,7 +736,7 @@
<li>If it is needed, the the base address of the section can be specified:
<div class="Bd Pp Bd-indent">
<pre>
-SECTION "CoolStuff",ROMX[$4567]
+SECTION "Cool Stuff",ROMX[$4567]
</pre>
</div>
</li>
@@ -740,7 +743,7 @@
<li>An example with a fixed bank:
<div class="Bd Pp Bd-indent">
<pre>
-SECTION "CoolStuff",ROMX[$4567],BANK[3]
+SECTION "Cool Stuff",ROMX[$4567],BANK[3]
</pre>
</div>
</li>
@@ -748,7 +751,7 @@
within the bank, that's also possible:
<div class="Bd Pp Bd-indent">
<pre>
-SECTION "CoolStuff",ROMX,BANK[7]
+SECTION "Cool Stuff",ROMX,BANK[7]
</pre>
</div>
</li>
@@ -848,7 +851,8 @@
several times per <code class="Nm">rgbasm</code> invocation, and across
several invocations. Different declarations are treated and merged
identically whether within the same invocation, or different ones.</li>
- <li>A section cannot be declared both as unionized or non-unionized.</li>
+ <li>If one section has been declared as unionized, all sections with the same
+ name must be declared unionized as well.</li>
<li>All declarations must have the same type. For example, even if
<a class="Xr" href="rgblink.1.html">rgblink(1)</a>'s <code class="Fl">-w</code> flag is used,
<code class="Ic">WRAM0</code> and <code class="Ic">WRAMX</code> types are
@@ -865,7 +869,44 @@
<a class="Sx" href="#Unions">Unions</a>. Similarly, the size of an unionized
section is the largest of all its declarations.</p>
</section>
+<section class="Ss">
+<h2 class="Ss" id="Section_Fragments"><a class="permalink" href="#Section_Fragments">Section
+ Fragments</a></h2>
+Section fragments are sections with a small twist: when several of the same name
+ are encountered, they are concatenated instead of producing an error. This
+ works within the same file (paralleling the behavior "plain"
+ sections has in previous versions), but also across object files. However,
+ similarly to <a class="Sx" href="#Unionized_Sections">Unionized Sections</a>,
+ some rules must be followed:
+<ul class="Bl-bullet Bd-indent">
+ <li>If one section has been declared as fragment, all sections with the same
+ name must be declared fragments as well.</li>
+ <li>All declarations must have the same type. For example, even if
+ <a class="Xr" href="rgblink.1.html">rgblink(1)</a>'s <code class="Fl">-w</code> flag is used,
+ <code class="Ic">WRAM0</code> and <code class="Ic">WRAMX</code> types are
+ still considered different.</li>
+ <li>Different constraints (alignment, bank, etc.) can be specified for each
+ unionized section declaration, but they must all be compatible. For
+ example, alignment must be compatible with any fixed address, all
+ specified banks must be the same, etc.</li>
+ <li>A section fragment may not be unionized; after all, that wouldn't make
+ much sense.</li>
+</ul>
+<p class="Pp">When RGBASM merges two fragments, the one encountered later is
+ appended to the one encountered earlier.</p>
+<p class="Pp">When RGBLINK merges two fragments, the one whose file was
+ specified last is appended to the one whose file was specified first. For
+ example, assuming ‘<code class="Li">bar.o</code>’,
+ ‘<code class="Li">baz.o</code>’, and
+ ‘<code class="Li">foo.o</code>’ all contain a fragment with
+ the same name, the command</p>
+<div class="Bd Bd-indent"><code class="Li">rgblink -o rom.gb baz.o foo.o
+ bar.o</code></div>
+would produce the fragment from ‘<code class="Li">baz.o</code>’
+ first, followed by the one from ‘<code class="Li">foo.o</code>’,
+ and the one from ‘<code class="Li">bar.o</code>’ last.
</section>
+</section>
<section class="Sh">
<h1 class="Sh" id="SYMBOLS"><a class="permalink" href="#SYMBOLS">SYMBOLS</a></h1>
RGBDS supports several types of symbols:
@@ -919,6 +960,8 @@
‘<code class="Li">.local:</code>’. If the former notation
is used, then ‘<code class="Li">scope</code>’ must be the
actual current scope.</p>
+ <p class="Pp">Local labels may have whitespace before their declaration as
+ the only exception to the rule.</p>
<p class="Pp">A label's location (and thus value) is usually not determined
until the linking stage, so labels usually cannot be used as constants.
However, if the section in which the label is declared has a fixed base
@@ -1664,6 +1707,23 @@
destroy the options set by the program that included your file. The stack's
number of entries is limited only by the amount of memory in your
machine.</p>
+</section>
+<section class="Ss">
+<h2 class="Ss" id="Requesting_alignment"><a class="permalink" href="#Requesting_alignment">Requesting
+ alignment</a></h2>
+While <code class="Ic">ALIGN</code> as presented in
+ <a class="Sx" href="#SECTIONS">SECTIONS</a> is often useful as-is, sometimes
+ you instead want a particular piece of data (or code) in the middle of the
+ section to be aligned. This is made easier through the use of mid-section
+ <code class="Ic">align</code> <var class="Ar">align</var>,
+ <var class="Ar">offset</var>. It will alter the section's attributes to ensure
+ that the location the <code class="Ic">align</code> directive is at, has its
+ <var class="Ar">align</var> lower bits equal to <var class="Ar">offset</var>.
+<p class="Pp">If the constraint cannot be met (for example because the section
+ is fixed at an incompatible address), and error is produced. Note that
+ <code class="Ic">align</code> <var class="Ar">align</var> is a shorthand for
+ <code class="Ic">align</code> <var class="Ar">align</var>,
+ <span class="No">0</span>.</p>
</section>
</section>
<section class="Sh">
--- a/docs/rgbds.5.html
+++ b/docs/rgbds.5.html
@@ -107,9 +107,11 @@
; decide (floating bank). This field is only valid for ROMX,
; VRAM, WRAMX and SRAM sections.
- LONG Align ; Alignment of this section, expressed as 1 << align. 1 if
- ; not specified.
+ BYTE Align ; Alignment of this section, as N bits. 0 when not specified.
+ LONG Ofs ; Offset relative to the alignment specified above.
+ ; Must be below 1 << Align.
+
IF (Type == ROMX) || (Type == ROM0) ; Sections that can contain data.
BYTE Data[Size] ; Raw data of the section.
@@ -116,8 +118,6 @@
LONG NumberOfPatches ; Number of patches to apply.
- ; These types of sections may have patches
-
REPT NumberOfPatches
STRING SourceFile ; Name of the source file (for printing error
@@ -126,6 +126,16 @@
LONG Offset ; Offset into the section where patch should
; be applied (in bytes).
+ LONG PCSectionID ; Index within the file of the section in which
+ ; PC is located.
+ ; This is usually the same section that the
+ ; patch should be applied into, except e.g.
+ ; with LOAD blocks.
+
+ LONG PCOffset ; PC's offset into the above section.
+ ; Used because the section may be floating, so
+ ; PC's value is not known to RGBASM.
+
BYTE Type ; 0 = BYTE patch.
; 1 = little endian WORD patch.
; 2 = little endian LONG patch.
@@ -152,6 +162,13 @@
LONG Offset ; Offset into the section where the assertion is located.
+ LONG SectionID ; Index within the file of the section in which PC is
+ ; located, or -1 if defined outside a section.
+
+ LONG PCOffset ; PC's offset into the above section.
+ ; Used because the section may be floating, so PC's value
+ ; is not known to RGBASM.
+
BYTE Type ; 0 = Prints the message but allows linking to continue
; 1 = Prints the message and evaluates other assertions,
; but linking fails afterwards
@@ -161,10 +178,6 @@
BYTE RPN[RPNSize] ; RPN expression, same as patches. Assert fails if == 0.
- LONG SectionID ; The section number (of this object file) in which this
- ; assert is defined. If it doesn't belong to any specific
- ; section (like a constant), this field has the value -1.
-
STRING Message ; A message displayed when the assert fails. If set to
; the empty string, a generic message is printed instead.
@@ -248,7 +261,7 @@
</tr>
<tr>
<td><a class="permalink" href="#$23"><code class="Li" id="$23">$23</code></a></td>
- <td><a class="permalink" href="#unary"><code class="Li" id="unary">unary</code></a>!</td>
+ <td><a class="permalink" href="#unary__!"><code class="Li" id="unary__!">unary !</code></a></td>
</tr>
<tr>
<td><a class="permalink" href="#$30"><code class="Li" id="$30">$30</code></a></td>
--- a/docs/rgblink.1.html
+++ b/docs/rgblink.1.html
@@ -33,7 +33,7 @@
<table class="Nm">
<tr>
<td><code class="Nm">rgblink</code></td>
- <td>[<code class="Fl"><a href="#d">-d</a><a href="#t">t</a><a href="#V">V</a><a href="#v">v</a><a href="#w">w</a></code>] [<code class="Fl"><a href="#l">-l</a></code>
+ <td>[<code class="Fl"><a href="#d">-d</a><a href="#t">t</a><a href="#V">V</a><a href="#v">v</a><a href="#w">w</a><a href="#x">x</a></code>] [<code class="Fl"><a href="#l">-l</a></code>
<var class="Ar">linker_script</var>] [<code class="Fl"><a href="#m">-m</a></code>
<var class="Ar">map_file</var>] [<code class="Fl"><a href="#n">-n</a></code>
<var class="Ar">sym_file</var>] [<code class="Fl"><a href="#O">-O</a></code>
@@ -71,7 +71,7 @@
<dt><a class="permalink" href="#d"><code class="Fl" id="d">-d</code></a>,
<code class="Fl">--dmg</code></dt>
<dd>Enable DMG mode. Prohibit the use of sections that doesn't exist on a DMG,
- such as WRAMX and VRAM bank 1. This option automatically enables
+ such as VRAM bank 1. This option automatically enables
<code class="Fl">-w</code>.</dd>
<dt><a class="permalink" href="#l"><code class="Fl" id="l">-l</code></a>
<var class="Ar">linker_script,</var>
@@ -122,7 +122,8 @@
<dt><a class="permalink" href="#t"><code class="Fl" id="t">-t</code></a>,
<code class="Fl">--tiny</code></dt>
<dd>Expand the ROM0 section size from 16 KiB to the full 32 KiB assigned to
- ROM and prohibit the use of ROMX sections. Useful for ROMs that fit in 32
+ ROM. ROMX sections that are fixed to a bank other than 1 become errors,
+ other ROMX sections are treated as ROM0. Useful for ROMs that fit in 32
KiB.</dd>
<dt><a class="permalink" href="#V"><code class="Fl" id="V">-V</code></a>,
<code class="Fl">--version</code></dt>
@@ -133,7 +134,15 @@
<dt><a class="permalink" href="#w"><code class="Fl" id="w">-w</code></a>,
<code class="Fl">--wramx</code></dt>
<dd>Expand the WRAM0 section size from 4 KiB to the full 8 KiB assigned to
- WRAM and prohibit the use of WRAMX sections.</dd>
+ WRAM. WRAMX sections that are fixed to a bank other than 1 become errors,
+ other WRAMX sections are treated as WRAM0.</dd>
+ <dt><a class="permalink" href="#x"><code class="Fl" id="x">-x</code></a>,
+ <code class="Fl">--nopad</code></dt>
+ <dd>Disables padding the end of the final file. This option automatically
+ enables <code class="Fl">-t</code>. You can use this when not not making a
+ ROM. When making a ROM, be careful that not using this is not a
+ replacement for <a class="Xr" href="rgbfix.1.html">rgbfix(1)</a>'s <code class="Fl">-p</code>
+ option!</dd>
</dl>
</section>
<section class="Sh">