]> git.sur5r.net Git - cc65/blob - doc/osi.sgml
Adjusted doc to code.
[cc65] / doc / osi.sgml
1 <!doctype linuxdoc system>
2
3 <article>
4 <title>Ohio Scientific-specific information for cc65
5 <author>
6 <url url="mailto:stephan.muehlstrasser@web.de" name="Stephan M&uuml;hlstrasser">,<newline>
7 <url url="mailto:greg.king5@verizon.net" name="Greg King">
8
9 <abstract>
10 An overview over the Ohio Scientific runtime system as it is implemented for the cc65 C
11 compiler.
12 </abstract>
13
14 <!-- Table of contents -->
15 <toc>
16
17 <!-- Begin the document -->
18
19 <sect>Overview<p>
20
21 This file contains an overview of the Ohio Scientific runtime system as it comes with the
22 cc65 C compiler. It describes the memory layout, Ohio Scientific-specific header files,
23 and any pitfalls specific to that platform.
24
25 Please note that Ohio Scientific-specific functions are just mentioned here, they are
26 described in detail in the separate <url url="funcref.html" name="function
27 reference">. Even functions marked as "platform dependent" may be available on
28 more than one platform. Please see the function reference for more
29 information.
30
31 <sect>Targets<p>
32
33 Currently the target "osic1p" is implemented. This works for the Ohio Scientific
34 Challenger 1P machine and for the Briel Superboard /// replica.
35
36 <sect>Program file formats<p>
37
38 <descrip>
39   <tag/Binary, then text/
40   The standard binary output format generated by the linker for the osic1p
41   target is a pure machine language program.
42
43   For uploading into a real machine over its serial port or into an emulator,
44   that program must be converted into a text file that can be understood by
45   the 65V PROM monitor. For that purpose, the <bf/srec_cat/ program from <url
46   url="http://srecord.sourceforge.net/" name="the SRecord tool collection">
47   can be used.
48
49   Care must be taken that the <tt/-offset/ and <tt/-execution-start-address/
50   options for the <bf/srec_cat/ program correspond to the start address
51   of the executable.
52
53   Example for converting an executable "hello" file that was built for the
54   default start address &dollar;0200 to an uploadable file "hello.c1p":
55
56   <tscreen><verb>
57   srec_cat hello -bin -of 0x200 -o hello.c1p -os -esa=0x200
58   </verb></tscreen>
59
60   <tag/Hybrid/
61   The linker can create an alternate format that contains two parts:
62   <enum>
63     <item>A text header that is understood by the 65V PROM monitor.
64           It is a boot loader that reads the second part.
65     <item>The default binary code that is described above.
66   </enum>
67
68   You can make the alternate format by adding the option <tt/-u __BOOT__/ to
69   <tt/cl65/'s or <tt/ld65/'s command lines.
70
71   This format doesn't need to be converted. It is smaller than the text-only
72   format.  But, it cannot be loaded by <url
73   url="http://www.pcjs.org/docs/c1pjs/" name="C1Pjs">; you must use the
74   SRecord-produced text-only format with that emulator. (However, if you know
75   that you never will use C1Pjs, then you can edit the
76   <tt>cfg/osic1p*.cfg</tt> files; uncomment the lines that import <tt/__BOOT__/.
77   Then, you won't need to use <tt/-u __BOOT__/ on your command lines.)
78
79 </descrip>
80
81 <sect>Memory layout<p>
82
83 By default programs compiled for the osic1p target are configured for 32 kB RAM.
84 The RAM size can be configured via the symbol <tt/__HIMEM__/.
85
86 Special locations:
87
88 <descrip>
89   <tag/Program start address/
90   The default start address is &dollar;0200. The start address is configurable
91   via the linker option <tt/--start-addr/.
92
93   <tag/Stack/
94   The C runtime stack is located at the top of RAM and growing downwards.
95   The size is configurable via the symbol <tt/__STACKSIZE__/. The default
96   stack size is &dollar;0400.
97
98   <tag/Heap/
99   The C heap is located at the end of the program and grows towards the C
100   runtime stack.
101
102   <tag/Video RAM/
103   The 1 kB video RAM is located at &dollar;D000. On the monitor, only a subset
104   of the available video RAM is visible. The address of the upper left corner
105   of the visible area is &dollar;D085 and corresponds to conio cursor
106   position (0, 0).
107
108 </descrip><p>
109
110 Example for building a program with start address &dollar;0300, stack size
111 &dollar;0200 and RAM size &dollar;2000:
112
113 <tscreen><verb>
114 cl65 --start-addr 0x300 -Wl -D,__HIMEM__=$2000,-D,__STACKSIZE__=$0200 -t osic1p hello.c
115 </verb></tscreen>
116
117 <sect>Linker configurations<p>
118
119 The ld65 linker comes with a default config file "osic1p.cfg" for the Ohio Scientific
120 Challenger 1P, which is implicitly used via <tt/-t osic1p/. The
121 osic1p package comes with additional secondary linker config files, which are
122 used via <tt/-t osic1p -C &lt;configfile&gt;/.
123
124 <sect1>Default config file (<tt/osic1p.cfg/)<p>
125
126 The default configuration is tailored to C programs.
127
128 <sect1><tt/osic1p-asm.cfg/<p>
129
130 This configuration is made for assembler programmers who don't need a special
131 setup.
132
133 To use this config file, assemble with <tt/-t osic1p/ and link with
134 <tt/-C osic1p-asm.cfg/. The former will make sure that correct runtime library
135 is used, while the latter supplies the actual config. When using <tt/cl65/,
136 use both command line options.
137
138 Sample command lines for <tt/cl65/:
139
140 <tscreen><verb>
141 cl65 -t osic1p -C osic1p-asm.cfg -o program source.s
142 cl65 -t osic1p -C osic1p-asm.cfg -u __BOOT__ -o program.lod source.s
143 </verb></tscreen>
144
145 <sect>Platform-specific header files<p>
146
147 Programs containing Ohio Scientific-specific code may use the <tt/osic1p.h/
148 header file.
149
150 <sect1>Ohio Scientific-specific functions<p>
151
152 There are currently no special Ohio Scientific functions.
153
154 <sect1>Hardware access<p>
155
156 There is no specific support for direct hardware access.
157
158 <sect>Loadable drivers<p>
159
160 There are no loadable drivers available.
161
162 <sect>Support for different screen layouts<p>
163
164 By default the conio library uses a 24 columns by 24 lines screen layout
165 for the Challenger 1P, like under BASIC. In addition to that there is support
166 for other screen layouts with extra modules.
167
168 There is a module <tt/screen-c1p-24x24.o/ in the OSI-specific
169 cc65 runtime library that contains all conio functions that depend
170 on the screen layout. No further configuration is needed for using the
171 default screen layout of the Challenger 1P.
172
173 For other screen layouts additional versions of the screen module are
174 available. The linker finds these modules without further configuration
175 if they are specified on the compiler or linker command line. The
176 extra module then overrides the default module.
177
178 Sample <tt/cl65/ command line to override the default screen
179 module with the module <tt/osic1p-screen-s3-32x28.o/:
180
181 <tscreen><verb>
182 cl65 -o hello -t osic1p osic1p-screen-s3-32x28.o hello.c
183 </verb></tscreen>
184
185 Currently the following extra screen configuration modules are implemented:
186
187 <itemize>
188 <item><tt>osic1p-screen-s3-32x28.o</tt>: 32 columns by 28 lines mode
189 for Briel Superboard ///</item>
190 </itemize>
191
192 <sect>Limitations<p>
193
194 <sect1>stdio implementation<p>
195
196 There is no support for stdio at the moment.
197
198 <sect>Other hints<p>
199
200 <sect1>Passing arguments to the program<p>
201
202 There is currently no support for passing arguments to a program.
203
204 <sect1>Program return code<p>
205
206 The program return code currently has no effect. When the main() function
207 finishes, the boot prompt is shown again.
208
209 <sect>License<p>
210
211 This software is provided 'as-is', without any expressed or implied
212 warranty.  In no event will the authors be held liable for any damages
213 arising from the use of this software.
214
215 Permission is granted to anyone to use this software for any purpose,
216 including commercial applications, and to alter it and redistribute it
217 freely, subject to the following restrictions:
218
219 <enum>
220 <item>  The origin of this software must not be misrepresented; you must not
221         claim that you wrote the original software. If you use this software
222         in a product, an acknowledgment in the product documentation would be
223         appreciated but is not required.
224 <item>  Altered source versions must be plainly marked as such, and must not
225         be misrepresented as being the original software.
226 <item>  This notice may not be removed or altered from any source
227         distribution.
228 </enum>
229
230 </article>
231