mirror of https://github.com/cc65/cc65.git
214 lines
6.4 KiB
Plaintext
214 lines
6.4 KiB
Plaintext
<!doctype linuxdoc system> <!-- -*- text-mode -*- -->
|
|
|
|
<article>
|
|
|
|
<title>sim65 Users Guide
|
|
<author><url url="mailto:polluks@sdf.lonestar.org" name="Stefan A. Haubenthal">,<newline>
|
|
<url url="mailto:bbbradsmith@users.noreply.github.com" name="Brad Smith">
|
|
|
|
|
|
<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 should 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>
|
|
|
|
sim65 will exit with the error code of the simulated program,
|
|
which is limited to an 8-bit result 0-255.
|
|
|
|
An error in sim65, like bad arguments or an internal problem will exit with <tt/1/.
|
|
|
|
A timeout from <tt/-x/ will exit with <tt/2/.
|
|
|
|
|
|
<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 sim6502/ 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.
|
|
|
|
The standard C library high level file input and output is functional.
|
|
A sim65 application can be written like a command line application,
|
|
providing arguments to <tt/main/ and using the <tt/stdio.h/ interfaces.
|
|
|
|
Internally, file input and output is provided at a lower level by
|
|
a set of built-in paravirtualization functions (<ref id="paravirt-internal" name="see below">).
|
|
|
|
|
|
<sect>Creating a Test in Assembly<p>
|
|
|
|
Assembly tests may similarly be assembled and linked with
|
|
<tt/--target sim6502/ or <tt/--target sim65c02/.
|
|
Define and export <tt/_main/ as an entry point,
|
|
and the sim65 library provides two ways to return an 8-bit exit code:
|
|
|
|
<itemize>
|
|
|
|
<item>Return from <tt/_main/ with the exit code in <tt/A/.
|
|
|
|
<item><tt/jmp exit/ with the code in <tt/A/.
|
|
|
|
</itemize>
|
|
|
|
The binary file has a 12 byte header:
|
|
|
|
<itemize>
|
|
|
|
<item>5 byte <bf/signature/: <tt/$73, $69, $6D, $36, $35/ or <tt/'sim65'/
|
|
|
|
<item>1 byte <bf/version/: <tt/2/
|
|
|
|
<item>1 byte <bf/CPU type/: <tt/0/ = 6502, <tt/1/ = 65C02
|
|
|
|
<item>1 byte <bf/sp address/: the zero page address of the C parameter stack pointer <tt/sp/ used by the paravirtualization functions
|
|
|
|
<item>1 word <bf/load address/: where to load the data from the file into memory (default: <tt/$0200/)
|
|
|
|
<item>1 word <bf/reset address/: specifies where to begin execution after loading (default: <tt/$0200/)
|
|
|
|
</itemize>
|
|
|
|
Other internal details:
|
|
|
|
<itemize>
|
|
|
|
<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 the given <bf/reset address/.
|
|
|
|
<item>The <tt/exit/ address is <tt/$FFF9/.
|
|
Jumping to this address will terminate execution with the A register value as an exit code.
|
|
|
|
<label id="paravirt-internal">
|
|
<item>Several bytes immediately below the vector table are reserved for paravirtualization functions.
|
|
Except for <tt/exit/, a <tt/JSR/ to one of these addresses will return immediately after performing a special function.
|
|
These use cc65 calling conventions, and are intended 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>
|