diff --git a/doc/Makefile b/doc/Makefile index fb91a7dae..8cf6d1952 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -8,6 +8,7 @@ SGML = apple2.sgml \ ar65.sgml \ atari.sgml \ + atmos.sgml \ c128.sgml \ c16.sgml \ c64.sgml \ @@ -28,6 +29,7 @@ SGML = apple2.sgml \ ld65.sgml \ library.sgml \ lynx.sgml \ + nes.sgml \ plus4.sgml \ vic20.sgml diff --git a/doc/atmos.sgml b/doc/atmos.sgml new file mode 100644 index 000000000..c11cc5b7d --- /dev/null +++ b/doc/atmos.sgml @@ -0,0 +1,228 @@ + + +
+ +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 + +<abstract> +An overview over the Atmos runtime system as it is implemented for the cc65 C +compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<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, +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 +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. + + +<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 +available. ROM calls are possible without further precautions. + +Special locations: + +<descrip> + <tag/Stack/ + The C runtime stack is located at $97FF and growing downwards. + + <tag/Heap/ + 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> + +Programs containing Atmos specific code may use the <tt/atmos.h/ header file. + + +<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. + +<descrip> + + <tag><tt/VIA/</tag> + 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> + + + +<sect>Loadable drivers<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 +this may seem overhead, it has two advantages: + +<enum> +<item>The interface is identical to the one used for other platforms + and to the one for the Atmos once it has disk I/O. +<item>Once disk I/O is available, existing code can be changed to load drivers + at runtime with almost no effort. +</enum> + + + +<sect1>Graphics drivers<p> + +<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. + +</descrip><p> + + +<sect1>Extended memory drivers<p> + +No extended memory drivers are currently available for the Atmos. + + +<!--<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/atmos-pase.joy/</tag> + Supports two standard joystick connected to the P.A.S.E. interface of the Atmos. + +</descrip><p>--> + + + +<sect1>Mouse drivers<p> + +No mouse drivers are currently available for the Atmos. + + +<sect1>RS232 device drivers<p> + +No serial drivers are currently available for the Atmos. + + + +<sect>Limitations<label id="limitations"><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. + +To be more concrete, this limitation means that you cannot use any of the +following functions (and a few others): + +<itemize> +<item>fclose +<item>fopen +<item>fread +<item>fprintf +<item>fputc +<item>fscanf +<item>fwrite +<item>... +</itemize> + + + +<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: + +<tscreen><verb> + CALL#500:REM,ARG1," ARG2", ARG 3,, ARG5, ... +</verb></tscreen> + +<enum> +<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>A maximum number of 10 arguments (including the program name) are + supported. +</enum>--> + + +<sect1>Interrupts<p> + +The runtime for the Atmos uses routines marked as <tt/.CONDES/ type 2 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">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +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. +</enum> + +</article> + + + diff --git a/doc/index.sgml b/doc/index.sgml index 18d006f57..97dfa7cf0 100644 --- a/doc/index.sgml +++ b/doc/index.sgml @@ -94,6 +94,9 @@ Main documentation page, contains links to other available stuff. <tag><htmlurl url="atari.html" name="atari.html"></tag> Topics specific to the Atari 8 bit machines. + <tag><htmlurl url="atmos.html" name="atmos.html"></tag> + Topics specific to the Oric Atmos. + <tag><htmlurl url="c128.html" name="c128.html"></tag> Topics specific to the Commodore 128. @@ -109,6 +112,9 @@ Main documentation page, contains links to other available stuff. <tag><htmlurl url="lynx.html" name="lynx.html"></tag> Topics specific to the Atari Lynx Game Console. + <tag><htmlurl url="nes.html" name="nes.html"></tag> + Topics specific to the Nintendo Entertainment System. + <tag><htmlurl url="pet.html" name="pet.html"></tag> Topics specific to the Commodore PET machines. diff --git a/doc/nes.sgml b/doc/nes.sgml new file mode 100644 index 000000000..a3ac79a68 --- /dev/null +++ b/doc/nes.sgml @@ -0,0 +1,182 @@ +<!doctype linuxdoc system> + +<article> + +<title>Nintendo Entertainment System 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 + +<abstract> +An overview over the NES runtime system as it is implemented for the +cc65 C compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the NES runtime system as it comes +with the cc65 C compiler. It describes the memory layout, NES specific header +files, available drivers, and any pitfalls specific to that platform. + +Please note that NES specific functions are just mentioned here, they are +described in detail in the separate <htmlurl 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 NES target +is a machine language program with an INES cartridge header. It is of course +possible to change this behaviour by using a modified startup file and linker +config. + +<sect>Memory layout<p> + +cc65 generated programs with the default setup run with the I/O area and a +CHR bank enabled, which gives a usable memory range of $8000 - $FFF3. +All boot ROM entry points may be called directly without additional code. + +Special locations: + +<descrip> + <tag/Text screen/ + The text screen is located at VRAM $2000. + + <tag/Stack/ + The C runtime stack is located at $7FFF and growing downwards. + + <tag/Heap/ + 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> + +Programs containing NES specific code may use the <tt/nes.h/ header file. + + +<sect1>NES specific functions<p> + +<itemize> +<item>waitvblank +</itemize> + + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/nes.inc/ include file do +allow access to hardware located in the address space. + +<descrip> + + <tag><tt/PPU/</tag> + The <tt/PPU/ defines allow access to the PPU chip. + + <tag><tt/APU/</tag> + The <tt/APU/ defines allow access to the APU chip. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +<sect1>Graphics drivers<p> + +No graphics drivers are currently available for the NES. + +<sect1>Extended memory drivers<p> + +No extended memory drivers are currently available for the NES. + + +<sect1>Joystick drivers<p> + +A joystick driver for the standard buttons is available, but must be +statically linked, because no file I/O is available. See the documentation for +the <htmlurl url="co65.html" name="co65 utility"> for information on how to do +that. + +<sect1>Mouse drivers<p> + +No mouse drivers are currently available for the NES. + + +<sect1>RS232 device drivers<p> + +No serial drivers are currently available for the NES. + + + +<sect>Limitations<p> + +<sect1>Disk I/O<p> + +The existing library for the NES doesn't implement C file +I/O. There are no hacks for the <tt/read()/ and <tt/write()/ routines. + +To be more concrete, this limitation means that you cannot use any of the +following functions (and a few others): + +<itemize> +<item>fclose +<item>fopen +<item>fread +<item>fprintf +<item>fputc +<item>fscanf +<item>fwrite +<item>... +</itemize> + + + +<sect>Other hints<p> + + + +<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">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +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. +</enum> + +</article> + + +