README revision 11791 
1This directory contains a demo of a coupling between gem5 and SystemC-TLM.
2It is based on the gem5-systemc implementation in utils/systemc.
3First a simple example with gem5's traffic generator is shown, later an full
4system example.
5
6Files:
7
8    main.cc                -- demonstration top level
9    sc_port.{cc,hh}        -- transactor that translates beween gem5 and tlm
10    sc_mm.{cc,hh}          -- implementation of a tlm memory manager
11    sc_ext.{cc,hh}         -- a TLM extension that carries the gem5 packet
12    sc_target.{cc,hh}      -- an example TLM LT/AT memory module
13    tlm.py                 -- simple gem5 configuration
14    tgen.cfg               -- configuration file for the traceplayer
15
16Other Files will be used from utils/systemc example:
17
18    sc_logger.{cc,hh},
19    sc_module.{cc,hh},
20    sc_gem5_control.{cc,hh},
21    stats.{cc,hh}
22
23
24I. Traffic Generator Setup
25==========================
26
27To build:
28
29First build a normal gem5 (cxx-config not needed, Python needed).
30Second build gem5 as a library with cxx-config support and (optionally)
31without python.
32
33> cd ../..
34> scons build/ARM/gem5.opt
35> scons --with-cxx-config --without-python build/ARM/libgem5_opt.so
36> cd util/tlm
37
38Note: For MAC / OSX this command should be used:
39> scons --with-cxx-config --without-python build/ARM/libgem5_opt.dylib
40
41Set a proper LD_LIBRARY_PATH e.g. for bash:
42> export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:/path/to/gem5/build/ARM/"
43
44or for MAC / OSX:
45> export DYLD_LIBRARY_PATH="$DYLD_LIBRARY_PATH:/path/to/gem5/build/ARM/"
46
47Then edit the Makefile to set the paths for SystemC:
48
49    Linux:
50    SYSTEMC_INC = /opt/systemc/include
51    SYSTEMC_LIB = /opt/systemc/lib-linux64
52
53    MAC / OSX:
54    SYSTEMC_INC = /opt/systemc/include
55    SYSTEMC_LIB = /opt/systemc/lib-macosx64
56
57Then run make:
58
59> make
60
61Make a config file for the C++-configured gem5 using normal gem5
62
63> ../../build/ARM/gem5.opt ./tlm.py
64
65The message "fatal: Can't find port handler type 'tlm'" is okay.
66The configuration will be stored in the m5out/ directory
67
68The binary 'gem5.opt.sc', that has been created in the make step,
69can now be used to load in the generated config file from the previous
70normal gem5 run.
71
72Try:
73
74> ./gem5.opt.sc m5out/config.ini -e 1000000
75
76It should run a simulation for 1us.
77
78To see more information what happens inside the TLM module use the -D flag:
79
80> ./gem5.opt.sc m5out/config.ini -e 1000000 -D
81
82To see more information about the port coupling use:
83
84> ./gem5.opt.sc m5out/config.ini -e 1000000 -d ExternalPort
85
86II. Full System Setup
87=====================
88
89Build gem5 as discribed in Section I. Then, make a config file for the
90C++-configured gem5 using normal gem5
91
92> ../../build/ARM/gem5.opt ../../configs/example/fs.py --tlm-memory=memory \
93  --cpu-type=timing --num-cpu=1 --mem-type=SimpleMemory --mem-size=512MB   \
94  --mem-channels=1  --caches --l2cache --machine-type=VExpress_EMM         \
95  --dtb-filename=vexpress.aarch32.ll_20131205.0-gem5.1cpu.dtb              \
96  --kernel=vmlinux.aarch32.ll_20131205.0-gem5                              \
97  --disk-image=linux-aarch32-ael.img
98
99The message "fatal: Can't find port handler type 'tlm'" is okay.
100The configuration will be stored in the m5out/ directory
101
102The binary 'gem5.opt.sc' can now be used to load in the generated config
103file from the previous normal gem5 run.
104
105Try:
106
107> ./gem5.opt.sc m5out/config.ini -o 2147483648
108
109The parameter -o specifies the begining of the memory region (0x80000000).
110The system should boot now.
111
112For conveniance a run_gem5.sh file holds all those commands
113
114
115III. Elastic Trace Setup
116========================
117
118Elastic traces can also be replayed into the SystemC world.
119For more information on elastic traces please refer to:
120
121 - http://www.gem5.org/TraceCPU
122
123 - Exploring System Performance using Elastic Traces:
124   Fast, Accurate and Portable
125   R. Jagtap, S. Diestelhorst, A. Hansson, M. Jung, N. Wehn.
126   IEEE International Conference on Embedded Computer Systems Architectures
127   Modeling and Simulation (SAMOS), July, 2016, Samos Island, Greece.
128
129Similar to I. the simulation can be set up with this command:
130
131> ../../build/ARM/gem5.opt ./tlm_elastic.py
132
133Then:
134
135> ./gem5.opt.sc m5out/config.ini
136