Added comments of need for write and read FIFO. Added comments on flushing the write FIFO.

libraries/io/ddr/src/vhdl/io_ddr.vhd

@@ -78,7 +78,7 @@
 --                     |________| |      |______|<--\  | driver|  .  |      |
 --                                |                 |  |       |  .  |      |
 --                                | ctlr_wr_flush_en|  |       |  .  |      |
---                                |       ______    |  |       |  .  |      |
+--           ctlr_wr_fifo_src_out |       ______    |  |       |  .  |      |
 --                                \----->|io_ddr|---/  |       |  .  |      |
 --   dvr_clk ------------>               |driver|      |       |  .  |      |<--- phy_in
 --   dvr_wr_flush_en ----*-------------->|flush |      |       |---->|      |---> phy_ou
@@ -106,16 +106,38 @@
 -- . If the dvr_clk=ctlr_clk then the clock domain crossing logic defaults
 --   to wires. However dvr_clk could also be the dp_clk or the mm_clk and then 
 --   the clock domain crossing logic is needed.
---   No need to cross dvr_start_address, because the address is stable when the
---   dvr_en is stable.
 -- . Externally connect ctlr_clk = ctlr_clk_in = ctlr_clk_out
 -- . Typically wr_clk = rd_clk = dp_clk.
--- . To achieve maximum DDR access rate the g_wr_data_w and g_rd_data_w typically
---   already need to be equal to the c_ctlr_data_w, because the DP clk for wr_clk
---   and rd_clk can typically not run much faster than the ctlr_clk. Therefore in
---   practise the mixed width FIFO will often be used as equal width FIFO.
+-- . To achieve maximum DDR access rate the g_wr_data_w and g_rd_data_w
+--   typically already need to be equal to the c_ctlr_data_w, because the
+--   DP clk for wr_clk and rd_clk can typically not run much faster than the
+--   ctlr_clk. Therefore in practise the mixed width FIFO will often be used
+--   as equal width FIFO.
 -- . The main PHY signals are carried by phy_ou and phy_io. The phy_in signals
 --   are typically not needed.
+-- . If ctlr_clk is used as dp_clk and connected to wr_clk, rd_clk and dvr_clk
+--   then still the io_ddr_driver and a equal width rd FIFO are needed. The rd
+--   FIFO is needed because the DDR controller does not have flow control
+--   during the read burst. The wr FIFO is not needed provide that the user
+--   write source does support flow control. If the user write source does not
+--   support flow control then the wr FIFO is needed and io_ddr needs to be
+--   used.
+-- . The flushing does ensure that the write FIFO does not run full. If the
+--   write input FIFO is a mixed width FIFO with narrow write data, then it
+--   may not be possible to read the FIFO empty, because a wide data word
+--   can only be read when it is complete. Typically this behaviour is fine
+--   in applications, so no need to try to somehow flush an incomplete last
+--   wide word from the FIFO.
+-- . The flush control uses ctlr_wr_fifo_src_out and not the wr_sosi, because 
+--   dp_flush needs to be at the read side of the FIFO.
+-- . The dvr_wr_flush_en is mapped to the dvr_mosi.flush in the
+--   t_mem_ctlr_mosi. This is a bit awkward, because flush is not an Avalon
+--   MM interface signal. However some external control needs to decide on
+--   the need to flush or not, because that cannot be decided internally? An
+--   option could be to automatically trigger a flush event when the write
+--   FIFO runs almost full as indicated by wr_siso.ready. This scheme would
+--   require that there is never a need to flush as long as the FIFO has not
+--   run full.
         
 LIBRARY IEEE, technology_lib, tech_ddr_lib, common_lib, dp_lib;
 USE IEEE.STD_LOGIC_1164.ALL;

libraries/io/ddr/src/vhdl/io_ddr_driver_flush_ctrl.vhd

@@ -22,8 +22,9 @@
 
 -- Purpose: Flush the write input FIFO in io_ddr when not doing a write access.
 -- Description:
---   The write input FIFO is flushed by when the io_ddr is not doing a write
---   access, so when idle or also when doing a read access.
+--   The write input FIFO is flushed when the io_ddr is not doing a write
+--   access, so when idle or also when doing a read access. The flushing
+--   ensures that the FIFO does not run full.
 --   When the io_ddr is starting a new write access, then the write input FIFO
 --   gets filled. The filling starts dependent on:
 --
@@ -33,13 +34,6 @@
 --
 --   . g_use_channel = TRUE : start filling when channel matches g_start_channel
 --
---  Remarks:
---  . The flushing does ensure that the write FIFO does not run full. If the
---    write input FIFO is a mixed width FIFO with narrow write data, then it
---    may not be possible to read the FIFO empty, because a wide data word
---    can only be read when it is complete. Typically this behaviour is fine
---    in applications, so no need to try to somehow flush an incomplete last
---    wide word from the FIFO.
 
 LIBRARY IEEE, common_lib, dp_lib;
 USE IEEE.STD_LOGIC_1164.ALL;