ECE 368 CAD-Based Logic Design Shantanu Dutt Lecture 11 File I/O and Textio in VHDL (courtesy of Karam Chatha, ASU)

Files In all the testbenches we created so far, the test stimuli were coded inside each testbench. Hence, if we need to change the test stimuli we need to modify the model or create a new model. Input and output files can be used to get around this problem.

File Definition and Declaration file_type_defn <= type file_type_name is file of type_mark ; A file class needs to be defined before it can be used. Once defined, a file object can be declared. type integer _file is file of integer ; file_decl <= file id {, …} : subtype_indication [ [ open file_open_kind ] is string_expr ; file table: integer _file open read_mode is “table.dat” ; type file_open_kind is (read_mode, write_mode, append_mode);

File reading Given a file definition, VHDL implicitly provides the following subprograms: type file_type is file of element_type; procedure read ( file f: file_type; value : out element_type; length : out natural); function endfile ( file f: file_type ) return boolean; If the length of the element is greater than the length of the actual data on the file, it is placed left justified in the element.

Example p1: process is type bit_vector_file is file of bit_vectors; file vectors: bit_vector_file open read_mode is “vec.dat”; variable next_vector : bit_vector (63 downto 0); variable actual_len: natural; begin while not endfile(vectors) loop read (vectors,next_vector,actual_len); if actual_len > next_vector’length then report “vector too long”; else for bit_index in 1 to actual_len loop …. end loop; end if; end loop; wait; end process;

File writing Given a file definition, VHDL implicitly provides the following subprograms: type file_type is file of element_type; procedure write ( file f: file_type; value : in element_type);

Problem Description Write a process description that writes the data of integer type from an input signal to a file. Assume that the input signal “s1” is an “in” port of the top level entity. Assume the file name to be “out.dat”.

Example P1: process (s1) is type integer_file is file of integer; file out_file: integer_file open write_mode is “out.dat”; begin write (out_file,s1); end;

Files in Subprograms In all the examples of file I/O thus far, files are opened at the start of simulation, and automatically closed at end of simulation. However, for files declared in subprograms, files are opened and closed at each invocation of the subprogram.

Example function read_array (file_name: string; len: natural) return integer_vector is type integer_file is file of integer; file data_file: integer_file open read_mode is file_name; variable result: integer_vector(1 to len); variable index: integer := 1; begin while not endfile(data_file) and index <= len loop read(data_file, result(index)); index:= index + 1; end loop; return result; end;

File open and close In the examples discussed thus far: we have opened the files at definition. we have implicitly closed the files. VHDL permits explicit opening and closing of files.

File open and close procedure file_open (status : out file_open_status; file f: file_type; extern_name: in string; open_kind : in file_open_mode := read_mode); type file_open_status is (open_ok, status_error, name_error, mode_error); VHDL provides two implicit procedures: procedure file_close (file f: file_type);

Open errors status_error: file object previously open and associated with a physical file. name_error: in read mode indicates file does not exist. in write mode indicates file cannot be created. in append mode indicates both. mode_error: indicates file cannot be opened in the specified mode.

File procedure parameters procedure read_transform (file f: transform_file; variable transform : out transform_array) is begin for i in transform’range(1) loop for j in transform’range(2) loop if endfile(f) then report “unexpected end of file” severity error; return end if; read (f,transform(i,j)); end loop; end; VHDL does not permit reading or writing of 2-D arrays.

Package textio The file that we have created can read only one type of objects. The package textio provides useful functions for reading general text files. The package is part of the standard library “std”.

Package textio type line is access string; type text is file of string; type side is (right,left); subtype width is natural; file input: text open read_mode is “std_input”; file output: text open write_mode is “std_output”; procedure readline (file f: text; L: inout line); procedure writeline (file f: text; L: inout line);

Using textio procedures The type “access” denotes a pointer in VHDL. textio works with a pointer to a line of text or string. A pointer is an object that has the starting address of the line of text. Pointer String “readline” and “writeline” read and write an entire string that is pointed to by the pointer.

textio read procedures procedure read (L : inout line; value: out bit; good: out boolean); procedure read (L : inout line; value: out bit_vector; good: out boolean); procedure read (L : inout line; value: out boolean; good: out boolean); procedure read (L : inout line; value: out character; good: out boolean); procedure read (L : inout line; value: out integer; good: out boolean); procedure read (L : inout line; value: out real; good: out boolean); procedure read (L : inout line; value: out string; good: out boolean); procedure read (L : inout line; value: out time; good: out boolean);

textio read operation Every read operation that reads a data type other than “character” skips whitespace (ws) characters: Space, Tab. Reading a character does not skip ws chars since they are legitimate characters; if they need to be skipped, then that does need to be done explicitly at the point of the ws character w/ a read: read(L,c), where “c” is of type character. If the line contains the following items: fred “cat” a 10 ns readline(file_id,L); read (L,s); -- L is a string, s is a string read (L,s); read (L,bv); -- bv is a bit_vector read (L,i); -- i is an integer read (L,r); -- r is a real read (L,c); read(L,c); -- c is a character read (L,t); -- t is a time

textio write procedures procedure write (L : inout line; value: in bit; justified: in side := right; field: in width := 0); procedure write (L : inout line; value: in bit_vector; justified: in side := right; field: in width := 0); procedure write (L : inout line; value: in boolean; justified: in side := right; field: in width := 0); procedure write (L : inout line; value: in character; justified: in side := right; field: in width := 0); procedure write (L : inout line; value: in integer; justified: in side := right; field: in width := 0); procedure write (L : inout line; value: in real; justified: in side := right; field: in width := 0); procedure write (L : inout line; value: in string; justified: in side := right; field: in width := 0); procedure write (L : inout line; value: in time; justified: in side := right; field: in width; unit: in time:= ns);

textio write operation write (L,i,left,5); -- L is a line, i = 45 write (L,’ ‘); write (L,i,right,5); write (L,’ ‘); write (L,”fred”); write (L,’ ‘); write (L,”101”); write (L,’ ‘); write (L,r,left,3); -- r = write (L,’ ‘); write (L,t,left,0,ms); -- t = 23 micro secs writeline(file_id,L); 45bbb bbb45 fred ms