Merge pull request #165 from AntonioND/an/rgbasm-manual

Add documentation of rgbds to man pages and cleanup code

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

Makefile

@@ -63,8 +63,8 @@ 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
+	$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
 	$Q${RM} rgbgfx rgbgfx.exe ${rgbgfx_obj} rgbgfx.html
@@ -80,7 +80,9 @@ 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
 	$Qinstall -m ${MANMODE} src/link/rgblink.1 ${DESTDIR}${mandir}/man1/rgblink.1
 	$Qinstall -m ${MANMODE} src/link/rgblink.5 ${DESTDIR}${mandir}/man5/rgblink.5
@@ -137,8 +139,11 @@ 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/ > \
+		rgbasm-lang.html
 	$Qmandoc ${MANDOC} src/fix/rgbfix.1 | sed s/OpenBSD/General/ > \
 		rgbfix.html
 	$Qmandoc ${MANDOC} src/link/rgblink.1 | sed s/OpenBSD/General/ > \

include/asm/mylink.h

@@ -1,64 +1,6 @@
 #ifndef RGBDS_ASM_LINK_H
 #define RGBDS_ASM_LINK_H
 
-/* RGB4 .o format:
- *
- * Header
- * Symbols
- * Sections
- *
- * Header:
- * "RGB4"
- * LONG NumberOfSymbols
- * LONG NumberOfSections
- *
- * Symbols:
- * Symbol[NumberOfSymbols]
- *
- * Symbol:
- * char Name (NULL terminated)
- * char nType
- * if (nType != SYM_IMPORT)
- * {
- *		LONG SectionID
- *		LONG Offset
- * }
- *
- * Sections:
- * Section[NumberOfSections]
- *
- * Section:
- * char SectionName (NULL-terminated)
- * LONG SizeInBytes
- * char Type
- * LONG OrgPosition
- * LONG Bank
- * LONG Alignment
- * if (Type == ROM0 || Type == ROMX)
- * {
- *		char Data[SizeInBytes]
- *		Patches
- * }
- *
- * Patches:
- * LONG NumberOfPatches
- * Patch[NumberOfPatches]
- *
- * Patch:
- * char Filename NULL-terminated
- * LONG LineNo
- * LONG Offset
- * char Type
- * LONG RpnByteSize
- * Rpn[RpnByteSize]
- *
- * Rpn:
- * Operators: 0x00-0x7F
- * Constants: 0x80 0x00000000
- * Symbols  : 0x81 0x00000000
- *
- */
-
 enum {
 	RPN_ADD = 0,
 	RPN_SUB,
@@ -90,13 +32,6 @@ enum {
 
 	RPN_HRAM,
 
-	/* TODO: This hasn't been removed in order not to break compatibility
-	 * with the existing object files, but it will be removed in a future
-	 * version. */
-	RPN_unused,
-
-	RPN_RANGECHECK,
-
 	RPN_CONST = 0x80,
 	RPN_SYM = 0x81
 };
@@ -121,8 +56,6 @@ enum {
 enum {
 	PATCH_BYTE = 0,
 	PATCH_WORD_L,
-	PATCH_LONG_L,
+	PATCH_LONG_L
-	PATCH_WORD_B,
-	PATCH_LONG_B
 };
 #endif

include/asm/rpn.h

@@ -76,9 +76,6 @@ void rpn_UNNOT(struct Expression * expr, struct Expression * src);
 UWORD rpn_PopByte(struct Expression * expr);
 void rpn_Bank(struct Expression * expr, char *tzSym);
 void rpn_Reset(struct Expression * expr);
-int
-rpn_RangeCheck(struct Expression * expr, struct Expression * src, SLONG low,
-    SLONG high);
 void rpn_CheckHRAM(struct Expression * expr, struct Expression * src1);
 
 #endif

include/link/mylink.h

@@ -45,8 +45,6 @@ enum eRpnData {
 
 	RPN_HRAM,
 
-	RPN_RANGECHECK,
-
 	RPN_CONST = 0x80,
 	RPN_SYM = 0x81
 };
@@ -96,9 +94,7 @@ struct sSymbol {
 enum ePatchType {
 	PATCH_BYTE = 0,
 	PATCH_WORD_L,
-	PATCH_LONG_L,
+	PATCH_LONG_L
-	PATCH_WORD_B,
-	PATCH_LONG_B
 };
 
 struct sPatch {

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/asm/rgbasm.1

@@ -12,7 +12,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd April 8, 2017
+.Dd April 12, 2017
 .Dt RGBASM 1
 .Os RGBDS Manual
 .Sh NAME
@@ -82,9 +82,12 @@ run through
 and
 .Xr rgbfix 1 .
 .Sh SEE ALSO
+.Xr rgbasm 5 ,
 .Xr rgbfix 1 ,
 .Xr rgblink 1 ,
-.Xr rgbds 7
+.Xr rgbds.rgbformat 5 ,
+.Xr rgbds 7 ,
+.Xr gbz80 7
 .Pp
 .Lk https://rednex.github.io/rgbds/asm.htm rgbasm assembly commands
 .Sh HISTORY

src/asm/rpn.c

@@ -128,28 +128,6 @@ rpn_Bank(struct Expression * expr, char *tzSym)
 		yyerror("BANK argument must be a relocatable identifier");
 }
 
-int
-rpn_RangeCheck(struct Expression * expr, struct Expression * src, SLONG low,
-    SLONG high)
-{
-	*expr = *src;
-
-	if (rpn_isReloc(src)) {
-		pushbyte(expr, RPN_RANGECHECK);
-		pushbyte(expr, low);
-		pushbyte(expr, low >> 8);
-		pushbyte(expr, low >> 16);
-		pushbyte(expr, low >> 24);
-		pushbyte(expr, high);
-		pushbyte(expr, high >> 8);
-		pushbyte(expr, high >> 16);
-		pushbyte(expr, high >> 24);
-		return (1);
-	} else {
-		return (expr->nVal >= low && expr->nVal <= high);
-	}
-}
-
 void
 rpn_CheckHRAM(struct Expression * expr, struct Expression * src)
 {

src/gbz80.7

@@ -12,7 +12,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd April 8, 2017
+.Dd April 12, 2017
 .Dt GBZ80 7
 .Os RGBDS Manual
 .Sh NAME
@@ -25,6 +25,14 @@ including a short description, the number of bytes needed to encode them and the
 number of CPU cycles at 1MHz (or 2MHz in GBC dual speed mode) needed to complete
 them.
 .Pp
+Note: All arithmetic/logic operations that use register
+.Sy A No as destination can omit the destination as it is assumed it's register
+.Sy A .
+The following two lines have the same effect:
+.Pp
+.Dl OR A,B
+.Dl OR B
+.Pp
 .Sh LEGEND
 List of abbreviations used in this document.
 .Bl -tag

src/link/patch.c

@@ -206,29 +206,6 @@ calcrpn(struct sPatch * pPatch)
 			rpnpush(getsymbank(t));
 			size -= 4;
 			break;
-		case RPN_RANGECHECK:
-			{
-				SLONG low, high;
-
-				low = (*rpn++);
-				low |= (*rpn++) << 8;
-				low |= (*rpn++) << 16;
-				low |= (*rpn++) << 24;
-				high = (*rpn++);
-				high |= (*rpn++) << 8;
-				high |= (*rpn++) << 16;
-				high |= (*rpn++) << 24;
-				t = rpnpop();
-				if (t < low || t > high) {
-					errx(1,
-					    "%s(%ld) : Value must be in the range [%ld;%ld]",
-					    pPatch->pzFilename,
-					    pPatch->nLineNo, low, high);
-				}
-				rpnpush(t);
-				size -= 8;
-				break;
-			}
 		}
 	}
 	return (rpnpop());
@@ -264,22 +241,12 @@ Patch(void)
 				}
 				break;
 			case PATCH_WORD_L:
-			case PATCH_WORD_B:
 				if (t >= -32768 && t <= 65535) {
 					t &= 0xFFFF;
-					if (pPatch->Type == PATCH_WORD_L) {
+					pSect->pData[pPatch->nOffset] =
-						pSect->pData[pPatch->nOffset] =
+						t & 0xFF;
-						    t & 0xFF;
+					pSect->pData[pPatch->nOffset + 1] =
-						pSect->pData[pPatch->nOffset +
+						(t >> 8) & 0xFF;
-						    1] =
-						    (t >> 8) & 0xFF;
-					} else {
-						//Assume big endian
-						    pSect->pData[pPatch->nOffset] =
-						    (t >> 8) & 0xFF;
-						pSect->pData[pPatch->nOffset +
-						    1] = t & 0xFF;
-					}
 				} else {
 					errx(1,
 					    "%s(%ld) : Value must be 16-bit",
@@ -296,15 +263,6 @@ Patch(void)
 				pSect->pData[pPatch->nOffset + 3] =
 				    (t >> 24) & 0xFF;
 				break;
-			case PATCH_LONG_B:
-				pSect->pData[pPatch->nOffset + 0] =
-				    (t >> 24) & 0xFF;
-				pSect->pData[pPatch->nOffset + 1] =
-				    (t >> 16) & 0xFF;
-				pSect->pData[pPatch->nOffset + 2] =
-				    (t >> 8) & 0xFF;
-				pSect->pData[pPatch->nOffset + 3] = t & 0xFF;
-				break;
 			}
 
 			pPatch = pPatch->pNext;

src/link/rgblink.1

@@ -12,7 +12,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd April 8, 2017
+.Dd April 12, 2017
 .Dt RGBLINK 1
 .Os RGBDS Manual
 .Sh NAME
@@ -113,6 +113,7 @@ to fix these so that the program will actually run in a Game Boy:
 .Xr rgbasm 1 ,
 .Xr rgblink 5 ,
 .Xr rgbfix 1 ,
+.Xr rgbds.rgbformat 5 ,
 .Xr rgbds 7
 .Sh HISTORY
 .Nm

src/link/rgblink.5

@@ -12,7 +12,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd April 8, 2017
+.Dd April 12, 2017
 .Dt RGBLINK 5
 .Os RGBDS Manual
 .Sh NAME
@@ -81,6 +81,7 @@ linkerscript. The address and alignment musn't be set.
 .Xr rgbasm 1 ,
 .Xr rgblink 1 ,
 .Xr rgbfix 1 ,
+.Xr rgbds.rgbformat 5 ,
 .Xr rgbds 7
 .Sh HISTORY
 .Nm

src/rgbds.7

@@ -12,7 +12,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd April 8, 2017
+.Dd April 12, 2017
 .Dt RGBDS 7
 .Os RGBDS Manual
 .Sh NAME
@@ -28,6 +28,7 @@ To get a working ROM image from a single assembly source file:
 .Xr rgbasm 1 ,
 .Xr rgbfix 1 ,
 .Xr rgblink 1 ,
+.Xr rgbds.rgbformat 5 ,
 .Xr gbz80 7
 .Sh HISTORY
 .Bl -ohang

src/rgbds.rgbformat.5

@@ -0,0 +1,190 @@
+.\" 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 endian LONG 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 $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 $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.