RELEASE-NOTES.txt

Welcome to the 0.9.2 open source release of the Simulation Engine! SimEng is a fast, easy to use and modify cycle-level simulator for CPUs. Its initial focus is on simulating single Arm cores in server CPUs, and so the instruction set architecture (ISA) target is initially Armv8.4-a+SVE. Later versions of the Arm ISA, and other ISAs such as RISC-V, will be supported in future releases.

This SimEng release should be considered beta software - you are the first users outside of the core developers, so there *will* be lots of bugs and missing features. The good news is that the code has been designed to be simple to understand and modify, so if you find a bug, such as a missing instruction or missing system call, please submit a PR, or report an issue and we’ll get to it as soon as we can. 

You can find all the user and developer documentation on the SimEng webpage:

   https://uob-hpc.github.io/SimEng/index.html

SimEng should be fast, much faster than other cycle-level CPU simulators. The fastest hardware we’ve run it on is a 2021 Apple M1 Mac mini, where we’ve measured SimEng running at up to 1.5 MIPS for the Out of Order (OoO) core in our ThunderX2 and A64fx models. SVE (vector) codes are more complex to simulate and tend to be slower - on the same hardware we saw simulated SVE codes running at around 0.6 MIPS. SimEng should also be accurate - most of the codes we’ve tested report cycle counts within 5-10% of real hardware, for our ThunderX2 and A64fx models.

Things that should work in this first release include:
* Static AArch64 binaries compiled with either GCC 7.3 or later, or Arm Clang 20/LLVM 9 or later
* Single thread OpenMP programs
* Binaries compiled from Fortran or C programs

Pre-rolled CPU models in SimEng include:
* Marvell ThunderX2
* Fujitsu A64fx
* More Arm code models such as those found in other Arm server CPUs will be included in future releases

Current limitations (to be addressed in a future release):
* Dynamically linked binaries are not yet supported in SimEng but developments are currently being undertaken
* We don't currently support running MPI programs (we’ve had a statically linked OpenMPI single rank program run correctly, but this was painful to build)
* We only support a subset of Linux's system calls, and these run under emulation. The subset of 45 calls is enough to run all the codes we've tried so far
* No micro-oping support yet, which may impact cycle accuracy in some cases
* Only partial support for the ISA - we’ve focused on implementing the instructions we’ve seen generated by the compiler for all the test cases we’ve considered, about 782 different instructions so far (~17% of the entire ISA). You’re likely to come across “instruction not implemented” errors, just let us know when you see these
* Single core, single thread only for now
* SimEng currently only supports a very simple memory model, assuming all load/stores will hit the L1 cache
    * The longer-term plan is to add a full memory model and support for multicore simulations by using the SST framework - http://sst-simulator.org

Supported OSs (we’ve tested these, SimEng may also work on other platforms):
* CentOS 7
* Ubuntu
* Cray’s CLE 7, which is based on SLES 15
* macOS Big Sur

Compilers supported for building SimEng itself:
* GCC 7 or later
* Arm Clang 20 or later
* Apple Clang on Macs

Some benchmarks we’ve run ourselves and so should work:
* STREAM - https://www.cs.virginia.edu/stream/ 
* miniBUDE - https://github.com/UoB-HPC/miniBUDE 
* CloverLeaf - https://github.com/UK-MAC/CloverLeaf_Serial 
* Tealeaf - https://github.com/UoB-HPC/TeaLeaf

When you hit issues building or running SimEng, please do let us know, either by submitting a PR, or filing an issue via the SimEng Github repo:

  https://github.com/UoB-HPC/SimEng/

Thank you for using SimEng!

 - The SimEng development team.