diff --git a/Makefile b/Makefile index dbbd7e47..2d8f8043 100644 --- a/Makefile +++ b/Makefile @@ -82,6 +82,7 @@ install: all $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} diff --git a/src/link/rgblink.1 b/src/link/rgblink.1 index 1ff59477..227e2818 100644 --- 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 @@ Write a tiny 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 @@ to fix these so that the program will actually run in a Game Boy: .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. diff --git a/src/link/rgblink.5 b/src/link/rgblink.5 new file mode 100644 index 00000000..3d042159 --- /dev/null +++ b/src/link/rgblink.5 @@ -0,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.