mirror of
https://github.com/gbdev/rgbds.git
synced 2025-11-20 18:22:07 +00:00
Regenerate docs for 0.4.1
This commit is contained in:
ISSOtm
@@ -1064,10 +1064,10 @@ Pop register <b class="Sy">AF</b> from the stack. This is roughly equivalent to
|
||||
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>
|
||||
|
||||
@@ -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 @@ The <code class="Nm">rgbasm</code> program creates an RGB object file from an
|
||||
<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 @@ Warnings are diagnostic messages that indicate possibly erroneous behavior that
|
||||
<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>
|
||||
|
||||
@@ -232,7 +232,7 @@ A great number of operators you can use in expressions are available (listed
|
||||
<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 @@ Before you can start writing code, you must define a section. This tells the
|
||||
<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 @@ Before you can start writing code, you must define a section. This tells the
|
||||
<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
|
||||
@@ -848,7 +851,8 @@ When you're tight on RAM, you may want to define overlapping blocks of
|
||||
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,6 +869,43 @@ When you're tight on RAM, you may want to define overlapping blocks of
|
||||
<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>
|
||||
@@ -919,6 +960,8 @@ ThisWillBeExported.too::
|
||||
‘<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
|
||||
@@ -1665,6 +1708,23 @@ DW `00112233
|
||||
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">
|
||||
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
|
||||
|
||||
@@ -107,8 +107,10 @@ REPT NumberOfSections
|
||||
; 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.
|
||||
|
||||
@@ -116,8 +118,6 @@ REPT NumberOfSections
|
||||
|
||||
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 @@ REPT NumberOfSections
|
||||
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 @@ REPT NumberOfAssertions
|
||||
|
||||
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 @@ REPT NumberOfAssertions
|
||||
|
||||
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 @@ Expressions in the object file are stored as RPN. This is an expression of the
|
||||
</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>
|
||||
|
||||
@@ -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 @@ The <code class="Nm">rgblink</code> program links RGB object files, typically
|
||||
<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 @@ The <code class="Nm">rgblink</code> program links RGB object files, typically
|
||||
<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 @@ The <code class="Nm">rgblink</code> program links RGB object files, typically
|
||||
<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">
|
||||
|
||||
Reference in New Issue
Block a user