git.sur5r.net Git - cc65/blob - doc/osi.sgml

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