Skip to content

Latest commit

 

History

History
75 lines (54 loc) · 2.72 KB

README.md

File metadata and controls

75 lines (54 loc) · 2.72 KB
Raw

hera-py

Build Status Coverage Status PyPI

A toolkit for the Haverford Educational RISC Architecture (HERA) assembly language, comprising an interpreter, a debugger, an assembler, and a disassembler.

Installation

You can install hera-py with pip:

$ pip3 install hera-py

Usage

After installation, use the hera command to run a HERA program:

$ hera main.hera

Enter the interactive debugger with the debug subcommand:

$ hera debug main.hera

Assemble a HERA program into machine code:

$ hera assemble main.hera

Disassemble machine code back into the human-readable HERA syntax:

$ hera disassemble main.hera.lcode

You can also preprocess a HERA program without running it, to see how pseudo-instructions and labels are resolved to HERA code:

$ hera preprocess main.hera

Comparison with HERA-C and Hassem

HERA-C is the current HERA interpreter used at Haverford. It is implemented as a shell-script wrapper around a set of C++ macros that expand HERA instructions into C++ code, which is then compiled by g++.

hera-py improves on HERA-C in the following areas:

  • Includes a purpose-built HERA debugger
  • Concise and accurate error messages
  • Ease of use
    • Cross-platform and easy to install
    • Configurable with command-line options
    • Does not create temporary files
    • Command name has six fewer letters than HERA-C-Run

hera-py also supports several features that HERA-C does not:

  • Setting registers to the value of a label
  • Detecting stack overflow
  • Multi-precision multiplication
  • Relative branching by a fixed integer value (e.g., BRR(10))
  • Branching by the value of a register (e.g., SET(R1, 20); BR(R1))
  • Detecting invalid relative branches

HERA-C has a few features that hera-py does not:

  • C-style #define macros (and more generally the ability to embed arbitrary C++ code in HERA programs)

Small to medium-sized programs generally run faster with hera-py than with HERA-C, while very large programs are typically faster with HERA-C.

Hassem is the current HERA assembler used at Haverford. hera-py has better error messages than Hassem, allows the user greater control of output (e.g., with the --stdout flag), and fixes some Hassem bugs.

Acknowledgements

Thank you to Christopher Villalta for valuable feedback on early iterations of this project.