ref: 29d2fc6ebc4611728f750b28089a67b80483334a
parent: efe4599bd8c57a0741e0db704e73592c6b8bc4a1
author: Anthony J. Bentley <anthony@anjbe.name>
date: Fri Jul 27 21:30:30 EDT 2018
Cleanup "Sections" section.
--- a/src/asm/rgbasm.5
+++ b/src/asm/rgbasm.5
@@ -63,76 +63,110 @@
.Ed
.Pp
.Ss Sections
+.Ic SECTION Ar name , type
+.Pp
+.Ic SECTION Ar name , type , options
+.Pp
+.Ic SECTION Ar name , type Ns Bo Ar addr Bc
+.Pp
+.Ic SECTION Ar name , type Ns Bo Ar addr Bc , Ar options
+.Pp
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.
.Pp
-.Bd -literal -offset indent
- SECTION "CoolStuff",ROMX
-.Ed
-.Pp
-This switches to the section called
-.Dq CoolStuff
-(or creates it if it doesn't already exist) and 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.
+.Ar name
+is a string enclosed in double quotes and can be a new name or the name of an
+existing section.
+All sections assembled at the same time that have the same name and type are
+considered to be the same section, 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.
.Pp
-Possible section types are as follows:
+Possible section
+.Ar type Ns s
+are as follows:
.Pp
.Bl -tag
-.It Sy ROM0
+.It Cm ROM0
A ROM section.
-Mapped to memory at $0000–$3FFF (or $0000-$7FFF if tiny ROM mode is enabled in
+.Ar addr
+can range from $0000–$3FFF (or $0000–$7FFF if tiny ROM mode is enabled in
.Xr rgblink 1 ) .
-.It Sy ROMX
+.It Cm ROMX
A banked ROM section.
-Mapped to memory at $4000–$7FFF.
-Valid banks range from 1 to 511.
+.Ar addr
+can range from $4000–$7FFF.
+.Ar bank
+can range from 1 to 511.
Not available if tiny ROM mode is enabled in
.Xr rgblink 1 .
-.It Sy VRAM
+.It Cm VRAM
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
+.Ar addr
+can range from $8000–$9FFF.
+.Ar bank
+can be 0 or 1 but bank 1 is unavailable if DMG mode is enabled in
.Xr rgblink 1 .
-.It Sy SRAM
+Memory in this section can only be allocated with
+.Sy DS ,
+not filled with data.
+.It Cm SRAM
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.
-.It Sy WRAM0
+.Ar addr
+can range from $A000–$BFFF.
+.Ar bank
+can range from 0 to 15.
+Memory in this section can only be allocated with
+.Sy DS ,
+not filled with data.
+.It Cm WRAM0
A general-purpose RAM section.
-Mapped to memory at $C000–$CFFF, or $C000-$DFFF if DMG mode is enabled in
+.Ar addr
+can range from $C000–$CFFF, or $C000–$DFFF if DMG mode is enabled in
.Xr rgblink 1 .
-Can only allocate memory, not fill it.
-.It Sy WRAMX
+Memory in this section can only be allocated with
+.Sy DS ,
+not filled with data.
+.It Cm WRAMX
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.
+.Ar addr
+can range from $D000–$DFFF.
+.Ar bank
+can range from 1 to 7.
+Memory in this section can only be allocated with
+.Sy DS ,
+not filled with data.
Not available if DMG mode is enabled in
.Xr rgblink 1 .
-.It Sy OAM
+.It Cm OAM
An object attributes RAM section.
-Mapped to memory at $FE00-$FE9F.
-Can only allocate memory, not fill it.
-.It Sy HRAM
+.Ar addr
+can range from $FE00-$FE9F.
+Memory in this section can only be allocated with
+.Sy DS ,
+not filled with data.
+.It Cm HRAM
A high RAM section.
-Mapped to memory at $FF80–$FFFE.
-Can only allocate memory, not fill it.
+.Ar addr
+can range from $FF80–$FFFE.
+Memory in this section can only be allocated with
+.Sy DS ,
+not filled with data.
.Pp
-NOTE: If you use this method of allocating HRAM the assembler will NOT choose
-the short addressing mode in the LD instructions
+.Sy Note :
+If you use this method of allocating HRAM the assembler will
+.Em not
+choose the short addressing mode in the LD instructions
.Sy LD [$FF00+n8],A
and
.Sy LD A,[$FF00+n8]
because the actual address calculation is done by the linker.
If you find this undesirable you can use
-.Ic RSSET No / Ic RB No / Ic RW
+.Ic RSSET , RB ,
+or
+.Ic RW
instead or use the
.Sy LDH [$FF00+n8],A
and
@@ -143,17 +177,49 @@
This optimization can be disabled by passing the
.Fl L
flag to
-.Sy rgbasm
-as explained in
.Xr rgbasm 1 .
.El
.Pp
-A section is usually defined as a floating one, but the code can restrict where
-the linker can place it.
+.Ar option Ns s are comma separated and may include:
+.Bl -tag
+.It Cm BANK Ns Bq Ar bank
+Specify which
+.Ar bank
+for the linker to place the section.
+.It Cm ALIGN Ns Bq Ar align
+Place the section at an address whose
+.Ar align
+least‐significant bits are zero.
+It is a syntax error to use this option with
+.Ar addr .
+.El
.Pp
-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.
+If
+.Bq Ar addr
+is not specified, the section is considered
+.Dq floating ;
+the linker will automatically calculate an appropriate address for the section.
+Similarly, if
+.Cm BANK Ns Bq Ar bank
+is not specified, the linker will automatically find a bank with enough space.
+.Pp
+Sections can also be placed by using a linkerscript file.
+The format is described in
+.Xr 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.
+.Pp
+Section examples:
+.Bd -literal -offset indent
+ SECTION "CoolStuff",ROMX
+.Ed
+.Pp
+This switches to the section called
+.Dq CoolStuff
+(or creates it if it doesn't already exist) and defines it as a code section.
+.Pp
The following example defines a section that can be placed anywhere in any ROMX
bank:
.Pp
@@ -161,15 +227,13 @@
SECTION "CoolStuff",ROMX
.Ed
.Pp
-If it is needed, the following syntax can be used to fix the base address of the
-section:
+If it is needed, the the base address of the section can be specified:
.Pp
.Bd -literal -offset indent
SECTION "CoolStuff",ROMX[$4567]
.Ed
.Pp
-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:
+An example with a fixed bank:
.Pp
.Bd -literal -offset indent
SECTION "CoolStuff",ROMX[$4567],BANK[3]
@@ -182,14 +246,8 @@
SECTION "CoolStuff",ROMX,BANK[7]
.Ed
.Pp
-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
-.Ic 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
+Alignment examples:
+one use could be 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.
.Pp
.Bd -literal -offset indent
@@ -198,8 +256,9 @@
SECTION "VRAM Data",ROMX,BANK[2],ALIGN[4] ; align to 16 bytes
.Ed
.Pp
-HINT: If you think this is a lot of typing for doing a simple
-.Ic ORG
+.Sy Hint :
+If you think this is a lot of typing for doing a simple
+.Dq org
type thing you can quite easily write an intelligent macro (called
.Ic ORG
for example) that uses
@@ -207,11 +266,12 @@
for the section name and determines
correct section type etc as arguments for
.Ic SECTION .
-.Pp
+.Ss Section Stack
.Ic POPS
and
.Ic PUSHS
provide the interface to the section stack.
+.Pp
.Ic PUSHS
will push the current section context on the section stack.
.Ic POPS
@@ -220,15 +280,6 @@
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.
-.Pp
-Sections can also be placed by using a linkerscript file.
-The format is described in
-.Xr 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.
-.Pp
.Sh SYMBOLS
.Pp
.Ss Symbols