Start documentation for Ohio Scientific targets.

diff --git a/doc/index.sgml b/doc/index.sgml
index 7de8b26cea1270d3dc1b75541ef930a211c1cf28..921b8c03d54264b44ecb05dc7a0e36b1c77d735f 100644 (file)
--- a/doc/index.sgml
+++ b/doc/index.sgml
@@ -134,6 +134,9 @@
   <tag><htmlurl url="nes.html" name="nes.html"></tag>
   Topics specific to the Nintendo Entertainment System.
 
+  <tag><htmlurl url="osi.html" name="osi.html"></tag>
+  Topics specific to the Ohio Scientific machines.
+
   <tag><htmlurl url="pet.html" name="pet.html"></tag>
   Topics specific to the Commodore PET machines.
 

diff --git a/doc/osi.sgml b/doc/osi.sgml
new file mode 100644 (file)
index 0000000..c46a2a7
--- /dev/null
+++ b/doc/osi.sgml
@@ -0,0 +1,154 @@
+<!doctype linuxdoc system>
+
+<article>
+
+<title>Ohio Scientific-specific information for cc65
+<author>
+<url url="mailto:stephan.muehlstrasser@web.de" name="Stephan M&uuml;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 &dollar;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 &dollar;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 &dollar;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 &dollar;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 &dollar;0300, stack size
+&dollar;0200 and RAM size &dollar;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>