mirror of
https://github.com/gbdev/rgbds.git
synced 2025-11-20 18:22:07 +00:00
195 lines
5.6 KiB
Groff
195 lines
5.6 KiB
Groff
.\"
|
||
.\" This file is part of RGBDS.
|
||
.\"
|
||
.\" Copyright (c) 2017-2018, Antonio Nino Diaz and RGBDS contributors.
|
||
.\"
|
||
.\" SPDX-License-Identifier: MIT
|
||
.\"
|
||
.Dd January 26, 2018
|
||
.Dt RGBDS 5
|
||
.Os RGBDS Manual
|
||
.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 .
|
||
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.
|
||
.Pp
|
||
.Sh FILE STRUCTURE
|
||
The following types are used:
|
||
.Pp
|
||
.Ar LONG
|
||
is a 32‐bit integer stored in little‐endian format (Intel).
|
||
.Ar BYTE
|
||
is an 8‐bit integer.
|
||
.Ar STRING
|
||
is a 0‐terminated string of
|
||
.Ar BYTE .
|
||
.Pp
|
||
.Bd -literal
|
||
; Header
|
||
|
||
BYTE ID[4] ; "RGB6"
|
||
LONG NumberOfSymbols ; The number of symbols used in this file
|
||
LONG NumberOfSections ; The number of sections used in this file
|
||
|
||
; 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 (unused).
|
||
; 2 = EXPORT this symbol to other objects.
|
||
|
||
IF Type != 1 ; If symbol is defined in this object file.
|
||
|
||
STRING FileName ; 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
|
||
|
||
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.
|
||
|
||
LONG Align ; Alignment of this section (expressed as number of low bits
|
||
; to leave as 0). -1 if not defined.
|
||
|
||
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.
|
||
|
||
; These types of sections may have patches
|
||
|
||
REPT NumberOfPatches
|
||
|
||
STRING SourceFile ; Name of the source file (for printing error
|
||
; messages).
|
||
|
||
LONG Line ; The line of the source file.
|
||
|
||
LONG Offset ; Offset into the section where patch should
|
||
; be applied (in bytes).
|
||
|
||
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
|
||
.Ed
|
||
.Ss RPN DATA
|
||
Expressions in the object file are stored as RPN.
|
||
This is an expression of the form
|
||
.Do 2 5 + Dc .
|
||
This will first push the value
|
||
.Do 2 Dc to the stack.
|
||
Then
|
||
.Do 5 Dc .
|
||
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 BYTEs with some bytes being
|
||
special prefixes for integers and symbols.
|
||
.Pp
|
||
.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 $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 << comparison
|
||
.It Li $41 Ta Li >> comparison
|
||
.It Li $50 Ta Li BANK(symbol),
|
||
a
|
||
.Ar LONG
|
||
Symbol ID follows.
|
||
.It Li $51 Ta Li BANK(section_name),
|
||
a null-terminated string follows.
|
||
.It Li $52 Ta Li Current BANK() .
|
||
.It Li $60 Ta Li HRAMCheck.
|
||
Check if the value is in HRAM, AND it with 0xFF.
|
||
.It Li $80 Ta Ar LONG
|
||
integer follows.
|
||
.It Li $81 Ta Ar LONG
|
||
Symbol ID follows.
|
||
.El
|
||
.Pp
|
||
.Sh SEE ALSO
|
||
.Xr rgbasm 1 ,
|
||
.Xr rgblink 1 ,
|
||
.Xr rgbds 7 ,
|
||
.Xr gbz80 7
|
||
.Sh HISTORY
|
||
.Nm rgbds
|
||
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/rednex/rgbds .
|