Application design flow

Quick links: introduction, step-by-step, notes

Introduction

Depending on the complexity of a program, the application design flow (figure 1) may involve many iterations of modifying and subsequently compiling and testing the program on either the NOC simulator or the FPGA implementation.

Figure 1: The Application design flow.

There are three media on which a mMIPS NOC program can be run: the hardware simulator (A), the FPGA (B) and the Linux shell / Windows command prompt using a C++ Integrated Debugging Environment (not shown in figure 1). These media differ from each other with regard to accuracy, speed or debugging capabilities (see table 1).

Table 1: Properties of the hardware simulator, FPGA and C++ Integrated Debugging Environment (e.g. kdevelop) when they are used to run programs.

Run typeAccuracy SpeedDebugging capabilities
hardware simulator + cycle accurate -- very slow - printf(), memory trace
FPGA ++ the real thing - large up/download time - printf()
C++ IDE - simulation + approx. real time ++ capabilities of IDE

Code execution speed using the hardware simulator is much lower than on the FPGA. It takes three hours to simulate 600 milliseconds of the multi-processor JPEG decoder on a Pentium III 1 GHz processor running GNU/Linux 2.4.20 with 2048 MB of RAM (the ICS/ES servers). This is almost a factor of 20.000 slower (more information). Running the same code on the FPGA may perhaps take only 60 milliseconds, but up- and downloading instruction and data memories can take quite long. As an example, uploading four nodes of 16k code and 16k data to the BenOne development board using bendime.exe takes around 10 minutes (using the USB interface). This makes the hardware simulator useful for small programs (or program fragments) and the FPGA option useful for programs with a simulation time that is larger than the time it takes to up- and download the processor memories. The debugging information that the user gains from a FPGA session is the memory contents of all the processors when they stopped. Simple printf() debugging is possible because the mMIPS debugging library mtools supports a printf() variant that stores formatted output in memory. The hardware simulator adds the ability to trace specific memory addresses (see the step-by-step procedure for more information).

The third option of table 1 involves running the program on the Linux shell or Windows command prompt at a speed approximately the same as on the FPGA realization (for a typical system with a 1 GHz processor). It is the fastest option since there is no overhead for up- and downloading of the memories as with the FPGA. This option is also the least accurate, and thus most suitable for debugging in the early stages of your program development. When the program is compiled for the Linux or Windows command prompt, the communications functions of the C communications library will output all transmissions to a file and read all receptions from a file. This enables simple debugging using the network. See the C communications and debugging libraries more information. The third option also has the best debugging support. This is because the user has access to the debugging capabilities of an IDE such as kdevelop (ICS servers) or Borland C++ (Windows).

Step-by-step procedure

The procedure of debugging a C program will be made concrete by applying it on the gossip test application. Gossip is located in the folder ./c_prog/gossip of the package. There are separate design flows for all three media mentioned in table 1: using the hardware simulator, using the FPGA realization and using the C++ IDE.

Design flow using the hardware simulator mips (A)

1. Log on to an ICS Server
  Log on to a ICS server (e.g. co7.ics.ele.tue.nl). If you are using Windows you can use a SSH (Secure Shell) client such as SSH Secure Client to log on (instructions).
2. Update the hardware simulator for the mMIPS NOC
  It you have changed the C++ sources of the mMIPS NOC then you need to create a new hardware simulator. If not, then you can use the simulator mips in ./c_prog/gossip which is for the NOC that comes with the package (it is identical to the simulator that is present in ./samples/noc/simulator).
3. Set up the C communications and debugging libraries
  Gossip uses the C communications and debugging libraries. You need to compile these libraries and define an environment variable NOCTOOLS that points to them (see instructions). Needless to say, you only need to perform this step once (unless you change the library sources).
4. Modify the gossip sources
  Make modifications to the C sources of the application, if desired.
5. Compile and simulate
 

Use the script ./dolcc X to compile gossip, set up the data memories for the simulator (mips_ram.xXyY.bin) and run a simulation for X minutes. You can use a value of 0 if you don't want to do a simulation. You will need to modify the calculation of the simulation time if your computer has a different speed. You will also need to change the way the script creates the data memories if you have changed the sizes of the mMIPS memories. See the page on the hardware simulator mips for details about the simulator. The script is for the 2-by-2 mMIPS NOC but can be easily modified. The data memories of the nodes that the simulation returns (mips_ram.xXyY.dump) are copied to the subfolder dump.

