VHDL Reference Guide - File Declaration

**File** Declaration

Declaration	---- used in ---->	Package Process Architecture Procedure Function

Syntax

file logical_name : file_type is mode "file_name";

See LRM sections 3.4, 4.3.2 and 14.3

Rules and Examples

Usually, files of type text are used as they are portable between different VHDL simulators. The mode of the file refers to the direction of data flow, and may be either in (i.e. a read-only file) or out (a write-only file):

use std.textio.all;
package REF_PACK is
  file INFILE : text is in  "in.dat";
  file OUTFILE: text is out "out.dat";
end REF_PACK;

Text files may be read by using the endfile, readline and read subprograms defined in the package std.textio:

READ_FILE: process
  variable VEC_LINE : line;
  variable VEC_VAR : bit_vector(0 to 7);
  file VEC_FILE : text is in "stim.vec";
begin
  while not endfile(VEC_FILE) loop
    readline (VEC_FILE, VEC_LINE);
    read (VEC_LINE, VEC_VAR);
    A_BUS <= VEC_VAR;
    wait for 10 ns;
  end loop;
  wait;
end process READ_FILE;

The textio package must be made visible by the clause:

use std.textio.all;

Text files may be written by using the write and writeln subprograms, also defined in the textio package. Output data may be formatted using optional parameters for write - see the LRM section 14.3

Textio read and write procedures are defined for the types bit, bit_vector, bolean, character, integer, real, string and time. They are not compatible with user-defined types or std_logic_1164 types (although some vendors supply routines for the std_logic_1164_types).

Text files may be written by using the writeln and write subprograms defined in the package std.textio

WRITE_FILE: process (CLK)
  variable VEC_LINE : line;
  file VEC_FILE : text is out "results";
begin
  -- strobe OUT_DATA on falling edges 
  -- of CLK and write value out to file
  if CLK='0' then
    write (VEC_LINE, OUT_DATA);
    writeline (VEC_FILE, VEC_LINE);
  end if;
end process WRITE_FILE;

A file (read or write) is opened in VHDL when the structure in which it is declared is elaborated. This means that files declared in processes or architectures are opened only once at the beginning of a simulation. files declared in procedures are reopened at the beginning of the file every time the procedure is elaborated (every time it is executed) and are closed every time the procedure finishes execution.

Synthesis Issues

File declarations and operations are not supported by logic synthesis tools.

Whats New in '93

VHDL-93 allows files to be explicitly opened and closed during simulation - this was not directly supported in VHDL-87. Consequently, file declarations are not upwards-compatible between VHDL-87 and VHDL-93. For instance, in VHDL-93 the equivalent declaration to the example above would be:

file MYTEXT : text open read_mode is "enum.txt";

The new attributes 'image and 'value make textio for enumerated types much easier - see attributes