1RGBDS(5)                    BSD File Formats Manual                   RGBDS(5)
2

NAME

4     rgbds — object file format documentation
5

DESCRIPTION

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

FILE STRUCTURE

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

SEE ALSO

243     rgbasm(1), rgblink(1), rgbds(7), gbz80(7)
244

HISTORY

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
Impressum