From cb8cb876ec741c96b506f03539165b12b5d342e7 Mon Sep 17 00:00:00 2001 From: Rutger van Bergen Date: Mon, 19 Sep 2022 19:56:57 +0200 Subject: [PATCH] Add documentation, make capitalization uniform --- asminc/kim1.inc | 13 ++-- cfg/kim1-60k.cfg | 6 +- cfg/kim1.cfg | 2 +- doc/index.sgml | 3 + doc/kim1.sgml | 148 ++++++++++++++++++++++++++++++++++++++++ libsrc/kim1/crt0.s | 4 +- samples/kim1/kimHello.c | 2 +- src/common/target.h | 2 +- 8 files changed, 165 insertions(+), 15 deletions(-) create mode 100644 doc/kim1.sgml diff --git a/asminc/kim1.inc b/asminc/kim1.inc index f0d1555a7..b1046b01c 100644 --- a/asminc/kim1.inc +++ b/asminc/kim1.inc @@ -7,22 +7,21 @@ RAMSTART := $0200 ; Entry point + ; --------------------------------------------------------------------------- ; Monitor Functions ; --------------------------------------------------------------------------- - - OUTCHR := $1EA0 ; Output character INTCHR := $1E5A ; Input character without case conversion DUMPT := $1800 ; Dump memory to tape LOADT := $1873 ; Load memory from tape + + +; --------------------------------------------------------------------------- +; System Memory +; --------------------------------------------------------------------------- SAL := $17F5 ; Tape load address low SAH := $17F6 ; Tape load address high EAL := $17F7 ; Tape address end low EAH := $17F8 ; Tape address end high ID := $17F9 ; Tape Identification number - -; --------------------------------------------------------------------------- -; System Memory -; --------------------------------------------------------------------------- - diff --git a/cfg/kim1-60k.cfg b/cfg/kim1-60k.cfg index a6704d9dd..087715560 100644 --- a/cfg/kim1-60k.cfg +++ b/cfg/kim1-60k.cfg @@ -1,8 +1,8 @@ -# kim1.cfg (4k) +# kim1-60k.cfg (4k) # -# for unexpanded Kim-1 +# for expanded KIM-1 # -# ld65 --config kim1.cfg -o .bin .o +# ld65 --config kim1-60k.cfg -o .bin .o FEATURES { STARTADDRESS: default = $2000; diff --git a/cfg/kim1.cfg b/cfg/kim1.cfg index 69636065e..f48fed80e 100644 --- a/cfg/kim1.cfg +++ b/cfg/kim1.cfg @@ -1,6 +1,6 @@ # kim1.cfg (4k) # -# for unexpanded Kim-1 +# for unexpanded KIM-1 # # ld65 --config kim1.cfg -o .bin .o diff --git a/doc/index.sgml b/doc/index.sgml index bb3ad5357..bfce63486 100644 --- a/doc/index.sgml +++ b/doc/index.sgml @@ -154,6 +154,9 @@ Topics specific to the Bit Corporation Gamate Console. + + Topics specific to the MOS Technology KIM-1. + Topics specific to the Atari Lynx Game Console. diff --git a/doc/kim1.sgml b/doc/kim1.sgml new file mode 100644 index 000000000..0c8b54311 --- /dev/null +++ b/doc/kim1.sgml @@ -0,0 +1,148 @@ + + +
+MOS Technology KIM-1 specific information for cc65 +<author><url url="mailto:dave@davepl.com" name="Dave Plummer"> + +<abstract> +An overview over 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 +"platform dependent" 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 $200 - $0FFF. The 60k config expands +this range to $DFFF. The starting memory location and entry point for running the program is +$200, so when the program is transferred to the KIM-1, it is executed by typing '200 G'. + +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 $0FFF on 4kb KIM-1s, or at $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/kim.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 "master console" +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 "Hello World!" 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> diff --git a/libsrc/kim1/crt0.s b/libsrc/kim1/crt0.s index aefdc3545..f1fee86c1 100644 --- a/libsrc/kim1/crt0.s +++ b/libsrc/kim1/crt0.s @@ -40,8 +40,8 @@ _init: cld ; Clear decimal mode jsr _main -; Back from main (this is also the _exit entry). There may be a more elegant way to9 -; return to the monitor on the Kim-1, but I don't know it! +; Back from main (this is also the _exit entry). There may be a more elegant way to +; return to the monitor on the KIM-1, but I don't know it! _exit: brk diff --git a/samples/kim1/kimHello.c b/samples/kim1/kimHello.c index dcbfb4e67..0dca1345f 100644 --- a/samples/kim1/kimHello.c +++ b/samples/kim1/kimHello.c @@ -1,5 +1,5 @@ // -------------------------------------------------------------------------- -// Hello World for Kim-1 +// Hello World for KIM-1 // // Dave Plummer based on Sym-1 sample by Wayne Parham // diff --git a/src/common/target.h b/src/common/target.h index 7439fa621..0cec74b6e 100644 --- a/src/common/target.h +++ b/src/common/target.h @@ -87,7 +87,7 @@ typedef enum { TGT_C65, TGT_CX16, TGT_SYM1, - TGT_KIM1, // Added at end so as not to shift existing entries + TGT_KIM1, TGT_COUNT /* Number of target systems */ } target_t;