Verilog File Operations
Verilog has system tasks and functions that can open files, output values into files, read values from files and load into other variables and close files.
This application describes how the Verilog model or testbench can read text and binary files to load memories, apply a stimulus, and control simulation. The file I/O functions format is based on the C stdio routines, such as fopen, fgetc, fprintf, and fscanf.
The Verilog language has a set of system functions to write files ($fdisplay, $fwrite, etc.) but only reads files with a single, fixed format ($readmem).
In the past, if we wanted to read a file that was not in $readmem format, we would have to learn the Programming Language Interface (PLI) and the C language, write C code to read the file and pass values into Verilog, then debug the combined C and Verilog code. Also, the Verilog is limited to 32 open files at a time.
However, using the new file I/O system functions, we can perform the file I/O directly from Verilog. We can write Verilog HDL to:
- Read stimulus files to apply patterns to the inputs of a model.
- Read a file of expected values for comparison with your model.
- Read a script of commands to drive simulation.
- Read either ASCII or binary files into Verilog registers and memories.
- Have hundreds of log files open simultaneously (though they are written to one at a time).
The code for all the examples in this file is included in the examples directory for the file I/O functions.
NOTE: These system tasks behave the same as the equivalent stdio routines. For example, $fscanf will skip over white-space, including blank lines, just like fscanf(). We can prototype code in C then convert it to Verilog.
Opening and Closing Files
The $fopen function opens a file and returns a multi-channel descriptor in an unsized integer format. This is unique for each file. All communications between the simulator and the file take place through the file descriptor. Users can specify only the name of a file as an argument. It will create a file in the default folder or a folder given in the full path description.
We use the $fclose function to close an opened file. This function is called without any arguments. It simply closes all open files. If an argument is specified, it will close only a file in which the descriptor is given. By default, before the simulator terminates, all open files are closed. It means that the user does not have to close any files, and closing is done automatically by the simulator.
All file output tasks work in the same way as their corresponding display tasks. The only difference is a file descriptor that appears as the first argument in the function argument list. These functions only can append data to a file and cannot read data from files.
Opening File Modes
| Argument | Description |
|---|---|
| “r” or “rb” | Open for reading. |
| “w” or “wb” | Create a new file for writing. If the file exists, truncate it to zero length and overwrite it. |
| “a” or “ab” | If the file exists, append (open for writing at EOF), else create a new file. |
| “r+”, “r+b” or “rb+” | Open for both reading and writing. |
| “w+”, “w+b” or “wb+” | Truncate or create for an update. |
| “a+”, “a+b”, or “ab+” | Append, or create a new file for an update at EOF. |
How to Write Files
| Function | Description |
|---|---|
| $fdisplay | Similar to $display, write out to file instead |
| $fwrite | Similar to $write, write out to file instead |
| $fstrobe | Similar to $strobe, write out to file instead |
| $fmonitor | Similar to $monitor, write out to file instead |
Each of the above system’s functions prints values in radix decimal. They also have three other versions to print values in binary, octal and hexadecimal.
| Function | Description |
|---|---|
| $fdisplay() | Prints in decimal by default |
| $fdisplayb() | Prints in binary |
| $fdisplayo() | Prints in octal |
| $fdisplayh() | Prints in hexadecimal |
The above code gives the following outputs, such as:
Value displayed with $fdisplay 26 00011010 032 1a The value displayed with $fwrite 43001010110532b The value displayed with $fstrobe 60 00111100 074 3c The value displayed with $fmonitor 60 0 1 2 3 4
Read Files
To read and store data from a memory file, we use the $readmemh and $readmemb functions.
The $readmemb task reads binary data, and $readmemh reads hexadecimal data. Data has to exist in a text file. White space is allowed to improve readability, as well as comments in both single-line and block. The numbers have to be stored as binary or hexadecimal values. The basic form of a memory file contains numbers separated by new line characters loaded into the memory.
When a function is invoked without starting and finishing addresses, it loads data into memory starting from the first cell. Start and finish addresses have to be used to load data only into a specific part of memory.
The address can be explicit, given in the file with the @ character, followed by a hexadecimal address with data separated by a space. It is essential to remember the start and finish addresses range given in the file. The argument in function calls has to match each other. Otherwise, an error message will be displayed, and the loading process will be terminated.
Reading a Line
The system function $fgets reads characters from the file specified by [hl]fd[/hd] into the variable str until str is filled, or a newline character is read and transferred to str, or an EOF condition is encountered.
If an error occurs during the read, it returns code zero. Otherwise, it returns the number of characters read.
Detecting EOF
The system function $feof returns a non-zero value when EOF is found and returns zero otherwise for a given file descriptor as an argument.
Multiple Arguments to fdisplay
When multiple variables are given to $fdisplay, it simply prints all variables in the given order one after another without space.
Formatting Data to String
The first argument in the $sformat system function is the variable name into which the result is placed.
The second argument is the format_string, which tells how the following arguments should be formatted into a string.