X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fpce.sgml;h=a1866b8f09c0069933485695374af170099da853;hb=dfb7c0f24d7df8b6de735d730ba0465fc5d7c775;hp=74692ce169d078d6473d9cefd4fc395b262d9b27;hpb=f17850cf00171f1aa79848b34d927b229cf06288;p=cc65 diff --git a/doc/pce.sgml b/doc/pce.sgml index 74692ce16..a1866b8f0 100644 --- a/doc/pce.sgml +++ b/doc/pce.sgml @@ -1,11 +1,9 @@
- -PC-Engine (TurboGrafx) System specific information for cc65 -<author> -<url url="mailto:groepaz@gmx.net" name="Groepaz/Hitmen"> -<date>2015-07-14 +<title>PC-Engine (TurboGrafx 16) System-specific information for cc65 +<author><url url="mailto:groepaz@gmx.net" name="Groepaz/Hitmen">,<newline> +<url url="mailto:greg.king5@verizon.net" name="Greg King"> <abstract> An overview over the PCE runtime system as it is implemented for the @@ -20,86 +18,125 @@ cc65 C compiler. <sect>Overview<p> This file contains an overview of the PCE runtime system as it comes -with the cc65 C compiler. It describes the memory layout, PCE specific header +with the cc65 C compiler. It describes the memory layout, PCE-specific header files, available drivers, and any pitfalls specific to that platform. -Please note that PCE specific functions are just mentioned here, they are -described in detail in the separate <url url="funcref.html" name="function -reference">. Even functions marked as "platform dependent" may be available on +Please note that PCE-specific functions are just mentioned here; they are +described, in detail, in the separate <url url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" might be available on 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 | <-- "conio.bin" ++--------+--------+--------+--------+ + ++--------+--------+--------+--------+ +| Bank 0 | Bank 1 | Bank 2 | Bank 3 | <-- "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> -cc65 generated programs with the default setup run with the I/O area and a -CHR bank enabled, which gives a usable memory range of $8000 - $FFF3. -All boot ROM entry points may be called directly without additional code. +cc65-generated programs with the default setup run with the memory map that was +used by many PC-Engine games: +<itemize> +<item>The first 8K bytes is the I/O area. +<item>The second 8K bytes is RAM, which holds +<itemize> +<item>the redirected zero-page and the redirected hardware stack page, +<item>and 7680 bytes of general memory ($2200 - $3FFF). +</itemize> +<item>The last 8K bytes in the usual 64K-byte range is the ROM that holds the +program. +</itemize> Special locations: <descrip> <tag/Text screen and Font/ - The text screen is located at VRAM $0000, - the Font is located at VRAM $2000. + The text screen is located at Video RAM (VRAM) address $0000; + the Font is located at VRAM address $2000. <tag/Stack/ - The C runtime stack is located in system RAM at $3FFF and growing downwards. - - <tag/BSS and Data/ + The C run-time stack is located in system RAM at $3FFF; + and, grows downwards. - The BSS (uninitialized variables) and Data (initialized variables) sections are - placed one after the other into system RAM at $2000. + <tag/Data and BSS/ + The Data (initialized variables) and BSS (uninitialized variables) sections are + placed one after the other into system RAM at $2200. <tag/Heap/ - The C heap is located after the end of the Data section and grows towards the C - runtime stack. + The C heap is located after the end of the BSS section; + and, extends up to the C run-time stack. <tag/Code/ - The startup code is located at $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 + $E000 and $FFF5 in the System bank. -</descrip><p> + In a 16K cartridge, code and read-only data are located between $C000 + and $FFF5. + In a 32K cartridge, code and read-only data are located between $8000 + and $FFF5. +</descrip> -<sect>Platform specific header files<p> -Programs containing PCE specific code may use the <tt/pce.h/ header file. +<sect>Platform-specific header files<p> +Programs containing PCE-specific code may use the <tt/pce.h/ header file. -<sect1>PCE specific functions<p> + +<sect1>PCE-specific functions<p> <itemize> -<item>waitvblank</item> -<item>get_tv</item> (since all PCE systems are NTSC, this always returns TV_NTSC) +<item>waitvsync</item> +<item>get_tv (since all PCE systems are NTSC, this always returns TV_NTSC)</item> </itemize> - <sect1>Hardware access<p> -The following pseudo variables declared in the <tt/pce.inc/ include file do -allow access to hardware located in the address space. +The following constants, defined in the <tt/pce.inc/ include file, do +allow access to hardware that is located in the address space. <descrip> <tag><tt/PSG/</tag> - The <tt/PSG/ defines allow access to the PSG chip (Programmable Sound Generator). + The <tt/PSG/ defines allow access to the PSG (Programmable Sound Generator). <tag><tt/VCE/</tag> The <tt/VCE/ defines allow access to the VCE chip (Video Color Encoder). <tag><tt/VDC/</tag> - The <tt/VDC/ defines allow access to the VDC chip (Video Display Controller). + The <tt/VDC/ defines allow access to the VDC chip (Video Display Controller).<newline> + 32K of 16-bit words of Video RAM can be accessed only through this chip. -</descrip><p> +</descrip> @@ -111,12 +148,8 @@ The names in the parentheses denote the symbols to be used for static linking of <sect1>Graphics drivers<p> -<descrip> - No TGI graphics drivers are currently available for the PCE. -</descrip><p> - <sect1>Extended memory drivers<p> @@ -128,11 +161,11 @@ No extended memory drivers are currently available for the PCE. <descrip> <tag><tt/pce-stdjoy.joy (pce_stdjoy)/</tag> - A joystick driver for the standard two buttons joypad is available. + A joystick driver for the standard two-button joypad is available. - Note that the japanese 6-button pad is currently not supported. + Note that the Japanese 6-button pad currently is not supported. -</descrip><p> +</descrip> <sect1>Mouse drivers<p> @@ -148,16 +181,13 @@ No serial drivers are currently available for the PCE. <sect>Limitations<p> -<itemize> -<item>interruptor support in crt0 (and cfg) is missing -</itemize> <sect1>Disk I/O<p> The existing library for the PCE doesn't implement C file I/O. There are no hacks for the <tt/read()/ and <tt/write()/ routines. -To be more concrete, this limitation means that you cannot use any of the +To be more concrete, that limitation means that you cannot use any of the following functions (and a few others): <itemize> @@ -172,18 +202,21 @@ following functions (and a few others): <item>... </itemize> + + <sect>Other hints<p> <itemize> -<item>a good emulator to use for PC-Engine is "mednafen" (<url url="http://mednafen.sourceforge.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: +Some useful resources on PCE coding: <itemize> <item><url url="http://blog.blockos.org/?tag=pc-engine"> <item><url url="http://pcedev.blockos.org/viewforum.php?f=5"> -<item><url url="http://www.romhacking.net/?page=documents&category=&platform=4&:game=&author=&perpage=20&level=&title=&desc=&docsearch=Go"> +<item><url url="http://www.romhacking.net/?page=documents&platform=4"> <item><url url="http://archaicpixels.com/Main_Page"> <item><url url="http://www.magicengine.com/mkit/doc.html"> @@ -192,9 +225,11 @@ some useful resources on PCE coding: <item><url url="http://www.zeograd.com/parse.php?src=hucf"> </itemize> + + <sect>License<p> -This software is provided 'as-is', without any expressed or implied +This software is provided "as-is", without any expressed or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software. @@ -203,17 +238,14 @@ including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions: <enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. +<item>The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated, but is not required. +<item>Altered source versions must be marked plainly as such; and, must not + be misrepresented as being the original software. +<item>This notice may not be removed or altered from any source + distribution. </enum> </article> - - -