cores/ecc: Add initial doc with the help of our new assistant and to test its capabilities :)

litex/soc/cores/ecc.py

@@ -10,6 +10,9 @@ Error Correcting Code
 Hamming codes with additional parity (SECDED):
 - Single Error Correction
 - Double Error Detection
+
+This module contains modules for SECDED (Single Error Correction, Double Error Detection) ECC encoding
+and decoding.
 """
 
 from migen import *
@@ -19,6 +22,18 @@ from litex.gen import *
 # Helpers ------------------------------------------------------------------------------------------
 
 def compute_m_n(k):
+    """
+    Compute the number of syndrome and data bits.
+
+    This function computes the number of syndrome bits, `m`, and data bits, `n`, given the length of
+    the input binary string, `k`.
+
+    Args:
+        k (int): The length of the input binary string.
+
+    Returns:
+        tuple: A tuple containing the number of syndrome and data bits.
+    """
     m = 1
     while (2**m < (m + k + 1)):
         m = m + 1;
@@ -26,6 +41,18 @@ def compute_m_n(k):
     return m, n
 
 def compute_syndrome_positions(m):
+    """
+    Compute the positions of the syndrome bits.
+
+    This function computes the positions of the syndrome bits in the codeword, given the number of
+    syndrome bits, `m`.
+
+    Args:
+        m (int): The number of syndrome bits.
+
+    Returns:
+        list: A list of the positions of the syndrome bits in the codeword.
+    """
     r = []
     i = 1
     while i <= m:
@@ -34,6 +61,18 @@ def compute_syndrome_positions(m):
     return r
 
 def compute_data_positions(m):
+    """
+    Compute the positions of the data bits.
+
+    This function computes the positions of the data bits in the codeword, given the number of
+    syndrome bits, `m`.
+
+    Args:
+        m (int): The number of syndrome bits.
+
+    Returns:
+        list: A list of the positions of the data bits in the codeword.
+    """
     r = []
     e = compute_syndrome_positions(m)
     for i in range(1, m + 1):
@@ -42,6 +81,19 @@ def compute_data_positions(m):
     return r
 
 def compute_cover_positions(m, p):
+    """
+    Compute the positions of the bits covered by a syndrome bit.
+
+    This function computes the positions of the bits covered by a syndrome bit in the codeword, given
+    the number of syndrome bits, `m`, and the position of the syndrome bit, `p`.
+
+    Args:
+        m (int): The number of syndrome bits.
+        p (int): The position of the syndrome bit.
+
+    Returns:
+        list: A list of the positions of the bits covered by the syndrome bit in the codeword.
+    """
     r = []
     i = p
     while i <= m:
@@ -53,17 +105,51 @@ def compute_cover_positions(m, p):
 # SECDED (Single Error Correction, Double Error Detection) -----------------------------------------
 
 class SECDED:
+    """
+    The SECDED class provides methods for encoding and decoding data using the SECDED (Single Error
+    Correction, Double Error Detection) method.
+    """
     def place_data(self, data, codeword):
+        """
+        Place the data bits in the codeword.
+
+        This method places the input data bits in the codeword, setting the values of the data bits
+        in the codeword.
+
+        Args:
+            data (list)     : A list of the data bits to be placed in the codeword.
+            codeword (list) : A list of the codeword bits.
+        """
         d_pos = compute_data_positions(len(codeword))
         for i, d in enumerate(d_pos):
             self.comb += codeword[d-1].eq(data[i])
 
     def extract_data(self, codeword, data):
+        """
+        Extract the data bits from the codeword.
+
+        This method extracts the data bits from the codeword, setting the values of the data bits to
+        be the values of the data bits in the codeword.
+
+        Args:
+            codeword (list) : A list of the codeword bits.
+            data (list)     : A list of the data bits to be extracted from the codeword.
+        """
         d_pos = compute_data_positions(len(codeword))
         for i, d in enumerate(d_pos):
             self.comb += data[i].eq(codeword[d-1])
 
     def compute_syndrome(self, codeword, syndrome):
+        """
+        Compute the syndrome bits for the codeword.
+
+        This method computes the syndrome bits for the given codeword, setting the values of the
+        syndrome bits.
+
+        Args:
+            codeword (list): A list of the codeword bits.
+            syndrome (list): A list of the syndrome bits to be computed.
+        """
         p_pos = compute_syndrome_positions(len(codeword))
         for i, p in enumerate(p_pos):
             pn = Signal()
@@ -75,16 +161,48 @@ class SECDED:
             self.comb += syndrome[i].eq(pn)
 
     def place_syndrome(self, syndrome, codeword):
+        """
+        Place the syndrome bits in the codeword.
+
+        This method places the input syndrome bits in the codeword, setting the values of the syndrome
+        bits in the codeword.
+
+        Args:
+            syndrome (list): A list of the syndrome bits to be placed in the codeword.
+            codeword (list): A list of the codeword bits.
+        """
         p_pos = compute_syndrome_positions(len(codeword))
         for i, p in enumerate(p_pos):
             self.comb += codeword[p-1].eq(syndrome[i])
 
     def compute_parity(self, codeword, parity):
+        """
+        Compute the parity bit of the input data.
+
+        This function computes the parity bit of the input data, given the length of the input data,
+        data`, and the parity bit, `parity`.
+
+        Args:
+            data (list)     : The input data.
+            parity (Signal) : The parity bit.
+
+        Returns:
+            Signal: The computed parity bit.
+        """
         self.comb += parity.eq(Reduce("XOR", [codeword[i] for i in range(len(codeword))]))
 
 # ECC Encoder --------------------------------------------------------------------------------------
 
 class ECCEncoder(SECDED, Module):
+    """
+    ECCEncoder
+
+    This module does the ECC (Error Correcting Code) encoding using the SECDED (Single Error Correction,
+    Double Error Detection) method. This class provides methods for encoding data, computing
+    the parity bits, and generating the codeword.
+
+    Generates the codeword and parity bits for the input data.
+    """
     def __init__(self, k):
         m, n = compute_m_n(k)
 
@@ -116,6 +234,14 @@ class ECCEncoder(SECDED, Module):
 # ECC Decoder --------------------------------------------------------------------------------------
 
 class ECCDecoder(SECDED, Module):
+    """
+    ECCDecoder
+
+    This modules does the ECC (Error Correcting Code) decoding using the SECDED (Single Error Correction,
+    Double Error Detection) method.
+
+    Generates output data from codeword + parity bits  + sed/dec detection.
+    """
     def __init__(self, k):
         m, n = compute_m_n(k)