Tip 1: If you get the error "dolcc: Permission denied." this is probably because you do not have execute rights. You can grant yourself those rights by typing: chmod 744 dolcc.
Tip 2: You can redirect the output of the simulator to a file to allow you to read it back later and increase the simulation speed, especially if you use a slow connection. To redirect all output (both stdout and stderr) to the file output.txt you could give the following command: dolcc 10 >& output.txt. If you add a space followed by an ampersand ( &) at the end of the latter command, you return to the shell immediately while the simulation runs in the background.

5. Debugging options
 

See the page on the hardware simulator mips for an overview of the debugging capabilities of the simulator. After the script ./dolcc has copied the data memories to the subfolder dump, it calls the script strings.sh to echo the output of mprintf() to stdout. You need to update strings.sh if you changed the memory address range that mprintf() uses.
Tip 1: The output bitmap (in Sunraster format) is in the data memory file mips_ram.x0y1.dump (in the subfolder dumps) beginning at address 0x0 by default. khexedit is a Hexadecimal file viewer that can be used to compare this bitmap with output.ras that ./dogcc generated. You need to have an X-Server like Hummingbird Exceed running.

Design flow using the FPGA realization (B)

1. Log on to an ICS Server
  Log on to a ICS server (e.g. co7.ics.ele.tue.nl). If you are using Windows you can use a SSH (Secure Shell) client such as SSH Secure Client to log on (instructions).
2. Set up the C communications and debugging libraries
  Gossip uses the C communications and debugging libraries. You need to compile these libraries and define an environment variable NOCTOOLS that points to them (see instructions). Needless to say, you only need to perform this step once (unless you change the library sources).
3. Modify the gossip sources
  Make modifications to the C sources of the application, if desired.
4. Compile and generate the memories
 

Use the script ./dolcc X to compile gossip and set up the data memories (mips_ram.xXyY.bin). The argument X should be 0 to avoid a simulation. You will need change the way script creates the data memories if you have changed the sizes of the mMIPS memories. The script is for the 2-by-2 mMIPS NOC.

5. Upload the memories to the FPGA
  This step needs to be performed on a Windows PC that is connected to the development board. If there is a working NOC on the FPGA you can use the script benapp.bat in ./noc/bendime, which calls bendime.exe to upload the memories form the previous step. See the NOC design flow for instructions to get the FPGA on the NOC, if there is no NOC on the FPGA yet.
5. Debugging options
 

The script benapp.bat retrieves the contents of the data memories of the processors and saves it in the files mips_ram.xXyY.dump. You can use strings.sh from the Linux shell in the gossip directory to see the output of mprintf(). You will need to change that script if you have changed the memory address range that mprintf() uses.

Design flow using the C++ IDE

1. Log on to an ICS Server
  Log on to a ICS server (e.g. co7.ics.ele.tue.nl). If you are using Windows you can use a SSH (Secure Shell) client such as SSH Secure Client to log on (instructions).
2. Set up the C communications and debugging libraries
  Gossip uses the C communications and debugging libraries. You need to compile these libraries and define an environment variable NOCTOOLS that points to them (see instructions). Needless to say, you only need to perform this step once (unless you change the library sources).
3. Modify the gossip sources
  Make modifications to the C sources of the application, if desired.
4. Compile and generate the memories
 

Use the script ./dogcc to compile gossip using gcc and simulate the communication using files. See the C communications library page for background information on simulation of communication through files. The script is for the 2-by-2 mMIPS NOC. If you only want to compile gossip, you could use a simple make. See these files for more information.

5. Debugging options
 

You can use any Integrated Development Environment (IDE) to debug a program. If you use the KDE Development Environment you can use the project files that are in the gossip directory. You start this environment by typing kdevelop (an X server should be running). It supports all modern debugging options including watches and conditional breakpoints.

Notes

The compilation path of the JPEG decoder is analogous to that of gossip. You need to make few modifications to the C sources and shell scripts if you want to change the input image of the JPEG decoder or change the memory layout of the mMIPSes.