title	Example SystemC code
author	Doulos Inc

About the code

This is a set of example SystemC code mini-projects. Following briefly describes each project.

• hellosc: Simply displays Hello World from within a process. This is the simplest of examples.
• main: Contains an extensive main.cpp with debugging enhancements suitable for production. Replace minimal_top.?pp with your own version.
• thread-method: A simple illustration of the differences between SC_THREAD's vs SC_METHOD's
• thread_vs_method: A more complicated illustration of the behavior of SC_THREAD's vs SC_METHOD's
• nonblocking: Explains blocking vs non-blocking signal assignment in SystemC.
• netlist: Displays the design hierchy. Use in your designs.
• report_handler: Replace the default report handler with your own.
• reporting: Friendlier versions of reporting macros
• timer: Illustrates two very different types of "timers". One is for measuring execution performance of C++ code itself. The other is a hardware model that does not use sc_core::sc_clock.
• debug_fifo: A debug fifo with built-in read/write monitoring
• fixed: Illustrates use of SystemC fixed-point data types
• logic: Illustrates use of SystemC logic data types
• scdataperf: Illustrates the performance differences between various SystemC data types.
• trace: Illustrates how to get timing traces for viewing with waveform viewers ()

There are some important helper scripts and utilities that are not direct SystemC code, but used to build and run simulations:

• cmake simplifies CMakeLists.txt
• extern contains third-party libraries built with scripts (e.g., build-crc)
• include contains useful SystemC utilities (e.g., netlist and reporting add-ons)
• setup.profile sets up the environment (e.g., $WORKPATH_DIR)
• tools/* scripts that simplify building

Note: The top-level CMakeLists.txt will build and include all the mini-projects, but you are encouraged to enter each mini-project and build there. The top-level one is mostly used as a regression test.

Building

All of the samples are built inside their respective directories using cmake, and several of them use some third party libraries (mostly downloaded from GitHub). So you will need the following:

0. Set up the environment

source setup.profile # Assumes you are inside the top-level project directory. Only needs to be done once per shell.

1. Build the SystemC library itself if needed

build-systemc

2. Build the fmt and crc libraries using the build script as follows:

# both of the following will be installed under ../extern
build-crc
build-fmt ;#< this may take a few minutes

IMPORTANT: See note about locale's.

3. Enter the mini-project

cd MINI_PROJECT_NAME #< directory containing `CMakeLists.txt` and code of interest

4. Examine and build each project using following instructions.

Using the build script

The build script, located in ../extern/bin was designed to simplify using cmake; although, cmake is very simple to use once you learn it. When build runs it will display the steps you would need to use with cmake as output beginning with a % character.

By default, build will only configure and compile the code; however, you can have it run the code by adding the -test option:

build -test

You can make this the default by creating a file named .buildrc located in your home directory. This file simply contains command-line options for use with build.

echo "-test" >"${HOME}/.buildrc"

For more information using the --help option:

build --help

Try not to get bogged down in the advanced features. I normally restrict myself to:

build -clean
build -test

Locales

Ubunutu recently changed the way locales are handled. Instead of installing support for all locales, you may need to generate those you need. Here's how:

1. Examine /etc/locale.gen and choose an appropriate locale
2. Run: sudo locale-gen LOCALE
3. Run: sudo update-locale
4. Examine the ouput of locale
5. Add: export LANG=LOCALE

You will know if you get a complaint about LOCALE.

Have fun learning!