1 To start

You will need your own copy of the assembler. You can clone the assembler by using the menu item “File | Make a copy”, be sure to specify the (destination) Folder as some folder in your own Google Drive.

Also, every program should start with a nop instruction. This is due to a bug in Logisim that only seems to matter when Logisim is run from the CLI (command line interface).

2 The longer way

First use an editor to edit the source code in mnemonics.

Then copy-and-paste the code to column A of the source sheet of the assembler. If the assembler reports any errors, fix the errors in the editor, and repaste the entire program in column A of the “source” sheet.

Switch to the “RAM file” sheet, use the menu item “File | Download | Comma Separated Values” to download the CSV file.

On a command line, run the program. The exact command depends on the OS, but generally it is something like the following:

java -jar path/to/logisim310.jar path/to/processor0004.circ -load path/to/ramContent.csv -tty table > path/to/logFile.tsv

The way you specify a path depends on your operating system, please Google search for a tutorial that is specific to your operating system.

• ranContent.csv: this is the file that you downloaded earlier from the “RAM file” sheet of the assembler.
• logFile.tsv: this is the log file that is in a TSV (tab separated values) format.

Go back to the assembler, switch to the “traceRawData” sheet, then use the menu item “File | Import” to trigger the “Import file” dialog. Click “Upload”, select the logFile.tsv from earlier.

You will then be presented with the options of importing the TSV, be sure to follow these specifications:

• Import location: Replace Current Sheet
• Separator type: tab
• Convert text to numbers, dates, and formulas: uncheck

After the import, the “analysis” sheet displays the log of the execution of your code.

3 The shorter way

You can use riverSpider to automate a large portion of the steps. You can get the Linux/Unix/Mac OS version or the Windows Powershell version, depending on your operating system.

Read the README.md file for instruction to set up your own instance of riverSpider.

4 Reading the analysis sheet

• Column A: this is the address of the instruction that executed. You can cross reference this hexadecimal address with column W of the assemble sheet to find out exactly which instruction of your program corresponds to a particular trace entry
• Column B: if RAM is read from, there is an entry here. Note that there are “false entries” in this column for certain instructions. This means no every item is significant in column B.
• Column C: if RAM is written to, there is an entry here that specifies which location is overwritten by which value. Both the address and the content are specified in hexadecimal.
• Column D: if a register is updated, there is an entry here.
• Column E: if the flags register is updated, there is an entry here.

4.1 Skipping to the end

Some traces are very long. If you want to skip to the end, you can find the row number in the “summary” sheet, cell A1.

Skipping to the end of a trace is helpful if you just want to check to see if the program terminates with the correct outcome, or to find out how the program stopped.

4.2 Searching for specific items

Google Sheets offer some great features for searching and finding items. Use control-H or the menu item “Edit | Find and replace” to trigger the dialog box.

Do not replace any values in the analysis sheet, that will break the mechanism!

The search range control is very helpful if you want to find a pattern only in a specific column. For example, you may be interested in only when a register is updated, then the search can focus on column D. To specify column D, change the drop down of “Search” to “Specific range”, then specify “analysis!D:D” to search the entire column D.

Another great feature that is more advanced is “Search using regular expressions.” This allows you to use regular expressions to specify a pattern. This can be helpful in instances where a search is not for a specific value, but for a pattern that can be used to describe many individual values.