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     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
  79 Other 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
  87 III. Build
  88 ==========
  89
  90 First build a normal gem5 (cxx-config not needed, Python needed).
  91 Second build gem5 as a library with cxx-config support and (optionally)
  92 without 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
 100 Note: For MAC / OSX this command should be used:
 101 > scons --with-cxx-config --without-python --without-tcmalloc \
 102 >       build/ARM/libgem5_opt.dylib
 103
 104 To build all sources of the SystemC binding and the examples simply run scons:
 105
 106 > scons
 107
 108
 109 IV. Simple Examples
 110 ===================
 111
 112 In order to run our example simulation, we first need to create a config.ini
 113 that represents the gem5 configuration. We do so by starting gem5 with the
 114 desired python configuration script.
 115
 116 > ../../build/ARM/gem5.opt conf/tlm_{master,slave}.py
 117
 118 The message "fatal: Can't find port handler type 'tlm_{master,slave}'" is okay.
 119 The configuration will be stored in the m5out/ directory
 120
 121 The build step creates a binary 'gem5.sc' for each example in the
 122 build/examples/{master|slave}_port directories. It can now be used to load in
 123 the generated configuration file from the previous normal gem5 run.
 124
 125 Try:
 126
 127 > build/examples/{master,slave}_port/gem5.sc m5out/config.ini -e 1000000
 128
 129 It should run a simulation for 1us.
 130
 131 To 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
 136 V. Full System Setup
 137 =====================
 138
 139 Apart from the simple examples, there is a full system example that uses
 140 the gem5-to-TLM bridge.
 141
 142 Build gem5 as described in Section III. Then, make a config file for the
 143 C++-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
 153 The message "fatal: Can't find port handler type 'tlm_slave'" is okay.
 154 The configuration will be stored in the m5out/ directory
 155
 156 The binary 'build/examples/slave_port/gem5.sc' can now be used to load in the
 157 generated config file from the previous normal gem5 run.
 158
 159 Try:
 160
 161 > build/examples/slave_port/gem5.sc m5out/config.ini -o 2147483648
 162
 163 The parameter -o specifies the begining of the memory region (0x80000000).
 164 The system should boot now.
 165
 166 For convenience a run_gem5_fs.sh file holds all those commands
 167
 168
 169 VI. Elastic Trace Setup
 170 ========================
 171
 172 Elastic traces can also be replayed into the SystemC world.
 173 For 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
 183 Similar to IV. the simulation can be set up with this command:
 184
 185 > ../../build/ARM/gem5.opt ./conf/tlm_elastic_slave.py
 186
 187 Then:
 188
 189 > build/examples/slave_port/gem5.sc m5out/config.ini
 190
 191
 192 VII. 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.
 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.