.sections

Sections are a way to allow WLA DX to build up our ROM file for us, and throw away anything that is unused. This is useful for several reasons:

  • It allows us to include extra data/code in our source, and then have any parts that aren’t used be discarded at compile time. For example:
    • We might have several alternate fonts in our program, and WLA DX can discard any that aren’t being used.
    • We can have a set of useful functions we use in many projects; WLA DX can discard the code for any that aren’t being used.
  • It allows WLA DX to decide where to put our code and data automatically. This is very useful when we come to make larger programs that use paging.
  • It allows us to specify alignment, which can be useful for some coding tricks.
  • As a bonus, we get to define local labels.

If you are using sections then you should make sure that all of your code and data uses them, otherwise you may have problems when code or data gets overwritten.

You specify a section like this:

.section "SomeFunction" free
SomeFunction:
  ; ...
  ret
.ends

Between the .section and .ends directives is just regular code and directives, as before. We specify a section name between quotes. Here, I’ve named the section after the function that’s in it; however, section names have (almost) no restrictions on what characters you can use so you can be more descriptive if you want.

The last word on the line is almost always free. This tells WLA DX that we don’t care where it puts the contents of this section, so long as it is within the bank we have specified. We’ll come on to banking later; for now, we can think of this as saying it can go anywhere.

There are certain bits of code that have to go at a particular address - the boot code and interrupt handlers (like the pause button handler in Lesson 1). For these, instead of free we write force.

WLA DX notices the use of labels inside each section. If somewhere in our other code, we have

call SomeFunction

then WLA DX will know that we are using the contents of this section, so it will not discard it. If there are no such references, it will discard it. It also correctly handles the case where the only references are in sections that themselves will be discarded. In other words, it discards everything that is definitely not needed.

References are any usage of the label - whether it’s a call, jp, jr, ld, .dw, or anything else. (Note that jr into a different section is likely to break since WLA DX may place the sections too far apart - we have told it it can place them anywhere.)

force sections are never discarded. Therefore, the boot section is able to reference the main code and from there the references can be tracked as being used.

Finally, there are local labels. These are labels beginning with an underscore. These are only valid within the section, which means you can use labels with the same names in different sections without any errors. Any label that isn’t expected to be used anywhere else should either be an anonymous label or a local label. Local labels are naturally more descriptive than anonymous labels.


Lesson 2 | Using the VBlank for timing >