Video Beginner Series 3: RTL simulation with input from an image file (PPM)

[florentw]

Introduction

This Video Beginner Series 3 shows how to input image data (from a PPM (ASCII) file) to a RTL simulation with Vivado Simulator (VSIM).

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Summary

1. PPM file format

2. Reading files in VHDL

3. Reading files in Verilog

4. Tutorial - Read file in RTL simulation with Vivado Simulator

5. What next?

[florentw]

PPM file format

Portable PixMap (PPM) is a graphic format defined by the Netbm open-source project. This is an uncompressed picture file format thus it is quite straight forward to use it for RTL simulation.

The content of a PPM file is:

• A magic number: P6 if the pixels are encoded in binary or P3 if they are encoded in ASCII numbers
• A space character (space, tab or new line)
• The image width (in ASCII number)
• A space character (space, tab or new line)
• The image height (in ASCII number)
• A space character (space, tab or new line)
• Max encoding value
• A space character (space, tab or new line)
• Content of the image (pixel values - Red-Green-Blue)

Note: A line starting with # is a comment line (not displayed in the picture)

Example with a small image:

 

The content of the PPM file (ASCII format) can be:

P3

3 3
255

#RED

255 0 0
#YELLOW

255 255 0
#GREEN

0 255 0
#WHITE

255 255 255
#CYAN
0 255 255
#BLACK
0 0 0
#BLUE
0 0 255
#MAGENTA

255 0 255
#RED
255 0 0

GIMP is an open source tool which can allow you to view PPM files. For example, if we create a PPM file with the previous data using a text editor (the PPM file is provided in the design files XVES0003/img/image_1.ppm), we can then view the small image with GIMP.

Note: To see the picture in GIMP you might need to zoom in.

[florentw]

Reading files in VHDL

VHDL has the procedure FILE_OPEN to open an external file defined as below:

FILE_OPEN (Status, file, External_Name, Open_Kind);

This procedure has the following parameters:

• Status : output variable of type FILE_OPEN_STATUS which indicates if the file opening was successful (OPEN_OK)
• file : file object (input, usually type text)
• External_Name : path of the file (input, type sting)
• Open_Kind: Opening mode. Can be READ_MODE (read only), WRITE_MODE (write only) or APPEND_MODE (write only at the end of the file)

When opened, a file can be read line by line using the procedure READLINE defined as below:

READLINE(file, line);

This procedure has the following parameters:

• file : file object (input, usually type text)
• line: Line output (type line)

Then we can read each element of a line using the procedure READ defined as below:

READ(line, value);

This procedure has the following parameters:

• line: Line output (type line)
• value : output value

Finally the file can be closed using FILE_CLOSE

FILE_CLOSE(file);

[florentw]

Reading files in Verilog

Verilog has the system task $fopen to open a file in read mode defined as below

fd = $fopen (file_name, type);

This task has the following parameters:

• file_name : Name of the file
• type: Type for file descriptor (ex. “r” for reading, “w” for writing)

And output:

• fd: File descriptor

When opened, a file can be read line by line using the task $fgets defined as below:

$fgets(str, fd);

This procedure has the following parameters:

• str : Input string
• fd: file descriptor

Then we can read each element of a line using the task $sscanf defined as below:

$sscanf (str, format, arg);

This procedure has the following parameters:

• str: Input string
• format : control string
• arg: set of arguments specifying where to place the results

Finally the file can be closed using the task $fclose

$fclose(fd);

[florentw]

Tutorial - Reading file in RTL simulation with Vivado Simulator

Note: This tutorial is intended to be used only with Vivado 2018.1, in simulation only and only with the provided images

Build the Vivado project

1. Download the tutorial files and unzip the folde

2. Open Vivado 2018.1

3. In the tcl console, cd into the unzipped directory (cd <path>/XVES_0003)

4. In the tcl console, source the script:

• For VHDL project:
   create_proj_VHDL.tcl (source ./create_proj_VHDL.tcl)
• For Verilog project:
  create_proj_Verilog.tcl (source ./create_proj_Verilog.tcl)

5. In the Sources window you can see that the project only contains one file (tb_read_file) in the simulation sources (no Design Sources or Constraints files)

Add the input file to the project

 6. Open the file XVES_0003/img/image_2.ppm with a text editor

Notes:

• This is the same file as image_1.ppm without the comment line (this test bench does not support comment line in the input file).
• This is a P3 PPM file (ASCII encoded PPM),
• The width and the height are in the same line separated by a space character
• There is only one component per line

7. In Vivado, add this file to the simulation source files

1. Click File > Add Sources … > Add or create simulation sources
   
   
2. Click Add files
3. Change Files of type to All Files and select ppm. Click OK
   

Launch the simulation

8. Launch the behavioral simulation (Run Simulation > Run Behavioral Simulation)

9. In the tcl console you can find information printed by the test bench starting by “Note:”

      Q1. Find the line printing the value of pixel 1 (Note: Pixel #1: …). What is the value for the 3 components (Red, Green and Blue)?

      Q2. What color corresponds to these 3 values? Is it expected?

      Q3. Confirm that only 9 pixels values are printed (size of the picture (3x3))

10. Close the simulation

Change the input file

11. Add the file XVES_0003/img/image_3.ppm to the project simulation source files

12. Open the test bench file in the text editor and find the following line:

• VHDL
  

  constant    file_path_c : string := "image_2.ppm";

• Verilog
  

  reg[8*11:1] file_name = "image_2.ppm";

13. Change this line to:

• VHDL
  

  constant    file_path_c : string := "image_3.ppm";

• Verilog
  

  reg[8*11:1] file_name = "image_3.ppm";

14. Launch the behavioral simulation

15. In the waveform window, you can see the size of the new image input as signal values

      Q4. What is the width (hsize_s) and the height (vsize_s) of the new image input?

[florentw]

What Next?

• Do you have issues/questions following this Vivado Beginner Series?
  1. Search on the Xilinx forums for similar questions
  2. Create a new topic on the Video Board for your issue/question with the title starting with [Video Beginner Series 3] and followed by a quick description of your issue/question
• You think you master this subject?

• Look if there are unsolved topics on the Xilinx Forums about this Vivado Beginner Series you can answer

• You liked this Video Series?
  
  • You can give Kudos using the Kudos button 
  • Make sure you are following the Xilinx Video Series topic to be informed when an new topic is published (Go to the Xilinx Video Series topic > Options > Subscribe)