Subversion Repositories astron_mm

-------------------------------------------------------------------------------

--

-- Copyright 2020

-- ASTRON (Netherlands Institute for Radio Astronomy) <http://www.astron.nl/>

-- P.O.Box 2, 7990 AA Dwingeloo, The Netherlands

-- 

-- Licensed under the Apache License, Version 2.0 (the "License");

-- you may not use this file except in compliance with the License.

-- You may obtain a copy of the License at

-- 

--     http://www.apache.org/licenses/LICENSE-2.0

-- 

-- Unless required by applicable law or agreed to in writing, software

-- distributed under the License is distributed on an "AS IS" BASIS,

-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

-- See the License for the specific language governing permissions and

-- limitations under the License.

--

-------------------------------------------------------------------------------

-- Author :

--   D. van der Schuur  May 2012  Original for Python - file IO - VHDL 

--   E. Kooistra        feb 2017  Added purpose and description

--                                Added procedures for external control in a

--                                pure VHDL test bench.

--

-- Purpose: Provide DUT access via MM bus through file IO per MM slave

-- Description:

--   This package provides file IO access to MM slaves and to the status of

--   the simulation:

--

-- 1) MM slave access

--   Access to MM slaves is provided by component mm_file.vhd that first calls

--   mmf_file_create() and loop forever calling mmf_mm_from_file(). Each MM

--   slave has a dedicated pair of request (.ctrl) and response (.stat) IO

--   files.

--   The mmf_file_create() creates the .ctrl file and mmf_mm_from_file() reads

--   it to check whether there is a WR or RD access request. For a WR request

--   the wr_data and wr_addr are read from the .ctrl and output on the MM bus

--   via mm_mosi. For a RD access request the rd_addr is read from the .ctrl

--   and output on the MM bus via mm_mosi. The after the read latency the

--   rd_data is written to the .stat file that is then created and closed.

--

--                    wr             rd  _________               __________

--   mmf_mm_bus_wr() ---> ctrl file --->|         |---mm_mosi-->|          |

--                                      | mm_file |             | MM slave |

--   mmf_mm_bus_rd() <--- stat file <---|___\_____|<--mm_miso---|__________|

--                    rd             wr      \

--                                            \--> loop: mmf_mm_from_file()

--

--   The ctrl file is created by mm_file at initialization and recreated by

--   every call of mmf_mm_from_file().

--   The stat file is recreated by every call of mmf_mm_bus_rd().

--

-- 2) Simulator access

--   External access to the simulation is provided via a .ctrl file that

--   supports GET_SIM_TIME and then report the NOW time via the .stat file.

--   The simulation access is provided via a procedure mmf_poll_sim_ctrl_file()

--   that works similar component mm_file.vhd.

--

--                      wr             rd

--                    |---> ctrl file --->|

--   mmf_sim_get_now()|                   |mmf_poll_sim_ctrl_file()

--                    |<--- stat file <---|  \

--                      rd             wr     \

--                                             \--> loop: mmf_sim_ctrl_from_file()

--

--   The ctrl file is created by mmf_poll_sim_ctrl_file at initialization and

--   recreated by every call of mmf_sim_ctrl_from_file().

--   The stat file is recreated by every call of mmf_sim_get_now().

--

-- A) External control by a Python script

--   A Python script can issue requests via the .ctrl files to control the

--   simulation and read the .stat files. This models the MM access via a

--   Monitoring and Control protocol via 1GbE.

--

--   Internal procedures:

--   . mmf_file_create(filename: IN STRING);

