# Introduction to MPACT-Sim

MPACT-Sim is a framework and library designed to make it easier to create
high performance ISA simulators for a wide range of instruction set
architectures. Simulators built using MPACT-Sim are easy to create, easy to
instrument, and fast. The motivating use-case for MPACT-Sim is to quickly
create, and easily modify, simulators for (instruction set) architectural
exploration. However, the resulting simulator can also be used for system
modeling, compiler validation, or software development for architectures that
have no (or limited) hardware availability.

MPACT-Sim makes it easy to express and implement instruction semantics as simple
C++ functions/callables. MPACT-Sim also provides a declarative methodology for
expressing instructions to enable automatic generation of most of the
instruction decoder, increasing the ease and velocity by which new simulators
can be created. Custom configuration entries can easily be added, and the
resulting simulators are easy to instrument using a set of standard classes.

## Tutorials

The tutorials that follow provide a guided walk-through of creating an ISA
simulator for a subset of RiscV instructions sufficient for executing a "hello
world" application compiled for the RV32I architectural subset. They cover
the following activities:

- Write an ISA decoder description for RV32I.

  This describes the individual
  instructions independent of their external representation (encoding). This
  description is used to generate C++ code that initializes the simulator's
  internal instruction descriptors.
- Write a binary decoder description for RV32I.

  This describes the binary
  encoding of the instructions, bit-fields and their values. This is used to
  generate a decoder for the instructions capable of mapping an instruction word
  to an opcode, and extracting the values of specific bit-fields.
- Write an integrated (full) instruction decoder that integrates the two
  generated decoders, adding required code to cover what the generated code does
  not.

- Write instruction semantic functions to provide the implementations of each
  of the target RV32I instructions.

Writing the remaining code required to complete the simulator, including the
code controlling instruction issue, is not covered by the current tutorials, but
may be added in the future. However, sample code can be viewed in the tutorial
repository, as well as in the repository for full
\[MPACT-RiscV simulator\]https://github.com/mpact-riscv).

The simulator infrastructure is written in C++, so a good working knowledge of
C++ is assumed.