-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,7 +50,6 @@ 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;
@@ -135,14 +144,16 @@ BEGIN
     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;