TWiki> P1076 Web>Vhdl2019CollectedRequirements>TopLCS2016_006b (2020-02-17, JimLewis)EditAttach

Language Change Specification for TextIO Updates

LCS Number: LCS-2016-006b
Version: 1 {27-Feb-2017};2 {8-Mar-2017}
Date: 8-Mar-2017
Status: Draft
Author: Patrick Lehmann / Pablo Blecua
Email: Main.PatrickLehmann
Source Doc: File IO / TextIO updates
Summary: TextIO additions.
See LCS-2016-006a for file I/O additions.

Voting Results: Cast your votes here

Yes:

  1. Patrick Lehmann - 2017-01-12 - Ver 0
  2. Jim Lewis- 2017-03-05 - Ver 2
  3. %USERSIG(SteveGrout - 2017-03-05)% - Ver 2

No:

Abstain:

  1. Brent Hayhoe - 2017-02-16 Ver 0 - Abstain due to lack of personal time for review.
  2. Farrell Ostler - 2017-03-21

Revision Notes

V1: This version implements:

  • Conversion to decimal string for std_(u)logic_vector, unsigned, and signed
  • Decimal read/write for std_(u)logic_vector, unsigned, and signed
V2:
  • Moved "to_integer", "To_StdULogicVector", and "To_StdLogicVector" from ieee.numeric_std_unsigned to ieee.std_logic_1164.
  • Removed aliases in std_logic_textio (i.e. that package is not modified)
  • Updated "16.4 Package TEXTIO" to add DREAD and DWRITE procedures for BIT_VECTOR
  • Added "5.2.6 Predefined operations on scalar types" for the new:
    • TO_STRING for INTEGER/universal_integer with a FORMAT parameter.
    • TO_STRING for universal_real with a FORMAT or DIGITS parameter.
    • TO_BSTRING, TO_OSTRING, TO_HSTRING, TO_DSTRING for INTEGER/universal_integer/REAL/universal_real.
  • Added "5.3.2.4 Predefined operations on array types" for the new TO_DSTRING for BIT_VECTOR.
  • Added "G.4.8.5 Textio functions" to add the definitions of Dread, Decimal_read, Dwrite, and Decimal_write

Remarks

None

Details of Language Change

std_logic_1164

std_logic_1164.vhdl

[...]
-- TO_INTEGER Moved from numeric_std_unsigned.vhdl (ID:D.1)
function TO_INTEGER (ARG : STD_ULOGIC_VECTOR) return NATURAL;
-- To_StdULogic_Vector Moved from numeric_std_unsigned.vhdl (ID:D.5)
function To_StdULogicVector (ARG, SIZE : NATURAL) return STD_ULOGIC_VECTOR;
function To_StdULogicVector (ARG : NATURAL; SIZE_RES : STD_ULOGIC_VECTOR) return STD_ULOGIC_VECTOR;

alias To_Std_ULogic_Vector is To_StdULogicVector [NATURAL, NATURAL return STD_ULOGIC_VECTOR];
alias To_SULV is To_StdULogicVector [NATURAL, NATURAL return STD_ULOGIC_VECTOR];
alias To_Std_ULogic_Vector is To_StdULogicVector [NATURAL, STD_ULOGIC_VECTOR return STD_ULOGIC_VECTOR];
alias To_SULV is To_StdULogicVector [NATURAL, STD_ULOGIC_VECTOR return STD_ULOGIC_VECTOR];
-- To_StdLogic_Vector Moved from numeric_std_unsigned.vhdl (ID:D.3)
function To_StdLogicVector (ARG, SIZE : NATURAL) return STD_LOGIC_VECTOR;
function To_StdLogicVector (ARG : NATURAL; SIZE_RES : STD_LOGIC_VECTOR) return STD_LOGIC_VECTOR;

alias To_Std_Logic_Vector is To_StdLogicVector [NATURAL, NATURAL return STD_LOGIC_VECTOR];
alias To_SLV is To_StdLogicVector [NATURAL, NATURAL return STD_LOGIC_VECTOR];
alias To_Std_Logic_Vector is To_StdLogicVector [NATURAL, STD_LOGIC_VECTOR return STD_LOGIC_VECTOR];
alias To_SLV is To_StdLogicVector [NATURAL, STD_LOGIC_VECTOR return STD_LOGIC_VECTOR];
-- New functions/procedures from LCS-2016-006b

function TO_DSTRING (value : in STD_ULOGIC_VECTOR) return STRING; alias TO_DECIMAL_STRING is TO_DSTRING [STD_ULOGIC_VECTOR return STRING];

procedure DWRITE (L         : inout LINE; VALUE : in STD_ULOGIC_VECTOR;
                  JUSTIFIED : in    SIDE := right; FIELD : in WIDTH := 0);
alias DECIMAL_WRITE is DWRITE [LINE, STD_ULOGIC_VECTOR, SIDE, WIDTH];

procedure DREAD (L    : inout LINE; VALUE : out STD_ULOGIC_VECTOR;
                 GOOD : out   BOOLEAN);
procedure DREAD (L : inout LINE; VALUE : out STD_ULOGIC_VECTOR);
alias DECIMAL_READ is DREAD [LINE, STD_ULOGIC_VECTOR, BOOLEAN];
alias DECIMAL_READ is DREAD [LINE, STD_ULOGIC_VECTOR];

