6502 Simulator IDE
Help Topics

• General info
6502 Simulator IDE is a powerful application designed to provide 6502 microprocessor users and educators, Commodore 64 (C64) fans and retrocomputing enthusiasts with user-friendly graphical development environment for Windows with integrated simulator (emulator), 6502 basic compiler, assembler, disassembler and debugger for the MOS Technology 6502 8-bit microprocessor, with a special mode to support WDC 65C02 (W65C02S) that is currently in production. Special tools for the simulation of various basic interpreters are also available, including C64 ROM simulation.

The main application window shows 6502 microprocessor internal registers (and flags) structure, mnemonics of the last executed instruction, mnemonics of the next instruction that will be executed, clock cycles and instructions counter and interrupt interface.

• File menu
- Clear Memory
This command restores the initial state of the 64K memory with address range $0000-$FFFF assumed to be attached to the CPU. The whole memory is cleared - filled with the value $00.
- Load Program
This command loads a program file into the CPU memory. The default extension is OBJ that is used for the binary images of the code, but the files in the Intel HEX format can also be used. Once loaded program file can be quickly reloaded by clicking on its location field on the main program interface. Loading the program code with this command clears all the memory first.
- Reload
Reloads the currently loaded program.
- Save Memory
This command saves the contents of the memory to a file. One can choose between OBJ and HEX extensions, and this feature can be used to convert the program files from one format to the other.
- Load Another Program File
Loads another program file without clearing the memory first. The program location label on the main window will not be affected. This command accepts OBJ and HEX files, but one can also select to load a C64 PRG file.

• Simulation menu
- Start
6502 Simulator IDE enters simulation mode and begins the execution of instructions starting from the memory location pointed by the Reset Vector at memory location $FFFC. One should select the appropriate simulation rate using the Rate menu.
- Step
This command is enabled only when Step By Step simulation rate is selected. Next instruction is executed on every click on keyboard shortcut F2.
- Stop
6502 Simulator IDE exits simulation mode and presents the information about the total number of executed instructions, duration of the simulation and real-time duration of the simulation in clock cycles.
- Run To Next BASIC Statement
This command is enabled when the loaded program file is generated by the integrated 6502 Basic Compiler and when the Basic Program Tracking option is turned on. It will start executing the instructions until the beginning of the next basic statement has been reached. The simulation will be switched then to Step By Step mode.

• Rate menu
It enables user to change the simulation rate. It is accessible during the simulation, also.
- Step By Step
The interval between consecutive instructions is at user will. When the simulator is in Step By Step mode, it is possible to change the values in all CPU internal registers, by clicking on the appropriate fields on the program interface. When this simulation rate is selected new main menu item 'STEP' will appear on the program interface. That will enable an easy access to Step command from the Simulation menu. There is also the keyboard shortcut F2.
- Slow
The interval is 1500 ms.
- Normal
The interval is 250 ms.
- Fast
The interval is around 50 ms.
- Extremely Fast
The interval is very short and is linearly dependent on the overall computer performance.
- Ultimate
The main simulator window is not continuously refreshed after every simulated instruction that significantly improve the simulation performance. The refresh interval can be changed using Change Ultimate Rate Refresh Interval command in Options menu. The number of opened simulation tools directly affects the simulation performance. This is the fastest simulation rate possible.

