pythonRSC is an emulator for the RSC architecture written in Python.
With this program, you can generate bytecode of your program code for use in Logisim or just emulate program code outright. Additionally, you can debug your program and see its every step or even generate a control flow graph of your emulated program code.
There is an introduction video which goes over the basics of how to download and use the emulator.
There are nine registers in this architecture, each are named and explained below.
S: The stop register, if this register's value is 1, emulation is halted.
Z: The zero register, if this register's value is 1, ACC is currently 0.
IR: The instruction register, the emulator reads the value of this register to know what instruction to execute, can be seen here.
AR: The address register, any memory addresses that are going to be accessed are placed into this register, can be seen here.
DR: The data register, any values returned from a memory access will be put into this register, can be seen here.
PC: The program counter register, this register holds the value of the next instruction to be executed, can be seen here.
OUTR: The out register, the value in this register will be displayed on your Logisim board through a hexadecimal display.
ACC: The accumulator register, most instructions in this emulator operate on this register, used for arithmetic operations mainly.
R: No unique name, just a register, holds values to perform operations on ACC (i.e ADD, SUB, etc).
There are sixteen instructions in this architecture, each are named and explained below, along with a link to their implementation.
HALT: Sets the value of S to 1, halting emulation.
LDAC: Loads the value into ACC from the provided memory address operand.
STAC: Stores the current value of ACC into the provided memory address operand.
MVAC: Moves the current value from ACC into R, overwriting the current value.
MOVR: Moves the current value from R into ACC, overwriting the current value.
JMP: Sets PC to the provided memory address operand.
JMPZ: If Z is 1, sets PC to the provided memory address operand, otherwise increments PC by 1.
OUT: Moves the current value from ACC into OUTR.
SUB: Subtracts the current value in R from ACC, storing it in ACC.
ADD: Adds the current value in R to ACC, storing it in ACC.
INC: Increments the current value in ACC by 1.
CLAC: Sets the value of ACC to 0.
AND: Performs a bitwise AND of ACC and R, storing the result in ACC.
OR: Performs a bitwise OR of ACC and R, storing the result in ACC.
ASHR: Performs an arithmetic right shift by 1 on ACC.
NOT: Performs a bitwise NOT on ACC.
To download the package, you can simply use pip.
pip install pythonRSC
After downloading the package, you should have access to a command called 'pythonRSC'.
To use this command, you will need a program file to emulate. There are some test files provided.
pythonRSC run program_code.txt
This will parse the given program file, emulate it and output the state at the end of emulation.
If you desire to use the in-built assembler to parse the program file into logisim bytecode, there is a command for that.
You will need to provide a program file and specify a required output file name.
pythonRSC assemble program_code.txt -o bytecode.txt
If you want to debug your program, pythonRSC provides an easy-to-use timeless debugger similar to GDB Debugger.
The timeless part means that you can go forwards and backwards in execution, thereby relieving you of having to restart the emulator to chase an issue with your program.
To start the emulator with the debugger, use the following command.
pythonRSC debug program_code.txt
After executing, you will be met with a >> awaiting your next command.
The list of commands accepted by the debugger are listed below.
stepi [stepsize] This will 'step' forward once if stepsize is not provided, otherwise it will step as many times as provided in stepsize.
backi [stepsize] This will 'step' backwards once if stepsize is not provided, otherwise it will step as many times as provided in stepsize.
bp [addr|label] ... This will set a breakpoint at the given address(es) in hex or decimal or at given label(s). Breakpoints are enabled on initialization.
enable [addr|label] ... This will turn on a breakpoint if it was disabled, it can take a variadic amount of breakpoints to be enabled.
disable [addr|label] ... This will turn off a breakpoint, it can take a variadic amount of breakpoints to be disabled.
disas [start] [end] This will take a range of addresses and disassemble the instructions. Hexadecimal or decimal.
disas This variation of the disassemble command will try to identify if you are inside a label and disassemble that label for you.
print [type] [reg] This will print a register in your desired format (type). The types are /d (decimal) /t (binary) /x (hexadecimal).
run Resumes emulation unless a breakpoint is hit or HALT is met.
info This will print the current state of the emulator, in other words print all registers.
help This will just list the possible commands.
If you wish to generate a control flow graph from your program, you simply pass a flag to the CLI.
pythonRSC run program_code.txt -cfg pdf or pythonRSC debug program_code.txt -cfg png
GraphViz is required to be downloaded and on your PATH for this to work properly.
The control flow graph will appear at the end of execution. The graph is rendered using GraphViz and the library pythonCFG.
An example graph:
