Name

Contents

Usage

After installing the package you can call fprint as follows:

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

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 file output function 'fo'

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

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

   %[-][n]c

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 follows:

%n{<format-string>}

In this case, n is the iteration count and is mandatory. Iteration can be nested.

Special characters

A newline is specified in the format string by '\n'.

Things to notice

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

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.

Parametrization

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

A good way to understand fprint is to inspect the test bench and what it produces.

Known limitations and problems

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:
 

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

Author