X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fapple2enh.sgml;h=8b603e285f44e5b33df75dfea4e11aa90c244cf1;hb=bc26bd50972dcd991b3be3c2c1b887aeb2628c78;hp=7fcae15238c38119e00cd0cb7a14dc8b124ac128;hpb=feae688346d03cbd571fb945b43e5671ad3cda8a;p=cc65 diff --git a/doc/apple2enh.sgml b/doc/apple2enh.sgml index 7fcae1523..8b603e285 100644 --- a/doc/apple2enh.sgml +++ b/doc/apple2enh.sgml @@ -2,9 +2,9 @@
-enhanced Apple //e specific information for cc65 -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>2003-12-16 +<title>Enhanced Apple //e specific information for cc65 +<author>Oliver Schmidt, <htmlurl url="mailto:ol.sc@web.de" name="ol.sc@web.de"> +<date>2009-10-07 <abstract> An overview over the enhanced Apple //e runtime system as it is @@ -33,42 +33,32 @@ more information. <sect>Binary format<p> -The standard binary output format generated by the linker for the -enhanced Apple //e target is a machine language program with a 4 byte DOS -3.3 header. The standard load address is $803. +The standard binary file format generated by the linker for the +enhanced Apple //e target is a binary program with a 4 byte DOS 3.3 header +containing the load address and load length. The default load address is +$803. -The DOS header is in its own segment named <tt/EXEHDR/. If you don't want the -header for some reason, you can change - -<verb> - HEADER: start = $0000, size = $0004, file = %O; -</verb> - -to - -<verb> - HEADER: start = $0000, size = $0004, file = ""; -</verb> - -in the linker configuration to have the linker remove it. - -Please note that there is an 'Apple ][ ProDOS 8 system program -for loading binary programs' available in the cc65 User Contributions section. -It adds all benefits of a ProDOS 8 system program to the standard binary -program generated by the linker for the enhanced Apple //e target. +<bf/AppleCommander 1.3.5/ or later (available at <url +url="http://applecommander.sourceforge.net/">) includes the option <tt/-cc65/ +that allows to put binary files with a DOS 3.3 header onto disk images +containing DOS 3.3 as well as ProDOS 8. +For ProDOS 8 system programs the load address is fixed to $2000 so there +is no need for a header. Thus the linker configuration +<htmlurl url="apple2enh-4.html#ss4.3" name="apple2enh-system.cfg"> for those programs +omits the DOS 3.3 header. The right AppleCommander option to put system files +without a header on a ProDOS 8 disk image is <tt/-p/. <sect>Memory layout<p> In the standard setup, cc65 generated programs use the memory from -$803 to $95FF, so 35.5KB of RAM are available. While running -<tt/main()/ the Language Card bank 2 is enabled for read access. However while -running module constructors/destructors the Language Card is disabled. +$803 to $95FF, so 35.5 KB of RAM are available. Special locations: <descrip> + <tag/Stack/ The C runtime stack is located at HIMEM and grows downwards, regardless of how your linker config file is setup. @@ -76,33 +66,215 @@ Special locations: <tag/Heap/ The C heap is located at the end of the program and grows towards the C runtime stack. + </descrip><p> -Enabling the Language Card allows to use it as additional memory for executable -code. Actually doing so requires either to compile code with the option -<tt/--code-name HIGHCODE/ or to use <tt/#pragma codeseg ("HIGHCODE")/. +While running <tt/main()/ the Language Card bank 2 is enabled for read access. +However while running module constructors/destructors the Language Card is disabled. -The amount of memory available in the Language Card for executable code depends -on the chosen program environment. A plain vanilla ProDOS 8 doesn't actually -use the Language Card bank 2 memory from $D400 to $DFFF. -Therefore the builtin linker configuration defines these 3KB as <tt/LC/ memory -area for executable code. +Enabling the Language Card allows to use it as additional memory for cc65 +generated code. However code is never automatically placed there. Rather code +needs to be explicitly placed in the Language Card either per file by compiling +with <tt/--code-name HIGHCODE/ or per function by enclosing in <tt/#pragma +code-name (push, "HIGHCODE")/ and <tt/#pragma code-name (pop)/. In either case the +cc65 runtime system takes care of actually moving the code into the Language +Card. -A plain vanilla DOS 3.3 doesn't make use of the Language Card at all. So you -can change +The amount of memory available in the Language Card for generated code depends +on the chosen <htmlurl url="apple2enh-4.html" name="linker configuration">. -<verb> - LC: start = $D400, size = $0C00, define = yes; -</verb> -to -<verb> - LC: start = $D000, size = $3000, define = yes; -</verb> +<sect>Linker configurations<p> + +The ld65 linker comes with a builtin config file for the enhanced Apple //e, +which is used via <tt/-t apple2enh/ (and displayed via <tt/--dump-config apple2enh/). +The apple2enh package comes with additional secondary linker config files, which +are used via <tt/-C <configfile>/. + + +<sect1>builtin config file<p> + +Default configuration optimized for a binary program running on ProDOS 8 with +BASIC.SYSTEM. A plain vanilla ProDOS 8 doesn't actually use the Language Card +bank 2 memory from $D400 to $DFFF. + +<descrip> + + <tag><tt/RAM:/ Main memory area</tag> + From $803 to $95FF (35.5 KB) + + <tag><tt/LC:/ Language Card memory area</tag> + From $D400 to $DFFF (3 KB) + + <tag><tt/STARTADDRESS:/ Program start address</tag> + Variable (default: $803) + + <tag><tt/HEADER:/ Binary file header</tag> + DOS 3.3 header (address and length) + +</descrip><p> + + +<sect1><tt/apple2enh-dos33.cfg/<p> + +Configuration optimized for a binary program running on DOS 3.3. A plain +vanilla DOS 3.3 doesn't make use of the Language Card at all. + +<descrip> + + <tag><tt/RAM:/ Main memory area</tag> + From $803 to $95FF (35.5 KB) + + <tag><tt/LC:/ Language Card memory area</tag> + From $D000 to $FFFF (12 KB) + + <tag><tt/STARTADDRESS:/ Program start address</tag> + Variable (default: $803) + + <tag><tt/HEADER:/ Binary file header</tag> + DOS 3.3 header (address and length) + +</descrip><p> + + +<sect1><tt/apple2enh-system.cfg/<p> + +Configuration for a system program running on ProDOS 8. + +<descrip> + + <tag><tt/RAM:/ Main memory area</tag> + From $2000 to $BEFF (39.75 KB) + + <tag><tt/LC:/ Language Card memory area</tag> + From $D400 to $DFFF (3 KB) + + <tag><tt/STARTADDRESS:/ Program start address</tag> + Fixed ($2000) + + <tag><tt/HEADER:/ Binary file header</tag> + None + +</descrip><p> + + +<sect1><tt/apple2enh-loader.cfg/<p> + +Configuration optimized for a binary program running on ProDOS 8 without +BASIC.SYSTEM. Intended to be used with <bf/LOADER.SYSTEM - an +Apple ][ ProDOS 8 loader for cc65 programs/, which is available +in the cc65 User Contributions section. + +A program loaded by LOADER.SYSTEM works like a ProDOS 8 system program but +isn't tied to the start adress $2000. Thus with the default start +address $800 the main memory area is increased by 6 KB. + +<descrip> + + <tag><tt/RAM:/ Main memory area</tag> + From $800 to $BEFF (45.75 KB) + + <tag><tt/LC:/ Language Card memory area</tag> + From $D400 to $DFFF (3 KB) + + <tag><tt/STARTADDRESS:/ Program start address</tag> + Variable (default: $800) + + <tag><tt/HEADER:/ Binary file header</tag> + DOS 3.3 header (address and length) + +</descrip><p> + + +<sect1><tt/apple2enh-reboot.cfg/<p> + +Configuration optimized for a binary program running on ProDOS 8 without +BASIC.SYSTEM. Intended to be used with <bf/LOADER.SYSTEM - an +Apple ][ ProDOS 8 loader for cc65 programs/ (see above) together +with the function <tt/rebootafterexit()/. + +If a ProDOS 8 system program doesn't quit to the ProDOS 8 dispatcher but rather +reboots the machine after exit then a plain vanilla ProDOS 8 doesn't make use of +the Language Card bank 2 at all. + +This setup makes nearly 50 KB available to a cc65 program - on a 64 KB machine! + +<descrip> + + <tag><tt/RAM:/ Main memory area</tag> + From $800 to $BEFF (45.75 KB) + + <tag><tt/LC:/ Language Card memory area</tag> + From $D000 to $DFFF (4 KB) + + <tag><tt/STARTADDRESS:/ Program start address</tag> + Variable (default: $800) + + <tag><tt/HEADER:/ Binary file header</tag> + DOS 3.3 header (address and length) + +</descrip><p> + + + +<sect>ProDOS 8 system programs<p> + +ProDOS 8 system programs are always loaded to the start adress $2000. +For cc65 programs this means that the 6 KB from $800 to $2000 are +by default unused. There are however several options to make use of that memory +range. + + +<sect1>LOADER.SYSTEM<p> + +The easiest (and for really large programs in fact the only) way to have a cc65 +program use the memory from $800 to $2000 is to link it as binary +(as opposed to system) program using the linker configuration +<htmlurl url="apple2enh-4.html#ss4.4" name="apple2enh-loader.cfg"> with start address +$800 and load it with <bf/LOADER.SYSTEM - an Apple ][ +ProDOS 8 loader for cc65 programs/. The program then works like a system program +(i.e. quits to the ProDOS dispatcher). + +Using LOADER.SYSTEM is as simple as copying it to the ProDOS 8 directory of the +program to load under name <program>.SYSTEM as a system program. For +example the program <tt/MYPROG/ is loaded by <tt/MYPROG.SYSTEM/. + + +<sect1>Heap<p> + +If the cc65 program can be successully linked as system program using the linker +configuration <htmlurl url="apple2enh-4.html#ss4.3" name="apple2enh-system.cfg"> but +uses the heap either explicitly or implicitly (i.e. by loading a driver) then +the memory from $800 to $2000 can be added to the heap by calling +<tt/_heapadd ((void *) 0x0800, 0x1800);/ at the beginning of <tt/main()/. + + +<sect1>ProDOS 8 I/O buffers<p> + +ProDOS 8 requires for every open file a page-aligned 1 KB I/O buffer. By default +these buffers are allocated by the cc65 runtime system on the heap using +<tt/posix_memalign()/. While this is generally the best solution it means quite +some overhead for (especially rather small) cc65 programs which do open files +but don't make use of the heap otherwise. + +The apple2enh package comes with the alternative ProDOS 8 I/O buffer allocation +module <tt/apple2enh-iobuf-0800.o/ which uses the memory between $800 and +the program start address for the 1 KB I/O buffers. For system programs (with +start address $2000) this results in up to 6 I/O buffers and thus up to 6 +concurrently open files. + +While using <tt/_heapadd()/ as described in the section above together with the +default I/O buffer allocation basically yields the same placement of I/O buffers +in memory the primary benefit of <tt/apple2enh-iobuf-0800.o/ is a reduction in code +size - and thus program file size - of more than 1400 bytes. -in the linker configuration to define the whole 12KB Language Card address -space as memory area for executable code. +Using <tt/apple2enh-iobuf-0800.o/ is as simple as placing it on the linker command +line like this: + +<tscreen><verb> +cl65 -t apple2enh -C apple2enh-system.cfg myprog.c apple2enh-iobuf-0800.o +</verb></tscreen> @@ -112,7 +284,7 @@ Programs containing enhanced Apple //e specific code may use the <tt/apple2enh.h/ header file. -<sect1>enhanced Apple //e specific functions<p> +<sect1>Enhanced Apple //e specific functions<p> The functions listed below are special for the enhanced Apple //e. See the <htmlurl url="funcref.html" name="function reference"> for declaration and @@ -120,9 +292,11 @@ usage. <itemize> <item>_dos_type -<item>_textframe -<item>_textframexy <item>get_ostype +<item>rebootafterexit +<item>textframe +<item>textframexy +<item>videomode </itemize> @@ -150,7 +324,7 @@ you cannot do it, it just means that there's no help. <tt/--start-addr $6000/ to reserve both hires pages. In memory constrained situations the memory from $803 to $1FFF - can be made available to a program by executing <tt/_heapadd ((void *) 0x0803, 0x17FD);/ + can be made available to a program by calling <tt/_heapadd ((void *) 0x0803, 0x17FD);/ at the beginning of <tt/main()/. Doing so is beneficial even if the program doesn't use the the heap explicitly because loading the driver (and in fact already opening the driver file) uses the heap implicitly. @@ -221,6 +395,54 @@ you cannot do it, it just means that there's no help. <sect>Limitations<p> +<sect1>DOS 3.3<p> + +Although the standard binaries generated by the linker for the enhanced Apple //e +generally run both on DOS 3.3 (with Applesoft BASIC) and on ProDOS 8 (with +BASIC.SYSTEM) there are some limitations for DOS 3.3: + +<descrip> + + <tag>Disk File I/O</tag> + There's no disk file I/O support. Any attempt to use it yields an error with + <tt/errno/ set to <tt/ENOSYS/. This implicitly means that loadable drivers + are in general not functional as they depend on disk file I/O. However they + may be converted to statically linked drivers using the co65 object-file + converter. + + <tag/Interrupts/ + There's no <tt/interruptor/ support. Any attempt to use it yields the message + 'Failed to alloc interrupt' on program startup. This implicitly means that + <tt/a2e.stdmou.mou/ and <tt/a2e.ssc.ser/ are not functional as they depend on + interrupts. + +</descrip><p> + + +<sect1>DIO<p> + +Although <htmlurl url="dio.html" name="DIO"> generally works with all ProDOS 8 +devices, the function <htmlurl url="dio-3.html" name="dio_query_sectcount()"> +simply always return 280 (which is only correct for a 140 KB disk). + + +<sect1>Direct console I/O<p> + +<descrip> + + <tag/Color/ + The enhanced Apple //e has no color text mode. Therefore the functions + <htmlurl url="funcref-205.html" name="textcolor()">, + <htmlurl url="funcref-68.html" name="bgcolor()"> and + <htmlurl url="funcref-69.html" name="bordercolor()"> have no effect. + + <tag/Cursor/ + The enhanced Apple //e has no hardware cursor. Therefore the function + <htmlurl url="funcref-88.html" name="cursor()"> has no effect. + +</descrip><p> + + <sect>Other hints<p> @@ -260,6 +482,24 @@ discussion of the <tt/.CONDES/ feature in the <htmlurl url="ca65.html" name="assembler manual">. +<sect1>DIO<p> + +The function <htmlurl url="dio-1.html" name="dio_open()"> has the single parameter +<tt/drive_id/ to identify the drive to be opened. Therefore an Apple II +slot and drive pair is mapped to that <tt/drive_id/ according to the formula + +<verb> + drive_id = (slot * 2) + (drive - 1) +</verb> + +so that for example slot 6 drive 1 is mapped to <tt/drive_id/ 12. + +The function <htmlurl url="dio-1.html" name="dio_open()"> succeeds only if a +formatted disk is present in the drive. However intentionally no check is +performed on the presence of a ProDOS 8 disk. Therefore access to all standard +16-sector disks (as for instance DOS 3.3) is possible. + + <sect>Bugs/Feedback<p>