Directives are commands to the assembler. That means WLA DX for us. They are used to tell it how to do things, and also what to do, for pretty much all the cases except actual code.

Directives are easy to spot because they all have a dot in front of their names. They are all well documented in the WLA DX documentation.

Here are some of the most useful ones:

Memory layout

  • .org and .bank tell WLA DX exactly where the output should be placed in the file.
  • .memorymap tells WLA DX where the ROM and RAM appear from the CPU's point of view.
  • .rombankmap tells WLA DX how the ROM file is structured, in terms of mapping.
  • .section and .slot let us pass the decisions on where to place code and data, and how to discard unused parts, to WLA DX.
  • .ramsection allows us to structure our memory usage in a flexible way that results in debugging symbols.

Data definition

  • .db, .dsb, .dw and .dsw let us specify raw data in our source file.
  • .dbsin, .dbcos and .dbrnd (and their .dwXXX equivalents) let us get WLA DX to generate us some data.
  • .incbin lets us import external data from a file.
  • .struct and .dstruct let you have structured data (with multiple instances) in a clean way.
  • .enum can be useful for producing names for things like an object state, similarly to how they are used in C/C++/C#/Java/etc. (They can be used for memory management too but that has drawbacks.)

System-specific helpers

WLA DX supports many CPUs and consoles, and it has helper directives to make sure the resulting file is valid for that system. For the Master System, the main one we use is .sdsctag, which does the following:

  • Inserts all the necessary data to make the resulting file pass the BIOS checks, so it will run on a system with a BIOS.
  • Inserts the special SDSC tag which lets you include the title of the program, your name, the version number and an arbitrary comment; emulators and ROM management tools can then display this.

Conditional inclusion

If there are parts of your source that you want to sometimes exclude from the result - as in, pretend the code or data was not there in the source at all - you can use the various .if directives. These are similar to #ifdefs in C/C++.

Macros

Macros let you insert things into your source based on parameters or external data. They can be complicated but they are sometimes very useful. I will include some later in the tutorial.


< Numbers | Lesson 1 | Labels >