From 7a0056ebf6a0ac848a3fe353ac239ed9f64d533d Mon Sep 17 00:00:00 2001 From: Florent Kermarrec Date: Thu, 1 Dec 2022 10:27:05 +0100 Subject: [PATCH] cores/ecc: Add initial doc with the help of our new assistant and to test its capabilities :) --- litex/soc/cores/ecc.py | 126 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) diff --git a/litex/soc/cores/ecc.py b/litex/soc/cores/ecc.py index 1aaf8924a..22fb35b62 100644 --- a/litex/soc/cores/ecc.py +++ b/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)