From: Stephan Mühlstrasser <stephan.muehlstrasser@web.de>
Date: Sun, 8 Feb 2015 14:06:55 +0000 (+0100)
Subject: Completing OSI documentation.
X-Git-Tag: V2.15~22^2~15
X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=da8ec4f7b1c295bc112f75b246d4432fff0d1b6e;p=cc65

Completing OSI documentation.
---

diff --git a/doc/intro.sgml b/doc/intro.sgml
index 02c5c83d5..5ffef7e69 100644
--- a/doc/intro.sgml
+++ b/doc/intro.sgml
@@ -513,6 +513,75 @@ directory notePad.  Look at the eight file-positions on each page until you see
 The output is shown in a GEOS dialog box; click <bf/OK/ when you have finished
 reading it.
 
+<sect1>Ohio Scientific Challenger 1P<p>
+Available at <url url="http://www.pcjs.org/docs/c1pjs/" name="C1Pjs">:
+
+Emulates the Ohio Scientific Challenger 1P computer in different configurations.
+The 32 kb RAM machine that must be used with the default compiler settings is
+<url url="http://www.pcjs.org/devices/c1p/machine/32kb/" name="here">.
+
+In addition the srec_cat program from the
+<url url="http://srecord.sourceforge.net/" name="SRecord">
+tool collection must be installed. Some Linux distributions also provide the
+srecord package that can be installed directly from the distribution's
+repository.
+
+The osic1p runtime library directly returns to the boot prompt when the
+main() program exits. Therefore the C file in the tutorial must be slightly
+modified in order to see the results on the screen. Otherwise the program
+would print the text string and then jump to the boot prompt, making it
+impossible to see the results of running the tutorial program.
+
+In addition to that the cc65 target does not yet have support for stdio
+functions. Only the functions from the conio library are available.
+
+Therefore modify the main() function in hello.c as follows:
+
+<tscreen>
+#include <conio.h>
+#include <stdlib.h>
+
+extern const char text[];       /* In text.s */
+
+int main (void)
+{
+    clrscr();
+    cprintf ("%s\r\nPress <RETURN>\r\n", text);
+    cgetc();
+    return EXIT_SUCCESS;
+}
+</tscreen>
+
+Compile the tutorial with
+
+<tscreen><verb>
+cl65 -O -t osic1p hello.c text.s
+</verb></tscreen>
+
+Convert the executable file into a text file that can be loaded via
+the Ohio Scientific 65V PROM monitor at start address 0x200:
+
+<tscreen><verb>
+srec_cat hello -binary -offset 0x200 -o hello.c1p -Ohio_Scientific -execution-start-address=0x200
+</verb></tscreen>
+
+Open the URL <url url="http://www.pcjs.org/devices/c1p/machine/32kb/" name="http://www.pcjs.org/devices/c1p/machine/32kb/">
+in your browser and wait until the emulator is loaded. Click on the BREAK
+button to display the boot prompt, then press the M key to enter the
+65V PROM monitor. Press the "Choose File" button and select the hello.c1p
+that was created as the output of the above invocation of the srec_cat
+command. Press the "Load" button. You should see the following text on the
+screen:
+
+<tscreen><verb>
+Hello world!
+Press <RETURN>
+</verb></tscreen>
+
+After hitting the RETURN key you should see the boot prompt again.
+
+The program can also be uploaded over the serial port to a real Challenger 1P
+computer.
 
 <sect1>Contributions wanted<p>
 
diff --git a/doc/osi.sgml b/doc/osi.sgml
index 85d4dca44..7152f2815 100644
--- a/doc/osi.sgml
+++ b/doc/osi.sgml
@@ -79,7 +79,7 @@ Special locations:
   <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
+  of the visible area is &dollar;D085 and corresponds to conio cursor
   position (0, 0).
 
 </descrip><p>
@@ -91,12 +91,38 @@ Example for building a program with start address &dollar;0300, stack size
 cl65 --start-addr 0x300 -Wl -D,__HIMEM__=$2000,-D,__STACKSIZE__=$0300 -t osic1p hello.c
 </tscreen>
 
+<sect>Linker configurations<p>
+
+The ld65 linker comes with a default config file "osic1p.cfg" for the Ohio Scientific
+Challenger 1P, which is implicitly used via <tt/-t osic1p/. The
+osic1p package comes with additional secondary linker config files, which are
+used via <tt/-t osic1p -C &lt;configfile&gt;/.
+
+<sect1>default config file (<tt/osic1p.cfg/)<p>
+
+The default configuration is tailored to C programs.
+
+<sect1><tt/osic1p-asm.cfg/<p>
+
+This configuration is made for assembler programmers who don't need a special
+setup.
+
+To use this config file, assemble with <tt/-t osic1p/ and link with
+<tt/-C osic1p-asm.cfg/. The former will make sure that correct runtime library
+is used, while the latter supplies the actual config. When using <tt/cl65/,
+use both command line options.
+
+Sample command line for <tt/cl65/:
+
+<tscreen><verb>
+cl65 -o program -t osic1p -C osic1p-asm.cfg source.s
+</verb></tscreen>
+
 <sect>Platform-specific header files<p>
 
 Programs containing Ohio Scientific-specific code may use the <tt/osic1p.h/ 
 header file. 
 
-
 <sect1>Ohio Scientific-specific functions<p>
 
 There are currently no special Ohio Scientific functions.