From 680c62d589932bb342cd5fe9d0969501133d2efe Mon Sep 17 00:00:00 2001 From: =?utf8?q?Stephan=20M=C3=BChlstrasser?= Date: Fri, 6 Feb 2015 22:53:36 +0100 Subject: [PATCH] Start documentation for Ohio Scientific targets. --- doc/index.sgml | 3 + doc/osi.sgml | 154 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 157 insertions(+) create mode 100644 doc/osi.sgml diff --git a/doc/index.sgml b/doc/index.sgml index 7de8b26ce..921b8c03d 100644 --- a/doc/index.sgml +++ b/doc/index.sgml @@ -134,6 +134,9 @@ Topics specific to the Nintendo Entertainment System. + + Topics specific to the Ohio Scientific machines. + Topics specific to the Commodore PET machines. diff --git a/doc/osi.sgml b/doc/osi.sgml new file mode 100644 index 000000000..c46a2a742 --- /dev/null +++ b/doc/osi.sgml @@ -0,0 +1,154 @@ + + +
+ +Ohio Scientific-specific information for cc65 +<author> +<url url="mailto:stephan.muehlstrasser@web.de" name="Stephan Mühlstrasser"><newline> +<date>2015-02-04 + +<abstract> +An overview over the Ohio Scientific 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 Ohio Scientific runtime system as it comes with the +cc65 C compiler. It describes the memory layout, Ohio Scientific-specific header files, +and any pitfalls specific to that platform. + +Please note that Ohio Scientific-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>Targets<p> + +Currently the target "osic1p" is implemented. This works for the Ohio Scientific +Challenger 1P machine. + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the osic1p target +is a machine language program.<p> + +For uploading into a real machine over the serial port or into an emulator a +program must be converted to a text file that is understood by the 65V PROM +monitor. For this purpose the srec_cat program from the +<url url="http://srecord.sourceforge.net/" name="SRecord"> tool collection can be used. + +Care must be taken that the -offset and -execution-start-address options for the srec_cat +program correspond to the start address of the executable. + +Example for converting an executable "hello" that was built for the default +start address $0200 to an uploadable file "hello.c1p": + +<tscreen> +srec_cat hello -binary -offset 0x200 -o hello.c1p -Ohio_Scientific -execution-start-address=0x200 +</tscreen> + +<sect>Memory layout<p> + +By default programs compiled for the osic1p target are configured for 32 kB RAM. +The RAM size can be configured via the symbol __HIMEM__. + +Special locations: + +<descrip> + <tag/Program start address/ + The default start address is $0200. The start address is configurable + via the compiler option --start-addr. + + <tag/Stack/ + The C runtime stack is located at the top of RAM and growing downwards. + The size is configurable via the symbol __STACKSIZE__. The default + stack size is $0400. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + + <tag/Video RAM/ + The 1 kB video RAM is located at $D000. On the monitor only a subset + of the available video RAM is visible. The address of the upper left corner + of the visible area is $dollar;D085 and corresponds to conio cursor + position (0, 0). + +</descrip><p> + +Example for building a program with start address $0300, stack size +$0200 and RAM size $0200: + +<tscreen> +cl65 --start-addr 0x300 -Wl -D,__HIMEM__=$2000,-D,__STACKSIZE__=$0300 -t osic1p hello.c +</tscreen> + +<sect>Platform-specific header files<p> + +Programs containing PET-specific code may use the <tt/pet.h/ or <tt/cbm.h/ +header files. + + +<sect1>PET-specific functions<p> + +There are currently no special Ohio Scientific functions. + +<sect1>Hardware access<p> + +There is no specific support for direct hardware access. + +<sect>Loadable drivers<p> + +There are no loadable drivers available. + +<sect>Limitations<p> + +<sect1>conio implementation<p> + +The conio implementation is complete except for the kbhit() function. A +call to cgetc() always blocks until a character is entered. + +<sect1>stdio implementation<p> + +There is no support for stdio at the moment. + +<sect>Other hints<p> + +<sect1>Passing arguments to the program<p> + +There is currently no support for passing arguments to a program. + +<sect1>Program return code<p> + +The program return code currently has no effect. When the main() function +finishes, the boot prompt is shown again. + +<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> -- 2.39.5