Add documentation about the object file format

Copied from the HTML documentation and updated.

Signed-off-by: Antonio Niño Díaz <antonio_nd@outlook.com>

Makefile

@@ -63,7 +63,7 @@ rgbgfx_obj = \
 all: rgbasm rgblink rgbfix rgbgfx
 
 clean:
-	$Q${RM} rgbds.html gbz80.html
+	$Q${RM} rgbds.html gbz80.html rgbds.rgbformat.html
 	$Q${RM} rgbasm rgbasm.exe ${rgbasm_obj} rgbasm.html rgbasm-lang.html
 	$Q${RM} rgblink rgblink.exe ${rgblink_obj} rgblink.html rgblink-script.html
 	$Q${RM} rgbfix rgbfix.exe ${rgbfix_obj} rgbfix.html
@@ -80,6 +80,7 @@ install: all
 	$Qmkdir -p ${DESTDIR}${mandir}/man1 ${DESTDIR}${mandir}/man5 ${DESTDIR}${mandir}/man7
 	$Qinstall -m ${MANMODE} src/rgbds.7 ${DESTDIR}${mandir}/man7/rgbds.7
 	$Qinstall -m ${MANMODE} src/gbz80.7 ${DESTDIR}${mandir}/man7/gbz80.7
+	$Qinstall -m ${MANMODE} src/rgbds.rgbformat.5 ${DESTDIR}${mandir}/man7/rgbds.rgbformat.5
 	$Qinstall -m ${MANMODE} src/asm/rgbasm.1 ${DESTDIR}${mandir}/man1/rgbasm.1
 	$Qinstall -m ${MANMODE} src/asm/rgbasm.5 ${DESTDIR}${mandir}/man1/rgbasm.5
 	$Qinstall -m ${MANMODE} src/fix/rgbfix.1 ${DESTDIR}${mandir}/man1/rgbfix.1
@@ -138,6 +139,7 @@ MANDOC =	-Thtml -Ios=General -Oman=/rgbds/manual/%N/ \
 wwwman:
 	$Qmandoc ${MANDOC} src/rgbds.7 | sed s/OpenBSD/General/ > rgbds.html
 	$Qmandoc ${MANDOC} src/gbz80.7 | sed s/OpenBSD/General/ > gbz80.html
+	$Qmandoc ${MANDOC} src/rgbds.rgbformat.5 | sed s/OpenBSD/General/ > rgbds.rgbformat.html
 	$Qmandoc ${MANDOC} src/asm/rgbasm.1 | sed s/OpenBSD/General/ > \
 		rgbasm.html
 	$Qmandoc ${MANDOC} src/asm/rgbasm.5 | sed s/OpenBSD/General/ > \

src/asm/output.c

@@ -201,16 +201,15 @@ writepatch(struct Patch * pPatch, FILE * f)
 void
 writesection(struct Section * pSect, FILE * f)
 {
-	fputstring(pSect->pzName, f); // RGB3 addition
+	fputstring(pSect->pzName, f);
+
 	fputlong(pSect->nPC, f);
+
 	fputc(pSect->nType, f);
+
 	fputlong(pSect->nOrg, f);
-	//RGB1 addition
-
 	fputlong(pSect->nBank, f);
-	//RGB1 addition
+	fputlong(pSect->nAlign, f);
-
-	fputlong(pSect->nAlign, f); // RGB3 addition
 
 	if ((pSect->nType == SECT_ROM0)
 	    || (pSect->nType == SECT_ROMX)) {

src/rgbds.rgbformat.5

@@ -0,0 +1,194 @@
+.\" Copyright (c) 2017 Antonio Nino Diaz <antonio_nd@outlook.com>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd April 13, 2017
+.Dt RGBDS.RGBFORMAT 5
+.Os RGBDS Manual
+.Sh NAME
+.Nm rgbds.rgbformat
+.Nd 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]            ; "RGB4"
+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.
+
+        LONG    SectionID ; The section number (of this object file) in which
+                          ; this symbol is defined.
+
+        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 endianLONG patch.
+                                 ; 3 = big endian WORD patch (unused)
+                                 ; 4 = big endian LONG patch (unused)
+
+            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 $06 Ta Li | operator
+.It Li $07 Ta Li & operator
+.It Li $08 Ta Li ^ operator
+.It Li $09 Ta Li unary ~
+.It Li $0A Ta Li && comparison
+.It Li $0B Ta Li || comparison
+.It Li $0C Ta Li unary !
+.It Li $0D Ta Li == comparison
+.It Li $0E Ta Li != comparison
+.It Li $0F Ta Li > comparison
+.It Li $10 Ta Li < comparison
+.It Li $11 Ta Li >= comparison
+.It Li $12 Ta Li <= comparison
+.It Li $13 Ta Li << comparison
+.It Li $14 Ta Li >> comparison
+.It Li $15 Ta Li BANK()
+function.
+A symbol ID follows.
+.It Li $16 Ta Li HRAMCheck.
+Check if the value is in HRAM, AND it with 0xFF.
+.It Li $17 No Ta RangeCheck, LOW and HIGH signed LONGs follow.
+Check a value to see if it's within the range [LOW;HIGH].
+.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
+https://github.com/rednex/rgbds.