Verilog 读写文件（整理二）

Overview
________________________________________

This application note describes how your Verilog model or testbench can
read text and binary files to load memories, apply stimulus, and control
simulation. Files can also be written. The format of the file I/O functions
is based on the C stdio routines, such as fopen, fgetc, fprintf, and fscanf.
The Verilog language has a rich set of system functions to write files
($fdisplay, $fwrite, etc.) but only reads files with a single, fixed format
($readmem). In the past if you wanted to read a file that was not in $readmem
format, you 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. In addition, the Verilog
is limited to 32 open files at a time.
However, using the new file I/O system functions you can perform your
file I/O directly from Verilog. You 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 a 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)

File Input Functions

---

The file I/O system functions and tasks are based on the C stdio routines.
For more information on the stdio routines, consult a C manual. The major
differences between these system tasks and C are caused by the lack of
a pointer variable in the Verilog language. Strings in Verilog are stored
in registers, with 8 bits needed to store a single character.

OPEN A FILE

<span style="font-size:18px;">integer file;
 file = $fopenr("filename");
 file = $fopenw("filename");
 file = $fopena("filename");



</span>

The function $fopenr opens an existing file for reading. $fopenw opens
a new file for writing, and $fopena opens a new file for writing where
any data will be appended to the end of the file. The file name can be
either a quoted string or a reg holding the file name. If the file was
successfully opened, it returns an integer containing the file number(1..MAX_FILES)
or NULL (0) if there was an error. Note that these functions are not the
same as the built-in system function $fopen which opens a file for writing
by $fdisplay. The files are opened in C with 'rb', 'wb', and 'ab' which
allows reading and writing binary data on the PC. The 'b' is ignored on
Unix.

CLOSE A FILE

The function $fcloser closes a file for input. $fclosew closes a file for
output. It returns EOF if there was an error, otherwise 0. Note that these
are not the same as $fclose which closes files for writing.

TEST FOR END OF FILE

<span style="font-size:18px;">integer file;
reg eof;
 eof = $feof(file);</span>

The function $feof tests for end of file. If an end-of-file has been reached
while reading from the file, a non-zero value is returned; otherwise, a
0 is returned.

RETURN FILE STATUS

<span style="font-size:18px;">integer file;

 reg error;

 error = $ferror(file);</span>

The function $ferror returns the errorstatus of a file. If an error
has occurred while reading from a file, $ferror returns a non-zero value,
else 0. The error value is returned once, then reset to 0.

READ A SINGLE CHARACTER

<span style="font-size:18px;">integer file, char;
char = $fgetc(file);
 char = $getc();</span>

The function $fgetc reads a single character from the specified file and
returns it. If the end-of-file is reached, $fgetc returns EOF. You should
use a 32-bit register to hold the result from $fgetc to tell the difference
between the character with the value 255 and EOF. $getc reads from stdin.

PUSH BACK A CHARACTER

<span style="font-size:18px;">integer file;
reg [7:0] char, r;
 r = $ungetc(char, file);</span>

The function $ungetc pushes the character back into the file stream. That
character will be the next read by $fgetc. It returns the character if
it was successfully pushed back or EOF if it fails.

Note that since there is no $ungetc forstdin in C, there will not be
one in the file I/O package.

WRITE A SINGLE CHARACTER

<span style="font-size:18px;">integer stream, r, char;
 r = $fputc(stream, char);</span>

The function $fputc writes a single character to the specified
file. It returns EOF if there was an error, 0 otherwise.

READ A STRING

<span style="font-size:18px;">integer file, n, r;
 reg [n*8-1:0] string;
 r = $fgets(string, n, file);
 r = $gets(string);</span>

The function $fgets reads a string from the file. Characters are read
from the file into string until a newline is seen, end-of-file is reached,
or n-1 characters have been read. If the end-of-file is encountered, $fgets
returns a 0 and string is unchanged; otherwise, $fgets returns a 1. $gets
reads from stdin.

The function $gets is no longer supported by default in fileio v3.4.
If you want to use it, you must compile fileio.c with -DGETS. This is
because some C compilers will give an error message when compiling
fileio.c:

fileio.o: In function `fileio_gets_call`:
fileio.o: the gets function is dangerous and should not be used

You can either ignore this message, or stop using -DGETS to remove the
gets function call from fileio.c.

READ FORMATTED TEXT

<span style="font-size:18px;">integer file, count;
 count = $fscanf(file, format, args);
 count = $sscanf(string, format, args);
 count = $scanf(format, args);</span>

The function $fscanf parses formatted text from the file according
to the format and writes the results to args. $sscanf parses formatted
text from a string. $scanf parses formated text from stdin. See a C reference
manual for detailed information on fscanf, plus examples later in this
note.

The format can be either a stringconstant or a reg. It can contain:

• 
  Whitespace characters such as space, tab (\t), or newline (\n). One
  or more whitespace characters are treated as a single character, and can
  match zero or more whitespace characters from the input.
