raptor10.h

/*
 *  Copyright 2020 Roberto Francescon
 *  This file is part of freeRaptor.
 *
 *  freeRaptor is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 *  freeRaptor is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with freeRaptor.  If not, see <http://www.gnu.org/licenses/>.
 */

/**
 * @author  Roberto Francescon
 * @brief   Definition of fields, structures and functions for the
 *          implementation of Raptor10 FEC codes
 * @version 0.0.1
 * @file    raptor10.h
 */

#ifndef RAPTOR10_H
#define RAPTOR10_H

#include <stdint.h>
#include <stdlib.h>

#include <gf2matrix.h>
#include <raptor_consts.h> // J, C1 and C2

/** Type symbols is a Raptor 10 symbol: a K bytes array*/
typedef uint8_t *Symbol;

/**
 * Struct containing all the fileds needed by the Raptor10 code to operate
 * @struct Raptor10
 * @brief Structure holding all the fields needed by Raptor10 encoder and
 * decoder
 * @var Raptor10::F Transfer length of the object, in bytes
 * @var Raptor10::Al symbol alignment parameter
 * @var Raptor10::T symbol size, in bytes
 * @var Raptor10::Z number of source blocks
 * @var Raptor10::N number of sub-blocks in each source block
 * @var Raptor10::W a target on the sub-block size
 * @var Raptor10::P maximum packet payload size (multiple of ~Al~)
 * @var Raptor10::Kmax maximum number of source symbols per source block
 * @var Raptor10::Kmin minimum target on the number of symbols per source block
 * @var Raptor10::Gmax maximum target number of symbols per packet
 * @var Raptor10::K denotes the number of symbols in a single source block
 * @var Raptor10::L denotes the number of pre-coding symbols for a single
 * source block
 * @var Raptor10::S denotes the number of LDPC symbols for a single source
 * block
 * @var Raptor10::H denotes the number of Half symbols for a single source
 * block
 * @var Raptor10::G the number of symbols within an encoding symbol group
 * @var Raptor10::C denotes an array of intermediate symbols, C[0], C[1],
 * C[2],..., C[L-1]
 * @var Raptor10::C_ denotes an array of source symbols, C’[0], C’[1],
 * C’[2],..., C’[K-1]
 */
typedef struct {
  uint32_t F;
  uint32_t W;
  uint32_t P;
  uint32_t Al;
  uint32_t Kmax;
  uint32_t Kmin;
  uint32_t Gmax;
  uint32_t T;
  uint32_t Z;
  uint32_t N;
  uint32_t K;
  uint32_t L;
  uint32_t S;
  uint32_t H;
  uint32_t G;
  uint8_t *C;
  uint8_t *Cp;
} Raptor10;

/**
 * Factorial function
 * @param n number of which to make the factorial
 * @return the factorial
 */
int factorial(int n);

/**
 * Determine whether the provided number is prime or not
 * @param n number to test for primeness
 * @return 1 if the provided number is prime, 0 otherwise
 */
int is_prime(uint32_t n);

/**
 * Choose: binomial choosing among numbers
 * @param i first number
 * @param i second number
 * @return binomial
 */
int choose(int i, int j);

/**
 * Rand function generate pseudo-random numbers
 * The output is an integer between 0 and m-1. V0 and V1 are arrays of 4-bytes
 * values.
 */
uint32_t r10_Rand(uint32_t X, uint32_t i, uint32_t m);

/**
 * Random degree generation
 * @param v selector ft the degree
 */
uint32_t r10_Deg(uint32_t v);

/**
 * Funtion that implements the triple generator as specified in RFC 5053
 * @param K number of source symbols
 * @param X encoding symbolm ID
 * @param triple return array parameter
 */
void r10_Trip(uint32_t K, uint32_t X, uint32_t triple[3], Raptor10 *obj);

/**
 * Core oncoding function as specified by RFC5053
 * @param K number of source symbols
 * @param C array of intermediate symbols
 * @param triple triple generated by function Trip()
 */
void r10_LTEnc(uint32_t X, uint32_t K, uint32_t *C, uint32_t triple[3],
               uint32_t G, Raptor10 obj);

/**
 * Function that buils the LDPC submatrix
 *
 */
int r10_build_LDPC_submat(int K, int S, gf2matrix *A);

/**
 * Function that builds the Half submatrix
 */
int r10_build_Half_submat(unsigned int K, unsigned int S, unsigned int H,
                          gf2matrix *A);

/**
 * Function that builds the LT submatrix
 */
int r10_build_LT_submat(uint32_t K, uint32_t S, uint32_t H, Raptor10 *obj,
                        gf2matrix *A);

/**
 * Function that builds the LT matrix.
 */
void r10_build_LT_mat(uint32_t N, Raptor10 *obj, gf2matrix *G_LT,
                      uint32_t *ESIs);

/**
 * Function that builds the Constraints matrix
 */
int r10_build_constraints_mat(Raptor10 *obj, gf2matrix *A);

/**
 * Function responsible for computing all the needed parameters.
 * @param raptor_obj Raptor10 object to configure
 */
void r10_compute_params(Raptor10 *obj);

/**
 * Method the perform the XOR multiplication
 * It mutiplies a GF(2) matrix, A, with a symbol-based array, block,
 * where the symbol size is T and the matrix is a gf2matrix.
 * @param obj pointer to a Raptor10 specs object
 * @param A pointer to a gf2matrix encoding matrix
 * @param block array of symbols to right multiply
 * @param res_block return param with the resulting symbols
 */
void r10_multiplication(Raptor10 *obj, gf2matrix *A, uint8_t *block,
                        uint8_t *res_block);

/**
 * Encoding function
 * @param src_s source symbols block, to be encoded
 * @param enc_s return parameter for the encoded symbols block
 * @param obj Raptor10 coder object with configuration parameters
 * @param A constraints matrix
 */
void r10_encode(uint8_t *src_s, uint8_t *enc_s, Raptor10 *obj, gf2matrix *A);

/**
 * Decoding function
 * @param enc_s something encoded symbols block, to be decoded
 * @param dec_s return parameter for the decoded symbols block
 * @param obj Raptor10 coder object
 * @param A constraints matrix
 * @param N_ number of encoded symbols correctly received and passed to decoder
 * @param ESIs array of the ESI of the correctly received symbols
 */
void r10_decode(uint8_t *enc_s, uint8_t *dec_s, Raptor10 *obj, gf2matrix *A,
                uint32_t N_, uint32_t *ESIs);

#endif