X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fatmos.sgml;h=3fd61abcfb16774f6bef3d5c9f05370cf15e1a04;hb=8590de5cf3515d7df156a5d470ad06bd68f97555;hp=887115df71e3e58673b6c07eb211837736e71f43;hpb=63c53b8021c31b76e6e4233d3a351ba06f0eb1ae;p=cc65 diff --git a/doc/atmos.sgml b/doc/atmos.sgml index 887115df7..3fd61abcf 100644 --- a/doc/atmos.sgml +++ b/doc/atmos.sgml @@ -1,11 +1,11 @@
- -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"> <abstract> An overview over the Atmos runtime system as it is implemented for the cc65 C @@ -20,58 +20,87 @@ compiler. <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 14 byte tape header. 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> @@ -83,8 +112,7 @@ structures, accessing the struct fields will access the chip registers. <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> @@ -94,15 +122,27 @@ this may seem overhead, it has two advantages: 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> @@ -116,11 +156,13 @@ No extended memory drivers are currently available for the Atmos. <descrip> - <tag><tt/atmos-pase.joy/</tag> - Supports two standard joystick 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> @@ -130,7 +172,16 @@ No mouse drivers are currently available for the Atmos. <sect1>RS232 device drivers<p> -No serial drivers are currently available for the Atmos. +<descrip> + + <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 + blocks if the receiver asserts flow control because of a full buffer. + +</descrip><p> @@ -138,13 +189,14 @@ No serial drivers are currently available for the Atmos. <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> @@ -162,42 +214,57 @@ following functions (and a few others): <sect>Other hints<p> -<!--<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: +<sect1>Function keys<p> + +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 that is not +supported directly by BASIC, the following syntax was chosen: <tscreen><verb> - CALL#500:REM,ARG1," ARG2", ARG 3,, 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>--> +</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">. @@ -212,17 +279,14 @@ including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions: <enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. </enum> </article> - - -