Multi2sim Quickstart Tutorial

/* UMN 2016 Fall CSCI 5204 EE 5364, version 1.0 beta, created by Minjun Wu, 2016.09 */

1. Quickstart
2. --x86-config & --mem-config
3. For PA1
4. Reference & Appendix

1. Quickstart
- There are three very useful resources which can help you a lot!
./m2s --help
http://lacasa.uah.edu/portal/index.php/tutorials/36-multi2sim
http://www.multi2sim.org/downloads/m2s-guide-4.2.pdf

- Syntax[1]:
When you use m2s, the command line syntax is:
./m2s [<options>] [<x86_binary> [<arg_list>]]
There are 3 parts of this syntax: ./m2s, [<options>] and
[<x86_binary> [<arg_list>]]
You are running this simulator, so [<options>] is working for
configure your simulation architecture.
You also need a program to test your configured architecture, so your
program is: [<x86_binary> [<arg_list>]]. <x86_binary> is execution file
and <arg_list> is the program data input (if need).

- Syntax cont[2]:
If you see ./m2s --help, the syntax is:
./m2s [<options>] [<exe>] [<args>]
And the description:
Multi2Sim's command line can take a program executable <exe> as an
argument, given as a binary file in any of the supported CPU architectures,
and optionally followed by its arguments <args>. The following list of
command-line options can be used for <options>: xxxxxxxxx
So, we can get several info from this description:
followed by its arguments <args>, <args> is <exe>s arguments
a binary file in any of the supported CPU architectures, it can
automatically recognize or it need --arch-config to specify (I am not sure, I
think it can do it automatically).

- Options:
The syntax of [<options>] is:
[<options>] = [<options>] --option config-file/argument
that means option and its config-file is combined (report error if have
mistake)
e.g. ./m2s --x86-sim detailed --x86-config x86-config-file ./exe ./input
|---------------------| |----------------------------------|
option 1

option 2

There are a lot of options which can be used to specify your simulation.
Basically, they are working for: simulation setting and architecture setting.

Appendix A contains all the simulation setting info.

Architecture setting contains: CPU (x86, arm, mips etc. ), GPU,
Cache/Memory Hierarchy, Network[2].

2. --x86-config & --mem-config

- x86 general configuration:
--x86-config is special for configuring x86 CPU, but beside of that,
there are many --x86-xxx to set other architecture info.
e.g. --x86-max-inst <num of instr>
e.g. --x86-sim detailed
All these information can be found in command line:
./m2s --help
Appendix B will contain all --x86-xxx info.

- --x86-config:
The syntax of x86 configuration is:
--x86-config x86-config-file
The format of x86-config-file can be found in command line by:
./m2s --x86-help
This can help you find the item you want to set and Appendix C[3]
contains an x86-config-file example (the format).

- --mem-config:

The syntax is same with --x86-config, which you need a file with some
format to configure your cache/memory system. Also you can find the file
format by:
./m2s --mem-help
There is an example in Appendix D[3], also if need, m2s-guide[4] chapter
9.2 will help you.

3. For PA1
- several settings:
--x86-config <config file>:
FastForward, because of the bug, this one you MUST see
Appendix E or course announcement.
--x86-max-inst <num of inst>
--mem-config <file>

--x86-report <file>
--mem-report <file>
--x86-sim detailed:
Otherwise your x86-report/mem-report file will be empty (you
need the data in mem-report file).

Good luck!

Reference:
[1]. http://lacasa.uah.edu/portal/Upload/tutorials/m2s/GettingStartedMulti2Sim.txt
[2]. ./m2s --help
[3]. http://lacasa.uah.edu/portal/Upload/tutorials/m2s/Multi2SimSystemConfiguration.txt
[4]. http://www.multi2sim.org/downloads/m2s-guide-4.2.pdf

Appendix:
A: simulation setting info:
General Multi2Sim Options
=========================
--call-debug <file>
Dump debug information related with the CPU context call stacks,
including function invocations and returns.
--ctx-config <file>
Use <file> as the context configuration file. This file describes the
initial set of running applications, their arguments, and environment
variables. Use option --ctx-config-help for a description of the context
configuration file format.
--esim-debug <file>
Dump debug information related with the event-driven simulation engine.
--inifile-debug <file>
Dump debug information about all processed INI files into the specified
path.
--max-time <time> (default = 0)
Maximum simulation time in seconds. The simulator will stop once this
time is exceeded. A value of 0 (default) means no time limit.
--trace <file>
Generate a trace file with debug information on the configuration of the
modeled CPUs, GPUs, and memory system, as well as their dynamic
simulation. The trace is a compressed plain-text file in format. The
user should watch the size of the generated trace as simulation runs,
since the trace file can quickly become extremely large.
--visual <file>
Run the Multi2Sim Visualization Tool. This option consumes a file
generated with the '--trace' option in a previous simulation. This
option is only available on systems with support for GTK 3.0 or higher.

