git.sur5r.net Git - cc65/blob - doc/apple2.sgml

   1 <!doctype linuxdoc system>
   2
   3 <article>
   4
   5 <title>Apple&nbsp;&rsqb;&lsqb; specific information for cc65
   6 <author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
   7 <date>2003-12-16
   8
   9 <abstract>
  10 An overview over the Apple&nbsp;&rsqb;&lsqb; runtime system as it is
  11 implemented for the cc65 C compiler.
  12 </abstract>
  13
  14 <!-- Table of contents -->
  15 <toc>
  16
  17 <!-- Begin the document -->
  18
  19 <sect>Overview<p>
  20
  21 This file contains an overview of the Apple&nbsp;&rsqb;&lsqb; runtime system
  22 as it comes with the cc65 C compiler. It describes the memory layout,
  23 Apple&nbsp;&rsqb;&lsqb; specific header files, available drivers, and any
  24 pitfalls specific to that platform.
  25
  26 Please note that Apple&nbsp;&rsqb;&lsqb; specific functions are just mentioned
  27 here, they are described in detail in the separate <htmlurl url="funcref.html"
  28 name="function reference">. Even functions marked as "platform dependent" may
  29 be available on more than one platform. Please see the function reference for
  30 more information.
  31
  32
  33
  34 <sect>Binary format<p>
  35
  36 The standard binary output format generated by the linker for the
  37 Apple&nbsp;&rsqb;&lsqb; target is a machine language program with a 4 byte DOS
  38 3.3 header. The standard load address is &dollar;800.
  39
  40 The DOS header is in its own segment named <tt/EXEHDR/. If you don't want the
  41 header for some reason, you can change
  42
  43 <verb>
  44     HEADER: start = $0000, size = $4, file = %O;
  45 </verb>
  46
  47 to
  48
  49 <verb>
  50     HEADER: start = $0000, size = $4, file = "";
  51 </verb>
  52
  53 in the linker configuration to have the linker remove it.
  54
  55 Please note that there is a "Apple&nbsp;&rsqb;&lsqb; ProDOS 8 system program
  56 for loading binary programs" available in the cc65 User Contributions section.
  57 It adds all benefits of a ProDOS 8 system program to the standard binary
  58 program generated by the linker for the Apple&nbsp;&rsqb;&lsqb; target.
  59
  60
  61
  62 <sect>Memory layout<p>
  63
  64 In the standard setup, cc65 generated programs use the memory from
  65 &dollar;800 to &dollar;95FF, so 35.5K of memory are available. ROM calls are
  66 possible without further precautions.
  67
  68 Special locations:
  69
  70 <descrip>
  71   <tag/Stack/
  72   The C runtime stack is located at HIMEM and grows downwards, regardless of
  73   how your linker config file is setup.
  74
  75   <tag/Heap/
  76   The C heap is located at the end of the program and grows towards the C
  77   runtime stack.
  78 </descrip><p>
  79
  80
  81
  82 <sect>Platform specific header files<p>
  83
  84 Programs containing Apple&nbsp;&rsqb;&lsqb; specific code may use the
  85 <tt/apple2.h/ header file.
  86
  87
  88 <sect1>Apple&nbsp;&rsqb;&lsqb; specific functions<p>
  89
  90 The functions listed below are special for the Apple&nbsp;&rsqb;&lsqb;. See
  91 the <htmlurl url="funcref.html" name="function reference"> for declaration and
  92 usage.
  93
  94 <itemize>
  95 <item>_dos_type
  96 <item>get_ostype
  97 </itemize>
  98
  99
 100 <sect1>Hardware access<p>
 101
 102 There's currently no support for direct hardware access. This does not mean
 103 you cannot do it, it just means that there's no help.
 104
 105
 106
 107 <sect>Loadable drivers<p>
 108
 109
 110 <sect1>Graphics drivers<p>
 111
 112 <descrip>
 113
 114   <tag><tt/a2.lo.tgi/</tag>
 115   This driver was written by Stefan Haubenthal. It features a resolution of
 116   40&times;40 with 16 colors. At the bottom of the screen, 4 additional text
 117   lines are available.
 118
 119   <tag><tt/a2.hi.tgi/</tag>
 120   This driver was written by Stefan Haubenthal. It features a resolution of
 121   280&times;192 with 6 colors. Note that programs using this driver will have
 122   to be linked with <tt/--start-addr $4000/ to reserve the first hires page.
 123
 124 </descrip><p>
 125
 126
 127 <sect1>Extended memory drivers<p>
 128
 129 <descrip>
 130
 131   <tag><tt/a2.lc.emd/</tag>
 132   Gives access to 12KB RAM (48 pages of 256 bytes each) on the
 133   Apple2 language card. The driver was contributed by Stefan Haubenthal.
 134   Note that this driver is incompatible with any DOS using the language
 135   card memory!
 136
 137 </descrip><p>
 138
 139
 140 <sect1>Joystick drivers<p>
 141
 142 <descrip>
 143
 144   <tag><tt/a2.stdjoy.joy/</tag>
 145   Supports up to two standard analog joysticks connected to the game port of
 146   the Apple&nbsp;&rsqb;&lsqb;.
 147
 148 </descrip><p>
 149
 150
 151 <sect1>Mouse drivers<p>
 152
 153 Currently no drivers available (in fact, the API for loadable mouse drivers
 154 does not exist).
 155
 156
 157 <sect1>RS232 device drivers<p>
 158
 159 <descrip>
 160
 161   <tag><tt/a2.ssc.ser/</tag>
 162   Driver for the Apple2 Super Serial Card. Supports up to 19200 baud,
 163   hardware flow control (RTS/CTS) and interrupt driven receives. Note
 164   that because of the peculiarities of the 6551 chip transmits are not
 165   interrupt driven, and the transceiver blocks if the receiver asserts
 166   flow control because of a full buffer.
 167
 168 </descrip><p>
 169
 170
 171
 172 <sect>Limitations<p>
 173
 174
 175
 176 <sect>Other hints<p>
 177
 178
 179 <sect1>Passing arguments to the program<p>
 180
 181 Command line arguments can be passed to <tt/main()/ after BLOAD. Since this is not
 182 supported by BASIC, the following syntax was chosen:
 183
 184 <tscreen><verb>
 185 ]CALL2048:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
 186 </verb></tscreen>
 187
 188 <enum>
 189 <item>Arguments are separated by spaces.
 190 <item>Arguments may be quoted.
 191 <item>Leading and trailing spaces around an argument are ignored. Spaces within
 192       a quoted argument are allowed.
 193 <item>The first argument passed to <tt/main/ is the program name.
 194 <item>A maximum number of 10 arguments (including the program name) are
 195       supported.
 196 </enum>
 197
 198
 199 <sect1>Interrupts<p>
 200
 201 The runtime for the Apple&nbsp;&rsqb;&lsqb; uses routines marked as <tt/.CONDES/
 202 type 2 for ProDOS interrupt handlers. Such routines must be written as simple
 203 machine language subroutines and will be called automatically by the interrupt
 204 handler code when they are linked into a program. See the discussion of the
 205 <tt/.CONDES/ feature in the <htmlurl url="ca65.html" name="assembler manual">.
 206
 207
 208
 209 <sect>Bugs/Feedback<p>
 210
 211 If you have problems using the library, if you find any bugs, or if you're
 212 doing something interesting with it, I would be glad to hear from you. Feel
 213 free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
 214 name="uz@cc65.org">).
 215
 216
 217
 218 <sect>License<p>
 219
 220 This software is provided 'as-is', without any expressed or implied
 221 warranty.  In no event will the authors be held liable for any damages
 222 arising from the use of this software.
 223
 224 Permission is granted to anyone to use this software for any purpose,
 225 including commercial applications, and to alter it and redistribute it
 226 freely, subject to the following restrictions:
 227
 228 <enum>
 229 <item>  The origin of this software must not be misrepresented; you must not
 230         claim that you wrote the original software. If you use this software
 231         in a product, an acknowledgment in the product documentation would be
 232         appreciated but is not required.
 233 <item>  Altered source versions must be plainly marked as such, and must not
 234         be misrepresented as being the original software.
 235 <item>  This notice may not be removed or altered from any source
 236         distribution.
 237 </enum>
 238
 239 </article>