sim65 Users Guide

Stefan A. Haubenthal,
Brad Smith


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

1. Overview

2. Usage

3. Input and output

4. Creating a Test in C

5. Creating a Test in Assembly

6. Copyright


1. Overview

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

2. Usage

The simulator is called as follows:

        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

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 1.

A timeout from -x will exit with 2.

2.1 Command line options in detail

Here is a description of all the command line options:

-h, --help

Print the short option summary shown above.

-c, --cycles

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

-v, --verbose

Increase the simulator verbosity.

-V, --version

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

-x num

Exit simulator after num cycles.

3. Input and output

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

sim65 --verbose --verbose samples/gunzip65
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)

4. Creating a Test in C

For a C test linked with --target sim6502 and the sim6502.lib library, command line arguments to sim65 will be passed to main, and the return value from main will become sim65's exit code. The stdlib.h exit function may also be used to terminate with an exit code.

Exit codes are limited to an unsigned 8 bit value. (E.g. returning -1 will give an exit code of 255.)

The standard C library high level file input and output is functional. A sim65 application can be written like a command line application, providing command line arguments to main and using the stdio.h interfaces to interact with the console or access files.

Internally, file input and output is provided at a lower level by a set of built-in paravirtualization functions (see below).

Example:

#include <stdio.h>
int main()
{
    printf("Hello!\n");
    return 5;
}

// Build and run:
//   cl65 -t sim6502 -o example.prg example.c
//   sim65 example.prg

// Build and run, separate steps:
//   cc65 -t sim6502 -o example.s example.c
//   ca65 -t sim6502 -o example.o example.s
//   ld65 -t sim6502 -o example.prg example.o sim6502.lib
//   sim65 example.prg

5. Creating a Test in Assembly

Though a C test may also link with assembly code, a pure assembly test can also be created.

Link with --target sim6502 or --target sim65c02 and the corresponding library, define and export _main as an entry point, and the sim65 library provides two ways to return an 8-bit exit code:

Example:

.export _main
_main:
    lda #5
    rts

; Build and run:
;   cl65 -t sim6502 -o example.prg example.s
;   sim65 example.prg

; Build and run, separate steps:
;   ca65 -t sim6502 -o example.o example.s
;   ld65 -t sim6502 -o example.prg example.o sim6502.lib
;   sim65 example.prg

Internally, the binary program file has a 12 byte header provided by the library:

Other internal details:

6. Copyright

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:

  1. 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.
  2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
  3. This notice may not be removed or altered from any source distribution.