// ---------------------------
   //   VERIGEN for SystemVerilog
  //   written by Matthias Fertig
// --------------------------

      // PLEASE READ ...
     //
    // The CACHE example is a good entry point to get in touch with VERIGENSV. Please download the package from the VERIGEN website
   // The example is based on the Intel Opteron processor design with simplifications in the cache replacement strategy.
  // Please read Hennessy & Patterson, 6th Edition, Appendix B-13 to see the microarchitecture of the cache
 // The Verilator simulation (see Screenshot_cache_2.png) shows four access scenarios, read-miss, read-hit, write-hit and write-miss
//

  //
 // QUICK HOWTO ...
//
1. How to get the version of the tool?
./VERIGENSV_FREE -h

2. How to generate SystemVerilog?
./VERIGENSV_FREE -f cache.cfg

3. How to run a simulation with verigen?
make

4. How to view the waveforms?
gtkwave logs/vlt_dump.vcd 

 // Introduction
// -------------
This is the Verigen tool for SystemVerilog. The tool is based on the theory of Universal Memory Automata
Please read http://www-home.htwg-konstanz.de/~MFERTIG/files/publications/2020/MPC_063_09.pdf
for more information. The package provides all files for a simulation and coverage analysis with
Verilator. Please read https://www.veripool.org/wiki/verilator for more information on Verilator
All files for Verilator have been adapted from an official example. You can always refer to the
official Verilator page to get more details.

 // Preliminaries
// --------------
1. make
Try 'which make'
Run 'sudo apt-get install build-essential' if not available on your system.

2. verilator and verilator_coverage
Try 'which verilator' and 'which verilator_coverage'
Run 'apt-get install verilator' if not available on your system.

3. gktwave
Try 'which gtkwave'
Run 'sudo apt install gtkwave' if not available on your system.


 // Content of the package
// ----------------------
This package contains the following files:

1. cache.cfg
The Universal Memory Automata configuration file for the cache subsystem.

2. VERIGENSV_FREE
A free version of the binary executable for generating the SystemVerilog code from the cache.cfg configuration file. 
It supports up to five states and two memories. Please contact me if you need the full version. The file is compiled
on Ubuntu 18.04.5.LTS. Call 'VERIGENSV_FREE -f cache.cfg' to generate the file CACHE.sv.

3. obj_dir/CACHE.sv
The SystemVerilog code compiled from cache.cfg by using VERIGENSV.
Call 'VERIGENSV_FREE -f cache.cfg' to re-generate the file CACHE.sv.

4. Makefile
The main makefile to compile C++ headers, source files and executables for Verilator. Just run 'make' and
open 'logs/vlt_dump.vcd' with gtkwave. Makefile performs some sanity checks, sets up variables used by Verilator
to perform assertion checking and coverage analysis. VERILATOR_INPUT contains the input SystemVerilog and C++
simulation files for the MESI protocol. Adapt VERILATOR_INPUT for your purpose if needed. Output directories
are defined in the run-tag of the Makefile. Adapt to your own designs.

    The output structure is as follows:

    4a. binary executable for Verilator
    obj_dir/VCACHE
    
    4b. annontated SystemVerilog code for Verilator
    logs/annotated/CACHE.sv
    
    4c. Information from coverage analysis
    logs/coverage.dat
    

5. Makefile_obj
Called by Makefile. Defines the object files, dependencies, compile and linker flags, output object file.
Adapt this file for your purpose if required.

6. top.cpp
The C++ testbench. The testbench stimulates inputs and documents outputs in logs/vlt_dump.vcd and logs/coverage.dat.
Adapt the file for your purpose to configure a specific simulation scenario. Consider that every half cycle is one
increment in the simulation time. Secure that inputs change on the low half-cycle if your hardware is triggering
on the positive edge!



 // How to get started quickly
// ---------------------------

1. check that all preliminaries are available
which make
which verilator
which verilator_coverage

2. Unpack archive
tar xvfz VERIGENSV_FREE_CACHE.tgz

3. change to objects directory
cd obj_dir

4. run simulation with Verilator
make

5. check output with gtkwave
gtkwave logs/vlt_dump.vcd



 // How to adapt the design and rerun
// ----------------------------------

1. adapt obj_dir/cache.cfg
cd obj_dir
emacs cache.cfg

2. re-ccompile the SystemVerilog file CACHE.sv
../VERIGENSV_FREE -f cache.cfg

3. check syntax with lint
verilator +1800-2017ext+6.5 -lint-only -Wall cache.sv

4. run simulation with Verilator
make

5. check output with gtkwave
gtkwave logs/vlt_dump.vcd




That's it!
Have FUN!