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    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
61    examples/common/cli_parser.{cc,hh}     -- Simple cli argument parser
62    examples/common/report_hanlder.{cc,hh} -- Custom SystemC report handler
63
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
66
67    examples/master_port/main.cc          -- demonstration of the master port
68    examples/master_port/traffic_generator.{cc/hh}
69                                         -- an example traffic generator module
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
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
104To build all sources of the SystemC binding and the examples simply run scons:
105
106> scons
107
108
109IV. Simple Examples
110===================
111
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
116> ../../build/ARM/gem5.opt conf/tlm_{master,slave}.py
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
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.
124
125Try:
126
127> build/examples/{master,slave}_port/gem5.sc m5out/config.ini -e 1000000
128
129It should run a simulation for 1us.
130
131To see more information what happens inside the TLM modules use the -v flag:
132
133> build/{master,slave}_port/gem5.sc m5out/config.ini -e 1000000 -v
134
135
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
142Build gem5 as described in Section III. Then, make a config file for the
143C++-configured gem5 using normal gem5
144
145> ../../build/ARM/gem5.opt ../../configs/example/fs.py               \
146  --tlm-memory=transactor --cpu-type=TimingSimpleCPU --num-cpu=1     \
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
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.
158
159Try:
160
161> build/examples/slave_port/gem5.sc m5out/config.ini -o 2147483648
162
163The parameter -o specifies the begining of the memory region (0x80000000).
164The system should boot now.
165
166For convenience a run_gem5_fs.sh file holds all those commands
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
183Similar to IV. the simulation can be set up with this command:
184
185> ../../build/ARM/gem5.opt ./conf/tlm_elastic_slave.py
186
187or
188
189> ../../build/ARM/gem5.opt ./conf/tlm_elastic_slave_with_l2.py
190
191Then:
192
193> build/examples/slave_port/gem5.sc m5out/config.ini
194
195
196VII. Knwon issues
197=================
198
199* For some toolchains, compiling libgem5 with tcmalloc leads to errors
200  ('tcmalloc Attempt to free invalid pointer xxx') when linking libgem5 into a
201  SystemC application.
202* When SystemC is build with pthread support enabled, the binding of gem5 to
203  SystemC breaks. When gem5 is linked to a SystemC application, gem5's usage
204  of thread local storage results in a segfault.
205