dashmips 0.1.1

Mips Interpreter

Dashmips

Dashmips is a Mips Interpreter CLI Program.

Requirements

Dashmips has no dependencies beyond requiring python 3.7. There is a dataclasses module for python 3.6 that may make this module work but it is untested.

Install

The recommended way to install dashmips is with pip:

pip install dashmips

Usage

If you installed via pip you should now have a binary in your path that you can launch by typing:

dashmips

or equivalently

python -m dashmips

"Compiling"

To compile or run a mips program you run:

dashmips compile FILE.mips

What "compilation" means in dashmips is a conversion of the source file to a json format that is better understood by the program. You can use this json format to inspect the internals of how your mips program is interpreted by dashmips.

Running

This one's easy:

dashmips run FILE.mips

Note: FILE is a positional argument in the run subcommand

Debugging

In order to leave a flexible environment for debugging dashmips doesn't provide an interface for human debugging of a mips program. Instead the debugger included is a server that accepts the json format of a mips program over the network and will do the requested operations returning an updated MipsProgram json object.

There is a vscode extension that can speak dashmips specific json language here.

Debugging protocol

Small notes about the protocol if you want to proceed with a manual debugging. The JSON you send to the debug server is expected to take the following format:

interface DebugMessage {
    command: 'start' | 'step' | 'continue' | 'stop';
    program: MipsProgram;  // MipsProgram can be found in `dashmips/models.py`
    // properties below are optional
    breakpoints?: number[];
    message?: string;
    error?: boolean;
}

The commands listed are start, step, continue, and stop. In short each operation does the following:

• Start: sets the pc to the main label
• Step: runs exactly one instruction from current pc
• Continue: runs as many instructions as there are between current pc and a breakpoint
• Stop: Does nothing

The server is designed to be stateless so it can handle many clients at once.

Contributing

Getting Setup

If you want to contribute to the dashmips project you will need the following:

• Poetry is used for dependencies, it will help get you up and running
• After installing Poetry, and cloning this repository:
• poetry install - will install the dashmips dependencies in a virtual environment that won't harm your global set up.
• poetry run X - can run X command in the correct python environment
• Try poetry run pytest --tap-stream --tap-outdir=testout --mypy --docstyle --codestyle to ensure all tests are passing correctly

Adding Syscalls / Adding Instructions

You can add to the existing files in the dashmips/instructions and dashmips/syscalls directories using the relevant decorator (@). If you add instructions or syscalls to a new file in these subdirectories ensure that the new file is named with the pattern: *_instructions.py or *_syscalls.py where * is whatever identifier you choose.

Testing environment install

To make sure dashmips installs correctly in a clean environment I've created a dockerfile that sets up the minimal required env for dashmips. The command below can be used to create the image.

docker build --rm -f "tests\test_env\Dockerfile" -t dashmips_test_env:latest .

Happy coding!