[hdl] Document g_SYNC_EDGE generic in synchronisers.

This is to avoid any confusion caused by g_SYNC_EDGE and g_EDGE
generics used in gc_sync, gc_sync_ffs and gc_sync_edge modules.

Also use capitals for generics as defined by our coding style.

Signed-off-by: Dimitris Lampridis <dimitris.lampridis@cern.ch>

modules/common/gc_sync.vhd

@@ -9,7 +9,7 @@
 -- description: Elementary synchronizer chain using two flip-flops.
 --
 --------------------------------------------------------------------------------
--- Copyright CERN 2014-2018
+-- Copyright CERN 2014-2020
 --------------------------------------------------------------------------------
 -- Copyright and related rights are licensed under the Solderpad Hardware
 -- License, Version 2.0 (the "License"); you may not use this file except
@@ -27,7 +27,8 @@ use ieee.std_logic_1164.all;
 
 entity gc_sync is
   generic(
-    g_sync_edge : string := "positive");
+    -- valid values are "positive" and "negative"
+    g_SYNC_EDGE : string := "positive");
   port (
     clk_i     : in  std_logic;
     rst_n_a_i : in  std_logic;
@@ -69,11 +70,11 @@ architecture arch of gc_sync is
 
 begin
 
-  assert g_sync_edge = "positive" or g_sync_edge = "negative" severity failure;
+  assert g_SYNC_EDGE = "positive" or g_SYNC_EDGE = "negative" severity failure;
 
   gc_sync_ffs_in <= d_i;
 
-  sync_posedge : if (g_sync_edge = "positive") generate
+  sync_posedge : if (g_SYNC_EDGE = "positive") generate
     process(clk_i, rst_n_a_i)
     begin
       if rst_n_a_i = '0' then
@@ -86,7 +87,7 @@ begin
     end process;
   end generate sync_posedge;
 
-  sync_negedge : if(g_sync_edge = "negative") generate
+  sync_negedge : if(g_SYNC_EDGE = "negative") generate
     process(clk_i, rst_n_a_i)
     begin
       if rst_n_a_i = '0' then

modules/common/gc_sync_edge.vhd

@@ -10,7 +10,7 @@
 --   All the registers in the chain are cleared at reset.
 --
 --------------------------------------------------------------------------------
--- Copyright CERN 2010-2018
+-- Copyright CERN 2010-2020
 --------------------------------------------------------------------------------
 -- Copyright and related rights are licensed under the Solderpad Hardware
 -- License, Version 2.0 (the "License"); you may not use this file except
@@ -28,7 +28,12 @@ use ieee.std_logic_1164.all;
 
 entity gc_sync_edge is
   generic(
-    g_edge : string := "positive");
+    -- This defines the edge detection for the pulse_o output.
+    -- IMPORTANT: it should not be confused with g_SYNC_EDGE used
+    -- in other modules such as gc_sync_ffs. The gc_sync_edge module
+    -- is *only* sensitive to the rising edge of clk_i.
+    -- Valid values are "positive" and "negative"
+    g_EDGE : string := "positive");
   port(
     clk_i     : in  std_logic;   -- clock from the destination clock domain
     rst_n_a_i : in  std_logic;   -- async reset
@@ -48,9 +53,9 @@ begin
       d_i       => data_i,
       q_o       => sync);
 
-  assert g_edge = "positive" or g_edge = "negative" severity FAILURE;
+  assert g_EDGE = "positive" or g_EDGE = "negative" severity FAILURE;
 
-  sync_posedge : if g_edge = "positive" generate
+  sync_posedge : if g_EDGE = "positive" generate
     inst_pedge : entity work.gc_posedge
       port map (
         clk_i   => clk_i,
@@ -59,7 +64,7 @@ begin
         pulse_o => pulse_o);
   end generate;
 
-  sync_negedge : if g_edge = "negative" generate
+  sync_negedge : if g_EDGE = "negative" generate
     inst_pedge : entity work.gc_negedge
       port map (
         clk_i   => clk_i,

modules/common/gc_sync_ffs.vhd

@@ -10,7 +10,7 @@
 --   All the registers in the chain are cleared at reset.
 --
 --------------------------------------------------------------------------------
--- Copyright CERN 2010-2018
+-- Copyright CERN 2010-2020
 --------------------------------------------------------------------------------
 -- Copyright and related rights are licensed under the Solderpad Hardware
 -- License, Version 2.0 (the "License"); you may not use this file except
@@ -28,7 +28,8 @@ use ieee.std_logic_1164.all;
 
 entity gc_sync_ffs is
   generic(
-    g_sync_edge : string := "positive");
+    -- valid values are "positive" and "negative"
+    g_SYNC_EDGE : string := "positive");
   port(
     clk_i    : in  std_logic;   -- clock from the destination clock domain
     rst_n_i  : in  std_logic;   -- async reset
@@ -46,7 +47,7 @@ begin
 
   cmp_gc_sync : entity work.gc_sync
     generic map (
-      g_sync_edge => g_sync_edge)
+      g_SYNC_EDGE => g_SYNC_EDGE)
     port map (
       clk_i     => clk_i,
       rst_n_a_i => rst_n_i,
@@ -67,7 +68,7 @@ begin
       data_i  => sync,
       pulse_o => npulse);
 
-  sync_posedge : if (g_sync_edge = "positive") generate
+  sync_posedge : if (g_SYNC_EDGE = "positive") generate
     process(clk_i, rst_n_i)
     begin
       if(rst_n_i = '0') then
@@ -82,7 +83,7 @@ begin
     end process;
   end generate sync_posedge;
 
-  sync_negedge : if(g_sync_edge = "negative") generate
+  sync_negedge : if(g_SYNC_EDGE = "negative") generate
     process(clk_i, rst_n_i)
     begin
       if(rst_n_i = '0') then