X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fosi.sgml;h=eeaee4a97edccd472d3e13e96009d73c16cbdf3b;hb=74455508314bc2b007e812ec5f9429496b9fbd5f;hp=85d4dca440632e1cf36c353268f2ccd2bc22731d;hpb=88249a2125ca07353740337266a4155ca241c39e;p=cc65 diff --git a/doc/osi.sgml b/doc/osi.sgml index 85d4dca44..eeaee4a97 100644 --- a/doc/osi.sgml +++ b/doc/osi.sgml @@ -1,11 +1,10 @@
- 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"> <abstract> An overview over the Ohio Scientific runtime system as it is implemented for the cc65 C @@ -32,44 +31,68 @@ 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. +Challenger 1P machine and for the Briel Superboard /// replica. -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. +<sect>Program file formats<p> -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/ @@ -77,25 +100,52 @@ Special locations: 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> @@ -109,12 +159,37 @@ There is no specific support for direct hardware access. 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> @@ -142,14 +217,15 @@ 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. +<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> +