PCK_FIO is a VHDL package that defines fprint,a function for formatted file output. After installing the package you can call fprint as follows:

fprint(F, L, Format, fo(Expr_1), fo(Expr_2), ... fo(Expr_n));

where F is the filehandle and L is the line variable. The argument Format is the format string, which consists of `normal'' substrings which are copied verbatim, and format specifiers, starting with'%'`. A typical format string looks as follows:

"Arg1 = %6r, Arg2 = %10d, Arg3 = %-5r\n"

The remaining arguments are the expressions whose results you want to write to the file, embedded in fo function calls. There can be 0 to 32 of such arguments. The expressions can be of any type for which an fo function exists. String expressions can also be called directly.

The file output function 'fo'

The fo (file output) functions do the trick. They return a tagged string representation that is meaningful to format specifiers. Here are some examples:

  fo (signed'("1100"))   returns "S:1100"
  fo (unsigned'("1100")) returns "U:1100"
  fo (TRUE)              returns "L:T"
  fo (127)               returns "I:127"

The internal behavior of fo is irrelevant to the typical user. The fo function is currently overloaded as follows:

  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;

To support null-terminated strings, the function fo(Arg: string) processes Arg up to the first NUL character, if any. If you want the whole string to be outputted you can just enter the string as a direct argument in fprint. See also the examples in the testbench.

Format specifiers

The general format of a format specifier is:

%[-][n]c

The optional - sign specifies left justified output; default is right justified.

The optional number n specifies a field-width. If it is not specified, fprint does something reasonable.

c is the conversion specifier. Currently the following conversion specifiers are supported:

r
reasonable output format (inspired by Synopsys VSS). Prints the `most reasonable` representation e.g. hex for unsigned, signed and other bit-like vectors (not preferred for integers)
b
bit-oriented output
d
decimal output
s
string output (e.g. in combination with 'IMAGE for enum types)
q
`qualified` string output (shows internal representation from fo)
{}
Iteration operator, used as %n{<format-string>} where n is the iteration count and is mandatory. Iteration can be nested.

Special characters

To print a double quote, use '""' in the format string (VHDL convention). To print the special characters, '\', and '%', escape them with '\'. To prevent '{' and '}' from being interpreted as opening and closing brackets in iteration strings, escape them with '\'. A newline is specified in the format string by '\n'.

Things to notice

The fprint function expands into VHDL write and writeline commands. As in plain VHDL, nothing will be written to the output file until a writeline is given. Therefore, don't forget to include '\n' commands in the format string, or it `will not work`.

The preferred format specifier for integers is, naturally, %d. This calls the VHDL write for integers. If you specify a field width that is too small, the field will automatically be expanded. If you use %r 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 %d and %r output.

When using the %d format specifier, the VHDL constraints for the allowed integer range apply. In VHDL, signed/unsigned types have been standardized only relatively recently, in the package IEEE.numeric_std. The lack of a standard has caused (and is causing) portability issues. The most popular non-standard package that defines signed/unsigned is IEEE.std_logic_arith from Synopsys. PCK_FIO works with both packages, but refers to the standard package IEEE.numeric_std by default. To use IEEE.std_logic_arith instead, replace the reference to IEEE.numeric_std in the source code. This needs to be done consistently in a design database (e.g. in the PCK_FIO test bench as well).

Methodology notes

The obvious application for fprint is in test benches, to produce output files that trace the simulation behavior. Another interesting application for fprint is to produce info, warning and error messages in your models. As it can take arguments, fprint is much better suited for this task than VHDL's assert or report statements. Actually fprint produces its own (few) warning messages. An advanced usage is the generation of test vectors in a specific format. Instead of using the fo 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 fprint 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 format specifier.

Parameterization

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. You can adapt the output style by modifying the following constants in the package header:

  -- prefix string for hex output
  -- VHDL style:    "X"""
  -- Verilog style: "h'"
  -- C style:       "0x"
  constant FIO_h_PRE: string := "0x";

  -- postfix string for hex output
  -- VHDL style:    """"
  constant FIO_h_POST: string := "";

  -- prefix string for bit vector output
  -- VHDL style:    "B"""
  -- Verilog style: "b'"
  constant FIO_bv_PRE:  string := "";

  -- postfix string for bit vector output
  -- VHDL style:    """"
  constant FIO_bv_POST: string := "";

  -- prefix string for bit output
  -- VHDL style:    "'"
  -- Verilog style: "b'"
  constant FIO_b_PRE:  string := "";

  -- postfix string for bit output
  -- VHDL style:    "'"
  constant FIO_b_POST: string := "";

Test bench

Included in the distribution are the files TB_PCK_FIO_1987.vhd and TB_PCK_FIO_1993 with a test bench, depending on the standard you're running, for the PCK_FIO package. The file PCK_FIO.out.gold contains the expected output. If you run the test bench it should produce the file PCK_FIO.out that should be identical to PCK_FIO.out.gold. The source files should be analyzed in a VHDL library EASICS_PACKAGES. A good way to understand fprint is to inspect the test bench and what it produces.

Known limitations and problems

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). PCK_FIO is available in either standard VHDL Std1076-1987 or standard VHDL Std1076-1993. Nevertheless, some simulators/versions have problems with the package. The following is an overview of currently known issues:

 

PCK_FIO_1987 and various simulators/versions

 

Simulator PCK_FIO handling
Synopsys VSS 3.5 and earlier Incorrect (all zero) output in compiled mode
Synopsys VSS 97.01 OK
Synopsys VSS/Scirocco 2002.02 Incorrect output in compiled mode, interpreted mode works
Mentor quickhdl OK
Modeltech modelsim OK
Cadence Leapfrog Should work with 4.4.1. Mysterious problems have been reported - please run the test bench and report problems

 

PCK_FIO_1993 and various simulators/versions

 

Simulator PCK_FIO handling
Synopsys VSS/Scirocco 2000.02 Compile errors due to improper handling of files by Synopsys
Synopsys VSS/Scirocco 2000.06 works fine
Modeltech modelsim 5.4c and higher OK

Although the package name suggests file IO, it only does file output.