Improved comments.

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

@@ -42,22 +42,28 @@
 --   g_wr_flush_mode.
 --
 -- Usage:
--- . The dvr interface could be connected to a MM interface. The DDR memory
+-- . The dvr interface could be connected to a MM register. The DDR memory
 --   may then be used to capture (large) blocks of streaming data that can
 --   offline be read via a DP-MM interface (eg. like in bn_capture). During
 --   the read access the streaming write data then is flushed.
--- . The dvr interface could be connected to signals from a DP interface. For
---   write access the dvr_en could connect to the wr_sosi.sop and the
---   dvr_nof_data then equals the nof data from sop to eop. The dvr_done can
---   be treated as wr_siso.xon. The dvr_wr_not_rd selects between the write
---   stream to DDR access or the read stream from DDR access. For a read
---   access    or to a DP
---   interface
---   The dvr_en could be connected to a DP sop 
-
 --
--- Block diagram:
+-- . The dvr interface could be connected to a DP sequencer that can write
+--   blocks to DDR and read back from DDR. The DP sequencer uses signals
+--   from its input DP interface. For write access the dvr_en could relate
+--   to teh sop and the dvr_nof_data then equals the nof data from sop to eop.
+--   The dvr_done can be treated as xon. The dvr_wr_not_rd selects between
+--   the write stream to DDR access or the read stream from DDR access. For a
+--   read access the sequencer needs to generate the dvr signals itself.
+--
+-- . The dvr interface is mapped on the t_mem_ctlr_mosi/miso interface:
+--     dvr_miso.done     <= dvr_done              -- Requested wr or rd sequence is done
+--     dvr_en            <= dvr_mosi.burstbegin
+--     dvr_wr_not_rd     <= dvr_mosi.wr           -- No need to use dvr_mosi.rd
+--     dvr_start_address <= dvr_mosi.address
+--     dvr_nof_data      <= dvr_mosi.burstsize
+--     dvr_wr_flush_en   <= dvr_mosi.flush
 --
+-- Block diagram:
 --
 --                          ctlr_wr_fifo_src      ctlr_wr_snk   ctlr_mosi
 --                      ________      .   ______    .   _______   .   ______
@@ -90,15 +96,7 @@
 --            \------ctlr_clk_out-----------------------------------------------/
 --
 --     * = clock domain crossing between dvr_clk and ctlr_clk clock domains.
---
---   The dvr interface is mapped also on the t_mem_ctlr_mosi/miso interface:
---     dvr_miso.done     <= dvr_done;             -- Requested wr or rd sequence is done
---     dvr_en            <= dvr_mosi.burstbegin;
---     dvr_wr_not_rd     <= dvr_mosi.wr;          -- No need to use dvr_mosi.rd
---     dvr_start_address <= dvr_mosi.address(c_ctlr_address_w-1 DOWNTO 0);
---     dvr_nof_data      <= dvr_mosi.burstsize(c_ctlr_address_w-1 DOWNTO 0);
---     dvr_wr_flush_en   <= dvr_mosi.flush
---
+----
 -- Remarks:
 -- . 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 
@@ -107,6 +105,10 @@
 --   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.
 -- . The main PHY signals are carried by phy_ou and phy_io. The phy_in signals
 --   are typically not needed.
         
@@ -125,7 +127,7 @@ ENTITY io_ddr IS
     g_tech_ddr                : t_c_tech_ddr;
     g_cross_domain_dvr_ctlr   : BOOLEAN := TRUE;
     g_wr_data_w               : NATURAL := 32;  
-    g_wr_fifo_depth           : NATURAL := 128;     -- >=16 AND >g_tech_ddr.maxburstsize, defined at DDR side of the FIFO.
+    g_wr_fifo_depth           : NATURAL := 128;     -- >=16                             , defined at DDR side of the FIFO.
     g_rd_fifo_depth           : NATURAL := 256;     -- >=16 AND >g_tech_ddr.maxburstsize, defined at DDR side of the FIFO. 
     g_rd_data_w               : NATURAL := 32;
     g_wr_flush_mode           : STRING := "VAL";  -- "VAL", "SOP", "SYN"

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

@@ -104,7 +104,7 @@ BEGIN
   p_reg : PROCESS(rst, clk)
   BEGIN
     IF rst='1' THEN
-      state <= s_flush;
+      state <= s_flush;           -- default start in flush mode after power up
     ELSIF rising_edge(clk) THEN
       state <= nxt_state;
     END IF;