Usage

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 a 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;

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 has been developed with this latter package, and still refers to this package by default. However, PCK_FIO works with IEEE.numeric_std as well. To use IEEE.numeric_std, replace the reference to IEEE.std_logic_arith 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 is a file TB_PCK_FIO.vhd with a test bench for the PCK_FIO package. The file PCK_FIO.out.goldcontains 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 written in standard VHDL Std1076-1987. Nevertheless, some simulators/versions have problems with the package. The following is an overview of currently known issues:

Simulator PCK_FIO handling
Synopsys VSS 3.5 and earlier Incorrect (all zero) output in compiled mode
Synopsys VSS 97.01 OK
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

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