IEEE 200X Fast Track Change Proposal

ID:	  FT-08

Proposer:     Jim Lewis (jim@synthworks.com)
              Updated: David Bishop (dbishop@vhdl.org)

Status:       Open
Proposed:     7-April-2003
Updated:      18-Feb-2005
Analyzed:     Date
Resolved:     Date

Enhancement Summary:     
    Add impure functions NL and sim_resolution
    Add tee
    Add sread for reading tokens (non-space to whitespace)
    Add swrite for writing strings.
    Add hwrite, owrite, bwrite, hread, oread, bread 
    for bit_vector.


Related issues:          See std_logic_1164 discussions
Relevant LRM section:    


Enhancement Detail:
----------------------------
String NL is intended to represent NL in an operating 
system appropriate way.  For Windows it will be CR & LF and
for Unix it will be CR.  This string has been added to the package
"std.standard", so that it will be globally visible.
"Sim_resolution" is function in std.standard which provides the
simulation resolution.

The tee procedure writes to output file specified as well as
echoing the data to OUTPUT.

The procedure sread reads a token.  Skips leading white space.
Reads characters until white space or end  of line are reached.
Returns the string and the strlen.  If a bad read is made, the
"strlen" will return a 0.

Swrite is for printing strings (so you don't need the type 
qualifier).

hwrite, owrite, bwrite, hread, oread, bread are
formatted IO for bit_vector.

The package std_logic_textio was donated to the std_logic_1164 
effort.  This proposal is intended to provide for bit_vector
and integer what is in (or proposed to be in) the updated
std_logic_textio.  The contents of "std_logic_textio" have
been moved into "std_logic_1164" and the original "std_logic_textio"
package was left empty to preserve its name space.

1)  For hwrite and owrite if the array argument
does not provide enough bits to fill a character, 
fill the extra bits with 0.  For example, if printing
in hex and the value only has 21 bits, treat the value
as if the upper three bits are 0.  

  variable addr : std_logic_vector(20 downto 0) ;
  . . .
  hwrite(WB, addr) ;

if Addr = 1 0000 0000 0101 1010 1111
then printed value = 1005AF

  -- without this enhancement, one would need to write:
  hwrite(WB, "000" & addr) ; 

2) For hread and oread read sufficient characters (digits)
to fill the array, and if there are extra zero bits throw them 
away.  If any extra bits are non-zero, then error.  

Example, if we do a hex read into a 5-element vector and 
read 1F, we get three extra 0 bits, and no error.  On the 
other hand, if we read 3F, we get 001 as extra bits 
and generate an error.

This means to read a 21 bit hex address, I can simply

hread(RB, addr) ;

Otherwise to get the same meaning, I need to:
variable addr_temp : std_logic_vector(23 downto 0) ;

hread(RB, addr_temp) ;
addr <= addr_temp(addr'range) ; 

From 2005/01/10 discussion:
Modify working in LRM for "read" to specify what is to be returned
and the error message that is to be issues when a bad read occurs.

Analysis:
----------------------------
Add the following procedures to std.textio:

package standard_prototyle is
    impure function NL return string;   -- OS dependent constant to be CRLF
    impure function sim_resolution return DELAY_LENGTH;   -- Simulator resolution

end package standard_prototyle;

use STD.textio.all;

package std_textio_prototype is

    procedure tee (file F : text ; L : inout line)  ; 

    -- Read and Write procedures for String values 
    procedure SREAD (L: inout LINE;  VALUE: out STRING; STRLEN: out natural);

    alias swrite is write [line, string, side, width] ;

    -- Read and Write procedures for Hexadecimal values
    procedure HREAD (L: inout LINE;  VALUE: out BIT_VECTOR;  GOOD : out BOOLEAN);
    procedure HREAD (L: inout LINE;  VALUE: out BIT_VECTOR);

    procedure HWRITE (L: inout LINE;  VALUE: in BIT_VECTOR;
                      JUSTIFIED: in SIDE := RIGHT;  FIELD:in WIDTH := 0);

    -- Read and Write procedures for Octal values
    procedure OREAD (L: inout LINE;  VALUE: out BIT_VECTOR;  GOOD : out BOOLEAN);
    procedure OREAD (L: inout LINE;  VALUE: out BIT_VECTOR);

    procedure OWRITE (L: inout LINE;  VALUE: in BIT_VECTOR;
                      JUSTIFIED: in SIDE := RIGHT;  FIELD:in WIDTH := 0);

    -- Read and Write procedures for Binary values
  alias BREAD is READ [LINE, BIT_VECTOR, BOOLEAN];
  alias BREAD is READ [LINE, BIT_VECTOR];
  alias BWRITE is WRITE [LINE, BIT_VECTOR, SIDE, WIDTH];


end std_textio_prototype ;




Resolution:
----------------------------
[To be performed by the 200X Fast Track Working Group]