1.\" 2.\" This file is part of RGBDS. 3.\" 4.\" Copyright (c) 2010-2021, Anthony J. Bentley and RGBDS contributors. 5.\" 6.\" SPDX-License-Identifier: MIT 7.\" 8.Dd March 28, 2021 9.Dt RGBLINK 1 10.Os 11.Sh NAME 12.Nm rgblink 13.Nd Game Boy linker 14.Sh SYNOPSIS 15.Nm 16.Op Fl dtVvwx 17.Op Fl l Ar linker_script 18.Op Fl m Ar map_file 19.Op Fl n Ar sym_file 20.Op Fl O Ar overlay_file 21.Op Fl o Ar out_file 22.Op Fl p Ar pad_value 23.Op Fl S Ar spec 24.Op Fl s Ar symbol 25.Ar 26.Sh DESCRIPTION 27The 28.Nm 29program links RGB object files, typically created by 30.Xr rgbasm 1 , 31into a single Game Boy ROM file. 32The format is documented in 33.Xr rgbds 5 . 34.Pp 35ROM0 sections are placed in the first 16 KiB of the output ROM, and ROMX sections are placed in any 16 KiB 36.Dq bank 37except the first. 38If your ROM will only be 32 KiB, you can use the 39.Fl t 40option to change this. 41.Pp 42Similarly, WRAM0 sections are placed in the first 4 KiB of WRAM 43.Pq Dq bank 0 , 44and WRAMX sections are placed in any bank of the last 4 KiB. 45If your ROM doesn't use banked WRAM, you can use the 46.Fl w 47option to change this. 48.Pp 49Also, if your ROM is designed for a monochrome Game Boy, you can make sure that you don't use any incompatible section by using the 50.Fl d 51option, which implies 52.Fl w 53but also prohibits the use of banked VRAM. 54.Pp 55Note that options can be abbreviated as long as the abbreviation is unambiguous: 56.Fl Fl verb 57is 58.Fl Fl verbose , 59but 60.Fl Fl ver 61is invalid because it could also be 62.Fl Fl version . 63The arguments are as follows: 64.Bl -tag -width Ds 65.It Fl d , Fl Fl dmg 66Enable DMG mode. 67Prohibit the use of sections that doesn't exist on a DMG, such as VRAM bank 1. 68This option automatically enables 69.Fl w . 70.It Fl l Ar linker_script , Fl Fl linkerscript Ar linker_script 71Specify a linker script file that tells the linker how sections must be placed in the ROM. 72The attributes assigned in the linker script must be consistent with any assigned in the code. 73See 74.Xr rgblink 5 75for more information about the linker script format. 76.It Fl m Ar map_file , Fl Fl map Ar map_file 77Write a map file to the given filename, listing how sections and symbols were assigned. 78.It Fl n Ar sym_file , Fl Fl sym Ar sym_file 79Write a symbol file to the given filename, listing the address of all exported symbols. 80Several external programs can use this information, for example to help debugging ROMs. 81.It Fl O Ar overlay_file , Fl Fl overlay Ar overlay_file 82If specified, sections will be overlaid "on top" of the provided ROM image. 83In that case, all sections must be fixed. 84This may be used to patch an existing binary. 85.It Fl o Ar out_file , Fl Fl output Ar out_file 86Write the ROM image to the given file. 87.It Fl p Ar pad_value , Fl Fl pad Ar pad_value 88When inserting padding between sections, pad with this value. 89Has no effect if 90.Fl O 91is specified. 92The default is 0. 93.It Fl S Ar spec , Fl Fl scramble Ar spec 94Enables a different 95.Dq scrambling 96algorithm for placing sections. 97See 98.Sx Scrambling algorithm 99below for an explanation and a description of 100.Ar spec . 101.It Fl s Ar symbol , Fl Fl smart Ar symbol 102This option is ignored. 103It was supposed to perform smart linking but fell into disrepair, and so has been removed. 104It will be reimplemented at some point. 105.It Fl t , Fl Fl tiny 106Expand the ROM0 section size from 16 KiB to the full 32 KiB assigned to ROM. 107ROMX sections that are fixed to a bank other than 1 become errors, other ROMX sections are treated as ROM0. 108Useful for ROMs that fit in 32 KiB. 109.It Fl V , Fl Fl version 110Print the version of the program and exit. 111.It Fl v , Fl Fl verbose 112Verbose: enable printing more information to standard error. 113.It Fl w , Fl Fl wramx 114Expand the WRAM0 section size from 4 KiB to the full 8 KiB assigned to WRAM. 115WRAMX sections that are fixed to a bank other than 1 become errors, other WRAMX sections are treated as WRAM0. 116.It Fl x , Fl Fl nopad 117Disables padding the end of the final file. 118This option automatically enables 119.Fl t . 120You can use this when not not making a ROM. 121When making a ROM, be careful that not using this is not a replacement for 122.Xr rgbfix 1 Ap s Fl p 123option! 124.El 125.Ss Scrambling algorithm 126The default section placement algorithm tries to minimize the number of banks used; 127.Dq scrambling 128instead places sections into a given pool of banks, trying to minimize the number of sections sharing a given bank. 129This is useful to catch broken bank assumptions, such as expecting two different sections to land in the same bank (that is not guaranteed unless both are manually assigned the same bank number). 130.Pp 131A scrambling spec is a comma-separated list of region specs. 132A trailing comma is allowed, as well as whitespace between all specs and their components. 133Each region spec has the following form: 134.D1 Ar region Ns Op = Ns Ar size 135.Ar region 136must be one of the following (case-insensitive), while 137.Ar size 138must be a positive decimal integer between 1 and the corresponding maximum. 139Certain regions allow omitting the size, in which case it defaults to its max value. 140.Bl -column "Region name" "Max value" "Size optional" 141Region name Ta Max size Ta Size optional 142.Cm romx Ta 65535 Ta \&No 143.Cm sram Ta 255 Ta \&No 144.Cm wramx Ta 7 Ta Yes 145.El 146.Pp 147A 148.Ar size 149of 0 disables scrambling for that region. 150.Pp 151For example, 152.Ql romx=64,wramx=4 153will scramble 154.Ic ROMX 155sections among ROM banks 1 to 64, 156.Ic WRAMX 157sections among RAM banks 1 to 4, and will not scramble 158.Ic SRAM 159sections. 160.Pp 161Later region specs override earlier ones; for example, 162.Ql romx=42, Romx=0 163disables scrambling for 164.Cm romx . 165.Pp 166.Cm wramx 167scrambling is silently ignored if 168.Fl w 169is passed (including if implied by 170.Fl d ) , 171as 172.Ic WRAMX 173sections will be treated as 174.Ic WRAM0 . 175.Sh EXAMPLES 176All you need for a basic ROM is an object file, which can be made into a ROM image like so: 177.Pp 178.Dl $ rgblink -o bar.gb foo.o 179.Pp 180The resulting 181.Ar bar.gb 182will not have correct checksums (unless you put them in the assembly source). 183You should use 184.Xr rgbfix 1 185to fix these so that the program will actually run in a Game Boy: 186.Pp 187.Dl $ rgbfix -v bar.gb 188.Pp 189Here is a more complete example: 190.Pp 191.Dl $ rgblink -o bin/game.gb -n bin/game.sym -p 0xFF obj/title.o obj/engine.o 192.Sh BUGS 193Please report bugs on 194.Lk https://github.com/gbdev/rgbds/issues GitHub . 195.Sh SEE ALSO 196.Xr rgbasm 1 , 197.Xr rgblink 5 , 198.Xr rgbfix 1 , 199.Xr rgbds 5 , 200.Xr rgbds 7 201.Sh HISTORY 202.Nm 203was originally written by Carsten S\(/orensen as part of the ASMotor package, and was later packaged in RGBDS by Justin Lloyd. 204It is now maintained by a number of contributors at 205.Lk https://github.com/gbdev/rgbds . 206