rgblink.5

.\" SPDX-License-Identifier: MIT
.\"
.Dd September 18, 2024
.Dt RGBLINK 5
.Os
.Sh NAME
.Nm rgblink
.Nd linker script file format
.Sh DESCRIPTION
The linker script is a file that allows specifying attributes for sections at link time, and in a centralized manner.
There can only be one linker script per invocation of
.Nm ,
but it can be split into several files
.Pq using the Ic INCLUDE No directive .
.Ss Basic syntax
The linker script syntax is line-based.
Each line may have a directive or section name, a comment, both, or neither.
Whitespace (space and tab characters) is used to separate syntax elements, but is otherwise ignored.
.Pp
Comments begin with a semicolon
.Ql \&;
character, until the end of the line.
They are simply ignored.
.Pp
Keywords are composed of letters and digits (but they can't start with a digit); they are all case-insensitive.
.Pp
Numbers can be written in decimal format, or in binary using the
.Ql %
prefix, or in hexadecimal using the
.Ql $
prefix (hexadecimal digits are case-insensitive).
Note that unlike
.Xr rgbasm 5 ,
an octal
.Ql &
prefix is not supported, nor are
.Ql _
digit separators.
.Pp
Strings begin with a double quote, and end at the next (non-escaped) double quote.
Strings must not contain literal newline characters.
Most of the same character escapes as
.Xr rgbasm 5
are supported, specifically
.Ql \e\e ,
.Ql \e" ,
.Ql \en ,
.Ql \er ,
and
.Ql \et .
Other backslash escape sequences in
.Xr rgbasm 5
are only relevant to assembly code and do not apply in linker scripts.
.Ss Directives
.Bl -tag -width Ds
.It Including other files
.Ql Ic INCLUDE Ar path
acts as if the contents of the file at
.Ar path
were copy-pasted in place of the
.Ic INCLUDE
directive.
.Ar path
must be a string.
.It Specifying the active bank
The active bank can be set by specifying its type (memory region) and number.
The possible types are:
.Ic ROM0 , ROMX , VRAM , SRAM , WRAM0 , WRAMX , OAM ,
and
.Ic HRAM .
The bank number can be omitted from the types that only contain a single bank, which are:
.Ic ROM0 ,
.Ic ROMX No if Fl t No is passed to Xr rgblink 1 ,
.Ic VRAM No if Fl d No is passed to Xr rgblink 1 ,
.Ic WRAM0 ,
.Ic WRAMX No if Fl w No is passed to Xr rgblink 1 ,
.Ic OAM ,
and
.Ic HRAM .
.Pq Ic SRAM No is the only type that can never have its bank number omitted.
.Pp
After a bank specification, the
.Dq current address
is set to the last value it had for that bank.
If the bank has never been active thus far, the
.Dq current address
defaults to the beginning of the bank
.Pq e.g. Ad $4000 No for Ic ROMX No sections .
.Pp
Instead of giving a bank number, the keyword
.Ic FLOATING
can be used instead; this sets the type of the subsequent sections without binding them to a particular bank.
(If the type only allows a single bank, e.g.
.Ic ROM0 ,
then
.Ic FLOATING
is valid but redundant and has no effect.)
Since no particular section is active, the
.Dq current address
is made floating (as if by a
.Ql Ic FLOATING
directive), and
.Ic ORG
is not allowed.
.It Changing the current address
A bank must be active for any of these directives to be used.
.Pp
.Ql Ic ORG Ar addr
sets the
.Dq current address
to
.Ar addr .
This directive cannot be used to move the address backwards:
.Ar addr
must be greater than or equal to the
.Dq current address .
.Pp
.Ql Ic FLOATING
causes all sections between it and the next
.Ic ORG
or bank specification to be placed at addresses automatically determined by
.Nm .
.Pq It is, however, compatible with Ic ALIGN No below.
.Pp
.Ql Ic ALIGN Ar addr , Ar offset
increases the
.Dq current address
until it is aligned to the specified boundary (i.e. the
.Ar align
lowest bits of the address are equal to
.Ar offset ) .
If
.Ar offset
is omitted, it is implied to be 0.
For example, if the
.Dq current address
is $0007,
.Ql ALIGN 8
would set it to $0100, and
.Ql ALIGN 8 , 10
would set it to $000A.
.Pp
.Ql Ic DS Ar size
increases the
.Dq current address
by
.Ar size .
The gap is not allocated, so smaller floating sections can later be placed there.
.El
.Ss Section placement
A section can be placed simply by naming it (with a string).
Its bank is set to the active bank, and its address to the
.Dq current address .
Any constraints the section already possesses (whether from earlier in the linker script, or from the object files being linked) must be consistent with what the linker script specifies: the section's type must match, the section's bank number (if set) must match the active bank, etc.
In particular, if the section has an alignment constraint, the address at which it is placed by the linker script must obey that constraint; otherwise, an error will occur.
.Pp
After a section is placed, the
.Dq current address
is increased by the section's size.
This must not increase it past the end of the active memory region.
.Pp
The section must have been defined in the object files being linked, unless the section name is followed by the keyword
.Ic OPTIONAL .
.Sh EXAMPLES
.Bd -literal -offset indent
; This line contains only a comment
ROMX $F            ; start a bank
  "Some functions" ; a section name
  ALIGN 8          ; a directive
  "Some \e"array\e""

WRAMX 2            ; start another bank
  org $d123        ; another directive
  "Some variables"
.Ed
.Sh SEE ALSO
.Xr rgbasm 1 ,
.Xr rgbasm 5 ,
.Xr rgblink 1 ,
.Xr rgbfix 1 ,
.Xr rgbgfx 1 ,
.Xr gbz80 7 ,
.Xr rgbds 5 ,
.Xr rgbds 7
.Sh HISTORY
.Xr rgblink 1
was originally written by
.An Carsten S\(/orensen
as part of the ASMotor package, and was later repackaged in RGBDS by
.An Justin Lloyd .
It is now maintained by a number of contributors at
.Lk https://github.com/gbdev/rgbds .