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

   1 <!doctype linuxdoc system>
   2
   3 <article>
   4
   5 <title>PC-Engine (TurboGrafx) System specific information for cc65
   6 <author>
   7 <url url="mailto:groepaz@gmx.net" name="Groepaz/Hitmen">
   8 <date>2015-07-14
   9
  10 <abstract>
  11 An overview over the PCE runtime system as it is implemented for the
  12 cc65 C compiler.
  13 </abstract>
  14
  15 <!-- Table of contents -->
  16 <toc>
  17
  18 <!-- Begin the document -->
  19
  20 <sect>Overview<p>
  21
  22 This file contains an overview of the PCE runtime system as it comes
  23 with the cc65 C compiler. It describes the memory layout, PCE specific header
  24 files, available drivers, and any pitfalls specific to that platform.
  25
  26 Please note that PCE specific functions are just mentioned here, they are
  27 described in detail in the separate <url url="funcref.html" name="function
  28 reference">. Even functions marked as "platform dependent" may be available on
  29 more than one platform. Please see the function reference for more
  30 information.
  31
  32
  33 <sect>Binary format<p>
  34
  35 The standard binary output format generated by the linker for the PCE target
  36 is a cartridge image with no header. It is of course possible to change this
  37 behaviour by using a modified startup file and linker config.
  38
  39 <sect>Memory layout<p>
  40
  41 cc65 generated programs with the default setup run with the I/O area and a
  42 CHR bank enabled, which gives a usable memory range of &dollar;8000 - &dollar;FFF3.
  43 All boot ROM entry points may be called directly without additional code.
  44
  45 Special locations:
  46
  47 <descrip>
  48   <tag/Text screen and Font/
  49   The text screen is located at VRAM &dollar;0000,
  50   the Font is located at VRAM &dollar;2000.
  51
  52   <tag/Stack/
  53   The C runtime stack is located in system RAM at &dollar;3FFF and growing downwards.
  54
  55   <tag/BSS and Data/
  56
  57   The BSS (uninitialized variables) and Data (initialized variables) sections are
  58   placed one after the other into system RAM at &dollar;2000.
  59
  60   <tag/Heap/
  61   The C heap is located after the end of the Data section and grows towards the C
  62   runtime stack.
  63
  64   <tag/Code/
  65   The startup code is located at &dollar;E000 in the System/Hardware bank. Further
  66   code can be placed in other ROM banks, this must be done manually however.
  67
  68 </descrip><p>
  69
  70
  71
  72 <sect>Platform specific header files<p>
  73
  74 Programs containing PCE specific code may use the <tt/pce.h/ header file.
  75
  76
  77 <sect1>PCE specific functions<p>
  78
  79 <itemize>
  80 <item>waitvblank</item>
  81 <item>get_tv</item> (since all PCE systems are NTSC, this always returns TV_NTSC)
  82 </itemize>
  83
  84
  85
  86 <sect1>Hardware access<p>
  87
  88 The following pseudo variables declared in the <tt/pce.inc/ include file do
  89 allow access to hardware located in the address space.
  90
  91 <descrip>
  92
  93   <tag><tt/PSG/</tag>
  94   The <tt/PSG/ defines allow access to the PSG chip (Programmable Sound Generator).
  95
  96   <tag><tt/VCE/</tag>
  97   The <tt/VCE/ defines allow access to the VCE chip (Video Color Encoder).
  98
  99   <tag><tt/VDC/</tag>
 100   The <tt/VDC/ defines allow access to the VDC chip (Video Display Controller).
 101
 102 </descrip><p>
 103
 104
 105
 106 <sect>Loadable drivers<p>
 107
 108 All drivers must be statically linked because no file I/O is available.
 109 The names in the parentheses denote the symbols to be used for static linking of the drivers.
 110
 111
 112 <sect1>Graphics drivers<p>
 113
 114 <descrip>
 115
 116 No TGI graphics drivers are currently available for the PCE.
 117
 118 </descrip><p>
 119
 120
 121 <sect1>Extended memory drivers<p>
 122
 123 No extended memory drivers are currently available for the PCE.
 124
 125
 126 <sect1>Joystick drivers<p>
 127
 128 <descrip>
 129
 130   <tag><tt/pce-stdjoy.joy (pce_stdjoy)/</tag>
 131   A joystick driver for the standard two buttons joypad is available.
 132
 133 </descrip><p>
 134
 135
 136 <sect1>Mouse drivers<p>
 137
 138 No mouse drivers are currently available for the PCE.
 139
 140
 141 <sect1>RS232 device drivers<p>
 142
 143 No serial drivers are currently available for the PCE.
 144
 145
 146
 147 <sect>Limitations<p>
 148
 149 <sect1>Disk I/O<p>
 150
 151 The existing library for the PCE doesn't implement C file
 152 I/O. There are no hacks for the <tt/read()/ and <tt/write()/ routines.
 153
 154 To be more concrete, this limitation means that you cannot use any of the
 155 following functions (and a few others):
 156
 157 <itemize>
 158 <item>fclose
 159 <item>fopen
 160 <item>fread
 161 <item>fprintf
 162 <item>fputc
 163 <item>fscanf
 164 <item>fwrite
 165 <item>...
 166 </itemize>
 167
 168
 169
 170 <sect>Other hints<p>
 171
 172
 173
 174 <sect>License<p>
 175
 176 This software is provided 'as-is', without any expressed or implied
 177 warranty.  In no event will the authors be held liable for any damages
 178 arising from the use of this software.
 179
 180 Permission is granted to anyone to use this software for any purpose,
 181 including commercial applications, and to alter it and redistribute it
 182 freely, subject to the following restrictions:
 183
 184 <enum>
 185 <item>  The origin of this software must not be misrepresented; you must not
 186         claim that you wrote the original software. If you use this software
 187         in a product, an acknowledgment in the product documentation would be
 188         appreciated but is not required.
 189 <item>  Altered source versions must be plainly marked as such, and must not
 190         be misrepresented as being the original software.
 191 <item>  This notice may not be removed or altered from any source
 192         distribution.
 193 </enum>
 194
 195 </article>
 196
 197
 198