------------------------------------------------------------------------------ INSTALL: Recoding Infrastructure for SystemC (RISC) V 0.3.0 ------------------------------------------------------------------------------ Requirements: - host platform: Linux, CentOS 6.8, x86_64 (or similar) - GNU C++ compiler tool chain (version 4.4.7 works, others may also) Sources: - http://www.cecs.uci.edu/~doemer/risc/v030/LICENSE - http://www.cecs.uci.edu/~doemer/risc/v030/INSTALL - http://www.cecs.uci.edu/~doemer/risc/v030/Makefile - http://www.cecs.uci.edu/~doemer/risc/v030/risc_v0.3.0.tar.gz Third party packages: - boost library (version 1.47.0) - ROSE compiler source installation - Accellera SystemC 2.3.1 source installation Default directory hierarchy: Makefile - Makefile to download, build, install RISC system $RISC_DOWNLOAD/ - download directory ('make clean_downloads' rm's this) boost_1_47_0.tar.gz - BOOST library package edg4x-rose/ - ROSE compiler GIT checkout systemc-2.3.1.tgz - Accellera SystemC library package risc_v0.3.0.tar.gz - RISC core package $RISC_BUILD/ - build directory ('make clean' removes this) boost_1_47_0/ - BOOST library source, object files, etc. edg4x-rose/ - ROSE compiler source, object files, etc. systemc-2.3.1/ - SystemC library source, object files, etc. objdir/ - default SystemC objects (Quick threads) objdir_pt/ - Posix-thread based SystemC objects systemc-2.3.1_lw/ - patched SystemC library source, object files, etc. objdir_lw/ - light-weight SystemC objects systemc-2.3.1_oop/ - patched SystemC library source, object files, etc. objdir_oop/ - OOO PDES SystemC objects systemc-2.3.1_mic/ - patched SystemC library for MIC (optional) objdir_mic/ - OOO PDES SystemC objects for MIC (optional) risc_v0.3.0/ - RISC compiler and simulator, including: Makefile - Makefile to build RISC compiler, simulator src/ - source code of RISC compiler oopsc/ - patch files for OOO PDES SystemC lwsc/ - patch files for light-weight SystemC headers $RISC/ - installation of the entire RISC system bin/ - executable files, including: risc - RISC compiler man/ - manual pages, including: manl/risc.l - RISC compiler man page lib/ - linker libraries, including: librisc.a - RISC API library include/ - compiler include files, including: risc.h - RISC API main header file examples/ - application examples, including: simple/ - simple examples HelloWorld.cpp - classic HelloWorld example demo/ - OOO PDES demo examples mandelbrot.cpp - Mandelbrot renderer play.cpp - audio/video player docs/ - documentation, including: RISC_API/index.html - RISC API, doxygen tree OOPSC_API/index.html - OOO PDES SystemC API, doxygen tree PDF/ - technical reports in PDF pkg/ - prereq packages for RISC (3rd party) boost_1_47_0/ - BOOST library edg4x-rose/ - ROSE compiler systemc-2.3.1/ - SystemC library (Quick threads) include/systemc.h - Accellera SystemC headers systemc-2.3.1_pt/ - SystemC library (Posix threads) include/systemc.h - Accellera SystemC headers systemc-2.3.1_lw/ - SystemC library (light-weight) include/systemc.h - light-weight SystemC headers systemc-2.3.1_oop/ - SystemC library (OOO PDES) include/systemc.h - OOO PDES SystemC headers systemc-2.3.1_mic/ - SystemC library (OOO PDES for MIC, optional) include/systemc.h - OOO PDES SystemC headers Installation Instructions for the RISC Compiler and Simulator: ============================================================== The following instructions describe the installation of the entire RISC system including the needed prerequisite third party packages. This installation is automated by use of a top-level Makefile which supports 'make' targets for all major components, as well as for the entire RISC system. ----------------------------------------------------------------------------- Step 1: Download the top-level Makefile and instructions ----------------------------------------------------------------------------- We will assume familiarity with Linux and the shell interface (csh). First, create a top-level directory for the RISC system. By default, this will hold the source and build directory trees, and also contain the installed RISC system (see default directory hierarchy above). csh$ mkdir risc_v0.3.0 csh$ cd risc_v0.3.0 Next download the top-level Makefile and corresponding instructions for the automated installation. csh$ wget http://www.cecs.uci.edu/~doemer/risc/v030/Makefile csh$ wget http://www.cecs.uci.edu/~doemer/risc/v030/INSTALL csh$ more INSTALL The downloaded INSTALL file should show/match these instructions (this text is in the INSTALL file). ----------------------------------------------------------------------------- Step 2: Adjust the paths in the top-level Makefile ----------------------------------------------------------------------------- Using your favorite text editor, adjust the directory paths defined in the first section of the Makefile (near the top) so that they fit your environment: # PATHS: (adjust these to fit your environment!) TOP = /path/to/risc_v0.3.0/top RISC = $(TOP)/risc_v0.3.0 RISC_PKG = $(TOP)/risc_v0.3.0/pkg SOURCES = /path/to/risc_v0.3.0/sources RISC_DOWNLOAD = $(SOURCES)/download RISC_BUILD = $(SOURCES)/build Typically, only the "/path/to/risc_v0.3.0" needs adjustment. For example, it should be "/home/user/risc_v0.3.0" for a "user" who wants to install RISC in his/her home directory under "risc_v0.3.0". Note that $TOP points to the install directory, whereas $SOURCES contains the downloaded packages ($RISC_DOWNLOAD) as well as the build directories ($RISC_BUILD). Thus, to save disk space, the entire $SOURCE tree may be deleted after the installation. In case you already have the needed 3rd party packages installed (with the correct settings), then you can adjust the paths defined in the next section (to save disk space and installation time). Otherwise, just leave this section as is and the packages will be downloaded, built and installed automatically. # 3RD PARTY PACKAGES: (adjust if you already have these installed) BOOST_HOME = $(RISC_PKG)/boost_1_47_0 BOOST_TARGET = $(BOOST_HOME)/include/boost/version.hpp ROSE_HOME = $(RISC_PKG)/edg4x-rose ROSE_TARGET = $(ROSE_HOME)/lib/librose.so SYSTEMC_HOME = $(RISC_PKG)/systemc-2.3.1_pt SYSTEMC_TARGET = $(SYSTEMC_HOME)/include/systemc.h ----------------------------------------------------------------------------- Step 3: Build and install the entire RISC system ----------------------------------------------------------------------------- With the configured top-level Makefile, the entire RISC system (including all 3rd party packages) can build automatically: csh$ make all This command will prepare the RISC directory tree, then download, build, and install the 3rd party packages (BOOST, ROSE, SystemC), and then download, build, and install the RISC compiler and simulator core package. This process will take significant time (about 2 hours on a modern quad-core workstation). At the end, the following message should be displayed: *********************************************************** *** RISC: Demo successful. *********************************************************** Congratulations, you have successfully installed the RISC system! ----------------------------------------------------------------------------- Trouble shooting: Build RISC components separately ----------------------------------------------------------------------------- If things go wrong and you get errors during any of the download, build, or install phases, the process will be aborted. Then you will need to find and resolve the problem, and resume the process. Here, building components separately will save time. The top-level Makefile allows to build RISC component by component (while observing the prerequisite dependencies). The following 'make' targets are supported: csh$ make dirs -> builds the RISC directory tree csh$ make downloads -> downloads all needed packages csh$ make boost -> builds and installs the BOOST library csh$ make sysc -> builds and installs Accellera SystemC csh$ make risc -> builds and installs RISC compiler and simulator csh$ make demo -> demonstrates/tests RISC OoO PDES examples In addition, the following service targets are supported: csh$ make test -> tests components and runs the RISC demo csh$ make clean -> deletes the $RISC_BUILD directory csh$ make clean_downloads -> deletes the $RISC_DOWNLOAD directory csh$ make uninstall -> deletes the $RISC installatin directory For every target component, the Makefile script will display messages reporting about the process. ----------------------------------------------------------------------------- Step 4: Use RISC (for instance, run the RISC demo examples) ----------------------------------------------------------------------------- To run the included demonstration examples, setup the RISC environment variables first: sh $ . /path/to/RISC/bin/setup.sh or csh$ source /path/to/RISC/bin/setup.csh Next, copy the demo examples into a working directory: $ mkdir work $ cp $RISC/examples/demo/* work/ $ cd work/ Then compile and simulate the examples. For instance, the conceptual DVD player example can be built and run as follows: $ vi play.cpp $ make play_seq $ make play_ooo $ /usr/bin/time play_seq $ /usr/bin/time play_ooo Note that the above installation includes both RISC (i.e. out-of-order, 'ooo') and traditional Accellera (i.e. sequential, 'seq') SystemC, so that you can directly compare the RISC OoO PDES against the classic Accellera DES. The simulation of the Mandelbrot renderer follows the same scheme: $ vi mandelbrot.cpp $ make mandelbrot_seq $ make mandelbrot_ooo $ /usr/bin/time mandelbrot_seq $ /usr/bin/time mandelbrot_ooo Depending on the parallelism available on your host machine, you can adjust the examples to your own preferences. Have fun! :-) ------------------------------------------------------------------------------ The RISC Team, September 30, 2016. ------------------------------------------------------------------------------