Improved description.

libraries/base/dp/src/vhdl/dp_xonoff.vhd

@@ -21,20 +21,34 @@
 
 -- Purpose: Add flow XON-XOFF control by flushing frames
 -- Description:
---   The dp_xonoff can be applied when the upstream source keeps on producing
---   blocks of data, because it does not listen to the in_siso.xon = '0'. The
---   purpose of dp_xonoff.vhd is then to avoid downstream overflow, when the
---   downstream signals out_siso.xon = '0' to indicate that it cannot accept
---   more blocks. Therefore the dp_xonoff listens to the out_siso.xon and
---   flushes (discards) blocks when out_siso.xon = '0'. The dp_xonoff operates
---   per block, so it takes care that complete blocks are flushed when
---   out_siso.xon = '0', or passed on when out_siso.xon = '1'. The
---   in_siso.xon = '1' always, because the dp_xonoff will discard incoming
---   blocks if they cannot be passed on. When out_siso.xon = '1', then
---   in_siso.ready <= in_sosi.ready, so passed on. When out_siso.xon = '0',
---   then in_siso.xon = '1' and in_siso.ready <= '1' (so in_siso =
---   c_dp_sosi.rdy), because dp_xonoff can flush incoming blocks at maximum
---   rate, until out_siso.xon = '1' again.
+--   The siso.xon signal provides flow control per block of data, so at
+--   sop/eop boundaries. A source that listens to siso.xon can stop streaming
+--   blocks when siso.xon = '0' and resume streaming blocks when siso.xon =
+--   '1'. The siso.ready signal provides flow control per clock cycle. Hence
+--   the siso.ready can also cause a source to stop streaming.
+--
+--   If a source keeps on streaming blocks of data, becaue it does not listen
+--   to siso.xon and also not to siso.ready, then the dp_xonoff can be applied
+--   to drop the blocks when siso.xon = '0'. The purpose of dp_xonoff.vhd is
+--   then to avoid downstream overflow, when the downstream signals
+--   out_siso.xon = '0' to indicate that it cannot accept more blocks.
+--   Therefore the dp_xonoff listens to the out_siso.xon and flushes
+--   (discards) blocks when out_siso.xon = '0' and resumes letting blocks
+--   through when siso.xon = '1' again.
+--
+--   The dp_xonoff operates per block, so it takes care that complete blocks
+--   are flushed when out_siso.xon = '0', or passed on when out_siso.xon =
+--   '1'. Discarding blocks is acceptable to avoid overflow. Discarding data
+--   in a block is not acceptable, because that would corrupt the block
+--   format (e.g. its length, or cause missing sop or eop). Therefore the
+--   dp_xonoff uses siso.xon and does not listen to siso.ready.
+--
+--   The dp_xonoff in_siso.xon = '1' always, because the dp_xonoff will
+--   discard incoming blocks if they cannot be passed on. When out_siso.xon
+--   = '1', then in_siso.ready <= in_sosi.ready, so passed on. When
+--   out_siso.xon = '0', then in_siso.xon = '1' and in_siso.ready <= '1'
+--   (so in_siso = c_dp_sosi.rdy), because dp_xonoff can flush incoming
+--   blocks at maximum rate, until out_siso.xon = '1' again.
 --
 --   A dp_fifo will keep on outputing blocks when its out_siso.xon = '0',
 --   because it only passes in_siso.xon <= out_siso.xon, so it relies on its