Oliver Schmidt updated the graphics drivers and part of the C library for the

Apple machines.


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

doc/apple2.sgml

@@ -35,25 +35,25 @@ more information.
 
 The standard binary output format generated by the linker for the
 Apple ][ target is a machine language program with a 4 byte DOS
-3.3 header. The standard load address is $800.
+3.3 header. The standard 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 = $4, file = %O;
+    HEADER: start = $0000, size = $0004, file = %O;
 </verb>
 
 to
 
 <verb>
-    HEADER: start = $0000, size = $4, file = "";
+    HEADER: start = $0000, size = $0004, file = "";
 </verb>
 
 in the linker configuration to have the linker remove it.
 
-Please note that there is a "Apple&nbsp;&rsqb;&lsqb; ProDOS 8 system program
-for loading binary programs" available in the cc65 User Contributions section.
+Please note that there is an 'Apple&nbsp;&rsqb;&lsqb; 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 Apple&nbsp;&rsqb;&lsqb; target.
 
@@ -62,8 +62,9 @@ program generated by the linker for the Apple&nbsp;&rsqb;&lsqb; target.
 <sect>Memory layout<p>
 
 In the standard setup, cc65 generated programs use the memory from
-&dollar;800 to &dollar;95FF, so 35.5K of memory are available. ROM calls are
-possible without further precautions.
+&dollar;803 to &dollar;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.
 
 Special locations:
 
@@ -77,6 +78,32 @@ Special locations:
   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")/.
+
+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 &dollar;D400 to &dollar;DFFF.
+Therefore the builtin linker configuration defines these 3KB as <tt/LC/ memory
+area for executable code.
+
+A plain vanilla DOS 3.3 doesn't make use of the Language Card at all. So you
+can change
+
+<verb>
+    LC: start = $D400, size = $0C00, define = yes;
+</verb>
+
+to
+
+<verb>
+    LC: start = $D000, size = $3000, define = yes;
+</verb>
+
+in the linker configuration to define the whole 12KB Language Card address
+space as memory area for executable code.
+
 
 
 <sect>Platform specific header files<p>
@@ -112,14 +139,19 @@ you cannot do it, it just means that there's no help.
 <descrip>
 
   <tag><tt/a2.lo.tgi/</tag>
-  This driver was written by Stefan Haubenthal. It features a resolution of
-  40&times;40 with 16 colors. At the bottom of the screen, 4 additional text
-  lines are available.
+  This driver features a resolution of 40&times;48 with 16 colors.
 
   <tag><tt/a2.hi.tgi/</tag>
-  This driver was written by Stefan Haubenthal. It features a resolution of
-  280&times;192 with 6 colors. Note that programs using this driver will have
-  to be linked with <tt/--start-addr $4000/ to reserve the first hires page.
+  This driver features a resolution of 280&times;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
+  <tt/--start-addr $6000/ to reserve both hires pages.
+  
+  In memory constrained situations the memory from &dollar;803 to &dollar;1FFF
+  can be made available to a program by executing <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.
 
 </descrip><p>
 
@@ -128,11 +160,12 @@ you cannot do it, it just means that there's no help.
 
 <descrip>
 
-  <tag><tt/a2.lc.emd/</tag>
-  Gives access to 12KB RAM (48 pages of 256 bytes each) on the
-  Apple&nbsp;II Language Card. The driver was contributed by Stefan Haubenthal.
-  Note that this driver is incompatible with any DOS using the Language
-  Card memory!
+  <tag><tt/a2.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
+  and that it doesn't check for ProDOS 8 RAM disk content!
 
 </descrip><p>
 
@@ -155,10 +188,13 @@ you cannot do it, it just means that there's no help.
   <tag><tt/a2.stdmou.mou/</tag>
   Driver for the AppleMouse&nbsp;II Card. Searches all Apple&nbsp;II slots
   for an AppleMouse&nbsp;II Card compatible firmware. The default bounding
-  box is &lsqb;0..279,0..191&rsqb;. Programs using this driver will have
-  to be linked with <tt/--start-addr $4000/ to reserve the first hires page
-  if they are intended to run on an Apple&nbsp;&rsqb;&lsqb; (in contrast to
-  an Apple&nbsp;//e).
+  box is &lsqb;0..279,0..191&rsqb;.
+  
+  Programs using this driver will have to be linked with <tt/--start-addr $4000/
+  to reserve the first hires page if they are intended to run on an
+  Apple&nbsp;&rsqb;&lsqb; (in contrast to an Apple&nbsp;//e) because the
+  AppleMouse&nbsp;II Card firmware writes to the hires page when initializing
+  on that machine.
 
   Note that the Apple&nbsp;&rsqb;&lsqb; default mouse callbacks support text
   mode only.
@@ -178,8 +214,8 @@ you cannot do it, it just means that there's no help.
   flow control because of a full buffer.
 
   The driver defaults to slot 2. Call <tt/ser_ioctl(0, &lt;slot&gt;)/ prior to
-  <tt/ser_open/ in order to select a different slot. <tt/ser_ioctl/ succeeds
-  for all Apple&nbsp;II slots, but <tt/ser_open/ fails with
+  <tt/ser_open()/ in order to select a different slot. <tt/ser_ioctl()/
+  succeeds for all Apple&nbsp;II slots, but <tt/ser_open()/ fails with
   <tt/SER_ERR_NO_DEVICE/ if there's no SSC firmware found in the selected slot.
 
 </descrip><p>
@@ -199,7 +235,7 @@ Command line arguments can be passed to <tt/main()/ after BLOAD. Since this is n
 supported by BASIC, the following syntax was chosen:
 
 <tscreen><verb>
-]CALL2048:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
+]CALL2051:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
 </verb></tscreen>
 
 <enum>
@@ -216,10 +252,11 @@ supported by BASIC, the following syntax was chosen:
 <sect1>Interrupts<p>
 
 The runtime for the Apple&nbsp;&rsqb;&lsqb; uses routines marked as <tt/.CONDES/
-type 2 for ProDOS 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">.
+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">.
 
 
 
@@ -235,7 +272,7 @@ name="uz@cc65.org">).
 <sect>License<p>
 
 This software is provided 'as-is', without any expressed or implied
-warranty.  In no event will the authors be held liable for any damages
+warranty. In no event will the authors be held liable for any damages
 arising from the use of this software.
 
 Permission is granted to anyone to use this software for any purpose,