util/tlm/README

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 sent 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
gem5 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:

    sc_logger.{cc,hh},
    sc_module.{cc,hh},
    sc_gem5_control.{cc,hh},
    stats.{cc,hh}


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)
without python.

> cd ../..
> scons build/ARM/gem5.opt
> 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 --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/"

or for MAC / OSX:
> export DYLD_LIBRARY_PATH="$DYLD_LIBRARY_PATH:/path/to/gem5/build/ARM/"

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"

To build one of the examples:

> cd examples/{master,slave}_port
> scons
> cd ../../


IV. Simple Examples
===================

> cd examples/{master,slave}_port

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.

> ../../../../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 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:

> ./gem5.opt.sc m5out/config.ini -e 1000000

It should run a simulation for 1us.

To see more information what happens inside the TLM modules use the -v flag:

> ./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


V. Full System Setup
=====================

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=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_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
file from the previous normal gem5 run.

Try:

> ./gem5.opt.sc m5out/config.ini -o 2147483648

The parameter -o specifies the begining of the memory region (0x80000000).
The system should boot now.

For convenience a run_gem5.sh file holds all those commands


VI. Elastic Trace Setup
========================

Elastic traces can also be replayed into the SystemC world.
For more information on elastic traces please refer to:

 - http://www.gem5.org/TraceCPU

 - Exploring System Performance using Elastic Traces:
   Fast, Accurate and Portable
   R. Jagtap, S. Diestelhorst, A. Hansson, M. Jung, N. Wehn.
   IEEE International Conference on Embedded Computer Systems Architectures
   Modeling and Simulation (SAMOS), July, 2016, Samos Island, Greece.

Similar IV. the simulation can be set up with this command:

> ../../../../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