# Name

PCK_FIO - VHDL package for formatted file output

# Contents

Usage
The file output function 'fo'
Format specifiers
Special characters
Things to watch out for
Methodology notes
Parametrization
Test bench
Known limitations and problems
Author

# 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 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 follows:
  `%n{<format-string>}`
In this case, 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.

# Parametrization

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_1987
--- | ---
Synopsys VSS 3.5 and earlier | Incorrect (all zero) output in compiled mode
Synopsys VSS 97.01 | OK
Synopsys VSS/Scirocco 2000.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_1993
--- | ---
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.

# Author

Jan Decaluwe