1<!doctype linuxdoc system>      <!-- -*- text-mode -*- -->
2
3<article>
4
5<title>sim65 Users Guide
6<author><url url="mailto:polluks@sdf.lonestar.org" name="Stefan A. Haubenthal">,<newline>
7<url url="mailto:bbbradsmith@users.noreply.github.com" name="Brad Smith">
8
9
10<abstract>
11sim65 is a simulator for 6502 and 65C02 CPUs. It allows to test target
12independent code.
13</abstract>
14
15<!-- Table of contents -->
16<toc>
17
18<!-- Begin the document -->
19
20<sect>Overview<p>
21
22
23sim65 is used as part of the toolchain to test 6502 or 65C02 code.
24The binary to test should be compiled with <tt/--target sim6502/ or <tt/--target sim65c02/.
25
26
27<sect>Usage<p>
28
29The simulator is called as follows:
30
31<tscreen><verb>
32        Usage: sim65 [options] file [arguments]
33        Short options:
34          -h                    Help (this text)
35          -c                    Print amount of executed CPU cycles
36          -v                    Increase verbosity
37          -V                    Print the simulator version number
38          -x <num>              Exit simulator after <num> cycles
39
40        Long options:
41          --help                Help (this text)
42          --cycles              Print amount of executed CPU cycles
43          --verbose             Increase verbosity
44          --version             Print the simulator version number
45</verb></tscreen>
46
47
48<sect1>Command line options in detail<p>
49
50Here is a description of all the command line options:
51
52<descrip>
53
54  <tag><tt>-h, --help</tt></tag>
55
56  Print the short option summary shown above.
57
58
59  <tag><tt>-c, --cycles</tt></tag>
60
61  Print the number of executed CPU cycles when the program terminates.
62  The cycles for the final "<tt>jmp exit</tt>" are not included in this
63  count.
64
65
66  <tag><tt>-v, --verbose</tt></tag>
67
68  Increase the simulator verbosity.
69
70
71  <tag><tt>-V, --version</tt></tag>
72
73  Print the version number of the utility. When submitting a bug report,
74  please include the operating system you're using, and the compiler
75  version.
76
77
78  <tag><tt>-x num</tt></tag>
79
80  Exit simulator after num cycles.
81</descrip>
82
83
84<sect>Input and output<p>
85
86The simulator will read one binary file per invocation and can log the
87program loading and paravirtualization calls to stderr.
88
89Example output for the command
90<tscreen><verb>
91sim65 --verbose --verbose samples/gunzip65
92</verb></tscreen>
93<tscreen><verb>
94Loaded 'samples/gunzip65' at $0200-$151F
95PVWrite ($0001, $13C9, $000F)
96GZIP file name:PVWrite ($0001, $151F, $0001)
97
98PVRead ($0000, $FFD7, $0001)
99PVOpen ("", $0001)
100PVRead ($0003, $1520, $6590)
101PVClose ($0003)
102PVWrite ($0001, $13D9, $000F)
103Not GZIP formatPVWrite ($0001, $151F, $0001)
104
105PVExit ($01)
106</verb></tscreen>
107
108
109<sect>Creating a Test in C<p>
110
111For a C test compiled and linked with <tt/--target sim6502/ the
112command line arguments to <tt/sim65/ will be passed to <tt/main/,
113and the return value from <tt/main/ will become sim65's exit code.
114The <tt/exit/ function may also be used to terminate with an exit code.
115
116Exit codes are limited to 8 bits.
117
118The standard C library high level file input and output is functional.
119A sim65 application can be written like a command line application,
120providing arguments to <tt/main/ and using the <tt/stdio.h/ interfaces.
121
122Internally, file input and output is provided at a lower level by
123a set of built-in paravirtualization functions (<ref id="paravirt-internal" name="see below">).
124
125
126<sect>Creating a Test in Assembly<p>
127
128Assembly tests may similarly be assembled and linked with
129<tt/--target sim6502/ or <tt/--target sim65c02/,
130and the sim65 library provides an <tt/exit/ symbol that the program may <tt/JMP/
131to terminate with the current A register value as an exit code.
132
133The binary file has a 12 byte header:
134
135<itemize>
136
137<item>5 byte <bf/signature/: <tt/$73, $69, $6D, $36, $35/ or <tt/'sim65'/
138
139<item>1 byte <bf/version/: <tt/2/
140
141<item>1 byte <bf/CPU type/: <tt/0/ = 6502, <tt/1/ = 65C02
142
143<item>1 byte <bf/sp address/: the zero page address of the C parameter stack pointer <tt/sp/ used by the paravirtualization functions
144
145<item>1 word <bf/load address/: where to load the data from the file into memory (default: <tt/$0200/)
146
147<item>1 word <bf/reset address/: specifies where to begin execution after loading (default: <tt/$0200/)
148
149</itemize>
150
151Other internal details:
152
153<itemize>
154
155<item>The entire 64 kilobyte address space is writeable RAM.
156Aside from the loaded binary, the reset vector at <tt/$FFFC/ will be
157pre-loaded with the given <bf/reset address/.
158
159<item>The <tt/exit/ address is <tt/$FFF9/.
160Jumping to this address will terminate execution with the A register value as an exit code.
161
162<label id="paravirt-internal">
163<item>Several bytes immediately below the vector table are reserved for paravirtualization functions.
164Except for <tt/exit/, a <tt/JSR/ to one of these addresses will return immediately after performing a special function.
165These use cc65 calling conventions, and are intended for use with the sim65 target C library.
166
167<item><tt/IRQ/ and <tt/NMI/ events will not be generated, though <tt/BRK/
168can be used if the IRQ vector at <tt/$FFFE/ is manually prepared by the test code.
169
170</itemize>
171
172
173<sect>Copyright<p>
174
175sim65 (and all cc65 binutils) are (C) Copyright 1998-2000 Ullrich von
176Bassewitz. For usage of the binaries and/or sources the following conditions
177do apply:
178
179This software is provided 'as-is', without any expressed or implied
180warranty.  In no event will the authors be held liable for any damages
181arising from the use of this software.
182
183Permission is granted to anyone to use this software for any purpose,
184including commercial applications, and to alter it and redistribute it
185freely, subject to the following restrictions:
186
187<enum>
188<item>  The origin of this software must not be misrepresented; you must not
189        claim that you wrote the original software. If you use this software
190        in a product, an acknowledgment in the product documentation would be
191        appreciated but is not required.
192<item>  Altered source versions must be plainly marked as such, and must not
193        be misrepresented as being the original software.
194<item>  This notice may not be removed or altered from any source
195        distribution.
196</enum>
197
198</article>
199