]> git.sur5r.net Git - cc65/blob - doc/pce.sgml
Merge pull request #7 from cc65/master
[cc65] / doc / pce.sgml
1 <!doctype linuxdoc system>
2
3 <article>
4
5 <title>PC-Engine (TurboGrafx) System specific information for cc65
6 <author><url url="mailto:groepaz@gmx.net" name="Groepaz/Hitmen">,<newline>
7 <url url="mailto:greg.king5@verizon.net" name="Greg King">
8 <date>2018-02-12
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
34 <sect>Binary format<p>
35
36 The binary output file generated by the linker, for the PCE target, is an
37 image, with no header, that has 8K bytes in the wrong place.  That file must be
38 post-processed; the 8K at the end must be moved to the front of the image.
39
40 On POSIX systems, the <tt/dd/ command and the shell give a convenient way to do
41 it.  Here is an example of their use:
42 <tscreen><verb>
43 dd if=conio.bin bs=8K skip=3 > conio.pce
44 dd if=conio.bin bs=8K count=3 >> conio.pce
45 </verb></tscreen>
46 The first command grabs the last 8K of a 32K file, and writes it as the first
47 part of a new file.  The second command reads all but the last part of the old
48 file, and appends it to the new file.
49 <tscreen><verb>
50 +--------+--------+--------+--------+
51 | Bank 1 | Bank 2 | Bank 3 | Bank 0 |  &lt;-- "conio.bin"
52 +--------+--------+--------+--------+
53
54 +--------+--------+--------+--------+
55 | Bank 0 | Bank 1 | Bank 2 | Bank 3 |  &lt;-- "conio.pce"
56 +--------+--------+--------+--------+
57 </verb></tscreen>
58 <em/Note/:  That <tt/.pce/ file shows the format of the ROM cartridge that is
59 plugged into a PC-Engine.  But, that <tt/.bin/ file shows what programs
60 actually see when they execute the code in that cartridge.
61
62
63
64 <sect>Memory layout<p>
65
66 cc65 generated programs with the default setup run with the I/O area and a
67 CHR bank enabled, which gives a usable memory range of &dollar;8000 - &dollar;FFF3.
68 All boot ROM entry points may be called directly without additional code.
69
70 Special locations:
71
72 <descrip>
73   <tag/Text screen and Font/
74   The text screen is located at VRAM &dollar;0000,
75   the Font is located at VRAM &dollar;2000.
76
77   <tag/Stack/
78   The C runtime stack is located in system RAM at &dollar;3FFF and growing downwards.
79
80   <tag/Data and BSS/
81   The Data (initialized variables) and BSS (uninitialized variables) sections are
82   placed one after the other into system RAM at &dollar;2200.
83
84   <tag/Heap/
85   The C heap is located after the end of the BSS section; and, grows towards the C
86   runtime stack.
87
88   <tag/Code/
89   In an 8K ROM cartridge, code and read-only data are located between
90   &dollar;E000 and &dollar;FFF5 in the System bank.
91
92   In a 16K cartridge, code and read-only data are located between &dollar;C000
93   and &dollar;FFF5.
94
95   In a 32K cartridge, code and read-only data are located between &dollar;8000
96   and &dollar;FFF5.
97 </descrip><p>
98
99
100
101 <sect>Platform specific header files<p>
102
103 Programs containing PCE specific code may use the <tt/pce.h/ header file.
104
105
106 <sect1>PCE specific functions<p>
107
108 <itemize>
109 <item>waitvsync</item>
110 <item>get_tv (since all PCE systems are NTSC, this always returns TV_NTSC)</item>
111 </itemize>
112
113
114
115 <sect1>Hardware access<p>
116
117 The following pseudo variables declared in the <tt/pce.inc/ include file do
118 allow access to hardware located in the address space.
119
120 <descrip>
121
122   <tag><tt/PSG/</tag>
123   The <tt/PSG/ defines allow access to the PSG chip (Programmable Sound Generator).
124
125   <tag><tt/VCE/</tag>
126   The <tt/VCE/ defines allow access to the VCE chip (Video Color Encoder).
127
128   <tag><tt/VDC/</tag>
129   The <tt/VDC/ defines allow access to the VDC chip (Video Display Controller).
130
131 </descrip><p>
132
133
134
135 <sect>Loadable drivers<p>
136
137 All drivers must be statically linked because no file I/O is available.
138 The names in the parentheses denote the symbols to be used for static linking of the drivers.
139
140
141 <sect1>Graphics drivers<p>
142
143 No TGI graphics drivers are currently available for the PCE.
144
145
146 <sect1>Extended memory drivers<p>
147
148 No extended memory drivers are currently available for the PCE.
149
150
151 <sect1>Joystick drivers<p>
152
153 <descrip>
154
155   <tag><tt/pce-stdjoy.joy (pce_stdjoy)/</tag>
156   A joystick driver for the standard two buttons joypad is available.
157
158   Note that the japanese 6-button pad is currently not supported.
159
160 </descrip><p>
161
162
163 <sect1>Mouse drivers<p>
164
165 No mouse drivers are currently available for the PCE.
166
167
168 <sect1>RS232 device drivers<p>
169
170 No serial drivers are currently available for the PCE.
171
172
173
174 <sect>Limitations<p>
175
176 <itemize>
177 <item>interruptor support in crt0 (and cfg) is missing
178 </itemize>
179
180 <sect1>Disk I/O<p>
181
182 The existing library for the PCE doesn't implement C file
183 I/O. There are no hacks for the <tt/read()/ and <tt/write()/ routines.
184
185 To be more concrete, this limitation means that you cannot use any of the
186 following functions (and a few others):
187
188 <itemize>
189 <item>printf
190 <item>fclose
191 <item>fopen
192 <item>fread
193 <item>fprintf
194 <item>fputc
195 <item>fscanf
196 <item>fwrite
197 <item>...
198 </itemize>
199
200 <sect>Other hints<p>
201
202 <itemize>
203 <item><url url="https://mednafen.github.io/" name= "Mednafen"> is a good
204 emulator to use for the PC-Engine.
205 </itemize>
206
207 some useful resources on PCE coding:
208
209 <itemize>
210 <item><url url="http://blog.blockos.org/?tag=pc-engine">
211 <item><url url="http://pcedev.blockos.org/viewforum.php?f=5">
212 <item><url url="http://www.romhacking.net/?page=documents&amp;platform=4">
213 <item><url url="http://archaicpixels.com/Main_Page">
214
215 <item><url url="http://www.magicengine.com/mkit/doc.html">
216
217 <item><url url="https://github.com/uli/huc">
218 <item><url url="http://www.zeograd.com/parse.php?src=hucf">
219 </itemize>
220
221 <sect>License<p>
222
223 This software is provided 'as-is', without any expressed or implied
224 warranty.  In no event will the authors be held liable for any damages
225 arising from the use of this software.
226
227 Permission is granted to anyone to use this software for any purpose,
228 including commercial applications, and to alter it and redistribute it
229 freely, subject to the following restrictions:
230
231 <enum>
232 <item>  The origin of this software must not be misrepresented; you must not
233         claim that you wrote the original software. If you use this software
234         in a product, an acknowledgment in the product documentation would be
235         appreciated but is not required.
236 <item>  Altered source versions must be plainly marked as such, and must not
237         be misrepresented as being the original software.
238 <item>  This notice may not be removed or altered from any source
239         distribution.
240 </enum>
241
242 </article>