-Added more comments.

libraries/dsp/carousel_correlator/src/vhdl/permutator.vhd

@@ -28,8 +28,18 @@ USE dp_lib.dp_stream_pkg.ALL;
 -- Purpose:
 -- . Outputs all unique pair permutations of the words at the inputs.
 -- Description:
--- . Example permutations of [0,1,2]: [[0,0],[0,1],[0,2],[1,2],[1,1],[2,2]]
 -- . c_nof_permutations = g_nof_inputs*(g_nof_inputs+1)/2
+-- . Example permutations of [0,1,2]: [[0,0],[0,1],[0,2],[1,1],[1,2],[2,2]]
+--   . Note the order of the permutations; low pairs to high pairs
+-- . All inputs to permutate (snk_in_arr) must be valid on one and the same clock cycle.
+-- . Process p_permu_wires is wires only and provides all permutations
+--   instantaniously, in parallel:
+--   . Low pair  [snk_in_arr[0],             snk_in_arr[0]             ] on permu_out_2arr[0]
+--   . ..
+--   . ..
+--   . High pair [snk_in_arr[g_nof_inputs-1],snk_in_arr[g_nof_inputs-1]] on permu_out_2arr[g_nof_inputs-1]
+-- . The output of process p_permu_wires is wired to the desired g_nof_outputs. The parallel permutations
+--   shown above will be serialized if they do not fit across g_nof_outputs (see 'usage' below').
 -- Usage:
 -- . Determine g_nof_inputs; e.g. 3 
 -- . Calculate c_nof_permutations: e.g. 6
@@ -40,18 +50,17 @@ USE dp_lib.dp_stream_pkg.ALL;
 --     . 1 cycle  * 6 outputs
 -- . Set your g_nof_outputs accordingly.
 
-
 ENTITY permutator IS
   GENERIC (
     g_nof_inputs  : NATURAL := 8;
     g_nof_outputs : NATURAL := 9
   ); 
   PORT (
-    rst         : IN  STD_LOGIC;
-    clk         : IN  STD_LOGIC;
+    rst          : IN  STD_LOGIC;
+    clk          : IN  STD_LOGIC;
 
-    snk_in_arr  : IN  t_dp_sosi_arr(g_nof_inputs-1 DOWNTO 0);
-    snk_out_arr : OUT t_dp_siso_arr(g_nof_inputs-1 DOWNTO 0) := (OTHERS=>c_dp_siso_rdy);
+    snk_in_arr   : IN  t_dp_sosi_arr(g_nof_inputs-1 DOWNTO 0);
+    snk_out_arr  : OUT t_dp_siso_arr(g_nof_inputs-1 DOWNTO 0) := (OTHERS=>c_dp_siso_rdy);
 
     src_out_2arr : OUT t_dp_sosi_2arr_2(g_nof_outputs-1 DOWNTO 0) -- Array of pairs
   );
@@ -130,19 +139,21 @@ BEGIN
     VARIABLE v_out_index  : NATURAL;
     VARIABLE v_duplicates : NATURAL;
   BEGIN
-    v_out_index := 0;
+    v_out_index  := 0;
     v_duplicates := 0;
     FOR i IN 0 TO g_nof_inputs-1 LOOP
       v_duplicates := i;
       FOR j IN 0 TO g_nof_inputs-1 LOOP
+        -- Wire up our permutation pair by using inverse indices (j,i) and (i,j) 
         permu_out_2arr(v_out_index)(0) <= permu_in_2arr(i)(j);
         permu_out_2arr(v_out_index)(1) <= permu_in_2arr(j)(i);
         IF v_duplicates = 0 THEN
           -- We assigned a unique pair. Keep incrementing the index.
           v_out_index := v_out_index+1;
         ELSE
-          -- We just assigned a duplicate. Don't increment v_out_index so
-          -- that output will get re-assigned in the next loop iteration.
+          -- We just wired a duplicate permutation pair. Don't increment 
+          -- v_out_index so that permutation pair will get re-assigned in the
+          -- next loop iteration.
           v_duplicates := v_duplicates-1;
         END IF;
       END LOOP;
@@ -154,6 +165,4 @@ BEGIN
   -----------------------------------------------------------------------------
   src_out_2arr <= permu_out_2arr;
 
-
-
 END rtl;