README revision 12207
111832SChristian.Menard@tu-dresden.deThis directory contains a demo of a coupling between gem5 and SystemC-TLM.  It
211832SChristian.Menard@tu-dresden.deis based on the gem5-systemc implementation in utils/systemc. This Readme gives
311832SChristian.Menard@tu-dresden.dean overall overview (I), describes the source files in this directory (II),
411832SChristian.Menard@tu-dresden.deexplains the build steps (III), shows how to run example simulations (IV-VI)
511832SChristian.Menard@tu-dresden.deand lists known issues (VII).
610993Sjungma@eit.uni-kl.de
710993Sjungma@eit.uni-kl.de
811832SChristian.Menard@tu-dresden.deI. Overview
911832SChristian.Menard@tu-dresden.de===========
1011832SChristian.Menard@tu-dresden.de
1111832SChristian.Menard@tu-dresden.deThe sources in this directory provide three SystemC modules that manage the
1211832SChristian.Menard@tu-dresden.deSystemC/gem5 co-simulation: Gem5SimControl, Gem5MasterTransactor, and
1311832SChristian.Menard@tu-dresden.deGem5SlaveTransactor. They also implement gem5's ExternalMaster::Port interface
1411832SChristian.Menard@tu-dresden.de(SCMasterPort) and ExternalSlave::Port interface (SCSlavePort).
1511832SChristian.Menard@tu-dresden.de
1611832SChristian.Menard@tu-dresden.de**SCMasterPort** and **Gem5MasterTransactor** together form a TLM-to-gem5
1711832SChristian.Menard@tu-dresden.debridge. SCMasterPort implements gem5's ExternalMaster::Port interface and forms
1811832SChristian.Menard@tu-dresden.dethe gem5 end of the bridge. Gem5MasterTransactor is a SystemC module that
1911832SChristian.Menard@tu-dresden.deprovides a target socket and represents the TLM side of the bridge. All TLM
2011832SChristian.Menard@tu-dresden.derequests send to this target socket, are translated to gem5 requests and
2111832SChristian.Menard@tu-dresden.deforwarded to the gem5 world through the SCMasterPort. Then the gem5 world
2211832SChristian.Menard@tu-dresden.dehandles the request and eventually issues a response. When the response arrives
2311832SChristian.Menard@tu-dresden.deat the SCMasterPort it gets translated back into a TLM response and forwarded
2411832SChristian.Menard@tu-dresden.deto the TLM world through target socket of the Gem5MasterTransactor.
2511832SChristian.Menard@tu-dresden.deSCMasterPort and Gem5MasterTransactor are bound to each other by configuring
2611832SChristian.Menard@tu-dresden.dethem for the same port name.
2711832SChristian.Menard@tu-dresden.de
2811832SChristian.Menard@tu-dresden.de**SCSlavePort** and **Gem5SlaveTransactor** together form a gem5-to-TLM bridge.
2911832SChristian.Menard@tu-dresden.deGem5SlaveTransactor is a SystemC module that provides a initiator socket and
3011832SChristian.Menard@tu-dresden.derepresents the TLM end of the bridge. SCSlavePort implements gem5's
3111832SChristian.Menard@tu-dresden.deExternalSlave::Port interface and forms the gem5 side of the bridge. All gem5
3211971Szulian@eit.uni-kl.derequests sent to the SCSlavePort, are translated to TLM requests and forwarded
3311832SChristian.Menard@tu-dresden.deto the TLM world through the initiator socket of the Gem5SlaveTransactor. Then
3411832SChristian.Menard@tu-dresden.dethe TLM world handles the request and eventually issues a response. When the
3511971Szulian@eit.uni-kl.deresponse arrives at the Gem5SlaveTransactor it gets translated back into a
3611971Szulian@eit.uni-kl.degem5 response and forwarded to the gem5 world through the SCSlavePort. SCSLavePort
3711832SChristian.Menard@tu-dresden.deand Gem5SlaveTransactor are bound to each other by configuring them for the
3811832SChristian.Menard@tu-dresden.desame port name.
3911832SChristian.Menard@tu-dresden.de
4011832SChristian.Menard@tu-dresden.de**Gem5SimControl** is the central SystemC module that represents the complete
4111832SChristian.Menard@tu-dresden.degem5 world. It is responsible for instantiating all gem5 objects according to a
4211832SChristian.Menard@tu-dresden.degiven configuration file, for configuring the simulation and for maintaining
4311832SChristian.Menard@tu-dresden.dethe gem5 event queue. It also keeps track of all SCMasterPort and SCSlavePort
4411832SChristian.Menard@tu-dresden.deand responsible for connecting all Gem5MasterTransactor and Gem5SlaveTransactor
4511832SChristian.Menard@tu-dresden.demodules to their gem5 counterparts. This module must be instantiated exactly
4611832SChristian.Menard@tu-dresden.deonce in order to run a gem5 simulation from within an SystemC environment.
4711832SChristian.Menard@tu-dresden.de
4811832SChristian.Menard@tu-dresden.de
4911832SChristian.Menard@tu-dresden.deII. Files
5011832SChristian.Menard@tu-dresden.de=========
5111832SChristian.Menard@tu-dresden.de
5212047Schristian.menard@tu-dresden.de    src/sc_slave_port.{cc,hh}     -- Implements SCSlavePort
5312047Schristian.menard@tu-dresden.de    src/sc_master_port.{cc,hh}    -- Implements SCMasterPort
5412047Schristian.menard@tu-dresden.de    src/sc_mm.{cc,hh}             -- Implementation of a TLM memory manager
5512047Schristian.menard@tu-dresden.de    src/sc_ext.{cc,hh}            -- TLM extension that carries a gem5 packet
5612047Schristian.menard@tu-dresden.de    src/sc_peq.{cc,hh}            -- TLM PEQ for scheduling gem5 events
5712047Schristian.menard@tu-dresden.de    src/sim_control.{cc,hh}       -- Implements Gem5SimControl
5812047Schristian.menard@tu-dresden.de    src/slave_transactor.{cc,hh}  -- Implements Gem5SlaveTransactor
5912047Schristian.menard@tu-dresden.de    src/master_transactor.{cc,hh} -- Implements Gem5MasterTransactor
6011832SChristian.Menard@tu-dresden.de
6112047Schristian.menard@tu-dresden.de    examples/common/cli_parser.{cc,hh}     -- Simple cli argument parser
6212047Schristian.menard@tu-dresden.de    examples/common/report_hanlder.{cc,hh} -- Custom SystemC report handler
6311832SChristian.Menard@tu-dresden.de
6412047Schristian.menard@tu-dresden.de    examples/slave_port/main.cc           -- demonstration of the slave port
6512047Schristian.menard@tu-dresden.de    examples/slave_port/sc_target.{cc,hh} -- an example TLM LT/AT memory module
6611832SChristian.Menard@tu-dresden.de
6712047Schristian.menard@tu-dresden.de    examples/master_port/main.cc          -- demonstration of the master port
6812047Schristian.menard@tu-dresden.de    examples/master_port/traffic_generator.{cc/hh}
6911832SChristian.Menard@tu-dresden.de                                         -- an example traffic generator module
7012047Schristian.menard@tu-dresden.de
7112047Schristian.menard@tu-dresden.de    conf/tlm_slave.py           -- simple gem5 configuration connecting to a
7212047Schristian.menard@tu-dresden.de                                   SytemC/TLM slave module
7312047Schristian.menard@tu-dresden.de    conf/tlm_elastic_slave.py   -- gem5 configuration with an elastic trace
7412047Schristian.menard@tu-dresden.de                                   replayer
7512047Schristian.menard@tu-dresden.de    conf/tlm_master.py          -- simple gem5 configuration connecting to a
7612047Schristian.menard@tu-dresden.de                                   SytemC/TLM master module
7712047Schristian.menard@tu-dresden.de    conf/tgen.cfg               -- trace generator configuration
7810993Sjungma@eit.uni-kl.de
7910993Sjungma@eit.uni-kl.deOther Files will be used from utils/systemc example:
8010993Sjungma@eit.uni-kl.de
8110993Sjungma@eit.uni-kl.de    sc_logger.{cc,hh},
8210993Sjungma@eit.uni-kl.de    sc_module.{cc,hh},
8310993Sjungma@eit.uni-kl.de    sc_gem5_control.{cc,hh},
8410993Sjungma@eit.uni-kl.de    stats.{cc,hh}
8510993Sjungma@eit.uni-kl.de
8610993Sjungma@eit.uni-kl.de
8711832SChristian.Menard@tu-dresden.deIII. Build
8811832SChristian.Menard@tu-dresden.de==========
8910993Sjungma@eit.uni-kl.de
9010993Sjungma@eit.uni-kl.deFirst build a normal gem5 (cxx-config not needed, Python needed).
9110993Sjungma@eit.uni-kl.deSecond build gem5 as a library with cxx-config support and (optionally)
9210993Sjungma@eit.uni-kl.dewithout python.
9310993Sjungma@eit.uni-kl.de
9410993Sjungma@eit.uni-kl.de> cd ../..
9510993Sjungma@eit.uni-kl.de> scons build/ARM/gem5.opt
9611832SChristian.Menard@tu-dresden.de> scons --with-cxx-config --without-python --without-tcmalloc \
9711832SChristian.Menard@tu-dresden.de>       build/ARM/libgem5_opt.so
9811099Sabdul.mutaal@gmail.com> cd util/tlm
9910993Sjungma@eit.uni-kl.de
10011791Sjungma@eit.uni-kl.deNote: For MAC / OSX this command should be used:
10111832SChristian.Menard@tu-dresden.de> scons --with-cxx-config --without-python --without-tcmalloc \
10211832SChristian.Menard@tu-dresden.de>       build/ARM/libgem5_opt.dylib
10311791Sjungma@eit.uni-kl.de
10412047Schristian.menard@tu-dresden.deTo build all sources of the SystemC binding and the examples simply run scons:
10510993Sjungma@eit.uni-kl.de
10611832SChristian.Menard@tu-dresden.de> scons
10711791Sjungma@eit.uni-kl.de
10810993Sjungma@eit.uni-kl.de
10911832SChristian.Menard@tu-dresden.deIV. Simple Examples
11011832SChristian.Menard@tu-dresden.de===================
11110993Sjungma@eit.uni-kl.de
11211832SChristian.Menard@tu-dresden.deIn order to run our example simulation, we first need to create a config.ini
11311832SChristian.Menard@tu-dresden.dethat represents the gem5 configuration. We do so by starting gem5 with the
11411832SChristian.Menard@tu-dresden.dedesired python configuration script.
11510993Sjungma@eit.uni-kl.de
11612047Schristian.menard@tu-dresden.de> ../../build/ARM/gem5.opt conf/tlm_{master,slave}.py
11711832SChristian.Menard@tu-dresden.de
11811832SChristian.Menard@tu-dresden.deThe message "fatal: Can't find port handler type 'tlm_{master,slave}'" is okay.
11910993Sjungma@eit.uni-kl.deThe configuration will be stored in the m5out/ directory
12010993Sjungma@eit.uni-kl.de
12112047Schristian.menard@tu-dresden.deThe build step creates a binary 'gem5.sc' for each example in the
12212047Schristian.menard@tu-dresden.debuild/examples/{master|slave}_port directories. It can now be used to load in
12312047Schristian.menard@tu-dresden.dethe generated configuration file from the previous normal gem5 run.
12410993Sjungma@eit.uni-kl.de
12510993Sjungma@eit.uni-kl.deTry:
12610993Sjungma@eit.uni-kl.de
12712047Schristian.menard@tu-dresden.de> build/examples/{master,slave}_port/gem5.sc m5out/config.ini -e 1000000
12810993Sjungma@eit.uni-kl.de
12910993Sjungma@eit.uni-kl.deIt should run a simulation for 1us.
13010993Sjungma@eit.uni-kl.de
13111832SChristian.Menard@tu-dresden.deTo see more information what happens inside the TLM modules use the -v flag:
13210993Sjungma@eit.uni-kl.de
13312047Schristian.menard@tu-dresden.de> build/{master,slave}_port/gem5.sc m5out/config.ini -e 1000000 -v
13410993Sjungma@eit.uni-kl.de
13511832SChristian.Menard@tu-dresden.de
13611832SChristian.Menard@tu-dresden.deV. Full System Setup
13710993Sjungma@eit.uni-kl.de=====================
13810993Sjungma@eit.uni-kl.de
13911832SChristian.Menard@tu-dresden.deApart from the simple examples, there is a full system example that uses
14011832SChristian.Menard@tu-dresden.dethe gem5-to-TLM bridge.
14111832SChristian.Menard@tu-dresden.de
14211832SChristian.Menard@tu-dresden.deBuild gem5 as described in Section III. Then, make a config file for the
14310993Sjungma@eit.uni-kl.deC++-configured gem5 using normal gem5
14410993Sjungma@eit.uni-kl.de
14512047Schristian.menard@tu-dresden.de> ../../build/ARM/gem5.opt ../../configs/example/fs.py               \
14612047Schristian.menard@tu-dresden.de  --tlm-memory=transactor --cpu-type=TimingSimpleCPU --num-cpu=1     \
14711832SChristian.Menard@tu-dresden.de  --mem-type=SimpleMemory --mem-size=512MB --mem-channels=1 --caches \
14811832SChristian.Menard@tu-dresden.de  --l2cache --machine-type=VExpress_EMM                              \
14911832SChristian.Menard@tu-dresden.de  --dtb-filename=vexpress.aarch32.ll_20131205.0-gem5.1cpu.dtb        \
15011832SChristian.Menard@tu-dresden.de  --kernel=vmlinux.aarch32.ll_20131205.0-gem5                        \
15110993Sjungma@eit.uni-kl.de  --disk-image=linux-aarch32-ael.img
15210993Sjungma@eit.uni-kl.de
15311832SChristian.Menard@tu-dresden.deThe message "fatal: Can't find port handler type 'tlm_slave'" is okay.
15410993Sjungma@eit.uni-kl.deThe configuration will be stored in the m5out/ directory
15510993Sjungma@eit.uni-kl.de
15612047Schristian.menard@tu-dresden.deThe binary 'build/examples/slave_port/gem5.sc' can now be used to load in the
15712047Schristian.menard@tu-dresden.degenerated config file from the previous normal gem5 run.
15810993Sjungma@eit.uni-kl.de
15910993Sjungma@eit.uni-kl.deTry:
16010993Sjungma@eit.uni-kl.de
16112047Schristian.menard@tu-dresden.de> build/examples/slave_port/gem5.sc m5out/config.ini -o 2147483648
16210993Sjungma@eit.uni-kl.de
16310993Sjungma@eit.uni-kl.deThe parameter -o specifies the begining of the memory region (0x80000000).
16410993Sjungma@eit.uni-kl.deThe system should boot now.
16510993Sjungma@eit.uni-kl.de
16612047Schristian.menard@tu-dresden.deFor convenience a run_gem5_fs.sh file holds all those commands
16711554Sjungma@eit.uni-kl.de
16811554Sjungma@eit.uni-kl.de
16911832SChristian.Menard@tu-dresden.deVI. Elastic Trace Setup
17011554Sjungma@eit.uni-kl.de========================
17111554Sjungma@eit.uni-kl.de
17211554Sjungma@eit.uni-kl.deElastic traces can also be replayed into the SystemC world.
17311554Sjungma@eit.uni-kl.deFor more information on elastic traces please refer to:
17411554Sjungma@eit.uni-kl.de
17511554Sjungma@eit.uni-kl.de - http://www.gem5.org/TraceCPU
17611554Sjungma@eit.uni-kl.de
17711554Sjungma@eit.uni-kl.de - Exploring System Performance using Elastic Traces:
17811554Sjungma@eit.uni-kl.de   Fast, Accurate and Portable
17911554Sjungma@eit.uni-kl.de   R. Jagtap, S. Diestelhorst, A. Hansson, M. Jung, N. Wehn.
18011554Sjungma@eit.uni-kl.de   IEEE International Conference on Embedded Computer Systems Architectures
18111554Sjungma@eit.uni-kl.de   Modeling and Simulation (SAMOS), July, 2016, Samos Island, Greece.
18211554Sjungma@eit.uni-kl.de
18312047Schristian.menard@tu-dresden.deSimilar to IV. the simulation can be set up with this command:
18411554Sjungma@eit.uni-kl.de
18512047Schristian.menard@tu-dresden.de> ../../build/ARM/gem5.opt ./conf/tlm_elastic_slave.py
18611554Sjungma@eit.uni-kl.de
18712207Sjungma@eit.uni-kl.deor
18812207Sjungma@eit.uni-kl.de
18912207Sjungma@eit.uni-kl.de> ../../build/ARM/gem5.opt ./conf/tlm_elastic_slave_with_l2.py
19012207Sjungma@eit.uni-kl.de
19111554Sjungma@eit.uni-kl.deThen:
19211554Sjungma@eit.uni-kl.de
19312047Schristian.menard@tu-dresden.de> build/examples/slave_port/gem5.sc m5out/config.ini
19411832SChristian.Menard@tu-dresden.de
19511832SChristian.Menard@tu-dresden.de
19611832SChristian.Menard@tu-dresden.deVII. Knwon issues
19711832SChristian.Menard@tu-dresden.de=================
19811832SChristian.Menard@tu-dresden.de
19911832SChristian.Menard@tu-dresden.de* For some toolchains, compiling libgem5 with tcmalloc leads to errors
20011832SChristian.Menard@tu-dresden.de  ('tcmalloc Attempt to free invalid pointer xxx') when linking libgem5 into a
20111832SChristian.Menard@tu-dresden.de  SystemC application.
20212047Schristian.menard@tu-dresden.de* When SystemC is build with pthread support enabled, the binding of gem5 to
20312047Schristian.menard@tu-dresden.de  SystemC breaks. When gem5 is linked to a SystemC application, gem5's usage
20412047Schristian.menard@tu-dresden.de  of thread local storage results in a segfault.
205