srsLTE/lib/include/srslte/phy/fec/ldpc/ldpc_decoder.h

/**
 *
 * \section COPYRIGHT
 *
 * Copyright 2013-2020 Software Radio Systems Limited
 *
 * By using this file, you agree to the terms and conditions set
 * forth in the LICENSE file which can be found at the top level of
 * the distribution.
 *
 */

/*!
 * \file ldpc_decoder.h
 * \brief Declaration of the LDPC decoder.
 * \author David Gregoratti (CTTC)
 * \date 2020
 *
 * \copyright Software Radio Systems Limited
 *
 */

#ifndef SRSLTE_LDPCDECODER_H
#define SRSLTE_LDPCDECODER_H

#include "srslte/phy/fec/ldpc/base_graph.h"

/*!
 * \brief Types of LDPC decoder.
 */
typedef enum {
  SRSLTE_LDPC_DECODER_F,            /*!< \brief %Decoder working with real-valued LLRs. */
  SRSLTE_LDPC_DECODER_S,            /*!< \brief %Decoder working with 16-bit integer-valued LLRs. */
  SRSLTE_LDPC_DECODER_C,            /*!< \brief %Decoder working with 8-bit integer-valued LLRs. */
  SRSLTE_LDPC_DECODER_C_FLOOD,      /*!< \brief %Decoder working with 8-bit integer-valued LLRs, flooded scheduling. */
  SRSLTE_LDPC_DECODER_C_AVX2,       /*!< \brief %Decoder working with 8-bit integer-valued LLRs (AVX2 version). */
  SRSLTE_LDPC_DECODER_C_AVX2_FLOOD, /*!< \brief %Decoder working with 8-bit integer-valued LLRs, flooded scheduling
                                   (AVX2 version). */
} srslte_ldpc_decoder_type_t;

/*!
 * \brief Describes an LDPC decoder.
 */
typedef struct SRSLTE_API {
  void*              ptr;   /*!< \brief Registers used by the decoder. */
  srslte_basegraph_t bg;    /*!< \brief Current base graph. */
  uint16_t           ls;    /*!< \brief Current lifting size. */
  uint8_t            bgN;   /*!< \brief Number of variable nodes in the BG. */
  uint16_t           liftN; /*!< \brief Number of variable nodes in the lifted graph. */
  uint8_t            bgM;   /*!< \brief Number of check nodes in the BG. */
  uint16_t           liftM; /*!< \brief Number of check nodes in the lifted graph. */
  uint8_t            bgK;   /*!< \brief Number of "uncoded bits" in the BG. */
  uint16_t           liftK; /*!< \brief Number of uncoded bits in the lifted graph. */
  uint16_t*          pcm;   /*!< \brief Pointer to the parity check matrix (compact form). */

  int8_t (*var_indices)[MAX_CNCT]; /*!< \brief Pointer to lists of variable indices connected to a given check node. */

  float scaling_fctr; /*!< \brief Scaling factor for the normalized min-sum algorithm. */

  void (*free)(void*); /*!< \brief Pointer to a "destructor". */

  int (*decode_f)(void*,
                  const float*,
                  uint8_t*,
                  uint32_t); /*!< \brief Pointer to the decoding function (float version). */
  int (*decode_s)(void*,
                  const int16_t*,
                  uint8_t*,
                  uint32_t); /*!< \brief Pointer to the decoding function (16-bit version). */
  int (*decode_c)(void*,
                  const int8_t*,
                  uint8_t*,
                  uint32_t); /*!< \brief Pointer to the decoding function (16-bit version). */
} srslte_ldpc_decoder_t;

/*!
 * Initializes all the LDPC decoder variables according to the given base graph
 * and lifting size.
 * \param[out] q            A pointer to a srslte_ldpc_decoder_t structure.
 * \param[in]  type         Type of LDPC decoder.
 * \param[in]  bg           The desired base graph (BG1 or BG2).
 * \param[in]  ls           The desired lifting size.
 * \param[in]  scaling_fctr Scaling factor of the normalized min-sum algorithm.
 * \return An integer: 0 if the function executes correctly, -1 otherwise.
 */
