1RGBDS(5) BSD File Formats Manual RGBDS(5)
2
4 rgbds — object file format documentation
5
7 This is the description of the object files used by rgbasm(1) and
8 rgblink(1). Please note that the specification is not stable yet. RGBDS
9 is still in active development, and some new features require adding more
10 information to the object file, or modifying some fields, both of which
11 break compatibility with older versions.
12
14 The following types are used:
15 LONG is a 32-bit integer stored in little-endian format. BYTE is an
17 8-bit integer. STRING is a 0-terminated string of BYTE. Brackets after
18 a type (e.g. LONG[n]) indicate n consecutive elements (here, LONGs). All
19 items are contiguous, with no padding anywhere—this also means that they
20 may not be aligned in the file!
21 REPT n indicates that the fields between the REPT and corresponding ENDR
23 are repeated n times.
24 All IDs refer to objects within the file; for example, symbol ID $0001
26 refers to the second symbol defined in this object file's Symbols array.
27 The only exception is the Source file info nodes, whose IDs are back‐
28 wards, i.e. source node ID $0000 refers to the last node in the array,
29 not the first one. References to other object files are made by imports
30 (symbols), by name (sections), etc.—but never by ID.
31 Header
33 BYTE Magic[4]
34 "RGB9"
35 LONG RevisionNumber
36 The format's revision number this file uses. (This is always in
37 the same place in all revisions.)
38 LONG NumberOfSymbols
39 How many symbols are defined in this object file.
40 LONG NumberOfSections
41 How many sections are defined in this object file.
42 Source file info
44 LONG NumberOfNodes
45 The number of source context nodes contained in this file.
46 REPT NumberOfNodes
47 LONG ParentID
48 ID of the parent node, -1 meaning that this is the root
49 node.
50 Important: the nodes are actually written in reverse or‐
52 der, meaning the node with ID 0 is the last one in the
53 list!
54 LONG ParentLineNo
55 Line at which the parent node's context was exited; mean‐
56 ingless for the root node.
57 BYTE Type
58 Value Meaning
59 0 REPT node
60 1 File node
61 2 Macro node
62 IF Type ≠ 0
63 If the node is not a REPT node...
64 STRING Name
66 The node's name: either a file name, or the
67 macro's name prefixes by its definition's file
68 name (e.g. ‘src/includes/defines.asm::error’).
69 ELSE If the node is a REPT, it also contains the iteration
70 counter of all parent REPTs.
71 LONG Depth
73 LONG Iter[Depth]
74 The number of REPT iterations, by increasing
75 depth.
76 ENDC
77 ENDR
78 Symbols
80 REPT NumberOfSymbols
81 STRING Name
82 This symbol's name. Local symbols are stored as their
83 full name (‘Scope.symbol’).
84 BYTE Type
85 Value Meaning
86 0 Local symbol only used in this file.
87 1 Import of an exported symbol (by name) from
88 another object file.
89 2 Exported symbol visible from other object files.
90 IF Type ≠ 1
91 If the symbol is defined in this object file...
92 LONG NodeID
94 Context in which the symbol was defined.
95 LONG LineNo
96 Line number in the context at which the symbol
97 was defined.
98 LONG SectionID
99 The ID of the section in which the symbol is de‐
100 fined. If the symbol doesn't belong to any spe‐
101 cific section (i.e. it's a constant), this field
102 contains -1.
103 LONG Value
104 The symbol's value. If the symbol belongs to a
105 section, this is the offset within that symbol's
106 section.
107 ENDC
108 ENDR
109 Sections
111 REPT NumberOfSections
112 STRING Name
113 The section's name.
114 LONG Size
115 The section's size, in bytes.
116 BYTE Type
117 Bits 0–2 indicate the section's type:
118 Value Meaning
119 0 WRAM0
120 1 VRAM
121 2 ROMX
122 3 ROM0
123 4 HRAM
124 5 WRAMX
125 6 SRAM
126 7 OAM
127 Bit 7 being set means that the section is a "union" (see
129 “Unionized sections” in rgbasm(5)). Bit 6 being set
130 means that the section is a "fragment" (see “Section
131 fragments” in rgbasm(5)). These two bits are mutually
132 exclusive.
133 LONG Address
134 Address this section must be placed at. This must either
135 be valid for the section's Type (as affected by flags
136 like -t or -d in rgblink(1)), or -1 to indicate that the
137 linker should automatically decide (the section is
138 “floating”).
139 LONG Bank
140 ID of the bank this section must be placed in. This must
141 either be valid for the section's Type (with the same
142 caveats as for the Address), or -1 to indicate that the
143 linker should automatically decide.
144 BYTE Alignment
145 How many bits of the section's address should be equal to
146 AlignOfs, starting from the least-significant bit.
147 LONG AlignOfs
148 Alignment offset. Must be strictly less than ‘1 <<
149 Alignment’.
150 IF Type = 2 || Type = 3
151 If the section has ROM type, it contains data.
152 BYTE Data[Size]
154 The section's raw data. Bytes that will be
155 patched over must be present, even though their
156 contents will be overwritten.
157 LONG NumberOfPatches
158 How many patches must be applied to this sec‐
159 tion's Data.
160 REPT NumberOfPatches
161 LONG NodeID
162 Context in which the patch was defined.
163 LONG LineNo
164 Line number in the context at which the
165 patch was defined.
166 LONG Offset
167 Offset within the section's Data at which
168 the patch should be applied. Must not be
169 greater than the section's Size minus the
170 patch's size (see Type below).
171 LONG PCSectionID
172 ID of the section in which PC is located.
173 (This is usually the same section within
174 which the patch is applied, except for
175 e.g. ‘LOAD’ blocks, see “RAM code” in
176 rgbasm(5).)
177 LONG PCOffset
178 Offset of the PC symbol within the sec‐
179 tion designated by PCSectionID. It is
180 expected that PC points to the instruc‐
181 tion's first byte for instruction oper‐
182 ands (i.e. ‘jp @’ must be an infinite
183 loop), and to the patch's first byte oth‐
184 erwise (‘db’, ‘dw’, ‘dl’).
185 BYTE Type
186 Value Meaning
187 0 Single-byte patch
188 1 Little-endian two-byte patch
189 2 Little-endian four-byte patch
190 3 Single-byte ‘jr’ patch; the
191 patch's value will be subtracted
192 to PC + 2 (i.e. ‘jr @’ must be
193 the infinite loop ‘18 FE’).
194 LONG RPNSize
195 Size of the RPNExpr below.
196 BYTE RPNExpr[RPNSize]
197 The patch's value, encoded as a RPN ex‐
198 pression (see RPN EXPRESSIONS).
199 ENDR
200 ENDC
201 Assertions
203 LONG NumberOfAssertions
204 How many assertions this object file contains.
205 REPT NumberOfAssertions
206 Assertions are essentially patches with a message.
207 LONG NodeID
209 Context in which the assertions was defined.
210 LONG LineNo
211 Line number in the context at which the assertion was de‐
212 fined.
213 LONG Offset
214 Unused leftover from the patch structure.
215 LONG PCSectionID
216 ID of the section in which PC is located.
217 LONG PCOffset
218 Offset of the PC symbol within the section designated by
219 PCSectionID.
220 BYTE Type
221 Describes what should happen if the expression evaluates
222 to a non-zero value.
223 Value Meaning
224 0 Print a warning message, and continue linking
225 normally.
226 1 Print an error message, so linking will fail,
227 but allow other assertions to be evaluated.
228 2 Print a fatal error message, and abort
229 immediately.
230 LONG RPNSize
231 Size of the RPNExpr below.
232 BYTE RPNExpr[RPNSize]
233 The patch's value, encoded as a RPN expression (see RPN
234 EXPRESSIONS).
235 STRING Message
236 The message displayed if the expression evaluates to a
237 non-zero value. If empty, a generic message is displayed
238 instead.
239 ENDR
240 RPN EXPRESSIONS
242 Expressions in the object file are stored as RPN, or “Reverse Polish
243 Notation”, which is a notation that allows computing arbitrary expres‐
244 sions with just a simple stack. For example, the expression ‘2 5 -’ will
245 first push the value “2” to the stack, then “5”. The ‘-’ operator pops
246 two arguments from the stack, subtracts them, and then pushes back the
247 result (“3”) on the stack. A well-formed RPN expression never tries to
248 pop from an empty stack, and leaves exactly one value in it at the end.
249 RGBDS encodes RPN expressions as an array of BYTEs. The first byte en‐
251 codes either an operator, or a literal, which consumes more BYTEs after
252 it.
253 Value Meaning
255 $00 Addition operator (‘+’)
256 $01 Subtraction operator (‘-’)
257 $02 Multiplication operator (‘*’)
258 $03 Division operator (‘/’)
259 $04 Modulo operator (‘%’)
260 $05 Negation (unary ‘-’)
261 $06 Exponent operator (‘**’)
262 $10 Bitwise OR operator (‘|’)
263 $11 Bitwise AND operator (‘&’)
264 $12 Bitwise XOR operator (‘^’)
265 $13 Bitwise complement operator (unary ‘~’)
266 $21 Logical AND operator (‘&&’)
267 $22 Logical OR operator (‘||’)
268 $23 Logical complement operator (unary ‘!’)
269 $30 Equality operator (‘==’)
270 $31 Non-equality operator (‘!=’)
271 $32 Greater-than operator (‘>’)
272 $33 Less-than operator (‘<’)
273 $34 Greater-than-or-equal operator (‘>=’)
274 $35 Less-than-or-equal operator (‘<=’)
275 $40 Left shift operator (‘<<’)
276 $41 Arithmetic/signed right shift operator (‘>>’)
277 $42 Logical/unsigned right shift operator (‘>>>’)
278 $50 BANK(symbol), followed by the symbol's LONG ID.
279 $51 BANK(section), followed by the section's STRING name.
280 $52 PC's BANK() (i.e. ‘BANK(@)’).
281 $53 SIZEOF(section), followed by the section's STRING name.
282 $54 STARTOF(section), followed by the section's STRING name.
283 $60 ‘ldh’ check. Checks if the value is a valid ‘ldh’ operand
284 (see “Load Instructions” in gbz80(7)), i.e. that it is be‐
285 tween either $00 and $FF, or $FF00 and $FFFF, both inclu‐
286 sive. The value is then ANDed with $00FF (‘& $FF’).
287 $61 ‘rst’ check. Checks if the value is a valid ‘rst’ (see
288 “RST vec” in gbz80(7)) vector, that is one of $00, $08,
289 $10, $18, $20, $28, $30, or $38. The value is then ORed
290 with $C7 (‘| $C7’).
291 $80 Integer literal. Followed by the LONG integer.
292 $81 A symbol's value. Followed by the symbol's LONG ID.
293
295 rgbasm(1), rgblink(1), rgbds(7), gbz80(7)
296
298 rgbds was originally written by Carsten Sørensen as part of the ASMotor
299 package, and was later packaged in RGBDS by Justin Lloyd. It is now
300 maintained by a number of contributors at https://github.com/gbdev/rgbds
301BSD March 28, 2021 BSD