mirror of
https://github.com/gbdev/rgbds.git
synced 2025-11-20 10:12:06 +00:00
fd78a9ae83
Notable side effects: * Use the standard-conformant MSVC preproc * Add test for linker script INCLUDE * Improve wording of placement conflict errors * Fix errors from not newline-terminated files * Teach checkdiff about the linker script doc * Call linker script "commands" "directives" instead --------- Co-authored-by: Rangi42 <remy.oukaour+rangi42@gmail.com>
106 lines
3.1 KiB
Groff
106 lines
3.1 KiB
Groff
.\" SPDX-License-Identifier: MIT
|
|
.\"
|
|
.Dd March 28, 2021
|
|
.Dt RGBLINK 5
|
|
.Os
|
|
.Sh NAME
|
|
.Nm rgblink
|
|
.Nd linker script file format
|
|
.Sh DESCRIPTION
|
|
The linker script is an external file that allows the user to specify the order of sections at link time and in a centralized manner.
|
|
.Pp
|
|
A linker script consists of a series of bank declarations, each optionally followed by a list of section names (in double quotes) or directives.
|
|
All reserved keywords (bank types and directive names) are case-insensitive; all section names are case-sensitive.
|
|
.Pp
|
|
Any line can contain a comment starting with
|
|
.Ql \&;
|
|
that ends at the end of the line.
|
|
.Bd -literal -offset indent
|
|
; This line is a comment
|
|
ROMX $F ; start a bank
|
|
"Some functions" ; a section name
|
|
ALIGN 8 ; a directive
|
|
"Some array"
|
|
|
|
WRAMX 2 ; start another bank
|
|
org $d123 ; another directive
|
|
"Some variables"
|
|
.Ed
|
|
.Pp
|
|
Numbers can be in decimal or hexadecimal format
|
|
.Pq the prefix is Ql $ .
|
|
It is an error if any section name or directive is found before setting a bank.
|
|
.Pp
|
|
Files can be included by using the
|
|
.Ic INCLUDE
|
|
keyword, followed by a string with the path of the file that has to be included.
|
|
.Pp
|
|
The possible bank types are:
|
|
.Cm ROM0 , ROMX , VRAM , SRAM , WRAM0 , WRAMX , OAM
|
|
and
|
|
.Cm HRAM .
|
|
Unless there is a single bank, which can occur with types
|
|
.Cm ROMX , VRAM , SRAM
|
|
and
|
|
.Cm WRAMX ,
|
|
it is mandatory to specify a bank number after the type.
|
|
.Pp
|
|
Section names in double quotes support the same character escape sequences as strings in
|
|
.Xr rgbasm 5 ,
|
|
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 section names.
|
|
.Pp
|
|
When a new bank statement is found, sections found after it will be placed right from the beginning of that bank.
|
|
If 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.
|
|
.Pp
|
|
The only three directives are
|
|
.Ic ORG ,
|
|
.Ic ALIGN ,
|
|
and
|
|
.Ic DS :
|
|
.Bl -bullet
|
|
.It
|
|
.Ic ORG
|
|
sets the address in which new sections will be placed.
|
|
It can not be lower than the current address.
|
|
.It
|
|
.Ic ALIGN
|
|
will increase the address until it is aligned to the specified boundary
|
|
.Po it tries to set to 0 the number of bits specified after the directive:
|
|
.Ql ALIGN 8
|
|
will align to $100
|
|
.Pc .
|
|
.It
|
|
.Ic DS
|
|
will increase the address by the specified non-negative amount.
|
|
.El
|
|
.Pp
|
|
.Sy Note :
|
|
The bank, alignment, address and type of sections can be specified both in the source code and in the linker script.
|
|
For 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.
|
|
For example,
|
|
.Ql ALIGN[8]
|
|
in the source code is compatible with
|
|
.Ql ORG $F00
|
|
in the linker script.
|
|
.Sh SEE ALSO
|
|
.Xr rgbasm 1 ,
|
|
.Xr rgblink 1 ,
|
|
.Xr rgbfix 1 ,
|
|
.Xr rgbds 5 ,
|
|
.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
|
|
.Lk https://github.com/gbdev/rgbds .
|