misc: Clean up and complete the gem5<->SystemC-TLM bridge [6/10]

The current TLM bridge only provides a Slave Port that allows the gem5
world to send request to the SystemC world. This patch series refractors
and cleans up the existing code, and adds a Master Port that allows the
SystemC world to send requests to the gem5 world.

This patch:
 * Update the README

1 files changed, 130 insertions, 48 deletions

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.
-
-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
+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).
+
+
+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-<arch>/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