<title>Ohio Scientific-specific information for cc65
<author>
-<url url="mailto:stephan.muehlstrasser@web.de" name="Stephan Mühlstrasser"><newline>
-<date>2015-02-04
+<url url="mailto:stephan.muehlstrasser@web.de" name="Stephan Mühlstrasser">,<newline>
+<url url="mailto:greg.king5@verizon.net" name="Greg King">
+<date>2015-03-17
<abstract>
An overview over the Ohio Scientific runtime system as it is implemented for the cc65 C
<sect>Targets<p>
Currently the target "osic1p" is implemented. This works for the Ohio Scientific
-Challenger 1P machine.
+Challenger 1P machine and for the Briel Superboard /// replica.
-<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>
-
-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>
+<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 $0200 to an uploadable file "hello.c1p":
+
+ <tscreen><verb>
+ srec_cat hello -bin -of 0x200 -o hello.c1p -os -esa=0x200
+ </verb></tscreen>
+
+ <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>
+
+ You can make the alternate format by adding the option <tt/-u __BOOT__/ to
+ <tt/cl65/'s or <tt/ld65/'s command lines.
+
+ 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. (However, if you know
+ that you never will use C1Pjs, then you can edit the
+ <tt>cfg/osic1p*.cfg</tt> files; uncomment the lines that import <tt/__BOOT__/.
+ Then, you won't need to use <tt/-u __BOOT__/ on your command lines.)
+
+</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 $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 $0400.
<tag/Heap/
runtime stack.
<tag/Video RAM/
- The 1 kB video RAM is located at $D000. On the monitor only a subset
+ 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
+ of the visible area is $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:
+$0200 and RAM size $2000:
-<tscreen>
-cl65 --start-addr 0x300 -Wl -D,__HIMEM__=$2000,-D,__STACKSIZE__=$0300 -t osic1p hello.c
-</tscreen>
+<tscreen><verb>
+cl65 --start-addr 0x300 -Wl -D,__HIMEM__=$2000,-D,__STACKSIZE__=$0200 -t osic1p hello.c
+</verb></tscreen>
-<sect>Platform-specific header files<p>
+<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 <configfile>/.
+
+<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.
-Programs containing Ohio Scientific-specific code may use the <tt/osic1p.h/
-header file.
+Sample command lines for <tt/cl65/:
+<tscreen><verb>
+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.
<sect1>Ohio Scientific-specific functions<p>
There are no loadable drivers available.
-<sect>Limitations<p>
+<sect>Support for different screen layouts<p>
+
+By default the conio library uses a 24 columns by 24 lines screen layout
+for the Challenger 1P, like under BASIC. In addition to that there is support
+for other screen layouts with extra modules.
+
+There is a module <tt/screen-c1p-24x24.o/ in the OSI-specific
+cc65 runtime library that contains all conio functions that depend
+on the screen layout. No further configuration is needed for using the
+default screen layout of the Challenger 1P.
-<sect1>conio implementation<p>
+For other screen layouts additional versions of the screen module are
+available. The linker finds these modules without further configuration
+if they are specified on the compiler or linker command line. The
+extra module then overrides the default module.
-The conio implementation is complete except for the kbhit() function. A
-call to cgetc() always blocks until a character is entered.
+Sample <tt/cl65/ command line to override the default screen
+module with the module <tt/osic1p-screen-s3-32x28.o/:
+
+<tscreen><verb>
+cl65 -o hello -t osic1p osic1p-screen-s3-32x28.o hello.c
+</verb></tscreen>
+
+Currently the following extra screen configuration modules are implemented:
+
+<itemize>
+<item><tt>osic1p-screen-s3-32x28.o</tt>: 32 columns by 28 lines mode
+for Briel Superboard ///</item>
+</itemize>
+
+<sect>Limitations<p>
<sect1>stdio implementation<p>
</enum>
</article>
+