1RGBASM(5) BSD File Formats Manual RGBASM(5)
2
4 rgbasm — language documentation
5
7 This is the full description of the language used by rgbasm(1). The
8 description of the instructions supported by the Game Boy CPU is in
9 gbz80(7).
10 It is strongly recommended to have some familiarity with the Game Boy
12 hardware before reading this document. RGBDS is specifically targeted at
13 the Game Boy, and thus a lot of its features tie directly to its con‐
14 cepts. This document is not intended to be a Game Boy hardware refer‐
15 ence.
16 Generally, “the linker” will refer to rgblink(1), but any program that
18 processes RGB object files (described in rgbds(5)) can be used in its
19 place.
20
22 The syntax is line‐based, just as in any other assembler, meaning that
23 you do one instruction or pseudo‐op per line:
24 [label] [instruction] [; comment]
26 Example:
28 John: ld a,87 ;Weee
30 All reserved keywords (pseudo‐ops, mnemonics, registers etc.) are case‐
32 insensitive, all identifiers (symbol names) are case-sensitive.
33 Comments are used to give humans information about the code, such as
35 explanations. The assembler always ignores comments and their contents.
36 There are three syntaxes for comments. The most common is that anything
38 that follows a semicolon ‘;’ not inside a string, is a comment until the
39 end of the line. The second is a block comment, beginning with ‘/*’ and
40 ending with ‘*/’. It can be split across multiple lines, or occur in the
41 middle of an expression:
42 X = /* the value of x
44 should be 3 */ 3
45 The third is that lines beginning with a ‘*’ (not even spaces before it)
46 are ignored. This third syntax is deprecated (will be removed in a
47 future version) and should be replaced with either of the first two.
48 Sometimes lines can be too long and it may be necessary to split them.
50 To do so, put a backslash at the end of the line:
51 DB 1, 2, 3, \
53 4, 5, 6, \ ; Put it before any comments
54 7, 8, 9
55 This works anywhere in the code except inside of strings. To split
57 strings it is needed to use STRCAT() like this:
58 db STRCAT("Hello ", \
60 "world!")
61
63 An expression can be composed of many things. Numerical expressions are
64 always evaluated using signed 32-bit math. Zero is considered to be the
65 only "false" number, all non-zero numbers (including negative) are
66 "true".
67 An expression is said to be "constant" if rgbasm knows its value. This
69 is generally always the case, unless a label is involved, as explained in
70 the SYMBOLS section.
71 The instructions in the macro-language generally require constant expres‐
73 sions.
74 Numeric Formats
76 There are a number of numeric formats.
77 Format type Prefix Accepted characters
79 Hexadecimal $ 0123456789ABCDEF
80 Decimal none 0123456789
81 Octal & 01234567
82 Binary % 01
83 Fixed point (16.16) none 01234.56789
84 Character constant none "ABYZ"
85 Gameboy graphics ` 0123
86 The "character constant" form yields the value the character maps to in
88 the current charmap. For example, by default (refer to ascii(7)) ‘"A"’
89 yields 65. See Character maps for information on charmaps.
90 The last one, Gameboy graphics, is quite interesting and useful. After
92 the backtick, 8 digits between 0 and 3 are expected, corresponding to
93 pixel values. The resulting value is the two bytes of tile data that
94 would produce that row of pixels. For example, ‘`01012323’ is equivalent
95 to ‘$0F55’.
96 You can also use symbols, which are implicitly replaced with their value.
98 Operators
100 A great number of operators you can use in expressions are available
101 (listed from highest to lowest precedence):
102 Operator Meaning
104 ( ) Precedence override
105 FUNC() Built-in function call
106 ~ + - Unary complement/plus/minus
107 * / % Multiply/divide/modulo
108 << >> Shift left/right
109 & | ^ Binary and/or/xor
110 + - Add/subtract
111 != == <= >= < > Comparison
112 && || Boolean and/or
113 ! Unary not
114 ~ complements a value by inverting all its bits.
116 % is used to get the remainder of the corresponding division. ‘5 % 2’ is
118 1.
119 Shifting works by shifting all bits in the left operand either left
121 (‘<<’) or right (‘>>’) by the right operand's amount. When shifting
122 left, all newly-inserted bits are reset; when shifting right, they are
123 copies of the original most significant bit instead. This makes ‘a << b’
124 and ‘a >> b’ equivalent to multiplying and dividing by 2 to the power of
125 b, respectively.
126 Comparison operators return 0 if the comparison is false, and 1 other‐
128 wise.
129 Unlike in a lot of languages, and for technical reasons, rgbasm still
131 evaluates both operands of ‘&&’ and ‘||’.
132 ! returns 1 if the operand was 0, and 0 otherwise.
134 Fixed‐point Expressions
136 Fixed-point numbers are basically normal (32-bit) integers, which count
137 65536th's instead of entire units, offering better precision than inte‐
138 gers but limiting the range of values. The upper 16 bits are used for
139 the integer part and the lower 16 bits are used for the fraction
140 (65536ths). Since they are still akin to integers, you can use them in
141 normal integer expressions, and some integer operators like ‘+’ and ‘-’
142 don't care whether the operands are integers or fixed-point. You can
143 easily truncate a fixed-point number into an integer by shifting it right
144 by 16 bits. It follows that you can convert an integer to a fixed-point
145 number by shifting it left.
146 The following functions are designed to operate with fixed-point numbers:
148 delim $$
149 Name Operation
151 DIV(x, y) $x ÷ y$
152 MUL(x, y) $x × y$
153 SIN(x) $sin (x )$
154 COS(x) $cos (x )$
155 TAN(x) $tan (x )$
156 ASIN(x) $asin (x )$
157 ACOS(x) $acos (x )$
158 ATAN(x) $atan (x )$
159 ATAN2(x, y) Angle between $( x, y )$ and $( 1, 0 )$
160 delim off
161 These functions are useful for automatic generation of various tables.
163 Example: assuming a circle has 65536.0 degrees, and sine values are in
164 range [-1.0 ; 1.0]:
165 ; --
167 ; -- Generate a 256-byte sine table with values between 0 and 128
168 ; --
169 ANGLE = 0.0
170 REPT 256
171 db MUL(64.0, SIN(ANGLE) + 1.0) >> 16
172 ANGLE = ANGLE + 256.0 ; 256 = 65536 / table_len, with table_len = 256
173 ENDR
174 String Expressions
176 The most basic string expression is any number of characters contained in
177 double quotes (‘"for instance"’). The backslash character ‘\’ is special
178 in that it causes the character following it to be “escaped”, meaning
179 that it is treated differently from normal. There are a number of escape
180 sequences you can use within a string:
181 String Meaning
183 ‘\\ Produces a backslash’
184 ‘\" Produces a double quote without terminating’
185 ‘\, Comma’
186 ‘\{ Curly bracket left’
187 ‘\} Curly bracket right’
188 ‘\n Newline ($0A)’
189 ‘\r Carriage return ($0D)’
190 ‘\t Tab ($09)’
191 "\1" – "\9" Macro argument (Only the body of a macro,
192 see Invoking macros)
193 ‘\@ Label name suffix (Only in the body of
194 macros and REPTs)’
195 (Note that some of those can be used outside of strings, when noted fur‐
196 ther in this document.)
197 A funky feature is ‘{symbol}’ within a string, called “symbol
199 interpolation”. This will paste symbol's contents as a string. If it's
200 a string symbol, the string is simply inserted. If it's a numeric sym‐
201 bol, its value is converted to hexadecimal notation with a dollar sign
202 ‘$’ prepended.
203 TOPIC equs "life, the universe, and everything"
205 ANSWER = 42
206 ; Prints "The answer to life, the universe, and everything is $2A"
207 PRINTT "The answer to {TOPIC} is {ANSWER}\n"
208 Symbol interpolations can be nested, too!
210 It's possible to change the way numeric symbols are converted by specify‐
212 ing a print type like so: ‘{d:symbol}’. Valid print types are:
213 Print type Format Example
215 ‘d Decimal 42’
216 ‘x Lowercase hexadecimal 2a’
217 ‘X Uppercase hexadecimal 2A’
218 ‘b Binary 101010’
219 Note that print types should only be used with numeric values, not
221 strings.
222 HINT: The {symbol} construct can also be used outside strings. The sym‐
224 bol's value is again inserted directly.
225 The following functions operate on string expressions. Most of them
227 return a string, however some of these functions actually return an inte‐
228 ger and can be used as part of an integer expression!
229 Name Operation
231 STRLEN(string) Returns the number of characters in string.
232 STRCAT(str1, str2) Appends str2 to str1.
233 STRCMP(str1, str2) Returns -1 if str1 is alphabetically lower than
234 str2 , zero if they match, 1 if str1 is greater
235 than str2.
236 STRIN(str1, str2) Returns the position of str2 in str1 or zero if
237 it's not present (first character is position
238 1).
239 STRSUB(str, pos, len) Returns a substring from str starting at pos
240 (first character is position 1) and len
241 characters long.
242 STRUPR(str) Converts all characters in str to capitals and
243 returns the new string.
244 STRLWR(str) Converts all characters in str to lower case and
245 returns the new string.
246 Character maps
248 When writing text that is meant to be displayed in the Game Boy, the
249 characters used in the source code may have a different encoding than the
250 default of ASCII. For example, the tiles used for uppercase letters may
251 be placed starting at tile index 128, which makes it difficult to add
252 text strings to the ROM.
253 Character maps allow mapping strings up to 16 characters long to an abi‐
255 trary 8-bit value:
256 CHARMAP "<LF>", 10
258 CHARMAP "í", 20
259 CHARMAP "A", 128
260 By default, a character map contains ASCII encoding.
261 It is possible to create multiple character maps and then switch between
263 them as desired. This can be used to encode debug information in ASCII
264 and use a different encoding for other purposes, for example. Initially,
265 there is one character map called ‘main’ and it is automatically selected
266 as the current character map from the beginning. There is also a charac‐
267 ter map stack that can be used to save and restore which character map is
268 currently active.
269 Command Meaning
271 NEWCHARMAP name Creates a new, empty character map called
272 name.
273 NEWCHARMAP name, basename Creates a new character map called name,
274 copied from character map basename.
275 SETCHARMAP name Switch to character map name.
276 PUSHC Push the current character map onto the
277 stack.
278 POPC Pop a character map off the stack and switch
279 to it.
280 Note: Character maps affect all strings in the file from the point in
282 which they are defined, until switching to a different character map.
283 This means that any string that the code may want to print as debug
284 information will also be affected by it.
285 Note: The output value of a mapping can be 0. If this happens, the
287 assembler will treat this as the end of the string and the rest of it
288 will be trimmed.
289 Other functions
291 There are a few other functions that do various useful things:
292 Name Operation
294 BANK(arg) Returns a bank number. If arg is the symbol @, this func‐
295 tion returns the bank of the current section. If arg is a
296 string, it returns the bank of the section that has that
297 name. If arg is a label, it returns the bank number the
298 label is in. The result may be constant if rgbasm is able
299 to compute it.
300 DEF(label) Returns TRUE (1) if label has been defined, FALSE (0) oth‐
301 erwise. String symbols are not expanded within the paren‐
302 theses.
303 HIGH(arg) Returns the top 8 bits of the operand if arg is a label or
304 constant, or the top 8-bit register if it is a 16-bit
305 register.
306 LOW(arg) Returns the bottom 8 bits of the operand if arg is a label
307 or constant, or the bottom 8-bit register if it is a 16-bit
308 register (AF isn't a valid register for this function).
309 ISCONST(arg) Returns 1 if arg's value is known by RGBASM (e.g. if it can
310 be an argument to IF), or 0 if only RGBLINK can compute its
311 value.
312
314 Before you can start writing code, you must define a section. This tells
315 the assembler what kind of information follows and, if it is code, where
316 to put it.
317 SECTION name, type
319 SECTION name, type, options
320 SECTION name, type[addr]
321 SECTION name, type[addr], options
322 name is a string enclosed in double quotes, and can be a new name or the
324 name of an existing section. If the type doesn't match, an error occurs.
325 All other sections must have a unique name, even in different source
326 files, or the linker will treat it as an error.
327 Possible section types are as follows:
329 ROM0 A ROM section. addr can range from $0000 to $3FFF, or $0000
331 to $7FFF if tiny ROM mode is enabled in the linker.
332 ROMX A banked ROM section. addr can range from $4000 to $7FFF.
334 bank can range from 1 to 511. Becomes an alias for ROM0 if
335 tiny ROM mode is enabled in the linker.
336 VRAM A banked video RAM section. addr can range from $8000 to
338 $9FFF. bank can be 0 or 1, but bank 1 is unavailable if DMG
339 mode is enabled in the linker.
340 SRAM A banked external (save) RAM section. addr can range from
342 $A000 to $BFFF. bank can range from 0 to 15.
343 WRAM0 A general-purpose RAM section. addr can range from $C000 to
345 $CFFF, or $C000 to $DFFF if WRAM0 mode is enabled in the
346 linker.
347 WRAMX A banked general-purpose RAM section. addr can range from
349 $D000 to $DFFF. bank can range from 1 to 7. Becomes an
350 alias for WRAM0 if WRAM0 mode is enabled in the linker.
351 OAM An object attribute RAM section. addr can range from $FE00
353 to $FE9F.
354 HRAM A high RAM section. addr can range from $FF80 to $FFFE.
356 Note: While rgbasm will automatically optimize ld instruc‐
358 tions to the smaller and faster ldh (see gbz80(7)) whenever
359 possible, it is generally unable to do so when a label is
360 involved. Using the ldh instruction directly is recommended.
361 This forces the assembler to emit a ldh instruction and the
362 linker to check if the value is in the correct range.
363 Since RGBDS produces ROMs, code and data can only be placed in ROM0 and
365 ROMX sections. To put some in RAM, have it stored in ROM, and copy it to
366 RAM.
367 options are comma-separated and may include:
369 BANK[bank] Specify which bank for the linker to place the section in.
371 See above for possible values for bank, depending on type.
372 ALIGN[align, offset]
374 Place the section at an address whose align least‐significant
375 bits are equal to offset. (Note that ALIGN[align] is a
376 shorthand for ALIGN[align, 0]). This option can be used with
377 [addr], as long as they don't contradict eachother. It's
378 also possible to request alignment in the middle of a sec‐
379 tion, see Requesting alignment below.
380 If [addr] is not specified, the section is considered “floating”; the
382 linker will automatically calculate an appropriate address for the sec‐
383 tion. Similarly, if BANK[bank] is not specified, the linker will auto‐
384 matically find a bank with enough space.
385 Sections can also be placed by using a linker script file. The format is
387 described in rgblink(5). They allow the user to place floating sections
388 in the desired bank in the order specified in the script. This is useful
389 if the sections can't be placed at an address manually because the size
390 may change, but they have to be together.
391 Section examples:
393 SECTION "Cool Stuff",ROMX
396 This switches to the section called “CoolStuff”, creating it if it
397 doesn't already exist. It can end up in any ROM bank. Code and data may
398 follow.
399 If it is needed, the the base address of the section can be specified:
401 SECTION "Cool Stuff",ROMX[$4567]
403 An example with a fixed bank:
405 SECTION "Cool Stuff",ROMX[$4567],BANK[3]
407 And if you want to force only the section's bank, and not its position
409 within the bank, that's also possible:
410 SECTION "Cool Stuff",ROMX,BANK[7]
412 Alignment examples: The first one could be useful for defining an OAM
414 buffer to be DMA'd, since it must be aligned to 256 bytes. The second
415 could also be appropriate for GBC HDMA, or for an optimized copy code
416 that requires alignment.
417 SECTION "OAM Data",WRAM0,ALIGN[8] ; align to 256 bytes
419 SECTION "VRAM Data",ROMX,BANK[2],ALIGN[4] ; align to 16 bytes
420 Section Stack
422 POPS and PUSHS provide the interface to the section stack. The number of
423 entries in the stack is limited only by the amount of memory in your
424 machine.
425 PUSHS will push the current section context on the section stack. POPS
427 can then later be used to restore it. Useful for defining sections in
428 included files when you don't want to override the section context at the
429 point the file was included.
430 RAM Code
432 Sometimes you want to have some code in RAM. But then you can't simply
433 put it in a RAM section, you have to store it in ROM and copy it to RAM
434 at some point.
435 This means the code (or data) will not be stored in the place it gets
437 executed. Luckily, LOAD blocks are the perfect solution to that. Here's
438 an example of how to use them:
439 SECTION "LOAD example", ROMX
441 CopyCode:
442 ld de, RAMCode
443 ld hl, RAMLocation
444 ld c, RAMLocation.end - RAMLocation
445 .loop
446 ld a, [de]
447 inc de
448 ld [hli], a
449 dec c
450 jr nz, .loop
451 ret
452 RAMCode:
454 LOAD "RAM code", WRAM0
455 RAMLocation:
456 ld hl, .string
457 ld de, $9864
458 .copy
459 ld a, [hli]
460 ld [de], a
461 inc de
462 and a
463 jr nz, .copy
464 ret
465 .string
467 db "Hello World!", 0
468 .end
469 ENDL
470 A LOAD block feels similar to a SECTION declaration because it creates a
472 new one. All data and code generated within such a block is placed in
473 the current section like usual, but all labels are created as if they
474 were placed in this newly-created section.
475 In the example above, all of the code and data will end up in the "LOAD
477 example" section. You will notice the ‘RAMCode’ and ‘RAMLocation’
478 labels. The former is situated in ROM, where the code is stored, the
479 latter in RAM, where the code will be loaded.
480 You cannot nest LOAD blocks, nor can you change the current section
482 within them.
483 Unionized Sections
485 When you're tight on RAM, you may want to define overlapping blocks of
486 variables, as explained in the Unions section. However, the UNION key‐
487 word only works within a single file, which prevents e.g. defining tempo‐
488 rary variables on a single memory area across several files. Unionized
489 sections solve this problem. To declare an unionized section, add a
490 UNION keyword after the SECTION one; the declaration is otherwise not
491 different. Unionized sections follow some different rules from normal
492 sections:
493 · The same unionized section (= having the same name) can be
495 declared several times per rgbasm invocation, and across sev‐
496 eral invocations. Different declarations are treated and
497 merged identically whether within the same invocation, or dif‐
498 ferent ones.
499 · If one section has been declared as unionized, all sections
501 with the same name must be declared unionized as well.
502 · All declarations must have the same type. For example, even if
504 rgblink(1)'s -w flag is used, WRAM0 and WRAMX types are still
505 considered different.
506 · Different constraints (alignment, bank, etc.) can be specified
508 for each unionized section declaration, but they must all be
509 compatible. For example, alignment must be compatible with any
510 fixed address, all specified banks must be the same, etc.
511 · Unionized sections cannot have type ROM0 or ROMX.
513 Different declarations of the same unionized section are not appended,
515 but instead overlaid on top of eachother, just like Unions. Similarly,
516 the size of an unionized section is the largest of all its declarations.
517 Section Fragments
519 Section fragments are sections with a small twist: when several of the
520 same name are encountered, they are concatenated instead of producing an
521 error. This works within the same file (paralleling the behavior "plain"
522 sections has in previous versions), but also across object files. To
523 declare an section fragment, add a FRAGMENT keyword after the SECTION
524 one; the declaration is otherwise not different. However, similarly to
525 Unionized Sections, some rules must be followed:
526 · If one section has been declared as fragment, all sections with
528 the same name must be declared fragments as well.
529 · All declarations must have the same type. For example, even if
531 rgblink(1)'s -w flag is used, WRAM0 and WRAMX types are still
532 considered different.
533 · Different constraints (alignment, bank, etc.) can be specified
535 for each unionized section declaration, but they must all be
536 compatible. For example, alignment must be compatible with any
537 fixed address, all specified banks must be the same, etc.
538 · A section fragment may not be unionized; after all, that
540 wouldn't make much sense.
541 When RGBASM merges two fragments, the one encountered later is appended
543 to the one encountered earlier.
544 When RGBLINK merges two fragments, the one whose file was specified last
546 is appended to the one whose file was specified first. For example,
547 assuming ‘bar.o’, ‘baz.o’, and ‘foo.o’ all contain a fragment with the
548 same name, the command
549 rgblink -o rom.gb baz.o foo.o bar.o
550 would produce the fragment from ‘baz.o’ first, followed by the one from
551 ‘foo.o’, and the one from ‘bar.o’ last.
552
554 RGBDS supports several types of symbols:
555 Label Numerical symbol designating a memory location. May or may not
557 have a value known at assembly time.
558 Constant Numerical symbol whose value has to be known at assembly time.
560 Macro A block of rgbasm code that can be invoked later.
562 String equate String symbol that can be evaluated, similarly to a macro.
564 Symbol names can contain letters, numbers, underscores ‘_’, hashes ‘#’
566 and at signs ‘@’. However, they must begin with either a letter, or an
567 underscore. Periods ‘.’ are allowed exclusively for labels, as described
568 below. A symbol cannot have the same name as a reserved keyword. In the
569 line where a symbol is defined there must not be any whitespace before
570 it, otherwise rgbasm will treat it as a macro invocation.
571 Label declaration
573 One of the assembler's main tasks is to keep track of addresses
574 for you, so you can work with meaningful names instead of "magic"
575 numbers.
576 This can be done in a number of ways:
578 GlobalLabel ; This syntax is deprecated,
580 AnotherGlobal: ; please use this instead
581 .locallabel
582 .yet_a_local:
583 AnotherGlobal.with_another_local:
584 ThisWillBeExported:: ; Note the two colons
585 ThisWillBeExported.too::
586 Declaring a label (global or local) with ‘::’ does an EXPORT at
588 the same time. (See Exporting and importing symbols below).
589 Any label whose name does not contain a period is a global label,
591 others are locals. Declaring a global label sets it as the cur‐
592 rent label scope until the next one; any local label whose first
593 character is a period will have the global label's name implic‐
594 itly prepended. Local labels can be declared as ‘scope.local:’
595 or simply as as ‘.local:’. If the former notation is used, then
596 ‘scope’ must be the actual current scope.
597 Local labels may have whitespace before their declaration as the
599 only exception to the rule.
600 A label's location (and thus value) is usually not determined
602 until the linking stage, so labels usually cannot be used as con‐
603 stants. However, if the section in which the label is declared
604 has a fixed base address, its value is known at assembly time.
605 rgbasm is able to compute the subtraction of two labels either if
607 both are constant as described above, or if both belong to the
608 same section.
609 EQU EQU allows defining constant symbols. Unlike SET below, con‐
611 stants defined this way cannot be redefined. They can, for exam‐
612 ple, be used for things such as bit definitions of hardware reg‐
613 isters.
614 SCREEN_WIDTH equ 160 ; In pixels
616 SCREEN_HEIGHT equ 144
617 Note that colons ‘:’ following the name are not allowed.
619 SET SET, or its synonym =, defines constant symbols like EQU, but
621 those constants can be re-defined. This is useful for variables
622 in macros, for counters, etc.
623 ARRAY_SIZE EQU 4
625 COUNT SET 2
626 COUNT SET ARRAY_SIZE+COUNT
627 ; COUNT now has the value 6
628 COUNT = COUNT + 1
629 Note that colons ‘:’ following the name are not allowed.
631 RSSET, RSRESET, RB, RW
633 The RS group of commands is a handy way of defining structures:
634 RSRESET
636 str_pStuff RW 1
637 str_tData RB 256
638 str_bCount RB 1
639 str_SIZEOF RB 0
640 The example defines four constants as if by:
642 str_pStuff EQU 0
644 str_tData EQU 2
645 str_bCount EQU 258
646 str_SIZEOF EQU 259
647 There are five commands in the RS group of commands:
649 Command Meaning
651 RSRESET Equivalent to ‘RSSET 0’.
652 RSSET constexpr Sets the _RS counter to constexpr.
653 RB constexpr Sets the preceding symbol to _RS and adds
654 constexpr to _RS.
655 RW constexpr Sets the preceding symbol to _RS and adds
656 constexpr * 2 to _RS.
657 RL constexpr Sets the preceding symbol to _RS and adds
658 constexpr * 4 to _RS. (In practice, this one
659 cannot be used due to a bug).
660 If the argument to RB, RW, or RL is omitted, it's assumed to be
662 1.
663 Note that colons ‘:’ following the name are not allowed.
665 EQUS EQUS is used to define string symbols. Wherever the assembler
667 meets a string symbol its name is replaced with its value. If
668 you are familiar with C you can think of it as similar to #define
669 .
670 COUNTREG EQUS "[hl+]"
672 ld a,COUNTREG
673 PLAYER_NAME EQUS "\"John\""
675 db PLAYER_NAME
676 This will be interpreted as:
678 ld a,[hl+]
680 db "John"
681 String symbols can also be used to define small one-line macros:
683 pusha EQUS "push af\npush bc\npush de\npush hl\n"
685 Note that colons ‘:’ following the name are not allowed. String
687 equates can't be exported or imported.
688 Important note: An EQUS can be expanded to a string that contains
690 another EQUS and it will be expanded as well. If this creates an
691 infinite loop, rgbasm will error out once a certain depth is
692 reached. See the -r command-line option in rgbasm(1). Also, a
693 macro can contain an EQUS which calls the same macro, which
694 causes the same problem.
695 MACRO One of the best features of an assembler is the ability to write
697 macros for it. Macros can be called with arguments, and can
698 react depending on input using IF constructs.
699 MyMacro: MACRO
701 ld a,80
702 call MyFunc
703 ENDM
704 Note that a single colon ‘:’ following the macro's name is
706 required. Macros can't be exported or imported.
707 Plainly nesting macro definitions is not allowed, but this can be
709 worked around using EQUS. This won't work:
710 outer: MACRO
712 inner: MACRO
713 PRINTT "Hello!\n"
714 ENDM
715 ENDM
716 But this will:
718 outer: MACRO
720 definition equs "inner: MACRO\nPRINTT \"Hello!\\n\"\nENDM"
721 definition
722 PURGE definition
723 ENDM
724 Exporting and importing symbols
726 Importing and exporting of symbols is a feature that is very useful when
727 your project spans many source files and, for example, you need to jump
728 to a routine defined in another file.
729 Exporting of symbols has to be done manually, importing is done automati‐
731 cally if rgbasm finds a symbol it does not know about.
732 The following will cause symbol1, symbol2 and so on to be accessible to
734 other files during the link process:
735 EXPORT symbol1 [, symbol2, ...]
736 For example, if you have the following three files:
738 ‘a.asm’:
740 SECTION "a", WRAM0
741 LabelA:
742 ‘b.asm’:
744 SECTION "b", WRAM0
745 ExportedLabelB1::
746 ExportedLabelB2:
747 EXPORT ExportedLabelB2
748 ‘c.asm’:
750 SECTION "C", ROM0[0]
751 dw LabelA
752 dw ExportedLabelB1
753 dw ExportedLabelB2
754 Then ‘c.asm’ can use ‘ExportedLabelB1’ and ‘ExportedLabelB2’, but not
756 ‘LabelA’, so linking them together will fail:
757 $ rgbasm -o a.o a.asm
759 $ rgbasm -o b.o b.asm
760 $ rgbasm -o c.o c.asm
761 $ rgblink a.o b.o c.o
762 error: c.asm(2): Unknown symbol "LabelA"
763 Linking failed with 1 error
764 Note also that only exported symbols will appear in symbol and map files
766 produced by rgblink(1).
767 GLOBAL is a deprecated synonym for EXPORT, do not use it.
769 Purging symbols
771 PURGE allows you to completely remove a symbol from the symbol table as
772 if it had never existed. USE WITH EXTREME CAUTION!!! I can't stress this
773 enough, you seriously need to know what you are doing. DON'T purge a
774 symbol that you use in expressions the linker needs to calculate. When
775 not sure, it's probably not safe to purge anything other than string sym‐
776 bols, macros, and constants.
777 Kamikaze EQUS "I don't want to live anymore"
779 AOLer EQUS "Me too"
780 PURGE Kamikaze, AOLer
781 Note that, as an exception, string symbols in the argument list of a
783 PURGE command will not be expanded.
784 Predeclared Symbols
786 The following symbols are defined by the assembler:
787 Type Name Contents
789 EQU @ PC value (essentially, the current
790 memory address)
791 EQU _PI Fixed point π
792 SET _RS _RS Counter
793 EQU _NARG Number of arguments passed to macro,
794 updated by SHIFT
795 EQU __LINE__ The current line number
796 EQUS __FILE__ The current filename
797 EQUS __DATE__ Today's date
798 EQUS __TIME__ The current time
799 EQUS __ISO_8601_LOCAL__ ISO 8601 timestamp (local)
800 EQUS __ISO_8601_UTC__ ISO 8601 timestamp (UTC)
801 EQU __UTC_YEAR__ Today's year
802 EQU __UTC_MONTH__ Today's month number, 1–12
803 EQU __UTC_DAY__ Today's day of the month, 1–31
804 EQU __UTC_HOUR__ Current hour, 0–23
805 EQU __UTC_MINUTE__ Current minute, 0–59
806 EQU __UTC_SECOND__ Current second, 0–59
807 EQU __RGBDS_MAJOR__ Major version number of RGBDS
808 EQU __RGBDS_MINOR__ Minor version number of RGBDS
809 EQU __RGBDS_PATCH__ Patch version number of RGBDS
810
812 Declaring variables in a RAM section
813 DS allocates a number of empty bytes. This is the preferred method of
814 allocating space in a RAM section. You can also use DB, DW and DL with‐
815 out any arguments instead (see Defining constant data below).
816 DS 42 ; Allocates 42 bytes
818 Empty space in RAM sections will not be initialized. In ROM sections, it
820 will be filled with the value passed to the -p command-line option,
821 except when using overlays with -O.
822 Defining constant data
824 DB defines a list of bytes that will be stored in the final image. Ideal
825 for tables and text. Note that strings are not zero-terminated!
826 DB 1,2,3,4,"This is a string"
828 DS can also be used to fill a region of memory with some value. The fol‐
830 lowing produces 42 times the byte $FF:
831 DS 42, $FF
833 Alternatively, you can use DW to store a list of words (16-bit) or DL to
835 store a list of double-words/longs (32-bit). Strings are not allowed as
836 arguments to DW and DL.
837 You can also use DB, DW and DL without arguments, or leaving empty ele‐
839 ments at any point in the list. This works exactly like DS 1, DS 2 and
840 DS 4 respectively. Consequently, no-argument DB, DW and DL can be used
841 in a WRAM0 / WRAMX / HRAM / VRAM / SRAM section.
842 Including binary files
844 You probably have some graphics, level data, etc. you'd like to include.
845 Use INCBIN to include a raw binary file as it is. If the file isn't
846 found in the current directory, the include-path list passed to rgbasm(1)
847 (see the -i option) on the command line will be searched.
848 INCBIN "titlepic.bin"
850 INCBIN "sprites/hero.bin"
851 You can also include only part of a file with INCBIN. The example below
853 includes 256 bytes from data.bin, starting from byte 78.
854 INCBIN "data.bin",78,256
856 The length argument is optional. If only the start position is speci‐
858 fied, the bytes from the start position until the end of the file will be
859 included.
860 Unions
862 Unions allow multiple memory allocations to overlap, like unions in C.
863 This does not increase the amount of memory available, but allows re-
864 using the same memory region for different purposes.
865 A union starts with a UNION keyword, and ends at the corresponding ENDU
867 keyword. NEXTU separates each block of allocations, and you may use it
868 as many times within a union as necessary.
869 ; Let's say PC = $C0DE here
871 UNION
872 ; Here, PC = $C0DE
873 Name: ds 8
874 ; PC = $C0E6
875 Nickname: ds 8
876 ; PC = $C0EE
877 NEXTU
878 ; PC is back to $C0DE
879 Health: dw
880 ; PC = $C0E0
881 Something: ds 6
882 ; And so on
883 Lives: db
884 NEXTU
885 VideoBuffer: ds 19
886 ENDU
887 In the example above, ‘Name, Health, VideoBuffer’ all have the same
889 value, as do ‘Nickname’ and ‘Lives’. Thus, keep in mind that ld
890 [Health], a is identical to ld [Name], a.
891 The size of this union is 19 bytes, as this is the size of the largest
893 block (the last one, containing ‘VideoBuffer’). Nesting unions is possi‐
894 ble, with each inner union's size being considered as described above.
895 Unions may be used in any section, but inside them may only be DS - like
897 commands (see Declaring variables in a RAM section).
898
900 Invoking macros
901 You execute the macro by inserting its name.
902 add a,b
904 ld sp,hl
905 MyMacro ; This will be expanded
906 sub a,87
907 It's valid to call a macro from a macro (yes, even the same one).
909 When rgbasm sees MyMacro it will insert the macro definition (the code
911 enclosed in MACRO / ENDM).
912 Suppose your macro contains a loop.
914 LoopyMacro: MACRO
916 xor a,a
917 .loop ld [hl+],a
918 dec c
919 jr nz,.loop
920 ENDM
921 This is fine, but only if you use the macro no more than once per scope.
923 To get around this problem, there is the escape sequence \@ that expands
924 to a unique string.
925 \@ also works in REPT blocks.
927 LoopyMacro: MACRO
929 xor a,a
930 .loop\@ ld [hl+],a
931 dec c
932 jr nz,.loop\@
933 ENDM
934 Important note: Since a macro can call itself (or a different macro that
936 calls the first one), there can be circular dependency problems. If this
937 creates an infinite loop, rgbasm will error out once a certain depth is
938 reached. See the -r command-line option in rgbasm(1). Also, a macro can
939 have inside an EQUS which references the same macro, which has the same
940 problem.
941 It's possible to pass arguments to macros as well! You retrieve the
943 arguments by using the escape sequences \1 through \9, \1 being the first
944 argument specified on the macro invocation.
945 LoopyMacro: MACRO
947 ld hl,\1
948 ld c,\2
949 xor a,a
950 .loop\@ ld [hl+],a
951 dec c
952 jr nz,.loop\@
953 ENDM
954 Now I can call the macro specifying two arguments, the first being the
956 address and the second being a byte count. The generated code will then
957 reset all bytes in this range.
958 LoopyMacro MyVars,54
960 Arguments are passed as string equates, although there's no need to
962 enclose them in quotes. Thus, an expression will not be evaluated first
963 but kind of copy-pasted. This means that it's probably a very good idea
964 to use brackets around \1 to \9 if you perform further calculations on
965 them. For instance, consider the following:
966 print_double: MACRO
968 PRINTV \1 * 2
969 ENDM
970 print_double 1 + 2
971 The PRINTV statement will expand to ‘PRINTV 1 + 2 * 2’, which will print
973 5 and not 6 as you might have expected.
974 Line continuations work as usual inside macros or lists of macro argu‐
976 ments. However, some characters need to be escaped, as in the following
977 example:
978 PrintMacro: MACRO
980 PRINTT \1
981 ENDM
982 PrintMacro STRCAT("Hello "\, \
984 "world\\n")
985 The comma needs to be escaped to avoid it being treated as separating the
987 macro's arguments. The backslash ‘\’ (from ‘\n’) also needs to be
988 escaped because of the way rgbasm processes macro arguments.
989 In reality, up to 256 arguments can be passed to a macro, but you can
991 only use the first 9 like this. If you want to use the rest, you need to
992 use the SHIFT command.
993 SHIFT is a special command only available in macros. Very useful in REPT
995 blocks. It will shift the arguments by one to the left, and decrease
996 _NARG by 1. \1 will get the value of \2, \2 will get the value of \3,
997 and so forth.
998 This is the only way of accessing the value of arguments from 10 to 256.
1000 SHIFT can optionally be given an integer parameter, and will apply the
1002 above shifting that number of times.
1003 Printing things during assembly
1005 The next four commands print text and values to the standard output.
1006 Useful for debugging macros, or wherever you may feel the need to tell
1007 yourself some important information.
1008 PRINTT "I'm the greatest programmer in the whole wide world\n"
1010 PRINTI (2 + 3) / 5
1011 PRINTV $FF00 + $F0
1012 PRINTF MUL(3.14, 3987.0)
1013 PRINTT prints out a string. Be careful to add a line feed ("\n") at the
1015 end, as it is not added automatically.
1016 PRINTV prints out an integer value in hexadecimal or, as in the example,
1018 the result of a calculation. Unsurprisingly, you can also print out a
1019 constant symbol's value.
1020 PRINTI prints out a signed integer value.
1022 PRINTF prints out a fixed point value.
1024 Be careful that none of those automatically print a line feed; if you
1026 need one, use PRINTT \n.
1027 Automatically repeating blocks of code
1029 Suppose you want to unroll a time consuming loop without copy-pasting it.
1030 REPT is here for that purpose. Everything between REPT and the matching
1031 ENDR will be repeated a number of times just as if you had done a
1032 copy/paste operation yourself. The following example will assemble ‘add
1033 a,c’ four times:
1034 REPT 4
1036 add a,c
1037 ENDR
1038 You can also use REPT to generate tables on the fly:
1040 ; --
1042 ; -- Generate a 256 byte sine table with values between 0 and 128
1043 ; --
1044 ANGLE = 0.0
1045 REPT 256
1046 db (MUL(64.0, SIN(ANGLE)) + 64.0) >> 16
1047 ANGLE = ANGLE+256.0
1048 ENDR
1049 As in macros, you can also use the escape sequence \@. REPT blocks can
1051 be nested.
1052 Aborting the assembly process
1054 FAIL and WARN can be used to print errors and warnings respectively dur‐
1055 ing the assembly process. This is especially useful for macros that get
1056 an invalid argument. FAIL and WARN take a string as the only argument
1057 and they will print this string out as a normal error with a line number.
1058 FAIL stops assembling immediately while WARN shows the message but con‐
1060 tinues afterwards.
1061 If you need to ensure some assumption is correct when compiling, you can
1063 use ASSERT and STATIC_ASSERT. Syntax examples are given below:
1064 Function:
1066 xor a
1067 ASSERT LOW(Variable) == 0
1068 ld h, HIGH(Variable)
1069 ld l, a
1070 ld a, [hli]
1071 ; You can also indent this!
1072 ASSERT BANK(OtherFunction) == BANK(Function)
1073 call OtherFunction
1074 ; Lowercase also works
1075 assert Variable + 1 == OtherVariable
1076 ld c, [hl]
1077 ret
1078 .end
1079 ; If you specify one, a message will be printed
1080 STATIC_ASSERT .end - Function < 256, "Function is too large!"
1081 First, the difference between ASSERT and STATIC_ASSERT is that the former
1083 is evaluated by RGBASM if it can, otherwise by RGBLINK; but the latter is
1084 only ever evaluated by RGBASM. If RGBASM cannot compute the value of the
1085 argument to STATIC_ASSERT, it will produce an error.
1086 Second, as shown above, a string can be optionally added at the end, to
1088 give insight into what the assertion is checking.
1089 Finally, you can add one of WARN, FAIL or FATAL as the first optional
1091 argument to either ASSERT or STATIC_ASSERT. If the assertion fails, WARN
1092 will cause a simple warning (controlled by rgbasm(1) flag -Wassert) to be
1093 emitted; FAIL (the default) will cause a non-fatal error; and FATAL imme‐
1094 diately aborts.
1095 Including other source files
1097 Use INCLUDE to process another assembler file and then return to the cur‐
1098 rent file when done. If the file isn't found in the current directory,
1099 the include path list (see the -i option in rgbasm(1)) will be searched.
1100 You may nest INCLUDE calls infinitely (or until you run out of memory,
1101 whichever comes first).
1102 INCLUDE "irq.inc"
1104 Conditional assembling
1106 The four commands IF, ELIF, ELSE, and ENDC let you have rgbasm skip over
1107 parts of your code depending on a condition. This is a powerful feature
1108 commonly used in macros.
1109 IF NUM < 0
1111 PRINTT "NUM < 0\n"
1112 ELIF NUM == 0
1113 PRINTT "NUM == 0\n"
1114 ELSE
1115 PRINTT "NUM > 0\n"
1116 ENDC
1117 The ELIF (standing for "else if") and ELSE blocks are optional. IF /
1119 ELIF / ELSE / ENDC blocks can be nested.
1120 Note that if an ELSE block is found before an ELIF block, the ELIF block
1122 will be ignored. All ELIF blocks must go before the ELSE block. Also,
1123 if there is more than one ELSE block, all of them but the first one are
1124 ignored.
1125
1127 Changing options while assembling
1128 OPT can be used to change some of the options during assembling from
1129 within the source, instead of defining them on the command-line.
1130 OPT takes a comma-separated list of options as its argument:
1132 PUSHO
1134 OPT g.oOX ;Set the GB graphics constants to use these characters
1135 DW `..ooOOXX
1136 POPO
1137 DW `00112233
1138 The options that OPT can modify are currently: b, g and p.
1140 POPO and PUSHO provide the interface to the option stack. PUSHO will
1142 push the current set of options on the option stack. POPO can then later
1143 be used to restore them. Useful if you want to change some options in an
1144 include file and you don't want to destroy the options set by the program
1145 that included your file. The stack's number of entries is limited only
1146 by the amount of memory in your machine.
1147 Requesting alignment
1149 While ALIGN as presented in SECTIONS is often useful as-is, sometimes you
1150 instead want a particular piece of data (or code) in the middle of the
1151 section to be aligned. This is made easier through the use of mid-sec‐
1152 tion align align, offset. It will alter the section's attributes to
1153 ensure that the location the align directive is at, has its align lower
1154 bits equal to offset.
1155 If the constraint cannot be met (for example because the section is fixed
1157 at an incompatible address), and error is produced. Note that align
1158 align is a shorthand for align align, 0.
1159
1161 rgbasm(1), rgblink(1), rgblink(5), rgbds(5), rgbds(7), gbz80(7)
1162
1164 rgbasm was originally written by Carsten Sørensen as part of the ASMotor
1165 package, and was later packaged in RGBDS by Justin Lloyd. It is now
1166 maintained by a number of contributors at .:
1167 https://github.com/gbdev/rgbds
1168BSD December 5, 2019 BSD