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.
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
--cpu <type> Override CPU type (6502, 65C02, 6502X)
--trace Enable CPU trace
--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.
Here is a description of all the command line options:
-h, --helpPrint the short option summary shown above.
-c, --cyclesPrint the number of executed CPU cycles when the program terminates.
The cycles for the final "jmp exit" are not included in this
count.
--cpu <type>Specify the CPU type to use while executing the program. This CPU type is normally determined from the program file header, but it can be useful to override it.
--tracePrint a single line of information for each instruction or interrupt that is executed by the CPU to stdout.
-v, --verboseIncrease the simulator verbosity.
-V, --versionPrint the version number of the utility. When submitting a bug report, please include the operating system you're using, and the compiler version.
-x numExit simulator after num cycles.
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)
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
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:
_main with the exit code in A.
jmp exit with the code in A. (.import exit from the sim65 library.)
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:
$73, $69, $6D, $36, $35 or 'sim65'
2
0 = 6502, 1 = 65C02
sp used by the paravirtualization functions
$0200)
$0200)
Other internal details:
$FFFC will be
pre-loaded with the given reset address.
exit address is $FFF9.
Jumping to this address will terminate execution with the A register value as an exit code.
exit, a 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.
IRQ and NMI events will not be generated, though BRK
can be used if the IRQ vector at $FFFE is manually prepared by the test code.
sim6502 or sim65c02 targets provide a default configuration,
but if customization is needed sim6502.cfg or sim65c02.cfg might be used as a template.
The sim65 simulator supports a memory-mapped counter peripheral that manages a number of 64-bit counters that are continuously updated as the simulator is running. For each counter, it also provides a 64 bit "latching" register.
The functionality of the counter peripheral is accessible through 3 registers:
PERIPHERALS_COUNTER_LATCH ($FFC0, write-only)PERIPHERALS_COUNTER_SELECT ($FFC1, read/write)PERIPHERALS_COUNTER_VALUE ($FFC2..$FFC9, read-only)These three registers are used as follows.
When a program explicitly requests a "counter latch" operation by writing any value
to the PERIPHERALS_COUNTER_LATCH address ($FFC0), all live registers are simultaneously
copied to the latch registers. They will keep their newly latched values until another latch
operation is requested.
The PERIPHERALS_COUNTER_SELECT address ($FFC1) register holds an 8-bit value that
specifies which 64-bit latch register is currently readable through the PERIPHERALS_COUNTER_VALUE
address range. Six values are currently defined:
Values $00 to $03 provide access to the latched (frozen) value of their respective live
counters at the time of the last write to PERIPHERALS_COUNTER_LATCH.
When PERIPHERALS_COUNTER_SELECT equals $80, the PERIPHERALS_COUNTER_VALUE
will be a 64-bit value corresponding to the number of nanoseconds elapsed since the Unix epoch
(Midnight, Jan 1st, 1970 UTC), at the time of the last latch operation.
When PERIPHERALS_COUNTER_SELECT equals $81, the high 32 bits of PERIPHERALS_COUNTER_VALUE
will be a 32-bit value corresponding to the number of seconds elapsed since the Unix epoch (Midnight, Jan 1st,
1970 UTC), at the time of the last latch operation. The low 32 bits of
PERIPHERALS_COUNTER_VALUE will hold the nanoseconds since the start of that second.
The two different wallclock-time latch registers will always refer to precisely the same time instant. For some applications, the single 64-bit value measured in nanoseconds will be more convenient, while for other applications, the split 32/32 bits representation with separate second and nanosecond values will be more convenient.
Note that the time elapsed since the Unix epoch is an approximation, as the implementation depends on the way POSIX defines time-since-the-epoch. Unfortunately, POSIX incorrectly assumes that all days are precisely 86400 seconds long, which is not true in case of leap seconds. The way this inconsistency is resolved is system dependent.
On reset, PERIPHERALS_COUNTER_SELECT is initialized to zero. If the PERIPHERALS_COUNTER_SELECT
register holds a value other than one of the six values described above, all PERIPHERALS_COUNTER_VALUE
bytes will read as zero.
The PERIPHERALS_COUNTER_VALUE addresses ($FFC2..$FFC9) are used to read to currently
selected 64-bit latch register value. Address $FFC2 holds the least significant byte (LSB),
while address $FFC9 holds the most significant byte (MSB).
On reset, all latch registers are reset to zero. Reading any of the PERIPHERALS_COUNTER_VALUE
bytes before the first write to PERIPHERALS_COUNTER_LATCH will yield zero.
Example:
/* This example uses the peripheral support in sim65.h */
#include <stdio.h>
#include <sim65.h>
static void print_current_counters(void)
{
peripherals.counter.latch = 0; /* latch values */
peripherals.counter.select = COUNTER_SELECT_CLOCKCYCLE_COUNTER;
printf("clock cycles ............... : %08lx %08lx\n", peripherals.counter.value32[1], peripherals.counter.value32[0]);
peripherals.counter.select = COUNTER_SELECT_INSTRUCTION_COUNTER;
printf("instructions ............... : %08lx %08lx\n", peripherals.counter.value32[1], peripherals.counter.value32[0]);
peripherals.counter.select = COUNTER_SELECT_WALLCLOCK_TIME;
printf("wallclock time ............. : %08lx %08lx\n", peripherals.counter.value32[1], peripherals.counter.value32[0]);
peripherals.counter.select = COUNTER_SELECT_WALLCLOCK_TIME_SPLIT;
printf("wallclock time, split ...... : %08lx %08lx\n", peripherals.counter.value32[1], peripherals.counter.value32[0]);
printf("\n");
}
int main(void)
{
print_current_counters();
print_current_counters();
return 0;
}
The sim65 simulator supports a memory-mapped peripheral that allows control of the simulator behavior itself.
The sim65 control peripheral interface consists of 2 registers:
PERIPHERALS_SIMCONTROL_CPUMODE ($FFCA, read/write)PERIPHERALS_SIMCONTROL_TRACEMODE ($FFCB, read/write)Address PERIPHERALS_SIMCONTROL_CPUMODE allows access to the currently active CPU mode.
Possible values are CPU_6502 (0), CPU_65C02 (1), and CPU_6502X (2). For specialized applications, it may be useful to switch CPU models at runtime; this is supported by writing 0, 1, or 2 to this address. Writing any other value will be ignored.
Address PERIPHERALS_SIMCONTROL_TRACEMODE allows inspection and control of the currently active
CPU tracing mode.
A value of 0 means tracing is disabled; a value of $7F fully enables tracing. The 7 lower bits of the value actually provide control over which fields are printed; see below for an explanation of the seven fields.
Having the ability to enable/disable tracing on the fly can be a useful debugging aid. For example, it can be used to enable tracing for short fragments of code. Consider the following example:
/* This example uses the TRACE_ON and TRACE_OFF macros defined in sim65.h */
#include <stdio.h>
#include <sim65.h>
unsigned x;
int main(void)
{
TRACE_ON();
x = 0x1234; /* We want to see what happens here. */
TRACE_OFF();
return 0;
}
This small test program, when compiled with optimizations enabled (-O), produces the output trace below:
70 232 022E A2 12 ldx #$12 A=7F X=00 Y=04 S=FD Flags=nvdizC SP=FFBC
71 234 0230 A9 34 lda #$34 A=7F X=12 Y=04 S=FD Flags=nvdizC SP=FFBC
72 236 0232 8D C8 02 sta $02C8 A=34 X=12 Y=04 S=FD Flags=nvdizC SP=FFBC
73 240 0235 8E C9 02 stx $02C9 A=34 X=12 Y=04 S=FD Flags=nvdizC SP=FFBC
74 244 0238 A9 00 lda #$00 A=34 X=12 Y=04 S=FD Flags=nvdizC SP=FFBC
75 246 023A 8D CB FF sta $FFCB A=00 X=12 Y=04 S=FD Flags=nvdiZC SP=FFBC
The example output shows the full trace format, consisting of the following seven fields:
x = 0x1234;'
starts at the 70th CPU instruction since the start of the simulator, and takes four 6502 instructions.
The two instructions that follow correspond to the execution of the TRACE_OFF' macro
that disables tracing.Writing a specific value to PERIPHERALS_SIMCONTROL_TRACEMODE will control which of these
seven fields are displayed. The following values are defined to denote the seven fields:
For example, writing the value $16 to PERIPHERALS_SIMCONTROL_TRACEMODE will only display
the program counter, instruction assembly, and CPU registers fields.
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: