sc2vhdl Crash Course

Mini-table of contents:

• Compilation and installation
• Instructions how to use the sc2vhdl program
• List of command line options for sc2vhdl

Compilation and installation

The program was developed and tested on OS Linux, specifically Fedora 10 x86-64 and Eee PC 1.0.1 (Xandros / Debian 4.0, x86).

Instruction how to get going:

1. Check the dependencies - see section [Dependencies].
2. Prepare a patched GCC - see section [Preparing the patched GCC].
3. Compile the programs. It shall be sufficient to run the command make in the top-level directory of the source package.
4. Run the automatised tests. Change to directory tests/emulator and run the script run.sh. Then run in the same way the script in the directory tests/elab.

Dependencies

You need the following C++ libraries have installed to compile the SCVHDL:

• expat - XML parser library (SAX parser);
• boost - C++ tools library

Furthemore you need the following programs/tools/utilities:

• gcc+make toolchain;
• cmake - the program generates the Makefiles;
• graphviz - the program renders diagrams from .dot files;
• ghdl - VHDL simulator. It is used to check syntax and basic semantics of VHDL files generated by the SCVHDL program.

Preparing the patched GCC

You have to compile and install GCC 4.3.0 with plugin support. Then, the plugin itself is located in sc2vhdl/gcc-4.3.0-p/src and it will be compiled alongside with the main program.

The source text of the plugin uses GCC internal header files. Therefore, you should keep the relative position of directories which is specified bellow (this constraint can be relaxed by editing sc2vhdl/config.def).

After executing the steps bellow you will have the 'GCC with plugin support' installed in a directory $HOME/altgcc. The names of binaries shall begin with "p430" prefix (eg. p430g++) so the collision with your system GCC won't happen. Plugins can be loaded to the GCC by using new command line options -fplugin and -fplugin-arg:

    --fplugin=/path/to/plugin.so
    --fplugin-arg=some-parameters-for-the-plugin

1. GCC source codes:
   1. Download from the Internet the source codes of GCC 4.3.0 (exactly this version!)
   2. Unpack the tarball to same directory where the directory sc2vhdl/ is. That is, you shall have directories eg. $HOME/sc2vhdl and $HOME/gcc-4.3.0
   3. Please rename the directory "gcc-4.3.0" to "gcc-4.3.0-plugin".

2. GCC plugin support: Apply the patch "gcc-4.3.0-plugin-support.patch" on the GCC source texts. That is, change to gcc-4.3.0-plugin and run the command:

       patch -p1 <../sc2vhdl/gcc-4.3.0-p/gcc-4.3.0-plugin-support.patch
   

   Note: The plugin patch is taken from project Mozilla Dehydra/Treehydra.

3. Configure GCC:
   1. Create a directory gcc-4.3.0-plugin-obj in the same directory where sc2vhdl and gcc-4.3.0-plugin are located. The GCC compilation will run in this directory (out-of-tree build).
   2. Create directory $HOME/altgcc. Compiled GCC will be installed here.
   3. Configure gcc - the script "configure" HAS TO BE run from the directory gcc-4.3.0-plugin-obj! :

      ../gcc-4.3.0-plugin/configure --prefix=$HOME/altgcc
              --enable-languages=c,c++ --program-prefix=p430 \
              --disable-bootstrap --without-libstdcxx \
              --enable-checking CFLAGS="-g3 -O0" --enable-__cxa_atexit \
              --enable-targets=x86_64
      

   Notes:

   • --program-prefix=p430 : names of the compiled binaries will begin by "p430" prefix, eg. p430gcc, p430g++, so a name collision with system GCC won't happen.
   • --prefix=$HOME/altgcc : binaries will be installed to \$HOME/altgcc.
   • --enable-targets=x86_64 : select this option depending on your system's architecture to compile a 64b compiller.

4. GCC compilation and installation: run in the directory gcc-4.3.0-plugin-obj:

       make && make install
   

5. Add the newly installed GCC to your PATH:
   1. in the file $HOME/.bash_profile append directory $HOME/altgcc/bin at the end of PATH, eg: PATH=$PATH:$HOME/bin:$HOME/altgcc/bin
   2. then you should restart your session for changes to take effect.

Instructions how to use the sc2vhdl program

To process SYSTEMC source text by SCVHDL:

1. In the SYSTEMC source texts comment out the parts which set up and call functions writing VCD files (sc_create_vcd_trace_file,
   sc_close_vcd_trace_file).

2. Comment out all the prints: printf, cout and so on.

3. Source texts consisting of multiple .cpp files have to be compactified. Create a new file foo.cpp into which all the other shall be included by the #include directive (see eg. te29/tst.cpp). You will compile only this one file foo.cpp.

4. Compile the file (foo.cpp) with the patched GCC, scc plugin and supplied SYSTEMC libraries. Use the following template, changing paths to relevant files:

   p430g++ foo.cpp -c -DSC_SYNTHESIS -I../../../systemc/ \
           -fplugin=../../../gcc-4.3.0-p/src/scc_plugin.so \
           -fplugin-arg=foo.ast
   

5. File foo.ast, which was generated by GCC, will be processed by SCVHDL program. Use the following template, changing paths to relevant files:

   sc2vhdl --elab-conf resrc/sc2vhdl-config.xml tst.ast
   

When in doubt please take a look at script in tests/elab/run.sh.

List of command line options for sc2vhdl

Table: Command line options for SCVHDL

option	description
Application options
--input-file arg	name of input AST file
--add-main-arg arg	append arg as another command line parameter of the emulated program (into its argv array)
--check-exit-code arg	check that the return code of the emulated program equals the specified value arg
--no-emul	stop the processing right before the emulation would start
--elab-conf arg	the parameter arg specifies a name of configuration file for the elaboration phase. The standard file is resrc/sc2vhdl-config.xml.
--one-file	generate all the VHDL code into one big file
--vhdl-port-buffer	replace port type OUT by type BUFFER
--vhdl-proxy-out	create an auxiliary signals for OUTput ports. All assignments (and readbacks) shall go through this aux. signals. This solves the issue where it is permitted in SYSTEMC to read OUTput ports, while in VHDL it is not. --options-file arg
Controlling the listings
--dump-html-dir arg	parameter arg specifies a name of directory into which various HTML files will be written. Default value is ./html.
--dump-decl-all	list all declarations
--dump-passes	write CFG and DFG diagrams during the transformation passes.
--dump-inst	write HTML files with lists of all instances existing at the end of emulation phase
--dump-func-fg arg	write CFG and DFG diagrams of the specified function arg
--dump-backtrack	write DFG diagrams showing the results of backtracking of objects to their declarations in original SYSTEMC.
--dump-timing arg	write timing and memory consumption information into the specified file arg.
--print-trace	make the emulator write tracing information during the interpretation
--report-severity-yes arg	enable reports of the specified severity arg: Options are: DEBUG, DUMP, TRACE, HBEAT, INFO, WARN, ERROR.
--report-severity-no arg	disable reports of the specified severity arg.

About this document ...

This document was generated using the LaTeX2HTML translator Version 2002-2-1 (1.71)

Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The command line arguments were:
latex2html -split 0 app_manual-en.tex

The translation was initiated by Jaroslav Sýkora on 2009-06-22