<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<LINK REL="stylesheet" TYPE="text/css" HREF="doc.css">
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.71">
<TITLE>Nintendo Entertainment System specific information for cc65</TITLE>
</HEAD>
<BODY>
<H1>Nintendo Entertainment System specific information for cc65</H1>
<H2>
<A HREF="mailto:uz@cc65.org">Ullrich von Bassewitz</A>,<BR>
<A HREF="mailto:polluks@sdf.lonestar.org">Stefan A. Haubenthal</A></H2>
<HR>
<EM>An overview over the NES runtime system as it is implemented for the
cc65 C compiler.</EM>
<HR>
<P>
<H2><A NAME="toc1">1.</A> <A HREF="nes.html#s1">Overview</A></H2>
<P>
<H2><A NAME="toc2">2.</A> <A HREF="nes.html#s2">Binary format</A></H2>
<P>
<H2><A NAME="toc3">3.</A> <A HREF="nes.html#s3">Memory layout</A></H2>
<P>
<H2><A NAME="toc4">4.</A> <A HREF="nes.html#s4">Platform specific header files</A></H2>
<UL>
<LI><A NAME="toc4.1">4.1</A> <A HREF="nes.html#ss4.1">NES specific functions</A>
<LI><A NAME="toc4.2">4.2</A> <A HREF="nes.html#ss4.2">Hardware access</A>
</UL>
<P>
<H2><A NAME="toc5">5.</A> <A HREF="nes.html#s5">Loadable drivers</A></H2>
<UL>
<LI><A NAME="toc5.1">5.1</A> <A HREF="nes.html#ss5.1">Graphics drivers</A>
<LI><A NAME="toc5.2">5.2</A> <A HREF="nes.html#ss5.2">Extended memory drivers</A>
<LI><A NAME="toc5.3">5.3</A> <A HREF="nes.html#ss5.3">Joystick drivers</A>
<LI><A NAME="toc5.4">5.4</A> <A HREF="nes.html#ss5.4">Mouse drivers</A>
<LI><A NAME="toc5.5">5.5</A> <A HREF="nes.html#ss5.5">RS232 device drivers</A>
</UL>
<P>
<H2><A NAME="toc6">6.</A> <A HREF="nes.html#s6">Limitations</A></H2>
<UL>
<LI><A NAME="toc6.1">6.1</A> <A HREF="nes.html#ss6.1">Disk I/O</A>
</UL>
<P>
<H2><A NAME="toc7">7.</A> <A HREF="nes.html#s7">Other hints</A></H2>
<P>
<H2><A NAME="toc8">8.</A> <A HREF="nes.html#s8">License</A></H2>
<HR>
<H2><A NAME="s1">1.</A> <A HREF="#toc1">Overview</A></H2>
<P>This file contains an overview of the NES runtime system as it comes
with the cc65 C compiler. It describes the memory layout, NES specific header
files, available drivers, and any pitfalls specific to that platform.</P>
<P>Please note that NES specific functions are just mentioned here, they are
described in detail in the separate
<A HREF="funcref.html">function reference</A>. Even functions marked as "platform dependent" may be available on
more than one platform. Please see the function reference for more
information.</P>
<H2><A NAME="s2">2.</A> <A HREF="#toc2">Binary format</A></H2>
<P>The standard binary output format generated by the linker for the NES target
is a machine language program with an INES cartridge header. It is of course
possible to change this behaviour by using a modified startup file and linker
config.</P>
<H2><A NAME="s3">3.</A> <A HREF="#toc3">Memory layout</A></H2>
<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.</P>
<P>Special locations:</P>
<P>
<DL>
<DT><B>Text screen</B><DD>
<P>The text screen is located at VRAM $2000.</P>
<DT><B>Stack</B><DD>
<P>The C runtime stack is located at $7FFF and growing downwards.</P>
<DT><B>Heap</B><DD>
<P>The C heap is located at the end of the program and grows towards the C
runtime stack.</P>
</DL>
</P>
<H2><A NAME="s4">4.</A> <A HREF="#toc4">Platform specific header files</A></H2>
<P>Programs containing NES specific code may use the <CODE>nes.h</CODE> header file.</P>
<H2><A NAME="ss4.1">4.1</A> <A HREF="#toc4.1">NES specific functions</A>
</H2>
<P>
<UL>
<LI>get_tv</LI>
<LI>waitvsync - wait until the start of the next frame</LI>
</UL>
</P>
<H2><A NAME="ss4.2">4.2</A> <A HREF="#toc4.2">Hardware access</A>
</H2>
<P>The following pseudo variables declared in the <CODE>nes.inc</CODE> include file do
allow access to hardware located in the address space.</P>
<P>
<DL>
<DT><B><CODE>PPU</CODE></B><DD>
<P>The <CODE>PPU</CODE> defines allow access to the PPU chip.</P>
<DT><B><CODE>APU</CODE></B><DD>
<P>The <CODE>APU</CODE> defines allow access to the APU chip.</P>
</DL>
</P>
<H2><A NAME="s5">5.</A> <A HREF="#toc5">Loadable drivers</A></H2>
<P>All drivers must be statically linked because no file I/O is available.
The names in the parentheses denote the symbols to be used for static linking of the drivers.</P>
<H2><A NAME="ss5.1">5.1</A> <A HREF="#toc5.1">Graphics drivers</A>
</H2>
<P>
<DL>
<DT><B><CODE>nes-64-56-2.tgi (nes_64_56_2)</CODE></B><DD>
<P>This driver features a resolution of 64×56 with 2 colors using the
CHR bank.</P>
</DL>
</P>
<H2><A NAME="ss5.2">5.2</A> <A HREF="#toc5.2">Extended memory drivers</A>
</H2>
<P>No extended memory drivers are currently available for the NES.</P>
<H2><A NAME="ss5.3">5.3</A> <A HREF="#toc5.3">Joystick drivers</A>
</H2>
<P>
<DL>
<DT><B><CODE>nes-stdjoy.joy (nes_stdjoy)</CODE></B><DD>
<P>A joystick driver for the standard four buttons joypad is available.</P>
</DL>
</P>
<P>The generic interface doesn't export the start and select buttons. To
test for those, use the defines in nes.h instead of the generic masks.</P>
<P>Example:
<BLOCKQUOTE><CODE>
<PRE>
if (joy_read(0) & KEY_A)
</PRE>
</CODE></BLOCKQUOTE>
</P>
<H2><A NAME="ss5.4">5.4</A> <A HREF="#toc5.4">Mouse drivers</A>
</H2>
<P>No mouse drivers are currently available for the NES.</P>
<H2><A NAME="ss5.5">5.5</A> <A HREF="#toc5.5">RS232 device drivers</A>
</H2>
<P>No serial drivers are currently available for the NES.</P>
<H2><A NAME="s6">6.</A> <A HREF="#toc6">Limitations</A></H2>
<H2><A NAME="ss6.1">6.1</A> <A HREF="#toc6.1">Disk I/O</A>
</H2>
<P>The existing library for the NES doesn't implement C file
I/O. There are no hacks for the <CODE>read()</CODE> and <CODE>write()</CODE> routines.</P>
<P>To be more concrete, this limitation means that you cannot use any of the
following functions (and a few others):</P>
<P>
<UL>
<LI>fclose</LI>
<LI>fopen</LI>
<LI>fread</LI>
<LI>fprintf</LI>
<LI>fputc</LI>
<LI>fscanf</LI>
<LI>fwrite</LI>
<LI>...</LI>
</UL>
</P>
<H2><A NAME="s7">7.</A> <A HREF="#toc7">Other hints</A></H2>
<H2><A NAME="s8">8.</A> <A HREF="#toc8">License</A></H2>
<P>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.</P>
<P>Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:</P>
<P>
<OL>
<LI> 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.</LI>
<LI> Altered source versions must be plainly marked as such, and must not
be misrepresented as being the original software.</LI>
<LI> This notice may not be removed or altered from any source
distribution.</LI>
</OL>
</P>
</BODY>
</HTML>