Merge pull request #662 from Compyx/master

[cc65] / doc / pce.sgml

diff --git a/doc/pce.sgml b/doc/pce.sgml
index 104dee52621ebdea8ff0579b5b542bec6e643905..bc7dcf5c841e58a6cf5ac2999165c28d0122f252 100644 (file)
--- a/doc/pce.sgml
+++ b/doc/pce.sgml
@@ -3,9 +3,9 @@
 <article>
 
 <title>PC-Engine (TurboGrafx) System specific information for cc65
-<author>
-<url url="mailto:groepaz@gmx.net" name="Groepaz/Hitmen">
-<date>2016-09-29
+<author><url url="mailto:groepaz@gmx.net" name="Groepaz/Hitmen">,<newline>
+<url url="mailto:greg.king5@verizon.net" name="Greg King">
+<date>2018-02-12
 
 <abstract>
 An overview over the PCE runtime system as it is implemented for the
@@ -30,11 +30,36 @@ more than one platform. Please see the function reference for more
 information.
 
 
+
 <sect>Binary format<p>
 
-The standard binary output format generated by the linker for the PCE target
-is a cartridge image with no header. It is of course possible to change this
-behaviour by using a modified startup file and linker config.
+The binary output file generated by the linker, for the PCE target, is an
+image, with no header, that has 8K bytes in the wrong place.  That file must be
+post-processed; the 8K at the end must be moved to the front of the image.
+
+On POSIX systems, the <tt/dd/ command and the shell give a convenient way to do
+it.  Here is an example of their use:
+<tscreen><verb>
+dd if=conio.bin bs=8K skip=3 > conio.pce
+dd if=conio.bin bs=8K count=3 >> conio.pce
+</verb></tscreen>
+The first command grabs the last 8K of a 32K file, and writes it as the first
+part of a new file.  The second command reads all but the last part of the old
+file, and appends it to the new file.
+<tscreen><verb>
++--------+--------+--------+--------+
+| Bank 1 | Bank 2 | Bank 3 | Bank 0 |  &lt;-- "conio.bin"
++--------+--------+--------+--------+
+
++--------+--------+--------+--------+
+| Bank 0 | Bank 1 | Bank 2 | Bank 3 |  &lt;-- "conio.pce"
++--------+--------+--------+--------+
+</verb></tscreen>
+<em/Note/:  That <tt/.pce/ file shows the format of the ROM cartridge that is
+plugged into a PC-Engine.  But, that <tt/.bin/ file shows what programs
+actually see when they execute the code in that cartridge.
+
+
 
 <sect>Memory layout<p>
 
@@ -52,19 +77,23 @@ Special locations:
   <tag/Stack/
   The C runtime stack is located in system RAM at &dollar;3FFF and growing downwards.
 
-  <tag/BSS and Data/
-
-  The BSS (uninitialized variables) and Data (initialized variables) sections are
-  placed one after the other into system RAM at &dollar;2000.
+  <tag/Data and BSS/
+  The Data (initialized variables) and BSS (uninitialized variables) sections are
+  placed one after the other into system RAM at &dollar;2200.
 
   <tag/Heap/
-  The C heap is located after the end of the Data section and grows towards the C
+  The C heap is located after the end of the BSS section; and, grows towards the C
   runtime stack.
 
   <tag/Code/
-  The startup code is located at &dollar;E000 in the System/Hardware bank. Further
-  code can be placed in other ROM banks, this must be done manually however.
+  In an 8K ROM cartridge, code and read-only data are located between
+  &dollar;E000 and &dollar;FFF5 in the System bank.
 
+  In a 16K cartridge, code and read-only data are located between &dollar;C000
+  and &dollar;FFF5.
+
+  In a 32K cartridge, code and read-only data are located between &dollar;8000
+  and &dollar;FFF5.
 </descrip><p>
 
 
@@ -77,7 +106,7 @@ Programs containing PCE specific code may use the <tt/pce.h/ header file.
 <sect1>PCE specific functions<p>
 
 <itemize>
-<item>waitvblank</item>
+<item>waitvsync</item>
 <item>get_tv (since all PCE systems are NTSC, this always returns TV_NTSC)</item>
 </itemize>
 
@@ -171,7 +200,8 @@ following functions (and a few others):
 <sect>Other hints<p>
 
 <itemize>
-<item>a good emulator to use for PC-Engine is "mednafen" (<url url="http://mednafen.fobby.net/">)
+<item><url url="https://mednafen.github.io/" name= "Mednafen"> is a good
+emulator to use for the PC-Engine.
 </itemize>
 
 some useful resources on PCE coding:
@@ -210,6 +240,3 @@ freely, subject to the following restrictions:
 </enum>
 
 </article>
-
-
-