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