X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fapple2enh.sgml;h=215c6d384d44b977b4686a2be4c242ccfb9d44e4;hb=bb9aa7558f724445217afd7042cb3c3e9e248970;hp=6d0c8916cd50e65ec6f1245536e89117df41d96a;hpb=56fea8788f38112cc6207f3fc32731f9842a4b0a;p=cc65 diff --git a/doc/apple2enh.sgml b/doc/apple2enh.sgml index 6d0c8916c..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 @@ -243,8 +242,8 @@ 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 +If the cc65 program can be successfully linked as system program using the linker +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,16 +286,15 @@ 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> +<item>_auxtype <item>_dos_type -<item>drivecount -<item>drivelist +<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,8 +351,8 @@ you cannot do it, it just means that there's no help. <descrip> - <tag><tt/a2e.auxmem.emd/</tag> - Gives access to 47,5 KB RAM (190 pages of 256 bytes each) on an Extended + <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. Note that this driver doesn't check for the actual existence of the memory @@ -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> @@ -482,12 +479,12 @@ These are defined to be OpenApple + number key. <sect1>Interrupts<p> -The runtime for the enhanced Apple //e uses routines marked as <tt/.CONDES/ -type <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 url="ca65.html" -name="assembler manual">. +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 <url +url="ca65.html" name="assembler manual">. <sect1>DIO<p> @@ -495,36 +492,27 @@ 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 - <verb> - drive_id = slot * 16 + (drive - 1) * 128 - </verb> + <tscreen> + 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 _oserror value 82. + This condition is indicated by the <tt/_oserror/ value 82. </descrip><p> -<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