mirror of
https://github.com/gbdev/rgbds.git
synced 2025-11-20 18:22:07 +00:00
276 lines
9.2 KiB
Groff
276 lines
9.2 KiB
Groff
.\"
|
|
.\" This file is part of RGBDS.
|
|
.\"
|
|
.\" Copyright (c) 2017-2021, Antonio Nino Diaz and RGBDS contributors.
|
|
.\"
|
|
.\" SPDX-License-Identifier: MIT
|
|
.\"
|
|
.Dd March 28, 2021
|
|
.Dt RGBDS 5
|
|
.Os
|
|
.Sh NAME
|
|
.Nm rgbds
|
|
.Nd object file format documentation
|
|
.Sh DESCRIPTION
|
|
This is the description of the object files used by
|
|
.Xr rgbasm 1
|
|
and
|
|
.Xr rgblink 1 .
|
|
.Em Please note that the specifications may change .
|
|
This toolchain is in development and new features may require adding more information to the current format, or modifying some fields, which would break compatibility with older versions.
|
|
.Sh FILE STRUCTURE
|
|
The following types are used:
|
|
.Pp
|
|
.Ar LONG
|
|
is a 32-bit integer stored in little-endian format.
|
|
.Ar BYTE
|
|
is an 8-bit integer.
|
|
.Ar STRING
|
|
is a 0-terminated string of
|
|
.Ar BYTE .
|
|
.Bd -literal
|
|
; Header
|
|
|
|
BYTE ID[4] ; "RGB9"
|
|
LONG RevisionNumber ; The format's revision number this file uses.
|
|
LONG NumberOfSymbols ; The number of symbols used in this file.
|
|
LONG NumberOfSections ; The number of sections used in this file.
|
|
|
|
; File info
|
|
|
|
LONG NumberOfNodes ; The number of nodes contained in this file.
|
|
|
|
REPT NumberOfNodes ; IMPORTANT NOTE: the nodes are actually written in
|
|
; **reverse** order, meaning the node with ID 0 is
|
|
; the last one in the file!
|
|
|
|
LONG ParentID ; ID of the parent node, -1 means this is the root.
|
|
|
|
LONG ParentLineNo ; Line at which the parent context was exited.
|
|
; Meaningless on the root node.
|
|
|
|
BYTE Type ; 0 = REPT node
|
|
; 1 = File node
|
|
; 2 = Macro node
|
|
|
|
IF Type != 0 ; If the node is not a REPT...
|
|
|
|
STRING Name ; The node's name: either a file name, or macro name
|
|
; prefixed by its definition file name.
|
|
|
|
ELSE ; If the node is a REPT, it also contains the iter
|
|
; counts of all the parent REPTs.
|
|
|
|
LONG Depth ; Size of the array below.
|
|
|
|
LONG Iter[Depth] ; The number of REPT iterations by increasing depth.
|
|
|
|
ENDC
|
|
|
|
ENDR
|
|
|
|
; Symbols
|
|
|
|
REPT NumberOfSymbols ; Number of symbols defined in this object file.
|
|
|
|
STRING Name ; The name of this symbol. Local symbols are stored
|
|
; as "Scope.Symbol".
|
|
|
|
BYTE Type ; 0 = LOCAL symbol only used in this file.
|
|
; 1 = IMPORT this symbol from elsewhere
|
|
; 2 = EXPORT this symbol to other objects.
|
|
|
|
IF (Type & 0x7F) != 1 ; If symbol is defined in this object file.
|
|
|
|
LONG SourceFile ; File where the symbol is defined.
|
|
|
|
LONG LineNum ; Line number in the file where the symbol is defined.
|
|
|
|
LONG SectionID ; The section number (of this object file) in which
|
|
; this symbol is defined. If it doesn't belong to any
|
|
; specific section (like a constant), this field has
|
|
; the value -1.
|
|
|
|
LONG Value ; The symbols value. It's the offset into that
|
|
; symbol's section.
|
|
|
|
ENDC
|
|
|
|
ENDR
|
|
|
|
; Sections
|
|
|
|
REPT NumberOfSections
|
|
STRING Name ; Name of the section
|
|
|
|
LONG Size ; Size in bytes of this section
|
|
|
|
BYTE Type ; 0 = WRAM0
|
|
; 1 = VRAM
|
|
; 2 = ROMX
|
|
; 3 = ROM0
|
|
; 4 = HRAM
|
|
; 5 = WRAMX
|
|
; 6 = SRAM
|
|
; 7 = OAM
|
|
; Bits 7 and 6 are independent from the above value:
|
|
; Bit 7 encodes whether the section is unionized
|
|
; Bit 6 encodes whether the section is a fragment
|
|
; Bits 6 and 7 may not be both set at the same time!
|
|
|
|
LONG Org ; Address to fix this section at. -1 if the linker should
|
|
; decide (floating address).
|
|
|
|
LONG Bank ; Bank to load this section into. -1 if the linker should
|
|
; decide (floating bank). This field is only valid for ROMX,
|
|
; VRAM, WRAMX and SRAM sections.
|
|
|
|
BYTE Align ; Alignment of this section, as N bits. 0 when not specified.
|
|
|
|
LONG Ofs ; Offset relative to the alignment specified above.
|
|
; Must be below 1 << Align.
|
|
|
|
IF (Type == ROMX) || (Type == ROM0) ; Sections that can contain data.
|
|
|
|
BYTE Data[Size] ; Raw data of the section.
|
|
|
|
LONG NumberOfPatches ; Number of patches to apply.
|
|
|
|
REPT NumberOfPatches
|
|
|
|
LONG SourceFile ; ID of the source file node (for printing
|
|
; error messages).
|
|
|
|
LONG LineNo ; Line at which the patch was created.
|
|
|
|
LONG Offset ; Offset into the section where patch should
|
|
; be applied (in bytes).
|
|
|
|
LONG PCSectionID ; Index within the file of the section in which
|
|
; PC is located.
|
|
; This is usually the same section that the
|
|
; patch should be applied into, except e.g.
|
|
; with LOAD blocks.
|
|
|
|
LONG PCOffset ; PC's offset into the above section.
|
|
; Used because the section may be floating, so
|
|
; PC's value is not known to RGBASM.
|
|
|
|
BYTE Type ; 0 = BYTE patch.
|
|
; 1 = little endian WORD patch.
|
|
; 2 = little endian LONG patch.
|
|
; 3 = JR offset value BYTE patch.
|
|
|
|
LONG RPNSize ; Size of the buffer with the RPN.
|
|
; expression.
|
|
|
|
BYTE RPN[RPNSize] ; RPN expression. Definition below.
|
|
|
|
ENDR
|
|
|
|
ENDC
|
|
|
|
ENDR
|
|
|
|
; Assertions
|
|
|
|
LONG NumberOfAssertions
|
|
|
|
REPT NumberOfAssertions
|
|
|
|
LONG SourceFile ; ID of the source file node (for printing the failure).
|
|
|
|
LONG LineNo ; Line at which the assertion was created.
|
|
|
|
LONG Offset ; Offset into the section where the assertion is located.
|
|
|
|
LONG SectionID ; Index within the file of the section in which PC is
|
|
; located, or -1 if defined outside a section.
|
|
|
|
LONG PCOffset ; PC's offset into the above section.
|
|
; Used because the section may be floating, so PC's value
|
|
; is not known to RGBASM.
|
|
|
|
BYTE Type ; 0 = Prints the message but allows linking to continue
|
|
; 1 = Prints the message and evaluates other assertions,
|
|
; but linking fails afterwards
|
|
; 2 = Prints the message and immediately fails linking
|
|
|
|
LONG RPNSize ; Size of the RPN expression's buffer.
|
|
|
|
BYTE RPN[RPNSize] ; RPN expression, same as patches. Assert fails if == 0.
|
|
|
|
STRING Message ; A message displayed when the assert fails. If set to
|
|
; the empty string, a generic message is printed instead.
|
|
|
|
ENDR
|
|
.Ed
|
|
.Ss RPN DATA
|
|
Expressions in the object file are stored as RPN.
|
|
This is an expression of the form
|
|
.Dq 2 5 + .
|
|
This will first push the value
|
|
.Do 2 Dc to the stack, then
|
|
.Dq 5 .
|
|
The
|
|
.Do + Dc operator pops two arguments from the stack, adds them, and then pushes the result on the stack, effectively replacing the two top arguments with their sum.
|
|
In the RGB format, RPN expressions are stored as
|
|
.Ar BYTE Ns s
|
|
with some bytes being special prefixes for integers and symbols.
|
|
.Bl -column -offset indent "Sy String" "Sy String"
|
|
.It Sy Value Ta Sy Meaning
|
|
.It Li $00 Ta Li + operator
|
|
.It Li $01 Ta Li - operator
|
|
.It Li $02 Ta Li * operator
|
|
.It Li $03 Ta Li / operator
|
|
.It Li $04 Ta Li % operator
|
|
.It Li $05 Ta Li unary -
|
|
.It Li $06 Ta Li ** operator
|
|
.It Li $10 Ta Li \&| operator
|
|
.It Li $11 Ta Li & operator
|
|
.It Li $12 Ta Li ^ operator
|
|
.It Li $13 Ta Li unary ~
|
|
.It Li $21 Ta Li && comparison
|
|
.It Li $22 Ta Li || comparison
|
|
.It Li $23 Ta Li unary \&!
|
|
.It Li $30 Ta Li == comparison
|
|
.It Li $31 Ta Li != comparison
|
|
.It Li $32 Ta Li > comparison
|
|
.It Li $33 Ta Li < comparison
|
|
.It Li $34 Ta Li >= comparison
|
|
.It Li $35 Ta Li <= comparison
|
|
.It Li $40 Ta Li << operator
|
|
.It Li $41 Ta Li >> operator
|
|
.It Li $42 Ta Li >>> operator
|
|
.It Li $50 Ta Li BANK(symbol) ,
|
|
a
|
|
.Ar LONG
|
|
Symbol ID follows, where -1 means PC
|
|
.It Li $51 Ta Li BANK(section_name) ,
|
|
a null-terminated string follows.
|
|
.It Li $52 Ta Li Current BANK()
|
|
.It Li $53 Ta Li SIZEOF(section_name) ,
|
|
a null-terminated string follows.
|
|
.It Li $54 Ta Li STARTOF(section_name) ,
|
|
a null-terminated string follows.
|
|
.It Li $60 Ta Li HRAMCheck .
|
|
Checks if the value is in HRAM, ANDs it with 0xFF.
|
|
.It Li $61 Ta Li RSTCheck .
|
|
Checks if the value is a RST vector, ORs it with 0xC7.
|
|
.It Li $80 Ta Ar LONG
|
|
integer follows.
|
|
.It Li $81 Ta Ar LONG
|
|
symbol ID follows.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr rgbasm 1 ,
|
|
.Xr rgblink 1 ,
|
|
.Xr rgbds 7 ,
|
|
.Xr gbz80 7
|
|
.Sh HISTORY
|
|
.Nm
|
|
was originally written by Carsten S\(/orensen as part of the ASMotor package,
|
|
and was later packaged in RGBDS by Justin Lloyd.
|
|
It is now maintained by a number of contributors at
|
|
.Lk https://github.com/gbdev/rgbds .
|