shithub: rgbds

ref: b0ec8468e65c1fdc17102fcfd29747ef29535f4f
dir: /docs/rgbds.5.html/

View raw version
<!DOCTYPE html>
<html>
<!-- This is an automatically generated file.  Do not edit.
   This file is part of RGBDS.
  
   Copyright (c) 2017-2018, Antonio Nino Diaz and RGBDS contributors.
  
   SPDX-License-Identifier: MIT
   -->
<head>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <meta charset="utf-8"/>
  <link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
  <link rel="stylesheet" href="rgbds.css" type="text/css" media="all"/>
  <title>RGBDS(5)</title>
</head>
<body>
<table class="head">
  <tr>
    <td class="head-ltitle">RGBDS(5)</td>
    <td class="head-vol">File Formats Manual</td>
    <td class="head-rtitle">RGBDS(5)</td>
  </tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<code class="Nm">rgbds</code> &#x2014;
<span class="Nd">object file format documentation</span>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
This is the description of the object files used by <a class="Xr" href="rgbasm.1.html">rgbasm(1)</a>
  and <a class="Xr" href="rgblink.1.html">rgblink(1)</a>. <i class="Em">Please note that the
  specifications may change.</i> 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.
</section>
<section class="Sh">
<h1 class="Sh" id="FILE_STRUCTURE"><a class="permalink" href="#FILE_STRUCTURE">FILE
  STRUCTURE</a></h1>
The following types are used:
<p class="Pp"><var class="Ar">LONG</var> is a 32&#x2010;bit integer stored in
    little&#x2010;endian format. <var class="Ar">BYTE</var> is an 8&#x2010;bit
    integer. <var class="Ar">STRING</var> is a 0&#x2010;terminated string of
    <var class="Ar">BYTE</var>.</p>
<div class="Bd Pp">
<pre>
; Header

BYTE    ID[4]            ; &quot;RGB9&quot;
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

; Symbols

REPT    NumberOfSymbols   ; Number of symbols defined in this object file.

    STRING  Name          ; The name of this symbol. Local symbols are stored
                          ; as &quot;Scope.Symbol&quot;.

    BYTE    Type          ; 0 = LOCAL symbol only used in this file.
                          ; 1 = IMPORT this symbol from elsewhere
                          ; 2 = EXPORT this symbol to other objects.
                          ; Bit 7 is independent from the above value, and
                          ; encodes whether the section is unionized

    IF (Type &amp; 0x7F) != 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 1 &lt;&lt; align. 1 if
                  ; not specified.

    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    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

; Assertions

LONG  NumberOfAssertions

REPT  NumberOfAssertions

  STRING  SourceFile   ; Name of the source file (for printing the failure).

  LONG    Offset       ; Offset into the section where the assertion is located.

  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.

  LONG    SectionID    ; The section number (of this object file) in which this
                       ; assert is defined. If it doesn't belong to any specific
                       ; section (like a constant), this field has the value -1.

  STRING  Message      ; A message displayed when the assert fails. If set to
                       ; the empty string, a generic message is printed instead.

ENDR
</pre>
</div>
<section class="Ss">
<h2 class="Ss" id="RPN_DATA"><a class="permalink" href="#RPN_DATA">RPN
  DATA</a></h2>
Expressions in the object file are stored as RPN. This is an expression of the
  form &#x201C;2 5 +&#x201D;. This will first push the value &#x201C;2&#x201D;
  to the stack, then &#x201C;5&#x201D;. The &#x201C;+&#x201D; 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 <var class="Ar">BYTE</var>s with some bytes
  being special prefixes for integers and symbols.
