<url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline>
<url url="mailto:polluks@sdf.lonestar.org" name="Stefan A. Haubenthal">,<newline>
<url url="mailto:greg.king5@verizon.net" name="Greg King">
-<date>2014-03-27
+<date>2015-01-09
<abstract>
An overview over the Atmos runtime system as it is implemented for the cc65 C
information.
+
<sect>Binary format<p>
The standard binary output format generated by the linker for the Atmos target
-is a machine language program with a 17 byte tape header including a cc65 tag.
-The standard load and autostart address is $500.
+is a machine language program with a one-line BASIC stub that jumps to the
+machine-language part through <tt/CALL/. It has one sacrificial byte attached
+to the end (a bug in the Oric ROM means that BASIC can put a variable on top
+of the last byte that was loaded). It has a 24-byte tape header. A file can
+be CLOADed as a BASIC program, and started by typing <tt/RUN/. The standard
+load address is $501.
+
<sect>Memory layout<p>
-In the standard setup, cc65 generated programs use the memory from
-$500 to $9800, so nearly 37K of memory (including the stack) is
+In the standard setup, cc65-generated programs use the memory from
+$0501 to $9800; so, nearly 37K of memory (including the stack) is
available. ROM calls are possible without further precautions.
+If your program needs more memory, and it won't use TGI graphics, then you can
+use the ld65 command-line option, <tt/-D __GRAB__=1/, when building the
+program, to include the graphics screen RAM. Then, nearly 44K of memory
+($0501 to $B400) is available.
+
Special locations:
<descrip>
<tag/Stack/
- The C runtime stack is located at $97FF and growing downwards.
+ The C runtime stack is located at $97FF (or $B3FF), and grows
+ downwards.
<tag/Heap/
- The C heap is located at the end of the program and grows towards the C
+ The C heap is located at the end of the program, and grows towards the C
runtime stack.
</descrip><p>
<descrip>
<tag><tt/VIA/</tag>
- Access to the VIA (versatile interface adapter) chip is available via the
+ Access to the VIA (Versatile Interface Adapter) chip is available via the
<tt/VIA/ variable. The structure behind this variable is explained in <tt/_6522.h/.
</descrip><p>
<sect1>Graphics drivers<p>
-The default drivers, <tt/tgi_stddrv (tgi_static_stddrv)/, point to <tt/atmos-240-200-2.tgi (atmos_240_200_2_tgi)/.
+The default drivers, <tt/tgi_stddrv (tgi_static_stddrv)/,
+point to <tt/atmos-240-200-2.tgi (atmos_240_200_2_tgi)/.
<descrip>
<descrip>
<tag><tt/atmos-pase.joy (atmos_pase_joy)/</tag>
- Supports two standard joysticks connected to the P.A.S.E. interface of the Atmos.
+ Supports two standard joysticks connected to a P.A.S.E. / Altai interface of the Atmos.
+
+ <tag><tt/atmos-ijk.joy (atmos_ijk_joy)/</tag>
+ Supports two standard joysticks connected to an IJK interface of the Atmos.
</descrip><p>
<sect1>Disk I/O<p>
-The existing library for the Atmos doesn't implement C file
-I/O. There are hacks for the <tt/read()/ and <tt/write()/ routines in
-place, which will make functions work that read from and write to <tt/stdout/
-(like <tt/printf()/). However, those functions have some shortcomings which
-won't be fixed, because they're going to be replaced anyway.
+The existing library for the Atmos doesn't implement C file I/O. There are
+hacks for the <tt/read()/ and <tt/write()/ routines in place, which will make
+functions work that read from <tt/stdin/ and write to <tt/stdout/ and
+<tt/stderr/ (such as <tt/printf()/). However, those functions have some
+shortcomings which won't be fixed, because they're going to be replaced
+anyway.
-To be more concrete, the limitation means that you cannot use any of the
+To be more concrete, that limitation means that you cannot use any of the
following functions (and a few others):
<itemize>
<sect1>Function keys<p>
-These are defined to be FUNCT + number key.
+They are defined to be FUNCT + a number key.
+
+
+<sect1>Capitals lock<p>
+
+The keyboard's "CAPS Lock" mode is turned off while the program is running.
+The previous mode (usually, CAPS Lock turned on [because Oric BASIC keywords
+must be UPPER-case]) is restored when the program stops.
<sect1>Passing arguments to the program<p>
supported directly by BASIC, the following syntax was chosen:
<tscreen><verb>
- CALL#500:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
+ RUN:REM arg1 " ARG2 IS QUOTED" ARG3 "" ARG5
</verb></tscreen>
<enum>
+<item>You must turn <tt/CAPS/ lock off (tap CTRL-T) when you want to type
+ lower-case arguments (but, <tt/RUN/ and <tt/REM/ must be UPPER-case).
<item>Arguments are separated by spaces.
<item>Arguments may be quoted.
<item>Leading and trailing spaces around an argument are ignored. Spaces within
</enum>
+<sect1>Automatic starting<p>
+
+Usually, a cc65-built program just will sit quietly in memory, after it is
+CLOADed. It waits for you to start it (by typing BASIC's <tt/RUN/ command).
+But, if you want to create a program that will start running immediately after
+it is loaded, then you can use the linker command-line option
+<tt/-D __AUTORUN__=$C7/.
+
+
<sect1>Interrupts<p>
The runtime for the Atmos uses routines marked as <tt/.INTERRUPTOR/ for