gbdev/rgbds
1
0
Fork 0
mirror of https://github.com/gbdev/rgbds.git synced 2025-11-20 10:12:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update RGBASM manual

Browse Source
This commit is contained in:
ISSOtm
2021-04-01 00:11:37 +02:00
parent a890bd072b
commit 291dcf3b6c
1 changed files with 102 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files

182
src/asm/rgbasm.5
View File

@@ -63,7 +63,7 @@ X = /* the value of x
Sometimes lines can be too long and it may be necessary to split them. Sometimes lines can be too long and it may be necessary to split them.
To do so, put a backslash at the end of the line: To do so, put a backslash at the end of the line:
.Bd -literal -offset indent .Bd -literal -offset indent
DB 1, 2, 3,\ \[rs] LD [B @:...], 1, 2, 3,\ \[rs]
4, 5, 6,\ \[rs]\ ;\ Put it before any comments 4, 5, 6,\ \[rs]\ ;\ Put it before any comments
7, 8, 9 7, 8, 9
.Ed .Ed
@@ -73,7 +73,7 @@ To split strings it is needed to use
.Fn STRCAT .Fn STRCAT
like this: like this:
.Bd -literal -offset indent .Bd -literal -offset indent
db STRCAT("Hello ",\ \[rs] LD [B @:], STRCAT("Hello ",\ \[rs]
"world!") "world!")
.Ed .Ed
.Sh EXPRESSIONS .Sh EXPRESSIONS
@@ -226,7 +226,7 @@ For example:
; (shifted and scaled from the range [-1.0, 1.0]) ; (shifted and scaled from the range [-1.0, 1.0])
ANGLE = 0.0 ANGLE = 0.0
REPT 256 REPT 256
db (MUL(64.0, SIN(ANGLE)) + 64.0) >> 16 ld [b @], (MUL(64.0, SIN(ANGLE)) + 64.0) >> 16
ANGLE = ANGLE + 256.0 ; 256.0 = 65536 degrees / 256 entries ANGLE = ANGLE + 256.0 ; 256.0 = 65536 degrees / 256 entries
ENDR ENDR
.Ed .Ed
@@ -417,9 +417,9 @@ CHARMAP "&iacute", 20
CHARMAP "A", 128 CHARMAP "A", 128
.Ed .Ed
This would result in This would result in
.Ql db \(dqAmen<LF>\(dq .Ql ld [b @:...], \(dqAmen<LF>\(dq
being equivalent to being equivalent to
.Ql db 128, 109, 101, 110, 10 . .Ql ld [b @:...], 128, 109, 101, 110, 10 .
.Pp .Pp
Any characters in a string without defined mappings will be copied directly, using the source file's encoding of characters to bytes. Any characters in a string without defined mappings will be copied directly, using the source file's encoding of characters to bytes.
.Pp .Pp
@@ -574,15 +574,15 @@ While
will automatically optimize will automatically optimize
.Ic ld .Ic ld
instructions to the smaller and faster instructions to the smaller and faster
.Ic ldh .Ic ld\ h
(see (see
.Xr gbz80 7 ) .Xr gbz80 7 )
whenever possible, it is generally unable to do so when a label is involved. whenever possible, it is generally unable to do so when a label is involved.
Using the Using the
.Ic ldh .Ic ld\ h
instruction directly is recommended. instruction directly is recommended.
This forces the assembler to emit a This forces the assembler to emit a
.Ic ldh .Ic ld\ h
instruction and the linker to check if the value is in the correct range. instruction and the linker to check if the value is in the correct range.
.El .El
.Pp .Pp
@@ -699,11 +699,11 @@ CopyCode:
ld c, RAMLocation.end - RAMLocation ld c, RAMLocation.end - RAMLocation
\&.loop \&.loop
ld a, [de] ld a, [de]
inc de ld de+
ld [hli], a ld [hli], a
dec c ld c-
jr nz, .loop ld nz pc, b .loop
ret ld pc,[sp++]
RAMCode: RAMCode:
LOAD "RAM code", WRAM0 LOAD "RAM code", WRAM0
@@ -713,13 +713,13 @@ RAMLocation:
\&.copy \&.copy
ld a, [hli] ld a, [hli]
ld [de], a ld [de], a
inc de ld de+
and a ld a,a&a
jr nz, .copy ld nz pc, b .copy
ret ld pc,[sp++]
\&.string \&.string
db "Hello World!", 0 ld [b @:...], "Hello World!", 0
\&.end \&.end
ENDL ENDL
.Ed .Ed
@@ -929,14 +929,14 @@ references the one before the expression;
and so on. and so on.
.Bd -literal -offset indent .Bd -literal -offset indent
ld hl, :++ ld hl, :++
: ld a, [hli] ; referenced by "jr nz" : ld a, [hli] ; referenced by "ld nz pc"
ldh [c], a ldh [c], a
dec c ld c-
jr nz, :- ld nz pc,b :-
ret ld pc,[sp++]
: ; referenced by "ld hl" : ; referenced by "ld hl"
dw $7FFF, $1061, $03E0, $58A5 ld [w @:], $7FFF, $1061, $03E0, $58A5
.Ed .Ed
.Pp .Pp
A label's location (and thus value) is usually not determined until the linking stage, so labels usually cannot be used as constants. A label's location (and thus value) is usually not determined until the linking stage, so labels usually cannot be used as constants.
@@ -1036,13 +1036,13 @@ DEF COUNTREG EQUS "[hl+]"
ld a,COUNTREG ld a,COUNTREG
DEF PLAYER_NAME EQUS "\[rs]"John\[rs]"" DEF PLAYER_NAME EQUS "\[rs]"John\[rs]""
db PLAYER_NAME ld [b @:], PLAYER_NAME
.Ed .Ed
.Pp .Pp
This will be interpreted as: This will be interpreted as:
.Bd -literal -offset indent .Bd -literal -offset indent
ld a,[hl+] ld a,[hl+]
db "John" ld [b @:], "John"
.Ed .Ed
.Pp .Pp
String equates can also be used to define small one-line macros: String equates can also be used to define small one-line macros:
@@ -1135,7 +1135,7 @@ constructs.
.Bd -literal -offset indent .Bd -literal -offset indent
MACRO MyMacro MACRO MyMacro
ld a, 80 ld a, 80
call MyFunc ld[--sp],pc, MyFunc
ENDM ENDM
.Ed .Ed
.Pp .Pp
@@ -1208,9 +1208,9 @@ ExportedLabelB2:
.Ql c.asm : .Ql c.asm :
.Bd -literal -compact .Bd -literal -compact
SECTION "C", ROM0[0] SECTION "C", ROM0[0]
dw LabelA ld [w @], LabelA
dw ExportedLabelB1 ld [w @], ExportedLabelB1
dw ExportedLabelB2 ld [w @], ExportedLabelB2
.Ed .Ed
.Pp .Pp
Then Then
@@ -1281,18 +1281,20 @@ Refer to the spec at
.Lk https://reproducible-builds.org/docs/source-date-epoch/ . .Lk https://reproducible-builds.org/docs/source-date-epoch/ .
.Sh DEFINING DATA .Sh DEFINING DATA
.Ss Declaring variables in a RAM section .Ss Declaring variables in a RAM section
.Ic DS .Ic LD [B @:<len>]
allocates a number of empty bytes. allocates a number of empty bytes.
This is the preferred method of allocating space in a RAM section. This is the preferred method of allocating space in a RAM section.
You can also use You can also use
.Ic DB , DW .Ic LD [B @] , LD [W @]
and and
.Ic DL .Ic LD [L @]
without any arguments instead (see with
.Ql \&?
instead (see
.Sx Defining constant data .Sx Defining constant data
below). below).
.Bd -literal -offset indent .Bd -literal -offset indent
DS 42 ;\ Allocates 42 bytes LD [B @:42], ? ;\ Allocates 42 bytes
.Ed .Ed
.Pp .Pp
Empty space in RAM sections will not be initialized. Empty space in RAM sections will not be initialized.
@@ -1301,17 +1303,24 @@ In ROM sections, it will be filled with the value passed to the
command-line option, except when using overlays with command-line option, except when using overlays with
.Fl O . .Fl O .
.Ss Defining constant data .Ss Defining constant data
.Ic DB .Ic LD [B @]
defines a list of bytes that will be stored in the final image. defines a list of bytes that will be stored in the final image.
Ideal for tables and text. Ideal for tables and text.
.Bd -literal -offset indent .Bd -literal -offset indent
DB 1,2,3,4,"This is a string" LD [B @:...], 1,2,3,4,"This is a string"
.Ed .Ed
.Pp .Pp
Python slice syntax is used: for a single byte, close the brackets immediately after
.Ql @ ;
if more than one entry follows, a colon must be added after the
.Ql @ ,
optionally followed by an ellipsis
.Ql ... .
.Pp
Alternatively, you can use Alternatively, you can use
.Ic DW .Ic LD [W @]
to store a list of words (16-bit) or to store a list of words (16-bit) or
.Ic DL .Ic LD [L @]
to store a list of double-words/longs (32-bit). to store a list of double-words/longs (32-bit).
.Pp .Pp
Strings are handled a little specially: they first undergo charmap conversion (see Strings are handled a little specially: they first undergo charmap conversion (see
@@ -1323,32 +1332,38 @@ DW "Hello!"
DW "H", "e", "l", "l", "o", "!" DW "H", "e", "l", "l", "o", "!"
.Ed .Ed
.Pp .Pp
Note that strings require a colon after the
.Ql @
in the directive.
.Pp
If you do not want this special handling, enclose the string in parentheses. If you do not want this special handling, enclose the string in parentheses.
.Pp .Pp
.Ic DS .Ic LD [B @:<len>]
can also be used to fill a region of memory with some repeated values. can also be used to fill a region of memory with some repeated values.
For example: For example:
.Bd -literal -offset indent .Bd -literal -offset indent
; outputs 3 bytes: $AA, $AA, $AA ; outputs 3 bytes: $AA, $AA, $AA
DS 3, $AA LD [B @:3], $AA
; outputs 7 bytes: $BB, $CC, $BB, $CC, $BB, $CC, $BB ; outputs 7 bytes: $BB, $CC, $BB, $CC, $BB, $CC, $BB
DS 7, $BB, $CC LD [B @:7], $BB, $CC
.Ed .Ed
.Pp .Pp
You can also use You can also use
.Ic DB , DW .Ic LD [B @] , LD [W @]
and and
.Ic DL .Ic LD [L @]
without arguments. with
.Ql \&?
as its sole argument (in which case neither the colon nor an ellipsis may be present).
This works exactly like This works exactly like
.Ic DS 1 , DS 2 .Ic LD [B @:1] , LD [B @:2]
and and
.Ic DS 4 .Ic LD [B @:4]
respectively. respectively.
Consequently, no-argument Consequently, these forms of
.Ic DB , DW .Ic LD [B @] , LD [W @]
and and
.Ic DL .Ic LD [L @]
can be used in a can be used in a
.Ic WRAM0 .Ic WRAM0
/ /
@@ -1363,23 +1378,24 @@ section.
.Ss Including binary files .Ss Including binary files
You probably have some graphics, level data, etc. you'd like to include. You probably have some graphics, level data, etc. you'd like to include.
Use Use
.Ic INCBIN .Ic LD [B @:...] =
to include a raw binary file as it is. to include a raw binary file as it is.
.Pq The ellipsis are optional.
If the file isn't found in the current directory, the include-path list passed to If the file isn't found in the current directory, the include-path list passed to
.Xr rgbasm 1 .Xr rgbasm 1
(see the (see the
.Fl i .Fl i
option) on the command line will be searched. option) on the command line will be searched.
.Bd -literal -offset indent .Bd -literal -offset indent
INCBIN "titlepic.bin" LD [B @:] = "titlepic.bin"
INCBIN "sprites/hero.bin" LD [B @:...] = "sprites/hero.bin"
.Ed .Ed
.Pp .Pp
You can also include only part of a file with You can also include only part of a file with
.Ic INCBIN . .Ic LD [B @:] .
The example below includes 256 bytes from data.bin, starting from byte 78. The example below includes 256 bytes from data.bin, starting from byte 78.
.Bd -literal -offset indent .Bd -literal -offset indent
INCBIN "data.bin",78,256 LD [B @:] = "data.bin"[78:256]
.Ed .Ed
.Pp .Pp
The length argument is optional. The length argument is optional.
@@ -1399,19 +1415,19 @@ separates each block of allocations, and you may use it as many times within a u
; Let's say PC = $C0DE here ; Let's say PC = $C0DE here
UNION UNION
; Here, PC = $C0DE ; Here, PC = $C0DE
Name: ds 8 Name: ld [b @:8], ?
; PC = $C0E6 ; PC = $C0E6
Nickname: ds 8 Nickname: ld [b @:8], ?
; PC = $C0EE ; PC = $C0EE
NEXTU NEXTU
; PC is back to $C0DE ; PC is back to $C0DE
Health: dw Health: ld pc [w @], ?
; PC = $C0E0 ; PC = $C0E0
Something: ds 6 Something: ld [b @:6], ?
; And so on ; And so on
Lives: db Lives: ld pc [b @], ?
NEXTU NEXTU
VideoBuffer: ds 19 VideoBuffer: ld [b @:19], ?
ENDU ENDU
.Ed .Ed
.Pp .Pp
@@ -1431,17 +1447,17 @@ The size of this union is 19 bytes, as this is the size of the largest block (th
Nesting unions is possible, with each inner union's size being considered as described above. Nesting unions is possible, with each inner union's size being considered as described above.
.Pp .Pp
Unions may be used in any section, but inside them may only be Unions may be used in any section, but inside them may only be
.Ic DS - .Ic LD\ [B\ @],\ ? Ns - Ns
like commands (see like commands (see
.Sx Declaring variables in a RAM section ) . .Sx Declaring variables in a RAM section ) .
.Sh THE MACRO LANGUAGE .Sh THE MACRO LANGUAGE
.Ss Invoking macros .Ss Invoking macros
You execute the macro by inserting its name. You execute the macro by inserting its name.
.Bd -literal -offset indent .Bd -literal -offset indent
add a,b ld a,a+b
ld sp,hl ld sp,hl
MyMacro ;\ This will be expanded MyMacro ;\ This will be expanded
sub a,87 ld a,a-87
.Ed .Ed
.Pp .Pp
It's valid to call a macro from a macro (yes, even the same one). It's valid to call a macro from a macro (yes, even the same one).
@@ -1458,10 +1474,10 @@ it will insert the macro definition (the code enclosed in
Suppose your macro contains a loop. Suppose your macro contains a loop.
.Bd -literal -offset indent .Bd -literal -offset indent
MACRO LoopyMacro MACRO LoopyMacro
xor a,a ld a,a^a
\&.loop ld [hl+],a \&.loop ld [hl+],a
dec c ld c-
jr nz,.loop ld nz pc,b .loop
ENDM ENDM
.Ed .Ed
.Pp .Pp
@@ -1476,10 +1492,10 @@ also works in
blocks. blocks.
.Bd -literal -offset indent .Bd -literal -offset indent
MACRO LoopyMacro MACRO LoopyMacro
xor a,a ld a,a^a
\&.loop\[rs]@ ld [hl+],a \&.loop\[rs]@ ld [hl+],a
dec c ld c-
jr nz,.loop\[rs]@ ld nz pc,b .loop\[rs]@
ENDM ENDM
.Ed .Ed
.Pp .Pp
@@ -1507,10 +1523,10 @@ being the first argument specified on the macro invocation.
MACRO LoopyMacro MACRO LoopyMacro
ld hl,\[rs]1 ld hl,\[rs]1
ld c,\[rs]2 ld c,\[rs]2
xor a,a ld a,a^a
\&.loop\[rs]@ ld [hl+],a \&.loop\[rs]@ ld [hl+],a
dec c ld c-
jr nz,.loop\[rs]@ ld nz pc,b .loop\[rs]@
ENDM ENDM
.Ed .Ed
.Pp .Pp
@@ -1622,7 +1638,7 @@ The following example will assemble
four times: four times:
.Bd -literal -offset indent .Bd -literal -offset indent
REPT 4 REPT 4
add a,c ld a,a+c
ENDR ENDR
.Ed .Ed
.Pp .Pp
@@ -1634,7 +1650,7 @@ to generate tables on the fly:
; (shifted and scaled from the range [-1.0, 1.0]) ; (shifted and scaled from the range [-1.0, 1.0])
ANGLE = 0.0 ANGLE = 0.0
REPT 256 REPT 256
db (MUL(64.0, SIN(ANGLE)) + 64.0) >> 16 ld [b @], (MUL(64.0, SIN(ANGLE)) + 64.0) >> 16
ANGLE = ANGLE + 256.0 ; 256.0 = 65536 degrees / 256 entries ANGLE = ANGLE + 256.0 ; 256.0 = 65536 degrees / 256 entries
ENDR ENDR
.Ed .Ed
@@ -1658,21 +1674,21 @@ String equates are not expanded within the symbol name.
For example, this code will produce a table of squared values from 0 to 255: For example, this code will produce a table of squared values from 0 to 255:
.Bd -literal -offset indent .Bd -literal -offset indent
FOR N, 256 FOR N, 256
dw N * N ld [w @], N * N
ENDR ENDR
.Ed .Ed
.Pp .Pp
It acts just as if you had done: It acts just as if you had done:
.Bd -literal -offset ident .Bd -literal -offset ident
N = 0 N = 0
dw N * N ld [w @], N * N
N = 1 N = 1
dw N * N ld [w @], N * N
N = 2 N = 2
dw N * N ld [w @], N * N
; ... ; ...
N = 255 N = 255
dw N * N ld [w @], N * N
N = 256 N = 256
.Ed .Ed
.Pp .Pp
@@ -1763,18 +1779,18 @@ and
Syntax examples are given below: Syntax examples are given below:
.Bd -literal -offset indent .Bd -literal -offset indent
Function: Function:
xor a ld a,a^a
ASSERT LOW(Variable) == 0 ASSERT LOW(Variable) == 0
ld h, HIGH(Variable) ld h, HIGH(Variable)
ld l, a ld l, a
ld a, [hli] ld a, [hli]
; You can also indent this! ; You can also indent this!
ASSERT BANK(OtherFunction) == BANK(Function) ASSERT BANK(OtherFunction) == BANK(Function)
call OtherFunction ld [--sp], pc,OtherFunction
; Lowercase also works ; Lowercase also works
assert Variable + 1 == OtherVariable assert Variable + 1 == OtherVariable
ld c, [hl] ld c, [hl]
ret ld pc,[sp++]
\&.end \&.end
; If you specify one, a message will be printed ; If you specify one, a message will be printed
STATIC_ASSERT .end - Function < 256, "Function is too large!" STATIC_ASSERT .end - Function < 256, "Function is too large!"
@@ -1883,9 +1899,9 @@ takes a comma-separated list of options as its argument:
.Bd -literal -offset indent .Bd -literal -offset indent
PUSHO PUSHO
OPT g.oOX ;Set the GB graphics constants to use these characters OPT g.oOX ;Set the GB graphics constants to use these characters
DW `..ooOOXX LD [W @], `..ooOOXX
POPO POPO
DW `00112233 LD [W @], `00112233
.Ed .Ed
.Pp .Pp
The options that OPT can modify are currently: The options that OPT can modify are currently: