Before you can start writing code, you must define a section. This tells the assembler what kind of information follows and, if it is code, where to put it.
This switches to the section called "CoolStuff" (or creates it if it doesn't already exist) and it defines it as a code section. All sections assembled at the same time that have the same name, type, etc, are considered to be the same one, and their code is put together in the object file generated by the assembler. All other sections must have a unique name, even in different source files, or the linker will treat it as an error.
Possible section types are as follows:
A ROM section. Mapped to memory at $0000–$3FFF (or $0000-$7FFF if tiny ROM mode is enabled in rgblink(1)).
A banked ROM section. Mapped to memory at $4000–$7FFF. Valid banks range from 1 to 511. Not available if tiny ROM mode is enabled in rgblink(1).
A banked video RAM section. Mapped to memory at $8000–$9FFF. Can only allocate memory, not fill it. Valid banks are 0 and 1 but bank 1 isn't available if DMG mode is enabled in rgblink(1).
A banked external (save) RAM section. Mapped to memory at $A000–$BFFF. Can only allocate memory, not fill it. Valid banks range from 0 to 15.
A general-purpose RAM section. Mapped to memory at $C000–$CFFF, or $C000-$DFFF if DMG mode is enabled in rgblink(1). Can only allocate memory, not fill it.
A banked general-purpose RAM section. Mapped to memory at $D000–$DFFF. Can only allocate memory, not fill it. Valid banks range from 1 to 7. Not available if DMG mode is enabled in rgblink(1).
An object attributes RAM section. Mapped to memory at $FE00-$FE9F. Can only allocate memory, not fill it.
A high RAM section. Mapped to memory at $FF80–$FFFE. Can only allocate memory, not fill it.
NOTE: If you use this method of allocating HRAM the assembler will NOT choose the short addressing mode in the LD instructions LD [$FF00+n8],A and LD A,[$FF00+n8] because the actual address calculation is done by the linker. If you find this undesirable you can use RSSET
/ RW instead or use the LDH [$FF00+n8],A and LDH A,[$FF00+n8] syntax instead. This forces the assembler to emit the correct instruction and the linker to check if the value is in the correct range.
A section is usually defined as a floating one, but the code can restrict where the linker can place it.
If a section is defined with no indications, it is a floating section. The linker will decide where to place it in the final binary and it has no obligation to follow any specific rules. The following example defines a section that can be placed anywhere in any ROMX bank:
If it is needed, the following syntax can be used to fix the base address of the section:
It won't, however, fix the bank number, which is left to the linker. If you also want to specify the bank you can do:
And if you only want to force the section into a certain bank, and not it's position within the bank, that's also possible:
In addition, you can specify byte alignment for a section. This ensures that the section starts at a memory address where the given number of least-significant bits are 0. This can be used along with BANK
, if desired. However, if an alignment is specified, the base address must be left unassigned. This can be useful when using DMA to copy data or when it is needed to align the start of an array to 256 bytes to optimize the code that accesses it.
SECTION "OAM Data",WRAM0,ALIGN; align to 256 bytes
SECTION "VRAM Data",ROMX,BANK,ALIGN; align to 16 bytes
HINT: If you think this is a lot of typing for doing a simple ORG
type thing you can quite easily write an intelligent macro (called ORG
for example) that uses @
for the section name and determines correct section type etc as arguments for SECTION
provide the interface to the section stack. PUSHS
will push the current section context on the section stack. POPS
can then later be used to restore it. Useful for defining sections in included files when you don't want to destroy the section context for the program that included your file. The number of entries in the stack is limited only by the amount of memory in your machine.
Sections can also be placed by using a linkerscript file. The format is described in rgblink(5)
. They allow the user to place floating sections in the desired bank in the order specified in the script. This is useful if the sections can't be placed at an address manually because the size may change, but they have to be together.