<table class="Bl-column Bd-indent">
  <tr>
    <th>Value</th>
    <th>Meaning</th>
  </tr>
  <tr>
    <td><a class="permalink" href="#$00"><code class="Li" id="$00">$00</code></a></td>
    <td><a class="permalink" href="#+_operator"><code class="Li" id="+_operator">+
      operator</code></a></td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$01"><code class="Li" id="$01">$01</code></a></td>
    <td><a class="permalink" href="#-_operator"><code class="Li" id="-_operator">-
      operator</code></a></td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$02"><code class="Li" id="$02">$02</code></a></td>
    <td><a class="permalink" href="#*_operator"><code class="Li" id="*_operator">*
      operator</code></a></td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$03"><code class="Li" id="$03">$03</code></a></td>
    <td><a class="permalink" href="#/_operator"><code class="Li" id="/_operator">/
      operator</code></a></td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$04"><code class="Li" id="$04">$04</code></a></td>
    <td><a class="permalink" href="#__operator"><code class="Li" id="__operator">%
      operator</code></a></td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$05"><code class="Li" id="$05">$05</code></a></td>
    <td><a class="permalink" href="#unary_-"><code class="Li" id="unary_-">unary
      -</code></a></td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$10"><code class="Li" id="$10">$10</code></a></td>
    <td>|
      <a class="permalink" href="#operator"><code class="Li" id="operator">operator</code></a></td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$11"><code class="Li" id="$11">$11</code></a></td>
    <td><a class="permalink" href="#&amp;_operator"><code class="Li" id="&amp;_operator">&amp;
      operator</code></a></td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$12"><code class="Li" id="$12">$12</code></a></td>
    <td><a class="permalink" href="#__operator_2"><code class="Li" id="__operator_2">^
      operator</code></a></td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$13"><code class="Li" id="$13">$13</code></a></td>
    <td><a class="permalink" href="#unary_~"><code class="Li" id="unary_~">unary
      ~</code></a></td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$21"><code class="Li" id="$21">$21</code></a></td>
    <td><a class="permalink" href="#&amp;&amp;_comparison"><code class="Li" id="&amp;&amp;_comparison">&amp;&amp;
      comparison</code></a></td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$22"><code class="Li" id="$22">$22</code></a></td>
    <td><a class="permalink" href="#___comparison"><code class="Li" id="___comparison">||
      comparison</code></a></td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$23"><code class="Li" id="$23">$23</code></a></td>
    <td><a class="permalink" href="#unary"><code class="Li" id="unary">unary</code></a>!</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$30"><code class="Li" id="$30">$30</code></a></td>
    <td><a class="permalink" href="#==_comparison"><code class="Li" id="==_comparison">==
      comparison</code></a></td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$31"><code class="Li" id="$31">$31</code></a></td>
    <td><a class="permalink" href="#!=_comparison"><code class="Li" id="!=_comparison">!=
      comparison</code></a></td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$32"><code class="Li" id="$32">$32</code></a></td>
    <td><a class="permalink" href="#__comparison"><code class="Li" id="__comparison">&gt;
      comparison</code></a></td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$33"><code class="Li" id="$33">$33</code></a></td>
    <td><a class="permalink" href="#__comparison_2"><code class="Li" id="__comparison_2">&lt;
      comparison</code></a></td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$34"><code class="Li" id="$34">$34</code></a></td>
    <td><a class="permalink" href="#_=_comparison"><code class="Li" id="_=_comparison">&gt;=
      comparison</code></a></td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$35"><code class="Li" id="$35">$35</code></a></td>
    <td><a class="permalink" href="#_=_comparison_2"><code class="Li" id="_=_comparison_2">&lt;=
      comparison</code></a></td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$40"><code class="Li" id="$40">$40</code></a></td>
    <td><a class="permalink" href="#___operator"><code class="Li" id="___operator">&lt;&lt;
      operator</code></a></td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$41"><code class="Li" id="$41">$41</code></a></td>
    <td><a class="permalink" href="#___operator_2"><code class="Li" id="___operator_2">&gt;&gt;
      operator</code></a></td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$50"><code class="Li" id="$50">$50</code></a></td>
    <td><a class="permalink" href="#BANK(symbol)"><code class="Li" id="BANK(symbol)">BANK(symbol)</code></a>,
      a <var class="Ar">LONG</var> Symbol ID follows.</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$51"><code class="Li" id="$51">$51</code></a></td>
    <td><a class="permalink" href="#BANK(section_name)"><code class="Li" id="BANK(section_name)">BANK(section_name)</code></a>,
      a null-terminated string follows.</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$52"><code class="Li" id="$52">$52</code></a></td>
    <td><a class="permalink" href="#Current_BANK()"><code class="Li" id="Current_BANK()">Current
      BANK()</code></a></td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$60"><code class="Li" id="$60">$60</code></a></td>
    <td><a class="permalink" href="#HRAMCheck"><code class="Li" id="HRAMCheck">HRAMCheck</code></a>.
      Checks if the value is in HRAM, ANDs it with 0xFF.</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$61"><code class="Li" id="$61">$61</code></a></td>
    <td><a class="permalink" href="#RSTCheck"><code class="Li" id="RSTCheck">RSTCheck</code></a>.
      Checks if the value is a RST vector, ORs it with 0xC7.</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$80"><code class="Li" id="$80">$80</code></a></td>
    <td><var class="Ar">LONG</var> integer follows.</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#$81"><code class="Li" id="$81">$81</code></a></td>
    <td><var class="Ar">LONG</var> symbol ID follows.</td>
  </tr>
</table>
</section>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
  ALSO</a></h1>
<a class="Xr" href="rgbasm.1.html">rgbasm(1)</a>, <a class="Xr" href="rgblink.1.html">rgblink(1)</a>,
  <a class="Xr" href="rgbds.7.html">rgbds(7)</a>, <a class="Xr" href="gbz80.7.html">gbz80(7)</a>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<code class="Nm">rgbds</code> was originally written by Carsten S&#x00F8;rensen
  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
  <a class="Lk" href="https://github.com/rednex/rgbds">https://github.com/rednex/rgbds</a>.
</section>
</div>
<table class="foot">
  <tr>
    <td class="foot-date">January 26, 2018</td>
    <td class="foot-os">General</td>
  </tr>
</table>
</body>
</html>