Manifold User Guide


Manifold is a parallel discrete event simulation framework for simulation of modern multicore computer architectures. The software mainly consists of two layers: a simulation kernel layer, and a model layer that contains a few computer architecture models. In addition, Manifold also provides a few ready-to-use simulator programs. This user guide describes how to obtain Manifold source code, and how to build and run the simulator programs.

Directory Structure

The Manifold source code is organized as follows:

  |... code
       |... doc
       |... kernel
       |... models
       |    |... cache
       |    |    |... mcp-cache
       |    |... memory
       |    |    |... CaffDRAM
       |    |... network
       |    |    |... iris
       |    |... processor
       |         |... zesto
       |... simulator
            |... zesto
                 |... QsimClient
                 |... QsimLib
                 |... TraceProc

where ROOT represents the root of the source tree.


To build and run the simulator programs that are part of the software package, you will need to perform the following steps:

The simulators can respectively take instructions from three different sources: trace files, QSim library, and QSim server. Depending on which source you use, some of the steps above may be optional.

The following explains each step in detail.

Install Required Packages

Before you proceed, you need to install the following required packages.

Download and Build QSim

If you choose to use QSim to get instructions, you need to build and install QSim first.


QSim is available through SVN check out. The latest version at this writing is 0.1.4, at the following address:

Build and Installation

Instructions for building and installing QSim can be found in the INSTALL file in the root directory of QSim source code.

In addition to the QSim libaries, you also need to do the following:

All the instructions are in the INSTALL file.

After you are finished, you installation directory should look like the following, assuming QSIM_INSTALL is the root of the installation directory.

$ ls <QSIM_INSTALL>/lib

$ ls <QSIM_INSTALL>/include
mgzd.h  qsim-client.h  qsim.h  qsim-load.h  qsim-net.h  qsim-regs.h  qsim-vm.h

Download and Build Manifold Libraries

There are two ways to download Manifold source code: from the Manifold website or through SVN checkout. Depending on which way is used to obtain the souce code, the build process is slightly different.

Download Manifold source package

Manifold source package is available at the Manifold website:

After download, follow the following instructions to build the manifold libraries:

  1. Untar the source package.
    $ tar xvfz manifold-0.8.tar.gz

  2. Go to the code subdirectory.
    $ cd manifold-0.8/code

  3. Run configure and make.
    $ ./configure [--prefix=INSTALL_PATH]
    $ make
    The default installation directory is /usr/local/lib. If you want to install in a different location, the path of that location should be passed to configure. In addition, if QSim is installed in a location other than the default, you need to tell configure that location. Options that you can specify for configure are described below.

  4. Optionally, install the libraries.
    $ make install

Download Manifold source code through SVN checkout

Manifold source code is available through SVN checkout at the following address:

To build the un-packaged source code, you need to have autotools package installed on your machine.

  1. From the code subdirectory, run autoreconf.
    $ cd code
    $ ./autoreconf -si
    This would create the configure script.

  2. Run configure and make.
    $ ./configure [--prefix=INSTALL_PATH]
    $ make

  3. Optionally, install the libraries.
    $ make install

Configure options

This section describes all of the options you can use when running the configure script.

Build the Simulator Program

The simulator programs are located in ROOT/code/simulator/zesto. There are three subdirectories for three types of simulators, based on how they get instructions:

To build the simulators, follow the following steps. Here we use the simulators under QsimClient as an example.

  1. Go to the simulator source directory.
    $ cd ROOT/code/simulator/zesto/QsimClient

  2. Run make. It is likely that you need to modify the Makefile so the header files and libraries can be found.
    $ make

Start the Simulator

In each of the three subdirectories, i.e., QsimClient, QsimLib, and , there is a program called zesto_llp. This program simulates the following system model, where each core node has a processor core, a private L1 cache, and a shared L2 slice.


Figure 1 System Model Simulated by zesto_llp.

We describe how to start the simulators in each of the three subdirectories.

Start the Simulators in QSimClient

These simulators require QSim server be started first.

To start the QSim server, run the following commands:

$ cd QSIM_ROOT/remote/server
$ make
$ ./server <port> <state_file> <benchmark>  


After the QSim server has started, the simulator can be started.

If QSim is installed in /usr/local, do the following,

$ mpirun -np <NP> <prog> <conf_file> <zesto_conf_file> <server> <port>

If Qsim is not installed in /usr/local. Do the following, assuming QSim installation path is QSIM_INSTALL.

$ QSIM_PREFIX=<QSIM_INSTALL> LD_LIBRARY_PATH=<QSIM_INSTALL>/lib  mpirun -np <NP> <prog> <conf_file> <zesto_conf_file> <server> <port>


For example:

$ mpirun -np 2 zesto_llp conf2x2_iris_torus_llp.cfg 6.cfg localhost 12345

Start the Simulators in QSimLib

Simulators in this subdirectory can only be run with 1 LP, or in sequential mode.

If QSim is installed in /usr/local, do the following.

$ mpirun -np 1 <prog> <conf_file> <zesto_conf_file> <state_file> <benchmark>

If Qsim is not installed in /usr/local. Do the following, assuming QSim installation path is QSIM_INSTALL.

$ QSIM_PREFIX=<QSIM_INSTALL> LD_LIBRARY_PATH=<QSIM_INSTALL>/lib  mpirun -np 1 <prog> <conf_file> <zesto_conf_file> <state_file> <benchmark>


For example:

$ mpirun -np 1 zesto_llp conf4x1_ring_llp.cfg 6.cfg myState_16 myBench.tar

Start the Simulators in TraceProc

These simulators use Pin traces.

$ mpirun -np <NP> <prog> <conf_file> <zesto_conf_file> <trace_file_basename>


For example:

$ mpirun -np 2 zesto_llp conf2x2_iris_torus_llp.cfg 6.cfg myTrace

Common Problems

The following is a list of commonly encountered problems, and how to solve them.

Generated on Mon Jun 25 12:17:29 2012 by  doxygen 1.6.3