std_logic_1164-body.vhdl
  function TO_INTEGER (ARG : STD_ULOGIC_VECTOR) return NATURAL is
    constant ARG_LEFT : INTEGER := ARG'length-1;
    alias XXARG       : STD_ULOGIC_VECTOR(ARG_LEFT downto 0) is ARG;
    variable XARG     : STD_ULOGIC_VECTOR(ARG_LEFT downto 0);
    variable RESULT   : NATURAL := 0;
  begin
    if (ARG'length < 1) then
      assert FALSE
        report "STD_LOGIC_1164.TO_INTEGER: null detected, returning 0"
        severity warning;
      return 0;
    end if;
    XARG := TO_01(XXARG, 'X');
    if (XARG(XARG'left) = 'X') then
      assert FALSE
        report "STD_LOGIC_1164.TO_INTEGER: metavalue detected, returning 0"
        severity warning;
      return 0;
    end if;
    for I in XARG'range loop
      RESULT := RESULT+RESULT;
      if XARG(I) = '1' then
        RESULT := RESULT + 1;
      end if;
    end loop;
    return RESULT;
  end function TO_INTEGER;

  ------------------------------------------------------------------
  ------------------------------------------------------------------
  function To_StdULogicVector (ARG, SIZE : NATURAL) return STD_ULOGIC_VECTOR is
    variable RESULT : STD_ULOGIC_VECTOR(SIZE-1 downto 0);
    variable I_VAL  : NATURAL := ARG;
  begin
    if (SIZE < 1) then return "";
    end if;
    for I in 0 to RESULT'left loop
      if (I_VAL mod 2) = 0 then
        RESULT(I) := '0';
      else RESULT(I) := '1';
      end if;
      I_VAL          := I_VAL/2;
    end loop;
    if not(I_VAL = 0) then
      assert FALSE
        report "STD_LOGIC_1164.To_StdULogicVector: vector truncated"
        severity warning;
    end if;
    return RESULT;
  end function To_StdULogicVector;

  function To_StdULogicVector (ARG : NATURAL; SIZE_RES : STD_ULOGIC_VECTOR)
    return STD_ULOGIC_VECTOR is
  begin
    return To_StdULogicVector (ARG  => ARG, SIZE => SIZE_RES'length);
  end function To_StdULogicVector;  

  function To_StdLogicVector (ARG, SIZE : NATURAL) return STD_LOGIC_VECTOR is
  begin
    return std_logic_vector(To_StdULogicVector (ARG  => ARG, SIZE => SIZE));
  end function To_StdLogicVector;
 
  function To_StdLogicVector (ARG : NATURAL; SIZE_RES : STD_LOGIC_VECTOR)
    return STD_LOGIC_VECTOR is
  begin
    return To_StdLogicVector (ARG  => ARG, SIZE => SIZE_RES'length);
  end function To_StdLogicVector;
  ------------------------------------------------------------------
  ------------------------------------------------------------------
  function TO_DSTRING (value : in STD_ULOGIC_VECTOR) return STRING is
    variable l : LINE;
  begin
    write(l, to_integer(value));
    return(l.all);
  end function TO_DSTRING;

  ------------------------------------------------------------------
  ------------------------------------------------------------------
  procedure DWRITE (L         : inout LINE; VALUE : in STD_ULOGIC_VECTOR;
                    JUSTIFIED : in    SIDE := right; FIELD : in WIDTH := 0) is
  begin
    write(L, to_dstring(VALUE), JUSTIFIED, FIELD);
  end procedure DWRITE;

  ------------------------------------------------------------------
  ------------------------------------------------------------------
  procedure DREAD (L    : inout LINE; VALUE : out STD_ULOGIC_VECTOR;
                   GOOD : out   BOOLEAN)  is
    variable value_i : INTEGER;
    variable good_i  : BOOLEAN;
  begin
    READ(L => L, VALUE => value_i, GOOD => good_i);
    if good_i AND (value_i > -1) then
      -- TBC if we use a) or b). b) is implemented now.
      -- a) The user does not know the integer size, so as a convention
      -- we return the maximum integer length (i.e. 32 bits).
      -- b) Get the length from VALUE and truncate with a warning if the
      -- read integer doesn't fit in the vector.
      VALUE := To_StdULogicVector(value_i, VALUE'LENGTH);   
    else
      VALUE := (VALUE'RANGE => 'X');   -- READ error or Negative number
    end if;
    GOOD  := good_i;
  end procedure DREAD;
  ------------------------------------------------------------------
  ------------------------------------------------------------------
  procedure DREAD (L : inout LINE; VALUE : out STD_ULOGIC_VECTOR) is
    variable value_i : INTEGER;
  begin
    READ(L => L, VALUE => value_i);
    if (value_i < 0) then
      assert false report "STD_LOGIC_1164.DREAD: Read value less than 0: "
        & INTEGER'image(value_i);
      VALUE := (VALUE'RANGE => 'X');
    else
      VALUE := To_StdULogicVector(value_i, VALUE'LENGTH);
    end if;
  end procedure DREAD;

numeric_std

numeric_std.vhdl
function TO_DSTRING (value : in UNRESOLVED_UNSIGNED) return STRING;
alias TO_DECIMAL_STRING is TO_DSTRING [UNRESOLVED_UNSIGNED return STRING];
function TO_DSTRING (value : in UNRESOLVED_SIGNED) return STRING;
alias TO_DECIMAL_STRING is TO_DSTRING [UNRESOLVED_SIGNED return STRING];

procedure DWRITE (L         : inout LINE; VALUE : in UNRESOLVED_UNSIGNED;
                  JUSTIFIED : in    SIDE := right; FIELD : in WIDTH := 0);

procedure DWRITE (L         : inout LINE; VALUE : in UNRESOLVED_SIGNED;
                  JUSTIFIED : in    SIDE := right; FIELD : in WIDTH := 0);

alias DECIMAL_WRITE is DWRITE [LINE, UNRESOLVED_UNSIGNED, SIDE, WIDTH];
alias DECIMAL_WRITE is DWRITE [LINE, UNRESOLVED_SIGNED, SIDE, WIDTH];

procedure DREAD (L    : inout LINE; VALUE : out UNRESOLVED_UNSIGNED;
                 GOOD : out   BOOLEAN);

procedure DREAD (L : inout LINE; VALUE : out UNRESOLVED_UNSIGNED);

procedure DREAD (L    : inout LINE; VALUE : out UNRESOLVED_SIGNED;
                 GOOD : out   BOOLEAN);

procedure DREAD (L : inout LINE; VALUE : out UNRESOLVED_SIGNED);

alias DECIMAL_READ is DREAD [LINE, UNRESOLVED_UNSIGNED, BOOLEAN];
alias DECIMAL_READ is DREAD [LINE, UNRESOLVED_SIGNED, BOOLEAN];

alias DECIMAL_READ is DREAD [LINE, UNRESOLVED_UNSIGNED];
alias DECIMAL_READ is DREAD [LINE, UNRESOLVED_SIGNED];
numeric_std-body.vhdl
  function TO_DSTRING (value : in UNRESOLVED_UNSIGNED) return STRING is
    variable l : LINE;
  begin
    write(l, to_integer(value));
    return(l.all);
  end function TO_DSTRING;
  ------------------------------------------------------------------
  ------------------------------------------------------------------
  function TO_DSTRING (value : in UNRESOLVED_SIGNED) return STRING is
    variable l : LINE;
  begin
    write(l, to_integer(signed(value)));
    return(l.all);
  end function TO_DSTRING;

  ------------------------------------------------------------------
  ------------------------------------------------------------------
  procedure DWRITE (L         : inout LINE; VALUE : in UNRESOLVED_UNSIGNED;
                    JUSTIFIED : in    SIDE := right; FIELD : in WIDTH := 0) is
  begin
    write(L, to_dstring(VALUE), JUSTIFIED, FIELD);
  end procedure DWRITE;

  ------------------------------------------------------------------
  ------------------------------------------------------------------
  procedure DWRITE (L         : inout LINE; VALUE : in UNRESOLVED_SIGNED;
                    JUSTIFIED : in    SIDE := right; FIELD : in WIDTH := 0) is
  begin
    write(L, to_dstring(VALUE), JUSTIFIED, FIELD);
  end procedure DWRITE;

  ------------------------------------------------------------------
  ------------------------------------------------------------------
  procedure DREAD (L    : inout LINE; VALUE : out UNRESOLVED_UNSIGNED;
                   GOOD : out   BOOLEAN)  is
    variable value_sulv : STD_ULOGIC_VECTOR(VALUE'RANGE);
  begin
    DREAD(L => L, VALUE => value_sulv, GOOD => GOOD);
    VALUE := unsigned(value_sulv);
  end procedure DREAD;
  ------------------------------------------------------------------
  ------------------------------------------------------------------
  procedure DREAD (L    : inout LINE; VALUE : out UNRESOLVED_UNSIGNED) is
    variable value_sulv : STD_ULOGIC_VECTOR(VALUE'RANGE);
  begin
    DREAD(L => L, VALUE => value_sulv);
    VALUE := unsigned(value_sulv);
  end procedure DREAD;

  ------------------------------------------------------------------
  ------------------------------------------------------------------
  procedure DREAD (L    : inout LINE; VALUE : out UNRESOLVED_SIGNED;
                   GOOD : out   BOOLEAN)  is
    variable value_i : INTEGER;
    variable good_i  : BOOLEAN;
  begin
    READ(L => L, VALUE => value_i, GOOD => good_i);
    if good_i then
      -- TBC if we use a) or b). b) is implemented now.
      -- a) The user does not know the integer size, so as a convention
      -- we return the maximum integer length (i.e. 32 bits).
      -- b) Get the length from VALUE and truncate with a warning if the
      -- read integer doesn't fit in the vector.
      VALUE := to_signed(value_i, VALUE'LENGTH);   
    else
      VALUE := (VALUE'RANGE => 'X');   -- READ error
    end if;
    GOOD  := good_i;
  end procedure DREAD;
  ------------------------------------------------------------------
  ------------------------------------------------------------------
  procedure DREAD (L    : inout LINE; VALUE : out UNRESOLVED_SIGNED) is
    variable value_i : INTEGER;
  begin
    READ(L => L, VALUE => value_i);
    VALUE := to_signed(value_i, VALUE'LENGTH);
  end procedure DREAD;  

numeric_std_unsigned

numeric_std_unsigned.vhdl

--============================================================================
-- Conversion Functions
--============================================================================
-- All the conversion functions are now defined in ieee.std_logic_1164, and therefore
 -- are not needed here anymore.
 -- Id: D.1
 function TO_INTEGER (ARG : STD_ULOGIC_VECTOR) return NATURAL;
 -- Result subtype: NATURAL. Value cannot be negative since parameter is an
 -- UNSIGNED vector.
 -- Result: Converts the UNSIGNED vector to an INTEGER.

-- Id: D.3
 function To_StdLogicVector (ARG, SIZE : NATURAL) return STD_LOGIC_VECTOR;
 -- Result subtype: STD_LOGIC_VECTOR(SIZE-1 downto 0)
 -- Result: Converts a non-negative INTEGER to an UNSIGNED vector with
 -- the specified SIZE.

function To_StdLogicVector (ARG : NATURAL; SIZE_RES : STD_ULOGIC_VECTOR)
 return STD_LOGIC_VECTOR;
 -- Result subtype: STD_LOGIC_VECTOR(SIZE_RES'length-1 downto 0)

alias To_Std_Logic_Vector is
 To_StdLogicVector[NATURAL, NATURAL return STD_LOGIC_VECTOR];
 alias To_Std_Logic_Vector is
 To_StdLogicVector[NATURAL, NATURAL return STD_LOGIC_VECTOR];
 alias To_SLV is
 To_StdLogicVector[NATURAL, NATURAL return STD_LOGIC_VECTOR];
 alias To_Std_Logic_Vector is
 To_StdLogicVector[NATURAL, STD_ULOGIC_VECTOR return STD_LOGIC_VECTOR];
 alias To_SLV is
 To_StdLogicVector[NATURAL, STD_ULOGIC_VECTOR return STD_LOGIC_VECTOR];

-- Id: D.5
 function To_StdULogicVector (ARG, SIZE : NATURAL) return STD_ULOGIC_VECTOR;
 -- Result subtype: STD_ULOGIC_VECTOR(SIZE-1 downto 0)
 -- Result: Converts a non-negative INTEGER to an UNSIGNED vector with
 -- the specified SIZE.

function To_StdULogicVector (ARG : NATURAL; SIZE_RES : STD_ULOGIC_VECTOR)
 return STD_ULOGIC_VECTOR;
 -- Result subtype: STD_LOGIC_VECTOR(SIZE_RES'length-1 downto 0)

alias To_Std_ULogic_Vector is To_StdULogicVector[NATURAL, NATURAL return STD_ULOGIC_VECTOR];
 alias To_SULV is To_StdULogicVector[NATURAL, NATURAL return STD_ULOGIC_VECTOR];
 alias To_Std_ULogic_Vector is To_StdULogicVector[NATURAL, STD_ULOGIC_VECTOR return STD_ULOGIC_VECTOR];
 alias To_SULV is To_StdULogicVector[NATURAL, STD_ULOGIC_VECTOR return STD_ULOGIC_VECTOR];

numeric_std_unsigned-body.vhdl
-- All the conversion functions are now defined in ieee.std_logic_1164, and therefore
 -- are not needed here anymore.
 -- Id: D.1
 function TO_INTEGER (ARG : STD_ULOGIC_VECTOR) return NATURAL is
 begin
 return TO_INTEGER(UNSIGNED(ARG));
 end function TO_INTEGER;
-- Id: D.3
 function To_StdLogicVector (ARG, SIZE : NATURAL) return STD_LOGIC_VECTOR is
 begin
 return STD_LOGIC_VECTOR (TO_UNSIGNED(ARG => ARG,
 SIZE => SIZE));
 end function To_StdLogicVector;
-- Id: D.5
 function To_StdULogicVector (ARG, SIZE : NATURAL) return STD_ULOGIC_VECTOR is
 begin
 return STD_ULOGIC_VECTOR (TO_UNSIGNED(ARG => ARG,
 SIZE => SIZE));
 end function To_StdULogicVector;
function To_StdLogicVector (ARG : NATURAL; SIZE_RES : STD_LOGIC_VECTOR)
 return STD_LOGIC_VECTOR is
 begin
 return STD_LOGIC_VECTOR (TO_UNSIGNED (ARG => ARG,
 SIZE => SIZE_RES'length));
 end function To_StdLogicVector;
function To_StdULogicVector (ARG : NATURAL; SIZE_RES : STD_ULOGIC_VECTOR)
 return STD_ULOGIC_VECTOR is
 begin
 return STD_ULOGIC_VECTOR (TO_UNSIGNED (ARG => ARG,
 SIZE => SIZE_RES'length));
 end function To_StdULogicVector;

16.3 Package STANDARD

package STANDARD is
[...]
-- function TO_STRING (VALUE: BIT_VECTOR) return STRING;
-- alias TO_BSTRING is TO_STRING [BIT_VECTOR return STRING];
-- alias TO_BINARY_STRING is TO_STRING [BIT_VECTOR return STRING];
-- function TO_OSTRING (VALUE: BIT_VECTOR) return STRING;
-- alias TO_OCTAL_STRING is TO_OSTRING [BIT_VECTOR return STRING];
-- function TO_HSTRING (VALUE: BIT_VECTOR) return STRING;
-- alias TO_HEX_STRING is TO_HSTRING [BIT_VECTOR return STRING];
-- function TO_DSTRING (VALUE: BIT_VECTOR) return STRING;
-- alias TO_DECIMAL_STRING is TO_DSTRING [BIT_VECTOR return STRING];
[...]

-- Predefined TO_STRING operations on scalar types

-- function TO_STRING (VALUE: BOOLEAN) return STRING;
-- function TO_STRING (VALUE: BIT) return STRING;
-- function TO_STRING (VALUE: CHARACTER) return STRING;
-- function TO_STRING (VALUE: SEVERITY_LEVEL) return STRING;
-- function TO_STRING (VALUE: universal_integer) return STRING;
-- function TO_STRING (VALUE: universal_real) return STRING;
-- function TO_STRING (VALUE: INTEGER) return STRING;
-- function TO_STRING (VALUE: REAL) return STRING;
-- function TO_STRING (VALUE: TIME) return STRING;
-- function TO_STRING (VALUE: FILE_OPEN_KIND) return STRING;
-- function TO_STRING (VALUE: FILE_OPEN_STATUS) return STRING;

-- Predefined overloaded TO_STRING operations

-- function TO_STRING (VALUE: universal_real; DIGITS: NATURAL) return STRING;
-- function TO_STRING (VALUE: universal_real; FORMAT: STRING) return STRING;
-- function TO_STRING (VALUE: REAL; DIGITS: NATURAL) return STRING;
-- function TO_STRING (VALUE: REAL; FORMAT: STRING) return STRING;
-- function TO_STRING (VALUE: TIME; UNIT: TIME) return STRING;
-- function TO_STRING (VALUE: universal_integer; FORMAT: STRING) return STRING;
-- function TO_STRING (VALUE: INTEGER; FORMAT: STRING) return STRING;

-- Predefined TO_xSTRING operations on scalar types

-- function TO_BSTRING (VALUE: universal_integer) return STRING;
-- alias TO_BINARY_STRING is TO_BSTRING [universal_integer return STRING];
-- function TO_OSTRING (VALUE: universal_integer) return STRING;
-- alias TO_OCTAL_STRING is TO_OSTRING [universal_integer return STRING];
-- function TO_HSTRING (VALUE: universal_integer) return STRING;
-- alias TO_HEX_STRING is TO_HSTRING [universal_integer return STRING];
-- alias TO_DSTRING is TO_STRING [universal_integer return STRING];
-- alias TO_DECIMAL_STRING is TO_STRING [universal_integer return STRING];
 
-- function TO_BSTRING (VALUE: INTEGER) return STRING;
-- alias TO_BINARY_STRING is TO_BSTRING [INTEGER return STRING];
-- function TO_OSTRING (VALUE: INTEGER) return STRING;
-- alias TO_OCTAL_STRING is TO_OSTRING [INTEGER return STRING];
-- function TO_HSTRING (VALUE: INTEGER) return STRING;
-- alias TO_HEX_STRING is TO_HSTRING [INTEGER return STRING];
-- alias TO_DSTRING is TO_STRING [INTEGER return STRING];
-- alias TO_DECIMAL_STRING is TO_STRING [INTEGER return STRING];
 
-- function TO_BSTRING (VALUE: universal_real) return STRING;
-- alias TO_BINARY_STRING is TO_BSTRING [universal_real return STRING];
-- function TO_OSTRING (VALUE: universal_real) return STRING;
-- alias TO_OCTAL_STRING is TO_OSTRING [universal_real return STRING];
-- function TO_HSTRING (VALUE: universal_real) return STRING;
-- alias TO_HEX_STRING is TO_HSTRING [universal_real return STRING];
-- alias TO_DSTRING is TO_STRING [universal_real return STRING];
-- alias TO_DECIMAL_STRING is TO_STRING [universal_real return STRING];
 
-- function TO_BSTRING (VALUE: REAL) return STRING;
-- alias TO_BINARY_STRING is TO_BSTRING [REAL return STRING];
-- function TO_OSTRING (VALUE: REAL) return STRING;
-- alias TO_OCTAL_STRING is TO_OSTRING [REAL return STRING];
-- function TO_HSTRING (VALUE: REAL) return STRING;
-- alias TO_HEX_STRING is TO_HSTRING [REAL return STRING];
-- alias TO_DSTRING is TO_STRING [REAL return STRING];
-- alias TO_DECIMAL_STRING is TO_STRING [REAL return STRING];

end package STANDARD;

16.4 Package TEXTIO

package TEXTIO is
[...]
-- Input routines for standard types:
[...]
alias BREAD is READ [LINE, BIT_VECTOR, BOOLEAN];
alias BREAD is READ [LINE, BIT_VECTOR];
procedure BREAD (L : inout LINE; VALUE : out INTEGER;
                 GOOD : out BOOLEAN);
procedure BREAD (L : inout LINE; VALUE : out INTEGER);
alias BINARY_READ is READ [LINE, BIT_VECTOR, BOOLEAN];
alias BINARY_READ is READ [LINE, BIT_VECTOR];
alias BINARY_READ is BREAD [LINE, INTEGER, BOOLEAN];
alias BINARY_READ is BREAD [LINE, INTEGER];
procedure OREAD (L: inout LINE; VALUE: out BIT_VECTOR;
                 GOOD: out BOOLEAN);
procedure OREAD (L: inout LINE; VALUE: out BIT_VECTOR);
procedure OREAD (L : inout LINE; VALUE : out INTEGER;
                 GOOD : out BOOLEAN);
procedure OREAD (L : inout LINE; VALUE : out INTEGER);
alias OCTAL_READ is OREAD [LINE, BIT_VECTOR, BOOLEAN];
alias OCTAL_READ is OREAD [LINE, BIT_VECTOR];
alias OCTAL_READ is OREAD [LINE, INTEGER, BOOLEAN];
alias OCTAL_READ is OREAD [LINE, INTEGER];

procedure HREAD (L: inout LINE; VALUE: out BIT_VECTOR;
                 GOOD: out BOOLEAN);
procedure HREAD (L: inout LINE; VALUE: out BIT_VECTOR);
procedure HREAD (L : inout LINE; VALUE : out INTEGER;
                 GOOD : out BOOLEAN);
procedure HREAD (L : inout LINE; VALUE : out INTEGER);
alias HEX_READ is HREAD [LINE, BIT_VECTOR, BOOLEAN];
alias HEX_READ is HREAD [LINE, BIT_VECTOR];
alias HEX_READ is HREAD [LINE, INTEGER, BOOLEAN];
alias HEX_READ is HREAD [LINE, INTEGER];

procedure DREAD (L : inout LINE; VALUE : out BIT_VECTOR;
                 GOOD : out BOOLEAN);
procedure DREAD (L : inout LINE; VALUE : out BIT_VECTOR);
alias DREAD is READ [LINE, INTEGER, BOOLEAN];
alias DREAD is READ [LINE, INTEGER];
alias DECIMAL_READ is DREAD [LINE, BIT_VECTOR, BOOLEAN];
alias DECIMAL_READ is DREAD [LINE, BIT_VECTOR];
alias DECIMAL_READ is READ [LINE, INTEGER, BOOLEAN];
alias DECIMAL_READ is READ [LINE, INTEGER];

-- Output routines for standard types:
[...]
alias BWRITE is WRITE [LINE, BIT_VECTOR, SIDE, WIDTH];
procedure BWRITE (L : inout LINE; VALUE : in INTEGER;
                  JUSTIFIED : in SIDE := right; FIELD : in WIDTH := 0);
alias BINARY_WRITE is WRITE [LINE, BIT_VECTOR, SIDE, WIDTH];
alias BINARY_WRITE is WRITE [LINE, INTEGER, SIDE, WIDTH];


procedure OWRITE (L: inout LINE; VALUE: in BIT_VECTOR;
                  JUSTIFIED: in SIDE := RIGHT; FIELD: in WIDTH := 0);
procedure OWRITE (L : inout LINE; VALUE : in INTEGER;
                  JUSTIFIED : in SIDE := right; FIELD : in WIDTH := 0);
alias OCTAL_WRITE is OWRITE [LINE, BIT_VECTOR, SIDE, WIDTH];
alias OCTAL_WRITE is OWRITE [LINE, INTEGER, SIDE, WIDTH];

procedure HWRITE (L: inout LINE; VALUE: in BIT_VECTOR;
                  JUSTIFIED: in SIDE := RIGHT; FIELD: in WIDTH := 0);
procedure HWRITE (L : inout LINE; VALUE : in INTEGER;
                  JUSTIFIED : in SIDE := right; FIELD : in WIDTH := 0);
alias HEX_WRITE is HWRITE [LINE, BIT_VECTOR, SIDE, WIDTH];
alias HEX_WRITE is HWRITE [LINE, INTEGER, SIDE, WIDTH];

procedure DWRITE (L : inout LINE; VALUE : in BIT_VECTOR;
                  JUSTIFIED : in SIDE := right; FIELD : in WIDTH := 0);
procedure DWRITE (L : inout LINE; VALUE : in INTEGER;
                  JUSTIFIED : in SIDE := right; FIELD : in WIDTH := 0);
alias DECIMAL_WRITE is DWRITE [LINE, BIT_VECTOR, SIDE, WIDTH];
alias DECIMAL_WRITE is DWRITE [LINE, INTEGER, SIDE, WIDTH];

end package TEXTIO;

5.2.6 Predefined operations on scalar types

Page 43 of the LRM
[...]
The function RISING_EDGE applied to a signal S of type BIT is TRUE if the expression “S'EVENT and S = '1'” is TRUE, and FALSE otherwise. The function FALLING_EDGE applied to a signal S of type BIT is TRUE if the expression “S'EVENT and S = '0'” is TRUE, and FALSE otherwise.

The following operation is implicitly declared in package STD.STANDARD at the end of the package declaration:

function TO_STRING (VALUE: universal_integer; FORMAT: STRING) return STRING;
function TO_STRING (VALUE: INTEGER; FORMAT: STRING) return STRING;


This overloaded TO_STRING operation returns the value of the VALUE parameter converted to a string whose format is specified by the value of the FORMAT parameter. The result type of the operation is the type STRING defined in package STANDARD.

The format of the result is determined using the value of the FORMAT parameter in the manner described in ISO/IEC 8859-1:1998, ISO/IEC 9899:1999/Cor 1:2001, and ISO/IEC 9899:1999/Cor 2:2004 for the C fprintf function. A model is erroneous if it calls the operation with a value for the FORMAT parameter that is other than a conversion specification in which the conversion specifier is one of d, i, u, x, X, or o. Moreover, the model is erroneous if the conversion specification contains a length modifier or uses an asterisk for the field width or precision.

The following operation is implicitly declared in package STD.STANDARD at the end of the package declaration:

function TO_STRING (VALUE: TIME; UNIT: TIME) return STRING;

This overloaded TO_STRING operation returns the string representation (see 5.7) of the value of its actual parameter. The result type of the operation is the type STRING defined in package STANDARD. The parameter UNIT specifies how the result is to be formatted. The value of this parameter shall be equal to one of the units declared as part of the declaration of type TIME; the result is that the TIME value is formatted as an integer or real literal representing the number of multiples of this unit, followed by the name of the unit itself.


The following operations are implicitly declared in package STD.STANDARD at the end of the package declaration:

function TO_STRING (VALUE: universal_real; DIGITS: NATURAL) return STRING;
function TO_STRING (VALUE: universal_real; FORMAT: STRING) return STRING;
function TO_STRING (VALUE: REAL; DIGITS: NATURAL) return STRING;
function TO_STRING (VALUE: REAL; FORMAT: STRING) return STRING;

These overloaded TO_STRING operations return the value of the VALUE parameter converted to a string whose format is specified by the value of the DIGITS or FORMAT parameter, respectively. The result type of the operations is the type STRING defined in package STANDARD.

For the operation with the DIGITS parameter, the result is the string representation of the value. The DIGITS specifies how many digits appear to the right of the decimal point. If DIGITS is 0, then the string representation is the same as that produced by the TO_STRING operation without the DIGITS or FORMAT parameter. If DIGITS is non-zero, then the string representation contains an integer part followed by '.' followed by the fractional part, using the specified number of digits, and no exponent (e.g., 3.14159).

For the operation with the FORMAT parameter, the format of the result is determined using the value of the FORMAT parameter in the manner described in ISO/IEC 8859-1:1998, ISO/IEC 9899:1999/Cor 1:2001, and ISO/IEC 9899:1999/Cor 2:2004 for the C fprintf function. A model is erroneous if it calls the operation with a value for the FORMAT parameter that is other than a conversion specification in which the conversion specifier is one of e, E, f, F, g, G, a, or A. Moreover, the model is erroneous if the conversion specification contains a length modifier or uses an asterisk for the field width or precision. An implementation shall support use of the conversion specifiers e, E, f, g, and G, and may additionally support use of the conversion specifiers F, a, and A. A model is erroneous if it calls the operation with a value for the FORMAT parameter that is a conversion specification in which the conversion specifier is one of F, a, or A and the implementation does not support use of the conversion specifier. The values of FLT_RADIX and DECIMAL_DIG (described in ISO/IEC 8859-1:1998, ISO/IEC 9899:1999/Cor 1:2001, and ISO/IEC 9899:1999/Cor 2:2004) are implementation defined.

The following operations are implicitly declared in package STD.STANDARD at the end of the package declaration:

alias TO_BSTRING is TO_STRING [universal_integer return STRING];
alias TO_BINARY_STRING is TO_STRING [universal_integer return STRING];
function TO_OSTRING (VALUE: universal_integer) return STRING;
alias TO_OCTAL_STRING is TO_OSTRING [universal_integer return STRING];
function TO_HSTRING (VALUE: universal_integer) return STRING;
alias TO_HEX_STRING is TO_HSTRING [universal_integer return STRING];
alias TO_DSTRING is TO_STRING [universal_integer return STRING];
alias TO_DECIMAL_STRING is TO_STRING [universal_integer return STRING];

alias TO_BSTRING is TO_STRING [INTEGER return STRING];
alias TO_BINARY_STRING is TO_STRING [INTEGER return STRING];
function TO_OSTRING (VALUE: INTEGER) return STRING;
alias TO_OCTAL_STRING is TO_OSTRING [INTEGER return STRING];
function TO_HSTRING (VALUE: INTEGER) return STRING;
alias TO_HEX_STRING is TO_HSTRING [INTEGER return STRING];
alias TO_DSTRING is TO_STRING [INTEGER return STRING];
alias TO_DECIMAL_STRING is TO_STRING [INTEGER return STRING];

These operations return strings that are the binary, octal, hexadecimal, and decimal, representations, respectively, of the parameters. For the TO_OSTRING operation, the result is an uppercase octal number corresponding to the representation of the parameter value. Similarly, for the TO_HSTRING operation, the result is an uppercase hexadecimal number corresponding to the representation of the parameter value. For the TO_DSTRING operation, the result is a decimal number corresponding to the representation of the parameter value.

The following operations are implicitly declared in package STD.STANDARD at the end of the package declaration:

alias TO_BSTRING is TO_STRING [universal_real return STRING];
alias TO_BINARY_STRING is TO_STRING [universal_real return STRING];
function TO_OSTRING (VALUE: universal_real) return STRING;
alias TO_OCTAL_STRING is TO_OSTRING [universal_real return STRING];
function TO_HSTRING (VALUE: universal_real) return STRING;
alias TO_HEX_STRING is TO_HSTRING [universal_real return STRING];
alias TO_DSTRING is TO_STRING [universal_real return STRING];
alias TO_DECIMAL_STRING is TO_STRING [universal_real return STRING];

alias TO_BSTRING is TO_STRING [REAL return STRING];
alias TO_BINARY_STRING is TO_STRING [REAL return STRING];
function TO_OSTRING (VALUE: REAL) return STRING;
alias TO_OCTAL_STRING is TO_OSTRING [REAL return STRING];
function TO_HSTRING (VALUE: REAL) return STRING;
alias TO_HEX_STRING is TO_HSTRING [REAL return STRING];
alias TO_DSTRING is TO_STRING [REAL return STRING];
alias TO_DECIMAL_STRING is TO_STRING [REAL return STRING];

These operations return strings that are the binary, octal, hexadecimal, and decimal, representations, respectively, of the parameters. For the TO_OSTRING operation, the result is an uppercase octal number corresponding to the representation of the parameter value. Similarly, for the TO_HSTRING operation, the result is an uppercase hexadecimal number corresponding to the representation of the parameter value. For the TO_DSTRING operation, the result is a decimal number corresponding to the representation of the parameter value.
[...]

5.3.2.4 Predefined operations on array types

Page 50 of the LRM
[...]

function TO_HSTRING (VALUE: BIT_VECTOR) return STRING;
alias TO_HEX_STRING is TO_HSTRING [BIT_VECTOR return STRING];
function TO_DSTRING (VALUE: BIT_VECTOR) return STRING;
alias TO_DECIMAL_STRING is TO_DSTRING [BIT_VECTOR return STRING];

These operations return strings that are the binary, octal, and hexadecimal, and decimal, representations, respectively, of the parameters. For the TO_OSTRING operation, the result has an uppercase octal digit corresponding to each group of three elements in the parameter value. If the length of the parameter value is not a multiple of three, then one or two '0' elements are implicitly concatenated on the left of the parameter value to yield a value that is a multiple of three in length. Similarly, for the TO_HSTRING operation, the result has an uppercase hexadecimal digit corresponding to each group of four elements in the parameter value. If the length of the parameter value is not a multiple of four, then one, two, or three '0' elements are implicitly concatenated on the left of the parameter value to yield a value that is a multiple of four in length. For the TO_DSTRING operation, the result is a decimal number corresponding to the unsigned representation of the parameter value.

G.4.8.5 Textio functions

Page 536 of the LRM

[...]

Hex_read Alias for hread.

Dwrite Decimal write. The pre- and post-binary-point parts of the number are written separately, with a binary point between them.

Dread Decimal read. The number read is interpreted as separate pre- and post-binary-point parts, with an optional binary point between them. If a “.” is found in the input string, then the index is checked to ensure that the binary point is in the correct place. It is an error if a "." is found in the input string and the VALUE parameter is of type INTEGER.

Decimal_write Alias for Dwrite.

Decimal_read Alias for Dread.

To_string Returns a string that can be padded and left or right justified, for example:

[...]

Style Notes

Changes are shown in red font.
Deletions are crossed out.
Editing or reviewing notes in green font.

Reviewing Notes

TODO

Details of Language Change

x.y.z General [For reviewers to follow the chain of EBNF rules.]

Comments

The function: 

function TO_INTEGER (ARG : STD_ULOGIC_VECTOR) return NATURAL;

is already in numeric_std_unsigned. See numeric_std_unsigned Id: D.1

-- Jim Lewis - 2017-03-05

Version 2 of this LCS implements the quick-fix of making TO_INTEGER local to the std_logic_1164. It also defines To_StdULogicVector to remove the use of to_unsigned in the DREAD procedures defined in std_logic_1164.

-- Pablo2 Blecua - 2017-03-08

@TODO Meeting 9-Mar-2017

  • Does not need aliases in std_logic_textio, but it is ok to be there
  • if To_xString for integer is implicit in std.standard, need corresponding text in LRM

-- Jim Lewis - 2017-03-09

Deleted the changes from std_logic_textio.

Regarding the to_Xstring for integers. I see three solutions:

  • We do not implement the to_Xstring functions in std.STANDARD and let the user write them themselves if needed (using the to_Xstring in numeric_std is very easy).
  • We implement in std.STANDARD to_hstring, to_ostring, to_bstring and to_dstring (the latter only for consistency since it should return the same as to_string). With the corresponding update of LRM 5.2.6
  • We implement in std.STANDARD "function TO_STRING (VALUE: INTEGER; FORMAT: STRING) return STRING;" And update the LRM 5.2.6 specifying that FORMAT can be: d, i, u, x, X, o. This is more in line with what is now provided for REAL but does not provide the functionality of to_bstring.

-- Pablo2 Blecua - 2017-03-10

I have implemented the 3rd solution that defines the new overloaded function: function TO_STRING (VALUE: INTEGER; FORMAT: STRING) return STRING

-- Pablo2 Blecua - 2017-03-12

To be consistent with other types, such as std_logic_vector, it would be nice to have to_hstring, to_ostring, and to_bstring. These can just call your to_string(..., FORMAT)

-- Jim Lewis - 2017-03-13

Comments from 3/21/2017 Meeting

  • to_integer, to_slv
    • Rob is not real comfortable with moving these but it is not a show stopper
    • in numeric_std_unsigned is missing the aliases to to_integer (to maintain backward compatibility)
    • Perhaps we can wait on moving to_integer
  • Rob does not like to_hstring for real. How is it defined to work, esp wrt the decimal point?

-- Jim Lewis - 2017-03-21

1.1) to_integer and to_sulv/to_slv are moved to std_logic_1164 because now they are used in there (due to the addition of TO_DSTRING and DREAD respectively). Since to_sulv was moved it made sense to move to_slv too. Now numeric_std_unsigned has no conversion functions. If it is decided not to move them and make a local version of to_integer and to_sulv in std_logic_1164 it can be done, but then there will be duplicated code.

1.2) I thought about the alias for to_integer in numeric_std_unsigned, but do we really need it? When using numeric_std_unsigned I think that std_logic_1164 must be used too, and therefore to_integer is visible (only that it is now in a different file). If that is not the case aliases can be quickly added.

1.3) It can be done both ways. My view is that it is "cleaner" to move them.

2.1) to_hstring (and to_ostring) for real are there to be consistent with what is in float_generic_pkg. I assumed that if for floats compliant to IEEE-754 these functions were offered they should also be there for real/universal_real. These functions return the "raw" hexadecimal value of the 32/64 bits representing the real number (as in float_generic_pkg). "For the TO_OSTRING operation, the result is an uppercase octal number corresponding to the representation of the parameter value. Similarly, for the TO_HSTRING operation, the result is an uppercase hexadecimal number corresponding to the representation of the parameter value." tried to say that but probably without success!.

2.2) Another option (at least for to_hstring) is to return the same as when calling to_STRING(..., FORMAT) with format being 'a' or 'A'.

2.3) Or they can just be removed.

-- Pablo2 Blecua - 2017-03-22

Edit | Attach | Print version | History: r21 < r20 < r19 < r18 < r17 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r21 - 2020-02-17 - 15:34:40 - JimLewis
 
Copyright © 2008-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback