3. Assembler Directives¶
Here’s the order in which the data is placed into the output:
Data and group 3 directives outside sections.
Group 2 directives.
Data and group 3 directives inside sections.
Group 1 directives.
ALL |
All, GB-Z80, Z80, 6502, 65C02, 65CE02, 65816, HUC6280, SPC-700, 68000, 6800, 6801, 6809, 8008, 8080 and SuperFX versions apply. |
GB |
Only the GB-Z80 version applies. |
GB8 |
Only the GB-Z80 and 65816 versions apply. |
Z80 |
Only the Z80 version applies. |
658 |
Only the 65816 version applies. |
68K |
Only the 68000 version applies. |
680 |
Only the 6800, 6801 and 6809 versions apply. |
800 |
Only the 8008 version applies. |
808 |
Only the 8080 version applies. |
SPC |
Only the SPC-700 version applies. |
SFX |
Only the SuperFX version applies. |
65x |
Only the 6502, 65C02, 65CE02, 65816 and HUC6280 versions apply. |
!GB |
All but the GB-Z80 versions apply. |
Group 1:
GB |
|
68K |
|
Z80 |
|
658 |
|
Z80 |
|
Z80 |
|
Group 2:
GB |
|
GB |
|
GB |
|
GB |
|
ALL |
|
658 |
|
658 |
|
658 |
|
658 |
|
ALL |
|
658 |
|
GB |
|
658 |
|
GB |
|
GB |
|
658 |
|
GB8 |
|
GB |
|
ALL |
|
GB |
|
GB |
|
GB |
|
GB |
|
GB |
|
GB |
|
658 |
|
658 |
|
68K |
|
Z80 |
|
658 |
|
658 |
|
658 |
|
GB |
|
Group 3:
65x |
|
658 |
|
65x |
|
658 |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
658 |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
658 |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
ALL |
|
658 |
|
ALL |
|
ALL |
|
Descriptions:
3.1. .16BIT
¶
Analogous to .8BIT
. .16BIT
forces all addresses and immediate values to
be expanded into 16-bit range, when possible, that is:
LSR 11 ; $46 $0B
That would be the case, normally, but after .16BIT
it becomes:
LSR 11 ; $4E $0B $00
This is not a compulsory directive.
3.2. .24BIT
¶
Analogous to .8BIT
and .16BIT
. .24BIT
forces all addresses to
be expanded into 24-bit range, when possible, that is:
AND $11 ; $25 $11
That would be the case, normally, but after .24BIT
it becomes:
AND $11 ; $2F $11 $00 $00
If it is not possible to expand the address into .24BIT
range,
then WLA tries to expand it into 16-bit range.
This is not a compulsory directive.
3.3. .8BIT
¶
There are a few mnemonics that look identical, but take different sized arguments. Here’s a list of such 6502 mnemonics:
ADC, AND, ASL, BIT, CMP, CPX, CPY, DEC, EOR, INC, LDA, LDX, LDY, ORA, ROL, SBC, STA, STX and STY.
For example:
LSR 11 ; $46 $0B
LSR $A000 ; $4E $00 $A0
The first one could also be:
LSR 11 ; $4E $0B $00
.8BIT
is here to help WLA to decide to choose which one of the opcodes it
selects. When you give .8BIT
(default) no 8-bit address/value is expanded
to 16-bits.
By default WLA uses the smallest possible size. This is true also when WLA finds a computation it can’t solve right away. WLA assumes the result will be inside the smallest possible bounds, which depends on the type of the mnemonic.
You can also use the fixed argument size versions of such mnemonics by giving the size with the operand (i.e., operand hinting). Here are few examples:
LSR 11.B ; $46 $0B
LSR 11.W ; $4E $0B $00
In WLA-65816 .ACCU
/ .INDEX
/ SEP
/ REP
override
.8BIT
/ .16BIT
/.24BIT
when considering the immediate values, so be
careful. Still, operand hints override all of these, so use them to be sure.
This is not a compulsory directive.
3.4. .ACCU 8
¶
Forces WLA to override the accumulator size given with SEP
/ REP
.
.ACCU
doesn’t produce any code, it only affects the way WLA interprets the
immediate values (8 for 8 bit operands, 16 for 16 bit operands) for opcodes
dealing with the accumulator.
So after giving .ACCU 8
:
AND #6
will produce $29 $06
, and after giving .ACCU 16
:
AND #6
will yield $29 $00 $06
.
Note that SEP
/ REP
again will in turn reset the accumulator/index
register size.
This is not a compulsory directive.
3.5. .ADDR 16000, main, 255
¶
.ADDR
is an alias for .DW
.
This is not a compulsory directive.
3.6. .ALIGN 4
¶
Makes it so that on the next line the address is a multiple of the supplied
value. Currently this directive can only be given outside .SECTION
s or
inside FORCE .SECTION
s or inside .SECTION
s that have ALIGN that is
a multiple of the .ALIGN
here.
This is not a compulsory directive.
3.7. .ARRAYDB NAME MyArray INDICES '0', 0, 1
¶
This is the same as .DB
, but defines bytes by reading indexed values from
the given array. In the example the indices are ‘0’ (48), 0 and 1.
NAME
and INDICES
are optional so this works also:
.ARRAYDB MyArray '0', 0, 1
If you supply .ARRAYDB
a string as indices, each character is used as an index:
.ARRAYDB NAME MyArray INDICES "MAP THIS!"
This is not a compulsory directive.
3.8. .ARRAYDD NAME MyArray INDICES '0', 0, 1
¶
.ARRAYDD
works the same way as .ARRAYDB
, but defines 32-bit double words.
This is not a compulsory directive.
3.9. .ARRAYDEF NAME MyArray SIZE 256
¶
.ARRAYDEF
is an alias for .ARRAYDEFINE
.
This is not a compulsory directive.
3.10. .ARRAYDEFINE NAME MyArray SIZE 256
¶
Defines an array called MyArray, and its initial size is 256 items. Each
item is an ANSI C89 int (32-bit). The array can be written into using
directive .ARRAYIN
and it can be read from using directive
.ARRAYOUT
. This array exists only in WLA’s memory and during
assembling, but it can be used for e.g., mapping parts of ASCII table
into e.g., 4 bits:
// define a too small array for mapping "0123456789" -> 4-bits
// it gets enlarged by out-of-bounds .ARRAYINs later...
.ARRAYDEFINE NAME MyArray SIZE 4
// define the mapping
.ARRAYIN NAME MyArray INDEX '0' VALUE %0000
.ARRAYIN NAME MyArray INDEX '1' VALUE %0001
.ARRAYIN NAME MyArray INDEX '2' VALUE %0010
.ARRAYIN NAME MyArray INDEX '3' VALUE %0011
.ARRAYIN NAME MyArray INDEX '4' VALUE %0100
.ARRAYIN NAME MyArray INDEX '5' VALUE %0101
.ARRAYIN NAME MyArray INDEX '6' VALUE %0110
.ARRAYIN NAME MyArray INDEX '7' VALUE %0111
.ARRAYIN NAME MyArray INDEX '8' VALUE %1000
.ARRAYIN NAME MyArray INDEX '9' VALUE %1001
// map!
.ARRAYOUT NAME MyArray INDEX '6' DEFINITION Mapping
.DB Mapping
.ARRAYOUT NAME MyArray INDEX '6' DEFINITION Mapping
.DB Mapping
.ARRAYOUT NAME MyArray INDEX '8' DEFINITION Mapping
.DB Mapping
.ARRAYOUT NAME MyArray INDEX '2' DEFINITION Mapping
.DB Mapping
.ARRAYOUT NAME MyArray INDEX '7' DEFINITION Mapping
.DB Mapping
.ARRAYOUT NAME MyArray INDEX '5' DEFINITION Mapping
.DB Mapping
You can also do the mapping using e.g., .ARRAYDB
:
.ARRAYDB NAME MyArray INDICES '6', '6', '8', '2', '7', '5'
.ARRAYDB NAME MyArray INDICES "668275"
And create the mapping using only one .ARRAYIN
:
.ARRAYIN NAME MyArray INDEX '0' VALUES %0000, %0001, \
%0010, %0011, %0100, %0101, %0110, %0111, %1000, \
%1001
Note that keywords NAME and SIZE are optional, so this works also:
.ARRAYDEFINE MyArray 4
This is not a compulsory directive.
3.11. .ARRAYDL NAME MyArray INDICES '0', 0, 1
¶
.ARRAYDL
works the same way as .ARRAYDB
, but defines 24-bit long words.
This is not a compulsory directive.
3.12. .ARRAYDW NAME MyArray INDICES '0', 0, 1
¶
.ARRAYDW
works the same way as .ARRAYDB
, but defines 16-bit words.
This is not a compulsory directive.
3.13. .ARRAYIN NAME MyArray INDEX 0 VALUE 10
¶
Writes a value into an array defined using .ARRAYDEFINE
. Check out
.ARRAYDEFINE
for a nice example. The value needs to be known at the
time the assembler is parsing through the code.
Keywords NAME, INDEX and VALUE are optional so this works also:
.ARRAYIN MyArray 0 10
This is not a compulsory directive.
3.14. .ARRAYOUT NAME MyArray INDEX 0 DEFINITION ArrayOut
¶
Reads a value from an array defined using .ARRAYDEFINE
. Check out
.ARRAYDEFINE
for a nice example. The value is stored in definition
ArrayOut
in the example.
Keywords NAME, INDEX and DEFINITION are optional so this works also:
.ARRAYOUT MyArray 0 ArrayOut
This is not a compulsory directive.
3.15. .ASC "HELLO WORLD!"
¶
.ASC
is an alias for .DB
, but if you use .ASC
it will remap
the characters using the mapping given via .ASCIITABLE
.
You can also use ASC(‘?’) to map individual characters in the code
.DB ASC('A'), ASC('B'), ASC(10), ASC('\r')
and
LD A, ASC(‘A’)
This is not a compulsory directive.
3.16. .ASCIITABLE
¶
.ASCIITABLE
’s only purpose is to provide character mapping for .ASC
and ASC('?')
. Take a look at the example:
.ASCIITABLE
MAP "A" TO "Z" = 0
MAP "!" = 90
.ENDA
Here we set such a mapping that character A
is equal to 0
, B
is
equal to 1
, C
is equal to 2
, and so on, and !
is equal
to 90
.
After you’ve given the .ASCIITABLE
, use .ASC
to define bytes using
this mapping (.ASC
is an alias for .DB
, but with .ASCIITABLE
mapping). For example, .ASC "ABZ"
would define bytes 0
, 1
and
25
in our previous example.
Note that the following works as well:
.ASCIITABLE
MAP 'A' TO 'Z' = 0
MAP 65 = 90 ; 65 is the decimal for ASCII 'A'
.ENDA
Also note that the characters that are not given any mapping in
.ASCIITABLE
map to themselves (i.e., 2
maps to 2
in our previous
example, etc.).
This is not a compulsory directive.
3.17. .ASCSTR "HELLO WORLD!", $A
¶
.ASCSTR
is the same as .ASC
, but it maps only supplied strings. All given
bytes are not touched.:
.ASCSTR "HELLO WORLD!", $A
In this example the string “HELLO WORLD!” is mapped using the mapping given via
.ASCIITABLE
, but the last byte $A is left as it is.
This is not a compulsory directive.
3.18. .ASCTABLE
¶
.ASCTABLE
is an alias for .ASCIITABLE
.
This is not a compulsory directive.
3.19. .ASM
¶
Tells WLA to start assembling. Use .ASM
to continue the work which has been
disabled with .ENDASM
. .ASM
and .ENDASM
can be used to mask away
big blocks of code. This is analogous to the ANSI C -comments (/*...*/
),
but .ASM
and .ENDASM
can be nested, unlike the ANSI C -counterpart.
This is not a compulsory directive.
3.20. .ASSERT VALUE_1 == 1
¶
.ASSERT
takes a condition, and if it’s evaluated to be true, nothing happens. If
it’s false, then assembling ends right there in an error.
This is not a compulsory directive.
3.21. .BACKGROUND "parallax.gb"
¶
This chooses an existing ROM image (parallax.gb
in this case) as a
background data for the project. You can overwrite the data with OVERWRITE
sections only, unless you first clear memory blocks with .UNBACKGROUND
after which there’s room for other sections as well.
Note that .BACKGROUND
can be used only when compiling an object file.
.BACKGROUND
is useful if you wish to patch an existing ROM image with
new code or data.
This is not a compulsory directive.
3.22. .BANK 0 SLOT 1
¶
Defines the ROM bank and the slot it is inserted into in the memory. You can also type the following:
.BANK 0
This tells WLA to move into BANK 0 which will be put into the DEFAULTSLOT
of .MEMORYMAP
.
Every time you use .BANK
, supply .ORG
/ .ORGA
as well, just to make
sure WLA calculates addresses correctly.
This is a compulsory directive.
3.23. .BASE $80
¶
Defines the base value for the bank number (used only in 24-bit addresses and
when getting a label’s bank number with :
). Here are few examples of how
to use .BASE
(both examples assume the label resides in the first ROM
bank):
.BASE $00
label1:
.BASE $80
label2:
JSL label1 ; if label1 address is $1234, this will assemble into
; JSL $001234
JSL label2 ; label2 is also $1234, but this time the result will be
; JSL $801234
.BASE
defaults to $00
. Note that the address of the label will also
contribute to the bank number (bank number == .BASE
+ ROM bank of the
label).
On 65816, use .LOROM
, .HIROM
or .EXHIROM
to define the ROM mode.
This is not a compulsory directive.
3.24. .BITS 4 DATA %1011, %0100, %1010, %0101
¶
This is the same as .DB
, but defines bits (1-32). Consecutive .BITS
will supply bits to the same bitstream, so don’t do any stream breaking
.DB
calls or anything that defines data. DATA
is optional. Give
.BITS START
to start a new bitstream.
Here’s an example of how to define two bytes worth of bits:
.BITS 6 CABBAGE, %011110 ; CABBAGE == %110011
.BITS 4 8+2 ; 8 + 2 == %1010
.BITS 4 %1011
.ENDBITS ; writes the final byte in the bitstream
; and resets the counters
If your .BITS
bitstream doesn’t define exactly a multiple of 8 bits,
the remaining bits are set to zero. Remember to issue .ENDBITS
after
the last .BITS
.
Currently the bits are written from most significant bit to the least significant bit, so our previous example would give us (consecutive) bytes %11001101, %11101010 and %10110000 ($CD, $EA and $B0).
This is not a compulsory directive.
3.25. .BLOCK "Block1"
¶
Begins a block (called Block1
in the example). These blocks have only
one function: to display the number of bytes they contain. When you
embed such a block into your code, WLA displays its size when it assembles
the source file.
Use .ENDB
to terminate a .BLOCK
. Note that you can nest .BLOCK
s.
This is not a compulsory directive.
3.26. .BR
¶
Inserts a breakpoint that behaves like a .SYM
without a name. Breakpoints
can only be seen in WLALINK’s symbol file.
This is not a compulsory directive.
3.27. .BREAK
¶
Exits the active .REPEAT
or .WHILE
.
This is not a compulsory directive.
3.28. .BREAKPOINT
¶
.BREAKPOINT
is an alias for .BR
.
This is not a compulsory directive.
3.29. .BYT 100, $30, %1000, "HELLO WORLD!"
¶
.BYT
is an alias for .DB
.
This is not a compulsory directive.
3.30. .CARTRIDGETYPE 1
¶
Indicates the type of the cartridge (mapper and so on). This is a standard
Gameboy cartridge type indicator value found at $147
in a Gameboy ROM, and
there this one is put to also.
This is not a compulsory directive.
3.31. .COMPUTEGBCHECKSUM
¶
When this directive is used WLA computes the ROM checksum found at $14E
and
$14F
in a Gameboy ROM. Note that this directive can only be used with
WLA-GB.
Note that you can also write .COMPUTECHECKSUM
(the old name for this
directive), but it’s not recommended.
This is not a compulsory directive.
3.32. .COMPUTEGBCOMPLEMENTCHECK
¶
When this directive is used WLA computes the ROM complement check found at
$14D
in a Gameboy ROM.
Note that you can still use .COMPUTECOMPLEMENTCHECK
(the old name for this
directive), but it’s not recommended.
This is not a compulsory directive.
3.33. .COMPUTESMDCHECKSUM
¶
When this directive is used WLA computes the Sega Mega Drive ROM checksum
found at $18E
. Note that this directive works only with WLA-68000.
This is not a compulsory directive.
3.34. .COMPUTESMSCHECKSUM
¶
When this directive is used WLA computes the ROM checksum found at $7FFA
and $7FFB
(or $3FFA
- $3FFB
is the ROM is 16KBs, or
$1FFA
- $1FFB
for 8KB ROMs) in a SMS/GG ROM. Note that this directive
can only be used with WLA-z80. Also note that the ROM size must be at least
8KBs. The checksum is calculated using bytes
0x0000
- 0x1FEF
/ 0x3FEF
/ 0x7FEF
.
This is not a compulsory directive.
3.35. .COMPUTESNESCHECKSUM
¶
When this directive is used WLA computes the SNES ROM checksum and
inverse checksum found at $7FDC
- $7FDF
(LoROM), $FFDC
- $FFDF
(HiROM) or $40FFDC
- $40FFDF
and $FFDC
- $FFDF
(ExHiROM).
Note that this directive can only be used with WLA-65816. Also note
that the ROM size must be at least 32KB for LoROM images, 64KB for
HiROM images and 32.5MBit for ExHiROM.
.LOROM
, .HIROM
or .EXHIROM
must be issued before .COMPUTESNESCHECKSUM
.
This is not a compulsory directive.
3.36. .CONTINUE
¶
Jumps to the beginning of an active .REPEAT
or .WHILE
.
This is not a compulsory directive.
3.37. .COUNTRYCODE 1
¶
Indicates the country code located at $14A
of a Gameboy ROM.
This is not a compulsory directive.
3.38. .DATA $ff00, 2
¶
Defines bytes after a .TABLE has been used to define the format. An alternative way of defining bytes to .DB/.DW.
Note that when you use .DATA you can give as many items .TABLE defines. The next time you’ll use .DATA you’ll continue from the point the previous .DATA ended.
Examples:
.TABLE dsw 2, dsb 2
This defines two rows worth of bytes:
.DATA $ff00, $aabb, $10, $20, $1020, $3040, $50, $60
This does the same:
.DATA $ff00, $aabb
.DATA $10, $20
.DATA $1020, $3040
.DATA $50, $60
This is not a compulsory directive.
3.39. .DB 100, $30, %1000, "HELLO WORLD!"
¶
Defines bytes.
This is not a compulsory directive.
3.40. .DBCOS 0.2, 10, 3.2, 120, 1.3
¶
Defines bytes just like .DSB
does, only this time they are filled with
cosine data. .DBCOS
takes five arguments.
The first argument is the starting angle. Angle value ranges from 0
to
359.999
…, but you can supply WLA with values that are out of the range -
WLA fixes them ok. The value can be integer or float.
The second argument descibes the amount of additional angles. The example will define 11 angles.
The third argument is the adder value which is added to the angle value when next angle is calculated. The value can be integer or float.
The fourth and fifth arguments can be seen from the pseudo code below, which
also describes how .DBCOS
works. The values can be integer or float.
Remember that cos
(and sin
) here returns values ranging from
-1
to 1
:
.DBCOS A, B, C, D, E
for (B++; B > 0; B--) {
output_data((D * cos(A)) + E)
A = keep_in_range(A + C)
}
This is not a compulsory directive.
3.41. .DBM filtermacro 1, 2, "encrypt me"
¶
Defines bytes using a filter macro. All the data is passed to filtermacro
in the first argument, one byte at a time, and the byte that actually gets
defined is the value of definition _OUT
(_out
works as well). The
second macro argument holds the offset from the beginning (the first byte) in
bytes (the series being 0
, 1
, 2
, 3
, …).
Here’s an example of a filter macro that increments all the bytes by one:
.macro increment
.redefine _out \1+1
.endm
This is not a compulsory directive.
3.42. .DBRND 20, 0, 10
¶
Defines bytes, just like .DSB
does, only this time they are filled with
(pseudo) random numbers. We use the integrated Mersenne Twister to generate
the random numbers. If you want to seed the random number generator,
use .SEED
.
The first parameter (20
in the example) defines the number of random
numbers we want to generate. The next two tell the range of the random
numbers, i.e. min and max.
Here’s how it works:
.DBRND A, B, C
for (i = 0; i < A; i++)
output_data((rand() % (C-B+1)) + B);
You can also use the following keywords to make the code clearer:
.DBRND COUNT A MIN B MAX C
This is not a compulsory directive.
3.43. .DBSIN 0.2, 10, 3.2, 120, 1.3
¶
Analogous to .DBCOS
, but does sin()
instead of cos()
.
This is not a compulsory directive.
3.44. .DD $1ffffff, $2000000
¶
Defines double words (four bytes each). .DD
takes only numbers, labels and
characters as input, not strings.
This is not a compulsory directive.
3.45. .DDM filtermacro 1, 2, 3
¶
Defines 32-bit words using a filter macro. Works just like .DBM
, .DWM
and .DLM
.
This is not a compulsory directive.
3.46. .DEF IF $FF0F
¶
.DEF
is an alias for .DEFINE
.
This is not a compulsory directive.
3.47. .DEFINE IF $FF0F
¶
Assigns a number or a string to a definition label.
By default all defines are local to the file where they are
presented. If you want to make the definition visible to all the
files in the project, use .EXPORT
or add EXPORT to the end of .DEFINE:
.DEFINE ID_0 0 EXPORT
WARNING: Please declare your definition lexically before using it as otherwise the assembler might make incorrect assumptions about its value and size and choose e.g. wrong opcodes and generate binary that doesn’t run properly.
Here are some examples:
.DEFINE X 1000
.DEFINE FILE "level01.bin"
.DEFINE TXT1 "hello and welcome", 1, "to a new world...", 0
.DEFINE BYTES 1, 2, 3, 4, 5
.DEFINE COMPUTATION X+1
.DEFINE DEFAULTV
All definitions with multiple values are marked as data strings,
and .DB
is about the only place where you can later on use them:
.DEFINE BYTES 1, 2, 3, 4, 5
.DB 0, BYTES, 6
is the same as:
.DB 0, 1, 2, 3, 4, 5, 6
If you omit the definition value (in our example DEFAULTV
), WLA
will default to 0
.
Note that you must do your definition before you use it, otherwise WLA will use the final value of the definition. Here’s an example of this:
.DEFINE AAA 10
.DB AAA ; will be 10.
.REDEFINE AAA 11
but:
.DB AAA ; will be 11.
.DEFINE AAA 10
.REDEFINE AAA 11
You can also create definitions on the command line. Here’s an example of this:
wla-gb -vl -DMOON -DNAME=john -DPRICE=100 -DADDRESS=$100 math.s
MOON
’s value will be 0
, NAME
is a string definition with value
john
, PRICE
’s value will be 100
, and ADDRESS
’s value will be
$100
.
Note that:
.DEFINE AAA = 10 ; the same as ".DEFINE AAA 10".
works as well. And this works also:
AAA = 10
This is not a compulsory directive.
3.48. .DESTINATIONCODE 1
¶
.DESTINATIONCODE
is an alias for .COUNTRYCODE
.
This is not a compulsory directive.
3.49. .DL $102030, $405060
¶
Defines long words (three bytes each). .DL
takes only numbers, labels and
characters as input, not strings.
This is not a compulsory directive.
3.50. .DLM filtermacro 1, 2, 3
¶
Defines 24-bit words using a filter macro. Works just like .DBM
, .DWM
and .DDM
.
This is not a compulsory directive.
3.51. .DS 256, $10
¶
.DS
is an alias for .DSB
.
This is not a compulsory directive.
3.52. .DSB 256, $10
¶
Defines 256
bytes of $10
.
This is not a compulsory directive.
3.53. .DSD 256, $1ffffff
¶
Defines 256
double words (four bytes) of $1ffffff
.
This is not a compulsory directive.
3.54. .DSL 16, $102030
¶
Defines 16
long words (three bytes) of $102030
.
This is not a compulsory directive.
3.55. .DSTRUCT waterdrop INSTANCEOF water VALUES
¶
Defines an instance of .STRUCT
water, called waterdrop, and fills
it with the given data. Before calling .DSTRUCT
we must have defined
the structure, and in this example it could be like:
.STRUCT water
name ds 8
age db
weight dw
.ENDST
There are two syntaxes for .DSTRUCT
; the new and legacy versions. To use
the new syntax, put the keyword VALUES
at the end of the first line.
The old syntax uses the keyword DATA
or none at all.
The new syntax looks like this:
.DSTRUCT waterdrop INSTANCEOF water VALUES
name: .db "tingle"
age: .db 40
weight: .dw 120
.ENDST
The fields can be put in any order. Any omitted fields are set to the
.EMPTYFILL
value ($00
by default). Any data-defining directive
can be used within .DSTRUCT
, as long as it does not exceed the size of
the data it is being defined for. The only exception is .DSTRUCT
itself,
which cannot be nested.
The old syntax looks like this:
.DSTRUCT waterdrop INSTANCEOF water DATA "tingle", 40, 120
The DATA
and INSTANCEOF
keywords are optional. This will assign
data for each field of the struct in the order they were defined.
In either example you would get the following labels:
waterdrop
waterdrop.name
waterdrop.age
waterdrop.weight
_sizeof_waterdrop = 11
_sizeof_waterdrop.name = 8
_sizeof_waterdrop.age = 1
_sizeof_waterdrop.weight = 2
The legacy syntax does not support unions; it will give an error if you attempt to define data for a union.
For the new syntax, nested structs are supported like so (assume the
water
struct is also defined:
.STRUCT drop_pair
waterdrops: instanceof water 2
.ENDST
.DSTRUCT drops INSTANCEOF drop_pair VALUES
waterdrops.1: .db "qwertyui" 40
.dw 120
waterdrops.2.name: .db "tingle"
waterdrops.2.age: .db 40
waterdrops.2.weight: .dw 12
.ENDST
In this case, the properties of waterdrops.1
were defined
implicitly; 8 bytes for the name, followed by a byte for the age,
followed by a word for the weight. The values for waterdrops.2
were
defined in a more clear way.
In this case, waterdrops
and waterdrops.1
are equivalent.
waterdrops.1.name
is different, even though its address is the same,
because it has a size of 8. If you attempted to do this:
.DSTRUCT drops INSTANCEOF drop_pair VALUES
waterdrops.1.name: .db "qwertyui" 40
.dw 120
.ENDST
It would fail, because only the 8 name bytes are available to be defined
in this context, as opposed to the 11 bytes for the entire
waterdrops.1
structure.
Named unions can be assigned to in a similar way, by writing its full
name with a .
separating the union name and the field name.
The struct can be defined namelessly:
.DSTRUCT INSTANCEOF drop_pair VALUES
...
.ENDST
You can use SIZE
to specify the size of the instance. The additional
bytes are filled with .EMPTYFILL
:
.DSTRUCT INSTANCEOF drop_pair SIZE 128 VALUES
...
.ENDST
If you don’t want to generate labels use NOLABELS
:
.DSTRUCT INSTANCEOF drop_pair NOLABELS VALUES
...
.ENDST
Here’s another example using the legacy syntax:
.DSTRUCT INSTANCEOF water SIZE 32 NOLABELS DATA "Ocean", 100, 16384
This is not a compulsory directive.
3.56. .DSW 128, 20
¶
Defines 128
words (two bytes) of 20
.
This is not a compulsory directive.
3.57. .DW 16000, 10, 255
¶
Defines words (two bytes each). .DW
takes only numbers, labels and
characters as input, not strings.
This is not a compulsory directive.
3.58. .DWCOS 0.2, 10, 3.2, 1024, 1.3
¶
Analogous to .DBCOS
(but defines 16-bit words).
This is not a compulsory directive.
3.59. .DWM filtermacro 1, 2, 3
¶
Defines 16-bit words using a filter macro. Works just like .DBM
, .DLM
and .DDM
.
This is not a compulsory directive.
3.60. .DWRND 20, 0, 10
¶
Analogous to .DBRND
(but defines words).
This is not a compulsory directive.
3.61. .DWSIN 0.2, 10, 3.2, 1024, 1.3
¶
Analogous to .DBCOS
(but defines 16-bit words and does sin()
instead of
cos()
).
This is not a compulsory directive.
3.62. .ELIF defined(DEBUG) && VERSION > 110
¶
.ELIF
means ELSE IF
. Can be used after an .IF
and the likes in
following fashion
.IF VERSION == 101
.db 1
.ELIF VERSION == 102
.db 2
.ELIF VERSION == 103
.db 3
.ELSE
.db $ff
.ENDIF
This is not a compulsory directive.
3.63. .ELSE
¶
If the previous .IFxxx
failed then the following text until
.ENDIF
is acknowledged.
This is not a compulsory directive.
3.64. .EMPTYFILL $C9
¶
This byte is used in filling the unused areas of the ROM file. EMPTYFILL
defaults to $00
.
This is not a compulsory directive.
3.65. .ENDASM
¶
Tells WLA to stop assembling. Use .ASM
to continue the work.
This is not a compulsory directive.
3.66. .ENDA
¶
Ends the ASCII table.
This is not a compulsory directive, but when .ASCIITABLE
or .ASCTABLE
are used this one is required to terminate them.
3.67. .ENDB
¶
Terminates .BLOCK
.
This is not a compulsory directive, but when .BLOCK
is used this one is
required to terminate it.
3.68. .ENDBITS
¶
Terminates .BITS
.
This is not a compulsory directive, but when .BITS
is used this one is
required to terminate it.
3.69. .ENDEMUVECTOR
¶
Ends definition of the emulation mode interrupt vector table.
This is not a compulsory directive, but when .SNESEMUVECTOR
is used this one is required to terminate it.
3.70. .ENDE
¶
Ends the enumeration.
This is not a compulsory directive, but when .ENUM
is used this one is
required to terminate it.
3.71. .ENDIF
¶
This terminates any .IFxxx
directive.
This is not a compulsory directive, but if you use any .IFxxx
then
you need also to apply this.
3.72. .ENDME
¶
Terminates .MEMORYMAP
.
This is not a compulsory directive, but when .MEMORYMAP
is used this one
is required to terminate it.
3.73. .ENDM
¶
Ends a .MACRO
.
This is not a compulsory directive, but when .MACRO
is used this one is
required to terminate it.
3.74. .ENDNATIVEVECTOR
¶
Ends definition of the native mode interrupt vector table.
This is not a compulsory directive, but when .SNESNATIVEVECTOR
is used this one is required to terminate it.
3.75. .ENDRO
¶
Ends the rom bank map.
This is not a compulsory directive, but when .ROMBANKMAP
is used this
one is required to terminate it.
3.76. .ENDR
¶
Ends the .REPEAT
or .WHILE
.
This is not a compulsory directive, but when .REPEAT
or .WHILE
is
used this one is required to terminate it.
3.77. .ENDSNES
¶
This ends the SNES header definition.
This is not a compulsory directive, but when .SNESHEADER
is used this
one is required to terminate it.
3.78. .ENDST
¶
Ends the structure definition.
This is not a compulsory directive, but when .STRUCT
is used this one is
required to terminate it.
3.79. .ENDS
¶
Ends the section.
This is not a compulsory directive, but when .SECTION
or .RAMSECTION
is used this one is required to terminate it.
3.80. .ENDU
¶
Ends the current union.
3.81. .ENUM $C000
¶
Starts enumeration from $C000
. Very useful for defining variables.
To start a descending enumeration, put DESC
after the starting
value. WLA defaults to ASC
(ascending enumeration).
You can also add EXPORT
after these if you want to export all
the generated definitions automatically.
Here’s an example of .ENUM
:
.STRUCT mon ; check out the documentation on
name ds 2 ; .STRUCT
age db
.ENDST
.ENUM $A000
_scroll_x DB ; db - define byte (byt and byte work also)
_scroll_y DB
player_x: DW ; dw - define word (word works also)
player_y: DW
map_01: DS 16 ; ds - define size (bytes)
map_02 DSB 16 ; dsb - define size (bytes)
map_03 DSW 8 ; dsw - define size (words)
monster INSTANCEOF mon 3 ; three instances of structure mon
dragon INSTANCEOF mon ; one mon
.ENDE
Previous example transforms into following definitions:
.DEFINE _scroll_x $A000
.DEFINE _scroll_y $A001
.DEFINE player_x $A002
.DEFINE player_y $A004
.DEFINE map_01 $A006
.DEFINE map_02 $A016
.DEFINE map_03 $A026
.DEFINE monster $A036
.DEFINE monster.1 $A036
.DEFINE monster.1.name $A036
.DEFINE monster.1.age $A038
.DEFINE monster.2 $A039
.DEFINE monster.2.name $A039
.DEFINE monster.2.age $A03B
.DEFINE monster.3 $A03C
.DEFINE monster.3.name $A03C
.DEFINE monster.3.age $A03E
.DEFINE dragon $A03F
.DEFINE dragon.name $A03F
.DEFINE dragon.age $A041
DB
, DW
, DS
, DSB
, DSW
and INSTANCEOF
can also be in
lowercase. You can also use a dotted version of the symbols, but it doesn’t
advance the memory address. Here’s an example:
.ENUM $C000 DESC EXPORT
bigapple_h db
bigapple_l db
bigapple: .dw
.ENDE
And this is what is generated:
.DEFINE bigapple_h $BFFF
.DEFINE bigapple_l $BFFE
.DEFINE bigapple $BFFE
.EXPORT bigapple, bigapple_l, bigapple_h
This way you can generate a 16-bit variable address along with pointers to its parts.
Here’s another example with a nameless INSTANCEOF:
.STRUCT position_t
pos_x DW
pos_y DW
.ENDST
.STRUCT enemy_t
id DW
INSTANCEOF position_t ; here we import fields from position_t
health DW
.ENDST
.ENUM $A000
nemesis INSTANCEOF enemy_t
.ENDE
Regarding nemesis, you’ll get these definitions:
.DEFINE nemesis $A000
.DEFINE nemesis.id $A000
.DEFINE nemesis.pos_x $A002
.DEFINE nemesis.pos_y $A004
.DEFINE nemesis.health $A006
If you want more flexible variable positioning, take a look at
.RAMSECTION
s.
You can also specify the size of an instantiated struct (padding added at the end)
using the keyword SIZE
. Also use keyword COUNT
to make things more clear:
.STRUCT mon ; the size of this .STRUCT is 3 (bytes)
name ds 2
age db
.ENDST
.ENUM $A000
monsters INSTANCEOF mon SIZE 4 COUNT 2 ; two instances of structure mon.
.ENDE ; each instance is padded to 4 bytes.
Note that in the previous example we’ll also get extra definitions
_paddingof_monsters.1 (== 1) _paddingof_monsters.2 (== 1)
This is not a compulsory directive.
3.82. .ENUMID ID_1 0
¶
.ENUMID
will create definitions with an autoincrementing value.
For example:
.ENUMID 0
.ENUMID ID_1
.ENUMID ID_2
.ENUMID ID_3
… will create the following definitions:
ID_1 = 0
ID_2 = 1
ID_3 = 2
You can also specify the adder:
.ENUMID 0 STEP 2
.ENUMID MONSTER_ID_1
.ENUMID MONSTER_ID_2
.ENUMID MONSTER_ID_3
… to create definitions:
MONSTER_ID_1 = 0
MONSTER_ID_2 = 2
MONSTER_ID_3 = 4
If you wish to export the definitions automatically, use EXPORT:
.ENUMID 16 STEP 2 EXPORT
.ENUMID MUSIC_1
.ENUMID MUSIC_2
.ENUMID MUSIC_3
… will create the following definitions and export them all:
MUSIC_1 = 16
MUSIC_2 = 18
MUSIC_3 = 20
This is not a compulsory directive.
3.83. .EQU IF $FF0F
¶
.EQU
is an alias for .DEFINE
.
This is not a compulsory directive.
3.84. .EXHIROM
¶
With this directive you can define the SNES ROM mode to be ExHiROM.
Issuing .EXHIROM
will override the user’s ROM bank map when
WLALINK computes 24-bit addresses and bank references. If no
.HIROM
, .LOROM
or .EXHIROM
are given then WLALINK obeys the
banking defined in .ROMBANKMAP
.
.EXHIROM
also sets the ROM mode bit in $40FFD5
(mirrored in
$FFD5
).
This is not a compulsory directive.
3.85. .EXPORT work_x
¶
Exports the definition work_x
to outside world. Exported definitions are
visible to all object files and libraries in the linking procedure. Note
that you can only export value definitions, not string definitions.
You can export as many definitions as you wish with one .EXPORT
:
.EXPORT NUMBER, NAME, ADDRESS, COUNTRY
.EXPORT NAME, AGE
This is not a compulsory directive.
3.86. .FAIL "THE EYE OF MORDOR HAS SEEN US!"
¶
Terminates the compiling process. You can also specify the error code:
.FAIL 2
These work as well:
.FAIL
.FAIL "EXIT CODE IS 1"
.FAIL "UH OH..." 3
By default, if you don’t specify the error code, it’ll be 1.
This is not a compulsory directive.
3.87. .FARADDR main, irq_1
¶
.FARADDR
is an alias for .DL
.
This is not a compulsory directive.
3.88. .FASTROM
¶
Sets the ROM memory speed bit in $FFD5
(.HIROM
), $7FD5
(.LOROM
)
or $FFD5
and $40FFD5
(.EXHIROM
) to indicate that the SNES ROM chips
are 120ns chips.
This is not a compulsory directive.
3.89. .FCLOSE FP_DATABIN
¶
Closes the filehandle FP_DATABIN
.
This is not a compulsory directive.
3.90. .FILTER filtermacro 1, 2, "encrypt me"
¶
Runs the supplied data, in bytes, through a filter macro. All the data is
passed to filtermacro
in the first argument, one byte at a time. The
second macro argument holds the offset from the beginning (the first byte) in
bytes (the series being 0
, 1
, 2
, 3
, …).
Here’s an example of a filter macro that defines bits (four per byte):
.macro increment
.bits 4 \1
.endm
Here’s a bigger example where we map some ASCII characters into 4 bits per char:
// define an array for mapping ASCII values into less bits
.ARRAYDEFINE NAME MapArray SIZE 4
.ARRAYIN NAME MapArray INDEX 'A' VALUES %0000, %0001, %0010, \
%0011, %0100, %0101, %0110 // defines mappings for A-G
.ARRAYIN NAME MapArray INDEX 0 VALUE %1111
.MACRO MapInto4Bits
.ARRAYOUT NAME MapArray INDEX \1 DEFINITION MAPPING
.BITS 4 MAPPING
.IF \1 == 0
.ENDBITS
.ENDIF
.ENDM
.FILTER MapInto4Bits "BAGED", 0
This is not a compulsory directive.
3.91. .FOPEN "data.bin" FP_DATABIN
¶
Opens the file data.bin
for reading and associates the filehandle with
name FP_DATABIN
.
This is not a compulsory directive.
3.92. .FREAD FP_DATABIN DATA
¶
Reads one byte from FP_DATABIN
and creates a definition called
DATA
to hold it. DATA
is an ordinary definition label, so you can
.UNDEFINE
it.
Here’s an example on how to use .FREAD
:
.fopen "data.bin" fp
.fsize fp t
.repeat t
.fread fp d
.db d+26
.endr
.undefine t, d
This is not a compulsory directive.
3.93. .FSEEK FP_DATABIN 10 START
¶
Sets the file position of the given file pointer. There are three modes:
.FSEEK FP_DATABIN 10 START ; 10 bytes from the beginning of the file
.FSEEK FP_DATABIN -10 END ; 10 bytes before the end of the file
.FSEEK FP_DATABIN 10 CURRENT ; 10 bytes forward from the current
; position
This is not a compulsory directive.
3.94. .FSIZE FP_DATABIN SIZE
¶
Creates a definition called SIZE
, which holds the size of the file
associated with the filehandle FP_DATABIN
. SIZE
is an ordinary
definition label, so you can .UNDEFINE
it.
This is not a compulsory directive.
3.95. .FTELL FP_DATABIN POSITION
¶
Creates a definition called POSITION
, which holds the file position
of the file associated with the filehandle FP_DATABIN
. POSITION
is an ordinary definition label, so you can .UNDEFINE
it.
This is not a compulsory directive.
3.96. .FUNCTION SUM_AB(varA,varB)
¶
Creates a function called SUM_AB
. Here are some examples:
.FUNCTION SUM_AB(varA, varB) (varA + varB)
.FUNCTION SUB_A_6(varA) varA-6
.FUNCTION SUM_ABC(varA, varB, varC) (SUM_AB(varA. varB) + varC)
.FUNCTION CONSTANT_1() 1
.FUNCTION
can be used anywhere values are expected:
LDA SUM_AB(1, 2)
.DEFINE SUM = 0 + 1 + SUM_AB(2, 3) + 4 + 5
This is not a compulsory directive.
3.97. .GBHEADER
¶
This begins the GB header definition, and automatically defines
.COMPUTEGBCHECKSUM
. End the header definition with .ENDGB.
Here’s an example:
.GBHEADER
NAME "TANKBOMBPANIC" ; identical to a freestanding .NAME.
LICENSEECODEOLD $34 ; identical to a freestanding .LICENSEECODEOLD.
LICENSEECODENEW "HI" ; identical to a freestanding .LICENSEECODENEW.
CARTRIDGETYPE $00 ; identical to a freestanding .CARTRIDGETYPE.
RAMSIZE $09 ; identical to a freestanding .RAMSIZE.
ROMSIZE ; identical to a freestanding .ROMSIZE.
COUNTRYCODE $01 ; identical to a freestanding .COUNTRYCODE/DESTINATIONCODE.
DESTINATIONCODE $01 ; identical to a freestanding .DESTINATIONCODE/COUNTRYCODE.
NINTENDOLOGO ; identical to a freestanding .NINTENDOLOGO.
VERSION $01 ; identical to a freestanding .VERSION.
ROMDMG ; identical to a freestanding .ROMDMG.
; Alternatively, ROMGBC or ROMGBCONLY can be used
.ENDGB
This is not a compulsory directive.
3.98. .HEX "a0A0ffDE"
¶
Defines bytes using the supplied string that contains the bytes in
hexadecimal format. For example, the same result can be obtained
using .DB
.DB $a0, $A0, $ff, $DE
.HEX
can also be used in the following ways:
.HEX 01 AA 02 BB 03 CC ; -> .DB $01, $AA, $02, $BB, $03, $CC
.HEX BLOCK
01 02 03 04 05 06 ; -> .DB $01, $02, $03, $04, $05, $06
07 08 09 0A 0B 0C ; -> .DB $07, $08, $09, $0A, $0B, $0C
.ENDHEX
This is not a compulsory directive.
3.99. .HIROM
¶
With this directive you can define the SNES ROM mode to be HiROM.
Issuing .HIROM
will override the user’s ROM bank map when
WLALINK computes 24-bit addresses and bank references. If no
.HIROM
, .LOROM
or .EXHIROM
are given then WLALINK obeys the
banking defined in .ROMBANKMAP
.
.HIROM
also sets the ROM mode bit in $FFD5
.
This is not a compulsory directive.
3.100. .IF DEBUG == 2
¶
If the condition is fulfilled the following piece of code is
acknowledged until .ENDIF
/ .ELSE
/ .ELIF
occurs in the text,
otherwise it is skipped. Operands must be immediate values or strings.
The following operators are supported:
|
not |
|
less than |
|
less or equal to |
|
greater than |
|
greater or equal to |
|
equals to |
|
doesn’t equal to |
|
logical or |
|
logical and |
All IF
directives (yes, including .IFDEF
, .IFNDEF
, etc) can be
nested. They can also be used within ENUM
s, RAMSECTION
s,
STRUCT
s, ROMBANKMAP
s, and most other directives that occupy multiple
lines.
Note that complex conditions are also possible
.IF DEBUG == 2 && defined(HELLO) && exists("main.s")
Here defined() and exists() both return 1 of they are true, and 0 if false. In fact in conditions 0 is false and anything else is considered to be true.
This is not a compulsory directive.
3.101. .IFDEF IF
¶
If IF
is defined, then the following piece of code is acknowledged
until .ENDIF
/ .ELSE
occurs in the text, otherwise it is skipped.
This is not a compulsory directive.
3.102. .IFDEFM \2
¶
If the specified argument is defined (argument number two, in the example),
then the following piece of code is acknowledged until .ENDIF
/ .ELSE
occurs in the macro, otherwise it is skipped.
This is not a compulsory directive. .IFDEFM
works only inside a macro.
3.103. .IFEQ DEBUG 2
¶
If the value of DEBUG
equals to 2
, then the following piece of code is
acknowledged until .ENDIF
/ .ELSE
occurs in the text, otherwise it is
skipped. Both arguments can be computations, defines or immediate values.
This is not a compulsory directive.
3.104. .IFEXISTS "main.s"
¶
If main.s
file can be found, then the following piece of code is
acknowledged until .ENDIF
/ .ELSE
occurs in the text, otherwise it is
skipped.
By writing the following few lines you can include a file if it exists without breaking the compiling loop if it doesn’t exist:
.IFEXISTS FILE
.INCLUDE FILE
.ENDIF
This is not a compulsory directive.
3.105. .IFGR DEBUG 2
¶
If the value of DEBUG
is greater than 2
, then the following piece of
code is acknowledged until .ENDIF
/ .ELSE
occurs in the text, otherwise
it is skipped. Both arguments can be computations, defines or immediate values.
This is not a compulsory directive.
3.106. .IFGREQ DEBUG 2
¶
If the value of DEBUG
is greater or equal to 2
, then the following
pieceof code is acknowledged until .ENDIF
/ .ELSE
occurs in the text,
otherwise it is skipped. Both arguments can be computations, defines or
immediate values.
This is not a compulsory directive.
3.107. .IFLE DEBUG 2
¶
If the value of DEBUG
is less than 2
, then the following piece of code
is acknowledged until .ENDIF
/ .ELSE
occurs in the text, otherwise it is
skipped. Both arguments can be computations, defines or immediate values.
This is not a compulsory directive.
3.108. .IFLEEQ DEBUG 2
¶
If the value of DEBUG
is less or equal to 2
, then the following piece of
code is acknowledged until .ENDIF
/ .ELSE
occurs in the text, otherwise
it is skipped. Both arguments can be computations, defines or immediate values.
This is not a compulsory directive.
3.109. .IFNDEF IF
¶
If IF
is not defined, then the following piece of code is acknowledged
until .ENDIF
/ .ELSE
occurs in the text, otherwise it is skipped.
This is not a compulsory directive.
3.110. .IFNDEFM \2
¶
If the specified argument is not defined, then the following piece of
code is acknowledged until .ENDIF
/ .ELSE
occurs in the macro, otherwise
it is skipped.
This is not a compulsory directive. .IFNDEFM
works only inside a macro.
3.111. .IFNEQ DEBUG 2
¶
If the value of DEBUG
doesn’t equal to 2
, then the following piece of
code is acknowledged until .ENDIF
/ .ELSE
occurs in the text, otherwise
it is skipped. Both arguments can be computations, defines or immediate values.
This is not a compulsory directive.
3.112. .INC "cgb_hardware.i"
¶
INC
is an alias for INCLUDE
.
This is not a compulsory directive.
3.113. .INCBIN "sorority.bin"
¶
Includes the specified data file into the source file. .INCBIN
caches
all files into memory, so you can .INCBIN
any data file millions of
times, but it is loaded from hard drive only once.
You can optionally use SWAP
after the file name, e.g.,
.INCBIN "kitten.bin" SWAP
.INCBIN
data is divided into blocks of two bytes, and inside every block
the bytes are exchanged (like SWAP r
does to nibbles). This requires that
the size of the read data is even.
You can also force WLA to skip n bytes from the beginning of the file by writing for example:
.INCBIN "kitten.bin" SKIP 4
Four bytes are skipped from the beginning of kitten.bin
and the rest
is incbinned.
It is also possible to incbin only n bytes from a file:
.INCBIN "kitten.bin" READ 10 FREADSIZE bytesRead
Will read ten bytes from the beginning of kitten.bin
and create a definition called bytesRead
with value 10. If you make READ
negative, like:
.INCBIN "kitten.bin" READ -2
all bytes except the last two are read. To extend this:
.INCBIN "kitten.bin" SKIP 1 READ -2
and one byte will be skipped at the beginning of the file and two at the end.
You can also force WLA to create a definition holding the size of the file:
.INCBIN "kitten.bin" FSIZE size_of_kitten
Want to circulate all the included bytes through a filter macro? Do this:
.INCBIN "kitten.bin" FILTER filtermacro
The filter macro is executed for each byte of the included data, data
byte being the first argument, and offset from the beginning being the
second parameter, just like in the case of .DBM
, .DWM
, .DLM
and .DDM
.
And you can combine all these four commands:
.INCBIN "kitten.bin" SKIP 10 READ 8 SWAP FSIZE size_of_kitten FILTER filtermacro
This example shows how to incbin eight bytes (swapped) after skipping
10 bytes from the beginning of file kitten.bin
, and how to get the
size of the file into a definition label size_of_kitten
. All the data bytes
are circulated through a filter macro.
Here’s an example of a filter macro that increments all the bytes by one:
.macro filtermacro ; the input byte is \1, the output byte is in "_out"
.redefine _out \1+1 ; \2 is the index of the element
.endm
Instead of passing just one byte at a time to the filter macro, you can specify the chunk size as follows:
.INCBIN "kitten.bin" FILTER filtermacro FILTERSIZE 4
FILTERSIZE
specifies the chunk size of the number of bytes (read) in 1 in the filter
macro. 2 in the macro specifies the index of the chunk and 3 specifies the
size of the chunk (same as FILTERSIZE
). You can still use SWAP
to change
the order of the bytes in 1.
If the file’s not found in the .INCDIR
directory, WLA tries to find it
in the current working directory. If the INCDIR
is specified in the command
line, WLA will first search for the file in that directory. If not found, it
will then proceed as aforementioned.
This is not a compulsory directive.
3.114. .INCDIR "/usr/programming/gb/include/"
¶
Changes the current include root directory. Use this to specify main
directory for the following .INCLUDE
, .INCBIN
and .STRINGMAPTABLE
directives.
If you want to change to the current working directory (WLA also defaults
to this), use:
.INCDIR ""
If the INCDIR
is specified in the command line, that directory will be
searched before the .INCDIR
in the file. If the file is not found, WLA
will then silently search the specified .INCDIR
.
This is not a compulsory directive.
3.115. .INCLUDE "cgb_hardware.i"
¶
Includes the specified file to the source file. If the file’s not found
in the .INCDIR
directory, WLA tries to find it in the current working
directory. If the INCDIR
is specified in the command line, WLA will first
try to find the file specified in that directory. Then proceed as mentioned
before if it is not found.
If you want to prefix all labels inside the included file with something, use:
.INCLUDE "music_player.s" NAMESPACE "musicplayer"
In the case of this example, all sections, macros, labels and references to
those labels inside the included file are prefixed with “musicplayer.”, though
there are a couple of exceptions. If a .SECTION
inside the included file has
its own namespace, the .INCLUDE
‘s namespace doesn’t affect it. If a .SECTION
inside the included file uses APPENDTO
with a section name that starts with
"*:"
, that APPENDTO
is considered to belong to the global namespace and we
won’t prefix it with the .INCLUDE
‘s namespace.
To add the namespace prefix to everything including .DEFINE
s use the keyword
ISOLATED
:
.INCLUDE "music_player.s" NAMESPACE "musicplayer" ISOLATED
Note that a dot is the namespace separator so your namespace cannot contain a dot.
Note that you can create the file name from pieces:
.INCLUDE ROOTDIR, SUBDIR, "cthulhu.s" NAMESPACE "cthulhu"
This might end up looking for a file “root/subdir/cthulhu.s”, depending on the definitions.
If you are using the .INCLUDE
inside a .MACRO
and want to have the file
included only once, use the keyword ONCE
:
.INCLUDE "include_one.s" NAMESPACE "once" ONCE
This is not a compulsory directive.
3.116. .INDEX 8
¶
Forces WLA to override the index (X
/ Y
) register size given with
SEP
/ REP
. .INDEX
doesn’t produce any code, it only affects the way
WLA interprets the immediate values (8
for 8 bit operands, 16
for 16
bit operands) for opcodes dealing with the index registers.
So after giving .INDEX 8
CPX #10
will produce $E0 $A0
, and after giving .INDEX 16
CPX #10
will yield $E0 $00 $A0
.
Note that SEP
/ REP
again will in turn reset the accumulator/index
register size.
This is not a compulsory directive.
3.117. .INPUT NAME
¶
.INPUT
is much like any Basic-language input: .INPUT
asks the user
for a value or string. After .INPUT
is the variable name used to store
the data.
.INPUT
works like .REDEFINE
, but the user gets to type in the data.
Here are few examples how to use input:
.PRINTT "The name of the ROM? "
.INPUT NAME
.NAME NAME
...
.PRINTT "Give the .DB amount.\n"
.INPUT S
.PRINTT "Give .DB data one at a time.\n"
.REPEAT S
.INPUT B
.DB B
.ENDR
...
This is not a compulsory directive.
3.118. .LICENSEECODENEW "1A"
¶
This is a standard new licensee code found at $144
and $145
in a
Gameboy ROM, and there this one is put to also. .LICENSEECODENEW
cannot be
defined with .LICENSEECODEOLD. $33
is inserted into $14B
, as well.
This is not a compulsory directive.
3.119. .LICENSEECODEOLD $1A
¶
This is a standard old licensee code found at $14B
in a Gameboy ROM, and there
this one is put to also. .LICENSEECODEOLD
cannot be defined with
.LICENSEECODENEW
.
This is not a compulsory directive.
3.120. .LONG $102030, $405060
¶
.LONG
is an alias for .DL
.
This is not a compulsory directive.
3.121. .LOROM
¶
With this directive you can define the SNES ROM mode to be LoROM.
Issuing .LOROM
will override the user’s ROM bank map when
WLALINK computes 24-bit addresses and bank references. If no
.HIROM
, .LOROM
or .EXHIROM
are given then WLALINK obeys the
banking defined in .ROMBANKMAP
.
WLA defaults to .LOROM
.
This is not a compulsory directive.
3.122. .MACRO TEST
¶
Begins a macro called TEST
.
You can use \@
inside a macro to e.g., separate a label from the other
macro TEST
occurrences. \@
is replaced with an integer number
indicating the amount of times the macro has been called previously so
it is unique to every macro call. \@
can also be used inside strings
inside a macro or just as a plain value. Look at the following examples
for more information.
You can also type \!
to get the name of the source file currently being
parsed. \.
can be used the same way to get the name of the macro.
Also, if you want to use macro arguments in e.g., calculation, you can
type \X
where X
is the number of the argument. Another way to refer
to the arguments is to use their names given in the definition of the
macro (see the examples for this).
Remember to use .ENDM
to finish the macro definition. Note that you
cannot use .INCLUDE
inside a macro. Note that WLA’s macros are in fact
more like procedures than real macros, because WLA doesn’t substitute
macro calls with macro data. Instead WLA jumps to the macro when it
encounters a macro call at compile time.
You can call macros from inside a macro. Note that the preprocessor does not expand the macros. WLA traverses through the code according to the macro calls.
Here are some examples:
.MACRO NOPMONSTER
.REPT 32 ; gives us 32 NOPs
NOP
.ENDR
.ENDM
.MACRO LOAD_ABCD
LD A, \1
LD B, \2
LD C, \3
LD D, :\4 ; load the bank number of \4 into register D.
NOPMONSTER ; note that \4 must be a label or ROM address
LD HL, 1<<\1 ; for this to work...
.INCBIN \5
.ENDM
.MACRO QUEEN
QUEEN\@:
LD A, \1
LD B, \1
CALL QUEEN\@
.DB "\@", 0 ; will translate into a zero terminated string
; holding the amount of macro QUEEN calls.
.DB "\\@", 0 ; will translate into a string containing
; \@.
.DB \@ ; will translate into a number indicating
; the amount of macro QUEEN calls.
.ENDM
.MACRO LOAD_ABCD_2 ARGS ONE, TWO, THREE, FOUR, FIVE
LD A, ONE ; note! ONE, TWO, THREE, FOUR and FIVE
LD B, TWO ; here are actually definitions that
LD C, THREE ; exist as long as the .MACRO is alive
LD D, FOUR ; so be careful when using named args...
NOPMONSTER
LD HL, 1<<ONE
.INCBIN FIVE
.ENDM
And here’s how they can be used:
NOPMONSTER
LOAD_ABCD $10, $20, $30, XYZ, "merman.bin"
QUEEN 123
LOAD_ABCD_2 $10, $20, $30, XYZ, "merman.bin"
Note that arguments can be optionally wrapped inside parentheses:
NOPMONSTER()
LOAD_ABCD($10, $20, $30, XYZ, "merman.bin")
QUEEN(123)
LOAD_ABCD_2($10, $20, $30, XYZ, "merman.bin")
Note that you must separate the arguments with commas.
Note that the following works as well:
.DEF prev_test $0000
.MACRO test ARGS str
__\._{\@+1}: ; this will become __test_1 during
.PRINT __\._{\@+1}, "\n" ; the first call, __test_2 during the
.WORD prev_test ; second call...
.REDEF prev_test __\._{\@+1}
.BYTE str.length, str, 0
.ENDM
If you want to give names to the macro’s arguments you can do that by listing them in order after supplying ARGS after the macro’s name.
Every time a macro is called a definition NARGS
is created. It shows
only inside the macro and holds the number of arguments the macro
was called with. So don’t have your own definition called NARGS
.
Here’s an example:
.MACRO LUPIN
.IF NARGS != 1
.FAIL
.ENDIF
.PRINTT "Totsan! Ogenki ka?\n"
.ENDM
You can also use \?
to ask for the type of the argument in the
following fashion:
.macro differentThings
.if \?1 == ARG_IMMEDIATE
.db \1
.elif \?1 == ARG_NUMBER
.db 1
.elif \?1 == ARG_STRING
.db 2
.elif \?1 == ARG_LABEL
.db 3
.elif \?1 == ARG_PENDING_CALCULATION
.db 4
.endif
.endm
.section "TestingDifferentThings"
TDT1:
differentThings 100
differentThings "HELLO"
differentThings TDT1
differentThings TDT1+1
differentThings #0
.ends
The previous example will result in .db 1, 2, 3, 4, 0
Here’s another useful example:
.DEFINE DEFINITION_A 1
.MACRO REDEFINER
.REDEFINE \1 = ?1 + 1 ; \1 here is the definition's name,
.ENDM ; and ?1 is its value.
REDEFINER &DEFINITION_A ; here we feed the definition's name
; as first argument, not it's value
Another useful example:
.MACRO LOOP ISOLATED
LD A, 10
- DEC A ; B
JP NZ, -
.ENDM
...
LD B, 20
- LOOP ; C
DEC B
JP NZ, - ; A
...
Here we use the keyword ISOLATED
to make un-named labels inside the
macro to be isolated from the outside world. Without it the jump in A
would jump to B, but now it jumps to C.
Using the keyword ISOLATED
we would also make the macro to have its own
child label stack:
.macro MACROM
AA03: .db 0
@child: .db 1 ; A
.dw @child ; B
.endm
AA00: .db "25>"
@child: MACROM ; C
.dw @child ; D
.db "<25"
In this case B points to A and D points to A. If you add keyword ISOLATED
to .MACRO
MACROM then B still points to A, but A doesn’t leak out of MACROM
and D points to C. Exiting a .MACRO
that uses keyword ISOLATED
restores
the child label stack.
One example more, but this time with local labels:
.macro LOCALS isolated
_hello: .db 0 ; A
.dw _hello + 1 ; B
.endm
_hello: .db "27>" ; C
.db 0, 1, 2
LOCALS
.dw _hello + 2 ; D
.db "<27"
Normally this would create the local label _hello
twice and it would not
work. Adding the keyword ISOLATED
to .MACRO
makes the local labels
unique and D points to C and B points to A.
To enable only local label isolation use the keyword ISOLATELOCAL
instead of
ISOLATED
and to enable only the isolation of un-named labels use the keyword
ISOLATEUNNAMED
.
Note that there is an alternative way of defining a .MACRO
:
.macro DBSUMOFTWOVALUES(v1,v2) isolated
.db v1+v2
.endm
This is not a compulsory directive.
3.123. .MEMORYMAP
¶
Begins the memory map definition. Using .MEMORYMAP
you must first
describe the target system’s memory architecture to WLA before it
can start to compile the code. .MEMORYMAP
gives you the freedom to
use WLA to compile data for numerous different real systems.
Examples:
.MEMORYMAP
DEFAULTSLOT 0
SLOTSIZE $4000
SLOT 0 $0000
SLOT 1 $4000
.ENDME
.MEMORYMAP
DEFAULTSLOT 0
SLOT 0 $0000 $4000 "ROMSlot"
SLOT 1 $4000 $4000 "RAMSlot"
.ENDME
.MEMORYMAP
DEFAULTSLOT 0
SLOT 0 START $0000 SIZE $4000 NAME "ROMSlot"
SLOT 1 START $4000 SIZE $4000 NAME "RAMSlot"
.ENDME
.MEMORYMAP
DEFAULTSLOT 1
SLOTSIZE $6000
SLOT 0 $0000
SLOTSIZE $2000
SLOT 1 $6000
SLOT 2 $8000
.ENDME
Here’s a real life example from Adam Klotblixt. It should be interesting for all the ZX81 coders:
...
.MEMORYMAP
DEFAULTSLOT 1
SLOTSIZE $2000
SLOT 0 $0000
SLOTSIZE $6000
SLOT 1 $2000
.ENDME
.ROMBANKMAP
BANKSTOTAL 2
BANKSIZE $2000
BANKS 1
BANKSIZE $6000
BANKS 1
.ENDRO
.BANK 1 SLOT 1
.ORGA $2000
...
SLOTSIZE
defines the size of the following slots, unless you explicitly
specify the size of the slot, like in the second and third examples. You
can redefine SLOTSIZE
as many times as you wish.
DEFAULTSLOT
describes the default slot for banks which aren’t explicitly
inserted anywhere. Check .BANK
definition for more information.
SLOT
defines a slot and its starting address. SLOT
numbering starts at
0
and ends to 255
so you have 256 slots at your disposal.
This is a compulsory directive, and make sure all the object files share
the same .MEMORYMAP
or you can’t link them together.
3.124. .NAME "NAME OF THE ROM"
¶
If .NAME
is used with WLA-GB then the 16 bytes ranging from $0134
to $0143
are filled with the provided string. WLA-65816 fills
the 21 bytes from $FFC0
to $FFD4
in HiROM and from $7FC0
to
$7FD4
in LoROM mode with the name string (SNES ROM title). For ExHiROM
the ranges are from $40FFC0
to $40FFD4
and from $FFC0
to $FFD4
(mirrored).
If the string is shorter than 16/21 bytes the remaining space is
filled with $00
.
This is not a compulsory directive.
3.125. .NEXTU name
¶
Proceeds to the next entry in a union.
3.126. .NINTENDOLOGO
¶
Places the required Nintendo logo into the Gameboy ROM at $104
.
This is not a compulsory directive.
3.127. .NOWDC
¶
Turns WLA-65816 into a mode where it accepts its default syntax assembly code, which doesn’t support WDC standard. This is the default mode for WLA-65816.
This is not a compulsory directive.
3.128. .ORG $150
¶
Defines the starting address. The value supplied here is relative to the
ROM bank given with .BANK
.
When WLA starts to parse a source file, .ORG
is set to $0
, but it’s
always a good idea to explicitly use .ORG
, for clarity.
This is a compulsory directive.
3.129. .ORGA $150
¶
Defines the starting address. The value supplied here is absolute and used
directly in address computations. WLA computes the right position in
ROM file. By using .ORGA
you can instantly see from the source file where
the following code is located in the 16-bit memory.
Here’s an example:
.MEMORYMAP
SLOTSIZE $4000
DEFAULTSLOT 0
SLOT 0 $0000
SLOT 1 $4000
.ENDME
.ROMBANKMAP
BANKSTOTAL 2
BANKSIZE $4000
BANKS 2
.ENDRO
.BANK 0 SLOT 1
.ORGA $4000
MAIN: JP MAIN
Here MAIN
is at $0000
in the ROM file, but the address for label
MAIN
is $4000
. By using .ORGA
instead of .ORG
, you can directly
see from the value the address where you want the code to be as .ORG
is
just an offset to the SLOT
.
3.130. .OUTNAME "other.o"
¶
Changes the name of the output file. Here’s an example:
wla-gb -o test.o test.s
would normally output test.o
, but if you had written:
.OUTNAME "new.o"
somewhere in the code WLA would write the output to new.o
instead.
This is not a compulsory directive.
3.131. .PRINT "Numbers 1 and 10: ", DEC 1, " $", HEX 10, "\n"
¶
Prints strings and numbers to stdout. A combination and a more usable version of .PRINTT and .PRINTV. Useful for debugging.
Optional: Give DEC
(decimal) or HEX
(hexadecimal) before the value you
want to print.
This is not a compulsory directive.
3.132. .PRINTT "Here we are...\n"
¶
Prints the given text into stdout. Good for debugging stuff. PRINTT
takes
only a string as argument, and the only supported formatting symbol is \n
(line feed).
This is not a compulsory directive.
3.133. .PRINTV DEC DEBUG+1
¶
Prints the value of the supplied definition or computation into stdout.
Computation must be solvable at the time of printing (just like definitions
values). PRINTV
takes max two parameters. The first describes the type of the
print output. DEC
means decimal, HEX
means hexadecimal. This is optional.
Default is DEC
.
Use PRINTV
with PRINTT
as PRINTV
doesn’t print linefeeds, only the
result. Here’s an example:
.PRINTT "Value of \"DEBUG\" = $"
.PRINTV HEX DEBUG
.PRINTT "\n"
This is not a compulsory directive.
3.134. .RAMSECTION "Vars" BASE $7E BANK 0 SLOT 1 ALIGN 256 OFFSET 32
¶
RAMSECTION
s accept only variable labels and variable sizes, and the
syntax to define these is identical to .ENUM
(all the syntax rules that
apply to .ENUM
apply also to .RAMSECTION
). Additionally you can embed
structures (.STRUCT
) into a RAMSECTION
. Here’s an example:
.RAMSECTION "Some of my variables" BANK 0 SLOT 1 RETURNORG PRIORITY 100
vbi_counter: db
player_lives: db
.ENDS
By default RAMSECTION
s behave like FREE
sections, but instead of
filling any banks RAM sections will occupy RAM banks inside slots. You can
fill different slots with different variable labels. It’s recommend that
you create separate slots for holding variables (as ROM and RAM don’t
usually overlap).
If you want that WLA returns the ORG
to what it was before issuing
the RAMSECTION
, use the keyword RETURNORG
.
Keyword PRIORITY
means just the same as PRIORITY
of a .SECTION
,
it is used to prioritize some sections when placing them in the output ROM/PRG.
The RAMSECTION
s with higher PRIORITY
are placed first in the output,
and if the priorities match, then bigger RAMSECTION
s are placed first.
NOTE! Currently WLA-DX assumes that there are 256 RAM banks available for
each slot in the memory map. There is no other way to limit this number at the
moment than manually keep the BANK
number inside real limits.
Anyway, here’s another example:
.MEMORYMAP
SLOTSIZE $4000
DEFAULTSLOT 0
SLOT 0 $0000 ; ROM slot 0.
SLOT 1 $4000 ; ROM slot 1.
SLOT 2 $A000 "RAMSlot" ; variable RAM is here!
.ENDME
.STRUCT game_object
x DB
y DB
.ENDST
.RAMSECTION "vars 1" BANK 0 SLOT 2
moomin1 DW
phantom DB
nyanko DB
enemy INSTANCEOF game_object
.ENDS
.RAMSECTION "vars 2" BANK 1 SLOT "RAMSlot" ; Here we use slot 2
moomin2 DW
.ENDS
.RAMSECTION "vars 3" BANK 1 SLOT $A000 ; Slot 2 here as well...
moomin3_all .DSB 3
moomin3_a DB
moomin3_b DB
moomin3_c DB
.ENDS
.RAMSECTION "vars 4" BANK 1 SLOT $A000
enemies INSTANCEOF game_object 2 STARTFROM 0 ; If you leave away "STARTFROM 0" the indexing will start from 1
.ENDS
If no other RAM sections are used, then this is what you will get:
.DEFINE moomin1 $A000
.DEFINE phantom $A002
.DEFINE nyanko $A003
.DEFINE enemy $A004
.DEFINE enemy.x $A004
.DEFINE enemy.y $A005
.DEFINE moomin2 $A000
.DEFINE moomin3_all $A002
.DEFINE moomin3_a $A002
.DEFINE moomin3_b $A003
.DEFINE moomin3_c $A004
.DEFINE enemies $A005
.DEFINE enemies.0 $A005
.DEFINE enemies.0.x $A005
.DEFINE enemies.0.y $A006
.DEFINE enemies.1 $A007
.DEFINE enemies.1.x $A007
.DEFINE enemies.1.y $A008
BANK
in .RAMSECTION
is optional so you can leave it away if you
don’t switch RAM banks, or the target doesn’t have them (defaults to 0).
NOTE! The generated _sizeof_ labels for .RAMSECTION
“vars 3” will be:
_sizeof_moomin3_all (== 3)
_sizeof_moomin3_a (== 1)
_sizeof_moomin3_b (== 1)
_sizeof_moomin3_c (== 1)
Going back to the previous example, if you wanted to make the size of all
instances of game_object
to be 8 (bytes) in enemies
:
.RAMSECTION "vars 4" BANK 1 SLOT $A000
enemies INSTANCEOF game_object SIZE 8 COUNT 2 STARTFROM 0
.ENDS
Use the keyword SIZE
to do that. Also note that the keyword COUNT
is optional, and recommended.
It is also possible to merge two or more sections using APPENDTO
:
.RAMSECTION "RAMSection1" BANK 0 SLOT 0
label1 DB
.ENDS
.RAMSECTION "RAMSection2" APPENDTO "RAMSection1"
label2 DB
.ENDS
NOTE! The APPENDTO
.SECTION
s are appended in the order the linker
sorts them. So first PRIORITY
is considered (0 by default, the bigger the
value the more important it is) and then the size of the .SECTION
is considered,
bigger .SECTION
s are more important than smaller.
If you wist to skip some bytes without giving them labels, use .
as
a label:
.RAMSECTION "ZERO_PAGE" BANK 0 SLOT 0
UsingThisByte1: DB
. DB ; RESERVED
. DB ; RESERVED
UsingThisByte2: DB
. DB ; RESERVED
UsingThisByte3: DB
.ENDS
If you want to use FORCE
RAMSECTIONs that are fixed to a specified
address, do as follows:
.RAMSECTION "FixedRAMSection" BANK 0 SLOT 0 ORGA $0 FORCE
. DB ; SYSTEM RESERVED
. DB ; SYSTEM RESERVED
PlayerX DB
PlayerY DB
.ENDS
Other types that are supported: SEMIFREE
and SEMISUBFREE
.
Note that .ALIGN
also works inside a .RAMSECTION
, but there are
limitations (see .ALIGN
). Here’s an example:
.RAMSECTION "AlignTest" BANK 0 SLOT 1 ALIGN 8
Objects INSTANCEOF game_object COUNT 2
.ALIGN 8
Byte1 DB
Byte2 DB
.ALIGN 4
Checksum DW
.ENDS
Here’s the order in which WLA writes the RAM sections:
FORCE
SEMISUBFREE
SEMIFREE
FREE
You can change this order using [ramsectionwriteorder]
in a link file.
NOTE: You can use ORGA
to specify the fixed address for a FORCE
RAMSECTION
. ORG
is also supported.
NOTE: When you have RAMSECTION
s inside libraries, you must give
them BANKs and SLOTs in the linkfile, under [ramsections].
NOTE: WINDOW
and BITWINDOW
work also with .RAMSECTION
s.
This is not a compulsory directive.
3.135. .RAMSIZE 0
¶
Indicates the size of the RAM. This is a standard Gameboy RAM size indicator
value found at $149
in a Gameboy ROM, and there this one is put to also.
This is not a compulsory directive.
3.136. .REDEF IF $0F
¶
.REDEF
is an alias for .REDEFINE
.
This is not a compulsory directive.
3.137. .REDEFINE IF $0F
¶
Assigns a new value or a string to an old definition. If the
definition doesn’t exist, .REDEFINE
performs .DEFINE
’s work.
When used with .REPT
REDEFINE
helps creating tables:
.DEFINE CNT 0
.REPT 256
.DB CNT
.REDEFINE CNT CNT+1
.ENDR
This is not a compulsory directive.
3.138. .REPEAT 6
¶
Repeats the text enclosed between .REPEAT x
and .ENDR
x
times
(6
in this example). You can use .REPEAT
s inside .REPEAT
s.
x
must be bigger or equal than 0
.
It’s also possible to have the repeat counter/index in a definition:
.REPEAT 6 INDEX COUNT
.DB COUNT
.ENDR
This would define bytes 0
, 1
, 2
, 3
, 4
and 5
.
This is not a compulsory directive.
3.139. .REPT 6
¶
.REPT
is an alias for .REPEAT
.
This is not a compulsory directive.
3.140. .ROMBANKMAP
¶
Begins the ROM bank map definition. You can use this directive to
define the project’s ROM banks. Use .ROMBANKMAP
when not all the
ROM banks are of equal size. Note that you can use .ROMBANKSIZE
and
.ROMBANKS
instead of .ROMBANKMAP
, but that’s only when the ROM banks
are equal in size.
Examples:
.ROMBANKMAP
BANKSTOTAL 16
BANKSIZE $4000
BANKS 16
.ENDRO
.ROMBANKMAP
BANKSTOTAL 510
BANKSIZE $6000
BANKS 1
BANKSIZE $2000
BANKS 509
.ENDRO
The first one describes an ordinary ROM image of 16 equal sized
banks. The second one defines a 4MB Pocket Voice ROM image.
In the PV ROM image the first bank is $6000
bytes and the remaining
509
banks are smaller ones, $2000
bytes each.
BANKSTOTAL
tells the total amount of ROM banks. It must be
defined prior to anything else.
BANKSIZE
tells the size of the following ROM banks. You can
supply WLA with BANKSIZE
as many times as you wish.
BANKS
tells the amount of banks that follow and that are of
the size BANKSIZE
which has been previously defined.
This is not a compulsory directive when .ROMBANKSIZE
and
.ROMBANKS
are defined.
You can redefine .ROMBANKMAP
as many times as you wish as long as
the old and the new ROM bank maps match as much as possible. This
way you can enlarge the size of the project on the fly.
3.141. .ROMBANKS 2
¶
Indicates the size of the ROM in rombanks.
This is a compulsory directive unless .ROMBANKMAP
is defined.
You can redefine .ROMBANKS
as many times as you wish as long as
the old and the new ROM bank maps match as much as possible. This
way you can enlarge the size of the project on the fly.
3.142. .ROMBANKSIZE $4000
¶
Defines the ROM bank size. Old syntax is .BANKSIZE x
.
This is a compulsory directive unless .ROMBANKMAP
is defined.
3.143. .ROMDMG
¶
Inserts data into the specific ROM location to mark the ROM as a DMG
(Gameboy) ROM ($00
-> $0146
). It will only run in DMG mode.
This is not a compulsory directive. .ROMDMG
cannot be used with .ROMSGB
.
3.144. .ROMGBCONLY
¶
Inserts data into the specific ROM location to mark the ROM as a Gameboy Color
ROM ($C0
-> $0143
, so ROM name is max. 15 characters long). It will
only run in GBC mode.
This is not a compulsory directive.
3.145. .ROMGBC
¶
Inserts data into the specific ROM location to mark the ROM as a dual-mode ROM
($80
-> $0143
, so ROM name is max. 15 characters long). It will run in
either DMG or GBC mode.
This is not a compulsory directive.
3.146. .ROMSGB
¶
Inserts data into the specific ROM location to mark the ROM as a Super
Gameboy enhanced ROM ($03
-> $0146
).
This is not a compulsory directive. .ROMSGB
cannot be used with .ROMDMG
.
3.147. .ROMSIZE 1
¶
This is a standard Gameboy ROM size indicator value found at $148
in a
Gameboy ROM, and there this one is put to also. If you don’t specify a value
then WLA-GB tries to calculate it based on .ROMBANKS
/ .ROMBANKMAP
.
This is not a compulsory directive.
3.148. .ROW $ff00, 1, "3"
¶
Defines bytes after a .TABLE has been used to define the format. An alternative way of defining bytes to .DB/.DW.
Note that when you use .ROW you’ll need to give all the items .TABLE defines, i.e. one full row. To give more or less bytes use .DATA.
Example:
.TABLE word, byte, word
.ROW $aabb, "H", $ddee
This is the same as
.DW $aabb .DB “H” .DW $ddee
This is not a compulsory directive.
3.149. .SDSCTAG 1.0, "DUNGEON MAN", "A wild dungeon exploration game", "Ville Helin"
¶
.SDSCTAG
adds SDSC tag to your SMS/GG ROM file. The ROM size must be at
least 8KB just like with .COMPUTESMSCHECKSUM
and .SMSTAG
. For more
information about this header take a look at https://www.smspower.org/Development/SDSCHeader.
Here’s an explanation of the arguments:
.SDSCTAG {version number}, {program name}, {program release notes}, {program author}
Note that program name, release notes and program author can also be pointers to strings instead of being only strings (which WLA terminates with zero, and places them into suitable locations inside the ROM file). So:
.SDSCTAG 0.8, PRGNAME, PRGNOTES, PRGAUTHOR
...
PRGNAME: .DB "DUNGEON MAN", 0
PRGNOTES: .DB "A wild and totally crazy dungeon exploration game", 0
PRGAUTHOR:.DB "Ville Helin", 0
works also. All strings supplied explicitly to .SDSCTAG
are placed
somewhere in .BANK 0 SLOT 0
.:
.SDSCTAG 1.0, "", "", ""
.SDSCTAG 1.0, 0, 0, 0
are also valid, here 0
and ""
mean the user doesn’t want to use any
descriptive strings. Version number can also be given as an integer, but then
the minor version number defaults to zero.
.SDSCTAG
also defines .SMSTAG
(as it’s part of the SDSC ROM tag
specification).
This is not a compulsory directive.
3.150. .SECTION "Init" FORCE
¶
Section is a continuous area of data which is placed into the output
file according to the section type and .BANK
and .ORG
directive
values.
The example begins a section called Init
. Before a section can be
declared, .BANK
and .ORG
should be used unless WLA is in library file
output mode. Library file’s sections must all be FREE
ones. .BANK
tells the bank number where this section will be later relocated into. .ORG
tells the offset for the relocation from the beginning of .BANK
.
It is also possible to supply BANK
, SLOT
, BASE
and ORG
or ORGA
to .SECTION
as follows:
.SECTION "NoInheritedParameters" BASE $70 BANK 0 SLOT 1 ORGA $1000
You can put sections inside a namespace. For instance, if you put a section
into a namespace called bank0
, then labels in that section can be
accessed with bank0.label
. This is not necessary inside the section
itself. The namespace directive should immediately follow the name:
.SECTION "Init" NAMESPACE "bank0"
You can give the size of the section, if you wish to force the section to some specific size, the following way:
.SECTION "Init" SIZE 100 FREE
It’s possible to force WLALINK to align the sections by giving the alignment as follows:
.SECTION "Init" SIZE 100 ALIGN 4 FREE
If you need an offset from the alignment, use OFFSET:
.SECTION "Init" SIZE 10 ALIGN 256 OFFSET 32 FREE
And if you want that WLA returns the ORG
to what it was before issuing
the section, put RETURNORG
at the end of the parameter list:
.SECTION "Init" SIZE 100 ALIGN 4 FREE RETURNORG
By default WLA advances the ORG
, so, for example, if your ORG
was
$0
before a section of 16 bytes, then the ORG
will be 16
after the
section.
Note also that if your section name begins with double underlines (e.g.,
__UNIQUE_SECTION!!!
) the section will be unique in the sense that
when WLALINK recieves files containing sections which share the same
name, WLALINK will save only the first of them for further processing,
all others are deleted from memory with corresponding labels, references
and calculations.
If a section name begins with an exclamation mark (!
) it tells
WLALINK to not to drop it, even if you use WLALINK’s ability to discard
all unreferenced sections and there are no references to the section. You can
achieve the same effect by adding KEEP
to the end of the list:
.SECTION "Init" SIZE 100 ALIGN 4 FREE RETURNORG KEEP
FORCE
after the name of the section tells WLA that the section must be
inserted so it starts at .ORG
. FORCE
can be replaced with FREE
which means that the section can be inserted somewhere in the defined bank,
where there is room. You can also use OVERWRITE
to insert the section into
the memory regardless of data collisions. Using OVERWRITE
you can easily
patch an existing ROM image just by .BACKGROUND
’ing the ROM image and
inserting OVERWRITE
sections into it. SEMIFREE
sections are also
possible and they behave much like FREE
sections. The only difference is
that they are positioned somewhere in the bank starting from .ORG
.
SEMISUBFREE
sections on the other hand are positioned somewhere in the bank
starting from $0
and ending to .ORG
.
SUPERFREE
sections are also available, and they will be positioned into
the first suitable place inside the first suitable bank (candidates for these
suitable banks have the same size with the slot of the section, no other banks
are considered). You can also leave away the type specifier as the default type
for the section is FREE
.
If you wish to specify the banks where the section could be inserted into, use
SEMISUPERFREE
(and BANKS
to specify the banks list):
.SECTION "IAmABankedSection" SEMISUPERFREE BANKS 15-13/10/6-9/3/1
The banks list in the example unrolls into this: [ 15, 14, 13, 10, 6, 7, 8, 9, 3, 1 ]. The banks are inspected for free space in the given order.
You can name the sections as you wish, but there is one special name. A section
called BANKHEADER
is placed in the front of the bank where it is defined.
These sections contain data that is not in the memory map of the machine, so
you can’t refer to the data of a BANKHEADER
section, but you can write
references to outside. So no labels inside BANKHEADER
sections. These
special sections are useful when writing e.g., MSX programs. Note that library
files don’t take BANKHEADER
sections.
Here’s an example of a BANKHEADER
section:
.BANK 0
.ORG 0
.SECTION "BANKHEADER"
.DW MAIN
.DW VBI
.ENDS
.SECTION "Program"
MAIN: CALL MONTY_ON_THE_RUN
VBI: PUSH HL
...
POP HL
RETI
.ENDS
Here’s an example of an ordinary section:
.BANK 0
.ORG $150
.SECTION "Init" FREE PRIORITY 1000
DI
LD SP, $FFFE
SUB A
LD ($FF00+R_IE), A
.ENDS
This tells WLA that a FREE
section called Init
must be located
somewhere in bank 0
and it has a sorting PRIORITY
of 1000. If you replace
FREE
with SEMIFREE
the section will be inserted somewhere in the bank 0
,
but not in the $0
- $14F
area. If you replace FREE
with SUPERFREE
the section will be inserted somewhere in any bank with the same size as bank 0
.
Here’s the order in which WLALINK writes the sections:
FORCE
SEMISUPERFREE
SEMISUBFREE
SEMIFREE
FREE
SUPERFREE
OVERWRITE
You can change this order using [sectionwriteorder]
in a link file.
Before the sections are inserted into the output file, they are sorted by
priorities, so that the section with the highest priority is processed first.
If priorities are the same, then the size of the section matters, and bigger
sections are processed before smaller ones. The default PRIORITY
, when not
explicitly given, is 0. Note that PRIORITY
accepts negative values as well.
You can use AUTOPRIORITY
instead of PRIORITY
when you want to assign
descending priority to sections. Using this you can make it so that e.g.,
APPENDTO
sections are appended in the lexical parsing order. AUTOPRIORITY
starts from 65535 and is subtracted by one every time it’s used.
You can also create a RAM section. For more information about them, please
read the .RAMSECTION
directive explanation.
It is also possible to merge two or more sections using APPENDTO
:
.SECTION "Base"
.DB 0
.ENDS
.SECTION "AppendToBase" FREE RETURNORG APPENDTO "Base"
.DB 1
.ENDS
And you can force a section to be placed after another section, with an offset:
.SECTION "Follower" OFFSET 32 AFTER "Base"
.DB 111
.ENDS
If you want to force WLALINK to place a section say between $0100 and $0200
in the address space, use WINDOW
(note that .SLOT
must be used to make
this placement possible, have the .SECTION
in the correct slot):
.SECTION "SpecialStuff" FREE WINDOW $0100 $0200
NOP
.ENDS
If you want to position a .SECTION
so that it is placed in memory in a
spot where e.g., only the least 8 bits of the address change (the .SECTION
must thus be less than 256 bytes in size), use BITWINDOW
:
.SECTION "PageX" FREE BITWINDOW 8
NOP
.ENDS
This is not a compulsory directive.
3.151. .SEED 123
¶
Seeds the random number generator.
The random number generator is initially seeded with the output of time()
,
which is, according to the manual, the time since the Epoch (00:00:00 UTC,
January 1, 1970), measured in seconds. So if you don’t .SEED
the random
number generator yourself with a constant value, .DBRND
and .DWRND
give
you different values every time you run WLA.
In WLA DX 9.4a and before we used the stdlib’s srand()
and rand()
functions making the output differ on different platforms. Since v9.4 WLA DX
contains its own Mersenne Twister pseudo random number generator.
This is not a compulsory directive.
3.152. .SEEDRANDOM
¶
Seeds the random number generator with the output of time()
, which is,
according to the manual, the time since the Epoch (00:00:00 UTC,
January 1, 1970), measured in seconds.
By default the (pseudo) random number generator is seeded with time()
,
so you don’t have to do it yourself, but just in the case you want to do it
somewhere in the source code, use this.
This is not a compulsory directive.
3.153. .SHIFT
¶
Shifts the macro arguments one down (\2
becomes \1
, \3
becomes \2
,
etc.). .SHIFT
can thus only be used inside a .MACRO
.
This is not a compulsory directive.
3.154. .SLOT 1
¶
Changes the currently active memory slot. This directive is meant to be
used with SUPERFREE
sections, where only the slot number is constant
when placing the sections.
You can use the number, address or name of the slot here:
.SLOT 1 ; Use slot 1.
.SLOT $2000 ; Use a slot with starting address of $2000.
.SLOT "SlotOne" ; Use a slot with a name "SlotOne"
This is not a compulsory directive.
3.155. .SLOWROM
¶
Clears the ROM memory speed bit in $FFD5
(.HIROM
), $7FD5
(.LOROM
)
or $FFD5
and $40FFD5
(.EXHIROM
) to indicate that the SNES ROM chips
are 200ns chips.
This is not a compulsory directive.
3.156. .SMC
¶
Forces WLALINK to compute a proper SMC header for the ROM file.
SMC header is a chunk of 512 bytes. WLALINK touches only its first three bytes, and sets the rest to zeroes. Here’s what will be inside the first three bytes:
Byte |
Description |
|
low byte of 8KB page count. |
|
high byte of 8KB page count. |
|
|
This is not a compulsory directive.
3.157. .SMDHEADER
¶
Defines the Sega Mega Drive ROM header in $100-$1FF
. All the fields
in .SMDHEADER
are optional. Here are the default values:
.SMDHEADER
SYSTEMTYPE "SEGA MEGA DRIVE " ; 16 bytes
COPYRIGHT " " ; 16 bytes
TITLEDOMESTIC " " ; 48 bytes (all spaces)
TITLEOVERSEAS " " ; 48 bytes (all spaces)
SERIALNUMBER " " ; 14 bytes (all spaces)
DEVICESUPPORT "J " ; 16 bytes ('J' and the rest are spaces)
ROMADDRESSRANGE $0, -1 ; 8 bytes (-1 is turned into ROM size minus one)
RAMADDRESSRANGE $FF0000, $FFFFFF ; 8 bytes
EXTRAMEMORY "RA", $A0, $20, S, E ; 12 bytes (S and E and start and end, both 0)
MODEMSUPPORT " " ; 12 bytes (all spaces)
REGIONSUPPORT "JUE" ; 3 bytes
.ENDSMD
When .SMDHEADER
is defined, also the ROM checksum is calculated.
See https://plutiedev.com/rom-header for more information about the SMD header.
This is not a compulsory directive.
3.158. .SMSHEADER
¶
All the fields in .SMSHEADER
are optional and PRODUCTCODE, VERSION,
REGIONCODE and RESERVEDSPACE default to zero. If ROMSIZE is not specified
it will be calculated automatically:
.SMSHEADER
PRODUCTCODE 26, 70, 2 ; 2.5 bytes
VERSION 1 ; 0-15
REGIONCODE 4 ; 3-7
RESERVEDSPACE 0, 0 ; 2 bytes
ROMSIZE 0 ; 0-15
CHECKSUMSIZE 32*1024 ; Uses the first this-many bytes in checksum
; calculations (excluding header area)
FORCECHECKSUM $1234 ; Forces the checksum to be this value
BASEADDRESS $1FF0 ; Write the header at this address
.ENDSMS
The REGIONCODE
also defines the system:
|
SMS Japan |
|
SMS Export |
|
GG Japan |
|
GG Export |
|
GG International |
When .SMSHEADER
is defined, also the checksum is calculated, and TMR SEGA,
two reserved bytes and ROM size are defined.
See http://www.smspower.org/Development/ROMHeader for more information about SMS header.
This is not a compulsory directive.
3.159. .SMSTAG
¶
.SMSTAG
forces WLA to write an ordinary SMS/GG ROM tag to the ROM file.
Currently only the string TMR SEGA
and ROM checksum are written
(meaning that .SMSTAG
also defines .COMPUTESMSCHECKSUM
). The ROM size
must be at least 8KBs.
This is not a compulsory directive.
3.160. .SNESEMUVECTOR
¶
Begins definition of the emulation mode interrupt vector table:
.SNESEMUVECTOR
COP COPHandler
UNUSED $0000
ABORT BRKHandler
NMI VBlank
RESET Main
IRQBRK IRQBRKHandler
.ENDEMUVECTOR
These can be defined in any order, but they will be placed into
memory starting at $7FF4
($FFF4
in HiROM, $40FFF4
and $FFF4
in
ExHiROM) in the order listed above. All the vectors default to $0000
.
This is not a compulsory directive.
3.161. .SNESHEADER
¶
This begins the SNES header definition, and automatically defines
.COMPUTESNESCHECKSUM
. From here you may define any of the following:
ID "ABCD"
- inserts a one to four letter string starting at$7FB2
(lorom) or$FFB2
(hirom).NAME "Hello World!"
- identical to a freestanding.NAME
.LOROM
- identical to a freestanding.LOROM
.HIROM
- identical to a freestanding.HIROM
.EXHIROM
- identical to a freestanding.EXHIROM
.SLOWROM
- identical to a freestanding.SLOWROM
.FASTROM
- identical to a freestanding.FASTROM
.CARTRIDGETYPE $00
- Places the given 8-bit value in$7FD6
($FFD6
in HiROM,$40FFD6
and$FFD6
in ExHiROM). Some possible values I’ve come across but cannot guarantee the accuracy of:$00
ROM
$01
ROM
RAM
$02
ROM
SRAM
$03
ROM
DSP1
$04
ROM
RAM
DSP1
$05
ROM
SRAM
DSP1
$13
ROM
Super FX
ROMSIZE $09
- Places the given 8-bit value in$7FD7
($FFD7
in HiROM,$40FFD7
and$FFD7
in ExHiROM). Possible values include (but may not be limited to):$08
2 Megabits
$09
4 Megabits
$0A
8 Megabits
$0B
16 Megabits
$0C
32 Megabits
SRAMSIZE $01
- Places the given 2-bit value into$7FD8
($FFD8
in HiROM,$40FFD8
and$FFD8
in ExHiROM). I believe these are the only possible values:$00
0 kilobits
$01
16 kilobits
$02
32 kilobits
$03
64 kilobits
COUNTRY $00
- Places the given 8-bit value into$7FD9
($FFD9
in HiROM,$40FFD9
and$FFD9
in ExHiROM).$00
is Japan and$01
is the United States, and there several more for other regions that I cannot recall off the top of my head.LICENSEECODE $00
- Places the given 8-bit value into$7FDA
($FFDA
in HiROM,$40FFDA
and$FFDA
in ExHiROM). You must find the legal values yourself as there are plenty of them. ;)VERSION $01
- Places the given 8-bit value into$7FDB
($FFDB
in HiROM,$40FFDB
and$FFDB
in ExHiROM). This is supposedly interpreted as version 1.byte, so a$01
here would be version 1.01.
This is not a compulsory directive.
3.162. .SNESNATIVEVECTOR
¶
Begins definition of the native mode interrupt vector table:
.SNESNATIVEVECTOR
COP COPHandler
BRK BRKHandler
ABORT ABORTHandler
NMI VBlank
UNUSED $0000
IRQ IRQHandler
.ENDNATIVEVECTOR
These can be defined in any order, but they will be placed into
memory starting at $7FE4
($FFE4
in HiROM, $40FFE4
and $FFE4
in
ExHiROM) in the order listed above. All the vectors default to $0000
.
This is not a compulsory directive.
3.163. .STRINGMAP script "Hello\n"
¶
After you’ve given the .STRINGMAPTABLE
, use .STRINGMAP
to define bytes
using the mapping in .STRINGMAPTABLE
. For example:
.STRINGMAP script, "いうえA\n"
.STRINGMAP
with .STRINGMAPTABLE
is an alternative way of mapping characters
to .ASC
and .ASCIITABLE
. Also note that here the result and the source of
the mapping can be more than just one byte.
This is not a compulsory directive.
3.164. .STRINGMAPTABLE script "script.tbl"
¶
.STRINGMAPTABLE
’s only purpose is to provide string mapping for
.STRINGMAP
. Take a look at the example:
.STRINGMAPTABLE script "script.tbl"
This will load the file “script.tbl” and define a new string mapping called “script”. This file is in the “table file” format commonly used for game translations; take a look at an example of one:
00=A
01=B
; This is a comment
ff01=あ
ff02=いうえ
fe=\n
The values to the left of the ‘=’ are a variable number of bytes expressed
in hex, which map to the text value on the right. Note that depending on the
text encoding of the file, this may be a variable number of bytes too. Thus
this is a more flexible version of .ASCIITABLE
.
After you’ve given the .STRINGMAPTABLE
, use .STRINGMAP
to define bytes
using this mapping. For example:
.STRINGMAP script, "いうえA\n"
This will map to the byte values FF 02 00 FE
, provided the source file and
TBL file use the same string encoding - use of UTF-8 is advised.
Note that all characters must be defined in the mapping - there is no fallback
to ASCII encoding. You also cannot mix in byte values like with .DB
and
.ASC
.
You can define multiple named string map tables.
This is not a compulsory directive.
3.165. .STRUCT enemy_object
¶
Begins the definition of a structure. These structures can be placed
inside RAMSECTION
s and ENUM
s. Here’s an example:
.STRUCT enemy_object
id dw ; the insides of a .STRUCT are 1:1 like in .ENUM
x db ; except that no structs inside structs are
y db ; allowed.
data ds 10
info dsb 16
stats dsw 4
.ENDST
This also creates a definition _sizeof_[struct name]
, in our example
this would be _sizeof_enemy_object
, and the value of this definition
is the size of the object, in bytes (2+1+1+10+16+4*2 = 38 in the example).
You’ll get the following definitions as well:
enemy_object.id (== 0)
enemy_object.x (== 2)
enemy_object.y (== 3)
enemy_object.data (== 4)
enemy_object.info (== 14)
enemy_object.stats (== 30)
After defining a .STRUCT
you can create an instance of it in a
.RAMSECTION
/ .ENUM
by typing:
<instance name> INSTANCEOF <struct name> [optional, the number of structures]
Here’s an example:
.RAMSECTION "enemies" BANK 4 SLOT 4
enemies INSTANCEOF enemy_object 4
enemyman INSTANCEOF enemy_object
enemyboss INSTANCEOF enemy_object
.ENDS
This will create definitions like enemies
, enemies.1.id
, enemies.1.x
,
enemies.1.y
and so on. Definition enemies
is followed by four enemy_object
instances. After those four come enemyman
and enemyboss
instances, but
as they are single instances, their definitions lack the index: enemyman
,
enemyman.id
, enemyman.x
, enemyman.y
and so on.
Take a look at the documentation on .RAMSECTION
& .ENUM
, they have more
examples of how you can use .STRUCT
s.
A WORD OF WARNING: Don’t use labels b
, B
, w
and W
inside a
structure as e.g., WLA sees enemy.b
as a byte sized reference to enemy. All
other labels should be safe:
lda enemy1.b ; load a byte from zeropage address enemy1 or from the address
; of enemy1.b??? i can't tell you, and WLA can't tell you...
It’s possible to explicitly define the size of the .STRUCT
by using keyword
SIZE
:
.STRUCT PaddedStruct SIZE 8
posX DW
posY DW
.ENDST
Normally this .STRUCT
would define four bytes, but by using keyword SIZE
its size is now eight bytes. The extra padding, put after the last item in the
.STRUCT
, will contain .EMPTYFILL
bytes when used with .DSTRUCT
.
Note that if we .DSTRUCT
“PaddedStruct” and name it PS1 we’ll also get a
definition
_paddingof_PS1 (== 4)
This is not a compulsory directive.
3.166. .SYM SAUSAGE
¶
WLA treats symbols (SAUSAGE
in this example) like labels, but they
only appear in the symbol files WLALINK outputs. Useful for finding out
the location where WLALINK puts data.
This is not a compulsory directive.
3.167. .SYMBOL SAUSAGE
¶
.SYMBOL
is an alias for .SYM
.
This is not a compulsory directive.
3.168. .TABLE byte, word, byte
¶
Defines table’s columns. With .DATA and .ROW you can define data much like using .DB or .DW, but .TABLE makes it convenient to feed big amounts of data in mixed format.
For example:
.TABLE byte, word, byte
After the columns have been defined, you can define rows using e.g.,
.ROW $01, $0302, $04
This is the same as:
.DB $01
.DW $0302
.DB $04
Note that .DATA can also be used instead of .ROW, if one wants to give the data in pieces.
- All supported column formats:
DB, BYT, BYTE
DW, WORD, ADDR
DL, LONG, FARADDR
DD
DS, DSB
DSW
DSL
DSD
This is not a compulsory directive.
3.169. .UNBACKGROUND $1000 $1FFF
¶
After issuing .BACKGROUND
you might want to free some parts of the
backgrounded ROM image for e.g., FREE
sections. With .UNBACKGROUND
you can define such regions. In the example a block starting at
$1000
and ending at $1FFF
was released (both ends included). You can
issue .UNBACKGROUND
as many times as you wish.
This is not a compulsory directive.
3.170. .UNDEF DEBUG
¶
.UNDEF
is an alias for .UNDEFINE
.
This is not a compulsory directive.
3.171. .UNDEFINE DEBUG
¶
Removes the supplied definition label from system. If there is no such label as given no error is displayed as the result would be the same.
You can undefine as many definitions as you wish with one .UNDEFINE
:
.UNDEFINE NUMBER, NAME, ADDRESS, COUNTRY
.UNDEFINE NAME, AGE
This is not a compulsory directive.
3.172. .UNION name
¶
Begins a “union”. This can only be used in .ENUM
s, .RAMSECTION
s
and .STRUCT
s.
When entering a union, the current address in the enum is saved, and the
following data is processed as normal. When the .NEXTU
directive is
encountered, the address is reverted back to the start of the union. This allows
one to assign an area of memory to multiple labels:
.ENUM $C000
.UNION
pos_lowbyte: db
pos_highbyte: db
extra_word: dw
.NEXTU
pos: dw
.ENDU
after: db
.ENDE
This example is equivalent to:
.DEFINE pos_lowbyte $c000
.DEFINE pos_highbyte $c001
.DEFINE extra_word $c002
.DEFINE pos $c000
.DEFINE after $c004
The .UNION
and .NEXTU
commands can be given an argument to assign
a prefix to the labels that follow:
.ENUM $C000
.UNION union1
byte1: db
byte2: db
.NEXTU union2
word1: dw
.ENDU
.ENDE
This example is equivalent to:
.DEFINE union1.byte1 $c000
.DEFINE union1.byte2 $c001
.DEFINE union2.word1 $c000
Unions can be nested.
3.173. .VERSION 1
¶
Indicates the Mask ROM version number located at $14C
of a Gameboy ROM.
This is not a compulsory directive.
3.174. .WDC
¶
Turns WLA-65816 into a mode where it accepts WDC standard assembly code, in addition to WLA’s own syntax. In WDC standard mode:
AND <x ; 8-bit
AND |? ; 16-bit
AND >& ; 24-bit
are the same as:
AND x.b ; 8-bit
AND ?.w ; 16-bit
AND &.l ; 24-bit
in WLA’s own syntax. Beware of the situations where you use ‘<’ and ‘>’ to get the low and high bytes!
This is not a compulsory directive.
3.175. .WHILE COUNTER > 0
¶
Repeats the text enclosed between .WHILE <CONDITION>
and .ENDR
:
.WHILE COUNTER > 0
.DB COUNTER
.REDEFINE COUNTER = COUNTER - 1
.ENDR
This is not a compulsory directive.
3.176. .WORD 16000, 10, 255
¶
.WORD
is an alias for .DW
.
This is not a compulsory directive.