Added a second OSI C1P program file format.

[cc65] / doc / osi.sgml

diff --git a/doc/osi.sgml b/doc/osi.sgml
index e360daf7afdc458748bbf53cbf9659b1f7b171e0..0167b2bd1ba5537c9e5a30444e0b1af414cc8ff2 100644 (file)
--- a/doc/osi.sgml
+++ b/doc/osi.sgml
@@ -4,8 +4,9 @@
 
 <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
+<url url="mailto:stephan.muehlstrasser@web.de" name="Stephan M&uuml;hlstrasser">,<newline>
+<url url="mailto:greg.king5@verizon.net" name="Greg King">
+<date>2015-03-07
 
 <abstract>
 An overview over the Ohio Scientific runtime system as it is implemented for the cc65 C
@@ -34,42 +35,63 @@ information.
 Currently the target "osic1p" is implemented. This works for the Ohio Scientific
 Challenger 1P machine.
 
-<sect>Binary format<p>
+<sect>Program file formats<p>
 
-The standard binary output format generated by the linker for the osic1p target
-is a machine language program.<p>
+<descrip>
+  <tag/Binary, then text/
+  The standard binary output format generated by the linker for the osic1p
+  target is a pure machine language program.
+
+  For uploading into a real machine over its serial port or into an emulator,
+  that program must be converted into a text file that can be understood by
+  the 65V PROM monitor. For that purpose, the <bf/srec_cat/ program from <url
+  url="http://srecord.sourceforge.net/" name="the SRecord tool collection">
+  can be used.
+
+  Care must be taken that the <tt/-offset/ and <tt/-execution-start-address/
+  options for the <bf/srec_cat/ program correspond to the start address
+  of the executable.
+
+  Example for converting an executable "hello" file that was built for the
+  default start address &dollar;0200 to an uploadable file "hello.c1p":
 
-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.
+  <tscreen><verb>
+  srec_cat hello -bin -of 0x200 -o hello.c1p -os -esa=0x200
+  </verb></tscreen>
 
-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.
+  <tag/Hybrid/
+  The linker can create an alternate format that contains two parts:
+  <enum>
+    <item>A text header that is understood by the 65V PROM monitor.
+          It is a boot loader that reads the second part.
+    <item>The default binary code that is described above.
+  </enum>
 
-Example for converting an executable "hello" that was built for the default
-start address &dollar;0200 to an uploadable file "hello.c1p":
+  You can make the alternate format by adding the option <tt/-u __BOOT__/ to
+  <tt/cl65/'s or <tt/ld65/'s command lines.
 
-<tscreen>
-srec_cat hello -binary -offset 0x200 -o hello.c1p -Ohio_Scientific -execution-start-address=0x200
-</tscreen>
+  This format doesn't need to be converted. It is smaller than the text-only
+  format.  But, it cannot be loaded by <url
+  url="http://www.pcjs.org/docs/c1pjs/" name="C1Pjs">; you must use the
+  SRecord-produced text-only format with that emulator.
+
+</descrip>
 
 <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__.
+The RAM size can be configured via the symbol <tt/__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.
+  via the linker option <tt/--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
+  The size is configurable via the symbol <tt/__STACKSIZE__/. The default
   stack size is &dollar;0400.
 
   <tag/Heap/
@@ -77,7 +99,7 @@ Special locations:
   runtime stack.
 
   <tag/Video RAM/
-  The 1 kB video RAM is located at &dollar;D000. On the monitor only a subset
+  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).
@@ -87,9 +109,9 @@ Special locations:
 Example for building a program with start address &dollar;0300, stack size
 &dollar;0200 and RAM size &dollar;2000:
 
-<tscreen>
+<tscreen><verb>
 cl65 --start-addr 0x300 -Wl -D,__HIMEM__=$2000,-D,__STACKSIZE__=$0200 -t osic1p hello.c
-</tscreen>
+</verb></tscreen>
 
 <sect>Linker configurations<p>
 
@@ -112,16 +134,17 @@ To use this config file, assemble with <tt/-t osic1p/ and link with
 is used, while the latter supplies the actual config. When using <tt/cl65/,
 use both command line options.
 
-Sample command line for <tt/cl65/:
+Sample command lines for <tt/cl65/:
 
 <tscreen><verb>
-cl65 -o program -t osic1p -C osic1p-asm.cfg source.s
+cl65 -t osic1p -C osic1p-asm.cfg -o program source.s
+cl65 -t osic1p -C osic1p-asm.cfg -u __BOOT__ -o program.lod source.s
 </verb></tscreen>
 
 <sect>Platform-specific header files<p>
 
-Programs containing Ohio Scientific-specific code may use the <tt/osic1p.h/ 
-header file. 
+Programs containing Ohio Scientific-specific code may use the <tt/osic1p.h/
+header file.
 
 <sect1>Ohio Scientific-specific functions<p>