<article>
-<title>Oric Atmos specific information for cc65
-<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
-Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org">
-<date>2005-07-17
+<title>Oric Atmos-specific information for cc65
+<author>
+<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>2015-01-09
<abstract>
An overview over the Atmos runtime system as it is implemented for the cc65 C
<sect>Overview<p>
This file contains an overview of the Atmos runtime system as it comes with the
-cc65 C compiler. It describes the memory layout, Atmos specific header files,
+cc65 C compiler. It describes the memory layout, Atmos-specific header files,
available drivers, and any pitfalls specific to that platform.
-Please note that Atmos specific functions are just mentioned here, they are
-described in detail in the separate <htmlurl url="funcref.html" name="function
+Please note that Atmos-specific functions are just mentioned 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.
+
<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>
-<sect>Platform specific header files<p>
+<sect>Platform-specific header files<p>
+
+Programs containing Atmos-specific code may use the <tt/atmos.h/ header file.
-Programs containing Atmos specific code may use the <tt/atmos.h/ header file.
+
+<sect1>Atmos-specific functions<p>
+
+The functions listed below are special for the Atmos. See the <url
+url="funcref.html" name="function reference"> for declaration and usage.
+
+<itemize>
+<item>atmos_load
+<item>atmos_save
+<item>atmos_explode
+<item>atmos_ping
+<item>atmos_shoot
+<item>atmos_tick
+<item>atmos_tock
+<item>atmos_zap
+</itemize>
<sect1>Hardware access<p>
The following pseudo variables declared in the <tt/atmos.h/ header file do allow
access to hardware located in the address space. Some variables are
-structures, accessing the struct fields will access the chip registers.
+structures; accessing the struct fields will access the chip registers.
<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>
<em>Note:</em> Since the Atmos doesn't have working disk I/O
(see <ref id="limitations" name="section "Limitations"">), the
available drivers cannot be loaded at runtime (so the term "loadable drivers"
-is somewhat misleading). Instead, the drivers have to be converted using the
-<htmlurl url="co65.html" name="co65 utility"> and statically linked. While
+is somewhat misleading). Instead, the drivers have to be statically linked. While
this may seem overhead, it has two advantages:
<enum>
at runtime with almost no effort.
</enum>
+The names in the parentheses denote the symbols to be used for static linking of the drivers.
<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)/.
+
<descrip>
- <tag><tt/atmos-240-200-2.tgi/</tag>
- This driver was written by Stefan Haubenthal. It features a resolution of
- 240×200 with 2 colors.
+ <tag><tt/atmos-228-200-3.tgi (atmos_228_200_3_tgi)/</tag>
+ This driver was written by Greg King and Stefan Haubenthal.
+ It features a resolution of 228×200 with a palette of two colors that
+ can be chosen from the Atmos's eight colors. The driver supports a third
+ palette-"color" that actually "flips" the pixel (it becomes the other color)
+ that is on the screen under the graphics cursor.
+
+ <tag><tt/atmos-240-200-2.tgi (atmos_240_200_2_tgi)/</tag>
+ This driver was written by Stefan Haubenthal and Greg King.
+ It features a resolution of 240×200 with black and white colors.
+ It is the default graphics driver for the Atmos.
</descrip><p>
<descrip>
- <tag><tt/atmos-pase.joy/</tag>
- Supports two standard joysticks connected to the P.A.S.E. interface of the Atmos.
+ <tag><tt/atmos-pase.joy (atmos_pase_joy)/</tag>
+ Supports two standard joysticks connected to a P.A.S.E. / Altai interface of the Atmos.
-</descrip><p>
+ <tag><tt/atmos-ijk.joy (atmos_ijk_joy)/</tag>
+ Supports two standard joysticks connected to an IJK interface of the Atmos.
+</descrip><p>
<sect1>Mouse drivers<p>
<descrip>
- <tag><tt/atmos-acia.ser/</tag>
+ <tag><tt/atmos-acia.ser (atmos_acia_ser)/</tag>
Driver for the Telestrat integrated serial controller and the Atmos with a
serial add-on.
- Note that because of the peculiarities of the 6551 chip together with the
- use of the NMI, transmits are not interrupt driven, and the transceiver
+ Note that, because of the peculiarities of the 6551 chip, together with the
+ use of the NMI, transmits are not interrupt driven; and, the transceiver
blocks if the receiver asserts flow control because of a full buffer.
-
+
</descrip><p>
<sect1>Disk I/O<p>
-The existing library for the Atmos doesn't implement C file
-I/O. There is one hack for the <tt/write()/ routine in
-place, which will make functions work that write to <tt/stdout/
-(like <tt/printf()/). However, this function has some shortcomings which
-won't be fixed, because it's 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, this 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>
<sect>Other hints<p>
+
<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>
-Command line arguments can be passed to <tt/main()/. Since this is not
-supported by BASIC, the following syntax was chosen:
+Command-line arguments can be passed to <tt/main()/. Since that is not
+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
a quoted argument are allowed.
-<item>The first argument passed to <tt/main/ is the program name.
+<item>The first argument passed to <tt/main()/ is the program name.
<item>A maximum number of 10 arguments (including the program name) are
supported.
</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/.CONDES/ type 2 for
+The runtime for the Atmos uses routines marked as <tt/.INTERRUPTOR/ for
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">.
-
-
-
-<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">).
+feature in the <url url="ca65.html" name="assembler manual">.
</enum>
</article>
-
-
-
projects / cc65 / blobdiff