SRSLTE_API int srslte_ldpc_decoder_init(srslte_ldpc_decoder_t*     q,
                                        srslte_ldpc_decoder_type_t type,
                                        srslte_basegraph_t         bg,
                                        uint16_t                   ls,
                                        float                      scaling_fctr);

/*!
 * The LDPC decoder "destructor": it frees all the resources allocated to the decoder.
 * \param[in] q A pointer to the dismantled decoder.
 */
SRSLTE_API void srslte_ldpc_decoder_free(srslte_ldpc_decoder_t* q);

/*!
 * Carries out the actual decoding with real-valued LLRs.
 * \param[in] q A pointer to the LDPC decoder (a srslte_ldpc_decoder_t structure
 *    instance) that carries out the decoding.
 * \param[in] llrs The LLRs obtained from the channel samples that correspond to
 *    the codeword to be decoded.
 * \param[out] message The message (uncoded bits) resulting from the decoding
 *    operation.
 * \param[in] cdwd_rm_length The number of bits forming the codeword (after rate matching).
 */
SRSLTE_API int
srslte_ldpc_decoder_decode_f(srslte_ldpc_decoder_t* q, const float* llrs, uint8_t* message, uint32_t cdwd_rm_length);

/*!
 * Carries out the actual decoding with 16-bit integer-valued LLRs. It is
 * recommended to use a 15-bit representation for the LLRs, given that all
 * values exceeding \f$ 2^{15}-1 \f$ (in magnitude) will be considered as infinity.
 * \param[in] q A pointer to the LDPC decoder (a srslte_ldpc_decoder_t structure
 *    instance) that carries out the decoding.
 * \param[in] llrs The LLRs obtained from the channel samples that correspond to
 *    the codeword to be decoded.
 * \param[out] message The message (uncoded bits) resulting from the decoding
 *    operation.
 * \param[in] cdwd_rm_length The number of bits forming the codeword (after rate matching).
 */
SRSLTE_API int
srslte_ldpc_decoder_decode_s(srslte_ldpc_decoder_t* q, const int16_t* llrs, uint8_t* message, uint32_t cdwd_rm_length);

/*!
 * Carries out the actual decoding with 8-bit integer-valued LLRs. It is
 * recommended to use a 7-bit representation for the LLRs, given that all
 * values exceeding \f$ 2^{7}-1 \f$ (in magnitude) will be considered as infinity.
 * \param[in] q A pointer to the LDPC decoder (a srslte_ldpc_decoder_t structure
 *    instance) that carries out the decoding.
 * \param[in] llrs The LLRs obtained from the channel samples that correspond to
 *    the codeword to be decoded.
 * \param[out] message The message (uncoded bits) resulting from the decoding
 *    operation.
 */
SRSLTE_API int srslte_ldpc_decoder_decode_c(srslte_ldpc_decoder_t* q, const int8_t* llrs, uint8_t* message);

/*!
 * Carries out the actual decoding with 8-bit integer-valued LLRs. It is
 * recommended to use a 7-bit representation for the LLRs, given that all
 * values exceeding \f$ 2^{7}-1 \f$ (in magnitude) will be considered as infinity.
 * \param[in] q A pointer to the LDPC decoder (a srslte_ldpc_decoder_t structure
 *    instance) that carries out the decoding.
 * \param[in] llrs The LLRs obtained from the channel samples that correspond to
 *    the codeword to be decoded.
 * \param[out] message The message (uncoded bits) resulting from the decoding
 *    operation.
 * \param[in] cdwd_rm_length The number of bits forming the codeword (after rate matching).
 */
SRSLTE_API int srslte_ldpc_decoder_decode_rm_c(srslte_ldpc_decoder_t* q,
                                               const int8_t*          llrs,
                                               uint8_t*               message,
                                               uint32_t               cdwd_rm_length);

#endif // SRSLTE_LDPCDECODER_H