-
Notifications
You must be signed in to change notification settings - Fork 16
Expand file tree
/
Copy pathsym1.html
More file actions
248 lines (176 loc) · 9.3 KB
/
sym1.html
File metadata and controls
248 lines (176 loc) · 9.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<LINK REL="stylesheet" TYPE="text/css" HREF="doc.css">
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.83">
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<TITLE>Synertek Systems Sym-1 specific information for cc65</TITLE>
</HEAD>
<BODY>
<H1>Synertek Systems Sym-1 specific information for cc65</H1>
<H2>
<A HREF="mailto:wayne@parhamdata.com">Wayne Parham</A></H2>
<HR>
<EM>An overview over the Sym-1 runtime system as it is implemented for the cc65 C compiler.</EM>
<HR>
<P>
<H2><A NAME="toc1">1.</A> <A HREF="sym1.html#s1">Overview</A></H2>
<P>
<H2><A NAME="toc2">2.</A> <A HREF="sym1.html#s2">Binary format</A></H2>
<P>
<H2><A NAME="toc3">3.</A> <A HREF="sym1.html#s3">Memory layout</A></H2>
<P>
<H2><A NAME="toc4">4.</A> <A HREF="sym1.html#s4">Platform specific header files</A></H2>
<UL>
<LI><A NAME="toc4.1">4.1</A> <A HREF="sym1.html#ss4.1">Hardware access</A>
</UL>
<P>
<H2><A NAME="toc5">5.</A> <A HREF="sym1.html#s5">Loadable drivers</A></H2>
<UL>
<LI><A NAME="toc5.1">5.1</A> <A HREF="sym1.html#ss5.1">Graphics drivers</A>
<LI><A NAME="toc5.2">5.2</A> <A HREF="sym1.html#ss5.2">Extended memory drivers</A>
<LI><A NAME="toc5.3">5.3</A> <A HREF="sym1.html#ss5.3">Joystick drivers</A>
<LI><A NAME="toc5.4">5.4</A> <A HREF="sym1.html#ss5.4">Mouse drivers</A>
<LI><A NAME="toc5.5">5.5</A> <A HREF="sym1.html#ss5.5">RS232 device drivers</A>
</UL>
<P>
<H2><A NAME="toc6">6.</A> <A HREF="sym1.html#s6">Limitations</A></H2>
<UL>
<LI><A NAME="toc6.1">6.1</A> <A HREF="sym1.html#ss6.1">Disk I/O</A>
</UL>
<P>
<H2><A NAME="toc7">7.</A> <A HREF="sym1.html#s7">Other hints</A></H2>
<UL>
<LI><A NAME="toc7.1">7.1</A> <A HREF="sym1.html#ss7.1">sym1.h</A>
</UL>
<P>
<H2><A NAME="toc8">8.</A> <A HREF="sym1.html#s8">License</A></H2>
<HR>
<H2><A NAME="s1">1.</A> <A HREF="#toc1">Overview</A></H2>
<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.</P>
<P>Please note that Sym-1 specific functions are just mentioned here, they are described in detail
in the separate
<A HREF="funcref.html">function reference</A>. Even functions marked as
"platform dependent" may be available on more than one platform. Please see the
function reference for more information.</P>
<H2><A NAME="s2">2.</A> <A HREF="#toc2">Binary format</A></H2>
<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>
<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.</P>
<H2><A NAME="s3">3.</A> <A HREF="#toc3">Memory layout</A></H2>
<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.</P>
<P>Special locations:</P>
<P>
<DL>
<DT><B>Text screen</B><DD>
<P>Conio support is not currently available for the Sym-1. But stdio console functions are available.</P>
<DT><B>Stack</B><DD>
<P>The C runtime stack is located at $0FFF on 4kb Syms, or at $7FFF for 32kb systems.
The stack always grows downwards.</P>
<DT><B>Heap</B><DD>
<P>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.</P>
</DL>
</P>
<H2><A NAME="s4">4.</A> <A HREF="#toc4">Platform specific header files</A></H2>
<P>Programs containing Sym-1 code may use the <CODE>sym1.h</CODE> header file. See the header file for more information.</P>
<H2><A NAME="ss4.1">4.1</A> <A HREF="#toc4.1">Hardware access</A>
</H2>
<P>The pseudo variables declared in the <CODE>sym1.inc</CODE> include file allow access to hardware located in the
address space. See the include file for more information.</P>
<H2><A NAME="s5">5.</A> <A HREF="#toc5">Loadable drivers</A></H2>
<H2><A NAME="ss5.1">5.1</A> <A HREF="#toc5.1">Graphics drivers</A>
</H2>
<P>No graphics drivers are currently available for the Sym-1.</P>
<H2><A NAME="ss5.2">5.2</A> <A HREF="#toc5.2">Extended memory drivers</A>
</H2>
<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.</P>
<H2><A NAME="ss5.3">5.3</A> <A HREF="#toc5.3">Joystick drivers</A>
</H2>
<P>No joystick driver is currently available for the Sym-1.</P>
<H2><A NAME="ss5.4">5.4</A> <A HREF="#toc5.4">Mouse drivers</A>
</H2>
<P>No mouse drivers are currently available for the Sym-1.</P>
<H2><A NAME="ss5.5">5.5</A> <A HREF="#toc5.5">RS232 device drivers</A>
</H2>
<P>No communication port drivers are currently available for the Sym-1. It has only the "master console"
e.g. stdin and stdout.</P>
<H2><A NAME="s6">6.</A> <A HREF="#toc6">Limitations</A></H2>
<H2><A NAME="ss6.1">6.1</A> <A HREF="#toc6.1">Disk I/O</A>
</H2>
<P>The existing library for the Sym-1 doesn't implement C file I/O.</P>
<P>To be more specific, this limitation means that you cannot use any of the following functions (and a few others):</P>
<P>
<UL>
<LI>fopen</LI>
<LI>fclose</LI>
<LI>fread</LI>
<LI>fwrite</LI>
<LI>...</LI>
</UL>
</P>
<H2><A NAME="s7">7.</A> <A HREF="#toc7">Other hints</A></H2>
<H2><A NAME="ss7.1">7.1</A> <A HREF="#toc7.1">sym1.h</A>
</H2>
<P>This header exposes Sym-specific I/O functions that are useful for reading and writing its ports and front panel.
See the <CODE>sym1.h</CODE> include file for a list of the functions available.</P>
<H3>Limited memory applications</H3>
<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.</P>
<H3>Using extended memory</H3>
<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.</P>
<H3>Sample programs</H3>
<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:</P>
<P>
<UL>
<LI>symHello prints "Hello World!" and then inputs characters, which are echoed on the screen.
It also makes a "beep" sound.</LI>
<LI>symTiny does the same as symHello, but does it with puts() rather than printf() to show the difference
in compiled binary size.</LI>
<LI>symDisplay allows entry of a message, which is then displayed by scrolling it across the front panel display.</LI>
<LI>symIO allows access to the Sym-1 digital I/O ports.</LI>
<LI>symNotepad is a simple text entry/retrieval program that uses tape storage.</LI>
<LI>symExtendedMemory demonstrates how to access upper-memory and add it to the heap.</LI>
</UL>
</P>
<H2><A NAME="s8">8.</A> <A HREF="#toc8">License</A></H2>
<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.</P>
<P>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:</P>
<P>
<OL>
<LI> 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.</LI>
<LI> Altered source versions must be plainly marked as such, and must not
be misrepresented as being the original software.</LI>
<LI> This notice may not be removed or altered from any source
distribution.</LI>
</OL>
</P>
</BODY>
</HTML>