0.9.6 documentation update (#396)

.circleci/config.yml

@@ -49,4 +49,5 @@ workflows:
             - docs-build
           filters:
             branches:
-              only: main
+              only: 
+                - main

CMakeLists.txt

@@ -50,7 +50,7 @@ FetchContent_Declare(
 )
 
 cmake_policy(SET CMP0048 NEW)
-project(SimEng VERSION 0.9.4 LANGUAGES C CXX)
+project(SimEng VERSION 0.9.6 LANGUAGES C CXX)
 
 # If no build type was defined, default to Release
 if(NOT CMAKE_BUILD_TYPE)

CONTRIBUTORS.txt

@@ -12,6 +12,8 @@ Current development team:
   Finn Wilkinson
   Rahat Muneeb
   Daniel Weaver
+  Alex Cockrean
+  Joseph Moore
 
 Additional Contributors:
   Ainsley Rutterford

RELEASE-NOTES.txt

@@ -1,16 +1,16 @@
-Welcome to the 0.9.5 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 Arm9.2-a+SVE+SME. RISC-V has also seen some inital support, starting with rv64ima. Later versions of the Arm ISA, additional RISC-V ISA extensions and other ISAs, will be supported in future releases.
+Welcome to the 0.9.6 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 Arm9.2-a+SVE+SME. There is also RISC-V support currently covering the rv64imafdc set of extensions. Later versions of the Arm ISA, additional RISC-V ISA extensions and other ISAs, 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 an M1-Ultra Mac Studio, where we’ve measured SimEng running at up to ~1 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 be fast, much faster than other cycle-level CPU simulators. The fastest hardware we’ve run it on is an M1-Ultra Mac Studio, where we’ve measured SimEng running at up to 1.4 MIPS for the Out of Order (OoO) core in our ThunderX2 and A64fx models. SVE (vector) and SME (matrix) codes are more complex to simulate and tend to be slower - on the same hardware we saw simulated SVE codes running at around 1.1 MIPS and SME codes at around 0.9 MIPS.
 
 Things that should work in this release include:
 * Static AArch64, with SVE/SME, binaries compiled with either GCC 7.3 or later, or Arm Clang 20/LLVM 9 or later
-* Static RISC-V binaries targetting rv64ima and compiled with GCC 12.2.0
+* Static RISC-V binaries targetting rv64imafdc and compiled with GCC 12.2.0
 * Single thread OpenMP programs
 * Binaries compiled from Fortran or C programs
 
@@ -25,15 +25,15 @@ Current limitations (to be addressed in a future release):
 * 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 43 calls is enough to run all the codes we've tried so far
 * Only partial support for micro-oping, mainly for Load and Store operations
-* 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 1000 different AArch64 instructions (~15% of the entire ISA) and about 150 different RISC-V instructions so far (~33% of the RISC-V ISA supported by Capstone). You’re likely to come across “instruction not implemented” errors, just let us know when you see these
+* 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 1000 different AArch64 instructions (~16% of the entire ISA) and about 210 different RISC-V instructions so far (~46% of the RISC-V ISA supported by Capstone). 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
 * Internally, SimEng currently only supports a very simple memory model, assuming all load/stores will hit the L1 cache. However, we have a tested integration with the SST framework (http://sst-simulator.org) allowing for a full memory model to be simulated.
 
 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/Monterey
+* macOS Monterey/Ventura/Sonoma
 
 Compilers supported for building SimEng itself:
 * GCC 7 or later

docs/requirements.txt

@@ -1,5 +1,5 @@
-Sphinx==1.6.7
+Sphinx==5.0.0
 sphinx-rtd-theme==0.5.2
 mistune==0.8.4
 m2r2==0.3.1
-Jinja2==3.0.3
+Jinja2==3.1.3

docs/sphinx/index.rst

@@ -44,13 +44,13 @@ SimEng is a framework for building modern, cycle-accurate processor simulators.
 - Accurate, aiming for simulated cycle times being within 5-10% of real hardware
 - Open source, with a permissive license to enable collaboration across academia and industry
 
-SimEng places an emphasis on performance and ease of use, whilst maintaining a clean, modern, simple and well-documented code base. For example, the current out-of-order (OoO) model is implemented in around 10,000 lines of simple C++, with another 17,000 and 3,000 lines or so implementing the specifics of the AArch64 and RISC-V ISAs respectively, and around 27,000 lines of code in the accompanying test suite. SimEng should be simple to read and understand, making it ideal to modify to your requirements and include it in your projects.
+SimEng places an emphasis on performance and ease of use, whilst maintaining a clean, modern, simple and well-documented code base. For example, the current out-of-order (OoO) model is implemented in around 11,000 lines of simple C++, with another 18,000 and 5,000 lines or so implementing the specifics of the AArch64 and RISC-V ISAs respectively, and around 41,000 lines of code in the accompanying test suite. SimEng should be simple to read and understand, making it ideal to modify to your requirements and include it in your projects.
 
 
 Features
 --------
 
-Currently, SimEng targets the Armv9.2-a ISA with support for the SVE, SVE2, and SME extensions as well as RISC-V rv64ima. SimEng has the ability to model up to out-of-order, superscalar, single-core processors, and to emulate a subset of Linux system-calls. It supports statically compiled C and Fortran binaries that run on real hardware, with additional support for single-threaded OpenMP binaries too. Internally, SimEng currently models memory as an infinite L1 cache, i.e. it assumes that all loads and stores hit the L1 cache. However, we have a tested integration with the `Structural Simulation Toolkit <http://sst-simulator.org/>`_ (SST) allowing for a full memory model to be simulated; more information can be found in the :doc:`SST Integration section <sst/index>`.
+Currently, SimEng targets the Armv9.2-a ISA with support for the SVE, SVE2, and SME extensions as well as RISC-V rv64imafdc. SimEng has the ability to model up to out-of-order, superscalar, single-core processors, and to emulate a subset of Linux system-calls. It supports statically compiled C and Fortran binaries that run on real hardware, with additional support for single-threaded OpenMP binaries too. Internally, SimEng currently models memory as an infinite L1 cache, i.e. it assumes that all loads and stores hit the L1 cache. However, we have a tested integration with the `Structural Simulation Toolkit <http://sst-simulator.org/>`_ (SST) allowing for a full memory model to be simulated; more information can be found in the :doc:`SST Integration section <sst/index>`.
 
 The main component provided by the simulator is a discrete processor core model, shown in diagrammatic form below.  This model accepts a clock signal and supports a memory access interface. A single YAML format configuration file can be passed to the simulation to specify models of existing microarchitectures, such as Marvell's ThunderX2 or Fujitsu's A64fx, or to model hypothetical core designs.
 
@@ -70,15 +70,17 @@ SimEng was first presented by `Professor Simon McIntosh-Smith <http://uob-hpc.gi
 
 Additionally, other works concerning SimEng and its use can be found below:
 
+- Second International workshop on RISC-V for HPC at SC2023 - `An Empirical Comparison of the RISC-V and AArch64 Instruction Sets <https://dl.acm.org/doi/abs/10.1145/3624062.3624233>`_
 - ModSim 2023 - :download:`Leveraging Arm's Scalable Matrix Extension to Accelerate Matrix Multiplication Kernels <assets/modsim23_poster.pdf>`
+- PMBS 2022 - `An Initial Evaluation of Arm's Scalable Matrix Extension <https://ieeexplore.ieee.org/document/10024029>`_
 - ModSim 2022 - :download:`A design space exploration for optimal vector unit composition <assets/modsim22_poster.pdf>`
 - :download:`Modelling Advanced Arm-based CPUs with SimEng <assets/simeng_arm_cpus.pdf>`
 
 
 Release
 -------
 
-This is SimEng's seventh release, and should be considered beta level software (version 0.9.5). We expect you to find issues, primarily in unimplemented instructions or unimplemented system calls. Please let us know when you hit these, either by submitting a pull request (PR), or by filing an issue on the Github repo. You can find the all the code and associated test suites for SimEng in the `GitHub repository <https://github.com/UoB-HPC/SimEng>`_. The file `RELEASE_NOTES.txt <https://github.com/UoB-HPC/SimEng/blob/main/RELEASE-NOTES.txt>`_, found in the root of the project, explains the status of the project and includes other relevant information from the SimEng development team.
+This is SimEng's eighth release, and should be considered beta level software (version 0.9.6). We expect you to find issues, primarily in unimplemented instructions or unimplemented system calls. Please let us know when you hit these, either by submitting a pull request (PR), or by filing an issue on the Github repo. You can find all the code and associated test suites for SimEng in the `GitHub repository <https://github.com/UoB-HPC/SimEng>`_. The file `RELEASE_NOTES.txt <https://github.com/UoB-HPC/SimEng/blob/main/RELEASE-NOTES.txt>`_, found in the root of the project, explains the status of the project and includes other relevant information from the SimEng development team.
 
 SimEng is released under the same license as LLVM, the permissive `Apache 2.0 <https://www.apache.org/licenses/LICENSE-2.0>`_ license. We are passionate about enabling experimentation with computer architectures, and want users and developers in academic and industry to have complete freedom to use SimEng anyway they wish, including using it in commercial settings.
 

src/lib/arch/riscv/Instruction_execute.cc

@@ -177,7 +177,7 @@ void Instruction::execute() {
          "Attempted to execute an instruction before all source operands were "
          "provided");
 
-  // Implementation of rv64iamfdc according to the v. 20191213 unprivileged spec
+  // Implementation of rv64imafdc according to the v. 20191213 unprivileged spec
 
   executed_ = true;
   switch (metadata_.opcode) {

test/integration/ConfigTest.cc

@@ -95,7 +95,7 @@ TEST(ConfigTest, Default) {
   emittedConfig =
       ryml::emitrs_yaml<std::string>(simeng::config::SimInfo::getConfig());
   expectedValues =
-      "Core:\n  ISA: rv64\n  'Simulation-Mode': emulation\n  "
+      "Core:\n  ISA: rv64\n  Compressed: 0\n  'Simulation-Mode': emulation\n  "
       "'Clock-Frequency-GHz': 1\n  'Timer-Frequency-MHz': 100\n  "
       "'Micro-Operations': 0\nFetch:\n  'Fetch-Block-Size': 32\n  "
       "'Loop-Buffer-Size': 32\n  'Loop-Detection-Threshold': "