• Tools menu
- Memory Editor
This is access to the graphical interface for the 6502 Simulator CPU 64K memory. It has a scroll bar and is very easy to use. The value in the specific memory location can be changed by clicking on it. When the entered value is confirmed by pressing Enter key, edit box will automatically move to the next memory location. Edit box can be moved freely over the memory table using arrow keys and it can be closed by Esc key. The Focus SP command will bring to focus and mark the memory location pointed by the Stack Pointer. If Track R/W option is selected, the simulator will automatically focus and mark the last read and the last written memory location if they are in the user-defined memory range. The performance optimization option for the Ultimate simulation rate is on by default.
- Disassembler
6502 Simulator IDE has a very powerful internal disassembler that is started by this command. Disassembler is independent from the simulator and it has its own memory buffer. So, it is necessary to load the program file (binary OBJ image or Intel HEX file) into disassembler memory first. Auto Load Program Loaded in the Simulator is on by default. The disassembling process is initiated by an appropriate command from the disassembler menu. It starts from $0000 address. After the operation is completed disassembler will display the output listing file that can be saved with LST extension if needed. The available options and commands include Listing Without Opcodes (the generated listing can be used by assembler directly), Load Program File With Offset (this command can be used to load multiple program files into the disassembler memory buffer at different offset addresses), Disassemble From Address (allows entering offset address that will be used as the starting address for the disassembler), Skip Empty Memory Ranges (used to detect and skip blocks of disassembler memory buffer with $00 values).
- Peripheral Devices
This tool used to simulate the communication with the memory mapped peripheral devices. They are referred to here as I/O ports. Up to four basic I/O peripheral devices can be setup. The bytes written to a memory mapped out port are displayed graphically by showing the individual bits. If the device is configured as an input device, the value it supplies when the memory mapped in port is read can be set either by entering it directly (click on value label) or by toggling individual bits of the graphical representation. There is also one output terminal useful for viewing ASCII characters sent to the port, and one input terminal with buffer that can be filled in by using the Send String, Send Hex Bytes and Send Dec Bytes commands.
- Memory Editor 2
This command starts another Memory Editor tool with the same features.
- Memory Editor 3
This command starts yet another Memory Editor tool with the same features. So, it is possible to simultaneously view/edit three different memory ranges during the simulation.
- Input/Output Terminal
This tool is designed to make it easy to communicate with various 6502 firmwares supporting serial input/output during the simulation of the code execution. The relevant information about the tool is displayed with the Info command. The interface is defined by the addresses of the input and output terminal memory mapped data and status registers, and the bit numbers in the status register that should serve the purpose of the Transmit Data Register Empty signal for the output terminal, and the Receive Data Register Full signal for the input terminal. Change Screen Color Scheme command is available.
- Commodore 64 Rom I/O Terminal
Commodore 64 Rom I/O Terminal simulation tool is designed to make it easy to communicate with C64 Rom code during the simulation of its execution. The relevant information about the tool is displayed with the Info command. It monitors some specific memory read and memory write accesses of the C64 Rom code to be able to simulate keyboard inputs and screen outputs. In that way it is possible to use C64 Basic interpreter just like on a real device. There is a command to open/close directly the C64 Video Memory Screen tool. Change Screen Color Scheme command is also available. Load PRG command will allow loading of the PRG files into C64 RAM memory. Ir requires that the number of simulated instructions must be at least 600000, that is needed for the C64 system initialization. This operation will switch to Step By Step simulation mode. The PRG files should be executed with either SYS or RUN basic commands. The correct info about this will be presented to the user. C64 PRG files can be generated with the integrated 6502 Basic Compiler.
- C64 Video Memory Screen
This tool displays the content of the C64 40x25 video memory starting from $0400 address. It supports original C64 codes for the letters and numbers. Several screen color schemes are available. The tool will display the last written video memory location.
- Video Memory Screen
This is a custom video memory display tool. Its setup includes starting address, columns and rows settings. Several screen color schemes are also available. The tool provides video memory range editing feature.
- Assembler
This command starts integrated assembler. Assembler source files can be edited, assembled and finally loaded into the simulator memory in the same graphical environment. Default extension is ASM. After the successful assembly process the internal assembler will generate two new files. One with OBJ extension that is binary image of the program and that can be directly loaded into the CPU memory, and the other with LST extension that is assembler listing used by the debugger. If Generate HEX File Also option is selected then program file in Intel HEX format will also be generated. This editor can also be used as the graphical interface for the external TASM assembler. It is only necessary to locate the executable file of the TASM assembler before the first use. More info can be found at the bottom of this file. The assembler comes with extensive list of powerful options and features that include support for bookmarks and breakpoints, and code execution tracking feature.
- Fast Debugger - Breakpoints Manager
This command starts integrated debugger that can be used to debug and monitor the program execution. If the assembler listing file of the program in memory does not exist, usable alternative listing will be generated by the internal disassembler. It is possible to define unlimited number of breakpoints by clicking on individual lines in the loaded program listing. When the simulation starts in faster rate modes it will automatically switch to Step By Step mode when reaching any of these breakpoints. The breakpoints are marked by red circles, and the current value of the PC register is marked by yellow arrow. There is an option to keep the PC pointer in focus during the simulation. Load and Save breakpoints commands are available. Visual appearance of the tool can be changed by horizontal resizing, and Change Color Scheme, Change Number Of Lines and Borders On/Off features. This tool features optimized for speed performance.
- BASIC Compiler
Powerful integrated 6502 BASIC Compiler editor window will be opened. It features source explorer, code tracking, bookmarks and breakpoints.
More information available in BASIC Compiler Reference Manual. It can be accessed from the Help menu of the main application window or from the basic compiler editor window. The compiler supports Boolean, Short, UShort, Integer, UInteger, Long, ULong and Single data types, with floating point math operations, and features also the special set of Commodore 64 related statements that can be used to generate working C64 PRG files.
- Floating Point Conversion Tool
This command starts the tool that converts real numbers to their four-byte single precision floating point representation. That representation is used for the 'Single' data type by the integrated basic compiler. There is also the inverse command, to calculate exact real number from the four floating point hex bytes.
- Simulation Log Viewer
This command starts integrated graphical tool that will log all the simulated instructions together with the values of all the 6502 registers and flags. The tool is designed for the debugging process.
- Watch Variables
During the simulation of programs written using integrated basic compiler, this tool can be used to watch the current values of all variables declared in the simulated basic program. It is also possible to add user defined variables to the list to monitor other memory locations of interest during the simulation. This feature is useful for memory monitoring for simulated program files, that are not compiled with the integrated basic compiler. User added variables will be remembered between sessions as long as the same program file is loaded in the simulator. Variables from the watch list can be easily removed with the Delete Variable command, so the list can contain variables of special interest only. Other commands and options include: Change Variable Value (can be also started by a single-click on the variable from the list), Display HEX Values, Confirm Delete, Track Variable Write Access, various sorting options. The window is resizable.
- External Modules
This tool should be used to establish automation interface with up to five external client/server modules. It is required to enter the class name supplied by external device in the form ApplicationName.ObjectName in order to establish connection with it. External client/server applications will be started and terminated automatically with 6502 Simulator IDE. More information available in External Modules Manual. It can be accessed from the Help menu of the main application window.

