Ohio Scientific-specific information for cc65

Stephan Mühlstrasser,
Greg King

2015-03-17
An overview over the Ohio Scientific runtime system as it is implemented for the cc65 C compiler.

1. Overview

2. Targets

3. Program file formats

4. Memory layout

5. Linker configurations

6. Platform-specific header files

7. Loadable drivers

8. Support for different screen layouts

9. Limitations

10. Other hints

11. License


1. Overview

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 function reference. Even functions marked as "platform dependent" may be available on more than one platform. Please see the function reference for more information.

2. Targets

Currently the target "osic1p" is implemented. This works for the Ohio Scientific Challenger 1P machine and for the Briel Superboard /// replica.

3. Program file formats

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 srec_cat program from the 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" file that was built for the default start address $0200 to an uploadable file "hello.c1p":

  srec_cat hello -bin -of 0x200 -o hello.c1p -os -esa=0x200
  

Hybrid

The linker can create an alternate format that contains two parts:

  1. A text header that is understood by the 65V PROM monitor. It is a boot loader that reads the second part.
  2. The default binary code that is described above.

You can make the alternate format by adding the option -u __BOOT__ to cl65's or 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 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 cfg/osic1p*.cfg files; uncomment the lines that import __BOOT__. Then, you won't need to use -u __BOOT__ on your command lines.)

4. Memory layout

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:

Program start address

The default start address is $0200. The start address is configurable via the linker option --start-addr.

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 $0400.

Heap

The C heap is located at the end of the program and grows towards the C runtime stack.

Video RAM

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 $D085 and corresponds to conio cursor position (0, 0).

Example for building a program with start address $0300, stack size $0200 and RAM size $2000:

cl65 --start-addr 0x300 -Wl -D,__HIMEM__=$2000,-D,__STACKSIZE__=$0200 -t osic1p hello.c

5. Linker configurations

The ld65 linker comes with a default config file "osic1p.cfg" for the Ohio Scientific Challenger 1P, which is implicitly used via -t osic1p. The osic1p package comes with additional secondary linker config files, which are used via -t osic1p -C <configfile>.

5.1 Default config file (osic1p.cfg)

The default configuration is tailored to C programs.

5.2 osic1p-asm.cfg

This configuration is made for assembler programmers who don't need a special setup.

To use this config file, assemble with -t osic1p and link with -C osic1p-asm.cfg. The former will make sure that correct runtime library is used, while the latter supplies the actual config. When using cl65, use both command line options.

Sample command lines for cl65:

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

6. Platform-specific header files

Programs containing Ohio Scientific-specific code may use the osic1p.h header file.

6.1 Ohio Scientific-specific functions

There are currently no special Ohio Scientific functions.

6.2 Hardware access

There is no specific support for direct hardware access.

7. Loadable drivers

There are no loadable drivers available.

8. Support for different screen layouts

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 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.

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.

Sample cl65 command line to override the default screen module with the module osic1p-screen-s3-32x28.o:

cl65 -o hello -t osic1p osic1p-screen-s3-32x28.o hello.c

Currently the following extra screen configuration modules are implemented:

9. Limitations

9.1 stdio implementation

There is no support for stdio at the moment.

10. Other hints

10.1 Passing arguments to the program

There is currently no support for passing arguments to a program.

10.2 Program return code

The program return code currently has no effect. When the main() function finishes, the boot prompt is shown again.

11. License

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:

  1. 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.
  2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
  3. This notice may not be removed or altered from any source distribution.