Manifold 0.10 User Guide



Manifold is a parallel discrete event simulation framework for simulation of modern multicore computer architectures. The software package consists of a parallel simulation kernel, a number of component models, and a few ready-to-use simulator programs that use the component models to build and simulate system models. Users can also port third-party components to Manifold and build system models with them. This user guide describes how to obtain Manifold source code, and how to build and run the simulator programs.


Manifold is designed for parallel simulation of multicore systems. The general simulation system is shown in Figure 1 below.


Figure 1 Manifold Simulation System.

At run-time, instruction streams are fed to the multicore system model for simulation. Example sources of instructions include PIN [1] trace files and the QSim [2] multicore emulator. Components of the system model can be assigned to different host machines for parallel simulation.

The following are the general steps that a simulator program needs to follow to create a system model for simulation.

The simulator programs that are part of the distribution package can serve as examples for how to write simulator programs with Manifold. The component models that are included in the package can be used in building system models. The user can also port third-party components to Manifold and build system models using such components.

Major features of Manifold include the following:

Current Release

The current release is Release 0.10. The software is distributed as a souce code package that contains the following:







Testing and Portability

Source Code Directory Structure

The Manifold source code is organized as follows:

  |... code
       |... doc
       |... kernel
       |... models
       |    |... cache
       |    |    |... mcp-cache
       |    |    |... simple-cache
       |    |... memory
       |    |    |... CaffDRAM
       |    |... network
       |    |    |... iris
       |    |... processor
       |         |... simple-proc
       |         |... zesto
       |... simulator
            |... smp
	         |... common
		 |... config
                 |... QsimClient
                 |... QsimLib
                 |... TraceProc

where ROOT represents the root of the source tree.

Under each of kernel, mcp-cache, iris, and zesto, there is a subdirectory doc/doxygen that contains a user guide in Doxygen format for the respective component.

The simulator directory

The simulator directory hosts a total of six simulator programs, two each under QsimClient, QsimLib, and TraceProc. The difference is the source of instruction streams. Programs under QsimClient use QSim server to get instructions. Those under QsimLib are built with the QSim libraries. And those under TraceProc use PIN traces.

The common code of the simulator programs is located in common. The directory config contains configuration files for the simulator programs.

Build Process Overview

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.2-pre1, 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 source 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.10.tar.gz

  2. Go to the code subdirectory.
    $ cd manifold-0.10/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 the 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 Programs

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:

In addition there are two other subdirectories:

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 Simulators

In each of the three subdirectories, i.e., QsimClient, QsimLib, and , there is a program called smp_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 2 System Model Simulated by smp_llp.

Configuration parameters for the components, except Zesto processor, are defined in a libconfig configuration file in the subdirectory config.

In the following 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 smp_llp ../config/conf2x2_iris_torus_llp.cfg ../config/6.cfg localhost 12345

The output of the simulation is stored in files named DBG_LOG<i>, where <i> is 0 to n-1, n being the number of LPs. The output files contain statistics collected by the components assigned to the corresponding LP.

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 smp_llp ../config/conf4x1_ring_llp.cfg ../config/6.cfg myState_16 myBench.tar

The output of the simulation is stored in a file named DBG_LOG0, which contains statistics collected by all of the components.

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 smp_llp ../config/conf2x2_iris_torus_llp.cfg ../config/6.cfg myTrace

The output of the simulation is stored in files named DBG_LOG<i>, where <i> is 0 to n-1, n being the number of LPs. The output files contain statistics collected by the components assigned to the corresponding LP.

Common Problems

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