1This directory contains a demo of a coupling between gem5 and SystemC-TLM.
2It is based on the gem5-systemc implementation in utils/systemc.
3First a simple example with gem5's traffic generator is shown, later an full
4system example.
| 1This directory contains a demo of a coupling between gem5 and SystemC-TLM. It
2is based on the gem5-systemc implementation in utils/systemc. This Readme gives
3an overall overview (I), describes the source files in this directory (II),
4explains the build steps (III), shows how to run example simulations (IV-VI)
5and lists known issues (VII).
|
5
| 6
|
6Files:
| |
7
| 7
|
8 main.cc -- demonstration top level
9 sc_port.{cc,hh} -- transactor that translates beween gem5 and tlm
10 sc_mm.{cc,hh} -- implementation of a tlm memory manager
11 sc_ext.{cc,hh} -- a TLM extension that carries the gem5 packet
12 sc_target.{cc,hh} -- an example TLM LT/AT memory module
13 tlm.py -- simple gem5 configuration
14 tgen.cfg -- configuration file for the traceplayer
| 8I. Overview
9===========
|
15
| 10
|
| 11The sources in this directory provide three SystemC modules that manage the
12SystemC/gem5 co-simulation: Gem5SimControl, Gem5MasterTransactor, and
13Gem5SlaveTransactor. They also implement gem5's ExternalMaster::Port interface
14(SCMasterPort) and ExternalSlave::Port interface (SCSlavePort).
15
16**SCMasterPort** and **Gem5MasterTransactor** together form a TLM-to-gem5
17bridge. SCMasterPort implements gem5's ExternalMaster::Port interface and forms
18the gem5 end of the bridge. Gem5MasterTransactor is a SystemC module that
19provides a target socket and represents the TLM side of the bridge. All TLM
20requests send to this target socket, are translated to gem5 requests and
21forwarded to the gem5 world through the SCMasterPort. Then the gem5 world
22handles the request and eventually issues a response. When the response arrives
23at the SCMasterPort it gets translated back into a TLM response and forwarded
24to the TLM world through target socket of the Gem5MasterTransactor.
25SCMasterPort and Gem5MasterTransactor are bound to each other by configuring
26them for the same port name.
27
28**SCSlavePort** and **Gem5SlaveTransactor** together form a gem5-to-TLM bridge.
29Gem5SlaveTransactor is a SystemC module that provides a initiator socket and
30represents the TLM end of the bridge. SCSlavePort implements gem5's
31ExternalSlave::Port interface and forms the gem5 side of the bridge. All gem5
32requests send to the SCSlavePort, are translated to TLM requests and forwarded
33to the TLM world through the initiator socket of the Gem5SlaveTransactor. Then
34the TLM world handles the request and eventually issues a response. When the
35response arrives at the Gem5SlaveTransactor it gets translated back into a TLM
36response and forwarded to the gem5 world through the SCSlavePort. SCSLavePort
37and Gem5SlaveTransactor are bound to each other by configuring them for the
38same port name.
39
40**Gem5SimControl** is the central SystemC module that represents the complete
41gem5 world. It is responsible for instantiating all gem5 objects according to a
42given configuration file, for configuring the simulation and for maintaining
43the gem5 event queue. It also keeps track of all SCMasterPort and SCSlavePort
44and responsible for connecting all Gem5MasterTransactor and Gem5SlaveTransactor
45modules to their gem5 counterparts. This module must be instantiated exactly
46once in order to run a gem5 simulation from within an SystemC environment.
47
48
49II. Files
50=========
51
52 sc_slave_port.{cc,hh} -- Implements SCSlavePort
53 sc_master_port.{cc,hh} -- Implements SCMasterPort
54 sc_mm.{cc,hh} -- Implementation of a TLM memory manager
55 sc_ext.{cc,hh} -- TLM extension that carries a gem5 packet
56 sc_peq.{cc,hh} -- TLM PEQ for scheduling gem5 events
57 sim_control.{cc,hh} -- Implements Gem5SimControl
58 slave_transactor.{cc,hh} -- Implements Gem5SlaveTransactor
59 master_transactor.{cc,hh} -- Implements Gem5MasterTransactor
60
61 example/common/cli_parser.{cc,hh} -- Simple cli argument parser
62 example/common/report_hanlder.{cc,hh} -- Custom SystemC report handler
63
64 example/slave_port/main.cc -- demonstration of the slave port
65 example/slave_port/sc_target.{cc,hh} -- an example TLM LT/AT memory module
66 example/slave_port/tlm.py -- simple gem5 configuration
67 example/slave_port/tlm_elastic.py -- gem5 configuration with an elastic
68 trace replayer
69 example/slave_port/tgen.cfg -- elastic traceplayer configuration
70
71 example/master_port/main.cc -- demonstration of the master port
72 example/master_port/traffic_generator.{cc/hh}
73 -- an example traffic generator module
74 example/master_port/tlm.py -- simple gem5 configuration
75
|
16Other Files will be used from utils/systemc example:
17
18 sc_logger.{cc,hh},
19 sc_module.{cc,hh},
20 sc_gem5_control.{cc,hh},
21 stats.{cc,hh}
22
23
| 76Other Files will be used from utils/systemc example:
77
78 sc_logger.{cc,hh},
79 sc_module.{cc,hh},
80 sc_gem5_control.{cc,hh},
81 stats.{cc,hh}
82
83
|
24I. Traffic Generator Setup
25==========================
| 84III. Build
85==========
|
26
| 86
|
27To build:
28
| |
29First build a normal gem5 (cxx-config not needed, Python needed).
30Second build gem5 as a library with cxx-config support and (optionally)
31without python.
32
33> cd ../..
34> scons build/ARM/gem5.opt
| 87First build a normal gem5 (cxx-config not needed, Python needed).
88Second build gem5 as a library with cxx-config support and (optionally)
89without python.
90
91> cd ../..
92> scons build/ARM/gem5.opt
|
35> scons --with-cxx-config --without-python build/ARM/libgem5_opt.so
| 93> scons --with-cxx-config --without-python --without-tcmalloc \
94> build/ARM/libgem5_opt.so
|
36> cd util/tlm
37
38Note: For MAC / OSX this command should be used:
| 95> cd util/tlm
96
97Note: For MAC / OSX this command should be used:
|
39> scons --with-cxx-config --without-python build/ARM/libgem5_opt.dylib
| 98> scons --with-cxx-config --without-python --without-tcmalloc \
99> build/ARM/libgem5_opt.dylib
|
40
41Set a proper LD_LIBRARY_PATH e.g. for bash:
42> export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:/path/to/gem5/build/ARM/"
43
44or for MAC / OSX:
45> export DYLD_LIBRARY_PATH="$DYLD_LIBRARY_PATH:/path/to/gem5/build/ARM/"
46
| 100
101Set a proper LD_LIBRARY_PATH e.g. for bash:
102> export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:/path/to/gem5/build/ARM/"
103
104or for MAC / OSX:
105> export DYLD_LIBRARY_PATH="$DYLD_LIBRARY_PATH:/path/to/gem5/build/ARM/"
106
|
47Then edit the Makefile to set the paths for SystemC:
| 107The build system finds your SystemC installation using pkg-config. Make sure
108that pkg-config is installed and your systemc.pc is within your
109PKG_CONFIG_PATH. You can add SystemC to the PKG_CONFIG_PATH using the following
110command:
111> export PKG_CONFIG_PATH="/path/to/systemc/lib-<arch>/pkgconfig/:$PKG_CONFIG_PATH"
|
48
| 112
|
49 Linux:
50 SYSTEMC_INC = /opt/systemc/include
51 SYSTEMC_LIB = /opt/systemc/lib-linux64
| 113To build one of the examples:
|
52
| 114
|
53 MAC / OSX:
54 SYSTEMC_INC = /opt/systemc/include
55 SYSTEMC_LIB = /opt/systemc/lib-macosx64
| 115> cd examples/{master,slave}_port
116> scons
117> cd ../../
|
56
| 118
|
57Then run make:
| |
58
| 119
|
59> make
| 120IV. Simple Examples
121===================
|
60
| 122
|
61Make a config file for the C++-configured gem5 using normal gem5
| 123> cd examples/{master,slave}_port
|
62
| 124
|
63> ../../build/ARM/gem5.opt ./tlm.py
| 125In order to run our example simulation, we first need to create a config.ini
126that represents the gem5 configuration. We do so by starting gem5 with the
127desired python configuration script.
|
64
| 128
|
65The message "fatal: Can't find port handler type 'tlm'" is okay.
| 129> ../../../../build/ARM/gem5.opt ./tlm.py
130
131The message "fatal: Can't find port handler type 'tlm_{master,slave}'" is okay.
|
66The configuration will be stored in the m5out/ directory
67
| 132The configuration will be stored in the m5out/ directory
133
|
68The binary 'gem5.opt.sc', that has been created in the make step,
69can now be used to load in the generated config file from the previous
| 134The build step creates a binary gem5.opt.sc in the example directory. It can
135now be used to load in the generated configuration file from the previous
|
70normal gem5 run.
71
72Try:
73
74> ./gem5.opt.sc m5out/config.ini -e 1000000
75
76It should run a simulation for 1us.
77
| 136normal gem5 run.
137
138Try:
139
140> ./gem5.opt.sc m5out/config.ini -e 1000000
141
142It should run a simulation for 1us.
143
|
78To see more information what happens inside the TLM module use the -D flag:
| 144To see more information what happens inside the TLM modules use the -v flag:
|
79
| 145
|
80> ./gem5.opt.sc m5out/config.ini -e 1000000 -D
| 146> ./gem5.opt.sc m5out/config.ini -e 1000000 -v
|
81
82To see more information about the port coupling use:
83
84> ./gem5.opt.sc m5out/config.ini -e 1000000 -d ExternalPort
85
| 147
148To see more information about the port coupling use:
149
150> ./gem5.opt.sc m5out/config.ini -e 1000000 -d ExternalPort
151
|
86II. Full System Setup
| 152
153V. Full System Setup
|
87=====================
88
| 154=====================
155
|
89Build gem5 as discribed in Section I. Then, make a config file for the
| 156Apart from the simple examples, there is a full system example that uses
157the gem5-to-TLM bridge.
158
159>cd examples/slave_port
160
161Build gem5 as described in Section III. Then, make a config file for the
|
90C++-configured gem5 using normal gem5
91
| 162C++-configured gem5 using normal gem5
163
|
92> ../../build/ARM/gem5.opt ../../configs/example/fs.py --tlm-memory=memory \
93 --cpu-type=timing --num-cpu=1 --mem-type=SimpleMemory --mem-size=512MB \
94 --mem-channels=1 --caches --l2cache --machine-type=VExpress_EMM \
95 --dtb-filename=vexpress.aarch32.ll_20131205.0-gem5.1cpu.dtb \
96 --kernel=vmlinux.aarch32.ll_20131205.0-gem5 \
| 164> ../../../../build/ARM/gem5.opt ../../../../configs/example/fs.py \
165 --tlm-memory=transactor --cpu-type=timing --num-cpu=1 \
166 --mem-type=SimpleMemory --mem-size=512MB --mem-channels=1 --caches \
167 --l2cache --machine-type=VExpress_EMM \
168 --dtb-filename=vexpress.aarch32.ll_20131205.0-gem5.1cpu.dtb \
169 --kernel=vmlinux.aarch32.ll_20131205.0-gem5 \
|
97 --disk-image=linux-aarch32-ael.img
98
| 170 --disk-image=linux-aarch32-ael.img
171
|
99The message "fatal: Can't find port handler type 'tlm'" is okay.
| 172The message "fatal: Can't find port handler type 'tlm_slave'" is okay.
|
100The configuration will be stored in the m5out/ directory
101
102The binary 'gem5.opt.sc' can now be used to load in the generated config
103file from the previous normal gem5 run.
104
105Try:
106
107> ./gem5.opt.sc m5out/config.ini -o 2147483648
108
109The parameter -o specifies the begining of the memory region (0x80000000).
110The system should boot now.
111
| 173The configuration will be stored in the m5out/ directory
174
175The binary 'gem5.opt.sc' can now be used to load in the generated config
176file from the previous normal gem5 run.
177
178Try:
179
180> ./gem5.opt.sc m5out/config.ini -o 2147483648
181
182The parameter -o specifies the begining of the memory region (0x80000000).
183The system should boot now.
184
|
112For conveniance a run_gem5.sh file holds all those commands
| 185For convenience a run_gem5.sh file holds all those commands
|
113
114
| 186
187
|
115III. Elastic Trace Setup
| 188VI. Elastic Trace Setup
|
116========================
117
118Elastic traces can also be replayed into the SystemC world.
119For more information on elastic traces please refer to:
120
121 - http://www.gem5.org/TraceCPU
122
123 - Exploring System Performance using Elastic Traces:
124 Fast, Accurate and Portable
125 R. Jagtap, S. Diestelhorst, A. Hansson, M. Jung, N. Wehn.
126 IEEE International Conference on Embedded Computer Systems Architectures
127 Modeling and Simulation (SAMOS), July, 2016, Samos Island, Greece.
128
| 189========================
190
191Elastic traces can also be replayed into the SystemC world.
192For more information on elastic traces please refer to:
193
194 - http://www.gem5.org/TraceCPU
195
196 - Exploring System Performance using Elastic Traces:
197 Fast, Accurate and Portable
198 R. Jagtap, S. Diestelhorst, A. Hansson, M. Jung, N. Wehn.
199 IEEE International Conference on Embedded Computer Systems Architectures
200 Modeling and Simulation (SAMOS), July, 2016, Samos Island, Greece.
201
|
129Similar to I. the simulation can be set up with this command:
| 202Similar IV. the simulation can be set up with this command:
|
130
| 203
|
131> ../../build/ARM/gem5.opt ./tlm_elastic.py
| 204> ../../../../build/ARM/gem5.opt ./tlm_elastic.py
|
132
133Then:
134
135> ./gem5.opt.sc m5out/config.ini
| 205
206Then:
207
208> ./gem5.opt.sc m5out/config.ini
|
| 209
210
211VII. Knwon issues
212=================
213
214* For some toolchains, compiling libgem5 with tcmalloc leads to errors
215 ('tcmalloc Attempt to free invalid pointer xxx') when linking libgem5 into a
216 SystemC application.
217* When SystemC was build with --enable-pthreads, SystemC applications linked
|
| |