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