util/tlm/README

   1 This directory contains a demo of a coupling between gem5 and SystemC-TLM.  It
   2 is based on the gem5-systemc implementation in utils/systemc. This Readme gives
   3 an overall overview (I), describes the source files in this directory (II),
   4 explains the build steps (III), shows how to run example simulations (IV-VI)
   5 and lists known issues (VII).
   6
   7
   8 I. Overview
   9 ===========
  10
  11 The sources in this directory provide three SystemC modules that manage the
  12 SystemC/gem5 co-simulation: Gem5SimControl, Gem5MasterTransactor, and
  13 Gem5SlaveTransactor. 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
  17 bridge. SCMasterPort implements gem5's ExternalMaster::Port interface and forms
  18 the gem5 end of the bridge. Gem5MasterTransactor is a SystemC module that
  19 provides a target socket and represents the TLM side of the bridge. All TLM
  20 requests send to this target socket, are translated to gem5 requests and
  21 forwarded to the gem5 world through the SCMasterPort. Then the gem5 world
  22 handles the request and eventually issues a response. When the response arrives
  23 at the SCMasterPort it gets translated back into a TLM response and forwarded
  24 to the TLM world through target socket of the Gem5MasterTransactor.
  25 SCMasterPort and Gem5MasterTransactor are bound to each other by configuring
  26 them for the same port name.
  27
  28 **SCSlavePort** and **Gem5SlaveTransactor** together form a gem5-to-TLM bridge.
  29 Gem5SlaveTransactor is a SystemC module that provides a initiator socket and
  30 represents the TLM end of the bridge. SCSlavePort implements gem5's
  31 ExternalSlave::Port interface and forms the gem5 side of the bridge. All gem5
  32 requests sent to the SCSlavePort, are translated to TLM requests and forwarded
  33 to the TLM world through the initiator socket of the Gem5SlaveTransactor. Then
  34 the TLM world handles the request and eventually issues a response. When the
  35 response arrives at the Gem5SlaveTransactor it gets translated back into a
  36 gem5 response and forwarded to the gem5 world through the SCSlavePort. SCSLavePort
  37 and Gem5SlaveTransactor are bound to each other by configuring them for the
  38 same port name.
  39
  40 **Gem5SimControl** is the central SystemC module that represents the complete
  41 gem5 world. It is responsible for instantiating all gem5 objects according to a
  42 given configuration file, for configuring the simulation and for maintaining
  43 the gem5 event queue. It also keeps track of all SCMasterPort and SCSlavePort
  44 and responsible for connecting all Gem5MasterTransactor and Gem5SlaveTransactor
  45 modules to their gem5 counterparts. This module must be instantiated exactly
  46 once in order to run a gem5 simulation from within an SystemC environment.
  47
  48
  49 II. 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
  76 Other 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
  84 III. Build
  85 ==========
  86
  87 First build a normal gem5 (cxx-config not needed, Python needed).
  88 Second build gem5 as a library with cxx-config support and (optionally)
  89 without 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
  97 Note: For MAC / OSX this command should be used:
  98 > scons --with-cxx-config --without-python --without-tcmalloc \
  99 >       build/ARM/libgem5_opt.dylib
 100
 101 Set a proper LD_LIBRARY_PATH e.g. for bash:
 102 > export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:/path/to/gem5/build/ARM/"
 103
 104 or for MAC / OSX:
 105 > export DYLD_LIBRARY_PATH="$DYLD_LIBRARY_PATH:/path/to/gem5/build/ARM/"
 106
 107 The build system finds your SystemC installation using pkg-config. Make sure
 108 that pkg-config is installed and your systemc.pc is within your
 109 PKG_CONFIG_PATH. You can add SystemC to the PKG_CONFIG_PATH using the following
 110 command:
 111 > export PKG_CONFIG_PATH="/path/to/systemc/lib-<arch>/pkgconfig/:$PKG_CONFIG_PATH"
 112
 113 To build one of the examples:
 114
 115 > cd examples/{master,slave}_port
 116 > scons
 117 > cd ../../
 118
 119
 120 IV. Simple Examples
 121 ===================
 122
 123 > cd examples/{master,slave}_port
 124
 125 In order to run our example simulation, we first need to create a config.ini
 126 that represents the gem5 configuration. We do so by starting gem5 with the
 127 desired python configuration script.
 128
 129 > ../../../../build/ARM/gem5.opt ./tlm.py
 130
 131 The message "fatal: Can't find port handler type 'tlm_{master,slave}'" is okay.
 132 The configuration will be stored in the m5out/ directory
 133
 134 The build step creates a binary gem5.opt.sc in the example directory.  It can
 135 now be used to load in the generated configuration file from the previous
 136 normal gem5 run.
 137
 138 Try:
 139
 140 > ./gem5.opt.sc m5out/config.ini -e 1000000
 141
 142 It should run a simulation for 1us.
 143
 144 To see more information what happens inside the TLM modules use the -v flag:
 145
 146 > ./gem5.opt.sc m5out/config.ini -e 1000000 -v
 147
 148 To see more information about the port coupling use:
 149
 150 > ./gem5.opt.sc m5out/config.ini -e 1000000 -d ExternalPort
 151
 152
 153 V. Full System Setup
 154 =====================
 155
 156 Apart from the simple examples, there is a full system example that uses
 157 the gem5-to-TLM bridge.
 158
 159 >cd examples/slave_port
 160
 161 Build gem5 as described in Section III. Then, make a config file for the
 162 C++-configured gem5 using normal gem5
 163
 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                        \
 170   --disk-image=linux-aarch32-ael.img
 171
 172 The message "fatal: Can't find port handler type 'tlm_slave'" is okay.
 173 The configuration will be stored in the m5out/ directory
 174
 175 The binary 'gem5.opt.sc' can now be used to load in the generated config
 176 file from the previous normal gem5 run.
 177
 178 Try:
 179
 180 > ./gem5.opt.sc m5out/config.ini -o 2147483648
 181
 182 The parameter -o specifies the begining of the memory region (0x80000000).
 183 The system should boot now.
 184
 185 For convenience a run_gem5.sh file holds all those commands
 186
 187
 188 VI. Elastic Trace Setup
 189 ========================
 190
 191 Elastic traces can also be replayed into the SystemC world.
 192 For 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
 202 Similar IV. the simulation can be set up with this command:
 203
 204 > ../../../../build/ARM/gem5.opt ./tlm_elastic.py
 205
 206 Then:
 207
 208 > ./gem5.opt.sc m5out/config.ini
 209
 210
 211 VII. 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