diff --git a/util/tlm/README b/util/tlm/README index cf2a4acfd..7eeafa71f 100644 --- a/util/tlm/README +++ b/util/tlm/README @@ -1,17 +1,77 @@ -This directory contains a demo of a coupling between gem5 and SystemC-TLM. -It is based on the gem5-systemc implementation in utils/systemc. -First a simple example with gem5's traffic generator is shown, later an full -system example. +This directory contains a demo of a coupling between gem5 and SystemC-TLM. It +is based on the gem5-systemc implementation in utils/systemc. This Readme gives +an overall overview (I), describes the source files in this directory (II), +explains the build steps (III), shows how to run example simulations (IV-VI) +and lists known issues (VII). -Files: - main.cc -- demonstration top level - sc_port.{cc,hh} -- transactor that translates beween gem5 and tlm - sc_mm.{cc,hh} -- implementation of a tlm memory manager - sc_ext.{cc,hh} -- a TLM extension that carries the gem5 packet - sc_target.{cc,hh} -- an example TLM LT/AT memory module - tlm.py -- simple gem5 configuration - tgen.cfg -- configuration file for the traceplayer +I. Overview +=========== + +The sources in this directory provide three SystemC modules that manage the +SystemC/gem5 co-simulation: Gem5SimControl, Gem5MasterTransactor, and +Gem5SlaveTransactor. They also implement gem5's ExternalMaster::Port interface +(SCMasterPort) and ExternalSlave::Port interface (SCSlavePort). + +**SCMasterPort** and **Gem5MasterTransactor** together form a TLM-to-gem5 +bridge. SCMasterPort implements gem5's ExternalMaster::Port interface and forms +the gem5 end of the bridge. Gem5MasterTransactor is a SystemC module that +provides a target socket and represents the TLM side of the bridge. All TLM +requests send to this target socket, are translated to gem5 requests and +forwarded to the gem5 world through the SCMasterPort. Then the gem5 world +handles the request and eventually issues a response. When the response arrives +at the SCMasterPort it gets translated back into a TLM response and forwarded +to the TLM world through target socket of the Gem5MasterTransactor. +SCMasterPort and Gem5MasterTransactor are bound to each other by configuring +them for the same port name. + +**SCSlavePort** and **Gem5SlaveTransactor** together form a gem5-to-TLM bridge. +Gem5SlaveTransactor is a SystemC module that provides a initiator socket and +represents the TLM end of the bridge. SCSlavePort implements gem5's +ExternalSlave::Port interface and forms the gem5 side of the bridge. All gem5 +requests send to the SCSlavePort, are translated to TLM requests and forwarded +to the TLM world through the initiator socket of the Gem5SlaveTransactor. Then +the TLM world handles the request and eventually issues a response. When the +response arrives at the Gem5SlaveTransactor it gets translated back into a TLM +response and forwarded to the gem5 world through the SCSlavePort. SCSLavePort +and Gem5SlaveTransactor are bound to each other by configuring them for the +same port name. + +**Gem5SimControl** is the central SystemC module that represents the complete +gem5 world. It is responsible for instantiating all gem5 objects according to a +given configuration file, for configuring the simulation and for maintaining +the gem5 event queue. It also keeps track of all SCMasterPort and SCSlavePort +and responsible for connecting all Gem5MasterTransactor and Gem5SlaveTransactor +modules to their gem5 counterparts. This module must be instantiated exactly +once in order to run a gem5 simulation from within an SystemC environment. + + +II. Files +========= + + sc_slave_port.{cc,hh} -- Implements SCSlavePort + sc_master_port.{cc,hh} -- Implements SCMasterPort + sc_mm.{cc,hh} -- Implementation of a TLM memory manager + sc_ext.{cc,hh} -- TLM extension that carries a gem5 packet + sc_peq.{cc,hh} -- TLM PEQ for scheduling gem5 events + sim_control.{cc,hh} -- Implements Gem5SimControl + slave_transactor.{cc,hh} -- Implements Gem5SlaveTransactor + master_transactor.{cc,hh} -- Implements Gem5MasterTransactor + + example/common/cli_parser.{cc,hh} -- Simple cli argument parser + example/common/report_hanlder.{cc,hh} -- Custom SystemC report handler + + example/slave_port/main.cc -- demonstration of the slave port + example/slave_port/sc_target.{cc,hh} -- an example TLM LT/AT memory module + example/slave_port/tlm.py -- simple gem5 configuration + example/slave_port/tlm_elastic.py -- gem5 configuration with an elastic + trace replayer + example/slave_port/tgen.cfg -- elastic traceplayer configuration + + example/master_port/main.cc -- demonstration of the master port + example/master_port/traffic_generator.{cc/hh} + -- an example traffic generator module + example/master_port/tlm.py -- simple gem5 configuration Other Files will be used from utils/systemc example: @@ -21,10 +81,8 @@ Other Files will be used from utils/systemc example: stats.{cc,hh} -I. Traffic Generator Setup -========================== - -To build: +III. Build +========== First build a normal gem5 (cxx-config not needed, Python needed). Second build gem5 as a library with cxx-config support and (optionally) @@ -32,11 +90,13 @@ without python. > cd ../.. > scons build/ARM/gem5.opt -> scons --with-cxx-config --without-python build/ARM/libgem5_opt.so +> scons --with-cxx-config --without-python --without-tcmalloc \ +> build/ARM/libgem5_opt.so > cd util/tlm Note: For MAC / OSX this command should be used: -> scons --with-cxx-config --without-python build/ARM/libgem5_opt.dylib +> scons --with-cxx-config --without-python --without-tcmalloc \ +> build/ARM/libgem5_opt.dylib Set a proper LD_LIBRARY_PATH e.g. for bash: > export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:/path/to/gem5/build/ARM/" @@ -44,29 +104,35 @@ Set a proper LD_LIBRARY_PATH e.g. for bash: or for MAC / OSX: > export DYLD_LIBRARY_PATH="$DYLD_LIBRARY_PATH:/path/to/gem5/build/ARM/" -Then edit the Makefile to set the paths for SystemC: +The build system finds your SystemC installation using pkg-config. Make sure +that pkg-config is installed and your systemc.pc is within your +PKG_CONFIG_PATH. You can add SystemC to the PKG_CONFIG_PATH using the following +command: +> export PKG_CONFIG_PATH="/path/to/systemc/lib-/pkgconfig/:$PKG_CONFIG_PATH" - Linux: - SYSTEMC_INC = /opt/systemc/include - SYSTEMC_LIB = /opt/systemc/lib-linux64 +To build one of the examples: - MAC / OSX: - SYSTEMC_INC = /opt/systemc/include - SYSTEMC_LIB = /opt/systemc/lib-macosx64 +> cd examples/{master,slave}_port +> scons +> cd ../../ -Then run make: -> make +IV. Simple Examples +=================== -Make a config file for the C++-configured gem5 using normal gem5 +> cd examples/{master,slave}_port -> ../../build/ARM/gem5.opt ./tlm.py +In order to run our example simulation, we first need to create a config.ini +that represents the gem5 configuration. We do so by starting gem5 with the +desired python configuration script. -The message "fatal: Can't find port handler type 'tlm'" is okay. +> ../../../../build/ARM/gem5.opt ./tlm.py + +The message "fatal: Can't find port handler type 'tlm_{master,slave}'" is okay. The configuration will be stored in the m5out/ directory -The binary 'gem5.opt.sc', that has been created in the make step, -can now be used to load in the generated config file from the previous +The build step creates a binary gem5.opt.sc in the example directory. It can +now be used to load in the generated configuration file from the previous normal gem5 run. Try: @@ -75,28 +141,35 @@ Try: It should run a simulation for 1us. -To see more information what happens inside the TLM module use the -D flag: +To see more information what happens inside the TLM modules use the -v flag: -> ./gem5.opt.sc m5out/config.ini -e 1000000 -D +> ./gem5.opt.sc m5out/config.ini -e 1000000 -v To see more information about the port coupling use: > ./gem5.opt.sc m5out/config.ini -e 1000000 -d ExternalPort -II. Full System Setup + +V. Full System Setup ===================== -Build gem5 as discribed in Section I. Then, make a config file for the +Apart from the simple examples, there is a full system example that uses +the gem5-to-TLM bridge. + +>cd examples/slave_port + +Build gem5 as described in Section III. Then, make a config file for the C++-configured gem5 using normal gem5 -> ../../build/ARM/gem5.opt ../../configs/example/fs.py --tlm-memory=memory \ - --cpu-type=timing --num-cpu=1 --mem-type=SimpleMemory --mem-size=512MB \ - --mem-channels=1 --caches --l2cache --machine-type=VExpress_EMM \ - --dtb-filename=vexpress.aarch32.ll_20131205.0-gem5.1cpu.dtb \ - --kernel=vmlinux.aarch32.ll_20131205.0-gem5 \ +> ../../../../build/ARM/gem5.opt ../../../../configs/example/fs.py \ + --tlm-memory=transactor --cpu-type=timing --num-cpu=1 \ + --mem-type=SimpleMemory --mem-size=512MB --mem-channels=1 --caches \ + --l2cache --machine-type=VExpress_EMM \ + --dtb-filename=vexpress.aarch32.ll_20131205.0-gem5.1cpu.dtb \ + --kernel=vmlinux.aarch32.ll_20131205.0-gem5 \ --disk-image=linux-aarch32-ael.img -The message "fatal: Can't find port handler type 'tlm'" is okay. +The message "fatal: Can't find port handler type 'tlm_slave'" is okay. The configuration will be stored in the m5out/ directory The binary 'gem5.opt.sc' can now be used to load in the generated config @@ -109,10 +182,10 @@ Try: The parameter -o specifies the begining of the memory region (0x80000000). The system should boot now. -For conveniance a run_gem5.sh file holds all those commands +For convenience a run_gem5.sh file holds all those commands -III. Elastic Trace Setup +VI. Elastic Trace Setup ======================== Elastic traces can also be replayed into the SystemC world. @@ -126,10 +199,19 @@ For more information on elastic traces please refer to: IEEE International Conference on Embedded Computer Systems Architectures Modeling and Simulation (SAMOS), July, 2016, Samos Island, Greece. -Similar to I. the simulation can be set up with this command: +Similar IV. the simulation can be set up with this command: -> ../../build/ARM/gem5.opt ./tlm_elastic.py +> ../../../../build/ARM/gem5.opt ./tlm_elastic.py Then: > ./gem5.opt.sc m5out/config.ini + + +VII. Knwon issues +================= + +* For some toolchains, compiling libgem5 with tcmalloc leads to errors + ('tcmalloc Attempt to free invalid pointer xxx') when linking libgem5 into a + SystemC application. +* When SystemC was build with --enable-pthreads, SystemC applications linked