X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fatmos.sgml;h=9e61fbd1c0e04fa1804fb1397fe46068882f82aa;hb=53df4da8e89f22ea815be947ff4f600a8d9ed8c5;hp=921b1164582a485f08d3cac898232824290eba8c;hpb=be6c70e74fd6caaab278c870b4f4c660557df605;p=cc65 diff --git a/doc/atmos.sgml b/doc/atmos.sgml index 921b11645..9e61fbd1c 100644 --- a/doc/atmos.sgml +++ b/doc/atmos.sgml @@ -2,11 +2,12 @@
-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>2014-03-27 +<date>2015-01-09 <abstract> An overview over the Atmos runtime system as it is implemented for the cc65 C @@ -31,27 +32,39 @@ 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> @@ -89,7 +102,7 @@ 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> @@ -116,7 +129,8 @@ 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)/. +The default drivers, <tt/tgi_stddrv (tgi_static_stddrv)/, +point to <tt/atmos-240-200-2.tgi (atmos_240_200_2_tgi)/. <descrip> @@ -145,7 +159,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> @@ -174,13 +191,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 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> @@ -201,7 +219,14 @@ following functions (and a few others): <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> @@ -210,10 +235,12 @@ 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 @@ -224,6 +251,15 @@ supported directly by BASIC, the following syntax was chosen: </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