mirror of
https://github.com/cc65/cc65.git
synced 2024-12-27 15:29:46 +00:00
174 lines
7.1 KiB
Plaintext
174 lines
7.1 KiB
Plaintext
<!doctype linuxdoc system>
|
|
|
|
<article>
|
|
<title>Synertek Systems Sym-1 specific information for cc65
|
|
<author><url url="mailto:wayne@parhamdata.com" name="Wayne Parham">
|
|
|
|
<abstract>
|
|
An overview over the Sym-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 Sym-1 runtime system as it comes with the cc65 C compiler.
|
|
It describes the memory layout, Sym-1 specific header files, available drivers, and any pitfalls
|
|
specific to the platform.
|
|
|
|
Please note that Sym-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 Sym-1 target is a raw binary BIN file, which
|
|
is essentially a memory image. You can convert this to a HEX file using BIN2HEX, which is a
|
|
popular open-source conversion utility program. A HEX file has ASCII representations of the
|
|
hexadecimal byte values of the machine-language program. So the HEX file can be transferred
|
|
to the Sym-1 using the RS-232 terminal port, just as if the machine-code was entered by hand.
|
|
Enter 'm 200' in the monitor and start the HEX file transfer.
|
|
|
|
<p>
|
|
|
|
Included with this distribution is a 4k configuration file and a 32k config file. The Sym-1
|
|
on-board memory is limited to 4 kbytes but system memory can be increased to 32 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 Sym-1 monitor ROM. cc65 generated programs compiled and linked
|
|
using 4k config run in the memory range of $200 - $0FFF. The 32k config expands
|
|
this range to $7FFF. Memory above 32k can be used to extend the heap, as described below.
|
|
The starting memory location and entry point for running the program is $200, so when the
|
|
program is transferred to the Sym-1, it is executed by typing 'g 200'. The system returns control
|
|
back to the monitor ROM when the program terminates, providing the '.' prompt.
|
|
|
|
Special locations:
|
|
|
|
<descrip>
|
|
<tag/Text screen/
|
|
Conio support is not currently available for the Sym-1. But stdio console functions are available.
|
|
|
|
<tag/Stack/
|
|
The C runtime stack is located at $0FFF on 4kb Syms, or at $7FFF for 32kb 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. Extended
|
|
memory can be added to the heap, as described below.
|
|
|
|
</descrip><p>
|
|
|
|
<sect>Platform specific header files<p>
|
|
|
|
Programs containing Sym-1 code may use the <tt/sym1.h/ header file. See the header file for more information.
|
|
|
|
<sect1>Hardware access<p>
|
|
|
|
The pseudo variables declared in the <tt/sym1.inc/ include file allow access to hardware located in the
|
|
address space. See the include file for more information.
|
|
|
|
<sect>Loadable drivers<p>
|
|
|
|
<sect1>Graphics drivers<p>
|
|
|
|
No graphics drivers are currently available for the Sym-1.
|
|
|
|
<sect1>Extended memory drivers<p>
|
|
|
|
There are no extended memory drivers for the Sym-1. However, there is a way to access memory beyond the
|
|
32kb boundary, if extended memory is physically present in the system. See the example program,
|
|
symExtendedMemory, in the samples directory.
|
|
|
|
<sect1>Joystick drivers<p>
|
|
|
|
No joystick driver is currently available for the Sym-1.
|
|
|
|
<sect1>Mouse drivers<p>
|
|
|
|
No mouse drivers are currently available for the Sym-1.
|
|
|
|
<sect1>RS232 device drivers<p>
|
|
|
|
No communication port drivers are currently available for the Sym-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 Sym-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>sym1.h<p>
|
|
This header exposes Sym-specific I/O functions that are useful for reading and writing its ports and front panel.
|
|
See the <tt/sym1.h/ include file for a list of the functions available.
|
|
|
|
<sect2>Limited memory applications<p>
|
|
|
|
As stated earlier, there are config files for 4kb and 32kb systems. If you have 32kb RAM, then you will probably
|
|
want to use the sym1-32k configuration, but if not - if you are using the sym1-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.
|
|
|
|
<sect3>Using extended memory<p>
|
|
|
|
Memory may be physically present that is addressed at locations above the monitor ROM at $8000. This extended
|
|
memory is accessible by adding to the heap, as described in the symExtendedMemory sample program.
|
|
|
|
<sect4>Sample programs<p>
|
|
|
|
All the samples will run on the "stock" 4kb Sym-1, except for symIO and symNotepad, which require 32kb.
|
|
Additionally, symExtendedMemory shows how to access memory above 32kb, so it expects more than 32kb.
|
|
These sample programs can be found in the samples/sym1 directory:
|
|
|
|
<itemize>
|
|
<item>symHello prints "Hello World!" and then inputs characters, which are echoed on the screen.
|
|
It also makes a "beep" sound.</item>
|
|
<item>symTiny does the same as symHello, but does it with puts() rather than printf() to show the difference
|
|
in compiled binary size.</item>
|
|
<item>symDisplay allows entry of a message, which is then displayed by scrolling it across the front panel display.</item>
|
|
<item>symIO allows access to the Sym-1 digital I/O ports.</item>
|
|
<item>symNotepad is a simple text entry/retrieval program that uses tape storage.</item>
|
|
<item>symExtendedMemory demonstrates how to access upper-memory and add it to the heap.</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>
|