X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fatmos.sgml;h=3fd61abcfb16774f6bef3d5c9f05370cf15e1a04;hb=74455508314bc2b007e812ec5f9429496b9fbd5f;hp=82aef6c314e8078579b097f653a8fd77c7fad468;hpb=c3d93d259b65c51ed5ac8e6cd58327af908c9501;p=cc65 diff --git a/doc/atmos.sgml b/doc/atmos.sgml index 82aef6c31..3fd61abcf 100644 --- a/doc/atmos.sgml +++ b/doc/atmos.sgml @@ -1,12 +1,11 @@
- -Oric Atmos specific information for cc65 -<author>Ullrich von Bassewitz <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"><newline> -Stefan A. Haubenthal <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org"><newline> +<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>2013-01-08 <abstract> An overview over the Atmos runtime system as it is implemented for the cc65 C @@ -21,56 +20,74 @@ 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 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> +<sect1>Atmos-specific functions<p> -The functions listed below are special for the Atmos. See the <htmlurl +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> @@ -78,12 +95,12 @@ url="funcref.html" name="function reference"> for declaration and usage. 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> @@ -110,6 +127,9 @@ The names in the parentheses denote the symbols to be used for static linking of <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-228-200-3.tgi (atmos_228_200_3_tgi)/</tag> @@ -137,7 +157,10 @@ No extended memory drivers are currently available for the Atmos. <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> @@ -154,8 +177,8 @@ No mouse drivers are currently available for the Atmos. <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> @@ -166,13 +189,14 @@ No mouse 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> @@ -190,37 +214,57 @@ following functions (and a few others): <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/.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">. +feature in the <url url="ca65.html" name="assembler manual">. @@ -235,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> - - -