CPU Simulator And Assembler

This is an HTML/Javascript CPU simulator and assembler for the CPU I designed. Originally, I created this CPU on paper many years ago for a homework assignment in college. More recently, I implemented my design in the Logisim (and Logisim Evolution) logic simulator, and eventually it ran on an FPGA. Refer to the Video Series section for links to my youtube series about this design.

(I purposely used an older browser for the screenshots because I prefer the 3d look over the flat button look of some modern browsers.)

Setup and Running

OPTIONAL: If you want a gradual transition between Dark and Light modes, uncomment the line containing transition: color 300ms, background-color 300ms;

There are various ways of starting up this webpage. If your browser is in your search path you could simply do the following, for example, at a command prompt:

firefox sim.html

Or you could start your browser and use your browser's "Open File" (or equivalent) menu option. Or you could use the file:/// URI/protocol and specify the whole path.

BTW, if you prefer to have the assembler be in a separate tab, you could use the provided assem.html, but you would lose the automatic loading of the program into the simulator.

For a live demo, go to https://mrmcsoftware.github.io/CPUsimulator but do try to use your own copy instead. Since the file loading function will only upload files from your computer (not a github repo), for the Live Demo, I've added the Examples: drop-down selection button at the top. You can select the example program you want to run, then click Start.

Note: Ignore index.html and programs.js. They are only there to make Github Pages work.

URL Parameters

These are optional parameters you can use if you don't like the defaults. Use these like this, for example (If specifying this on a terminal commandline, you probably will need to escape the special characters, depending on your OS (for example: sim.html?dark=false\&assembler=true if using Linux, "sim.html?dark=false&assembler=true" if using Windows)):

sim.html?dark=false&assembler=true&wordwrap=off&midimode=off&image=2

• dark=false - Turn off dark mode
• assembler=true - Show the assembler at startup
• midimode=off - The assembly program will be providing frequencies rather than midi note numbers
• verbose=on - Provide some extra simulation information in the browser's console
• wordwrap=off - Don't use word wrap on TTY screen
• image={number} - Select which fancy "CPU Simulator" image to use (0, 1, 2, 3, 4, or -1 (-1 for no image))

Using The Simulator

All the buttons, input boxes, checkboxes, and file selectors have tool tips to better explain the function. Hover your pointer over the desired element to view the tool tip.

The I/O panel contains the Video screen (256x256, 128x128 (scaled to 256x256), and 320x240), Y and A register LED displays, a 12x7 LED Matrix display, a Strobe LED and a CPU status LED below it (green means program running, red means program (CPU) halted).

Below the I/O panel is the TTY screen. Your program can output text to this TTY screen. After you click Start, keyboard focus will automatically switch to the TTY screen and you will be able to press keys which will then be given to your program via the DATAIN instruction. If you click elsewhere after clicking Start, you would need to first click the mouse pointer in the TTY screen for any key presses to be registered. For any subsequent key presses, you won't have to click the TTY screen again, unless you have clicked somewhere else since the click in the TTY screen. Note: any key presses that occur before a DATAIN is executed will be buffered and can be seen in the blue textbox (labeled KB) located above the checkboxes.

To the right of the I/O panel and TTY screen is the disassembly panel. You can click the Disassemble button to disassemble (convert your machine code (the running program) to assembly code) the machine code in the simulated computer's RAM. The image will be replaced with the disassembled code. Click Clear Disassembly to remove the disassembled code and return the image.

If you click the Instruction TTY checkbox on, an Instruction TTY will appear below the Disassembly panel. When your program runs, the currently running instruction and a few previously run instructions will be shown. Click the Instruction TTY checkbox off to remove the panel.

Note: These panels can be resized by clicking on and dragging the resize indicators at the bottom-right corner of the panels.

To assemble a program, click the Assembler checkbox on. The assembler section will appear below the simulator. Type (or Paste (by clicking the right mouse button in the panel)) your assembly code in the leftmost text box. You can also click the file upload box (some browsers call it Browse) below the assembly panel to select a file to load instead. Click the Assemble button to assemble your program. The text box to the right will show error messages and general information. You can control what information is shown by selecting from the drop-down list under the text box. The Save As: and Save Machine Code As: buttons will save your assembly source code and your assembled machine code (once assembled) respectively. The filename will be untitled.asm and untitled respectively if not specified in the colored text boxes near the buttons. Any saved machine code can be loaded into the simulator by choosing it with the file upload box at the top right corner of the simulator section.