--   . mmf_mm_from_file(SIGNAL mm_clk  : IN STD_LOGIC; 

--   . mmf_sim_ctrl_from_file(rd_filename: IN STRING;

--   

--   External procedures (used in a VHDL design to provide access to the MM

--   slaves and simulation via file IO):

--   . mm_file.vhd --> instead of a procedure MM slave file IO uses a component

--   . mmf_poll_sim_ctrl_file()

--   

-- B) External control by a VHDL process --> see tb_mm_file.vhd

--   Instead of a Python script the file IO access to the MM slaves can also

--   be used in a pure VHDL testbench. This is useful when the MM slave bus

--   signals (mm_mosi, mm_miso) are not available on the entity of the DUT

--   (device under test), which is typically the case when a complete FPGA

--   design needs to be simulated.

--

--   Internal procedures:

--   . mmf_wait_for_file_status()

--   . mmf_wait_for_file_empty()

--   . mmf_wait_for_file_not_empty()

--                                      

--   External procedures (used in a VHDL test bench to provide access to the 

--   MM slaves in a DUT VHDL design and simulation via file IO):

--   . mmf_mm_bus_wr()

--   . mmf_mm_bus_rd()

--   . mmf_sim_get_now()

--

--   External function to create unique sim.ctrl/sim.stat filename per test bench in a multi tb

--   . mmf_slave_prefix()

--

-- Remarks:

-- . The timing of the MM access in mmf_mm_bus_wr() and mmf_mm_bus_rd() and the

--   simulation access in mmf_sim_get_now() is not critical. The timing of the first

--   access depends on the tb. Due to falling_edge(mm_clk) in mmf_wait_for_file_*()

--   all subsequent accesses will start at falling_edge(mm_clk)

LIBRARY IEEE, common_pkg_lib, common_ram_lib;

USE IEEE.STD_LOGIC_1164.ALL;

USE IEEE.NUMERIC_STD.ALL;

USE common_pkg_lib.common_pkg.ALL;

USE common_pkg_lib.tb_common_pkg.ALL;

USE common_ram_lib.common_ram_pkg.ALL;

USE work.tb_common_mem_pkg.ALL;

USE std.textio.ALL;

USE IEEE.std_logic_textio.ALL;

USE common_pkg_lib.common_str_pkg.ALL;

PACKAGE mm_file_pkg IS

  -- Constants used by mm_file.vhd

  CONSTANT c_mmf_mm_clk_period : TIME :=  100 ps;  -- Default mm_clk period in simulation. Set much faster than DP clock to speed up

                                                   -- simulation of MM access. Without file IO throttling 100 ps is a good balance

                                                   -- between simulation speed and file IO rate.

  CONSTANT c_mmf_mm_timeout    : TIME := 1000 ns;  -- Default MM file IO timeout period. Set large enough to account for MM-DP clock

                                                   -- domain crossing delays. Use 0 ns to disable file IO throttling, to have file IO

                                                   -- at the mm_clk rate.

  CONSTANT c_mmf_mm_pause      : TIME :=  100 ns;  -- Default MM file IO pause period after timeout. Balance between file IO rate

                                                   -- reduction and responsiveness to new MM access.

  -- Procedure to (re)create empty file

  PROCEDURE mmf_file_create(filename: IN STRING);

  -- Procedure to perform an MM access from file

  PROCEDURE mmf_mm_from_file(SIGNAL mm_clk  : IN STD_LOGIC;

                             SIGNAL mm_rst  : IN STD_LOGIC;

                             SIGNAL mm_mosi : OUT t_mem_mosi;

                             SIGNAL mm_miso : IN  t_mem_miso;

                             rd_filename: IN STRING;

                             wr_filename: IN STRING;

                             rd_latency: IN NATURAL);

  -- Procedure to process a simulation status request from the .ctrl file and provide response via the .stat file

  PROCEDURE mmf_sim_ctrl_from_file(rd_filename: IN STRING;

                                   wr_filename: IN STRING);

  -- Procedure to poll the simulation status

  PROCEDURE mmf_poll_sim_ctrl_file(rd_file_name: IN STRING;

                                   wr_file_name: IN STRING);

  -- Procedure to poll the simulation status

  PROCEDURE mmf_poll_sim_ctrl_file(SIGNAL mm_clk  : IN STD_LOGIC;

                                   rd_file_name: IN STRING;

                                   wr_file_name: IN STRING);

  -- Procedures that keep reading the file until it has been made empty or not empty by some other program,

  -- to ensure the file is ready for a new write access

  PROCEDURE mmf_wait_for_file_status(rd_filename   : IN STRING;  -- file name with extension

                                     exit_on_empty : IN BOOLEAN;

                                     SIGNAL mm_clk : IN STD_LOGIC);

  PROCEDURE mmf_wait_for_file_empty(rd_filename   : IN STRING;  -- file name with extension

                                    SIGNAL mm_clk : IN STD_LOGIC);

  PROCEDURE mmf_wait_for_file_not_empty(rd_filename   : IN STRING;  -- file name with extension

                                        SIGNAL mm_clk : IN STD_LOGIC);

  -- Procedure to issue a write access via the MM request .ctrl file  

  PROCEDURE mmf_mm_bus_wr(filename      : IN STRING;   -- file name without extension

                          wr_addr       : IN INTEGER;  -- use integer to support full 32 bit range

                          wr_data       : IN INTEGER;

                          SIGNAL mm_clk : IN STD_LOGIC);

  -- Procedure to issue a read access via the MM request .ctrl file and get the read data from the MM response file

  PROCEDURE mmf_mm_bus_rd(filename       : IN STRING;   -- file name without extension

                          rd_latency     : IN NATURAL;

                          rd_addr        : IN INTEGER;  -- use integer to support full 32 bit range

                          SIGNAL rd_data : OUT STD_LOGIC_VECTOR(c_word_w-1 DOWNTO 0);

                          SIGNAL mm_clk  : IN STD_LOGIC);

  -- . rd_latency = 1

  PROCEDURE mmf_mm_bus_rd(filename       : IN STRING;

                          rd_addr        : IN INTEGER;

                          SIGNAL rd_data : OUT STD_LOGIC_VECTOR(c_word_w-1 DOWNTO 0);

                          SIGNAL mm_clk  : IN STD_LOGIC);

  -- Procedure that reads the rd_data every rd_interval until has the specified rd_value, the proc arguments can be understood as a sentence

  PROCEDURE mmf_mm_wait_until_value(filename         : IN STRING;   -- file name without extension

                                    rd_addr          : IN INTEGER;

                                    c_representation : IN STRING;  -- treat rd_data as "SIGNED" or "UNSIGNED" 32 bit word

                                    SIGNAL rd_data   : INOUT STD_LOGIC_VECTOR(c_word_w-1 DOWNTO 0);

                                    c_condition      : IN STRING;  -- ">", ">=", "=", "<=", "<", "/="

                                    c_rd_value       : IN INTEGER;

                                    c_rd_interval    : IN TIME;

                                    SIGNAL mm_clk    : IN STD_LOGIC);

  -- Procedure to get NOW via simulator status

  PROCEDURE mmf_sim_get_now(filename       : IN STRING;   -- file name without extension

                            SIGNAL rd_now  : OUT STRING;

                            SIGNAL mm_clk  : IN STD_LOGIC);

  -- Functions to create prefixes for the mmf file filename

  FUNCTION mmf_prefix(name : STRING; index : NATURAL) RETURN STRING;  -- generic prefix name with index to be used for a file IO filename

  FUNCTION mmf_tb_prefix(tb : INTEGER) RETURN STRING;                 -- fixed test bench prefix with index tb to allow file IO with multi tb

  FUNCTION mmf_subrack_prefix(subrack : INTEGER) RETURN STRING;       -- fixed subrack prefix with index subrack to allow file IO with multi subracks that use same unb numbers

  -- Functions to create mmf file prefix that is unique per slave, for increasing number of hierarchy levels:

  -- . return "filepath/s0_i0_"

  -- . return "filepath/s0_i0_s1_i1_"

  -- . return "filepath/s0_i0_s1_i1_s2_i2_"

  -- . return "filepath/s0_i0_s1_i1_s2_i2_s3_i3_"

  -- . return "filepath/s0_i0_s1_i1_s2_i2_s3_i3_s4_i4_"

  FUNCTION mmf_slave_prefix(dir_path, s0 : STRING; i0 : NATURAL) RETURN STRING;

  FUNCTION mmf_slave_prefix(dir_path, s0 : STRING; i0 : NATURAL; s1 : STRING; i1 : NATURAL) RETURN STRING;

  FUNCTION mmf_slave_prefix(dir_path, s0 : STRING; i0 : NATURAL; s1 : STRING; i1 : NATURAL; s2 : STRING; i2 : NATURAL) RETURN STRING;

  FUNCTION mmf_slave_prefix(dir_path, s0 : STRING; i0 : NATURAL; s1 : STRING; i1 : NATURAL; s2 : STRING; i2 : NATURAL; s3 : STRING; i3 : NATURAL) RETURN STRING;

  FUNCTION mmf_slave_prefix(dir_path, s0 : STRING; i0 : NATURAL; s1 : STRING; i1 : NATURAL; s2 : STRING; i2 : NATURAL; s3 : STRING; i3 : NATURAL; s4 : STRING; i4 : NATURAL) RETURN STRING;

  CONSTANT c_mmf_local_dir_path : STRING := "mmfiles/";   -- local directory in project file build directory

  FUNCTION mmf_slave_prefix(s0 : STRING; i0 : NATURAL) RETURN STRING;

  FUNCTION mmf_slave_prefix(s0 : STRING; i0 : NATURAL; s1 : STRING; i1 : NATURAL) RETURN STRING;

  FUNCTION mmf_slave_prefix(s0 : STRING; i0 : NATURAL; s1 : STRING; i1 : NATURAL; s2 : STRING; i2 : NATURAL) RETURN STRING;

  FUNCTION mmf_slave_prefix(s0 : STRING; i0 : NATURAL; s1 : STRING; i1 : NATURAL; s2 : STRING; i2 : NATURAL; s3 : STRING; i3 : NATURAL) RETURN STRING;

  FUNCTION mmf_slave_prefix(s0 : STRING; i0 : NATURAL; s1 : STRING; i1 : NATURAL; s2 : STRING; i2 : NATURAL; s3 : STRING; i3 : NATURAL; s4 : STRING; i4 : NATURAL) RETURN STRING;

  ----------------------------------------------------------------------------

  -- Declare mm_file component to support positional generic and port mapping of many instances in a TB

  ----------------------------------------------------------------------------

  COMPONENT mm_file

  GENERIC(

    g_file_prefix       : STRING;

    g_file_enable       : STD_LOGIC := '1';

    g_mm_rd_latency     : NATURAL := 2;

    g_mm_timeout        : TIME := c_mmf_mm_timeout;

    g_mm_pause          : TIME := c_mmf_mm_pause

  );

  PORT (

    mm_rst        : IN  STD_LOGIC;

    mm_clk        : IN  STD_LOGIC;

    mm_master_out : OUT t_mem_mosi;

    mm_master_in  : IN  t_mem_miso

  );

  END COMPONENT;

END mm_file_pkg;

PACKAGE BODY mm_file_pkg IS

  PROCEDURE mmf_file_create(filename: IN STRING) IS

    FILE created_file : TEXT OPEN write_mode IS filename;

  BEGIN

    -- Write the file with nothing in it

    write(created_file, "");

  END;

  PROCEDURE mmf_mm_from_file(SIGNAL mm_clk : IN STD_LOGIC;

                             SIGNAL mm_rst : IN STD_LOGIC;

                             SIGNAL mm_mosi : OUT t_mem_mosi;

                             SIGNAL mm_miso : IN  t_mem_miso;

                             rd_filename: IN STRING;

                             wr_filename: IN STRING;

                             rd_latency: IN NATURAL) IS

    FILE rd_file : TEXT;

    FILE wr_file : TEXT;

    VARIABLE open_status_rd: file_open_status;

    VARIABLE open_status_wr: file_open_status;

    VARIABLE rd_line : LINE;

    VARIABLE wr_line : LINE;

    -- Note: Both the address and the data are interpreted as 32-bit data!

    -- This means one has to use leading zeros in the file when either is

    -- less than 8 hex characters, e.g.:

    -- (address) 0000000A

    -- (data)    DEADBEEF

    -- ...as a hex address 'A' would fit in only 4 bits, causing an error in hread().

    VARIABLE v_addr_slv : STD_LOGIC_VECTOR(c_word_w-1 DOWNTO 0);

    VARIABLE v_data_slv : STD_LOGIC_VECTOR(c_word_w-1 DOWNTO 0);

    VARIABLE v_rd_wr_str : STRING(1 TO 2); -- Contains 'RD' or 'WR'

  BEGIN

    proc_common_wait_until_low(mm_clk, mm_rst);

    -- We have to open the file explicitely so we can check the status

    file_open(open_status_rd, rd_file, rd_filename, read_mode);

    -- open_status may throw an error if the file is being written to by some other program

    IF open_status_rd=open_ok THEN

      IF NOT endfile(rd_file) THEN

        -- The file is not empty: process its contents

        -- Read a line from it, first line indicates RD or WR

        readline(rd_file, rd_line);

        read(rd_line, v_rd_wr_str);

        -- The second line represents the address offset:

        readline(rd_file, rd_line);

        hread(rd_line, v_addr_slv);  -- read the string as HEX and assign to SLV.

        -- Write only: The third line contains the data to write:

        IF v_rd_wr_str="WR" THEN

          readline(rd_file, rd_line);

          hread(rd_line, v_data_slv);  -- read the string as HEX and assign to SLV.

        END IF;

        -- We're done reading MM request from the .ctrl file.

        -- Clear the .ctrl file by closing and recreating it, because we don't want to do the same

        -- MM request again the next time this procedure is called.

        file_close(rd_file);

        mmf_file_create(rd_filename);

        -- Execute the MM request to the MM slave

        IF v_rd_wr_str="WR" THEN

          print_str("[" & time_to_str(now) & "] " & rd_filename & ": Writing 0x" & slv_to_hex(v_data_slv) & " to address 0x" & slv_to_hex(v_addr_slv));

          -- Treat 32 bit hex data from file as 32 bit VHDL INTEGER, so need to use signed TO_SINT() to avoid out of NATURAL range

          -- warning in simulation due to '1' sign bit, because unsigned VHDL NATURAL only fits 31 bits

          proc_mem_mm_bus_wr(TO_UINT(v_addr_slv), TO_SINT(v_data_slv), mm_clk, mm_miso, mm_mosi);

        ELSIF v_rd_wr_str="RD" THEN

          proc_mem_mm_bus_rd(TO_UINT(v_addr_slv), mm_clk, mm_miso, mm_mosi);

          IF rd_latency>0 THEN

            proc_mem_mm_bus_rd_latency(rd_latency, mm_clk);

          END IF;

          v_data_slv := mm_miso.rddata(31 DOWNTO 0);

          print_str("[" & time_to_str(now) & "] " & rd_filename & ": Reading from address 0x" & slv_to_hex(v_addr_slv) & ": 0x" & slv_to_hex(v_data_slv));

          -- Write the RD response read data to the .stat file

          file_open(open_status_wr, wr_file, wr_filename, write_mode);

          hwrite(wr_line, v_data_slv);

          writeline(wr_file, wr_line);

          file_close(wr_file);

        END IF;

      ELSE

        -- Nothing to process; wait one MM clock cycle.

        proc_common_wait_some_cycles(mm_clk, 1);

      END IF;

    ELSE

      REPORT "mmf_mm_from_file() could not open " & rd_filename & " at " & time_to_str(now) SEVERITY NOTE;

      -- Try again next time; wait one MM clock cycle.

      proc_common_wait_some_cycles(mm_clk, 1);

    END IF;

    -- The END implicitely close the rd_file, if still necessary.

  END;

  PROCEDURE mmf_sim_ctrl_from_file(rd_filename: IN STRING;

                                   wr_filename: IN STRING) IS

    FILE rd_file : TEXT;

    FILE wr_file : TEXT;

    VARIABLE open_status_rd: file_open_status;

    VARIABLE open_status_wr: file_open_status;

    VARIABLE rd_line : LINE;

    VARIABLE wr_line : LINE;

    VARIABLE v_rd_wr_str : STRING(1 TO 12); -- "GET_SIM_TIME"

  BEGIN

    -- We have to open the file explicitely so we can check the status

    file_open(open_status_rd, rd_file, rd_filename, read_mode);

    -- open_status may throw an error if the file is being written to by some other program

    IF open_status_rd=open_ok THEN

      IF NOT endfile(rd_file) THEN

        -- The file is not empty: process its contents

        -- Read a line from it, interpret the simulation request

        readline(rd_file, rd_line);

        read(rd_line, v_rd_wr_str);

        -- We're done reading this simulation request .ctrl file. Clear the file by closing and recreating it.

        file_close(rd_file);

        mmf_file_create(rd_filename);

        -- Execute the simulation request

        IF v_rd_wr_str="GET_SIM_TIME" THEN

          -- Write the GET_SIM_TIME response time NOW to the .stat file

          file_open(open_status_wr, wr_file, wr_filename, write_mode);

          write(wr_line, time_to_str(now));

          writeline(wr_file, wr_line);

          file_close(wr_file);

        END IF;

      ELSE

        -- Nothing to process; wait in procedure mmf_poll_sim_ctrl_file

        NULL;

      END IF;

    ELSE

      REPORT "mmf_mm_from_file() could not open " & rd_filename & " at " & time_to_str(now) SEVERITY NOTE;

      -- Try again next time; wait in procedure mmf_poll_sim_ctrl_file

    END IF;

    -- The END implicitely close the rd_file, if still necessary.

  END;

  PROCEDURE mmf_poll_sim_ctrl_file(rd_file_name: IN STRING; wr_file_name : IN STRING) IS

  BEGIN

    -- Create the ctrl file that we're going to read from

    print_str("[" & time_to_str(now) & "] " & rd_file_name & ": Created" );

    mmf_file_create(rd_file_name);

    WHILE TRUE LOOP

      mmf_sim_ctrl_from_file(rd_file_name, wr_file_name);

      WAIT FOR 1 ns;

    END LOOP;

  END;

  PROCEDURE mmf_poll_sim_ctrl_file(SIGNAL mm_clk  : IN STD_LOGIC;

                                   rd_file_name: IN STRING; wr_file_name : IN STRING) IS

  BEGIN

    -- Create the ctrl file that we're going to read from

    print_str("[" & time_to_str(now) & "] " & rd_file_name & ": Created" );

    mmf_file_create(rd_file_name);

    WHILE TRUE LOOP

      mmf_sim_ctrl_from_file(rd_file_name, wr_file_name);

      proc_common_wait_some_cycles(mm_clk, 1);

    END LOOP;

  END;

  PROCEDURE mmf_wait_for_file_status(rd_filename   : IN STRING;  -- file name with extension

                                     exit_on_empty : IN BOOLEAN;

                                     SIGNAL mm_clk : IN STD_LOGIC) IS

    FILE     rd_file        : TEXT;

    VARIABLE open_status_rd : file_open_status;

    VARIABLE v_endfile      : BOOLEAN;

  BEGIN

    -- Check on falling_edge(mm_clk) because mmf_mm_from_file() operates on rising_edge(mm_clk)

    -- Note: In fact the file IO also works fine when rising_edge() is used, but then

    --       tb_tb_mm_file.vhd takes about 1% more mm_clk cycles

    WAIT UNTIL falling_edge(mm_clk);

    -- Keep reading the file until it has become empty by some other program

    WHILE TRUE LOOP

      -- Open the file in read mode to check whether it is empty

      file_open(open_status_rd, rd_file, rd_filename, read_mode);

      -- open_status may throw an error if the file is being written to by some other program

      IF open_status_rd=open_ok THEN

        v_endfile := endfile(rd_file);

        file_close(rd_file);

        IF exit_on_empty THEN

          IF v_endfile THEN

            -- The file is empty; continue

            EXIT;

          ELSE

            -- The file is not empty; wait one MM clock cycle.

            WAIT UNTIL falling_edge(mm_clk);

          END IF;

        ELSE

          IF v_endfile THEN

            -- The file is empty; wait one MM clock cycle.

            WAIT UNTIL falling_edge(mm_clk);

          ELSE

            -- The file is not empty; continue

            EXIT;

          END IF;

        END IF;

      ELSE

        REPORT "mmf_wait_for_file_status() could not open " & rd_filename & " at " & time_to_str(now) SEVERITY NOTE;

        WAIT UNTIL falling_edge(mm_clk);

      END IF;

    END LOOP;

    -- The END implicitely close the file, if still necessary.

  END;

  PROCEDURE mmf_wait_for_file_empty(rd_filename   : IN STRING;  -- file name with extension

                                    SIGNAL mm_clk : IN STD_LOGIC) IS

  BEGIN

    mmf_wait_for_file_status(rd_filename, TRUE, mm_clk);

  END;

  PROCEDURE mmf_wait_for_file_not_empty(rd_filename   : IN STRING;  -- file name with extension

                                        SIGNAL mm_clk : IN STD_LOGIC) IS

  BEGIN

    mmf_wait_for_file_status(rd_filename, FALSE, mm_clk);

  END;

  PROCEDURE mmf_mm_bus_wr(filename      : IN STRING;   -- file name without extension

                          wr_addr       : IN INTEGER;  -- use integer to support full 32 bit range

                          wr_data       : IN INTEGER;

                          SIGNAL mm_clk : IN STD_LOGIC) IS

    CONSTANT ctrl_filename  : STRING := filename & ".ctrl";

    FILE     ctrl_file      : TEXT;

    VARIABLE open_status_wr : file_open_status;

    VARIABLE wr_line        : LINE;

  BEGIN

    -- Write MM WR access to the .ctrl file.

    -- The MM device is ready for a new MM request, because any previous MM request has finished at

    -- mmf_mm_bus_wr() or mmf_mm_bus_rd() procedure exit, therefore just overwrite the .ctrl file.

    file_open(open_status_wr, ctrl_file, ctrl_filename, write_mode);

    -- open_status may throw an error if the file is being written to by some other program

    IF open_status_wr=open_ok THEN

      write(wr_line, STRING'("WR"));

      writeline(ctrl_file, wr_line);

      hwrite(wr_line, TO_SVEC(wr_addr, c_word_w));

      writeline(ctrl_file, wr_line);

      hwrite(wr_line, TO_SVEC(wr_data, c_word_w));

      writeline(ctrl_file, wr_line);

      file_close(ctrl_file);

    ELSE

      REPORT "mmf_mm_bus_wr() could not open " & ctrl_filename & " at " & time_to_str(now) SEVERITY NOTE;

    END IF;

    -- Prepare for next MM request

    -- Keep reading the .ctrl file until it is empty, to ensure that the MM device is ready for a new MM request

    mmf_wait_for_file_empty(ctrl_filename, mm_clk);

    -- The END implicitely close the ctrl_file, if still necessary.

  END;

  PROCEDURE mmf_mm_bus_rd(filename       : IN STRING;   -- file name without extension

                          rd_latency     : IN NATURAL;

                          rd_addr        : IN INTEGER;  -- use integer to support full 32 bit range

                          SIGNAL rd_data : OUT STD_LOGIC_VECTOR(c_word_w-1 DOWNTO 0);

                          SIGNAL mm_clk  : IN STD_LOGIC) IS

    CONSTANT ctrl_filename  : STRING := filename & ".ctrl";

    CONSTANT stat_filename  : STRING := filename & ".stat";

    FILE     ctrl_file      : TEXT;

    FILE     stat_file      : TEXT;

    VARIABLE open_status_wr : file_open_status;

    VARIABLE open_status_rd : file_open_status;

    VARIABLE wr_line        : LINE;

    VARIABLE rd_line        : LINE;

    VARIABLE v_rd_data      : STD_LOGIC_VECTOR(c_word_w-1 DOWNTO 0);

  BEGIN

    -- Clear the .stat file by recreating it, because we don't want to do read old file data again

    mmf_file_create(stat_filename);

    -- Write MM RD access to the .ctrl file.

    -- The MM device is ready for a new MM request, because any previous MM request has finished at

    -- mmf_mm_bus_wr() or mmf_mm_bus_rd() procedure exit, therefore just overwrite the .ctrl file.

    file_open(open_status_wr, ctrl_file, ctrl_filename, write_mode);

    -- open_status may throw an error if the file is being written to by some other program

    IF open_status_wr=open_ok THEN

      write(wr_line, STRING'("RD"));

      writeline(ctrl_file, wr_line);

      hwrite(wr_line, TO_SVEC(rd_addr, c_word_w));

      writeline(ctrl_file, wr_line);

      file_close(ctrl_file);

    ELSE

      REPORT "mmf_mm_bus_rd() could not open " & ctrl_filename & " at " & time_to_str(now) SEVERITY FAILURE;

    END IF;

    -- Wait until the MM RD access has written the read data to the .stat file

    mmf_wait_for_file_not_empty(stat_filename, mm_clk);

    -- Read the MM RD access read data from the .stat file

    file_open(open_status_rd, stat_file, stat_filename, read_mode);

    -- open_status may throw an error if the file is being written to by some other program

    IF open_status_rd=open_ok THEN

      readline(stat_file, rd_line);

      hread(rd_line, v_rd_data);

      file_close(stat_file);

      rd_data <= v_rd_data;

      -- wait to ensure rd_data has got v_rd_data, otherwise rd_data still holds the old data on procedure exit

      -- the wait should be < mm_clk period/2 to not affect the read rate

      WAIT FOR 1 fs;

    ELSE

      REPORT "mmf_mm_bus_rd() could not open " & stat_filename & " at " & time_to_str(now) SEVERITY FAILURE;

    END IF;

    -- No need to prepare for next MM request, because:

    -- . the .ctrl file must already be empty because the .stat file was there

    -- . the .stat file will be cleared on this procedure entry

    -- The END implicitely closes the files, if still necessary

  END;

  -- rd_latency = 1

  PROCEDURE mmf_mm_bus_rd(filename       : IN STRING;

                          rd_addr        : IN INTEGER;

                          SIGNAL rd_data : OUT STD_LOGIC_VECTOR(c_word_w-1 DOWNTO 0);

                          SIGNAL mm_clk  : IN STD_LOGIC) IS

  BEGIN

    mmf_mm_bus_rd(filename, 1, rd_addr, rd_data, mm_clk);

  END;

  PROCEDURE mmf_mm_wait_until_value(filename         : IN STRING;   -- file name without extension

                                    rd_addr          : IN INTEGER;

                                    c_representation : IN STRING;  -- treat rd_data as "SIGNED" or "UNSIGNED" 32 bit word

                                    SIGNAL rd_data   : INOUT STD_LOGIC_VECTOR(c_word_w-1 DOWNTO 0);

                                    c_condition      : IN STRING;  -- ">", ">=", "=", "<=", "<", "/="

                                    c_rd_value       : IN INTEGER;

                                    c_rd_interval    : IN TIME;

                                    SIGNAL mm_clk    : IN STD_LOGIC) IS

  BEGIN

    WHILE TRUE LOOP

      -- Read current 

      mmf_mm_bus_rd(filename, rd_addr, rd_data, mm_clk);  -- only read low part

      IF c_representation="SIGNED" THEN

        IF    c_condition=">"  THEN IF TO_SINT(rd_data)> c_rd_value THEN EXIT; ELSE WAIT FOR c_rd_interval; END IF;

        ELSIF c_condition=">=" THEN IF TO_SINT(rd_data)>=c_rd_value THEN EXIT; ELSE WAIT FOR c_rd_interval; END IF;

        ELSIF c_condition="/=" THEN IF TO_SINT(rd_data)/=c_rd_value THEN EXIT; ELSE WAIT FOR c_rd_interval; END IF;

        ELSIF c_condition="<=" THEN IF TO_SINT(rd_data)<=c_rd_value THEN EXIT; ELSE WAIT FOR c_rd_interval; END IF;

        ELSIF c_condition="<"  THEN IF TO_SINT(rd_data)< c_rd_value THEN EXIT; ELSE WAIT FOR c_rd_interval; END IF;

        ELSE                        IF TO_SINT(rd_data) =c_rd_value THEN EXIT; ELSE WAIT FOR c_rd_interval; END IF;  -- default: "="

        END IF;

      ELSE  -- default: UNSIGED

        IF    c_condition=">"  THEN IF TO_UINT(rd_data)> c_rd_value THEN EXIT; ELSE WAIT FOR c_rd_interval; END IF;

        ELSIF c_condition=">=" THEN IF TO_UINT(rd_data)>=c_rd_value THEN EXIT; ELSE WAIT FOR c_rd_interval; END IF;

        ELSIF c_condition="/=" THEN IF TO_UINT(rd_data)/=c_rd_value THEN EXIT; ELSE WAIT FOR c_rd_interval; END IF;

        ELSIF c_condition="<=" THEN IF TO_UINT(rd_data)<=c_rd_value THEN EXIT; ELSE WAIT FOR c_rd_interval; END IF;

        ELSIF c_condition="<"  THEN IF TO_UINT(rd_data)< c_rd_value THEN EXIT; ELSE WAIT FOR c_rd_interval; END IF;

        ELSE                        IF TO_UINT(rd_data) =c_rd_value THEN EXIT; ELSE WAIT FOR c_rd_interval; END IF;  -- default: "="

        END IF;

      END IF;

    END LOOP;

  END mmf_mm_wait_until_value;

  PROCEDURE mmf_sim_get_now(filename       : IN STRING;   -- file name without extension

                            SIGNAL rd_now  : OUT STRING;

                            SIGNAL mm_clk  : IN STD_LOGIC) IS

    CONSTANT ctrl_filename  : STRING := filename & ".ctrl";

    CONSTANT stat_filename  : STRING := filename & ".stat";

    FILE     ctrl_file      : TEXT;

    FILE     stat_file      : TEXT;

    VARIABLE open_status_wr : file_open_status;

    VARIABLE open_status_rd : file_open_status;

    VARIABLE wr_line        : LINE;

    VARIABLE rd_line        : LINE;

    VARIABLE v_rd_now       : STRING(rd_now'RANGE);