gbdev/rgbds
1
0
Fork 0
mirror of https://github.com/gbdev/rgbds.git synced 2025-11-20 10:12:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
Add documentation of rgbds to man pages and cleanup code

Signed-off-by: Antonio Niño Díaz <antonio_nd@outlook.com>
This commit is contained in:
Antonio Niño Díaz
2017-04-16 20:13:49 +01:00
parent f7f697c267 729683fb1f
commit 59c065cf31
14 changed files with 1234 additions and 158 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
Makefile
View File

@@ -63,8 +63,8 @@ rgbgfx_obj = \
all: rgbasm rgblink rgbfix rgbgfx
clean:
$Q${RM} rgbds.html gbz80.html
$Q${RM} rgbasm rgbasm.exe ${rgbasm_obj} rgbasm.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
$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/ > \

69
include/asm/mylink.h
View File

@@ -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_WORD_B,
PATCH_LONG_B
PATCH_LONG_L
};
#endif

3
include/asm/rpn.h
View File

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

6
include/link/mylink.h
View File

@@ -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_WORD_B,
PATCH_LONG_B
PATCH_LONG_L
};
struct sPatch {

11
src/asm/output.c
View File

@@ -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); // RGB3 addition
fputlong(pSect->nAlign, f);
if ((pSect->nType == SECT_ROM0)
|| (pSect->nType == SECT_ROMX)) {

7
src/asm/rgbasm.1
View File

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

1006
src/asm/rgbasm.5 Normal file
View File

File diff suppressed because it is too large Load Diff

22
src/asm/rpn.c
View File

@@ -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)
{

10
src/gbz80.7
View File

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

44
src/link/patch.c
View File

@@ -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] =
t & 0xFF;
pSect->pData[pPatch->nOffset +
1] =
pSect->pData[pPatch->nOffset + 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;

3
src/link/rgblink.1
View File

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

3
src/link/rgblink.5
View File

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

3
src/rgbds.7
View File

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

190
src/rgbds.rgbformat.5 Normal file
View File

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