• Options menu
- Resize Windows
It is used to set the desired size scale to some of the application windows that are not resizable. Main simulator window is also included.
- Shortcuts Panel Configuration
This opens an easy to use interface for turning on and customizing the fancy-looking shortcuts panel on the main IDE window, for an easy access to the most frequently used menu commands. The panel can contain up to three lines of menu item shortcuts. All main IDE window menu items are available to be placed on the panel.
- Enable Unofficial Instructions
This option will enable the unofficial 6502 instructions. They will be available in the simulator, assembler and disassembler. The option is visually available on the main simulator window.
- Enable 65C02 Mode
Used to enable the special mode to support WDC 65C02 (W65C02S). All documented differences are implemented, including the support for the new instructions. The option is visually available on the main simulator window.
- Enable Logging
This option will set the simulator to log all the simulated instructions together with the values of all the 6502 registers and flags. The data will be saved to the LOG.TXT file in the application folder. This option does not interfere with the integrated graphical Simulation Log Viewer.
- JAM (KIL, HLT) Stops Simulation
This feature will work only if the Enable Unofficial Instructions option is turned on. If this option is selected the simulation will automatically stop when the unofficial JAM (KIL, HLT) instruction is reached (that covers the opcodes: $02, $12, $22, $32, $42, $52, $62, $72, $92, $B2, $D2, $F2). If it is not selected, the simulator will execute this instruction repeatedly.
- Infinite Loop Stops Simulation
Checking this option will set the simulator to automatically stop the simulation when an infinite loop (unconditional branch to the same address) is encountered.
- FF Power On Defaults
Toggling this option will switch between $00 and $FF initial values for the 6502 CPU registers.
- Refresh Memory Editor
If this option is selected and Memory Editor is started, the displayed memory range will be refreshed after every simulated instruction, in all simulation rate modes. This is useful if you want to monitor what is going on on the stack or elsewhere in the memory during the simulation.
- Show ASCII Characters
Used in the Memory Editor windows for the expanded display with the panel showing ASCII characters for the values in the memory locations.
- Refresh Breakpoints Manager
If this option is selected and Fast Debugger - Breakpoints Manager is started, it will be refreshed after every simulated instruction. If Hold PC In Focus option is also selected, that will enable user to watch live presentation of the program execution.
- Save Positions
With this option selected, the positions of the windows on the screen will be remembered.
- Save Always On Top
With this option selected, the Always On Top setting for all of the windows with this feature will be remembered between the sessions.
- Show Pop-up Info Message Boxes
When this option is enabled the confirmation boxes showing results of operations will be displayed and will require user response to be closed. Alternatively, the Info Message Frames will be displayed near the bottom edge of the windows.
- Configure Info Message Frames
Used to setup Info Message Frames display duration in seconds, and display mode (centered below or docked in the corner).
- Auto Start Options
With this utility users can define actions that will be performed on the application startup. These actions include automatic opening of various tools and simulation interfaces from the Tools menu and automatic loading of the last used files in the simulator, assembler and basic compiler.
- Change Clock Frequency
This command allows user to change the frequency parameter that is used for the calculation of the real-time duration of the simulation. The entered value in MHz is remembered for the future sessions. The default value is 4 MHz.
- Change Offset Address For OBJ Files Loading
Allows user to change the starting address that will be used for the binary image files (OBJ extension) loading into the 64K memory buffer. The entered value is remembered for the future sessions. The default value is $0000. This parameter value is ignored for the HEX files loading.
- Change Ultimate Rate Refresh Interval
This command allows user to change the refresh interval (in milliseconds) for the main simulation interface when the simulation is running at Ultimate rate. Its value however does not affect the simulation performance considerably. The default value is 500ms.
- Run To Next BASIC Statement Simulation Rate
Sets the simulation rate for the command Run To Next BASIC Statement (Normal-Ultimate).
- Basic Program Tracking
Currently simulated basic statement will appear highlighted in Basic compiler window when this option is enabled.
- Editor Setup
With this setup tool it is possible to change various properties of basic compiler and assembler code editors.
- Change Color Theme
This command will open a dialog with the rich list of available color themes, so that the user can change the application overall visual appearance.
- Change Main Font
Allows user to set the main font used in the application. One should be careful with this command because some font selections will not be displayed properly. The default font is Tahoma.
- Clear App Registry Settings
This command will delete all application registry settings, restoring the state of the first application start.

