1.\"
2.\" This file is part of RGBDS.
3.\"
4.\" Copyright (c) 2017-2021, Antonio Nino Diaz and RGBDS contributors.
5.\"
6.\" SPDX-License-Identifier: MIT
7.\"
8.Dd March 28, 2021
9.Dt RGBLINK 5
10.Os
11.Sh NAME
12.Nm rgblink
13.Nd linker script file format
14.Sh DESCRIPTION
15The linker script is an external file that allows the user to specify the order of sections at link time and in a centralized manner.
16.Pp
17A linker script consists on a series of banks followed by a list of sections and, optionally, commands.
18They can be lowercase or uppercase, it is ignored.
19Any line can contain a comment starting with
20.Ql \&;
21that ends at the end of the line:
22.Bd -literal -offset indent
23ROMX $F ; This is a comment
24  "Functions to read array"
25  ALIGN 8
26  "Array aligned to 256 bytes"
27
28WRAMX 2
29  "Some variables"
30.Ed
31.Pp
32Numbers can be in decimal or hexadecimal format
33.Pq the prefix is Ql $ .
34It is an error if any section name or command is found before setting a bank.
35.Pp
36Files can be included by using the
37.Ic INCLUDE
38keyword, followed by a string with the path of the file that has to be included.
39.Pp
40The possible bank types are:
41.Cm ROM0 , ROMX , VRAM , SRAM , WRAM0 , WRAMX , OAM
42and
43.Cm HRAM .
44Unless there is a single bank, which can occur with types
45.Cm ROMX , VRAM , SRAM
46and
47.Cm WRAMX ,
48it is needed to specify a bank number after the type.
49.Pp
50When a new bank statement is found, sections found after it will be placed right from the beginning of that bank.
51If the linker script switches to a different bank and then comes back to a previous one, it will continue from the last address that was used.
52.Pp
53The only two commands are
54.Ic ORG
55and
56.Ic ALIGN :
57.Bl -bullet
58.It
59.Ic ORG
60sets the address in which new sections will be placed.
61It can not be lower than the current address.
62.It
63.Ic ALIGN
64will increase the address until it is aligned to the specified boundary
65.Po it tries to set to 0 the number of bits specified after the command:
66.Ql ALIGN 8
67will align to $100
68.Pc .
69.El
70.Pp
71.Sy Note:
72The bank, alignment, address and type of sections can be specified both in the source code and in the linker script.
73For a section to be able to be placed with the linker script, the bank, address and alignment must be left unassigned in the source code or be compatible with what is specified in the linker script.
74For example,
75.Ql ALIGN[8]
76in the source code is compatible with
77.Ql ORG $F00
78in the linker script.
79.Sh SEE ALSO
80.Xr rgbasm 1 ,
81.Xr rgblink 1 ,
82.Xr rgbfix 1 ,
83.Xr rgbds 5 ,
84.Xr rgbds 7
85.Sh HISTORY
86.Nm
87was originally written by Carsten S\(/orensen as part of the ASMotor package,
88and was later packaged in RGBDS by Justin Lloyd.
89It is now maintained by a number of contributors at
90.Lk https://github.com/gbdev/rgbds .
91