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 specifications may change. This
9 toolchain is in development and new features may require adding more in‐
10 formation to the current format, or modifying some fields, which would
11 break compatibility with older versions.
12
14 The following types are used:
15
16 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.
18
19 ; Header
20
21 BYTE ID[4] ; "RGB9"
22 LONG RevisionNumber ; The format's revision number this file uses.
23 LONG NumberOfSymbols ; The number of symbols used in this file.
24 LONG NumberOfSections ; The number of sections used in this file.
25
26 ; File info
27
28 LONG NumberOfNodes ; The number of nodes contained in this file.
29
30 REPT NumberOfNodes ; IMPORTANT NOTE: the nodes are actually written in
31 ; **reverse** order, meaning the node with ID 0 is
32 ; the last one in the file!
33
34 LONG ParentID ; ID of the parent node, -1 means this is the root.
35
36 LONG ParentLineNo ; Line at which the parent context was exited.
37 ; Meaningless on the root node.
38
39 BYTE Type ; 0 = REPT node
40 ; 1 = File node
41 ; 2 = Macro node
42
43 IF Type != 0 ; If the node is not a REPT...
44
45 STRING Name ; The node's name: either a file name, or macro name
46 ; prefixed by its definition file name.
47
48 ELSE ; If the node is a REPT, it also contains the iter
49 ; counts of all the parent REPTs.
50
51 LONG Depth ; Size of the array below.
52
53 LONG Iter[Depth] ; The number of REPT iterations by increasing depth.
54
55 ENDC
56
57 ENDR
58
59 ; Symbols
60
61 REPT NumberOfSymbols ; Number of symbols defined in this object file.
62
63 STRING Name ; The name of this symbol. Local symbols are stored
64 ; as "Scope.Symbol".
65
66 BYTE Type ; 0 = LOCAL symbol only used in this file.
67 ; 1 = IMPORT this symbol from elsewhere
68 ; 2 = EXPORT this symbol to other objects.
69
70 IF (Type & 0x7F) != 1 ; If symbol is defined in this object file.
71
72 LONG SourceFile ; File where the symbol is defined.
73
74 LONG LineNum ; Line number in the file where the symbol is defined.
75
76 LONG SectionID ; The section number (of this object file) in which
77 ; this symbol is defined. If it doesn't belong to any
78 ; specific section (like a constant), this field has
79 ; the value -1.
80
81 LONG Value ; The symbols value. It's the offset into that
82 ; symbol's section.
83
84 ENDC
85
86 ENDR
87
88 ; Sections
89
90 REPT NumberOfSections
91 STRING Name ; Name of the section
92
93 LONG Size ; Size in bytes of this section
94
95 BYTE Type ; 0 = WRAM0
96 ; 1 = VRAM
97 ; 2 = ROMX
98 ; 3 = ROM0
99 ; 4 = HRAM
100 ; 5 = WRAMX
101 ; 6 = SRAM
102 ; 7 = OAM
103 ; Bits 7 and 6 are independent from the above value:
104 ; Bit 7 encodes whether the section is unionized
105 ; Bit 6 encodes whether the section is a fragment
106 ; Bits 6 and 7 may not be both set at the same time!
107
108 LONG Org ; Address to fix this section at. -1 if the linker should
109 ; decide (floating address).
110
111 LONG Bank ; Bank to load this section into. -1 if the linker should
112 ; decide (floating bank). This field is only valid for ROMX,
113 ; VRAM, WRAMX and SRAM sections.
114
115 BYTE Align ; Alignment of this section, as N bits. 0 when not specified.
116
117 LONG Ofs ; Offset relative to the alignment specified above.
118 ; Must be below 1 << Align.
119
120 IF (Type == ROMX) || (Type == ROM0) ; Sections that can contain data.
121
122 BYTE Data[Size] ; Raw data of the section.
123
124 LONG NumberOfPatches ; Number of patches to apply.
125
126 REPT NumberOfPatches
127
128 LONG SourceFile ; ID of the source file node (for printing
129 ; error messages).
130
131 LONG LineNo ; Line at which the patch was created.
132
133 LONG Offset ; Offset into the section where patch should
134 ; be applied (in bytes).
135
136 LONG PCSectionID ; Index within the file of the section in which
137 ; PC is located.
138 ; This is usually the same section that the
139 ; patch should be applied into, except e.g.
140 ; with LOAD blocks.
141
142 LONG PCOffset ; PC's offset into the above section.
143 ; Used because the section may be floating, so
144 ; PC's value is not known to RGBASM.
145
146 BYTE Type ; 0 = BYTE patch.
147 ; 1 = little endian WORD patch.
148 ; 2 = little endian LONG patch.
149 ; 3 = JR offset value BYTE patch.
150
151 LONG RPNSize ; Size of the buffer with the RPN.
152 ; expression.
153
154 BYTE RPN[RPNSize] ; RPN expression. Definition below.
155
156 ENDR
157
158 ENDC
159
160 ENDR
161
162 ; Assertions
163
164 LONG NumberOfAssertions
165
166 REPT NumberOfAssertions
167
168 LONG SourceFile ; ID of the source file node (for printing the failure).
169
170 LONG LineNo ; Line at which the assertion was created.
171
172 LONG Offset ; Offset into the section where the assertion is located.
173
174 LONG SectionID ; Index within the file of the section in which PC is
175 ; located, or -1 if defined outside a section.
176
177 LONG PCOffset ; PC's offset into the above section.
178 ; Used because the section may be floating, so PC's value
179 ; is not known to RGBASM.
180
181 BYTE Type ; 0 = Prints the message but allows linking to continue
182 ; 1 = Prints the message and evaluates other assertions,
183 ; but linking fails afterwards
184 ; 2 = Prints the message and immediately fails linking
185
186 LONG RPNSize ; Size of the RPN expression's buffer.
187
188 BYTE RPN[RPNSize] ; RPN expression, same as patches. Assert fails if == 0.
189
190 STRING Message ; A message displayed when the assert fails. If set to
191 ; the empty string, a generic message is printed instead.
192
193 ENDR
194
195 RPN DATA
196 Expressions in the object file are stored as RPN. This is an expression
197 of the form “2 5 +”. This will first push the value “2” to the stack,
198 then “5”. The “+” operator pops two arguments from the stack, adds them,
199 and then pushes the result on the stack, effectively replacing the two
200 top arguments with their sum. In the RGB format, RPN expressions are
201 stored as BYTEs with some bytes being special prefixes for integers and
202 symbols.
203
204 Value Meaning
205 $00 + operator
206 $01 - operator
207 $02 * operator
208 $03 / operator
209 $04 % operator
210 $05 unary -
211 $06 ** operator
212 $10 | operator
213 $11 & operator
214 $12 ^ operator
215 $13 unary ~
216 $21 && comparison
217 $22 || comparison
218 $23 unary !
219 $30 == comparison
220 $31 != comparison
221 $32 > comparison
222 $33 < comparison
223 $34 >= comparison
224 $35 <= comparison
225 $40 << operator
226 $41 >> operator
227 $50 BANK(symbol), a LONG Symbol ID follows, where -1 means
228 PC
229 $51 BANK(section_name), a null-terminated string follows.
230 $52 Current BANK()
231 $53 SIZEOF(section_name), a null-terminated string fol‐
232 lows.
233 $54 STARTOF(section_name), a null-terminated string fol‐
234 lows.
235 $60 HRAMCheck. Checks if the value is in HRAM, ANDs it
236 with 0xFF.
237 $61 RSTCheck. Checks if the value is a RST vector, ORs it
238 with 0xC7.
239 $80 LONG integer follows.
240 $81 LONG symbol ID follows.
241
243 rgbasm(1), rgblink(1), rgbds(7), gbz80(7)
244
246 rgbds was originally written by Carsten Sørensen as part of the ASMotor
247 package, and was later packaged in RGBDS by Justin Lloyd. It is now
248 maintained by a number of contributors at https://github.com/gbdev/rgbds
249
250BSD March 28, 2021 BSD