Updated LOADER.SYSTEM to the current version targeted at cc65 binaries only.

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

targetutil/apple2/loader.txt

@@ -1,55 +1,55 @@
-Apple][ ProDOS 8 system program for loading binary programs (Oliver Schmidt)
-============================================================================
+LOADER.SYSTEM - an Apple][ ProDOS 8 loader for cc65 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'.
+Apple][ ProDOS 8 system programs (filetype SYS) are always loaded into memory
+starting at location $2000. This poses the problem of how to make efficient
+use of the memory in the range $0800-$2000. The usual approach of relocation
+has two downsides:
+- Relocating e.g. 30 kB from $2000-$9800 to $0800-$8000 takes a considerable
+  amount of time.
+- Really large programs just don't fit into memory when loaded starting at
+  location $2000.
 
-Using LOADER.SYSTEM instead to run a binary program has four advantages:
+The relocation can be eliminated by loading the major part(s) of the program
+from disk right to the final location by a rather small system program.
 
-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).
+LOADER.SYSTEM is such a small program. In fact it's so small that it fits into
+a single block in the ProDOS 8 file system making it a so-called seedling file,
+which are loaded really fast. LOADER.SYSTEM can load cc65 programs into memory
+anywhere in the range $0800-$BB00 (44,75 kB).
 
 
 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.
+Link the cc65 program to the start address $0803 (or any other address) and
+store it as binary program (filetype BIN). This is in fact no different from
+a binary program to be run by BASIC.SYSTEM's BRUN command in the usual way.
 
-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
+If however the cc65 program isn't run by BASIC.SYSTEM but is rather run by
+LOADER.SYSTEM then it behaves like a system program which means:
+- It uses memory up to the ProDOS 8 system global page located at $BF00.
+- It supports the ProDOS 8 startup file mechanism (mapped to argv[1]).
+- It quits to the ProDOS 8 dispatcher.
+
+Obviously LOADER.SYSTEM has to be told which cc65 program to run. Unfortunately
+the ProDOS 8 dispatcher has no notion of system program parameters so the usual
+approach would have been to make LOADER.SYSTEM bring up yet another menu to
+select the cc65 program to run.
+
+But to allow to select the cc65 program directly from the ProDOS 8 dispatcher
+anyway LOADER.SYSTEM detects the path to the cc65 program from its own path by
+just removing the '.SYSTEM' from its name. So if you want to run the cc65
 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.
+This means you will end up with a copy of LOADER.SYSTEM for every cc65 program
+to be run by it. But as LOADER.SYSTEM is a ProDOS 8 seedling file using up only
+a single block in the ProDOS 8 file system this should be no issue.
 
 
 Build
@@ -61,19 +61,14 @@ 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 file 'loader.system' as generated by the cc65 linker with the command above
+does NOT include the 4-byte address/length header that is generated for Apple][
+programs by default. This is because ProDOS 8 system programs are always loaded
+into memory starting at location $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