cc65/doc/kim1.sgml

<!doctype linuxdoc system>

<article>
<title>MOS Technology KIM-1 specific information for cc65
<author><url url="mailto:davepl@davepl.com" name="Dave Plummer">

<abstract>
An overview of the KIM-1 runtime system as it is implemented for the cc65 C compiler.
</abstract>

<!-- Table of contents -->
<toc>

<!-- Begin the document -->

<sect>Overview<p>

This file contains an overview of the KIM-1 runtime system as it comes with the cc65 C compiler.
It describes the memory layout, KIM-1 specific header files, available drivers, and any pitfalls
specific to the platform.

Please note that KIM-1 specific functions are just mentioned here, they are described in detail
in the separate <url url="funcref.html" name="function reference">.  Even functions marked as
&quot;platform dependent&quot; may be available on more than one platform.  Please see the
function reference for more information.

<sect>Binary format<p>

The output format generated by the linker for the KIM-1 target is a raw binary BIN file, which
is essentially a memory image.  You can convert this to a papertape format file using
Convert8bithexformat or KIMPaper, which are open-source conversion utility programs.
A papertape format files can be transferred to the KIM-1 using the RS-232 terminal port (TTY),
just as if the machine-code was entered by hand. Enter 'L' in the TTY and start the paper tape file
transfer.

<p>

Included with this distribution is a 4k configuration file and a 60k config file.  The KIM-1
on-board memory is limited to 4 kbytes but system memory can be increased to 60 kbytes of
contiguous RAM with aftermarket add-on boards.  So choose the config file that matches your
system configuration before compiling and linking user programs.

<sect>Memory layout<p>

The ROMs and I/O areas are defined in the configuration files, as are most of the entry points
for useful subroutines in the KIM-1 monitor ROM.  cc65 generated programs compiled and linked
using 4k config run in the memory range of &dollar;200 - &dollar;0FFF.  The 60k config expands
this range to &dollar;DFFF. When using the 4k config the starting memory location and entry point
for running the program is &dollar;200, so when the program is transferred to the KIM-1, it is
executed by typing '200 G'. With the 60k config the default starting memory location and entry
point is &dollar;2000.

Special locations:

<descrip>
  <tag/Text screen/
  Conio support is not currently available for the KIM-1.  But stdio console functions are available.

  <tag/Stack/
  The C runtime stack is located at &dollar;0FFF on 4kb KIM-1s, or at &dollar;DFFF for 60kb systems.
  The stack always grows downwards.

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

</descrip><p>

<sect>Platform specific header files<p>

Programs containing KIM-1 code may use the <tt/kim1.h/ header file.  See the header file for more information.

<sect>Loadable drivers<p>

<sect1>Graphics drivers<p>

No graphics drivers are currently available for the KIM-1.

<sect1>Joystick drivers<p>

No joystick driver is currently available for the KIM-1.

<sect1>Mouse drivers<p>

No mouse drivers are currently available for the KIM-1.

<sect1>RS232 device drivers<p>

No communication port drivers are currently available for the KIM-1.  It has only the &quot;master console&quot;
e.g. stdin and stdout.

<sect>Limitations<p>

<sect1>Disk I/O<p>

The existing library for the KIM-1 doesn't implement C file I/O.

To be more specific, this limitation means that you cannot use any of the following functions (and a few others):

<itemize>
<item>fopen
<item>fclose
<item>fread
<item>fwrite
<item>...
</itemize>

<sect>Other hints<p>

<sect1>kim1.h<p>
This header exposes KIM-1 specific I/O functions that are useful for reading and writing its ports and front panel.
See the <tt/kim1.h/ include file for a list of the functions available.

<sect1>Limited memory applications<p>

As stated earlier, there are config files for 4kb and 60kb systems.  If you have 60kb RAM, then you will probably
want to use the kim1-60k configuration, but if not - if you are using the kim1-4k configuration - then you may
want to use functions like getchar, putchar, gets and puts rather than functions like scanf and printf.
Printf, for example, requires about 1KB because it needs to know how to process all the format specifiers.

<sect1>Sample programs<p>

These sample programs can be found in the samples/kim1 directory:

<itemize>
<item>kimHello prints &quot;Hello World!&quot; and then inputs characters, which are echoed on the screen.
      This program will run on both 4kb and 60kb systems.</item>
<item>kimSieve finds the prime numbers up to 100,000 using the Sieve of Eratosthenes algorithm, and prints how many
      prime numbers were found. This program requires a 60kb system to run.</item>
</itemize>

<sect>License<p>

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:

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

</article>