File I/O Functions

Formal Definition

File I/O functions perform operations on files.

Simplified Syntax

$fopen (file_name) ;

$fclose (file_name) ;

$fdisplay (arguments) ;

$fwrite (arguments) ;

$fstrobe (arguments) ;

$fmonitor (arguments) ;

$readmemb ("file", memory_identifier [,begin_address[,end_address]]) ;

$readmemh ("file", memory_identifier [,begin_address[,end_address]]) ;

Description

The $fopen function opens a file and returns a multi-channel descriptor in the format of an unsized integer. 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, this will create a file in the default folder or a folder given in the full path description.

To close an opened file use the $fclose function. This function is called without any arguments, it simply closes all opened 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. This 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. (see the Display Tasks chapter for further information) 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.

To read data from a file and store it in memory, use the functions: $readmemb and $readmemh. 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 that will be loaded into the memory.

When a function is invoked without starting and finishing addresses, it loads data into memory starting from the first cell. To load data only into a specific part of memory, start and finish addresses have to be used. The address can be explicit, given in the file with the @ (at) character and is followed by a hexadecimal address with data separated by a space. It is very important to remember the range (start and finish addresses) given in the file, the argument in function calls have to match each other, otherwise an error message will be displayed and the loading process will be terminated.

Examples

Example 1

integer file ;
reg a, b, c;
initial begin
file = $fopen("results.dat") ;
a = b & c ;
$fdisplay(file, "Result is: %b", a) ;
$fclose(file) ;
end

Result of operation a = b & c will be put into the file result.dat.

Example 2

reg [3:0] memory [15:0] ;
initial begin
$readmemb("data.bin", memory) ;
end

Loading data in binary format from file data.bin into memory.

Example 3

reg [3:0] memory [15:0] ;
initial $readmemh("data.hex", memory, 4, 2) ;

Loading data in hexadecimal format from file data.hex into memory starting at address 4 and down to 2.

Important Notes

If the file that is being opened in one block and accessed in another parallel block, then an error can occur if accessing takes place before the file is opened.
Care must be taken when accessing files in independent procedural blocks.