Note: Even though I use uppercase for all the CPU instructions and assembler directives in the sample programs and in the lists below, lowercase can also be used (even any combination of lowercase and uppercase).

Once assembled, your program will be in the simulated computer's RAM, and you can click the Start button on the simulator to run it. You can click the Go To Top button to conveniently go back to the simulator.

Pausing and Stepping

Usually, you would first click the Start button to start running your program. You can pause the running program by clicking the Pause button. Click on Resume when you want to continue running the program. Or click the Step button to execute a CPU instruction on each click (and then click Resume to return to normal execution if desired). You could also click Pause before clicking Start, and then Step to step from the start.

Halting

The CPU's HALT instruction will stop the simulation of your program (and so will the Reset button). As a safety measure, when loading in a previously assembled program into the simulator, or when assembling using the assembler, a HALT instruction is automatically added at the end of the program to make sure the program will end instead of executing whatever might be in the simulated computer's RAM after your program. Be aware of that when assigning memory locations to your variables.

Speed

I use Javascript's setInterval to execute a CPU instruction at most once every millisecond (since setInterval is in milliseconds). Unfortunately, this means the fastest the simulation could be is 1000Hz, which is fairly slow. You can set this interval timer by entering a millisecond value in the yellow text input box at the top.

You can check the Fast Mode (Be Careful) checkbox which will bypass setInterval by running all the CPU instructions in your program in one shot. Be careful though, NO simulator control or browser function will be available until your program either finishes (with a HALT instruction) or reaches a DATAIN instruction (unless you have FASTINTR in various places in your code. I'll cover FASTINTR in the next paragraph). If neither can happen in your program, an infinite loop will occur and you will likely need to kill your browser (via whatever method is available in your OS). SO BE CAREFUL when selecting this option. If a DATAIN instruction is reached, Fast Mode will be turned off and you would have to click it on again (after a key press has satisfied the DATAIN loop (if there is one in your program)) if you want it back on. To avoid having to repeatedly click the Fast Mode checkbox and the TTY screen back and forth, you can press Ctrl-Shift in the TTY screen (while the TTY screen has focus) to turn on Fast Mode - that way the TTY screen won't lose focus. If the left Ctrl-Shift combination doesn't work for you, try the right Ctrl-Shift, OR hold the Ctrl key down while pressing Shift twice (probably a "browser thing"). Another caveat: if your program takes too long to either reach HALT or DATAIN, I suspect the browser's "safety feature" allowing you to stop the script will kick in, except the browser will perhaps be too busy to put the dialog up, thus creating a worse situation than it was supposed to solve. This is just a guess though.

There is a partial solution to this problem. FASTINTR will interrupt the continuous run loop temporarily allowing the browser to do whatever function it needs to do, and then go back to Fast Mode until the next FASTINTR, a HALT, or a DATAIN. It might be challenging to find the best places to put FASTINTR. Refer to the example program fractal.asm to see where I chose to put it - after each scanline of the generated fractal image.

Getting Data Into the Simulated Computer

The DATAIN CPU instruction will read from the simulated keyboard, the clock, and the (hypothetical) external device. The external device's value can be set (in hex) via the orange text input box at the top. For the most part, you wouldn't likely ever need to set it to anything, but it's there in case you want to. If the value is set to anything other than 0 (or nothing), any key press or clock value won't be accurate.

The Rest

The rest should be (I think) self-explanatory, so I won't cover the rest here.

GPU Version

simgpu.html is a version of the simulator that provides a simulated GPU. The GPU is based on my GPU Logisim component available on my github page. Refer to my GPU component github repo for a much more indepth description of its functions and how to program them. The only GPU functions that this web-based simulator doesn't do is the gradient paint and the XOR draw mode. XOR draw mode is available in Javascript but is apparently useless for "rubberbanding", etc. since it doesn't fully erase the previously XOR drawn primitive upon redraw due to antialiasing. Javascript has gradient paint, but it doesn't match Java's gradient paint (I don't think any language's gradient paint matches Java's). Load the GPU's RAM and/or ROM by clicking the buttons below the "Clear" buttons.

I've made this GPU version a separate web page since the added GPU functionality could conceivably reduce the speed of the rest of the simulated computer, so only use this version if you need the GPU.

Sample Programs

I've provided sample programs in the examples directory that you can look at and run on this simulator to better understand the instruction set, assembler directives, and the simulated computer's I/O. Both assembly source code (ending in