298 lines
12 KiB
HTML
298 lines
12 KiB
HTML
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<meta name="GENERATOR" content="Mozilla/4.5 [en] (X11; I; SunOS 5.7 sun4u) [Netscape]">
|
|
<title>VHDL package for formatted file output</title>
|
|
<!-- $Id: PCK_FIO.html,v 1.1 2008-08-23 08:20:28 Jens Exp $ -->
|
|
</head>
|
|
<body text="#000000" bgcolor="#FFFFFF" link="#0000EE" vlink="#551A8B" alink="#FF0000">
|
|
|
|
<hr SIZE=1 NOSHADE WIDTH="100%">
|
|
<h1>
|
|
<a NAME="PCK_FIO_name_0"></a>Name</h1>
|
|
<b>PCK_FIO</b> - VHDL package for formatted file output
|
|
<p>
|
|
<hr SIZE=1 NOSHADE WIDTH="100%">
|
|
<h1>
|
|
Contents</h1>
|
|
<a href="#PCK_FIO_usage_0">Usage</a>
|
|
<br><a href="#PCK_FIO_file_0">The file output function 'fo'</a>
|
|
<br><a href="#PCK_FIO_format_0">Format specifiers</a>
|
|
<br><a href="#PCK_FIO_special_0">Special characters</a>
|
|
<br><a href="#PCK_FIO_things_0">Things to watch out for</a>
|
|
<br><a href="#PCK_FIO_methodology_0">Methodology notes</a>
|
|
<br><a href="#PCK_FIO_parametrization_0">Parametrization</a>
|
|
<br><a href="#PCK_FIO_test_0">Test bench</a>
|
|
<br><a href="#PCK_FIO_limitations_0">Known limitations and problems</a>
|
|
<br><a href="#PCK_FIO_author_0">Author</a>
|
|
<p>
|
|
<hr SIZE=1 NOSHADE WIDTH="100%">
|
|
<h1>
|
|
<a NAME="PCK_FIO_usage_0"></a>Usage</h1>
|
|
PCK_FIO is a VHDL package that defines <tt>fprint, </tt>a function
|
|
for formatted file output.
|
|
<p>After installing the package you can call <tt>fprint</tt> as follows:
|
|
<pre> fprint(F, L, Format, fo(Expr_1), fo(Expr_2), ... fo(Expr_n));</pre>
|
|
where F is the filehandle and L is the line variable.
|
|
<p>The argument Format is the format string, which consists of ``normal''
|
|
substrings which are copied verbatim, and format specifiers, starting with
|
|
<tt>'%'</tt>.
|
|
A typical format string looks as follows:
|
|
<pre> "Arg1 = %6r, Arg2 = %10d, Arg3 = %-5r\n"</pre>
|
|
The remaining arguments are the expressions whose results you want to write
|
|
to the file, embedded in <tt>fo</tt> function calls. There can be 0 to
|
|
32 of such arguments. The expressions can be of any type for which an <tt>fo</tt>
|
|
function exists. String expressions can also be called directly.
|
|
<p>
|
|
<hr SIZE=1 NOSHADE WIDTH="100%">
|
|
<h1>
|
|
<a NAME="PCK_FIO_file_0"></a>The file output function <tt>'fo'</tt></h1>
|
|
The <tt>fo</tt> (<u>f</u>ile <u>o</u>utput) functions do the trick. They
|
|
return a tagged string representation that is meaningful to format specifiers.
|
|
Here are some examples:
|
|
<pre> fo (signed'("1100")) returns "S:1100"
|
|
fo (unsigned'("1100")) returns "U:1100"
|
|
fo (TRUE) returns "L:T"
|
|
fo (127) returns "I:127"</pre>
|
|
The internal behavior of <tt>fo</tt> is irrelevant to the typical user.
|
|
<p>The <tt>fo</tt> function is currently overloaded as follows:
|
|
<pre> function fo (Arg: unsigned) return string;
|
|
function fo (Arg: signed) return string;
|
|
function fo (Arg: std_logic_vector) return string;
|
|
function fo (Arg: std_ulogic_vector) return string;
|
|
function fo (Arg: bit_vector) return string;
|
|
function fo (Arg: integer) return string;
|
|
function fo (Arg: std_ulogic) return string;
|
|
function fo (Arg: bit) return string;
|
|
function fo (Arg: boolean) return string;
|
|
function fo (Arg: character) return string;
|
|
function fo (Arg: string) return string;
|
|
function fo (Arg: time) return string;</pre>
|
|
|
|
<pre>
|
|
<hr SIZE=1 NOSHADE WIDTH="100%"></pre>
|
|
|
|
<h1>
|
|
<a NAME="PCK_FIO_format_0"></a>Format specifiers</h1>
|
|
The general format of a format specifier is:
|
|
<pre> %[-][n]c</pre>
|
|
The optional <b>-</b> sign specifies left justified output; default is
|
|
right justified.
|
|
<p>The optional number <b>n</b> specifies a field-width. If it is not specified,
|
|
<tt>fprint</tt>
|
|
does something reasonable.
|
|
<p><b>c</b> is the conversion specifier. Currently the following conversion
|
|
specifiers are supported:
|
|
<dl COMPACT>
|
|
<dt>
|
|
<a NAME="PCK_FIO_r_0"></a><b>r</b></dt>
|
|
|
|
<dd>
|
|
reasonable output format (inspired by Synopsys VSS)</dd>
|
|
|
|
<dl COMPACT>Prints the ``most reasonable'' representation e.g. hex for
|
|
unsigned, signed and other bit-like vectors (not preferred for integers)</dl>
|
|
|
|
<dt>
|
|
<a NAME="PCK_FIO_b_0"></a><b>b</b></dt>
|
|
|
|
<dd>
|
|
bit-oriented output</dd>
|
|
|
|
<dt>
|
|
<a NAME="PCK_FIO_d_0"></a><b>d</b></dt>
|
|
|
|
<dd>
|
|
decimal output</dd>
|
|
|
|
<dt>
|
|
<a NAME="PCK_FIO_s_0"></a><b>s</b></dt>
|
|
|
|
<dd>
|
|
string output (e.g. in combination with 'IMAGE for enum types)</dd>
|
|
|
|
<dt>
|
|
<a NAME="PCK_FIO_q_0"></a><b>q</b></dt>
|
|
|
|
<dd>
|
|
``qualified'' string output (shows internal representation from <tt>fo</tt>)</dd>
|
|
|
|
<dt>
|
|
<a NAME="PCK_FIO__0"></a><b>{}</b></dt>
|
|
|
|
<dd>
|
|
Iteration operator, used as follows:</dd>
|
|
|
|
<dd>
|
|
<tt>%n{<format-string>}</tt></dd>
|
|
|
|
<br>In this case, <b>n</b> is the iteration count and is mandatory. Iteration
|
|
can be nested.</dl>
|
|
|
|
<hr SIZE=1 NOSHADE WIDTH="100%">
|
|
<h1>
|
|
<a NAME="PCK_FIO_special_0"></a>Special characters</h1>
|
|
To print a double-quote, use <tt>'""'</tt> in the format string (VHDL
|
|
convention). To print the special characters, <tt>'\'</tt>, and <tt>'%'</tt>,
|
|
escape them with <tt>'\'</tt>. To prevent <tt>'{'</tt> and <tt>'}'</tt>
|
|
from being interpreted as opening and closing brackets in iteration strings,
|
|
escape them with <tt>'\'</tt>.
|
|
<p>A newline is specified in the format string by <tt>'\n'</tt>.
|
|
<p>
|
|
<hr SIZE=1 NOSHADE WIDTH="100%">
|
|
<h1>
|
|
<a NAME="PCK_FIO_things_0"></a>Things to notice</h1>
|
|
The fprint function expands into VHDL <tt>write</tt> and <tt>writeline</tt>
|
|
commands. As in plain VHDL, nothing will be written to the output file
|
|
until a <tt>writeline</tt> is given. Therefore, don't forget to include
|
|
<tt>'\n'</tt>
|
|
commands in the format string, or it ``will not work''.
|
|
<p>The preferred format specifier for integers is, naturally, <b>%d</b>.
|
|
This calls the VHDL <tt>write</tt> for integers. If you specify a field
|
|
width that is too small, the field will automatically be expanded. If you
|
|
use <b>%r</b> for integers, the field is not expanded automatically, which
|
|
means that some digits are simply thrown away. This may sometimes be useful
|
|
but it is also dangerous. Look at the test bench output for differences
|
|
between <b>%d</b> and <b>%r</b> output.
|
|
<p>When using the <b>%d</b> format specifier, the VHDL constraints for
|
|
the allowed integer range apply.
|
|
<p>In VHDL, signed/unsigned types have been standardized only relatively
|
|
recently, in the package <tt>IEEE.numeric_std</tt>. The lack of a standard
|
|
has caused (and is causing) portability issues. The most popular non-standard
|
|
package that defines signed/unsigned is <tt>IEEE.std_logic_arith</tt> from
|
|
Synopsys. PCK_FIO has been developed with this latter package, and still
|
|
refers to this package by default. However, PCK_FIO works with
|
|
<tt>IEEE.numeric_std</tt>
|
|
as well. To use <tt>IEEE.numeric_std</tt>, replace the reference to <tt>IEEE.std_logic_arith</tt>
|
|
in the source code. This needs to be done consistently in a design
|
|
database (e.g. in the PCK_FIO test bench as well).
|
|
<p>
|
|
<hr SIZE=1 NOSHADE WIDTH="100%">
|
|
<h1>
|
|
<a NAME="PCK_FIO_methodology_0"></a>Methodology notes</h1>
|
|
The obvious application for <tt>fprint</tt> is in test benches, to produce
|
|
output files that trace the simulation behavior.
|
|
<p>Another interesting application for <tt>fprint</tt> is to produce info,
|
|
warning and error messages in your models. As it can take arguments, <tt>fprint</tt>
|
|
is much better suited for this task than VHDL's <tt>assert</tt> or <tt>report</tt>
|
|
statements. Actually <tt>fprint</tt> produces its own (few) warning messages.
|
|
<p>An advanced usage is the generation of test vectors in a specific format.
|
|
Instead of using the <tt>fo </tt>functions, you can write your own set
|
|
of functions that return the symbols of a specific test format in a way
|
|
that is understandable to the <tt>fprint</tt> format specifiers. As an
|
|
example, when a high output value should be represented using the symbol
|
|
'H' it suffices to write a conversion function that returns "B:H" and call
|
|
it in combination with the <b>%b</b> format specifier.
|
|
<p>
|
|
<hr SIZE=1 NOSHADE WIDTH="100%">
|
|
<h1>
|
|
<a NAME="PCK_FIO_parametrization_0"></a>Parametrization</h1>
|
|
Prefix and postfix strings for bit-oriented and hex-oriented output are
|
|
parameterizable in the packages to accommodate different output styles.
|
|
The settings in the distribution are such that hex output is indicated
|
|
by the prefix '0x', while bit output prefix and postfix are empty
|
|
strings.
|
|
<p>You can adapt the output style by modifying the following constants
|
|
in the package header:
|
|
<p> <tt> -- prefix string for hex output</tt>
|
|
<br><tt> -- VHDL style: "X"""</tt>
|
|
<br><tt> -- Verilog style: "h'"</tt>
|
|
<br><tt> -- C style: "0x"</tt>
|
|
<br><tt> constant FIO_h_PRE: string := "0x";</tt>
|
|
<p><tt> -- postfix string for hex output</tt>
|
|
<br><tt> -- VHDL style: """"</tt>
|
|
<br><tt> constant FIO_h_POST: string := "";</tt>
|
|
<p><tt> -- prefix string for bit vector output</tt>
|
|
<br><tt> -- VHDL style: "B"""</tt>
|
|
<br><tt> -- Verilog style: "b'"</tt>
|
|
<br><tt> constant FIO_bv_PRE: string := "";</tt>
|
|
<p><tt> -- postfix string for bit vector output</tt>
|
|
<br><tt> -- VHDL style: """"</tt>
|
|
<br><tt> constant FIO_bv_POST: string := "";</tt>
|
|
<p><tt> -- prefix string for bit output</tt>
|
|
<br><tt> -- VHDL style: "'"</tt>
|
|
<br><tt> -- Verilog style: "b'"</tt>
|
|
<br><tt> constant FIO_b_PRE: string := "";</tt>
|
|
<p><tt> -- postfix string for bit output</tt>
|
|
<br><tt> -- VHDL style: "'"</tt>
|
|
<br><tt> constant FIO_b_POST: string := "";</tt>
|
|
<p>
|
|
<hr SIZE=1 NOSHADE WIDTH="100%">
|
|
<h1>
|
|
<a NAME="PCK_FIO_test_0"></a>Test bench</h1>
|
|
Included in the distribution is a file <tt>TB_PCK_FIO.vhd</tt> with a test
|
|
bench for the PCK_FIO package. The file <tt>PCK_FIO.out.gold </tt>contains
|
|
the expected output. If you run the test bench it should produce the file
|
|
<tt>PCK_FIO.out</tt>
|
|
that should be identical to <tt>PCK_FIO.out.gold</tt>. The source files
|
|
should be analyzed in a VHDL library <tt>EASICS_PACKAGES</tt>.
|
|
<p>A good way to understand <tt>fprint</tt> is to inspect the test bench
|
|
and what it produces.
|
|
<p>
|
|
<hr SIZE=1 NOSHADE WIDTH="100%">
|
|
<h1>
|
|
<a NAME="PCK_FIO_limitations_0"></a>Known limitations and problems</h1>
|
|
This VHDL package is an implementation of a flexible concept. It is likely
|
|
to be extended and modified in the future. Backward compatibility is not
|
|
guaranteed. Therefore, it is not recommended to give this package the status
|
|
of a company-wide standard package (or even worse, a VHDL standard package).
|
|
Rather, it should be linked with a particular project (and it can be regarded
|
|
as a standard package within that project).
|
|
<p>PCK_FIO is written in standard VHDL Std1076-1987. Nevertheless, some
|
|
simulators/versions have problems with the package. The following is an
|
|
overview of currently known issues:
|
|
<br>
|
|
<center><table BORDER COLS=2 WIDTH="80%" >
|
|
<tr>
|
|
<th>Simulator</th>
|
|
|
|
<th>PCK_FIO handling</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Synopsys VSS 3.5 and earlier</td>
|
|
|
|
<td>Incorrect (all zero) output in compiled mode</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Synopsys VSS 97.01</td>
|
|
|
|
<td>OK</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Mentor quickhdl</td>
|
|
|
|
<td>OK</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Modeltech modelsim</td>
|
|
|
|
<td>OK</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Cadence Leapfrog</td>
|
|
|
|
<td>Should work with 4.4.1
|
|
<br>Mysterious problems have been reported - please run the test bench
|
|
and report problems</td>
|
|
</tr>
|
|
|
|
<caption ALIGN=BOTTOM>PCK_FIO and various simulators/versions</caption>
|
|
</table></center>
|
|
|
|
<p>Although the package name suggests file IO, it only does file output.
|
|
<p>
|
|
<hr SIZE=1 NOSHADE WIDTH="100%">
|
|
<h1>
|
|
<a NAME="PCK_FIO_author_0"></a>Author</h1>
|
|
<a href="mailto:jand@easics.be">Jan Decaluwe</a>
|
|
<p>
|
|
<hr SIZE=1 NOSHADE WIDTH="100%">
|
|
</body>
|
|
</html>
|