• Help menu
- Help Topics
This command will display Help Topics. This help file contains general information about the application with description of all menu items.
Help viewer window features navigation panel showing topics and subtopics of the displayed help file. Right-click on the navigation panel will show pop-up menu with Show All Subtopics and Hide All Subtopics commands. Single-click on the item from the navigation panel will move focus on the display panel to the appropriate position. Double-click on the topic item will show/hide its subtopics. The display panel shows the content of the loaded help file. Right-click will display pop-up menu containing various options and commands including: Copy, Copy RTF, Copy HTML, Print, Font Increase, Font Decrease, Font Reset, Always On Top. Help viewer window is resizable and will remember both its position and size. The vertical separator between navigation and display panels is movable and its position will also be saved after the viewer is closed.
- BASIC Compiler Reference Manual
BASIC Compiler Reference Manual will be displayed in the help viewer.
- External Modules Manual
External Modules Manual will be displayed in the help viewer.
- Show Tips
Initiates display of the selected tips related to the software usage.
- Check For Updates
This tool will enable user to establish connection with OshonSoft.com website to check out if there is a new software release available for download. Version log file will be displayed after the response from the website has been received. Handy Visit Download Page command is available.
- Bug Report Interface
This interface should be used to send the reports about possible bugs in software to OshonSoft.com. In addition to the user written part the full report will contain a part that is generated by the software (system report).
- About
This command will display the basic information about the software package.
- View License Information
This command will display the information about the installed license for the software.

