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 de‐
8 scription of the instructions supported by the Game Boy CPU is in
9 gbz80(7).
10 It is advisable to have some familiarity with the Game Boy hardware be‐
12 fore reading this document. RGBDS is specifically targeted at the Game
13 Boy, and thus a lot of its features tie directly to its concepts. This
14 document is not intended to be a Game Boy hardware reference.
15 Generally, “the linker” will refer to rgblink(1), but any program that
17 processes RGBDS object files (described in rgbds(5)) can be used in its
18 place.
19
21 The syntax is line-based, just as in any other assembler, meaning that
22 you do one instruction or directive per line:
23 [label] [instruction] [; comment]
25 Example:
27 John: ld a,87 ;Weee
29 All reserved keywords (directives, mnemonics, registers, etc.) are case-
31 insensitive; all identifiers (symbol names) are case-sensitive.
32 Comments are used to give humans information about the code, such as ex‐
34 planations. The assembler always ignores comments and their contents.
35 There are two syntaxes for comments. The most common is that anything
37 that follows a semicolon ‘;’ not inside a string, is a comment until the
38 end of the line. The second is a block comment, beginning with ‘/*’ and
39 ending with ‘*/’. It can be split across multiple lines, or occur in the
40 middle of an expression:
41 DEF X = /* the value of x
43 should be 3 */ 3
44 Sometimes lines can be too long and it may be necessary to split them.
46 To do so, put a backslash at the end of the line:
47 DB 1, 2, 3, \
49 4, 5, 6, \ ; Put it before any comments
50 7, 8, 9
51 DB "Hello, \ ; Space before the \ is included
52 world!" ; Any leading space is included
53 Symbol interpolation
55 A funky feature is writing a symbol between ‘{braces}’, called “symbol
56 interpolation”. This will paste the symbol's contents as if they were
57 part of the source file. If it is a string symbol, its characters are
58 simply inserted as-is. If it is a numeric symbol, its value is converted
59 to hexadecimal notation with a dollar sign ‘$’ prepended.
60 Symbol interpolations can be nested, too!
62 DEF topic EQUS "life, the universe, and \"everything\""
64 DEF meaning EQUS "answer"
65 ; Defines answer = 42
66 DEF {meaning} = 42
67 ; Prints "The answer to life, the universe, and "everything" is $2A"
68 PRINTLN "The {meaning} to {topic} is {{meaning}}"
69 PURGE topic, meaning, {meaning}
70 Symbols can be interpolated even in the contexts that disable automatic
72 expansion of string constants: ‘name’ will be expanded in all of
73 ‘DEF({name})’, ‘DEF {name} EQU/=/EQUS/etc ...’, ‘PURGE {name}’, and
74 ‘MACRO {name}’, but, for example, won't be in ‘DEF(name)’.
75 It's possible to change the way symbols are printed by specifying a print
77 format like so: ‘{fmt:symbol}’. The ‘fmt’ specifier consists of these
78 parts: ‘<sign><prefix><align><pad><width><frac><type>’. These parts are:
79 Part Meaning
81 ‘<sign> May be’ ‘+’ or ‘ ’. If specified, prints this character in
82 front of non-negative numbers.
83 ‘<prefix> May be’ ‘#’. If specified, prints the appropriate prefix for
84 numbers, ‘$’, ‘&’, or ‘%’.
85 ‘<align> May be’ ‘-’. If specified, aligns left instead of right.
86 ‘<pad> May be’ ‘0’. If specified, pads right-aligned numbers with
87 zeros instead of spaces.
88 ‘<width> May be one or more’ ‘0’ – ‘9’. If specified, pads the value
89 to this width, right-aligned with spaces by default.
90 ‘<frac> May be’ ‘.’ followed by one or more ‘0’ – ‘9’. If specified,
91 prints this many digits of a fixed-point fraction. Defaults
92 to 5 digits, maximum 255 digits.
93 ‘<type> Specifies the type of value.’
94 All the format specifier parts are optional except the ‘<type>’. Valid
96 print types are:
97 Print type Format Example
99 ‘d Signed decimal -42’
100 ‘u Unsigned decimal 42’
101 ‘x Lowercase hexadecimal 2a’
102 ‘X Uppercase hexadecimal 2A’
103 ‘b Binary 101010’
104 ‘o Octal 52’
105 ‘f Fixed-point 1234.56789’
106 ‘s String "example"’
107 Examples:
109 SECTION "Test", ROM0[2]
111 X: ; This works with labels **whose address is known**
112 DEF Y = 3 ; This also works with variables
113 DEF SUM EQU X + Y ; And likewise with numeric constants
114 ; Prints "%0010 + $3 == 5"
115 PRINTLN "{#05b:X} + {#x:Y} == {d:SUM}"
116 rsset 32
118 DEF PERCENT rb 1 ; Same with offset constants
119 DEF VALUE = 20
120 DEF RESULT = MUL(20.0, 0.32)
121 ; Prints "32% of 20 = 6.40"
122 PRINTLN "{d:PERCENT}% of {d:VALUE} = {f:RESULT}"
123 DEF WHO EQUS STRLWR("WORLD")
125 ; Prints "Hello world!"
126 PRINTLN "Hello {s:WHO}!"
127 Although, for these examples, STRFMT would be more approriate; see String
129 expressions further below.
130
132 An expression can be composed of many things. Numeric expressions are
133 always evaluated using signed 32-bit math. Zero is considered to be the
134 only "false" number, all non-zero numbers (including negative) are
135 "true".
136 An expression is said to be "constant" if rgbasm knows its value. This
138 is generally always the case, unless a label is involved, as explained in
139 the SYMBOLS section.
140 The instructions in the macro-language generally require constant expres‐
142 sions.
143 Numeric formats
145 There are a number of numeric formats.
146 Format type Prefix Accepted characters
148 Hexadecimal $ 0123456789ABCDEF
149 Decimal none 0123456789
150 Octal & 01234567
151 Binary % 01
152 Fixed-point none 01234.56789
153 Precise fixed-point none 12.34q8
154 Character constant none "ABYZ"
155 Gameboy graphics ` 0123
156 Underscores are also accepted in numbers, except at the beginning of one.
158 This can be useful for grouping digits, like ‘123_456’ or ‘%1100_1001’.
159 The "character constant" form yields the value the character maps to in
161 the current charmap. For example, by default (refer to ascii(7)) ‘"A"’
162 yields 65. See Character maps for information on charmaps.
163 The last one, Gameboy graphics, is quite interesting and useful. After
165 the backtick, 8 digits between 0 and 3 are expected, corresponding to
166 pixel values. The resulting value is the two bytes of tile data that
167 would produce that row of pixels. For example, ‘`01012323’ is equivalent
168 to ‘$0F55’.
169 You can also use symbols, which are implicitly replaced with their value.
171 Operators
173 A great number of operators you can use in expressions are available
174 (listed from highest to lowest precedence):
175 Operator Meaning
177 ( ) Precedence override
178 FUNC() Built-in function call
179 ** Exponent
180 ~ + - Unary complement/plus/minus
181 * / % Multiply/divide/modulo
182 << Shift left
183 >> Signed shift right (sign-extension)
184 >>> Unsigned shift right (zero-extension)
185 & | ^ Binary and/or/xor
186 + - Add/subtract
187 != == <= >= < > Comparison
188 && || Boolean and/or
189 ! Unary not
190 ~ complements a value by inverting all its bits.
192 % is used to get the remainder of the corresponding division, so that ‘a
194 / b * b + a % b == a’ is always true. The result has the same sign as
195 the divisor. This makes ‘a % b’. equal to ‘(a + b) % b’ or ‘(a - b) %
196 b’.
197 Shifting works by shifting all bits in the left operand either left
199 (‘<<’) or right (‘>>’) by the right operand's amount. When shifting
200 left, all newly-inserted bits are reset; when shifting right, they are
201 copies of the original most significant bit instead. This makes ‘a << b’
202 and ‘a >> b’ equivalent to multiplying and dividing by 2 to the power of
203 b, respectively.
204 Comparison operators return 0 if the comparison is false, and 1 other‐
206 wise.
207 Unlike in a lot of languages, and for technical reasons, rgbasm still
209 evaluates both operands of ‘&&’ and ‘||’.
210 ! returns 1 if the operand was 0, and 0 otherwise.
212 Fixed-point expressions
214 Fixed-point numbers are basically normal (32-bit) integers, which count
215 fractions instead of whole numbers. They offer better precision than in‐
216 tegers but limit the range of values. By default, the upper 16 bits are
217 used for the integer part and the lower 16 bits are used for the fraction
218 (65536ths). The default number of fractional bits can be changed with
219 the -Q command-line option. You can also specify a precise fixed-point
220 value by appending a “q” to it followed by the number of fractional bits,
221 such as ‘12.34q8’.
222 Since fixed-point values are still just integers, you can use them in
224 normal integer expressions. Some integer operators like ‘+’ and ‘-’
225 don't care whether the operands are integers or fixed-point. You can
226 easily truncate a fixed-point number into an integer by shifting it right
227 by 16 bits. It follows that you can convert an integer to a fixed-point
228 number by shifting it left.
229 The following functions are designed to operate with fixed-point numbers:
231 Name Operation
233 DIV(x, y) Fixed-point division (x÷y)×(2precision)
234 MUL(x, y) Fixed-point multiplication (x×y)÷(2precision)
235 FMOD(x, y) Fixed-point modulo (x%y)÷(2precision)
236 POW(x, y) x to the y power
237 LOG(x, y) Logarithm of x to the base y
238 ROUND(x) Round x to the nearest integer
239 CEIL(x) Round x up to an integer
240 FLOOR(x) Round x down to an integer
241 SIN(x) Sine of x
242 COS(x) Cosine of x
243 TAN(x) Tangent of x
244 ASIN(x) Inverse sine of x
245 ACOS(x) Inverse cosine of x
246 ATAN(x) Inverse tangent of x
247 ATAN2(x, y) Angle between (x,y) and (1,0)
248 All of these fixed-point functions can take an optional final argument,
250 which is the precision to use. For example, ‘MUL(6.0q8, 7.0q8, 8)’ will
251 evaluate to ‘42.0q8’ no matter what value is set as the current Q option.
252 The trigonometry functions ( SIN, COS, TAN, etc) are defined in terms of
254 a circle divided into 1.0 "turns" (equal to 2pi radians or 360 degrees).
255 These functions are useful for automatic generation of various tables.
257 For example:
258 ; Generate a table of sine values from sin(0.0) to sin(1.0), with
260 ; amplitude scaled from [-1.0, 1.0] to [0.0, 128.0]
261 DEF turns = 0.0
262 REPT 256
263 db MUL(64.0, SIN(turns) + 1.0) >> 16
264 DEF turns += 1.0 / 256
265 ENDR
266 String expressions
268 The most basic string expression is any number of characters contained in
269 double quotes (‘"for instance"’). The backslash character ‘\’ is special
270 in that it causes the character following it to be “escaped”, meaning
271 that it is treated differently from normal. There are a number of escape
272 sequences you can use within a string:
273 String Meaning
275 ‘\\ Produces a backslash’
276 ‘\" Produces a double quote without terminating’
277 ‘\{ Curly bracket left’
278 ‘\} Curly bracket right’
279 ‘\n Newline ($0A)’
280 ‘\r Carriage return ($0D)’
281 ‘\t Tab ($09)’
282 "\1" – "\9" Macro argument (Only in the body of a macro;
283 see Invoking macros)
284 ‘\# All _NARG macro arguments, separated by
285 commas (Only in the body of a macro)’
286 ‘\@ Label name suffix (Only in the body of a
287 macro or a REPT block)’
288 (Note that some of those can be used outside of strings, when noted fur‐
289 ther in this document.)
290 Multi-line strings are contained in triple quotes (‘"""for instance"""’).
292 Escape sequences work the same way in multi-line strings; however, lit‐
293 eral newline characters will be included as-is, without needing to escape
294 them with ‘\r’ or ‘\n’.
295 The following functions operate on string expressions. Most of them re‐
297 turn a string, however some of these functions actually return an integer
298 and can be used as part of an integer expression!
299 Name Operation
301 STRLEN(str) Returns the number of characters in str.
302 STRCAT(strs...) Concatenates strs.
303 STRCMP(str1, str2) Returns -1 if str1 is alphabetically lower than
304 str2 , zero if they match, 1 if str1 is greater
305 than str2.
306 STRIN(str1, str2) Returns the first position of str2 in str1 or
307 zero if it's not present (first character is
308 position 1).
309 STRRIN(str1, str2) Returns the last position of str2 in str1 or
310 zero if it's not present (first character is
311 position 1).
312 STRSUB(str, pos, len) Returns a substring from str starting at pos
313 (first character is position 1, last is position
314 -1) and len characters long. If len is not
315 specified the substring continues to the end of
316 str.
317 STRUPR(str) Returns str with all letters in uppercase.
318 STRLWR(str) Returns str with all letters in lowercase.
319 STRRPL(str, old, new) Returns str with each non-overlapping occurrence
320 of the substring old replaced with new.
321 STRFMT(fmt, args...) Returns the string fmt with each ‘%spec’ pattern
322 replaced by interpolating the format spec (using
323 the same syntax as Symbol interpolation) with
324 its corresponding argument in args (‘%%’ is
325 replaced by the ‘%’ character).
326 CHARLEN(str) Returns the number of charmap entries in str
327 with the current charmap.
328 CHARSUB(str, pos) Returns the substring for the charmap entry at
329 pos in str (first character is position 1, last
330 is position -1) with the current charmap.
331 Character maps
333 When writing text strings that are meant to be displayed on the Game Boy,
334 the character encoding in the ROM may need to be different than the
335 source file encoding. For example, the tiles used for uppercase letters
336 may be placed starting at tile index 128, which differs from ASCII start‐
337 ing at 65.
338 Character maps allow mapping strings to arbitrary 8-bit values:
340 CHARMAP "<LF>", 10
342 CHARMAP "í", 20
343 CHARMAP "A", 128
344 This would result in ‘db "Amen<LF>"’ being equivalent to ‘db 128, 109,
345 101, 110, 10’.
346 Any characters in a string without defined mappings will be copied di‐
348 rectly, using the source file's encoding of characters to bytes.
349 It is possible to create multiple character maps and then switch between
351 them as desired. This can be used to encode debug information in ASCII
352 and use a different encoding for other purposes, for example. Initially,
353 there is one character map called ‘main’ and it is automatically selected
354 as the current character map from the beginning. There is also a charac‐
355 ter map stack that can be used to save and restore which character map is
356 currently active.
357 Command Meaning
359 NEWCHARMAP name Creates a new, empty character map called
360 name and switches to it.
361 NEWCHARMAP name, basename Creates a new character map called name,
362 copied from character map basename, and
363 switches to it.
364 SETCHARMAP name Switch to character map name.
365 PUSHC Push the current character map onto the
366 stack.
367 POPC Pop a character map off the stack and switch
368 to it.
369 Note: Modifications to a character map take effect immediately from that
371 point onward.
372 Other functions
374 There are a few other functions that do various useful things:
375 Name Operation
377 BANK(arg) Returns a bank number. If arg is the symbol @, this func‐
378 tion returns the bank of the current section. If arg is a
379 string, it returns the bank of the section that has that
380 name. If arg is a label, it returns the bank number the
381 label is in. The result may be constant if rgbasm is able
382 to compute it.
383 SECTION(symbol)Returns the name of the section that symbol is in. symbol
384 must have been defined already.
385 SIZEOF(arg) Returns the size of the section named arg. The result is
386 not constant, since only RGBLINK can compute its value.
387 STARTOF(arg) Returns the starting address of the section named arg.
388 The result is not constant, since only RGBLINK can compute
389 its value.
390 DEF(symbol) Returns TRUE (1) if symbol has been defined, FALSE (0)
391 otherwise. String constants are not expanded within the
392 parentheses.
393 HIGH(arg) Returns the top 8 bits of the operand if arg is a label or
394 constant, or the top 8-bit register if it is a 16-bit
395 register.
396 LOW(arg) Returns the bottom 8 bits of the operand if arg is a label
397 or constant, or the bottom 8-bit register if it is a
398 16-bit register (AF isn't a valid register for this
399 function).
400 ISCONST(arg) Returns 1 if arg's value is known by RGBASM (e.g. if it
401 can be an argument to IF), or 0 if only RGBLINK can com‐
402 pute its value.
403
405 Before you can start writing code, you must define a section. This tells
406 the assembler what kind of information follows and, if it is code, where
407 to put it.
408 SECTION name, type
410 SECTION name, type, options
411 SECTION name, type[addr]
412 SECTION name, type[addr], options
413 name is a string enclosed in double quotes, and can be a new name or the
415 name of an existing section. If the type doesn't match, an error occurs.
416 All other sections must have a unique name, even in different source
417 files, or the linker will treat it as an error.
418 Possible section types are as follows:
420 ROM0 A ROM section. addr can range from $0000 to $3FFF, or $0000 to
422 $7FFF if tiny ROM mode is enabled in the linker.
423 ROMX A banked ROM section. addr can range from $4000 to $7FFF. bank
425 can range from 1 to 511. Becomes an alias for ROM0 if tiny ROM
426 mode is enabled in the linker.
427 VRAM A banked video RAM section. addr can range from $8000 to $9FFF.
429 bank can be 0 or 1, but bank 1 is unavailable if DMG mode is en‐
430 abled in the linker.
431 SRAM A banked external (save) RAM section. addr can range from $A000
433 to $BFFF. bank can range from 0 to 15.
434 WRAM0 A general-purpose RAM section. addr can range from $C000 to
436 $CFFF, or $C000 to $DFFF if WRAM0 mode is enabled in the linker.
437 WRAMX A banked general-purpose RAM section. addr can range from $D000
439 to $DFFF. bank can range from 1 to 7. Becomes an alias for
440 WRAM0 if WRAM0 mode is enabled in the linker.
441 OAM An object attribute RAM section. addr can range from $FE00 to
443 $FE9F.
444 HRAM A high RAM section. addr can range from $FF80 to $FFFE.
446 Note: While rgbasm will automatically optimize ld instructions to
448 the smaller and faster ldh (see gbz80(7)) whenever possible, it
449 is generally unable to do so when a label is involved. Using the
450 ldh instruction directly is recommended. This forces the assem‐
451 bler to emit a ldh instruction and the linker to check if the
452 value is in the correct range.
453 Since RGBDS produces ROMs, code and data can only be placed in ROM0 and
455 ROMX sections. To put some in RAM, have it stored in ROM, and copy it to
456 RAM.
457 options are comma-separated and may include:
459 BANK[bank]
461 Specify which bank for the linker to place the section in. See
462 above for possible values for bank, depending on type.
463 ALIGN[align, offset]
465 Place the section at an address whose align least-significant
466 bits are equal to offset. (Note that ALIGN[align] is a shorthand
467 for ALIGN[align, 0]). This option can be used with [addr], as
468 long as they don't contradict eachother. It's also possible to
469 request alignment in the middle of a section, see Requesting
470 alignment below.
471 If [addr] is not specified, the section is considered “floating”; the
473 linker will automatically calculate an appropriate address for the sec‐
474 tion. Similarly, if BANK[bank] is not specified, the linker will auto‐
475 matically find a bank with enough space.
476 Sections can also be placed by using a linker script file. The format is
478 described in rgblink(5). They allow the user to place floating sections
479 in the desired bank in the order specified in the script. This is useful
480 if the sections can't be placed at an address manually because the size
481 may change, but they have to be together.
482 Section examples:
484 SECTION "Cool Stuff",ROMX
487 This switches to the section called “CoolStuff”, creating it if it
488 doesn't already exist. It can end up in any ROM bank. Code and data may
489 follow.
490 If it is needed, the the base address of the section can be specified:
492 SECTION "Cool Stuff",ROMX[$4567]
494 An example with a fixed bank:
496 SECTION "Cool Stuff",ROMX[$4567],BANK[3]
498 And if you want to force only the section's bank, and not its position
500 within the bank, that's also possible:
501 SECTION "Cool Stuff",ROMX,BANK[7]
503 Alignment examples: The first one could be useful for defining an OAM
505 buffer to be DMA'd, since it must be aligned to 256 bytes. The second
506 could also be appropriate for GBC HDMA, or for an optimized copy code
507 that requires alignment.
508 SECTION "OAM Data",WRAM0,ALIGN[8] ; align to 256 bytes
510 SECTION "VRAM Data",ROMX,BANK[2],ALIGN[4] ; align to 16 bytes
511 Section stack
513 POPS and PUSHS provide the interface to the section stack. The number of
514 entries in the stack is limited only by the amount of memory in your ma‐
515 chine.
516 PUSHS will push the current section context on the section stack. POPS
518 can then later be used to restore it. Useful for defining sections in
519 included files when you don't want to override the section context at the
520 point the file was included.
521 RAM code
523 Sometimes you want to have some code in RAM. But then you can't simply
524 put it in a RAM section, you have to store it in ROM and copy it to RAM
525 at some point.
526 This means the code (or data) will not be stored in the place it gets ex‐
528 ecuted. Luckily, LOAD blocks are the perfect solution to that. Here's
529 an example of how to use them:
530 SECTION "LOAD example", ROMX
532 CopyCode:
533 ld de, RAMCode
534 ld hl, RAMLocation
535 ld c, RAMLocation.end - RAMLocation
536 .loop
537 ld a, [de]
538 inc de
539 ld [hli], a
540 dec c
541 jr nz, .loop
542 ret
543 RAMCode:
545 LOAD "RAM code", WRAM0
546 RAMLocation:
547 ld hl, .string
548 ld de, $9864
549 .copy
550 ld a, [hli]
551 ld [de], a
552 inc de
553 and a
554 jr nz, .copy
555 ret
556 .string
558 db "Hello World!", 0
559 .end
560 ENDL
561 A LOAD block feels similar to a SECTION declaration because it creates a
563 new one. All data and code generated within such a block is placed in
564 the current section like usual, but all labels are created as if they
565 were placed in this newly-created section.
566 In the example above, all of the code and data will end up in the "LOAD
568 example" section. You will notice the ‘RAMCode’ and ‘RAMLocation’ la‐
569 bels. The former is situated in ROM, where the code is stored, the lat‐
570 ter in RAM, where the code will be loaded.
571 You cannot nest LOAD blocks, nor can you change the current section
573 within them.
574 LOAD blocks can use the UNION or FRAGMENT modifiers, as described below.
576 Unionized sections
578 When you're tight on RAM, you may want to define overlapping static mem‐
579 ory allocations, as explained in the Unions section. However, a UNION
580 only works within a single file, so it can't be used e.g. to define tem‐
581 porary variables across several files, all of which use the same stati‐
582 cally allocated memory. Unionized sections solve this problem. To de‐
583 clare an unionized section, add a UNION keyword after the SECTION one;
584 the declaration is otherwise not different. Unionized sections follow
585 some different rules from normal sections:
586 • The same unionized section (i.e. having the same name) can be
588 declared several times per rgbasm invocation, and across sev‐
589 eral invocations. Different declarations are treated and
590 merged identically whether within the same invocation, or dif‐
591 ferent ones.
592 • If one section has been declared as unionized, all sections
594 with the same name must be declared unionized as well.
595 • All declarations must have the same type. For example, even if
597 rgblink(1)'s -w flag is used, WRAM0 and WRAMX types are still
598 considered different.
599 • Different constraints (alignment, bank, etc.) can be specified
601 for each unionized section declaration, but they must all be
602 compatible. For example, alignment must be compatible with any
603 fixed address, all specified banks must be the same, etc.
604 • Unionized sections cannot have type ROM0 or ROMX.
606 Different declarations of the same unionized section are not appended,
608 but instead overlaid on top of eachother, just like Unions. Similarly,
609 the size of an unionized section is the largest of all its declarations.
610 Section fragments
612 Section fragments are sections with a small twist: when several of the
613 same name are encountered, they are concatenated instead of producing an
614 error. This works within the same file (paralleling the behavior "plain"
615 sections has in previous versions), but also across object files. To de‐
616 clare an section fragment, add a FRAGMENT keyword after the SECTION one;
617 the declaration is otherwise not different. However, similarly to
618 Unionized sections, some rules must be followed:
619 • If one section has been declared as fragment, all sections with
621 the same name must be declared fragments as well.
622 • All declarations must have the same type. For example, even if
624 rgblink(1)'s -w flag is used, WRAM0 and WRAMX types are still
625 considered different.
626 • Different constraints (alignment, bank, etc.) can be specified
628 for each unionized section declaration, but they must all be
629 compatible. For example, alignment must be compatible with any
630 fixed address, all specified banks must be the same, etc.
631 • A section fragment may not be unionized; after all, that
633 wouldn't make much sense.
634 When RGBASM merges two fragments, the one encountered later is appended
636 to the one encountered earlier.
637 When RGBLINK merges two fragments, the one whose file was specified last
639 is appended to the one whose file was specified first. For example, as‐
640 suming ‘bar.o’, ‘baz.o’, and ‘foo.o’ all contain a fragment with the same
641 name, the command
642 rgblink -o rom.gb baz.o foo.o bar.o
643 would produce the fragment from ‘baz.o’ first, followed by the one from
644 ‘foo.o’, and the one from ‘bar.o’ last.
645
647 RGBDS supports several types of symbols:
648 Label Numeric symbol designating a memory location. May or may not
650 have a value known at assembly time.
651 Constant Numeric symbol whose value has to be known at assembly time.
653 Macro A block of rgbasm code that can be invoked later.
655 String A text string that can be expanded later, similarly to a macro.
657 Symbol names can contain ASCII letters, numbers, underscores ‘_’, hashes
659 ‘#’ and at signs ‘@’. However, they must begin with either a letter or
660 an underscore. Additionally, label names can contain up to a single dot
661 ‘.’, which may not be the first character.
662 A symbol cannot have the same name as a reserved keyword.
664 Labels
666 One of the assembler's main tasks is to keep track of addresses for you,
667 so you can work with meaningful names instead of “magic” numbers. Labels
668 enable just that: a label ties a name to a specific location within a
669 section. A label resolves to a bank and address, determined at the same
670 time as its parent section's (see further in this section).
671 A label is defined by writing its name at the beginning of a line, fol‐
673 lowed by one or two colons, without any whitespace between the label name
674 and the colon(s). Declaring a label (global or local) with two colons
675 ‘::’ will define and EXPORT it at the same time. (See Exporting and
676 importing symbols below). When defining a local label, the colon can be
677 omitted, and rgbasm will act as if there was only one.
678 A label is said to be local if its name contains a dot ‘.’; otherwise, it
680 is said to be global (not to be mistaken with “exported”, explained in
681 Exporting and importing symbols further below). More than one dot in la‐
682 bel names is not allowed.
683 For convenience, local labels can use a shorthand syntax: when a symbol
685 name starting with a dot is found (for example, inside an expression, or
686 when declaring a label), then the current “label scope” is implicitly
687 prepended.
688 Defining a global label sets it as the current “label scope”, until the
690 next global label definition, or the end of the current section.
691 Here are some examples of label definitions:
693 GlobalLabel:
695 AnotherGlobal:
696 .locallabel ; This defines "AnotherGlobal.locallabel"
697 .another_local:
698 AnotherGlobal.with_another_local:
699 ThisWillBeExported:: ; Note the two colons
700 ThisWillBeExported.too::
701 In a numeric expression, a label evaluates to its address in memory. (To
703 obtain its bank, use the ‘BANK()’ function described in Other functions).
704 For example, given the following, ‘ld de, vPlayerTiles’ would be equiva‐
705 lent to ‘ld de, $80C0’ assuming the section ends up at $80C0:
706 SECTION "Player tiles", VRAM
708 vPlayerTiles:
709 ds 6 * 16
710 .end
711 A label's location (and thus value) is usually not determined until the
713 linking stage, so labels usually cannot be used as constants. However,
714 if the section in which the label is defined has a fixed base address,
715 its value is known at assembly time.
716 Also, while rgbasm obviously can compute the difference between two la‐
718 bels if both are constant, it is also able to compute the difference be‐
719 tween two non-constant labels if they both belong to the same section,
720 such as ‘PlayerTiles’ and ‘PlayerTiles.end’ above.
721 Anonymous labels
723 Anonymous labels are useful for short blocks of code. They are defined
724 like normal labels, but without a name before the colon. Anonymous la‐
725 bels are independent of label scoping, so defining one does not change
726 the scoped label, and referencing one is not affected by the current
727 scoped label.
728 Anonymous labels are referenced using a colon ‘:’ followed by pluses ‘+’
730 or minuses ‘-’. Thus :+ references the next one after the expression,
731 :++ the one after that; :- references the one before the expression; and
732 so on.
733 ld hl, :++
735 : ld a, [hli] ; referenced by "jr nz"
736 ldh [c], a
737 dec c
738 jr nz, :-
739 ret
740 : ; referenced by "ld hl"
742 dw $7FFF, $1061, $03E0, $58A5
743 Variables
745 An equal sign = is used to define mutable numeric symbols. Unlike the
746 other symbols described below, variables can be redefined. This is use‐
747 ful for internal symbols in macros, for counters, etc.
748 DEF ARRAY_SIZE EQU 4
750 DEF COUNT = 2
751 DEF COUNT = 3
752 DEF COUNT = ARRAY_SIZE + COUNT
753 DEF COUNT *= 2
754 ; COUNT now has the value 14
755 Note that colons ‘:’ following the name are not allowed.
757 Variables can be conveniently redefined by compound assignment operators
759 like in C:
760 Operator Meaning
762 += -= Compound plus/minus
763 *= /= %= Compound multiply/divide/modulo
764 <<= >>= Compound shift left/right
765 &= |= ^= Compound and/or/xor
766 Examples:
768 DEF x = 10
770 DEF x += 1 ; x == 11
771 DEF y = x - 1 ; y == 10
772 DEF y *= 2 ; y == 20
773 DEF y >>= 1 ; y == 10
774 DEF x ^= y ; x == 1
775 Numeric constants
777 EQU is used to define immutable numeric symbols. Unlike = above, con‐
778 stants defined this way cannot be redefined. These constants can be used
779 for unchanging values such as properties of the hardware.
780 def SCREEN_WIDTH equ 160 ; In pixels
782 def SCREEN_HEIGHT equ 144
783 Note that colons ‘:’ following the name are not allowed.
785 If you really need to, the REDEF keyword will define or redefine a nu‐
787 meric constant symbol. (It can also be used for variables, although it's
788 not necessary since they are mutable.) This can be used, for example, to
789 update a constant using a macro, without making it mutable in general.
790 def NUM_ITEMS equ 0
792 MACRO add_item
793 redef NUM_ITEMS equ NUM_ITEMS + 1
794 def ITEM_{02x:NUM_ITEMS} equ \1
795 ENDM
796 add_item 1
797 add_item 4
798 add_item 9
799 add_item 16
800 assert NUM_ITEMS == 4
801 assert ITEM_04 == 16
802 Offset constants
804 The RS group of commands is a handy way of defining structure offsets:
805 RSRESET
807 DEF str_pStuff RW 1
808 DEF str_tData RB 256
809 DEF str_bCount RB 1
810 DEF str_SIZEOF RB 0
811 The example defines four constants as if by:
813 DEF str_pStuff EQU 0
815 DEF str_tData EQU 2
816 DEF str_bCount EQU 258
817 DEF str_SIZEOF EQU 259
818 There are five commands in the RS group of commands:
820 Command Meaning
822 RSRESET Equivalent to ‘RSSET 0’.
823 RSSET constexpr Sets the _RS counter to constexpr.
824 RB constexpr Sets the preceding symbol to _RS and adds constexpr to
825 _RS.
826 RW constexpr Sets the preceding symbol to _RS and adds constexpr *
827 2 to _RS.
828 RL constexpr Sets the preceding symbol to _RS and adds constexpr *
829 4 to _RS.
830 If the argument to RB, RW, or RL is omitted, it's assumed to be 1.
832 Note that colons ‘:’ following the name are not allowed.
834 String constants
836 EQUS is used to define string constant symbols. Wherever the assembler
837 reads a string constant, it gets expanded: the symbol's name is replaced
838 with its contents. If you are familiar with C, you can think of it as
839 similar to #define .
840 This expansion is disabled in a few contexts: ‘DEF(name)’, ‘DEF name
841 EQU/=/EQUS/etc ...’, ‘PURGE name’, and ‘MACRO name’ will not expand
842 string constants in their names.
843 DEF COUNTREG EQUS "[hl+]"
845 ld a,COUNTREG
846 DEF PLAYER_NAME EQUS "\"John\""
848 db PLAYER_NAME
849 This will be interpreted as:
851 ld a,[hl+]
853 db "John"
854 String constants can also be used to define small one-line macros:
856 DEF pusha EQUS "push af\npush bc\npush de\npush hl\n"
858 Note that colons ‘:’ following the name are not allowed.
860 String constants can't be exported or imported.
862 String constants, like numeric constants, cannot be redefined. However,
864 the REDEF keyword will define or redefine a string constant symbol. For
865 example:
866 DEF s EQUS "Hello, "
868 REDEF s EQUS "{s}world!"
869 ; prints "Hello, world!"
870 PRINTLN "{s}0
871 Important note: When a string constant is expanded, its expansion may
873 contain another string constant, which will be expanded as well. If this
874 creates an infinite loop, rgbasm will error out once a certain depth is
875 reached. See the -r command-line option in rgbasm(1). The same problem
876 can occur if the expansion of a macro invokes another macro, recursively.
877 The examples above for ‘EQU’, ‘=’, ‘RB’, ‘RW’, ‘RL’, and ‘EQUS’ all start
879 with ‘DEF’. (A variable definition may start with ‘REDEF’ instead, since
880 they are redefinable.) You may use the older syntax without ‘DEF’, but
881 then the name being defined must not have any whitespace before it; oth‐
882 erwise rgbasm will treat it as a macro invocation. Furthermore, without
883 the ‘DEF’ keyword, string constants may be expanded for the name. This
884 can lead to surprising results:
885 X EQUS "Y"
887 ; this defines Y, not X!
888 X EQU 42
889 ; prints "Y $2A"
890 PRINTLN "{X} {Y}"
891 Macros
893 One of the best features of an assembler is the ability to write macros
894 for it. Macros can be called with arguments, and can react depending on
895 input using IF constructs.
896 MACRO MyMacro
898 ld a, 80
899 call MyFunc
900 ENDM
901 The example above defines ‘MyMacro’ as a new macro. String constants are
903 not expanded within the name of the macro.
904 (Using the deprecated older syntax ‘MyMacro: MACRO’ instead of ‘MACRO
906 MyMacro’, with a single colon ‘:’ following the macro's name, string con‐
907 stants may be expanded for the name.)
908 Macros can't be exported or imported.
910 Plainly nesting macro definitions is not allowed, but this can be worked
912 around using EQUS. So this won't work:
913 MACRO outer
915 MACRO inner
916 PRINTLN "Hello!"
917 ENDM
918 ENDM
919 But this will:
921 MACRO outer
923 DEF definition EQUS "MACRO inner\nPRINTLN \"Hello!\"\nENDM"
924 definition
925 PURGE definition
926 ENDM
927 Macro arguments support all the escape sequences of strings, as well as
929 ‘\,’ to escape commas, as well as ‘\(’ and ‘\)’ to escape parentheses,
930 since those otherwise separate and enclose arguments, respectively.
931 Exporting and importing symbols
933 Importing and exporting of symbols is a feature that is very useful when
934 your project spans many source files and, for example, you need to jump
935 to a routine defined in another file.
936 Exporting of symbols has to be done manually, importing is done automati‐
938 cally if rgbasm finds a symbol it does not know about.
939 The following will cause symbol1, symbol2 and so on to be accessible to
941 other files during the link process:
942 EXPORT symbol1 [, symbol2, ...]
943 For example, if you have the following three files:
945 ‘a.asm’:
947 SECTION "a", WRAM0
948 LabelA:
949 ‘b.asm’:
951 SECTION "b", WRAM0
952 ExportedLabelB1::
953 ExportedLabelB2:
954 EXPORT ExportedLabelB2
955 ‘c.asm’:
957 SECTION "C", ROM0[0]
958 dw LabelA
959 dw ExportedLabelB1
960 dw ExportedLabelB2
961 Then ‘c.asm’ can use ‘ExportedLabelB1’ and ‘ExportedLabelB2’, but not
963 ‘LabelA’, so linking them together will fail:
964 $ rgbasm -o a.o a.asm
966 $ rgbasm -o b.o b.asm
967 $ rgbasm -o c.o c.asm
968 $ rgblink a.o b.o c.o
969 error: c.asm(2): Unknown symbol "LabelA"
970 Linking failed with 1 error
971 Note also that only exported symbols will appear in symbol and map files
973 produced by rgblink(1).
974 Purging symbols
976 PURGE allows you to completely remove a symbol from the symbol table as
977 if it had never existed. USE WITH EXTREME CAUTION! I can't stress this
978 enough, you seriously need to know what you are doing. DON'T purge a
979 symbol that you use in expressions the linker needs to calculate. When
980 not sure, it's probably not safe to purge anything other than variables,
981 numeric or string constants, or macros.
982 DEF Kamikaze EQUS "I don't want to live anymore"
984 DEF AOLer EQUS "Me too"
985 PURGE Kamikaze, AOLer
986 String constants are not expanded within the symbol names.
988 Predeclared symbols
990 The following symbols are defined by the assembler:
991 Name Type Contents
993 @ EQU PC value (essentially, the current
994 memory address)
995 _RS = _RS Counter
996 _NARG EQU Number of arguments passed to macro,
997 updated by SHIFT
998 __DATE__ EQUS Today's date
999 __TIME__ EQUS The current time
1000 __ISO_8601_LOCAL__ EQUS ISO 8601 timestamp (local)
1001 __ISO_8601_UTC__ EQUS ISO 8601 timestamp (UTC)
1002 __UTC_YEAR__ EQU Today's year
1003 __UTC_MONTH__ EQU Today's month number, 1–12
1004 __UTC_DAY__ EQU Today's day of the month, 1–31
1005 __UTC_HOUR__ EQU Current hour, 0–23
1006 __UTC_MINUTE__ EQU Current minute, 0–59
1007 __UTC_SECOND__ EQU Current second, 0–59
1008 __RGBDS_MAJOR__ EQU Major version number of RGBDS
1009 __RGBDS_MINOR__ EQU Minor version number of RGBDS
1010 __RGBDS_PATCH__ EQU Patch version number of RGBDS
1011 __RGBDS_RC__ EQU Release candidate ID of RGBDS, not
1012 defined for final releases
1013 __RGBDS_VERSION__ EQUS Version of RGBDS, as printed by
1014 ‘rgbasm --version’
1015 The current time values will be taken from the SOURCE_DATE_EPOCH environ‐
1017 ment variable if that is defined as a UNIX timestamp. Refer to the spec
1018 at https://reproducible-builds.org/docs/source-date-epoch/
1019
1021 Statically allocating space in RAM
1022 DS statically allocates a number of empty bytes. This is the preferred
1023 method of allocating space in a RAM section. You can also use DB, DW and
1024 DL without any arguments instead (see Defining constant data in ROM be‐
1025 low).
1026 DS 42 ; Allocates 42 bytes
1028 Empty space in RAM sections will not be initialized. In ROM sections, it
1030 will be filled with the value passed to the -p command-line option, ex‐
1031 cept when using overlays with -O.
1032 Defining constant data in ROM
1034 DB defines a list of bytes that will be stored in the final image. Ideal
1035 for tables and text.
1036 DB 1,2,3,4,"This is a string"
1038 Alternatively, you can use DW to store a list of words (16-bit) or DL to
1040 store a list of double-words/longs (32-bit). Both of these write their
1041 data in little-endian byte order; for example, ‘dw $CAFE’ is equivalent
1042 to ‘db $FE, $CA’ and not ‘db $CA, $FE’.
1043 Strings are handled a little specially: they first undergo charmap con‐
1045 version (see Character maps), then each resulting character is output in‐
1046 dividually. For example, under the default charmap, the following two
1047 lines are identical:
1048 DW "Hello!"
1050 DW "H", "e", "l", "l", "o", "!"
1051 If you do not want this special handling, enclose the string in parenthe‐
1053 ses.
1054 DS can also be used to fill a region of memory with some repeated values.
1056 For example:
1057 ; outputs 3 bytes: $AA, $AA, $AA
1059 DS 3, $AA
1060 ; outputs 7 bytes: $BB, $CC, $BB, $CC, $BB, $CC, $BB
1061 DS 7, $BB, $CC
1062 You can also use DB, DW and DL without arguments. This works exactly
1064 like DS 1, DS 2 and DS 4 respectively. Consequently, no-argument DB, DW
1065 and DL can be used in a WRAM0 / WRAMX / HRAM / VRAM / SRAM section.
1066 Including binary files
1068 You probably have some graphics, level data, etc. you'd like to include.
1069 Use INCBIN to include a raw binary file as it is. If the file isn't
1070 found in the current directory, the include-path list passed to rgbasm(1)
1071 (see the -i option) on the command line will be searched.
1072 INCBIN "titlepic.bin"
1074 INCBIN "sprites/hero.bin"
1075 You can also include only part of a file with INCBIN. The example below
1077 includes 256 bytes from data.bin, starting from byte 78.
1078 INCBIN "data.bin",78,256
1080 The length argument is optional. If only the start position is speci‐
1082 fied, the bytes from the start position until the end of the file will be
1083 included.
1084 Unions
1086 Unions allow multiple static memory allocations to overlap, like unions
1087 in C. This does not increase the amount of memory available, but allows
1088 re-using the same memory region for different purposes.
1089 A union starts with a UNION keyword, and ends at the corresponding ENDU
1091 keyword. NEXTU separates each block of allocations, and you may use it
1092 as many times within a union as necessary.
1093 ; Let's say PC = $C0DE here
1095 UNION
1096 ; Here, PC = $C0DE
1097 Name: ds 8
1098 ; PC = $C0E6
1099 Nickname: ds 8
1100 ; PC = $C0EE
1101 NEXTU
1102 ; PC is back to $C0DE
1103 Health: dw
1104 ; PC = $C0E0
1105 Something: ds 6
1106 ; And so on
1107 Lives: db
1108 NEXTU
1109 VideoBuffer: ds 19
1110 ENDU
1111 In the example above, ‘Name, Health, VideoBuffer’ all have the same
1113 value, as do ‘Nickname’ and ‘Lives’. Thus, keep in mind that ld
1114 [Health], a is identical to ld [Name], a.
1115 The size of this union is 19 bytes, as this is the size of the largest
1117 block (the last one, containing ‘VideoBuffer’). Nesting unions is possi‐
1118 ble, with each inner union's size being considered as described above.
1119 Unions may be used in any section, but inside them may only be DS - like
1121 commands (see Statically allocating space in RAM).
1122
1124 Invoking macros
1125 You execute the macro by inserting its name.
1126 add a,b
1128 ld sp,hl
1129 MyMacro ; This will be expanded
1130 sub a,87
1131 It's valid to call a macro from a macro (yes, even the same one).
1133 When rgbasm sees MyMacro it will insert the macro definition (the code
1135 enclosed in MACRO / ENDM).
1136 Suppose your macro contains a loop.
1138 MACRO LoopyMacro
1140 xor a,a
1141 .loop ld [hl+],a
1142 dec c
1143 jr nz,.loop
1144 ENDM
1145 This is fine, but only if you use the macro no more than once per scope.
1147 To get around this problem, there is the escape sequence \@ that expands
1148 to a unique string.
1149 \@ also works in REPT blocks.
1151 MACRO LoopyMacro
1153 xor a,a
1154 .loop\@ ld [hl+],a
1155 dec c
1156 jr nz,.loop\@
1157 ENDM
1158 Important note: Since a macro can call itself (or a different macro that
1160 calls the first one), there can be circular dependency problems. If this
1161 creates an infinite loop, rgbasm will error out once a certain depth is
1162 reached. See the -r command-line option in rgbasm(1). Also, a macro can
1163 have inside an EQUS which references the same macro, which has the same
1164 problem.
1165 It's possible to pass arguments to macros as well! You retrieve the ar‐
1167 guments by using the escape sequences \1 through \9, \1 being the first
1168 argument specified on the macro invocation.
1169 MACRO LoopyMacro
1171 ld hl,\1
1172 ld c,\2
1173 xor a,a
1174 .loop\@ ld [hl+],a
1175 dec c
1176 jr nz,.loop\@
1177 ENDM
1178 Now you can call the macro specifying two arguments, the first being the
1180 address and the second being a byte count. The generated code will then
1181 reset all bytes in this range.
1182 LoopyMacro MyVars,54
1184 Arguments are passed as string constants, although there's no need to en‐
1186 close them in quotes. Thus, an expression will not be evaluated first
1187 but kind of copy-pasted. This means that it's probably a very good idea
1188 to use brackets around \1 to \9 if you perform further calculations on
1189 them. For instance, consider the following:
1190 MACRO print_double
1192 PRINTLN \1 * 2
1193 ENDM
1194 print_double 1 + 2
1195 The PRINTLN statement will expand to ‘PRINTLN 1 + 2 * 2’, which will
1197 print 5 and not 6 as you might have expected.
1198 Line continuations work as usual inside macros or lists of macro argu‐
1200 ments. However, some characters need to be escaped, as in the following
1201 example:
1202 MACRO PrintMacro1
1204 PRINTLN STRCAT(\1)
1205 ENDM
1206 PrintMacro1 "Hello "\, \
1207 "world"
1208 MACRO PrintMacro2
1209 PRINT \1
1210 ENDM
1211 PrintMacro2 STRCAT("Hello ", \
1212 "world\n")
1213 The comma in ‘PrintMacro1’ needs to be escaped to prevent it from start‐
1215 ing another macro argument. The comma in ‘PrintMacro2’ does not need es‐
1216 caping because it is inside parentheses, similar to macro arguments in C.
1217 The backslash in ‘\n’ also does not need escaping because string literals
1218 work as usual inside macro arguments.
1219 Since there are only nine digits, you can only access the first nine
1221 macro arguments like this. To use the rest, you need to put the multi-
1222 digit argument number in angle brackets, like ‘\<10>’. This bracketed
1223 syntax supports decimal numbers and numeric constant symbols. For exam‐
1224 ple, ‘\<_NARG>’ will get the last argument.
1225 Other macro arguments and symbol interpolations will be expanded inside
1227 the angle brackets. For example, if ‘\1’ is ‘13’, then ‘\<\1>’ will ex‐
1228 pand to ‘\<13>’. Or if ‘v10 = 42’ and ‘x = 10’, then ‘\<v{d:x}>’ will
1229 expand to ‘\<42>’.
1230 Another way to access more than nine macro arguments is the SHIFT com‐
1232 mand, a special command only available in macros. It will shift the ar‐
1233 guments by one to the left, and decrease _NARG by 1. \1 will get the
1234 value of \2, \2 will get the value of \3, and so forth.
1235 SHIFT can optionally be given an integer parameter, and will apply the
1237 above shifting that number of times. A negative parameter will shift the
1238 arguments in reverse.
1239 SHIFT is useful in REPT blocks to repeat the same commands with multiple
1241 arguments.
1242 Printing things during assembly
1244 The PRINT and PRINTLN commands print text and values to the standard out‐
1245 put. Useful for debugging macros, or wherever you may feel the need to
1246 tell yourself some important information.
1247 PRINT "Hello world!\n"
1249 PRINTLN "Hello world!"
1250 PRINT _NARG, " arguments\n"
1251 PRINTLN "sum: ", 2+3, " product: ", 2*3
1252 PRINTLN "Line #", __LINE__
1253 PRINTLN STRFMT("E = %f", 2.718)
1254 PRINT prints out each of its comma-separated arguments. Numbers are
1256 printed as unsigned uppercase hexadecimal with a leading $. For differ‐
1257 ent formats, use STRFMT.
1258 PRINTLN prints out each of its comma-separated arguments, if any, fol‐
1260 lowed by a line feed (‘\n’).
1261 Automatically repeating blocks of code
1263 Suppose you want to unroll a time consuming loop without copy-pasting it.
1264 REPT is here for that purpose. Everything between REPT and the matching
1265 ENDR will be repeated a number of times just as if you had done a
1266 copy/paste operation yourself. The following example will assemble ‘add
1267 a,c’ four times:
1268 REPT 4
1270 add a,c
1271 ENDR
1272 You can also use REPT to generate tables on the fly:
1274 ; Generate a table of square values from 0**2 = 0 to 100**2 = 10000
1276 DEF x = 0
1277 REPT 101
1278 dw x * x
1279 DEF x += 1
1280 ENDR
1281 As in macros, you can also use the escape sequence \@. REPT blocks can
1283 be nested.
1284 A common pattern is to repeat a block for each value in some range. FOR
1286 is simpler than REPT for that purpose. Everything between FOR and the
1287 matching ENDR will be repeated for each value of a given symbol. String
1288 constants are not expanded within the symbol name. For example, this
1289 code will produce a table of squared values from 0 to 255:
1290 FOR N, 256
1292 dw N * N
1293 ENDR
1294 It acts just as if you had done:
1296 N = 0
1298 dw N * N
1299 N = 1
1300 dw N * N
1301 N = 2
1302 dw N * N
1303 ; ...
1304 N = 255
1305 dw N * N
1306 N = 256
1307 You can customize the range of FOR values, similarly to Python's ‘range’
1309 function:
1310 Code Range
1312 FOR V, stop V increments from 0 to stop
1313 FOR V, start, stop V increments from start to stop
1314 FOR V, start, stop, step V goes from start to stop by step
1315 The FOR value will be updated by step until it reaches or exceeds stop,
1317 i.e. it covers the half-open range from start (inclusive) to stop (exclu‐
1318 sive). The variable V will be assigned this value at the beginning of
1319 each new iteration; any changes made to it within the FOR loop's body
1320 will be overwritten. So the symbol V need not be already defined before
1321 any iterations of the FOR loop, but it must be a variable (Variables) if
1322 so. For example:
1323 FOR V, 4, 25, 5
1325 PRINT "{d:V} "
1326 DEF V *= 2
1327 ENDR
1328 PRINTLN "done {d:V}"
1329 This will print:
1331 4 9 14 19 24 done 29
1333 Just like with REPT blocks, you can use the escape sequence \@ inside of
1335 FOR blocks, and they can be nested.
1336 You can stop a repeating block with the BREAK command. A BREAK inside of
1338 a REPT or FOR block will interrupt the current iteration and not repeat
1339 any more. It will continue running code after the block's ENDR. For ex‐
1340 ample:
1341 FOR V, 1, 100
1343 PRINT "{d:V}"
1344 IF V == 5
1345 PRINT " stop! "
1346 BREAK
1347 ENDC
1348 PRINT ", "
1349 ENDR
1350 PRINTLN "done {d:V}"
1351 This will print:
1353 1, 2, 3, 4, 5 stop! done 5
1355 Aborting the assembly process
1357 FAIL and WARN can be used to print errors and warnings respectively dur‐
1358 ing the assembly process. This is especially useful for macros that get
1359 an invalid argument. FAIL and WARN take a string as the only argument
1360 and they will print this string out as a normal error with a line number.
1361 FAIL stops assembling immediately while WARN shows the message but con‐
1363 tinues afterwards.
1364 If you need to ensure some assumption is correct when compiling, you can
1366 use ASSERT and STATIC_ASSERT. Syntax examples are given below:
1367 Function:
1369 xor a
1370 ASSERT LOW(MyByte) == 0
1371 ld h, HIGH(MyByte)
1372 ld l, a
1373 ld a, [hli]
1374 ; You can also indent this!
1375 ASSERT BANK(OtherFunction) == BANK(Function)
1376 call OtherFunction
1377 ; Lowercase also works
1378 ld hl, FirstByte
1379 ld a, [hli]
1380 assert FirstByte + 1 == SecondByte
1381 ld b, [hl]
1382 ret
1383 .end
1384 ; If you specify one, a message will be printed
1385 STATIC_ASSERT .end - Function < 256, "Function is too large!"
1386 First, the difference between ASSERT and STATIC_ASSERT is that the former
1388 is evaluated by RGBASM if it can, otherwise by RGBLINK; but the latter is
1389 only ever evaluated by RGBASM. If RGBASM cannot compute the value of the
1390 argument to STATIC_ASSERT, it will produce an error.
1391 Second, as shown above, a string can be optionally added at the end, to
1393 give insight into what the assertion is checking.
1394 Finally, you can add one of WARN, FAIL or FATAL as the first optional ar‐
1396 gument to either ASSERT or STATIC_ASSERT. If the assertion fails, WARN
1397 will cause a simple warning (controlled by rgbasm(1) flag -Wassert) to be
1398 emitted; FAIL (the default) will cause a non-fatal error; and FATAL imme‐
1399 diately aborts.
1400 Including other source files
1402 Use INCLUDE to process another assembler file and then return to the cur‐
1403 rent file when done. If the file isn't found in the current directory,
1404 the include path list (see the -i option in rgbasm(1)) will be searched.
1405 You may nest INCLUDE calls infinitely (or until you run out of memory,
1406 whichever comes first).
1407 INCLUDE "irq.inc"
1409 You may also implicitly INCLUDE a file before the source file with the -P
1411 option of rgbasm(1).
1412 Conditional assembling
1414 The four commands IF, ELIF, ELSE, and ENDC let you have rgbasm skip over
1415 parts of your code depending on a condition. This is a powerful feature
1416 commonly used in macros.
1417 IF NUM < 0
1419 PRINTLN "NUM < 0"
1420 ELIF NUM == 0
1421 PRINTLN "NUM == 0"
1422 ELSE
1423 PRINTLN "NUM > 0"
1424 ENDC
1425 The ELIF (standing for "else if") and ELSE blocks are optional. IF /
1427 ELIF / ELSE / ENDC blocks can be nested.
1428 Note that if an ELSE block is found before an ELIF block, the ELIF block
1430 will be ignored. All ELIF blocks must go before the ELSE block. Also,
1431 if there is more than one ELSE block, all of them but the first one are
1432 ignored.
1433
1435 Changing options while assembling
1436 OPT can be used to change some of the options during assembling from
1437 within the source, instead of defining them on the command-line. (See
1438 rgbasm(1)).
1439 OPT takes a comma-separated list of options as its argument:
1441 PUSHO
1443 OPT g.oOX, Wdiv, L ; acts like command-line -g.oOX -Wdiv -L
1444 DW `..ooOOXX ; uses the graphics constant characters from OPT g
1445 PRINTLN $80000000/-1 ; prints a warning about division
1446 LD [$FF88], A ; encoded as LD, not LDH
1447 POPO
1448 DW `00112233 ; uses the default graphics constant characters
1449 PRINTLN $80000000/-1 ; no warning by default
1450 LD [$FF88], A ; optimized to use LDH by default
1451 The options that OPT can modify are currently: b, g, p, Q, r, h, L, and
1453 W. The Boolean flag options H, h, L, and l can be negated like ‘OPT !H’
1454 to act like omitting them from the command-line.
1455 POPO and PUSHO provide the interface to the option stack. PUSHO will
1457 push the current set of options on the option stack. POPO can then later
1458 be used to restore them. Useful if you want to change some options in an
1459 include file and you don't want to destroy the options set by the program
1460 that included your file. The stack's number of entries is limited only
1461 by the amount of memory in your machine.
1462 Requesting alignment
1464 While ALIGN as presented in SECTIONS is often useful as-is, sometimes you
1465 instead want a particular piece of data (or code) in the middle of the
1466 section to be aligned. This is made easier through the use of mid-sec‐
1467 tion ALIGN align, offset. It will alter the section's attributes to en‐
1468 sure that the location the ALIGN directive is at, has its align lower
1469 bits equal to offset.
1470 If the constraint cannot be met (for example because the section is fixed
1472 at an incompatible address), an error is produced. Note that ALIGN align
1473 is a shorthand for ALIGN align, 0.
1474
1476 rgbasm(1), rgblink(1), rgblink(5), rgbds(5), rgbds(7), gbz80(7)
1477
1479 rgbasm was originally written by Carsten Sørensen as part of the ASMotor
1480 package, and was later packaged in RGBDS by Justin Lloyd. It is now
1481 maintained by a number of contributors at https://github.com/gbdev/rgbds
1482BSD March 28, 2021 BSD