Cleanup "Sections" section.

src/asm/rgbasm.5

@@ -63,76 +63,110 @@ like this:
 .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 @@ check if the value is in the correct range.
 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
+.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
-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:
 .Pp
@@ -161,15 +227,13 @@ bank:
     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 @@ position within the bank, that's also possible:
     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 @@ start of an array to 256 bytes to optimize the code that accesses it.
     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 example) that uses
 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 @@ 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.
-.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