B: --x86-xxx
================================================================================
x86 CPU Options
================================================================================
--x86-config <file>
Configuration file for the x86 CPU timing model, including parameters
describing stage bandwidth, structures size, and other parameters of
processor cores and threads. Type 'm2s --x86-help' for details on the file
format.
--x86-debug-call <file>
Dump debug information about function calls and returns. The control flow
of an x86 program can be observed leveraging ELF symbols present in the
program binary.
--x86-debug-clrt <file>

Debug information for the newer implementation of the OpenCL runtime

library (not available yet).
--x86-debug-ctx <file>
Dump debug information related with context creation, destruction,
allocation, or state change.
--x86-debug-glut <file>
Debug information for GLUT runtime calls performed by an OpenGL program
based on the GLUT library.
--x86-debug-loader <file>
Dump debug information extending the analysis of the ELF program binary.
This information shows which ELF sections and symbols are loaded to the
initial program memory image.
--x86-debug-isa
Debug information for dynamic execution of x86 instructions. Updates on
the processor state can be analyzed using this information.
--x86-debug-opengl <file>
Debug information for OpenGL runtime calls.
--x86-debug-syscall
Debug information for system calls performed by an x86 program, including
system call code, arguments, and return value.
--x86-debug-trace-cache
Debug information for trace cache.
--x86-disasm <file>
Disassemble the x86 ELF file provided in <file>, using the internal x86
disassembler. This option is incompatible with any other option.
--x86-help
Display a help message describing the format of the x86 CPU context
configuration file.
--x86-last-inst <bytes>
Stop simulation when the specified instruction is fetched. Can be used to
trigger a checkpoint with option '--x86-save-checkpoint'. The instruction
must be given as a sequence of hexadecimal digits, including trailing
zeros if needed.
--x86-load-checkpoint <file>
Load a checkpoint of the x86 architectural state, created in a previous
execution of the simulator with option '--x86-save-checkpoint'.
--x86-max-cycles <cycles>
Maximum number of cycles for x86 timing simulation. Use 0 (default) for no
limit. This option is only valid for detailed x86 simulation (option
'--x86-sim detailed').
--x86-max-inst <inst>
Maximum number of
limit is given in
simulation, it is
instructions. Use

x86 instructions. On x86 functional simulation, this

number of emulated instructions. On x86 detailed
given as the number of committed (non-speculative)
0 (default) for unlimited.

--x86-report <file>
File to dump a report of the x86 CPU pipeline, including statistics such
as the number of instructions handled in every pipeline stage, read/write
accesses performed on pipeline queues, etc. This option is only valid for
detailed x86 simulation (option '--x86-sim detailed').
--x86-save-checkpoint
Save a checkpoint
Useful options to
'--x86-last-inst'

<file>
of x86 architectural state at the end of simulation.
use together with this are '--x86-max-inst' and
to force the simulation to stop and create a checkpoint.

--x86-sim {functional|detailed}
Choose a functional simulation (emulation) of an x86 program, versus
a detailed (architectural) simulation. Simulation is functional by
default.

C: x86-config-file example:
[ General ]
Frequency = 2000
Cores = 1
[ BranchPredictor ]
Kind = Bimodal
Bimod.Size = 512

D: mem-config-file example:
[CacheGeometry geo-l1]
Sets = 128
Assoc = 2
BlockSize = 256
Latency = 2
Policy = LRU
Ports = 2
[CacheGeometry geo-l2]
Sets = 256
Assoc = 4
BlockSize = 256
Latency = 4
Policy = LRU
Ports = 2
[Module mod-l1-0]
Type = Cache
Geometry = geo-l1
LowNetwork = net-l1-l2
LowModules = mod-l2-0
[Module mod-l2-0]
Type = Cache
Geometry = geo-l2

HighNetwork = net-l1-l2
LowNetwork = net-l2-mm
LowModules = mod-mm
[Module mod-mm]
Type = MainMemory
BlockSize = 256
Latency = 200
HighNetwork = net-l2-mm
[Network net-l1-l2]
DefaultInputBufferSize = 1024
DefaultOutputBufferSize = 1024
DefaultBandwidth = 256
[Network net-l2-mm]
DefaultInputBufferSize = 1024
DefaultOutputBufferSize = 1024
DefaultBandwidth = 256
[Entry core-0]
Arch = x86
Core = 0
Thread = 0
DataModule = mod-l1-0
InstModule = mod-l1-0

E: bug in multi2sim-5.0 for FastForward:

I am not sure if it has in github version, but I find this bug and fix it by
modifying source code and re-install it. If you are using multi2sim-5.0, you
will find your FastForward setting doesnt work anyway.
The reason is: m2s read the x86-config-file but doesnt match the
FastForward item. So, it will ignore your FastForward setting.
Fix: modify the code:
xxxx/multi2sim-5.0/src/arch/x86/timing/Cpu.cc
Cpu.cc <line 139>, insert one line at 139 with:
num_fast_forward_instructions = ini_file->ReadInt(section, "FastForward",
num_fast_forward_instructions);

Then reinstall multi2sim.

Also you will find the multi2sim is open source and the code is very
straightforward. In fact, your project contains to change some of the source
code and model your new architecture.

Good luck!