olo_fix_pkg¶

Status Information¶

Description¶

This package contains various definitions that are used accross many olo_fix components. For example does it contain definitions and conversions that simpilify passing en_cl_fix as strings to olo_fix_components, which is required for verilog compatibility.

Definitions¶

String Representations of FixRound_t¶

String representations for all rounding modes:

FixRound_Trunc_c Truncation
FixRound_NonSymPos_c: Nearest (round up if the value isexactly half-way)
FixRound_NonSymNeg_c: Nearest (round down if the value isexactly half-way)
FixRound_SymInf_c: Nearest (round away from zero if the valueis exactly half-way)
FixRound_SymZero_c: Nearest (round towards zero if the valueis exactly half-way)
FixRound_ConvEven_c: Convergent rounding
FixRound_ConvOdd_c: Convergent rounding

Example:

...
    Round_g => FixRound_Trunc_c, -- use olo_fix_pkg constant
...
    Round_g => to_string(Trunc_s), --- use en_cl_fix FixRound_t and convert to string

String Representations of FixSaturate_t¶

String representations for all saturation modes:

FixSaturate_None_c: No saturation (wrap)
FixSaturate_Warn_c: No saturation logic but warn in simulations in case of wraparounds
FixSaturate_Sat_c: Add saturation logic but do not warn in simulations if saturation happens (for cases where saturation is expected)
FixSaturate_SatWarn_c: Add saturation and warn in simulations if saturation happens (for cases where saturation is expected)

Example:

...
    Saturate_g => FixSaturate_None_c, -- use olo_fix_pkg constant
...
    Saturate_g => to_string(None_s), --- use en_cl_fix FixSaturate_t and convert to string

Functions¶

Calculate Width of Format in String Representation¶

The fixed-point formats are passed as strings (for verilog compatibility) but their width is required for input and output ports. Therefore a function to directly calcualte the width of a fixed-point format available as string is needed.

function fixFmtWidthFromString (fmt : string) return natural;

Dynamic Shift Function¶

The way cl_fix_shift from the en_cl_fix package is written, many synthesis tools cannot synthesize it for varaible shifts. Therefore a dynamic shift function is implemented in olo_fix_pkg that can be used in the olo_fix components instead of cl_fix_shift when variable shifts are required.

function fixDynShift(   a : std_logic_vector;
                        aFmt : FixFormat_t;
                        shift : integer; 
                        minShift : integer := 0;
                        maxShift : integer;
                        rFmt : FixFormat_t;
                        rnd : FixRound_t := Trunc_s;
                        sat : FixSaturate_t := None_s) return std_logic_vector;

The function works exactly the same as cl_fix_shift but taking additional parameters for minimum and maximum shift.

Note that the shift direction is left (like in cl_fix_shift) if the shift value is positive and right if the shift value is negative.

Reading Fixed-Point Stimuli Files¶

Stimuli files written by the olo_fix cosimulation infrastructure (e.g. olo_fix_cosim in Python) follow a simple text format: the first line contains the fixed-point format string (e.g. (1,0,15)) and every following line contains one sample as hex value. The functions below allow reading such files from a testbench or behavioral model.

The first two functions operate on an already opened file (file f : text) and read the header / one sample at a time:

-- Check the header (first line) against the expected format. Must be called once directly after
-- opening the file because it consumes the header line. Asserts on a format mismatch.
procedure fixFileCheckHeader (file f : text; fmt : FixFormat_t);

-- Read a single sample (one data line) and return it as std_logic_vector with exactly
-- cl_fix_width(fmt) bits.
impure function fixFileReadSample (file f : text; fmt : FixFormat_t) return std_logic_vector;

fixFileReadSample returns the sample with exactly cl_fix_width(fmt) bits, so it can be assigned directly to a port or signal of the corresponding format.

Usage example:

use std.textio.all;
...
constant Fmt_c : FixFormat_t := cl_fix_format_from_string("(1,0,15)");
...
file DataFile      : text;
variable DataSlv_v : std_logic_vector(cl_fix_width(Fmt_c)-1 downto 0);
...
-- Open the file and check its header against the expected format
file_open(DataFile, "stimuli.fix", read_mode);
fixFileCheckHeader(DataFile, Fmt_c);

-- Read all samples
while not endfile(DataFile) loop
    DataSlv_v := fixFileReadSample(DataFile, Fmt_c);
    -- ... use DataSlv_v ...
end loop;

file_close(DataFile);

The next two functions read a complete file (given by its path) in one call. They open the file, check its header against the passed format and return all samples - either as RealArray_t or as a comma-separated string of real values (e.g. "0.1, 1.0e2", which can be used to pass to coefficient initialization generics of olo_fix).

-- Read a complete file and return all samples as real values.
impure function fixFileReadReal (filePath : string; fmt : FixFormat_t) return RealArray_t;

-- Read a complete file and return all samples as a comma-separated string of real values.
impure function fixFileReadString (filePath : string; fmt : FixFormat_t) return string;

Usage example:

constant Fmt_c    : FixFormat_t := cl_fix_format_from_string("(1,0,15)");
constant Values_c : RealArray_t := fixFileReadReal("stimuli.fix", Fmt_c);
constant String_c : string      := fixFileReadString("stimuli.fix", Fmt_c);

Internal Functions and Constants¶

The following functions and constants are used in Open Logic internally but they are not intended for use by the user and hence they are undocumented

constant FixFmt_Unused_c : FixFormat_t := (0, 1, 0);

function fixFmtWidthFromStringTolerant (fmt : string) return natural;

function fixFmtFromStringTolerant (fmt : string) return FixFormat_t;

function fixImplementReg (
        logicPresent : boolean;
        regMode      : string) return boolean;