RGBDS(5)

📦
version 1.0.4 · 4 versions
, in arch rolling, nixpkgs unstable

✨ NAME ✨

rgbds — object file format documentation 💅

This is RGBDS(5), aka the File Formats Manual entry for the RGB object file format. Buckle up, bestie — we're going binary-structure deep. 🫶

💖 DESCRIPTION 💖

This is the description of the RGB object file format that rgbasm(1) outputs and rgblink(1) reads. It's literally the handoff between assembler and linker — main character energy, no cap. ✨

🦋 FILE STRUCTURE 🦋

Okay so these are the types you're gonna see:

  • LONG — a 32-bit integer stored in little-endian format. 🧠
  • BYTE — an 8-bit integer.
  • STRING — a 0-terminated string of BYTE.
  • Brackets after a type, like LONG[n], mean n consecutive elements — here, LONGs. 🌀

All items are contiguous, with no padding anywhere — and yes, that also means they may not be aligned in the file! 😭 No cozy alignment naps. Everything is packed.

REPT n means the fields between the REPT and the corresponding ENDR are repeated n times. 🔁

All IDs refer to objects within the file. For example, symbol ID $0001 refers to the second symbol defined in this object file's “Symbols” array. The only exception is the “Source file info” nodes, whose IDs are backwards — i.e. source node ID $0000 refers to the last node in the array, not the first one. 🫠 References to other object files are made by imports (symbols), by name (sections), etc. — but never by ID. Periodt.

This is the opening act, and it's short:

  • BYTE Magic[4] — the magic bytes are literally "RGB9" 🔮.
  • LONG RevisionNumber — the format's revision number this file uses. This is always in the same place in all revisions. Stable placement, we love to see it.
  • LONG NumberOfSymbols — how many symbols are defined in this object file.
  • LONG NumberOfSections — how many sections are defined in this object file.

🌸 Source file info 🌸

  • LONG NumberOfNodes — the number of source context nodes contained in this file.

Then it's a REPT NumberOfNodes situation, and each node has all this:

  • LONG ParentID — ID of the parent node, with -1 meaning that this is the root node.
⚠️ Important: the nodes are actually written in reverse order, meaning the node with ID 0 is the last one in the list! Don't get got by this, bestie. 😭
  • LONG ParentLineNo — line at which the parent node's context was exited; meaningless for the root node.
  • BYTE Type — bits 0–6 indicate the node's type:
    • 0 — REPT node 🌀
    • 1 — File node 📄
    • 2 — Macro node 🧩

Bit 7 being set means that the node is “quieted” (see “Excluding locations from backtraces” in rgbasm(5)). 🤫

  • IF Type ≠ 0 — if the node is not a REPT node...
    • STRING Name — the node's name: either a file name, or the macro's name prefixed by its definition's file name (e.g. src/includes/defines.asm::error). 📛
  • ELSE — if the node is a REPT, it also contains the iteration counter of all parent REPTs:
    • LONG Depth
    • LONG Iter[Depth] — the number of REPT iterations, by increasing depth. 📈
  • ENDC — closes that conditional.
  • ENDR — closes the whole repeated node block.

💅 Symbols 💅

REPT NumberOfSymbols — each symbol entry starts with:

  • STRING Name — this symbol's name. Local symbols are stored as their full name (Scope.symbol). 📛
  • BYTE Type — one of:
    • 0 — Local symbol only used in this file. 🏠
    • 1 — Import of an exported symbol (by name) from another object file. 📥
    • 2 — Exported symbol visible from other object files. 📤
  • IF Type ≠ 1 — if the symbol is defined in this object file...
    • LONG NodeID — context in which the symbol was defined.
    • LONG LineNo — line number in the context at which the symbol was defined.
    • LONG SectionID — the ID of the section in which the symbol is defined. If the symbol doesn't belong to any specific section (i.e. it's a constant), this field contains -1.
    • LONG Value — the symbol's value. If the symbol belongs to a section, this is the offset within that symbol's section.
  • ENDC — closes the IF Type ≠ 1 conditional.
  • ENDR — closes the symbol repeat.

👑 Sections 👑

REPT NumberOfSections — each section has:

  • STRING Name — the section's name.
  • LONG NodeID — context in which the section was defined.
  • LONG LineNo — line number in the context at which the section was defined.
  • LONG Size — the section's size, in bytes.
  • BYTE Type — bits 0–2 indicate the section's type:
    • 0 — WRAM0
    • 1 — VRAM
    • 2 — ROMX
    • 3 — ROM0
    • 4 — HRAM
    • 5 — WRAMX
    • 6 — SRAM
    • 7 — OAM

Bit 7 being set means that the section is a “union” (see “Unionized sections” in rgbasm(5)). Bit 6 being set means that the section is a “fragment” (see “Section fragments” in rgbasm(5)). These two bits are mutually exclusive. ⚔️

  • LONG Address — address this section must be placed at. This must either be valid for the section's Type (as affected by flags like -t or -d in rgblink(1)), or -1 to indicate that the linker should automatically decide — the section is “floating”. 🎈
  • LONG Bank — ID of the bank this section must be placed in. This must either be valid for the section's Type (with the same caveats as for the Address), or -1 to indicate that the linker should automatically decide.
  • BYTE Alignment — how many bits of the section's address should be equal to AlignOfs, starting from the least-significant bit.
  • LONG AlignOfs — alignment offset. Must be strictly less than 1 << Alignment. 📏
  • IF Type = 2 || Type = 3 — if the section has ROM type, it contains data:
    • BYTE Data[Size] — the section's raw data. Bytes that will be patched over must be present, even though their contents will be overwritten. 🧱
    • LONG NumberOfPatches — how many patches must be applied to this section's Data.

Then REPT NumberOfPatches — each patch is:

  • LONG NodeID — context in which the patch was defined.
  • LONG LineNo — line number in the context at which the patch was defined.
  • LONG Offset — offset within the section's Data at which the patch should be applied. Must not be greater than the section's Size minus the patch's size (see Type below).
  • LONG PCSectionID — ID of the section in which PC is located. This is usually the same section within which the patch is applied, except for e.g. LOAD blocks, see “RAM code” in rgbasm(5).
  • LONG PCOffset — offset of the PC symbol within the section designated by PCSectionID. It is expected that PC points to the instruction's first byte for instruction operands (i.e. jp @ must be an infinite loop), and to the patch's first byte otherwise (db, dw, dl). 🎯
  • BYTE Type — one of:
    • 0 — Single-byte patch
    • 1 — Little-endian two-byte patch
    • 2 — Little-endian four-byte patch
    • 3 — Single-byte jr patch; the patch's value will be subtracted to PC + 2 (i.e. jr @ must be the infinite loop 18 FE). 🕹️
  • LONG RPNSize — size of the RPNExpr below.
  • BYTE RPNExpr[RPNSize] — the patch's value, encoded as a RPN expression (see “RPN expressions”).

Then ENDR closes the patch repeat, and ENDC closes the ROM-data conditional.

⭐ Assertions ⭐

  • LONG NumberOfAssertions — how many assertions this object file contains.
  • REPT NumberOfAssertions — and then the assertion entries begin.

Assertions are essentially patches with a message. 💬

  • LONG NodeID — the context where this assertion got defined. iykyk, it's just the node it lives in 🫶
  • LONG LineNo — which line in that context the assertion was defined on. receipts! 📍
  • LONG Offset — literally unused, leftover from the patch structure. it's giving vestigial, don't worry about it 💀
  • LONG PCSectionID — the ID of the section that PC is chillin' in.
  • LONG PCOffset — where the PC symbol sits inside the section named by PCSectionID. that's its spot, periodt.
  • BYTE Type — tells you what should happen when the expression evaluates to a non-zero value. the options are:
    • 0 — print a warning message, and continue linking normally. soft launch vibes ✨
    • 1 — print an error message so linking will fail, but still let the other assertions get evaluated. it's not over till it's over 😭
    • 2 — print a fatal error message and abort immediately. no thoughts, no other assertions, just done 💅
  • LONG RPNSize — how big the RPNExpr below is.
  • BYTE RPNExpr[RPNSize] — the patch's value, encoded as an RPN expression (peep "RPN expressions"). this is the main character of the struct ngl 👑
  • STRING Message — the message that gets displayed if the expression evaluates to a non-zero value. if it's empty, a generic message shows up instead. no custom text? no problem.
  • ENDR

