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  Initial

--   E. Kooistra       Jan 2018  Removed unused generics and added remarks.

-- Purpose: Provide access to an MM slave via file IO

-- Description:

--   See mm_file_pkg.

--

-- * Optional MM file IO throttle via g_mm_timeout, g_mm_pause:

--   Default g_mm_timeout=0 ns for full speed MM file IO rate. Optional use

--   g_mm_timeout>0 ns to throttle MM file IO rate. The mm_master_out wr and

--   rd strobes are monitored. As long as a strobe occurs within

--   g_mm_timeout then the MM file IO operates at full speed. When no strobe

--   occurs within g_mm_timeout, then a delay of g_mm_pause is inserted

--   until the next MM file IO access will be done. This throttling reduces

--   the file IO rate when the MM slave is idle and picks up again at full

--   speed when MM slave accesses appear again.

--

--   The g_mm_timeout is in ns, and not defined in number of mm_clk cycles,

--   to make it independent of the simulation mm_clk period. This is

--   important to be able to handle clock domain crossings between a fast

--   simulation mm_clk and a relatively slow internal dp_clk. If the

--   g_mm_timeout is too short then it will occur for every MM access that

--   needs a MM-DP clock domain crossing. A dp_clk typically runs at

--   about 100 or 200 MHz, so period < about 10 ns. A clock domain crossing

--   takes about 25 clock cycles in both clock domains (see

--   common_reg_cross_domain.vhd). Hence a suitable default value for 

--   g_mm_timeout is about 250 ns. With some margin use 1000 ns. 

--   The g_mm_pause is defined in ns, but could as well have been defined

--   in number mm_clk cycle. Use g_mm_pause default 100 ns to have a factor

--   1000 reduction in file IO rate witk c_mmf_mm_clk_period = 100 ps, while

--   not introducing too much delay in case a new MM access is pending.

--

-- Remarks:

-- * Positional mapping of generics and port:

--   If necessary new generics or ports should be added after the existing

--   generics or ports, because then existing mm_file instances that use 

--   positional mapping instead of explicit name mapping (with =>) still 

--   compile ok.

--

-- * Default g_mm_rd_latency=2:

--   The default g_mm_rd_latency=2 to fit both MM reg (which typically have rd

--   latency 1) and MM ram (for which some have rd latency 2). This works

--   because the mm_master_out.rd strobes have gaps. The maximum rd strobe 

--   rate appears to be 1 strobe in every 4 cycles. By using default 

--   g_mm_rd_latency=2 the mm_file instances do not explicitly have to map the

--   actual MM slave rd latency, because using 2 fits all. This ensures 

--   that all existing mm_file instances that do not map g_mm_rd_latency still

--   work and for new mm_file instances it avoids the need to know whether the

--   MM slave actually has rd latency 1 or 2.

--

-- * Default g_file_enable='1':

--   Default the mm_file instance will open the files. However if the MM slave

--   will not be used in a test, then it can be good to use g_file_enable='0'

--   to avoid these files. For multi tb or tb with many mm_file instances this 

--   limits the number of file handlers and may help to improve the simulation

--   speed (and stability).

--

LIBRARY IEEE, common_pkg_lib, astron_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 astron_ram_lib.common_ram_pkg.ALL;

USE work.tb_common_mem_pkg.ALL;

USE common_pkg_lib.common_str_pkg.ALL;

USE work.mm_file_pkg.ALL;

USE IEEE.std_logic_textio.ALL;

USE std.textio.ALL;

ENTITY mm_file IS

  GENERIC (

    g_file_prefix       : STRING;            -- e.g. "ppsh" will create i/o files ppsh_stat.txt and ppsh_ctrl.txt

    g_file_enable       : STD_LOGIC := '1';  -- default use '1' to enable file IO, use '0' to disable file IO and force mm_master_out to c_mem_mosi_rst

    g_mm_rd_latency     : NATURAL := 2;      -- default use 2 to fit 0, 1 or 2, must be >= read latency of the MM slave

    g_mm_timeout        : TIME := c_mmf_mm_timeout;  -- use 0 ns for full speed MM, use > 0 ns to define time without MM access after which the MM file IO is paused

    g_mm_pause          : TIME := c_mmf_mm_pause     -- defines time for which MM file IO is paused to reduce the file IO rate when the MM slave is idle

  );

  PORT (

    mm_rst        : IN  STD_LOGIC;

    mm_clk        : IN  STD_LOGIC;

    mm_master_out : OUT t_mem_mosi := c_mem_mosi_rst;

    mm_master_in  : IN  t_mem_miso := c_mem_miso_rst

  );

END mm_file;

ARCHITECTURE str OF mm_file IS

  CONSTANT c_rd_file_name : STRING :=  g_file_prefix & ".ctrl";

  CONSTANT c_wr_file_name : STRING :=  g_file_prefix & ".stat";

  SIGNAL i_mm_master_out : t_mem_mosi;

  -- Optional file IO throttle control

  SIGNAL strobe          : STD_LOGIC;

  SIGNAL pause           : STD_LOGIC;

  SIGNAL polling         : STD_LOGIC := '0';  -- monitor signal to view in Wave window when mmf_mm_from_file() is busy

  SIGNAL timebegin       : TIME := 0 ns;

  SIGNAL timeout         : TIME := 0 ns;

BEGIN

  mm_master_out <= i_mm_master_out;

  no_file : IF g_file_enable='0' GENERATE

    i_mm_master_out <= c_mem_mosi_rst;

  END GENERATE;

  gen_file : IF g_file_enable='1' GENERATE

    p_file_to_mm : PROCESS

    BEGIN

      i_mm_master_out <= c_mem_mosi_rst;

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

      print_str("[" & time_to_str(NOW) & "] " & c_rd_file_name & ": Created" );

      mmf_file_create(c_rd_file_name);

      WHILE TRUE LOOP

        mmf_mm_from_file(mm_clk, mm_rst, i_mm_master_out, mm_master_in, c_rd_file_name, c_wr_file_name, g_mm_rd_latency);

        -- Optional file IO throttle control

        IF g_mm_timeout>0 ns AND pause='1' THEN

          polling <= '0';

          WAIT FOR g_mm_pause;  -- Pause the file IO when MM timeout is enabled and no strobes appeared for g_mm_timeout

          proc_common_wait_some_cycles(mm_clk, 1);  -- Realign to mm_clk, not needed but done to resemble return from mmf_mm_from_file()

          polling <= '1';

        END IF;

      END LOOP;

      WAIT;

    END PROCESS;

    -- Optional file IO throttle control

    gen_mm_timeout_control : IF g_mm_timeout>0 ns GENERATE

      strobe <= i_mm_master_out.wr OR i_mm_master_out.rd;  -- detect MM access

      pause <= NOT strobe WHEN timeout>g_mm_timeout ELSE '0';  -- issue MM file IO pause after strobe timeout

      -- Use mm_clk event to update time based on NOW, without event it does not update

      p_mm_now : PROCESS(mm_rst, mm_clk)

      BEGIN

        IF mm_rst='1' THEN

          -- during reset no timeouts

          timebegin <= NOW;

          timeout <= 0 ns;

        ELSE

          -- use MM access to restart timeout

          IF strobe='1' THEN

            timebegin <= NOW;

          END IF;

          timeout <= NOW - timebegin;

        END IF;

      END PROCESS;

    END GENERATE;

  END GENERATE;

END str;