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). 6 7 8I. Overview 9=========== 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 sent 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 36gem5 response 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
| 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). 6 7 8I. Overview 9=========== 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 sent 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 36gem5 response 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
| 52 src/sc_slave_port.{cc,hh} -- Implements SCSlavePort 53 src/sc_master_port.{cc,hh} -- Implements SCMasterPort 54 src/sc_mm.{cc,hh} -- Implementation of a TLM memory manager 55 src/sc_ext.{cc,hh} -- TLM extension that carries a gem5 packet 56 src/sc_peq.{cc,hh} -- TLM PEQ for scheduling gem5 events 57 src/sim_control.{cc,hh} -- Implements Gem5SimControl 58 src/slave_transactor.{cc,hh} -- Implements Gem5SlaveTransactor 59 src/master_transactor.{cc,hh} -- Implements Gem5MasterTransactor
|
60
| 60
|
61 example/common/cli_parser.{cc,hh} -- Simple cli argument parser 62 example/common/report_hanlder.{cc,hh} -- Custom SystemC report handler
| 61 examples/common/cli_parser.{cc,hh} -- Simple cli argument parser 62 examples/common/report_hanlder.{cc,hh} -- Custom SystemC report handler
|
63
| 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
| 64 examples/slave_port/main.cc -- demonstration of the slave port 65 examples/slave_port/sc_target.{cc,hh} -- an example TLM LT/AT memory module
|
70
| 66
|
71 example/master_port/main.cc -- demonstration of the master port 72 example/master_port/traffic_generator.{cc/hh}
| 67 examples/master_port/main.cc -- demonstration of the master port 68 examples/master_port/traffic_generator.{cc/hh}
|
73 -- an example traffic generator module
| 69 -- an example traffic generator module
|
74 example/master_port/tlm.py -- simple gem5 configuration
| |
75
| 70
|
| 71 conf/tlm_slave.py -- simple gem5 configuration connecting to a 72 SytemC/TLM slave module 73 conf/tlm_elastic_slave.py -- gem5 configuration with an elastic trace 74 replayer 75 conf/tlm_master.py -- simple gem5 configuration connecting to a 76 SytemC/TLM master module 77 conf/tgen.cfg -- trace generator configuration 78
|
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 84III. Build 85========== 86 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 93> scons --with-cxx-config --without-python --without-tcmalloc \ 94> build/ARM/libgem5_opt.so 95> cd util/tlm 96 97Note: For MAC / OSX this command should be used: 98> scons --with-cxx-config --without-python --without-tcmalloc \ 99> build/ARM/libgem5_opt.dylib 100
| 79Other Files will be used from utils/systemc example: 80 81 sc_logger.{cc,hh}, 82 sc_module.{cc,hh}, 83 sc_gem5_control.{cc,hh}, 84 stats.{cc,hh} 85 86 87III. Build 88========== 89 90First build a normal gem5 (cxx-config not needed, Python needed). 91Second build gem5 as a library with cxx-config support and (optionally) 92without python. 93 94> cd ../.. 95> scons build/ARM/gem5.opt 96> scons --with-cxx-config --without-python --without-tcmalloc \ 97> build/ARM/libgem5_opt.so 98> cd util/tlm 99 100Note: For MAC / OSX this command should be used: 101> scons --with-cxx-config --without-python --without-tcmalloc \ 102> build/ARM/libgem5_opt.dylib 103
|
101Set a proper LD_LIBRARY_PATH e.g. for bash: 102> export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:/path/to/gem5/build/ARM/"
| 104To build all sources of the SystemC binding and the examples simply run scons:
|
103
| 105
|
104or for MAC / OSX: 105> export DYLD_LIBRARY_PATH="$DYLD_LIBRARY_PATH:/path/to/gem5/build/ARM/" 106 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" 112 113To build one of the examples: 114 115> cd examples/{master,slave}_port
| |
116> scons
| 106> scons
|
117> cd ../../
| |
118 119 120IV. Simple Examples 121=================== 122
| 107 108 109IV. Simple Examples 110=================== 111
|
123> cd examples/{master,slave}_port 124
| |
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. 128
| 112In order to run our example simulation, we first need to create a config.ini 113that represents the gem5 configuration. We do so by starting gem5 with the 114desired python configuration script. 115
|
129> ../../../../build/ARM/gem5.opt ./tlm.py
| 116> ../../build/ARM/gem5.opt conf/tlm_{master,slave}.py
|
130 131The message "fatal: Can't find port handler type 'tlm_{master,slave}'" is okay. 132The configuration will be stored in the m5out/ directory 133
| 117 118The message "fatal: Can't find port handler type 'tlm_{master,slave}'" is okay. 119The configuration will be stored in the m5out/ directory 120
|
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 136normal gem5 run.
| 121The build step creates a binary 'gem5.sc' for each example in the 122build/examples/{master|slave}_port directories. It can now be used to load in 123the generated configuration file from the previous normal gem5 run.
|
137 138Try: 139
| 124 125Try: 126
|
140> ./gem5.opt.sc m5out/config.ini -e 1000000
| 127> build/examples/{master,slave}_port/gem5.sc m5out/config.ini -e 1000000
|
141 142It should run a simulation for 1us. 143 144To see more information what happens inside the TLM modules use the -v flag: 145
| 128 129It should run a simulation for 1us. 130 131To see more information what happens inside the TLM modules use the -v flag: 132
|
146> ./gem5.opt.sc m5out/config.ini -e 1000000 -v
| 133> build/{master,slave}_port/gem5.sc m5out/config.ini -e 1000000 -v
|
147
| 134
|
148To see more information about the port coupling use:
| |
149
| 135
|
150> ./gem5.opt.sc m5out/config.ini -e 1000000 -d ExternalPort 151 152
| |
153V. Full System Setup 154===================== 155 156Apart from the simple examples, there is a full system example that uses 157the gem5-to-TLM bridge. 158
| 136V. Full System Setup 137===================== 138 139Apart from the simple examples, there is a full system example that uses 140the gem5-to-TLM bridge. 141
|
159>cd examples/slave_port 160
| |
161Build gem5 as described in Section III. Then, make a config file for the 162C++-configured gem5 using normal gem5 163
| 142Build gem5 as described in Section III. Then, make a config file for the 143C++-configured gem5 using normal gem5 144
|
164> ../../../../build/ARM/gem5.opt ../../../../configs/example/fs.py \ 165 --tlm-memory=transactor --cpu-type=timing --num-cpu=1 \
| 145> ../../build/ARM/gem5.opt ../../configs/example/fs.py \ 146 --tlm-memory=transactor --cpu-type=TimingSimpleCPU --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 \ 170 --disk-image=linux-aarch32-ael.img 171 172The message "fatal: Can't find port handler type 'tlm_slave'" is okay. 173The configuration will be stored in the m5out/ directory 174
| 147 --mem-type=SimpleMemory --mem-size=512MB --mem-channels=1 --caches \ 148 --l2cache --machine-type=VExpress_EMM \ 149 --dtb-filename=vexpress.aarch32.ll_20131205.0-gem5.1cpu.dtb \ 150 --kernel=vmlinux.aarch32.ll_20131205.0-gem5 \ 151 --disk-image=linux-aarch32-ael.img 152 153The message "fatal: Can't find port handler type 'tlm_slave'" is okay. 154The configuration will be stored in the m5out/ directory 155
|
175The binary 'gem5.opt.sc' can now be used to load in the generated config 176file from the previous normal gem5 run.
| 156The binary 'build/examples/slave_port/gem5.sc' can now be used to load in the 157generated config file from the previous normal gem5 run.
|
177 178Try: 179
| 158 159Try: 160
|
180> ./gem5.opt.sc m5out/config.ini -o 2147483648
| 161> build/examples/slave_port/gem5.sc m5out/config.ini -o 2147483648
|
181 182The parameter -o specifies the begining of the memory region (0x80000000). 183The system should boot now. 184
| 162 163The parameter -o specifies the begining of the memory region (0x80000000). 164The system should boot now. 165
|
185For convenience a run_gem5.sh file holds all those commands
| 166For convenience a run_gem5_fs.sh file holds all those commands
|
186 187 188VI. Elastic Trace Setup 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
| 167 168 169VI. Elastic Trace Setup 170======================== 171 172Elastic traces can also be replayed into the SystemC world. 173For more information on elastic traces please refer to: 174 175 - http://www.gem5.org/TraceCPU 176 177 - Exploring System Performance using Elastic Traces: 178 Fast, Accurate and Portable 179 R. Jagtap, S. Diestelhorst, A. Hansson, M. Jung, N. Wehn. 180 IEEE International Conference on Embedded Computer Systems Architectures 181 Modeling and Simulation (SAMOS), July, 2016, Samos Island, Greece. 182
|
202Similar IV. the simulation can be set up with this command:
| 183Similar to IV. the simulation can be set up with this command:
|
203
| 184
|
204> ../../../../build/ARM/gem5.opt ./tlm_elastic.py
| 185> ../../build/ARM/gem5.opt ./conf/tlm_elastic_slave.py
|
205 206Then: 207
| 186 187Then: 188
|
208> ./gem5.opt.sc m5out/config.ini
| 189> build/examples/slave_port/gem5.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.
| 190 191 192VII. Knwon issues 193================= 194 195* For some toolchains, compiling libgem5 with tcmalloc leads to errors 196 ('tcmalloc Attempt to free invalid pointer xxx') when linking libgem5 into a 197 SystemC application.
|
217* When SystemC was build with --enable-pthreads, SystemC applications linked
| 198* When SystemC is build with pthread support enabled, the binding of gem5 to 199 SystemC breaks. When gem5 is linked to a SystemC application, gem5's usage 200 of thread local storage results in a segfault.
|
| |