X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fapple2enh.sgml;h=215c6d384d44b977b4686a2be4c242ccfb9d44e4;hb=bb9aa7558f724445217afd7042cb3c3e9e248970;hp=075811236efa7695db193c305cb7754d3ab0bf1a;hpb=1c77d3a6f0c3b99ea7f496c3c158075113b7603b;p=cc65 diff --git a/doc/apple2enh.sgml b/doc/apple2enh.sgml index 075811236..215c6d384 100644 --- a/doc/apple2enh.sgml +++ b/doc/apple2enh.sgml @@ -3,8 +3,8 @@
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 +<author><url url="mailto:ol.sc@web.de" name="Oliver Schmidt"> +<date>2014-04-10 <abstract> An overview over the enhanced Apple //e runtime system as it is @@ -24,7 +24,7 @@ enhanced Apple //e specific header files, available drivers, and any pitfalls specific to that platform. Please note that enhanced Apple //e specific functions are just mentioned -here, they are described in detail in the separate <htmlurl url="funcref.html" +here, they are described in detail in the separate <url url="funcref.html" name="function reference">. Even functions marked as "platform dependent" may be available on more than one platform. Please see the function reference for more information. @@ -45,7 +45,7 @@ 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 +<ref id="apple-sys-cfg" 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/. @@ -81,19 +81,19 @@ cc65 runtime system takes care of actually moving the code into the Language Card. The amount of memory available in the Language Card for generated code depends -on the chosen <htmlurl url="apple2enh-4.html" name="linker configuration">. +on the chosen <ref id="link-configs" name="linker configuration">. -<sect>Linker configurations<p> +<sect>Linker configurations<label id="link-configs"><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 ld65 linker comes with a default config file for the enhanced Apple //e, +which is used via <tt/-t apple2enh/. The apple2enh package comes with additional secondary linker config files, which -are used via <tt/-C <configfile>/. +are used via <tt/-t apple2enh -C <configfile>/. -<sect1>builtin config file<p> +<sect1>default config file (<tt/apple2enh.cfg/)<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 @@ -138,7 +138,7 @@ vanilla DOS 3.3 doesn't make use of the Language Card at all. </descrip><p> -<sect1><tt/apple2enh-system.cfg/<p> +<sect1><tt/apple2enh-system.cfg/<label id="apple-sys-cfg"><p> Configuration for a system program running on ProDOS 8. @@ -159,7 +159,7 @@ Configuration for a system program running on ProDOS 8. </descrip><p> -<sect1><tt/apple2enh-loader.cfg/<p> +<sect1><tt/apple2enh-loader.cfg/<label id="apple-load-cfg"><p> Configuration optimized for a binary program running on ProDOS 8 without BASIC.SYSTEM. Intended to be used with <bf/LOADER.SYSTEM - an @@ -231,10 +231,9 @@ range. 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). +<ref id="apple-load-cfg" name="apple2enh-loader.cfg"> with start address +$803 and load it with the targetutil LOADER.SYSTEM. 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 @@ -244,7 +243,7 @@ example the program <tt/MYPROG/ is loaded by <tt/MYPROG.SYSTEM/. <sect1>Heap<p> If the cc65 program can be successfully linked as system program using the linker -configuration <htmlurl url="apple2enh-4.html#ss4.3" name="apple2enh-system.cfg"> but +configuration <ref id="apple-sys-cfg" 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()/. @@ -287,7 +286,7 @@ Programs containing enhanced Apple //e specific code may use the <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 +the <url url="funcref.html" name="function reference"> for declaration and usage. <itemize> @@ -296,7 +295,6 @@ usage. <item>_filetype <item>get_ostype <item>rebootafterexit -<item>rootdir <item>ser_apple2_slot <item>textframe <item>textframexy @@ -314,18 +312,20 @@ you cannot do it, it just means that there's no help. <sect>Loadable drivers<p> +The names in the parentheses denote the symbols to be used for static linking of the drivers. + <sect1>Graphics drivers<p> <descrip> - <tag><tt/a2e.lo.tgi/</tag> + <tag><tt/a2e.lo.tgi (a2e_lo_tgi)/</tag> This driver features a resolution of 40×48 with 16 colors. The function <tt/tgi_apple2_mix()/ allows to activate 4 lines of text. The function clears the corresponding area at the bottom of the screen. - <tag><tt/a2e.hi.tgi/</tag> + <tag><tt/a2e.hi.tgi (a2e_hi_tgi)/</tag> This driver features a resolution of 280×192 with 8 colors and two hires pages. Note that programs using this driver will have to be linked with <tt/--start-addr $4000/ to reserve the first hires page or with @@ -351,7 +351,7 @@ you cannot do it, it just means that there's no help. <descrip> - <tag><tt/a2e.auxmem.emd/</tag> + <tag><tt/a2e.auxmem.emd (a2e_auxmem_emd)/</tag> Gives access to 47.5 KB RAM (190 pages of 256 bytes each) on an Extended 80-Column Text Card. @@ -365,7 +365,7 @@ you cannot do it, it just means that there's no help. <descrip> - <tag><tt/a2e.stdjoy.joy/</tag> + <tag><tt/a2e.stdjoy.joy (a2e_stdjoy_joy)/</tag> Supports up to two standard analog joysticks connected to the game port of the enhanced Apple //e. @@ -376,7 +376,7 @@ you cannot do it, it just means that there's no help. <descrip> - <tag><tt/a2e.stdmou.mou/</tag> + <tag><tt/a2e.stdmou.mou (a2e_stdmou_mou)/</tag> Driver for the AppleMouse II Card. Searches all Apple II slots for an AppleMouse II Card compatible firmware. The default bounding box is [0..279,0..191]. @@ -391,7 +391,7 @@ you cannot do it, it just means that there's no help. <descrip> - <tag><tt/a2e.ssc.ser/</tag> + <tag><tt/a2e.ssc.ser (a2e_ssc_ser)/</tag> Driver for the Apple II Super Serial Card. Supports up to 19200 baud, hardware flow control (RTS/CTS) and interrupt driven receives. Note that because of the peculiarities of the 6551 chip transmits are not @@ -421,9 +421,8 @@ BASIC.SYSTEM) there are some limitations for DOS 3.3: <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. + are in general not functional as they depend on disk file I/O. Therefore the statically + linked drivers have to be used instead. <tag/Interrupts/ There's no <tt/interruptor/ support. Any attempt to use it yields the message @@ -440,13 +439,11 @@ BASIC.SYSTEM) there are some limitations for DOS 3.3: <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. + textcolor(), bgcolor() and 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. + cursor() has no effect. </descrip><p> @@ -486,7 +483,7 @@ The runtime for the enhanced Apple //e uses routines marked as <tt/.INTERRUPTOR/ for ProDOS 8 interrupt handlers. Such routines must be written as simple machine language subroutines and will be called automatically by the interrupt handler code when they are linked into a -program. See the discussion of the <tt/.CONDES/ feature in the <htmlurl +program. See the discussion of the <tt/.CONDES/ feature in the <url url="ca65.html" name="assembler manual">. @@ -495,19 +492,19 @@ url="ca65.html" name="assembler manual">. <descrip> <tag/Drive ID/ - 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 + The function <url url="dio.html#s1" name="dio_open()"> has the single + parameter <tt/device/ to identify the device to be opened. Therefore an Apple II slot and drive pair is mapped to that <tt/drive_id/ according to the formula <tscreen> - drive_id = slot * 16 + (drive - 1) * 128 + device = slot + (drive - 1) * 8 </tscreen> - so that for example slot 6 drive 2 is mapped to <tt/drive_id/ 224. + so that for example slot 6 drive 2 is mapped to <tt/device/ 14. <tag/Sector count/ - The function <htmlurl url="dio-3.html" name="dio_query_sectcount()"> returns + The function <url url="dio.html#s3" name="dio_query_sectcount()"> returns the correct sector count for all ProDOS 8 disks. However for any non-ProDOS 8 disk it simply always returns 280 (which is only correct for a 140 KB disk). This condition is indicated by the <tt/_oserror/ value 82. @@ -516,15 +513,6 @@ url="ca65.html" name="assembler manual">. -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - <sect>License<p> This software is provided 'as-is', without any expressed or implied