*********************************************************************
* IMPORTANT NOTE:                                                   *
*                                                                   *
* To build this example you will need PSYLINK version 2.50 or later *
*                                                                   *
* To debug under DOS you need DBUGSAT version 4.70 or later.        *
*                                                                   *
* The Windows debugger does not support overlay debugging for the   *
* Saturn.                                                           *
*********************************************************************

This example consists of a main program and 3 overlayed levels.
The example is only a shell to demonstrate how to achieve this.


There is a make file. To build the example, run psymake. (Make sure
your psyq.ini file is set up correctly with an entry under [psylink]
so the linker knows where your Sega libraries are.


Examine the map file produced (MAIN.MAP). This will show you
that the address for the three levels' code and data all overlap
in memory. It will also show you the addresses of the global
symbols, demonstrating that they are in the same memory area.


Warning: there is no automatic system for loading levels when
a routine is called. It is up to you to make sure that the
level's code and data is in memory before you call it.


Have a look at the file MAIN.LK.

Each level's code file is included in the linker script with a suffix
which is then placed in front of the name of every section in that file.
You can then locate those sections in the group created at the top of
the script to hold that overlay.

Groups l2 and l3 are specified as being 'over' l1. This tells the linker
that all these groups should be placed at the same memory address. The
linker allocates enough space in memory to hold the largest of the
groups. (When a smaller group is in memory the extra space will be
wasted.)

Each group also has a 'file' parameter. This tells the linker not to
write the code for the group into the standard output file. Instead
the linker writes the code as a block of pure binary data into the
file name specified.

If you examine the contents of your directory after building this example,
you will find the output file MAIN.CPE and also the files L1.BIN, L2.BIN
and L3.BIN which contain the data for each of the levels. These are the
files that the main program should load into memory in the load_level
routine.

Formerly, it was necessary to use a small piece of assembler code to
obtain the address of the overlay area for use in loading the binary
overlay code. However, versions of the linker after 2.50 generate labels
which can be used to refer to the ORG and OBJ addresses (and size) of
each group. A group called l1 will have labels created as follows:

        _l1_obj
        _l1_org
        _l1_size

to indicate the group's position and size. Within each group, each
section will also have labels, eg the .text section within group l1
would have the labels

        _l1_text_org
        _l1_text_obj
        _l1_text_size

generated by the linker. Obviously you can then refer to these from
within your C code as demonstrated in main.c

