From 332c0d925c73aafde8efb6e32e614af89e2c215f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89der=20F=2E=20Zulian?= Date: Thu, 30 Aug 2018 13:31:49 +0200 Subject: [PATCH] doc improved --- README.md | 173 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 90 insertions(+), 83 deletions(-) diff --git a/README.md b/README.md index a2f1a73d..e2d5eca6 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ consumption, temperature behaviour and retention time errors. Open a terminal window, go to your home directory, create a directory for your projects and change to it. -``` bash +```bash $ cd $ mkdir projects $ cd projects @@ -19,7 +19,7 @@ $ cd projects Configure git on your machine. Some basic configurations follow. Replace **rhrkuser** with your own RHRK user when configuring your email. -``` bash +```bash $ git config --global user.name "FirstName OtherNames LastName" $ git config --global user.email rhrkuser@rhrk.uni-kl.de $ git config --global credential.helper 'cache --timeout=3600' @@ -33,7 +33,7 @@ Now clone **your fork** of the official repository into a local folder on your computer. Replace the occurrences of the word **user** with your own RHRK user name. **Note that it appears twice in the line below**. -``` bash +```bash $ git clone --recursive https://user@git.rhrk.uni-kl.de/user/dram.vp.system.git ``` @@ -53,14 +53,14 @@ repository. After cloning go to the project directory. -``` bash +```bash $ cd dram.vp.system ``` When working with a fork, the official repository must be added as a remote for your fork. Replace the word **user** with your own RHRK user name. -``` bash +```bash $ git remote add upstream https://user@git.rhrk.uni-kl.de/EIT-Wehn/dram.vp.system.git ``` @@ -71,7 +71,7 @@ the evolution of the official repository and avoid a huge divergence. To get the latest changes from the official repository merged into your fork you can use the commands that follow: -``` bash +```bash $ git fetch upstream $ git checkout master $ git merge upstream/master @@ -99,7 +99,7 @@ $ bash install_deb.sh You can use [utils/getsysc.sh](./utils/getsysc.sh) to download and install SystemC 2.3.1 and TLM 2.0. First read and understand the script then execute it. -``` bash +```bash $ bash getsysc.sh ``` @@ -158,7 +158,7 @@ $ ./make_pretty.sh ### Buiding with QTCreator Execute the *QTCreator*. -``` bash +```bash $ qtcreator & ``` @@ -174,7 +174,7 @@ To speedup the building process one can use the additional **make** option make as the number of jobs that can run simultaneously to improve the building time. -``` bash +```bash $ cat /proc/cpuinfo | grep processor | wc -l ``` @@ -192,7 +192,7 @@ version** configuration shown in the image below. In case you prefer a command line interface to the QTCreator GUI you can also use **qmake** to generate a Makefile and then compile the project. -``` bash +```bash $ mkdir build $ cd build $ qmake ../DRAMSys/DRAMSys.pro @@ -204,14 +204,14 @@ The compilation generates executable binary files **DRAMSys** and From the build directory use the commands below to execute DRAMSys. -``` bash +```bash $ cd simulator $ ./DRAMSys ``` From the build directory use the commands below to execute the traceAnalyzer. -``` bash +```bash $ cd traceAnalyzer $ export QT_QPA_PLATFORMTHEME=qgnomeplatform $ ./traceAnalyzer @@ -222,7 +222,7 @@ $ ./traceAnalyzer - Install SystemC manually in /opt: -``` bash +```bash $ ./configure --prefix=/opt/systemc $ make $ sudo make install @@ -230,7 +230,7 @@ $ sudo make install Or you can install via homebrew: -``` bash +```bash $ brew install systemc ``` @@ -246,7 +246,7 @@ ln -s lib/ lib-macosx64 - Install the required python 3 over homebrew: -``` bash +```bash $ brew install python3 ``` @@ -266,7 +266,7 @@ or you can install manually using official package provided in [link](https://ww **Note:** You have later setup PATH for Qt5 and its tool if you install QtCreator manually, e.g: -``` bash +```bash # Setting PATH for Qt5 and its tools PATH="/Users//Qt5.7.0/5.7/clang_64/bin:${PATH}" export PATH @@ -274,13 +274,13 @@ export PATH - Install the QWT manually to /opt/qwt, then do: -``` bash +```bash $ cd /Library/Frameworks $ sudo ln -s /opt/qwt-6.1.2/lib/qwt.framework/ . ``` - Export correct Environment Variables in your terminal's profile, e.g: -``` bash +```bash # Setting for DRAMSys # SystemC via official source export SYSTEMC_HOME=/opt/systemc @@ -311,7 +311,7 @@ has to be changed like [this](https://trac.macports.org/attachment/ticket/44288/ - Type following command inside your dram.vp.system folder: -``` bash +```bash $ mkdir build $ qmake ../DRAMSys/DRAMSys.pro $ make -j @@ -342,7 +342,7 @@ passed through the command line a default configuration file will be loaded. The XML code below shows a typic configuration: -``` xml +```xml @@ -570,7 +570,7 @@ Below, the sub-configurations are listed and explained. [am_ddr3_8x1Gbx8_dimm_p1KB_brc.xml](DRAMSys/library/resources/configs/amconfigs/am_ddr3_8x1Gbx8_dimm_p1KB_brc.xml) - ``` xml + ```xml @@ -615,7 +615,7 @@ Below, the sub-configurations are listed and explained. ![Address Mapping Sample 1](DRAMSys/docs/images/am_wideio_rbc.png) - ``` xml + ```xml @@ -646,7 +646,7 @@ Below, the sub-configurations are listed and explained. - "bank_bits": Number of the addres bits which are connected to a bank bit - "row_bits": Number of the addres bits which are connected to a row bit -``` json +```json { "Config": { "numberOfBankBits": 3, @@ -699,7 +699,7 @@ Below, the sub-configurations are listed and explained. An example follows. - ``` xml + ```xml @@ -951,7 +951,7 @@ knowhow of memory technologies. Resources of the simulator are available inside of the **resources** directory and its sub-directories. -``` bash +```bash $ cd DRAMSys/library/resources ``` @@ -978,14 +978,14 @@ the execution time: dram.vp.system\_YYYY\_MM\_DD-HH.MM.SS. Example on how to run the script: -``` bash +```bash $ cd DRAMSys/library/resources/scripts/DRAMSylva $ bash DRAMSylva.sh ``` To see the generated plots and CSV files: -``` bash +```bash $ nautilus dram.vp.system_YYYY_MM_DD-HH.MM.SS/build/simulator ``` @@ -999,7 +999,7 @@ data used to generate the plots. The CSV files are: Use the command below to find all generated CSV files: -``` bash +```bash $ ls -l dram.vp.system_YYYY_MM_DD-HH.MM.SS/build/simulator/*.csv ``` @@ -1009,7 +1009,7 @@ manipulation. Set the variable **create_comparison_plots** to **yes** in order to get plots for quick comparison from the CSV files generated. -``` bash +```bash create_comparison_plots="yes" ``` @@ -1022,7 +1022,7 @@ analyzer tool). **Note**: enabling this option may incur extra time for database manipulation and plot generation. Depending on the size and amount of database files it may take long to finish. -``` bash +```bash create_analyzer_plots="yes" ``` @@ -1032,7 +1032,7 @@ specifc configs. You can change what is going to be simulated by the script by editing it. There is a list of main configuration files on the top of the script: -``` bash +```bash sim_files=" ddr3-example.xml ddr3-single-device.xml @@ -1051,7 +1051,7 @@ trace specified in the simulation file. Files are expected to be available (already commited and pushed to be available after cloning) in the [traces folder](DRAMSys/library/resources/traces). -``` bash +```bash use_trace_list="yes" ``` @@ -1074,7 +1074,7 @@ expected to be available (already commited and pushed to be available after cloning) in the [trace folder](DRAMSys/library/resources/traces). DRAMSylva will uncompress the tarball extracting the traces before using them. -``` bash +```bash tgz_traces="yes" tgz_file="rgr_traces_flauer_ddr4_8b.tar.gz" ``` @@ -1085,7 +1085,7 @@ simulation files are the ones specified by sim_files. Files are expected to be available (already commited and pushed to be available after cloning) in [configs_json](DRAMSys/library/resources/scripts/DRAMSylva/configs_json). -``` bash +```bash use_json_cfg="yes" ``` @@ -1102,7 +1102,7 @@ Several examples of JSON configuration files are provided in + Add your JSON files to **json_cfg_list** in DRAMSylva.sh. -``` bash +```bash json_cfg_list=" ref.json ref_bw.json @@ -1124,7 +1124,7 @@ generating input traces for simple tests is provided. Example on how to run the script: -``` bash +```bash $ cd DRAMSys/library/resources/scripts $ ./trace_gen.py > trace.stl ``` @@ -1240,20 +1240,20 @@ running before starting. For more information about 3D-ICE visit the [official w [Download](http://esl.epfl.ch/3d-ice/download.html) the lastest version. Make sure you got version 2.2.6 or greater: -``` bash +```bash $ wget http://esl.epfl.ch/files/content/sites/esl/files/3dice/releases/3d-ice-latest.zip $ tar -xvzf 3d-ice-latest.zip ``` Install [SuperLU](http://crd-legacy.lbl.gov/~xiaoye/SuperLU/superlu_5.2.1.tar.gz) dependencies: -``` bash +```bash $ sudo apt-get install build-essential git bison flex libblas-dev ``` Download and install SuperLU: -``` bash +```bash $ wget http://crd.lbl.gov/~xiaoye/SuperLU/superlu_4.3.tar.gz $ tar xvfz superlu_4.3.tar.gz $ cd SuperLU_4.3/ @@ -1262,19 +1262,19 @@ $ cp MAKE_INC/make.linux make.inc Make sure the SuperLUroot variable in ./make.inc is properly set (in my case $(HOME)/repos/). -``` bash +```bash SuperLUroot = $(HOME)/repos/SuperLU_4.3 ``` Compile the library: -``` bash +```bash $ make superlulib ``` Download and install bison-2.4.1: -``` bash +```bash $ wget http://ftp.gnu.org/gnu/bison/bison-2.4.1.tar.gz $ tar xvzf bison-2.4.1.tar.gz $ cd bison-2.4.1 @@ -1285,33 +1285,33 @@ $ sudo make install Go to the 3d-ice directory: -``` bash +```bash $ cd 3d-ice-2.2.6 ``` Open the file makefile.def and set some variables. Set the correct path to the SuperLU library you just compiled (in my case $(HOME)/repos/): -``` bash +```bash SLU_MAIN = $(HOME)/repos/SuperLU_$(SLU_VERSION) ``` Set the YACC variable to bison-2.4.1: -``` bash +```bash YACC = bison-2.4.1 ``` Set the systemC architecture and main folder variables: -``` bash +```bash SYSTEMC_ARCH = [linux,linux64] SYSTEMC_MAIN = $(HOME)/repos/systemc-$(SYSTEMC_VERSION) ``` Compile 3D-ICE with SystemC/TLM2.0 support: -``` bash +```bash $ make clean $ make SYSTEMC_WRAPPER=y ``` @@ -1332,20 +1332,20 @@ automatic generated Makefiles. One way to ensure this is by running the command below inside your DRAMSys repository, but keep in mind that **untracked files and directories will be removed** from the repository. -``` bash +```bash $ git clean -fdx ``` This feature can be enabled via an environment variable. -``` bash +```bash $ export THERMALSIM=true $ qtcreator & ``` or -``` bash +```bash $ mkdir build $ cd build $ export THERMALSIM=true @@ -1357,7 +1357,7 @@ Before starting DRAMSys it is necessary to run the 3D-ICE server passing to it two arguments: a suitable configuration file and an Internet socket port number. And then wait until the server is ready to receive requests. -``` bash +```bash $ 3D-ICE-Server Preparing stk data ... done ! Preparing thermal data ... done ! @@ -1373,7 +1373,7 @@ simulation server. The DRAMSys' main configuration file is presented below. -``` xml +```xml @@ -1401,7 +1401,7 @@ The DRAMSys' main configuration file is presented below. Enable the error model in fr_fcfs.xml. -``` xml +```xml @@ -1420,14 +1420,14 @@ Enable the error model in fr_fcfs.xml. Generate the input trace file for DRAMSys. -``` bash +```bash $ cd DRAMSys/tests/error/ $ ./generateErrorTest.pl > test_error.stl ``` Start the 3D-ICE server providing the stack file and the port number. -``` bash +```bash $ cd DRAMSys/library/resources/configs/thermalsim $ 3D-ICE-Server stack.stk 11880 ``` @@ -1435,7 +1435,7 @@ $ 3D-ICE-Server stack.stk 11880 In another terminal or terminal tab start DRAMSys. Here the program's output is redirected to a file. -``` bash +```bash $ cd build/simulator/ $ ./DRAMSys > output ``` @@ -1450,17 +1450,17 @@ read the documentation in the gem5 repository *util/tlm/README* and [12]. The main steps for building gem5 and libgem5 follow: -``` bash +```bash scons build/ARM/gem5.opt ``` -``` bash +```bash scons --with-cxx-config --without-python --without-tcmalloc build/ARM/libgem5_opt.so ``` For MacOS: -``` bash +```bash scons --with-cxx-config --without-python --without-tcmalloc build/ARM/libgem5_opt.dylib ``` @@ -1519,7 +1519,7 @@ As mentioned before 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. -``` bash +```bash cd gem5/utils/tlm/ ../../build/ARM/gem5.opt conf/tlm_slave.py ``` @@ -1539,7 +1539,7 @@ in a conf directory of this building directory. Then the simulation can be started with: -``` bash +```bash ./DRAMSys_gem5 ../../DRAMSys/library/resources/simulations/ddr3-example.xml config.ini ``` @@ -1553,42 +1553,49 @@ All essential files for some functional examples are provided. Execute a hello world application: -``` bash -./DRAMSys_gem5 /home/eder/repos/dram.vp.system/DRAMSys/library/resources/simulations/ddr3-gem5-se.xml ../../DRAMSys/gem5/configs/hello.ini +```bash +./DRAMSys_gem5 ../../DRAMSys/library/resources/simulations/ddr3-gem5-se.xml ../../DRAMSys/gem5/configs/hello.ini ``` A **Hello world!** message should be printed to the standard output. Execute a bubble sort application: -``` bash -./DRAMSys_gem5 /home/eder/repos/dram.vp.system/DRAMSys/library/resources/simulations/ddr3-gem5-se.xml ../../DRAMSys/gem5/configs/bubblesort.ini +```bash +./DRAMSys_gem5 ../../DRAMSys/library/resources/simulations/ddr3-gem5-se.xml ../../DRAMSys/gem5/configs/bubblesort.ini ``` Wait some minutes for the bubble sort application to finish. -The hello application binary was copied from gem5 repository. The bubble sort application was obtained with [gem5.TnT](https://github.com/tukl-msd/gem5.TnT). +The hello application binary was copied from gem5 repository. + +The bubble sort application was obtained with [gem5.TnT](https://github.com/tukl-msd/gem5.TnT). Command template for generating **.ini** configuration files follows: -``` bash -build/ARM/gem5.opt configs/example/se.py -c --mem-size=512MB --mem-channels=1 --caches --l2cache --mem-type=SimpleMemory --cpu-type=TimingSimpleCPU --num-cpu=1 --tlm-memory=transactor +```bash +build/ARM/gem5.opt configs/example/se.py \ + -c --mem-size=512MB --mem-channels=1 \ + --caches --l2cache --mem-type=SimpleMemory \ + --cpu-type=TimingSimpleCPU --num-cpu=1 \ + --tlm-memory=transactor ``` An overview of the architcture being simulated is presented below: -![arch](DRAMSys/docs/images/gem5_se_mode_arch.png) +![arch](DRAMSys/docs/images/gem5_se_mode_arch.svg) Note: this is a gem5 generated file, therefore DRAMSys is omitted. DRAMSys is direct connected as external tlm slave. Note: workaround in se.py required: -``` - ... - if options.tlm_memory: - system.physmem = SimpleMemory() - MemConfig.config_mem(options, system) - ... + +```python +... +if options.tlm_memory: + system.physmem = SimpleMemory() +MemConfig.config_mem(options, system) +... ``` ### Boot Linux with gem5 and DRAMSys @@ -1597,7 +1604,7 @@ The procedure is very similar to the traffic generator example above. First we have to generate the config.ini file by starting gem5 with the following configuration: -``` bash +```bash build/ARM/gem5.opt configs/example/fs.py \ --tlm-memory=transactor --cpu-type=TimingSimpleCPU --num-cpu=1 \ --mem-type=SimpleMemory --mem-size=512MB --mem-channels=1 --caches \ @@ -1645,7 +1652,7 @@ The simconfig should be changed in order to support storage and address offsets: Then start DRAMSys_gem5 with the following command: -``` bash +```bash ./DRAMSys_gem5 ../../DRAMSys/library/resources/simulations/ddr3-example.xml config.ini ``` @@ -1655,19 +1662,19 @@ All essential files for a functional example are provided. Unzip the disk image: -``` bash +```bash tar -xaf DRAMSys/gem5/boot_linux/linux-aarch32-ael.img.tar.gz -C DRAMSys/gem5/boot_linux/ ``` Execute the example: -``` bash +```bash ./DRAMSys_gem5 ../../DRAMSys/library/resources/simulations/ddr3-boot-linux.xml ../../DRAMSys/gem5/configs/boot_linux.ini ``` Open a new terminal and connect to gem5: -``` bash +```bash telnet localhost 3456 ``` @@ -1681,7 +1688,7 @@ Some predefined configs are stored [here](DRAMSys/gem5/configs) and the related This is an example for running an elastic trace: -``` bash +```bash ./DRAMSys_gem5 ../../DRAMSys/library/resources/simulations/ddr3-example.xml ../../DRAMSys/gem5/configs/singleElasticTraceReplay.ini ``` @@ -1689,7 +1696,7 @@ Note that the address offset is usually zero for elastic traces. If two elastic traces should be used the main.cpp must be modified: -``` c++ +```c++ //#define CHOICE1 #define CHOICE2 //#define CHOICE3