From 16cbd15f4728260e5e9558ad27a82710b5162273 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89der=20Ferreira=20Zulian?= <fzeder@rhrk.uni-kl.de>
Date: Wed, 6 May 2015 10:51:07 +0200
Subject: [PATCH] Readme file updated with information about dramSys
 configuration

---
 README.md | 147 ++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 136 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 49080653..bac9ac77 100644
--- a/README.md
+++ b/README.md
@@ -5,8 +5,7 @@ Generic DRAM controller simulator and debug tools related to it.
 
 # Basic Setup
 
-In a terminal window execute the commands that follow (the '$' symbolizes the
-terminal prompt).
+In a terminal window execute the commands that follow.
 
 Go to your home directory.
 
@@ -33,7 +32,7 @@ In case of doubts about which repository you should clone ask your supervisor.
 $ git clone https://<user>@git.rhrk.uni-kl.de/<user>/dram.vp.system.git
 ```
 
-Go to the projetct directory.
+Go to the project directory.
 
 ```
 $ cd dram.vp.system
@@ -78,10 +77,130 @@ $ qmake ../dramSys/dramSys.pro
 $ make
 ```
 
- 
-# DRAMSys Resources
+### DRAMSys Configuration
 
-The simulator's configuration is done via some files. You can find such configuration files in the directory below and its sub-directories.
+The **dramSys** executable supports one argument which is a XML file that
+contains configurable aspects of the desired simulation. If no argument is
+passed through the command line a default configuration file will be loaded.
+
+The XML code below shows a typical simulation configuration:
+
+```
+<simulation>
+        <simconfig>
+                    <Debug value="1" />
+                    <DatabaseRecording value="1" />
+                    <PowerAnalysys value="1" />
+        </simconfig>
+        <memspecs>
+                <memspec src="../resources/configs/memspecs/WideIO.xml"></memspec>
+        </memspecs>
+        <addressmappings>
+                <addressmapping src="../resources/configs/amconfigs/am_wideio.xml"></addressmapping>
+        </addressmappings>
+        <memconfigs>
+           <memconfig src="../resources/configs/memconfigs/fifo.xml"/>
+        </memconfigs>
+
+<tracesetups>
+      <tracesetup id="fifo">
+       <device clkMhz="200">voco2.stl</device>
+</tracesetup>
+  </tracesetups>
+</simulation>
+```
+
+Some configuration fields reference other XML files which contain more
+specialized chunks of the configuration, e.g. memory specification and address
+mapping.
+
+The XML configuration files are parsed by the program and the configuration
+details extracted are assigned to the correspondent attributes of the internal
+configuration structure.
+
+
+#### Configuration File Sections
+
+The main configuration file is divided into self-contained sections, each of
+these sections is a set of logically related configuration aspects for the
+simulation.
+
+The list below, which is not intended to be exhaustive, present the
+configuration sections and possible configuration fields.
+
+- Simulator configuration
+  - Database recording
+  - Power analysis
+  - Debug mode
+
+- Memory specification
+  - Memory ID: JEDEC_256Mb_WIDEIO_SDR-200_128bit,
+    MICRON_4Gb_DDR4-2400_8bit_A, ...
+  - Memory type: WIDEIO_SD, DDR4, ...
+
+- Memory Architecture Specification
+  - Width
+  - Number of Banks
+  - Number of Ranks
+  - Number of Columns
+  - Number of Rows
+  - Data Rate
+  - Burst Length
+
+- Memory Timing Specification (memory dependent)
+  - Clock in MHz
+  - RC
+  - RCD
+  - RL
+  - RP
+  - RFC
+  - RAS
+  - WL
+  - AL
+  - DQSCK
+  - RTP
+  - WR
+  - XP
+  - XPDLL
+  - XS
+  - XSDLL
+  - REFI
+  - CL
+  - TAW
+  - RRD
+  - CCD
+  - WTR
+  - CKE
+  - CKESR
+
+- Memory Power Specification
+
+- Address Mapping
+  - Length: address length in bits
+  - Row: bits used for the row
+  - Bank:  bits used for the bank
+  - Column: bits used for the column
+
+- Memory Configuration
+  - Bankwise Logic
+  - Open Page Policy
+  - Maximum Number of Transactions
+  - Scheduler
+  - Capacitor size
+  - Powerdown Mode
+  - Powerdown Timeout
+  - Chip seed
+  - CSV file
+  - Storage Mode value
+
+
+Some attributes are self-explanatory while others require some previous
+knowhow of memory technologies or some knowledge of the simulator source code.
+
+## DRAMSys Resources
+
+Some resources of the simulator are available in the **resources** directory
+its sub-directories.
 
 ```
 $ cd /projects/dram.vp.system/dram/resources
@@ -89,9 +208,15 @@ $ cd /projects/dram.vp.system/dram/resources
 
 A short description of the content each directory follows.
 
-* resources
-  * configs - XML files used for configurate specific details of the simulation.
-  * scripts - useful tools.
-  * simulations - global configs for simulations: debug mode, power analysis and database recording. Some specific configuration files are referenced in the global configuration file.
-  * traces - trace files for simulations. They contain accesses to memory in certain known scenarios.
+- **resources**
+  - **configs**: XML files used for configure specific details of the simulation.
+    - am_configs: address mapping configuration
+    - memconfigs: memory configuration
+    - memspecs: configuration related to the memory technology
+    - simconfigs: simulator configuration
+  - **scripts**: useful tools like address scrambler, trace analyser, database
+    creator, etc.
+  - **simulations**: global configuration
+  - **traces**: trace files for simulations. They contain accesses to memory
+    in certain known scenarios.