✨ RPN expressions ✨

okay bestie so expressions in the object file are stored as RPN — that's "Reverse Polish Notation" — and it's this gorge notation that lets you compute literally arbitrary expressions with just a simple stack. 🥞

example time, because the way this works is actually iconic: the expression 2 5 - first pushes the value "2" onto the stack, then "5". then the - operator pops two arguments off the stack, subtracts them, and pushes the result ("3") right back on. slay. a well-formed RPN expression never tries to pop from an empty stack, and leaves exactly one value in it at the end. that's the vibe check for correctness fr fr.

RGBDS encodes RPN expressions as an array of BYTEs. the first byte encodes either an operator, or a literal — and literals gobble up more BYTEs after them:

  • $00 — Addition operator (+)
  • $01 — Subtraction operator (-)
  • $02 — Multiplication operator (*)
  • $03 — Division operator (/)
  • $04 — Modulo operator (%)
  • $05 — Negation (unary -)
  • $06 — Exponent operator (**)
  • $10 — Bitwise OR operator (|)
  • $11 — Bitwise AND operator (&)
  • $12 — Bitwise XOR operator (^)
  • $13 — Bitwise complement operator (unary ~)
  • $21 — Logical AND operator (&&)
  • $22 — Logical OR operator (||)
  • $23 — Logical complement operator (unary !)
  • $30 — Equality operator (==)
  • $31 — Non-equality operator (!=)
  • $32 — Greater-than operator (>)
  • $33 — Less-than operator (<)
  • $34 — Greater-than-or-equal operator (>=)
  • $35 — Less-than-or-equal operator (<=)
  • $40 — Left shift operator (<<)
  • $41 — Arithmetic/signed right shift operator (>>)
  • $42 — Logical/unsigned right shift operator (>>>)
  • $50 — BANK(symbol); followed by the symbol's LONG ID.
  • $51 — BANK(section); followed by the section's STRING name.
  • $52 — PC's BANK() (i.e. BANK(@)). hi bestie 👋
  • $53 — SIZEOF(section); followed by the section's STRING name.
  • $54 — STARTOF(section); followed by the section's STRING name.
  • $55 — SIZEOF(sectiontype); followed by the sectiontype's BYTE value (see the Type values in "Sections").
  • $56 — STARTOF(sectiontype); followed by the sectiontype's BYTE value (see the Type values in "Sections").
  • $60 — ldh check. checks if the value is a valid ldh operand (see "Load Instructions" in gbz80(7)), i.e. that it's between either $00 and $FF, or $FF00 and $FFFF, both inclusive. the value is then ANDed with $00FF (& $FF).
  • $61 — rst check. checks if the value is a valid rst vector (see "RST vec" in gbz80(7)), that is, one of $00, $08, $10, $18, $20, $28, $30, or $38. the value is then ORed with $C7 (| $C7).
  • $62 — bit/res/set check; followed by the instruction's BYTE mask. checks if the value is a valid bit index (see e.g. "BIT u3, r8" in gbz80(7)), that is, from 0 to 7. the value is then ORed with the instruction's mask.
  • $70 — HIGH byte.
  • $71 — LOW byte.
  • $72 — BITWIDTH value.
  • $73 — TZCOUNT value.
  • $80 — Integer literal; followed by the LONG integer. big number energy 🔥
  • $81 — A symbol's value; followed by the symbol's LONG ID.

👀 SEE ALSO 👀

📜 HISTORY 📜

rgbasm(1) and rgblink(1) were originally written by Carsten Sørensen as part of the ASMotor package, and was later repackaged in RGBDS by Justin Lloyd. it's now maintained by a number of contributors at https://github.com/gbdev/rgbds. legends, honestly 🫶👑

okay that's the whole page bestie, you ate that 💅 this lil masterpiece comes to you from Debian, dated September 22, 2026, and it's the RGBDS(5) page — go forth and encode your RPN with confidence, mwah 🎀✨💖

📦 where this page comes from