README

NVMain - An Architectural Level Main Memory Simulator
         for Emerging Non-Volatile Memories

======================================================

Sections

    1. Overview
    2. Building NVMain
       a. Trace Simulation
       b. Simulator-Connected Simulation
    3. Running NVMain
    4. Configuring NVMain
    5. Hacking NVMain
    6. README Changelog

------------------------------------------------------  

1. Overview

    NVMain is a cycle accurate main memory simulator
    designed to simulate emerging non-volatile
    memories at the architectural level. Since the 
    current status of non-volatile memory is unknown
    and this is a research tool, flexability is 
    provided to implement different variations of
    memory controllers, interconnects, organizations,
    etc. Detailed modification information is
    provided in section 5. Thanks for trying NVMain!


------------------------------------------------------

2. Building NVMain

    NVMain can be build as a standalone executable to
    run trace-based simulations, or it can be patched
    into a CPU simulator to provide closer to full
    system simulation. 

    2a. Trace Simulation

        The trace simulation can be build using scons:

        $ scons --build-type=[fast|debug|prof]

        Compiling with scons will automatically set 
        the compile flags needed for trace-based
        simulation. You can use --build-type=fast
        for -O3 optimization, --build-type=debug
        to add debugging symbol, or --build-type=prof
        to add support for profiling the simulator.

    2b. Simulator-Connected Simulation

        Running NVMain under a simulator depends on
        the simulator use. The 'patches' directory
        contains a directory for each of the supported
        simulators.

        gem5 (git);

           The gem5 patch is the most up-to-date patch
           in most cases. As of March 1st, 2017 gem5 uses
           a git repository as the master. The NVMain patch
           can be applied using the follwing command in the
           gem5 root directory:

           git apply /path/to/nvmain/patches/gem5/nvmain2-XYZ

           The patch can be removed using the following:

           git apply -R /path/to/nvmain/patches/gem5/nvmain2-XYZ

        gem5 (mercurial):

           If you are using a verison of gem5 cloned from
           the read-only mercurial mirror, mercurial queues
           can be used to apply the patch. To start, go to
           the gem5 root directory and import the patch

           $ hg qimport /path/to/nvmain/patches/gem5/nvmain2-XYZ

           Apply the path using qpush:

           $ hg qpush

           You can check that the patch was applied using
           qapplied:

           $ hg qapplied

           You can build gem5 normally at this point.
           You will need mercurial queues setup to do
           this. More information can be found at 
           http://mercurial.selenic.com/wiki/MqExtension/
           In general you should add the following to ~/.hgrc:

           [extensions]
           mq =

           and you should initialize queues in gem5 using:

           $ hg qinit


           To update the gem5 patch, first remove it and 
           delete it. It can then be imported again. In
           order to save your modifications, you can create
           your own patch before re-importing the nvmain 
           patch:

           $ hg qnew mychanges.patch
           $ hg qrefresh
              
           Now your changes are saved in the "mychanges.patch"
           file. Feel free to rename this :). Next re-import
           NVmain:

           $ hg qpop -a
           $ hg qdel nvmain-XYZ
           $ hg qimport /path/to/nvmain/patches/gem5/nvmain-XYZ
           $ hg qpush -a

        zsim:

           There is a 3rd-party effort to integrate NVMain with
           zsim, a PIN-based x86-64 simulator. Details can be
           found here:

           https://github.com/AXLEproject/axle-zsim-nvmain


------------------------------------------------------

3. Running NVMain


    NVMain can be run on the command line with trace-based
    simulation via:

    ./nvmain CONFIG_FILE TRACE_FILE [Cycles [PARAM=value]]


    The CONFIG_FILE is the path to the configuration file
    for the memory system being simulated. The TRACE_FILE
    is the path to the trace file with the memory requests
    to simulate. Cycles is optional and specifies the max
    number of cycles to simulate. By default the entire
    trace file is simulated. This is equivalent to providing
    "0" as the value for Cycles. Additionally, CONFIG_FILE
    parameters can be overriden using PARAM=value, for
    example, adding "MEM_CTL=FRFCFS" to the command line
    will override the value for MEM_CTL in the configuration
    file.

    A various number of trace formats are supported, such
    as "ProtocolTrace" traces from gem5 or NVMain traces
    which contain the minimum amount of information needed
    to simulate a request. NVMain traces are recommended.
    Traces can be generated by running gem5 with the
    printtrace.config configuration file. The NVMain trace
    format prints the previous and new value of data being
    written to memory to allow for simulation of MLC NVMs
    and data encoding techniques which require knowing
    which data bits are changing.

    For gem5, simulation is setup using python scripts.
    NVMain only patches gem5 to recognize command line
    options for NVMain. The example scripts provided with
    gem5 can be used:

    configs/example/se.py - Run in SE mode
    configs/example/fs.py - Run in FS mode

    When running gem5, the parameter --mem-type=NVMainMemory
    must be used to enable NVMain. The option --nvmain-config
    must be used to specify the NVMain configuration file.
    Below is an example command line:

    $ gem5.fast config/example/se.py -c hello_world      \
                --mem-type=NVMainMemory --caches         \
                --l2cache --l1i_size 32kB                \
                --l1d_size 32kB --l2_size 2MB            \
                --cpu-type=detailed                      \
                --nvmain-config=/path/to/nvmain.config


------------------------------------------------------

4. Configuring NVMain


    NVMain can be configured using the configuration files.
    Several example configuration files can be found in
    the Config/ folder in the NVMain trunk. 

    A more detailed listing of configuration parameter 
    names and potential values are on the NVMain wiki page
    at http://wiki.nvmain.org/.


------------------------------------------------------

5. Hacking NVMain


    As mentioned in the overview, NVMain is meant to 
    be flexible. Writing your own interconnect, 
    memory controller, endurance model, address 
    translator, etc. Can be done by creating a new 
    C++ file with your new class.

    Each unit has a Factory class which selects 
    the class to used based on the configuration
    file input. You can create a class by looking
    at one of the example classes in each folder:

    MemControl - Custom Memory Controllers
    FaultModels - Custom hard-fault models
    Decoders - Custom address translators
    Endurance - Custom Endurance models
    Interconnect - Custom Interconnects
    Prefetchers - Custom prefetchers
    SimInterface - Simulator interface used to
                   gather useful statistics from
                   the CPU simulator such as
                   instructions executed, cache
                   miss rates, etc.
    traceReader - Custom trace file readers

    When adding a class, make sure to update
    the factory class to #include your class
    header and to initialize your class if 
    the configuration is set to your class'
    name.

    In some folders there is a "GenerateSConscript.sh"
    This script should also be run when you
    create a new class so gem5 knows about it.


------------------------------------------------------


8/17/2012 - Created first README
2/8/2017 - Update README for cleanup branch