• Interrupts info
Both interrupts are supported: the NMI interrupts (jumps to the address pointed by the appropriate NMI vector at the location $FFFA) and the IRQ interrupt (jumps to the address pointed by the IRQ vector at $FFFE). Interrupts are triggered by pressing the NMI and IRQ buttons on the interrupt interface. The simulation can be reset by pressing the RESET button.

• Assembler overview
Here is the basic info related to the internal assembler.

Constants
Assembler accepts wide range of formats and notations for the numeric constants:
- characters: "n", 'n', A'n'
- hex numbers: 0xnn, 00h, $nn, &hnn, &nn, H'nn'
- binary numbers: %nnnn, 0bnnnn, nnnnb, B'nnnn'
- decimal numbers: nnn, .nnn, D'nnn'
Numeric constants may contain # prefix.

Directives
Assembler supports ORG, EQU, DB (DEFB), DW (DEFW), DS (DEFS) and END directives. They can also be used with the dot prefix (like .EQU).
Additionally, BYTE can be used as the alias for DB, WORD as the alias for DW, RES (or BLOCK) as the alias for DS.
Label is a symbol name for the current memory location counter value.
- ORG directive alters the setting of the location counter.
- EQU directive creates a symbol/label with the value of the given expression.
- DB directive initializes memory with one or more byte values.
- DW directive initializes memory with one or more word (2-byte) values.
For DB and DW, multiple expressions separated by commas may be specified. Strings are also accepted. There is no limit for the number of arguments.
- DS directive is used to reserve memory for variables. It reserves the specified number of bytes in the memory space (and fills them with $00 value).
- END directive marks the end of the source file.
- 6502 specific NEWPAGE directive will advance the memory location counter to the beginning of the next memory page.
*= will be recognized as the ORG directive.
= will be recognized as the EQU directive.

Expressions
Numeric argument can contain the arithmetic operations (+,-,*,/,\) and the bitwise logical operations (&,|,^).
Parentheses in the expression are also supported. The assembler is able to evaluate any expression, no matter how complicated it is.
This is the list of binary operators based on the increasing precedence implemented: |,^,&,(+,-),(*,/,\).
The prefixes upper, high (>) and low (<) can be used to return byte 2, byte 1 and byte 0 of the numeric argument.
The assembler can work with the full range of the unsigned 4-byte integer values, so loww and highw prefixes are also available to return the low and high words of the argument.
All the prefixes are treated as unary operators by the expression evaluation engine.
PC and $ symbols can be used to represent the absolute address of the line of code (the location counter value).
For the same purpose one can use * symbol, but only if it is followed by + or - operators.

Here is one test example:
   lab1    equ 100*2  ;C8
           lab2 equ 0x1264
   lab3    = 2
   lab4    equ 0x2345
           lda #lab1-0x10
           lda #0x55
           lda #<lab2
           lda #55h^0xfe+1
           lda #$55
           lda #h'55'
           lda #-1
           lda #-lab3
           lda #0x55+0x10
           lda #0x10*8
           lda #128/lab3
           lda #$-2
           lda #pc+2
           lda #high (0x1234+lab4)
           lda #low lab4
           lda #-0x4-lab3
           lda # high highw 2000000000  ;77359400
           lda # high loww 2000000000  ;77359400
           lda # high loww -1  ;FFFFFFFF
           lda # high highw -1  ;FFFFFFFF
           lda # high loww -2000000000  ;88CA6C00
           lda # high highw -2000000000  ;88CA6C00
           lda # high loww 3000000000  ;B2D05E00
           lda # low highw 3000000000  ;B2D05E00
           lda # high highw 3000000000  ;B2D05E00

Macros
OshonSoft 6502 Simulator IDE integrated assembler in the current release does not support macros.
It will however accept the ca65 longbranch macros: JEQ, JNE, JMI, JPL, JCS, JCC, JVS, JVC.

TASM
If better performance is needed, assembler editor can be used as the graphical interface for the external TASM assembler.
The external assembler will be started with -65 -b command line options.
TASM assembler can be downloaded from:
https://www.oshonsoft.com/tasm32.zip
TASM user manual is included in the archive.