Catapult C Synthesis Work Flow Tutorial
ELEC 522 Advanced VLSI Design, Rice University
Version 1.3 10/14/2010, Guohui Wang
Introduction In this tutorial, you will go through the complete work flow of Catapult C Synthesis, including bit accurate C program simulation, HDL generation, ModelSim/ISE Simulator simulation/verification, and integration with System Generator. You will build a simple sum of square computation block using Catapult C tool.
Objectives After this tutorial lab, you will be able to:
Write C/C++ code in Catapult C. Compile and simulate the C/C++ code using GCC; Use Catapult C to generate HDL code; Simulate/Verify the generated HDL model in ModelSim/ISE built-in Simulator; Integrate the HDL model into System Generator design by using the Black-box block. Then simulate a complete system in System Generator.
Design Description Use Catapult C Synthesis to implement a “sum of square” computation:
Computation equation: c = a*a + b*b; Data type: a and b are both 16bit fixed-point numbers; c is 34bit number.
Tools Used in This Lab In this lab, we will use the following tools:
Mentor Graphics Catapult C Synthesis 2009a.85 GCC 4.2.2 Xilinx ISE 10.1.3 ModelSim SE6.5c Xilinx System Generator 10.1 MATLAB 2008a
ELEC 522 Catapult C Synthesis Work Flow Tutorial ECE Department, Rice University Page 1 Procedure This tutorial comprises 6 primary steps:
1. Create a new Catapult project. Write C++ code in Catapult C; 2. Simulate C++ code using GCC; 3. Generate Verilog HDL code in Catapult; 4. Simulate/Verify HDL model in ModelSim/ISE-simulator; 5. Synthesize your HDL model using Xilinx ISE; 6. Use black-box to integrate the HDL model into System Generator and simulate the complete system in System Generator.
Please notice that the goal of this document is only to show the basic tool flow. Therefore, we do not optimize our design. In your project design, you might need to go back and forth for a couple of iterations between step 1 and step 4 to optimize your design. Besides, in this simple tutorial I have not considered the interface optimization. In your project, you need to consider the interface design, for example, pointer VS non-pointer interfaces.
STEP 1: C Programming in Catapult C Synthesis Create a new folder. Start the Catapult tool on the Linux server. Then create a new project in Catapult. Click “Set Working Directory”, in the popup dialog select the folder you just created.
In the menu, select File->New to create a new file. Type in the code below: Select File->Save as, to save this file as “example.h”.
//Include Catapult bit accurate types #include "ac_int.h"
int34 sumsquare(int16 a, int16 b);
Data type uint34 has been defined in ac_int.h: typedef ac_int<34, true> uint34;
Then create another new file, type in the following code, then save it as “example.cpp”.
#include "example.h" #pragma hls_design top
int34 sumsquare(int16 a, int16 b) { int34 c = 0; c = a * a + b* b; return c; }
ELEC 522 Catapult C Synthesis Work Flow Tutorial ECE Department, Rice University Page 2 In the cpp file, the header file is included at the beginning. Then ‘hls_design top’ pragma is used to tell Catapult tool that this kernel function is the top level design for the HDL model. Finally, the function sumsquare( ) is defined.
From the task bar, click “Setup Design”. If Catapult says “Passed Analyze”, it means there is no syntax error in your code. Otherwise, the tool shows you the error(s). This could help you quicckly debug the syntax error in your code.
SStep 2: Simulate C++ Code Using GCC Then we need to use GCC to simulate your C++ code. Create a new file, type the following code, and savee it as “example_tb.cpp”. This is our testbench in C++ language. Basically, in this testbench, we generate some test values, and then print the calculation results on the terminal.
#include
int main() { int16 aa = 0; int16 bb = 0; int34 cc = 0;
for ( int i = 0; i < 10; i++ ) { aa = i; bb = i+1; cc = sumsquare(aa, bb); printf ( "#%d: %d^2 + %d^2 = %d\r\n", i, aa.to_int(), bb.to_int(),// cc.to_int64()); }
return 0; }
o In this file, ‘//’ is used when you need to break one statements into two lines, and it tells the compiler that the statement is not finished and will continue in the next line.
ELEC 522 Catapult C Synthesis Work Flow Tutorial ECE Departmentt, Rice University Page 3 o Since aa, bb, cc are all Algorithmic C datatypes, they are not supported by standard printf( ) function. In order to print the values of aa and bb, you need to use a member method to_int( ) of the Class int16 to convert int16 datatype to the C++ int datatype, so that we could print the value through printf( ) function. Because cc is a 34bit number, if you convert it to the C++ int type, you will lose 2bits’ information. Therefore, you should use the member method to_int64( ) to convert int34 into C++ long long int datatype. (Please refer to the Chapter 2 in the document “Algorithmic C Datatypes”)
In order to compile the code using GCC, we need a Makefile. We could modify the Makefile from tutorial lab2. Finally, your Makefile will look like this:
# Makefile for example_tb.cpp CPP = /usr/bin/g++ INCLUDE = -I ${MGC_HOME}/shared/include
TARGET = example OBJECTS = example.o example_tb.o
${TARGET}: ${OBJECTS}
${OBJECTS}: example.cpp example_tb.cpp example.h Makefile
%.o : %.cpp ${CPP} -c ${INCLUDE} $<
${TARGET}: ${OBJECTS} ${CPP} ${OBJECTS} ${LINKARGS} -o $@
clean: rm -rf *.o ${TARGET}
Notice that, ${MGC_HOME} is an environment variable that points to the install path of Mentor Graphics Catapult C Synthesis. This environment varialble has been set when you log in the Linux server. In the .tcshrc file under your home directory, you source several setup scripts, and one of them sets the MGC_HOME environment variable.
At the Linux prompt, use “make” command to compile the testbench code. You will get an executable file named “example”. Run the executable file, you can see the printed results.
ELEC 522 Catapult C Synthesis Work Flow Tutorial ECE Department, Rice University Page 4
It is clear that the simulation results are correct. So far, we have finished the C++ code simulation.
SStep 3: Generate Verilog HDL Code in Catapult C Synthesis Configure your design for Xiilinx FPGA, Virtex-II Pro 2VP30ff896-7, set the frequency to 100MHz. Then click Apply button.
ELEC 522 Catapult C Synthesis Work Flow Tutorial ECE Departmentt, Rice University Page 5 Sincce you have more than one cpp file, you need to set one as the HLS top level file. Select “Int sumsquare” function, and check the “Top Design” box. Then click Apply.
Click “Architecture constraints” in the task bar on the left. Configure the architecture parameters. Then click “Schedule” to check the Gantt chart. In your project design, you need to check the timing schedule in the Gantt chart. Based on the schedule results, you might need to go back to “Architecture constraints” to change the architecture parameters to optimize your design.
Here, we just simply change the Design goal from ‘area’ to ‘latency’.
Then we pipeline the ‘sumsquare_main’ loop.
From the menu, in Tools->Set options->Output->Output format, check the box for “Verilog”. Then click Apply & Save.
ELEC 522 Catapult C Synthesis Work Flow Tutorial ECE Departmentt, Rice University Page 6
Finally, click “Generate RTL”. In the Output Files folder, you can check the reports for timing and resource usage. Verilog HDL RTL model is generated. You can also check the schematics for your design as well as the critical path.
SStep 4: Simulate//Verify HDL Model in ModelSim/ISE-simulator In order to simulate/verify the Verilog HDL code generated by Catapult, you could write a Verilog HDL testbench. However, the ISE tool provides a graphic-based testbennch editor that could help you generate the testbench easily. In this step, you will use ISE to generate a testbench waveform. Then you can edit the waveform and use it to simulate the HDL model.
Afteer that, you will generate a Verilog HDL testbench based on the testbench waveform. You will modiify the testbench file and use it to simulate our model. The reason why you still need a Verilog HDL testbench is that the text-baased testbench is much more flexible so that you could generate more complicated test vectors. Another reason is that by using a text-based testbench you could insert breakpoints in the testbench and debug the testbench just like debugging a C++ program in Visual C++. You are allowed to step over your testbench and check the value in each register.
ELEC 522 Catapult C Synthesis Work Flow Tutorial ECE Departmentt, Rice University Page 7
Step (1): Step (2): Step (3): Step (4): Create a new Import RTL Create a Simulate ISE project file testbench using the waveform waveform Step (5): Step (6): Step (7): Generate Modify the Simulate using Verilog Verilog the Verilog Testbench Testbench Testbench
In this step, you will learn to use Xilinx ISE, ISE simulator and ModelSim to simulate your HDL model.
ISE simulator (ISim) is a simulation tools which is buuilt in the Xilinx ISE tool. It has a waveform editor that allows you to generate a simulation testbench quiickly in an interactive way. The HDL simulation can be an even more fundamental step within your design flow with the tight integration of the ISE Simulator within your design environment. For more details, please check http://www.xilinx.com/tools/isim.htm.
ModelSim is one of the most powerful siimulation and verification tools in the CAD industry. It provides a unified debug environment for Verilog, VHDL and SystemC. Good standards and platform support in the industry make it easy to adopt in the majority of process and tool flows. For more details, please check www.model.com/content/modelsim-se-high-performance-simulation-and-debug.
In this step, you will first use ISE to build a new project. Then the methods of using ISim and ModelSim to simulate the HDL model are introduced, respectively.
Start Xilinx ISE on the Windows PC. Create a new ISE project. Set the project configuration like the figure below.
ELEC 522 Catapult C Synthesis Work Flow Tutorial ECE Departmentt, Rice University Page 8
Copy rtl.v and rtl_mgc_ioport.v from the Catapult project folder into the ISE project folder (we just created in the previous step). The reason why we need the rtl_mgc_ioport.v file is that we have used ‘mgc_in_wire’, ‘mgc_out_stdreg’ interfaces in our design (please refer to lab3 for details). rtl_mgc_ioport.v defines the Verilog model for these interfaces.
Now your top module should be ‘sumsquare’. The module with a icon in front of it is the top module. If not, please right click ‘sumsquare’ and select ‘Set as top module’.
Right click , select ‘Add new source’. Add a new Test Beench Waveform. Name it as ‘example_rtl_tb’.
Click Next button, then you need to assign the Unit Under Test (UUT) for this testbench. Here, since you want to verify the top level module, select ‘sumsquare’, click Next, then click Finish.
ELEC 522 Catapult C Synthesis Work Flow Tutorial ECE Departmentt, Rice University Page 9
In the ‘Initial Timing and Clock Wizard’, just keep the default value and click Finish. Once finished, you will see the waveform as below:
This is the testbench waveform. The clock is already set for you. You could edit the input value for ‘rst’, ‘a_rsc_z’ and ‘b_rsc_z’. You might notice that the simulation time is a little short. We could change this by right clicking the waveform; select ‘Set the end of Test Bench’. In the pop-up dialog, input a new simulation time. In this example, input 5000 ns.
Right click the waveform, in the menu, select Decimal for the data display for each input. Then edit the waveform as the picture below (*). Notice that the module is reset at the beginning of the simulation. Then some input values are given to ‘a_rsc_z’ and ‘b_rsc_z’ input ports. Finally, save the waveform. (*Please refer to the ISim User Guide for the details about using the ISim GUI.)
ELEC 522 Catapult C Synthesis Work Flow Tutorial ECE Departmentt, Rice University Page 10
(*Please notice: for both ISim and ModelSim simulation, the procedures above are the same; the following steps will be different.)
ISim Simulation Procedure: In the source tab, select ‘Behavior simulation’. Select ‘example_rtl_rb’ by clicking it. Then you will notice under the PProcess tab, there is a new item called ‘Xilinx ISE Simulator’.
Double click ‘Simulate Behavioral Model’ to start the simulation. You can see that the results are correct and the timing also met our expectation. By far, you have finished simulation/verification using ISE simulator.
ELEC 522 Catapult C Synthesis Work Flow Tutorial ECE Departmentt, Rice University Page 11
Next, you will generate a Verilog HDL testbench and use it to run the simulation. Select ‘example_rtl_tb’ in Source tab in the process tab. Double click ‘View Generated Testbench As HDL’, your testbench will be open as a text, but it is read-only now. From the menu, select File->Save as, save it as a Verilog HDL file (extension .v) using a different name, such as ‘example_rtl_tb_text.v’. Now you are allowed to edit it.
From the menu File->Project->Add Source, add the file ‘example_rtl_tb_text.v’ into the project. Modify the testbench as below. In this example, two new groups of input values are added. Save your changes.
Select the Verilog HDL testbench in Source tab by clicking it. Then double click ‘Simulate Behavior Model’, you could see the simulation results for your new input.
By far, you have finished simulation using ISim. Next, you will learn how to simulate using ModelSim.
ELEC 522 Catapult C Synthesis Work Flow Tutorial ECE Departmentt, Rice University Page 12
ModelSim Simulation Procedure: Assume you have two testbench files now: one is the waveform testbench, and the other is the text Verilog testbench. You could start the ModelSim simulation with eeither testbench, since the method is the same.
You need to set the path of ModelSim simulatorr. Then select ModelSim as the simulator in the project propertties*. You also need to compile the HDL simulation libraries that will be used by ModelSim*. (*Notice: these settings need to be done only once for each ISE project.)
Right click the prroject name ‘xc2vp30-7ff896’, select ‘Properties’ in the pop-up menu. Set the ‘Simulator’ option to ‘ModelSim-SE Verilog’.
Next, you need to set the path for ModelSim simulator in ISE tool so that you could start ModelSim simulation from ISE project. Go to mennu Edit->Preferences->ISE General->Integrated Tools, for the option ‘Model Tech Simulator’, click the browse button, then select ‘modelsim.exe’ in the following path : C:\modeltech_6.5c\win32. Once you finish, It should be like this:
ELEC 522 Catapult C Synthesis Work Flow Tutorial ECE Departmentt, Rice University Page 13
Next you need to compile the HDL simulation libraries for the ModelSim simulation. Select the current project by clicking its name. In the ‘Processes’ panel, expand the menu under the ‘Design Utilities’. You will see ‘Compile HDL Simulation Libraries’. Right click it, select the ‘Properties’ option in the menu. Set the “Simulator Path” to the folder where ModelSim.exe is installed.
Start compiling HDL simulation libraries by double clicking ‘Compile HDL Simulation Libraries’. If you have configured all the settings above correctly, the compiling process will finish in a while.
You have finished all the configurations needed to start a ModelSim simulation. Now, you can start the simulation. The following steps are almost the same as you did in the ISim simulation.
Change the ‘Sources for’ option in the ‘Sources’ panel to ‘Behavioral Simulation’. Click your simulation testbench ‘example_rtl_tb’. Either the text testbench oor the waveform testbench is fine, because they are essentially the same.
ELEC 522 Catapult C Synthesis Work Flow Tutorial ECE Departmentt, Rice University Page 14
Finally, double click ‘Simulate Behavioral Model’ to start the ModelSim simulation. You can check the simulation results in the ModelSim windows (*). ModelSim has more powerful debugging and simulation tools that can help you speed up your design/simulation process. (*Please refer to the ModelSim User Guide for the details about using the ModelSim GUI.)
By now, you have become familiar with simulating an RTL model using ISim and ModelSim. And you have also learnt how to generate and modify the Verilog testbench from a graphic-baased waveform testbench. Therefore, you are able to dessign more complicated testbenches for your own design in the same way.
ELEC 522 Catapult C Synthesis Work Flow Tutorial ECE Departmentt, Rice University Page 15 SStep 5: Synthesis Your Design in ISE & Post-route Simulation In the previous step, you have learnt how to simulate the HDL model. In this step, you will synthesize the HDL model so that you could get the synthesis results for timing and hardware resource information. Afteer synthesizing the HDL model, you could also do post-route simulation (in the previous step you did a behavioral simulation).
Still in ISE, change Source tab back to ‘Implementation’, then select ‘sumsquare’ module in Source tab. Double click ‘Synthesize-XST’ in the process window.
Normally, you will pass the ‘Synthesize-XST’ step. However, sometimes, you will get errors as below:
Go to the line which causes the error, you will notice the following statements:
The reason why you got this error is that ‘X’ (“Unknown”) or ‘Z’ (“High impedance”) values are not synthesizable, although they could be used in simulation/verification (A synthesizable model is a very important concept in Verilog HDL. Please refer to the Verilog tutorial or manual for details.). Therefore, you need to modify the HDL code.
Usually, there are around 5~6 these kind of errors in the code. The modification is simple, just remove “| 32’bX”, as shown below. Debug all the errors using this method, and you will now get a synthesizable HDL model.
Synthesize your model, and then check the synthesis report.
Once you have synthesized the model, you can start post-route simulation by selecting ‘Post-Route Simulation’ in the ‘Source’ panel. In post-route simulation, your design is simulated with all kinds of delays (circuit, routing, load etc) so that it is able to prrovide more accurate simulation results to you.
ELEC 522 Catapult C Synthesis Work Flow Tutorial ECE Departmentt, Rice University Page 16
Post-route simulation result is shown below:
Let us look at this waveform more closely:
Between the clock rising edge and the changing point of out_rsc_z (from 0 to 5), there is a 4ns latency, that is because the post-route simulation model already counts the latency of the actual data path. You could compare the post-route simulation result with the behavioral simulation result by zooming in the waveform closely.
Similarly, you could also run the post-route simulation in ModelSim. The method is the same as in Step 4.
ELEC 522 Catapult C Synthesis Work Flow Tutorial ECE Departmentt, Rice University Page 17 Step 6: Integrate HDL Model into System Generator In this step, you will integrate the HDL model into System Generator by using the Black-Box block. Then you could verify your design in a System Generator project.
At first, you need to create a skeleton file, which contains the Verilog HDL module with only module definition and interface declaration. This skeleton will tell System Generator Black Box block the basic information of you HDL model, so that System Generator will generate a configuration file for your HDL Black Box automatically. Once you have the configuration file for your Black Box, you need to replace the skeleton file with your synthesizable Verilog HDL file from Step 5.
Create a new folder for the System Generator project. Create a new skeleton file, and name it as ‘rtl.v’ (*Notice: the name should be the same as your RTL model.). Copy your RTL model definition into this file (Please just copy the module definition; in other words, there is only an empty module with interface definition but doing nothing). In our example, the definition of the RTL model is shown as below:
module sumsquare ( a_rsc_z, b_rsc_z, sumsquare_out_rsc_z, clk, rst ); input [15:0] a_rsc_z; input [15:0] b_rsc_z; output [33:0] sumsquare_out_rsc_z; input clk; input rst;
endmodule
Add an input ‘ce’ (clock enable signal) in the model, your code should look like this:
module sumsquare ( a_rsc_z, b_rsc_z, sumsquare_out_rsc_z, clk, ce, rst ); input [15:0] a_rsc_z; input [15:0] b_rsc_z; output [33:0] sumsquare_out_rsc_z; input clk; input ce; input rst;
endmodule
Clock and clock enable ports in black box HDL must appear as pairs . Each clock name (respectively, clock enable name) must contain the substring clk, for example my_clk_1 and my_ce_1. (Please refer to System Generator User Guide, Chapter 4: Importing HDL Modules.)
Run MATLAB. Create a new System Generator model in the same folder with your empty module definition file. Add a ‘Black Box’ from the Simulink Library Browser. In the pop-up dialog, select the empty module ‘rtl.v’. System Generator will generate a Black Box block for you.
ELEC 522 Catapult C Synthesis Work Flow Tutorial ECE Department, Rice University Page 18
Now, you are close to finished. There are only a few more steps left.
Copy your synthesizable HDL model ‘rtl.v’ into this folder, replace the empty module file. Copy all the code in ‘rtl_mgc_ioport.v’ to the end of ‘rtl.v’. Remember to add the ‘ce’ input port for the top level module of your design, since clock enable is expected by System Generator.
Double click the black box block, select ‘IISE simulator’ for simulation mode.
Now you have successfully made a Black Box for our Catapult design. It is ready for simulation. You can use this Black Box just as you use other Simulink blocks.
Create a complete System Generator system, and simulate it:
ELEC 522 Catapult C Synthesis Work Flow Tutorial ECE Departmentt, Rice University Page 19
We could also get the resource estimation from System Generator:
Congratulations! By now, you have finished the complete work flow of Catapult.
For the next step, you could go back to Catapult, try to change the architecture constraints for the Catapult project and simulate your new model.
ELEC 522 Catapult C Synthesis Work Flow Tutorial ECE Departmentt, Rice University Page 20