mirror of
https://github.com/gbdev/rgbds.git
synced 2025-11-20 10:12:06 +00:00
498 lines
9.9 KiB
Groff
498 lines
9.9 KiB
Groff
'\" e
|
|
.\"
|
|
.\" SPDX-License-Identifier: MIT
|
|
.\"
|
|
.Dd June 30, 2025
|
|
.Dt RGBASM-OLD 5
|
|
.Os
|
|
.Sh NAME
|
|
.Nm rgbasm-old
|
|
.Nd obsolete language documentation
|
|
.Sh DESCRIPTION
|
|
This is the list of features that have been removed from the
|
|
.Xr rgbasm 5
|
|
assembly language over its decades of evolution, along with their modern alternatives.
|
|
Its goal is to be a reference for backwards incompatibility, when upgrading an old assembly codebase to work with the latest RGBDS release.
|
|
It does
|
|
.Em not
|
|
attempt to list every syntax bug that was ever fixed (with some notable exceptions), nor new reserved keywords that may conflict with old identifiers.
|
|
.Sh REMOVED
|
|
These are features which have been completely removed, without any direct alternatives.
|
|
Usually these features were limiting the addition of other features, or had awkward limits on their own intended effects.
|
|
.Ss Automatic LD to LDH conversion (rgbasm -l)
|
|
Deprecated in 0.7.0, removed in 0.8.0.
|
|
.Pp
|
|
.Xr rgbasm 1
|
|
used to automatically treat
|
|
.Ql LD
|
|
as
|
|
.Ql LDH
|
|
if the address was known to be in the
|
|
.Ad $FF00-$FFFF
|
|
range, with the
|
|
.Fl L
|
|
flag to opt out.
|
|
.Xr rgbasm 1
|
|
0.6.0 added a
|
|
.Fl l
|
|
flag to opt in instead.
|
|
.Pp
|
|
Instead, use
|
|
.Ql LDH ,
|
|
and remove the
|
|
.Fl L
|
|
and
|
|
.Fl l
|
|
flags from
|
|
.Xr rgbasm 1 .
|
|
.Ss Automatic NOP after HALT (rgbasm -H)
|
|
Deprecated in 0.7.0, removed in 0.8.0.
|
|
.Pp
|
|
.Xr rgbasm 1
|
|
used to automatically insert a
|
|
.Ql NOP
|
|
after
|
|
.Ql HALT ,
|
|
with the
|
|
.Fl h
|
|
flag to opt out.
|
|
.Xr rgbasm 1
|
|
0.6.0 added a
|
|
.Fl H
|
|
flag to opt in instead.
|
|
.Pp
|
|
Instead, use an explicit
|
|
.Ql NOP
|
|
after
|
|
.Ql HALT ,
|
|
and remove the
|
|
.Fl h
|
|
and
|
|
.Fl H
|
|
flags from
|
|
.Xr rgbasm 1 .
|
|
.Ss Nested macro definitions
|
|
Removed in 0.4.2.
|
|
.Pp
|
|
Instead, put the nested macro definition inside a quoted string (making sure that none of its lines start with
|
|
.Ic ENDM ) ,
|
|
then interpolate that string.
|
|
For example:
|
|
.Bd -literal -offset indent
|
|
MACRO outer
|
|
DEF definition EQUS """
|
|
MACRO inner
|
|
println (\e1) - (\e\e1)
|
|
\enENDM"""
|
|
{definition}
|
|
PURGE definition
|
|
ENDM
|
|
outer 10
|
|
inner 3 ; prints 7
|
|
.Ed
|
|
.Ss Negative DS
|
|
Removed in 0.3.2.
|
|
.Pp
|
|
This was used to "rewind" the value of
|
|
.Ic @
|
|
in RAM sections, allowing labeled space allocations to overlap.
|
|
.Pp
|
|
Instead, use
|
|
.Ic UNION .
|
|
.Ss Section-local charmaps
|
|
Deprecated in 0.3.9, removed in 0.4.0.
|
|
.Pp
|
|
Defining a
|
|
.Ic CHARMAP
|
|
inside a
|
|
.Ic SECTION
|
|
when the current global charmap was the
|
|
.Sq main
|
|
one used to only define that character mapping within that
|
|
.Ic SECTION .
|
|
.Pp
|
|
Instead, use
|
|
.Ic PUSHC
|
|
and
|
|
.Ic POPC
|
|
and switch to a different character mapping for that section.
|
|
.Ss __FILE__ and __LINE__
|
|
Deprecated in 0.6.0, removed in 0.7.0.
|
|
.Pp
|
|
Instead, use
|
|
.Ic WARN
|
|
or
|
|
.Ic FAIL
|
|
to print a complete trace of filenames and line numbers.
|
|
.Ss _PI
|
|
Deprecated in 0.5.0, removed in 0.6.0.
|
|
.Pp
|
|
Instead, use
|
|
.Ql 3.141592653 .
|
|
.Ss Treating multi-character strings as numbers
|
|
Deprecated in 0.9.0.
|
|
.Pp
|
|
Instead, use a multi-value
|
|
.Ic CHARMAP ,
|
|
or explicitly combine the values of individual characters.
|
|
.Ss rgbgfx -f/--fix and -F/--fix-and-save
|
|
Removed in 0.6.0.
|
|
.Pp
|
|
Instead, use
|
|
.Ql rgbgfx -c/--colors
|
|
to explicitly specify a color palette.
|
|
If using
|
|
.Ql -c embedded ,
|
|
arrange the PNG's indexed palette in a separate graphics editor.
|
|
.Ss rgbgfx -D/--debug
|
|
Removed in 0.6.0.
|
|
.Sh REPLACED
|
|
These are features whose syntax has been changed without affecting functionality.
|
|
They can generally be updated with a single search-and-replace.
|
|
.Ss Defining constants and variables without DEF
|
|
Deprecated in 0.7.0, removed in 0.8.0.
|
|
.Pp
|
|
.Ic EQU , EQUS , = , RB , RW ,
|
|
and
|
|
.Ic RL
|
|
definitions used to just start with the symbol name, but had to be typed in column 1.
|
|
.Pp
|
|
Instead, use
|
|
.Ic DEF
|
|
before constant and variable definitions.
|
|
Note that
|
|
.Ic EQUS
|
|
expansion does not occur for the symbol name, so you have to use explicit
|
|
.Ql {interpolation} .
|
|
.Ss Defining macros like labels
|
|
Deprecated in 0.6.0, removed in 0.7.0.
|
|
.Pp
|
|
Macros used to be defined as
|
|
.Ql name: MACRO .
|
|
.Pp
|
|
Instead, use
|
|
.Ql MACRO name .
|
|
Note that
|
|
.Ic EQUS
|
|
expansion does not occur for the macro name, so you have to use explicit
|
|
.Ql {interpolation} .
|
|
.Ss Defining variables with SET
|
|
Deprecated in 0.5.2, removed in 0.6.0.
|
|
.Pp
|
|
Variables used to be defined as
|
|
.Ql name SET value .
|
|
.Pp
|
|
Instead, use
|
|
.Ql DEF name = value .
|
|
.Ss Global labels without colons
|
|
Deprecated in 0.4.0, removed in 0.5.0.
|
|
.Pp
|
|
Labels used to be definable with just a name, but had to be typed in column 1.
|
|
.Pp
|
|
Instead, use explicit colons; for example,
|
|
.Ql Label:
|
|
or exported
|
|
.Ql Label:: .
|
|
.Ss '\e,' in strings within macro arguments
|
|
Deprecated in 0.5.0, removed in 0.7.0.
|
|
.Pp
|
|
Macro arguments now handle quoted strings and parenthesized expressions as single arguments, so commas inside them are not argument separators and do not need escaping.
|
|
.Pp
|
|
Instead, just use commas without backslashes.
|
|
.Ss '*' comments
|
|
Deprecated in 0.4.1, removed in 0.5.0.
|
|
.Pp
|
|
These comments had to have the
|
|
.Ql *
|
|
typed in column 1.
|
|
.Pp
|
|
Instead, use
|
|
.Ql \&;
|
|
comments.
|
|
.Ss PRINTT, PRINTI, PRINTV, and PRINTF
|
|
Deprecated in 0.5.0, removed in 0.6.0.
|
|
.Pp
|
|
These directives were each specific to one type of value.
|
|
.Pp
|
|
Instead, use
|
|
.Ic PRINT
|
|
and
|
|
.Ic PRINTLN ,
|
|
with
|
|
.Ic STRFMT
|
|
or
|
|
.Ql {interpolation}
|
|
for type-specific formatting.
|
|
.Ss IMPORT and XREF
|
|
Removed in 0.4.0.
|
|
.Pp
|
|
Symbols are now automatically resolved if they were exported from elsewhere.
|
|
.Pp
|
|
Instead, just remove these directives.
|
|
.Ss GLOBAL and XDEF
|
|
Deprecated in 0.4.2, removed in 0.5.0.
|
|
.Pp
|
|
Instead, use
|
|
.Ic EXPORT .
|
|
.Ss HOME, CODE, DATA, and BSS
|
|
Deprecated in 0.3.0, removed in 0.4.0.
|
|
.Pp
|
|
Instead of
|
|
.Ic HOME ,
|
|
use
|
|
.Ic ROM0 ;
|
|
instead of
|
|
.Ic CODE
|
|
and
|
|
.Ic DATA ,
|
|
use
|
|
.Ic ROMX ;
|
|
instead of
|
|
.Ic BSS ,
|
|
use
|
|
.Ic WRAM0 .
|
|
.Ss JP [HL]
|
|
Deprecated in 0.3.0, removed in 0.4.0.
|
|
.Pp
|
|
Instead, use
|
|
.Ql JP HL .
|
|
.Ss LDI A, HL and LDD A, HL
|
|
Deprecated in 0.3.0, removed in 0.4.0.
|
|
.Pp
|
|
Instead, use
|
|
.Ql LDI A, [HL]
|
|
and
|
|
.Ql LDD A, [HL]
|
|
(or
|
|
.Ql LD A, [HLI]
|
|
and
|
|
.Ql LD A, [HLD] ;
|
|
or
|
|
.Ql LD A, [HL+]
|
|
and
|
|
.Ql LD A, [HL-] ) .
|
|
.Ss LDIO
|
|
Deprecated in 0.9.0.
|
|
.Pp
|
|
Instead, use
|
|
.Ql LDH .
|
|
.Ss LD [C], A and LD A, [C]
|
|
Deprecated in 0.9.0.
|
|
.Pp
|
|
Instead, use
|
|
.Ql LDH [C], A
|
|
and
|
|
.Ql LDH A, [C] .
|
|
.Pp
|
|
Note that
|
|
.Ql LD [$FF00+C], A
|
|
and
|
|
.Ql LD A, [$FF00+C]
|
|
were also deprecated in 0.9.0, but were
|
|
.Em undeprecated
|
|
in 0.9.1.
|
|
.Ss LDH [n8], A and LDH A, [n8]
|
|
Deprecated in 0.9.0.
|
|
.Pp
|
|
.Ql LDH
|
|
used to treat "addresses" from
|
|
.Ad $00
|
|
to
|
|
.Ad $FF
|
|
as if they were the low byte of an address from
|
|
.Ad $FF00
|
|
to
|
|
.Ad $FFFF .
|
|
.Pp
|
|
Instead, use
|
|
.Ql LDH [n16], A
|
|
and
|
|
.Ql LDH A, [n16] .
|
|
.Ss LD HL, [SP + e8]
|
|
Deprecated in 0.3.0, removed in 0.4.0.
|
|
.Pp
|
|
Instead, use
|
|
.Ql LD HL, SP + e8 .
|
|
.Ss LDHL SP, e8
|
|
Supported in ASMotor, removed in RGBDS.
|
|
.Pp
|
|
Instead, use
|
|
.Ql LD HL, SP + e8 .
|
|
.Ss OPT z
|
|
Deprecated in 0.4.0, removed in 0.5.0.
|
|
.Pp
|
|
Instead, use
|
|
.Ic OPT p .
|
|
.Ss rgbasm -i
|
|
Deprecated in 0.6.0, removed in 0.8.0.
|
|
.Pp
|
|
Instead, use
|
|
.Fl I
|
|
or
|
|
.Fl -include .
|
|
.Ss rgbgfx -h
|
|
Removed in 0.6.0.
|
|
.Pp
|
|
Instead, use
|
|
.Fl Z
|
|
or
|
|
.Fl -columns .
|
|
.Ss rgbgfx --output-*
|
|
Deprecated in 0.7.0, removed in 0.8.0.
|
|
.Pp
|
|
Instead, use
|
|
.Fl -auto-* .
|
|
.Sh CHANGED
|
|
These are breaking changes that did not alter syntax, and so could not practically be deprecated.
|
|
.Ss Trigonometry function units
|
|
Changed in 0.6.0.
|
|
.Pp
|
|
Instead of dividing a circle into 65536.0 "binary degrees", it is now divided into 1.0 "turns".
|
|
.Pp
|
|
For example, previously we had:
|
|
.EQ
|
|
delim $$
|
|
.EN
|
|
.Bl -bullet -offset indent
|
|
.It
|
|
.Ql SIN(0.25) == 0.00002 ,
|
|
because 0.25 binary degrees = $0.25 / 65536.0$ turns = $0.000004 tau$ radians = $0.000008 pi$ radians, and $sin ( 0.000008 pi ) = 0.00002$
|
|
.It
|
|
.Ql SIN(16384.0) == 1.0 ,
|
|
because 16384.0 binary degrees = $16384.0 / 65536.0$ turns = $0.25 tau$ radians = $pi / 2$ radians, and $sin ( pi / 2 ) = 1$
|
|
.It
|
|
.Ql ASIN(1.0) == 16384.0
|
|
.El
|
|
.Pp
|
|
Instead, now we have:
|
|
.Bl -bullet -offset indent
|
|
.It
|
|
.Ql SIN(0.25) == 1.0 ,
|
|
because $0.25$ turns = $0.25 tau$ radians = $pi / 2$ radians, and $sin ( pi / 2 ) = 1$
|
|
.It
|
|
.Ql SIN(16384.0) == 0.0 ,
|
|
because $16384$ turns = $16384 tau$ radians = $32768 pi$ radians, and $sin ( 32768 pi ) = 0$
|
|
.It
|
|
.Ql ASIN(1.0) == 0.25
|
|
.El
|
|
.EQ
|
|
delim off
|
|
.EN
|
|
.Ss % operator behavior with negative dividend or divisor
|
|
Changed in 0.5.0.
|
|
.Pp
|
|
Instead of having the same sign as the dividend (a remainder operation),
|
|
.Ql %
|
|
has the same sign as the divisor (a modulo operation).
|
|
.Pp
|
|
For example, previously we had:
|
|
.Bl -bullet -offset indent
|
|
.It
|
|
.Ql 13 % 10 == 3
|
|
.It
|
|
.Ql -13 % 10 == -3
|
|
.It
|
|
.Ql 13 % -10 == 3
|
|
.It
|
|
.Ql -13 % -10 == -3
|
|
.El
|
|
.Pp
|
|
Instead, now we have:
|
|
.Bl -bullet -offset indent
|
|
.It
|
|
.Ql 13 % 10 == 3
|
|
.It
|
|
.Ql -13 % 10 == 7
|
|
.It
|
|
.Ql 13 % -10 == -7
|
|
.It
|
|
.Ql -13 % -10 == -3
|
|
.El
|
|
.Ss ** operator associativity
|
|
Changed in 0.9.0.
|
|
.Pp
|
|
Instead of being left-associative,
|
|
.Ql **
|
|
is now right-associative.
|
|
.Pp
|
|
Previously we had
|
|
.Ql p ** q ** r == (p ** q) ** r .
|
|
.Pp
|
|
Instead, now we have
|
|
.Ql p ** q ** r == p ** (q ** r) .
|
|
.Sh BUGS
|
|
These are misfeatures that may have been possible by mistake.
|
|
They do not get deprecated, just fixed.
|
|
.Ss Space between exported labels' colons
|
|
Fixed in 0.7.0.
|
|
.Pp
|
|
Labels with two colons used to ignore a space between them; for example,
|
|
.Ql Label:\ : .
|
|
.Pp
|
|
Instead, use
|
|
.Ql Label:: .
|
|
.Ss Space between label and colon
|
|
Fixed in 0.9.0.
|
|
.Pp
|
|
Space between a label and its colon(s) used to be ignored; for example,
|
|
.Ql Label\ :
|
|
and
|
|
.Ql Label\ :: .
|
|
Now they are treated as invocations of the
|
|
.Ql Label
|
|
macro with
|
|
.Ql \&:
|
|
and
|
|
.Ql ::
|
|
as arguments.
|
|
.Pp
|
|
Instead, use
|
|
.Ql Label:
|
|
and
|
|
.Ql Label:: .
|
|
.Ss ADD r16 with implicit first HL operand
|
|
Fixed in 0.5.0.
|
|
.Pp
|
|
For example,
|
|
.Ql ADD BC
|
|
used to be treated as
|
|
.Ql ADD HL, BC ,
|
|
and likewise for
|
|
.Ql DE ,
|
|
.Ql HL ,
|
|
and
|
|
.Ql SP .
|
|
.Pp
|
|
Instead, use an explicit first
|
|
.Ql HL
|
|
operand.
|
|
.Ss = instead of SET
|
|
Fixed in 0.4.0.
|
|
.Pp
|
|
The
|
|
.Ic =
|
|
operator used to be an alias for the
|
|
.Ic SET
|
|
keyword, which included using
|
|
.Ic =
|
|
for the
|
|
.Ic SET
|
|
.Em instruction .
|
|
.Pp
|
|
Instead, just use
|
|
.Ic SET
|
|
for the instruction.
|
|
.Sh SEE ALSO
|
|
.Xr rgbasm 1 ,
|
|
.Xr gbz80 7 ,
|
|
.Xr rgbds 5 ,
|
|
.Xr rgbds 7
|
|
.Sh HISTORY
|
|
.Xr rgbasm 1
|
|
was originally written by
|
|
.An Carsten S\(/orensen
|
|
as part of the ASMotor package, and was later repackaged in RGBDS by
|
|
.An Justin Lloyd .
|
|
It is now maintained by a number of contributors at
|
|
.Lk https://github.com/gbdev/rgbds .
|