cc65/targetutil/apple2/loader.txt

Apple][ ProDOS 8 system program for loading binary programs (Oliver Schmidt)
============================================================================


Background
----------

The ordinary way to run a binary program using ProDOS 8 is to load BASIC.SYSTEM
first and enter then from the BASIC prompt 'BRUN MYPROGRAM' or '- MYPROGRAM'.

Using LOADER.SYSTEM instead to run a binary program has four advantages:

1. The binary program can be selected directly from the ProDOS 8 dispatcher.

2. The size of BASIC.SYSTEM is 21 blocks while the size of LOADER.SYSTEM is
   only 1 block. The benefits are:

   - Running a binary program with LOADER.SYSTEM is faster.

   - If the only use of BASIC.SYSTEM is to run binary programs it can be removed
     altogether thus freeing up precious floppy disk space.
     
3. BASIC.SYSTEM can load binary programs into the range $0800-$9600 (35,5 kB)
   while LOADER.SYSTEM can load much larger binary programs into the range
   $0800-$BB00 (44,75 kB).

4. If a binary program needs to reclaim the memory used by BASIC.SYSTEM it has
   to update the system bit map after being loaded and on exit it must call the
   ProDOS 8 dispatcher itself. But when run by LOADER.SYSTEM the binary program
   automatically has access to the range $0800-$BF00 (45,75 kB) just by checking
   HIMEM. On exit the binary program simply jumps to DOSWARM or DOSCOLD as usual
   which are set up by LOADER.SYSTEM to call the ProDOS 8 dispatcher (or reboot
   the computer - see below).


Usage
-----

Obviously LOADER.SYSTEM has to be told which binary program to run. As the
ProDOS 8 dispatcher has no notion of system program parameters the ordinary
approach would have been to make LOADER.SYSTEM bring up yet another menu to
select the binary program to run.

But to allow to select the binary program directly from the ProDOS 8 dispatcher
anyway LOADER.SYSTEM detects the path to the binary program from its own path
by just removing the '.SYSTEM' from its name. So if you want to run the binary
program MYPROGRAM you'll need a copy of LOADER.SYSTEM in the same directory
being renamed to MYPROGRAM.SYSTEM.

This means you'll end up with a copy of LOADER.SYSTEM for every binary program
you intend to run it. But as LOADER.SYSTEM is a seedling file using up only a
single block in the ProDOS 8 file system this should be no issue.


Build
-----

In case you want to build 'loader.system' from the source code yourself you can
do so using the following commands:

ca65 loader.s
ld65 -C loader.cfg -o loader.system loader.o

If you want LOADER.SYSTEM to reboot the computer on exit of the binary program
instead of calling the ProDOS 8 dispatcher then use the following commands:

ca65 -D REBOOT loader.s
ld65 -C loader.cfg -o loader.system loader.o


Installation
------------

The file 'loader.system' as generated by the cc65 linker does NOT have a 4-byte
address/length header as it is generated for ordinary Apple][ binaries. This is
because the start address for ProDOS 8 system programs is fixed to $2000.

The recommended way to transfer 'loader.system' from your native file system to
a ProDOS 8 file system disk image is to use AppleCommander which is available at
http://applecommander.sourceforge.net/

If you want to put the file 'loader.system' onto a disk image 'mydisk.dsk' as
system program MYPROGRAM.SYSTEM you can do so using the following command:

java -jar ac.jar -p mydisk.dsk MYPROGRAM.SYSTEM sys < loader.system