SECTION


Before you can start writing code you must define a section. This tells the assembler what kind of data follows and if it is code where to put it.

SECTION   "CoolStuff",CODE

This switches to the section called "CoolStuff" (or creates it if it doesn't already exits) and it defines it as a code section. All sections within a sourcefile must be identified by a unique name.

Section types
Name Function
CODE A code section. The linker decides where to put this. For the Gameboy it also decides which bank to put it in except #0 (the HOME bank).
DATA Really just a synonym for CODE.
BSS This section is for variables. For the Gameboy it will be placed where the Gameboy RAM is.
HOME Gameboy ONLY: A code section that will be placed in Gameboy bank #0.
VRAM Gameboy ONLY: This section is for allocating VRAM and will be placed where the Gameboy VRAM is.
HRAM Gameboy ONLY: This section is for allocating variables in the high RAM area ($FF80-$FFFE) and will be placed there. Suggested by Jens Ch. Restemeier. NOTE WELL: if you use this method of allocating HRAM the assembler will NOT choose the short addressingmode in the LD instruction because the actual address calculation is done by the linker! If you find this undesirable you can use RSSET/RB/RW/RQ instead or use the LDIO mnemonic. The address calculation is then done by the assembler.
ALIGNED_CODE Like a code section but which will have an address that will be aligned to some value that you specify.
ALIGNED_DATA A synonym for ALIGNED_CODE
ALIGNED_HOME Like ALIGNED_CODE but will be placed in Gameboy bank #0
CONTAINED_CODE A code section that will be guaranteed not to have any of its contents pass an address that is congruent modulo n where n is the argument specified at declaration.
CONTAINED_DATA A synonym for CONTAINED_CODE
CONTAINED_HOME Like CONTAINED_CODE but will be placed in Gameboy bank #0

Due to quite a lot of emails requesting an ORG directive you can now add an address to the sectiontype for the Gameboy:

SECTION   "CoolStuff",HOME[$1234]

This will force the section to address $1234. This also works with the other sectiontypes. For CODE/DATA sections the linker will then place the section in any bank at the address you specify. If you also want to specify the bank you can do:

SECTION   "CoolStuff",DATA[$4567],BANK[3]

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:

SECTION   "CoolStuff",CODE,BANK[7]

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 sectionname and determines correct sectiontype etc as arguments for SECTION

If you want an aligned section you use the ALIGNED_* section types. The example below will create a section aligned to an even 256 bytes so the address will be on the form $xx00:

SECTION   "CoolStuff",ALIGNED_HOME[$100]

For ALIGNED_CODE/ALIGNED_DATA you can also specify BANK:

SECTION   "CoolStuff",ALIGNED_CODE[$123],BANK[7]

NOTE: Aligned sections must have an alignment specified

You can use CONTAINED_* section types to have short code or data that is contained in an interval that does not cross the point where the address is congruent modulo n where n is the argument specified at declaration. To see how this is useful, take the example below:

SECTION   "CopyThisData",CONTAINED_DATA[$100]
Label1:	db "This string is contained between Label1 and Label2"
Label2:

In this example CONTAINED_DATA[$100] will guarantee that the most significant 8 bits of the addresses of Label1 and Label2 are the same. This property will enable the Game Boy coder to safely copy the string while just by comparing the lower byte of the source pointer, and thus saving clock cycles.
Obviously contained sections have to be smaller than the containment interval specified.
As with (ALIGNED_) CODE and DATA, CONTAINED_CODE/DATA can also have a BANK specified.

NOTE: Contained sections must have a containment interval specified

See also:



Last updated 18 July 1997 by Carsten Sorensen

Last updated 3 September 2008 by lai