HSOC Files

#----------------------------------------------------------------------
#                   HOW TO BUILD & USE HSoC LIBRARY - v 0.1
#
#                   Authors: HSoC Team (C) - 29 August 2013
#
#      Miltos Grammatikakis, Antonis Papagrigoriou and Polydoros Petrakis 
#
#       Copyright: See LICENSE file that comes with this distribution
#----------------------------------------------------------------------

Short Summary
-------------
HSoC is an easy-to-use, well-documented, open source, SystemC-based, cycle-accurate
virtual platform of heterogeneous shared memory-based multicore SoCs. HSoC is developed
using a bottom up design methodology, whereas for each component, we 
a) define clean interfaces, 
b) implement a separate library, and 
c) develop separate testbenches (regression unit testing). 

Large-scale system models can instantiate and connect objects from all HSoC libraries.
Each object may also collect different types of monitoring data locally by using an
internal global monitoring library.

Although, HSoC currently refers to heterogeneous SoC models specified in SystemC, HSoC
interfacing to multicore SoC components specified in Gem5 and OMNeT is also planned.

The target users of this virtual platform includes mainly CS/EE professionals. Some
experience with high-level SoC design methodology and SystemC (e.g. reading the SystemC
User Manual and/or understanding the examples) is required.


Additional Reading
------------------
An HSoC reference manual (with implementation notes) is under construction and will appear shortly.

A good startpoint is the HSoC library overview in "hsoc_technical_overview_dsd2013.pdf" (docs directory). 

The slides have been mostly based on the paper (available upon request):
M.D. Grammatikakis, A. Papagrigoriou, P. Petrakis and G. Kornaros, "Monitoring-Aware Virtual Platform
Prototype of Heterogeneous NoC-based Multicore SoCs", in Proc. Digital Systems Design Conf., 2013.  


Installation Prerequisites
--------------------------
Fully Compatible with
1) gcc compiler 4.7+ (http://gnu.org)
  (tested on OpenSuse 12.3 64-bit, but it should work also with other Linux platforms) 
2) SystemC-2.3.0 (http://www.systemc.org)
3) a late version of grace (e.g. 5.1.23); notice that the TARGET_ARCH environmental parameter
   required by SYSTEMC, must probably be switched off when installing grace to avoid interference.
   For this reason, we suggest to install grace via a linux package manager.


Installation steps
------------------
1) Unfortunately auto-configure has not yet been implemented, so set variables in config.mk,
   such as HSOC_LIB_PATH and LIBRARY_SRC_PATH (usually the current location of the library),
   SYSTEMC, TARGET_ARCH and TLM_HOME manually. Notice that TLM_HOME and SYSTEMC now point
   to the same directory (in SystemC-2.3.0).

   Note: This creates an incompatibility and platform-dependence (see prerequisites), but
         will be resolved by resorting to standard practices for GNU software package design
         in a subsequent version.

2) Make CC point to an your c++ compiler compatible with SystemC-2.3.0 (e.g. 4.7+ is suggested)

3) Download, install grace and set GRACE_HOME in the Makefiles of Stats and  Binary_Ncube.

4) To create the HSoC library modules and include files, run in the top directory (HSoC_LIB_PATH):
     make clean 
     make 


Your first test
---------------
1. Choose one of the regression tests, for instance:
     cd $HSOC_LIB_PATH/Memory_Controller

2. To compile the test run:
     make clean; make

   Note: For Binary_Ncube_DPM scenario, where there are two tests extending the same .h file,
         a make clean of the old test (Makefile.mpg4) must be done before compiling
         the new test (e.g. Makefile.random). The Makefile in the top directory (HSoC_LIB_PATH)
         must also be adjusted before a top-level make clean (see README.txt in Binary_NCube_DPM/).

3. read the README and run the binary:
     ./memory_controller.exe

4. examine the test setup (e.g. main and any tester/testbench/esender/receiver modules) and try
   to understand the input, output and any files created. In particular, depending on the example,
   note the .h library files used.

   Note: An HSoC reference manual (with implementation notes) on all library modules
         will be shortly available to speedup your learning curve!


Note on Older Versions
----------------------
A previous version of this platform has been fully compatible with
1) gcc compiler 4.1.2 (http://gnu.org)
  (previously tested on Centos 5.8 and OpenSuse 11.3 64-bit (32-bit would require changes), but it
   should work with other Linux platforms) 
2) SystemC-2.2 (http://www.systemc.org)
3) a late version of grace (e.g. 5.1.23); notice that the TARGET_ARCH environmental parameter
   required by SYSTEMC, must probably be switched off when installing grace to avoid interference.

Unfortunately, due to changes in compiler, the current version is known to cause glibc errors
with CPU and Memory_Controller classes. HSoC will probably not support SystemC-2.2 in the future.


Acknowledgment
--------------
The library has been developed in the course of FP7/ICT Collaborative STREP Project Virtical and
will be further supported and amended in new FP7 STREP and IP projects (TRESCCA, SAVE and DREAMS).

We are thankful to ARM for support with using FastModels platform and especially its SystemC
AMBA_PV bus interfaces (in conjunction to Virtical project). These models are not cycle-accurate
and implement transaction-level modeling (TLM2). Our DMA Controller and Camera modules use
(and actually extend) the AMBA interfaces as a way to illustrate complex system heterogeneity.
The ARM AMBA_PV (AXI3, AHB, APB) bus interface models are redistributed with this code only
for user convenience. More recent models (including ACE) are available from ARM website.


Comments and/or Suggestions
-----------------------
We will try to answer your technical questions, but try to be very specific.
We welcome new HSoC co-developers on board. 


Enjoy!

The HSoC Development Team

Miltos Grammatikakis, Antonis Papagrigoriou, Polydoros Petrakis 
Technological Educational Institute of Crete 

{mdgramma, ppetrak, apapa}@cs.teicrete.gr