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>  <toc>  <sect>Overview 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 The standard binary output format generated by the linker for the Sym-1 target is a 4 kbyte machine language program. It is, of course, possible to change this behavior by using one of the different linker configs. Included with this distribution is a 4k configuration file and a 32k config file. The Sym-1 on-board memory is limited to 4k 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 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. 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 $7FFFfor 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. </descrip> <sect>Platform specific header files Programs containing Sym-1 code may use the <tt/symio.h/ header file. See the header file for more information. <sect1>Hardware access The following 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 <sect1>Graphics drivers No graphics drivers are currently available for the Sym-1. <sect1>Extended memory drivers No extended memory drivers are currently available for the Sym-1. <sect1>Joystick drivers No joystick driver is currently available for the Sym-1. <sect1>Mouse drivers No mouse drivers are currently available for the Sym-1. <sect1>RS232 device drivers No communication port drivers are currently available for the Sym-1. It has only the "master console" e.g. stdin and stdout. <sect>Limitations <sect1>Disk I/O 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 <sect1>symio.h You can use stdio.h if you wish, which provides console I/O (like printf) but does not have access to a filesystem, as mentioned above. But there is another header available, which exposes Sym-specific I/O functions that are useful for reading and writing its ports and front panel. It also exposes functions normally included using stdio.h but only the console I/O functions and not the filesystem functions. See the symio.h include file for a list of the functions available. <sect2>Limited memory applications 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_32k configuration - then you may want to use functions like getchar, putchar, gets and puts rather than printf. Printf requires about 1kb because it needs to know how to process all the format specifiers. <sect3>Sample programs All the samples will run on the "stock" 4k Sym-1, except for symio.c, which requires 8k. Information on building and running it is in the samples/tutorial/sym1 directory. <itemize> <item>helloworld is the traditional "Hello World!" program, using printf().</item> <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> </itemize> <sect>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: <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>