cc65/doc/sim65.sgml

<!doctype linuxdoc system>      <!-- -*- text-mode -*- -->

<article>

<title>sim65 Users Guide
<author><url url="mailto:polluks@sdf.lonestar.org" name="Stefan A. Haubenthal">

<abstract>
sim65 is a simulator for 6502 and 65C02 CPUs. It allows to test target
independent code.
</abstract>

<!-- Table of contents -->
<toc>

<!-- Begin the document -->

<sect>Overview<p>


sim65 is used as part of the toolchain to test 6502 or 65C02 code.
The binary to test needs to be compiled with <tt/--target sim6502/ or <tt/--target sim65c02/.


<sect>Usage<p>

The simulator is called as follows:

<tscreen><verb>
        Usage: sim65 [options] file [arguments]
        Short options:
          -h                    Help (this text)
          -c                    Print amount of executed CPU cycles
          -v                    Increase verbosity
          -V                    Print the simulator version number
          -x <num>              Exit simulator after <num> cycles

        Long options:
          --help                Help (this text)
          --cycles              Print amount of executed CPU cycles
          --verbose             Increase verbosity
          --version             Print the simulator version number
</verb></tscreen>


<sect1>Command line options in detail<p>

Here is a description of all the command line options:

<descrip>

  <tag><tt>-h, --help</tt></tag>

  Print the short option summary shown above.


  <tag><tt>-c, --cycles</tt></tag>

  Print the number of executed CPU cycles when the program terminates.
  The cycles for the final "<tt>jmp exit</tt>" are not included in this
  count.


  <tag><tt>-v, --verbose</tt></tag>

  Increase the simulator verbosity.


  <tag><tt>-V, --version</tt></tag>

  Print the version number of the utility. When submitting a bug report,
  please include the operating system you're using, and the compiler
  version.


  <tag><tt>-x num</tt></tag>

  Exit simulator after num cycles.
</descrip>


<sect>Input and output<p>

The simulator will read one binary file per invocation and can log the
program loading and paravirtualization calls to stderr.

Example output for the command
<tscreen><verb>
sim65 --verbose --verbose samples/gunzip65
</verb></tscreen>
<tscreen><verb>
Loaded 'samples/gunzip65' at $0200-$151F
PVWrite ($0001, $13C9, $000F)
GZIP file name:PVWrite ($0001, $151F, $0001)

PVRead ($0000, $FFD7, $0001)
PVOpen ("", $0001)
PVRead ($0003, $1520, $6590)
PVClose ($0003)
PVWrite ($0001, $13D9, $000F)
Not GZIP formatPVWrite ($0001, $151F, $0001)

PVExit ($01)
</verb></tscreen>


<sect>Creating a Test in C<p>

For a C test compiled and linked with <tt/--target sim65/ the
command line arguments to <tt/sim65/ will be passed to <tt/main/,
and the return value from <tt/main/ will become sim65's exit code.
The <tt/exit/ function may also be used to terminate with an exit code.
 
Exit codes are limited to 8 bits.

In addition to this, the simulator provides a set of built-in functions
for simple file input and output:

<tscreen><verb>
  int open (const char* name, int flags, ...);
  int __fastcall__ close (int fd);
  int __fastcall__ read (int fd, void* buf, unsigned count);
  int __fastcall__ write (int fd, const void* buf, unsigned count);
</verb></tscreen>


<sect>Creating a Test in Assembly<p>

Assembly tests may similarly be assembled ant linked with <tt/--target sim65/,
and the sim65 library provides an <tt/exit/ symbol that the program may <tt/JMP/
to terminate with the current A register value as an exit code.

Without using the provided target library, there are some relevant internal details:

<itemize>

<item>The binary input file has a 1 byte header. A value of 0 indicates 6502 simulation,
and 1 indicates 65C02.

<item>The rest of the input file, after the header, will be loaded at <tt/$0200/,
and execution will begin at <tt/$0200/.

<item>The entire 64 kilobyte address space is writeable RAM.
Aside from the loaded binary, the reset vector at <tt/$FFFC/ will be
pre-loaded with <tt/$0200/ as the start address.

<item>The <tt/exit/ address is <tt/$FFF1/.
Jumping to this address will terminate execution with the A register value as an exit code.

<item>The built-in functions are provided by 6 "paravirtualization" hooks present at
<tt/$FFF0-$FFF5/. Except for <tt/exit/, a <tt/JSR/ to one of these
addresses will return immediately after performing a special function,
intended only for use with the sim65 target C library.

<item><tt/IRQ/ and <tt/NMI/ events will not be generated, though <tt/BRK/
can be used if the IRQ vector at <tt/$FFFE/ is manually prepared by the test code.

</itemize>


<sect>Copyright<p>

sim65 (and all cc65 binutils) are (C) Copyright 1998-2000 Ullrich von
Bassewitz. For usage of the binaries and/or sources the following conditions
do apply:

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.

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:

<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.
</enum>

</article>