shithub: rgbds

--- a/Makefile

+++ b/Makefile

@@ -82,6 +82,7 @@

 	$Qinstall -m ${MANMODE} src/asm/rgbasm.1 ${MANPREFIX}/man1/rgbasm.1

 	$Qinstall -m ${MANMODE} src/fix/rgbfix.1 ${MANPREFIX}/man1/rgbfix.1

 	$Qinstall -m ${MANMODE} src/link/rgblink.1 ${MANPREFIX}/man1/rgblink.1

+	$Qinstall -m ${MANMODE} src/link/rgblink.5 ${MANPREFIX}/man1/rgblink.5

 	$Qinstall -m ${MANMODE} src/gfx/rgbgfx.1 ${MANPREFIX}/man1/rgbgfx.1

 rgbasm: ${rgbasm_obj}

--- a/src/link/rgblink.1

+++ b/src/link/rgblink.1

@@ -1,4 +1,4 @@

-.Dd February 26, 2015

+.Dd March 27, 2017

 .Dt RGBLINK 1

 .Os RGBDS Manual

 .Sh NAME

@@ -14,6 +14,7 @@

 .Op Fl o Ar outfile

 .Op Fl p Ar pad_value

 .Op Fl s Ar symbol

+.Op Fl l Ar linkerscript

.Ar

 .Sh DESCRIPTION

The

@@ -54,6 +55,14 @@

 ROM file.

 This forces all ROMX sections to be of type ROM0, and increases the ROM0

 section size from 16KiB to 32KiB.

+.It Fl l Ar linkerscript

+Specify a linkerscript file that tells the linker how sections must be placed in

+the ROM.

+This file has priority over the attributes assigned in the source code, but they

+have to be consistent.

+See

+.Xr rgblink 5

+for more information about its format.

.El

 .Sh EXAMPLES

 All you need for a basic ROM is an object file, which can be made into a ROM

@@ -70,9 +79,11 @@

 .D1 $ rgbfix -v bar.gb

 .Sh SEE ALSO

 .Xr rgbasm 1 ,

+.Xr rgblink 5 ,

 .Xr rgbfix 1 ,

 .Xr rgbds 7

 .Sh HISTORY

.Nm

 was originally written by Carsten S\(/orensen as part of the ASMotor package,

-and was later packaged in RGBDS by Justin Lloyd.

+and was later packaged in RGBDS by Justin Lloyd. It is now maintained by a

+number of contributors at https://github.com/rednex/rgbds.

--- /dev/null

+++ b/src/link/rgblink.5

@@ -1,0 +1,68 @@

+.Dd March 27, 2017

+.Dt RGBLINK 5

+.Os RGBDS Manual

+.Sh NAME

+.Nm rgblink

+.Nd linkerscript file format

+.Sh DESCRIPTION

+The linkerscript is an external file that allows the user to specify the

+order of sections without the need for doing so before assembling each object

+file.

+.Pp

+The placement of sections specified in the linkerscript is done before the

+sections whose placement is defined in the source code.

+.Pp

+A linkerscript consists on a series of banks followed by a list of sections

+and, optionally, commands.

+They can be lowercase or uppercase, it is ignored.

+Any line can contain a comment starting with

+.Ql \&;

+that ends at the end of the line:

+.Pp

+  ROMX $F ; This is a comment

+   "Functions to read array"

+   ALIGN 8

+   "Array aligned to 256 bytes"

+  WRAMX 2

+    "Some variables"

+.Pp

+Numbers can be in decimal or hexadecimal format (the prefix is

+.Ql $ ) .

+It is an error if any bank or command is found before setting a bank.

+.Pp

+The possible bank types are: ROM0, ROMX, VRAM, WRAM0, WRAMX, OAM and HRAM.

+Types ROMX, VRAM, WRAMX and SRAM are banked, which means that it is needed to

+specify a bank after the type.

+.Pp

+When a new bank statement is found, sections found after it will be placed

+right from the beginning of that bank.

+If the linkerscript switches to a different bank and then it comes back to the

+previous one it will continue from the last address that was used.

+.Pp

+The only two commands are ORG and ALIGN:

+.Bl -bullet

+.It

+ORG sets the address in which new sections will be placed.

+It can not be lower than the current address.

+.It

+ALIGN will increase the address until it is aligned to the specified boundary

+(it tries to set to 0 the number of bits specified after the command: ALIGN 8

+will align to $100).

+.El

+.Pp

+Note: The bank, alignment, address and type of sections can be specified both

+in the source code and in the linkerscript.

+For a section to be able to be placed with the linkerscript the bank must be

+left unassigned in the source code or be the same as the one specified in the

+linkerscript. The address and alignment musn't be set.

+.Sh SEE ALSO

+.Xr rgbasm 1 ,

+.Xr rgblink 1 ,

+.Xr rgbfix 1 ,

+.Xr rgbds 7

+.Sh HISTORY

+.Nm

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