Added old obsolete version of LOADER.SYSTEM in order to retain the history. This version implemented the BASIC warmstart/coldstart hooks and was therefore fully compatible with any DOS 3.3 binary running under ProDOS. However later the Apple2 C library startup code was extended to not rely on the BASIC hooks when running under ProDOS without BASIC.SYSTEM. Therefore the hook functionality became obsolete and was later removed. This limits LOADER.SYSTEM to cc65 binaries - but it surely wasn't used for anything else anyway ;-)

git-svn-id: svn://svn.cc65.org/cc65/trunk@5416 b7a2c559-68d2-44c3-8de9-860c34a00d81

targetutil/apple2/loader.txt

@@ -0,0 +1,85 @@
+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