• 
  Conversion specifications which start with a %. Next is an optional
  *, which suppresses assignment. Then is an optional field width in decimal.
  Lastly is the operator character as follows:
• 
  b -- Binary values 0, 1, X, x, Z, z, _
• 
  d -- Decimal values 0-9, _, no X, x, Z, or z. Note that negative numbers
  are NOT supported because of a Verilog language limitation.
• 
  o -- Octal values 0-7, _, X, x, Z, z
• 
  h or x -- Hexadecimal values, 0-9, A-F, a-f, _, X, x, Z, z
• 
  c -- A single character
• 
  f -- A floating point number, no _, X, x, Z, or z
• 
  s -- A string
• 
  % -- The percent character
• 
  Other characters which must match the characters read from the file.
  Special characters are \" for the " character, \\ for the \ character,
  \oNNN is a single character whose ASCII value is specified by the octal
  number NNN, and %% for the character %.

The args is an optional list of registers to be assigned by $fscanf,
$sscanf, and $scanf. There must be a register for each conversion operator
(except those with %*). Bit subscripts are ignored.

Formatting & padding is closer toVerilog than C. For example,
%x of 16'h24 is '0024', not '24', and %0x returns '24', not '0024'.

$fscanf, $sscanf, and $scanf return thenumber of successful assignments
performed. If you do not want a return value from these routines, compile
fileio.c (and veriuser.c for Cadence users) with -Dscanf_task. VCS users
should switch from fileio.tab to fileio_task.tab

FIND THE FILE POSITION

<span style="font-size:18px;"></span>

<span style="font-size:18px;"><span lang="EN-US" style="color: rgb(51, 51, 51); font-family: 'Arial',sans-serif; font-size: 13.5pt; mso-fareast-font-family: 宋体; mso-font-kerning: 0pt;"><span style="font-family:宋体;font-size:14px;color:#000000;">integer file, position;
 position = $ftell(file);</span></span></span>

The function $ftell returns the position in the file for use by $fseek.
If there is an error, it returns a -1.
POSITION A FILE

<span style="font-size:18px;">
`define SEEK_SET 0
 `define SEEK_CUR 1
 `define SEEK_END 2
 integer file, offset, position, r;
 r = $fseek(file, 0, `SEEK_SET); /* Beginning */
 r = $fseek(file, 0, `SEEK_CUR); /* No effect */
 r = $fseek(file, 0, `SEEK_END); /* End of file */
 r = $fseek(file, position, `SEEK_SET); /* Previous loc */
</span>

The function $fseek allows random access in a file. You can position
at the beginning or end of a file, or use the position returned
from $ftell.

READ BINARY DATA

<span style="font-size:18px;">integer r, file, start, count;
 reg [15:0] mem[0:10], r16;
 r = $fread(file, mem[0], start, count);
 r = $fread(file, r16);</span>

The function $fread reads a binary file into a Verilog memory. The
first argument is either a register or a memory name, which must have a
subscript, though the value of the subscript is ignored. start and count
are optional.

By default $fread will store data in thefirst data location through
the final location. For the memory up[10:20], the first location loaded
would be up[10], then up[11]. For down[20:10], the first location would
be down[10], then down[11].

startand count are ignored if $fread storing data in a reg instead
of a memory. No warning isprinted if the file contains more data than
will fit in the memory.

startis the word offset from the lowest element in the memory.
For start = 2 and the memory up[10:20], the first data would be loaded
at up[12]. For the memory down[20:10] , the first location loaded would
be down[12], then down[13].

$freadreturns the number of elements read from the file, If $fread
terminates early because of an error, it will return the number of elements
successfully read. $feof can be used to determine whether the end-of-file
was reached during $fread.

Thedata in the file is broken into bytes according to the width
of the memory. An 8-bit widememory takes one byte per location, while
a 9-bit wide memory takes 2 bytes. Care should be taken when using memories
with widths not evenly divisible by 8 as there may be gaps in the data
in the memory vs. data in the file.

WRITING A FORMATTED STRING

<span style="font-size:18px;">integer file, r, a, b;
 reg [80*8:1] string;
 file = $fopenw("output.log");
 r = $sformat(string, "Formatted %d %x", a, b);
 r = $sprintf(string, "Formatted %d %x", a, b);
 r = $fprintf(file, "Formatted %d %x", a, b);</span>

The functions $sformat and$sprintf writes a formatted string into
a Verilog register.  The two functions are identical. $fprintfwrites
a formatted string to a file.  It has most, but not the formatting
capabilites of C stdio package.  The first argument is a register
to receive the formatted data, and the second is a format string. 
Additional arguments may be included.

Thesupported formats include b, c, d, e, f, g, h, m, o, r, s, and
x. %t for printing formatted time is NOT supported yet.

FLUSHING THE FILE STREAM

<span style="font-size:18px;">integer file, r;
 file = $fopenw("output.log");
 r = $fflush(file);</span>

The function $fflush(stream) causes any buffered data waiting to be
written for the named stream to be written to that file. If the stream
is 0, all files open for writing are flushed.