Add doxygen documentation to libosmocoding
This adds the minimum amount of API documentation that we should have on
all our code, particularly new code merged into a library.
Change-Id: I526804f64313867913574e50e5b9e9205ad3aa74
diff --git a/src/coding/gsm0503_interleaving.c b/src/coding/gsm0503_interleaving.c
index 22ad6f6..61d4fdc 100644
--- a/src/coding/gsm0503_interleaving.c
+++ b/src/coding/gsm0503_interleaving.c
@@ -1,6 +1,7 @@
/*
* (C) 2013 by Andreas Eversberg <jolly@eversberg.eu>
* (C) 2016 by Tom Tsou <tom.tsou@ettus.com>
+ * (C) 2017 by Hrald Welte <laforge@gnumonks.org>
*
* All Rights Reserved
*
@@ -26,6 +27,16 @@
#include <osmocom/coding/gsm0503_tables.h>
#include <osmocom/coding/gsm0503_interleaving.h>
+/*! \addtogroup interleaving
+ * @{
+ * \brief GSM TS 05.03 interleaving
+ *
+ * This module contains interleaving / de-interleaving routines for
+ * various channel types, as defined in 3GPP TS 05.03 / 45.003
+ */
+
+/*! \file gsm0503_interleaving.c */
+
/*
* GSM xCCH interleaving and burst mapping
*
@@ -48,6 +59,9 @@
* Where hl(B) and hn(B) are bits in burst B indicating flags.
*/
+/*! \brief De-Interleave burst bits according to TS 05.03 4.1.4
+ * \param[out] cB caller-allocated output buffer for 456 soft coded bits
+ * \param[in] iB 456 soft input bits */
void gsm0503_xcch_deinterleave(sbit_t *cB, const sbit_t *iB)
{
int j, k, B;
@@ -59,6 +73,9 @@
}
}
+/*! \brief Interleave burst bits according to TS 05.03 4.1.4
+ * \param[out] iB caller-allocated output buffer for 456 soft interleaved bits
+ * \param[in] cB 456 soft input coded bits */
void gsm0503_xcch_interleave(ubit_t *cB, ubit_t *iB)
{
int j, k, B;
@@ -70,6 +87,11 @@
}
}
+/*! \brief De-Interleave MCS1 DL burst bits according to TS 05.03 5.1.5.1.5
+ * \param[out] u caller-allocated output buffer for 12 soft coded bits
+ * \param[out] hc caller-allocated output buffer for 68 soft coded bits
+ * \param[out] dc caller-allocated output buffer for 372 soft coded bits
+ * \param[in] iB 452 interleaved soft input bits */
void gsm0503_mcs1_dl_deinterleave(sbit_t *u, sbit_t *hc,
sbit_t *dc, const sbit_t *iB)
{
@@ -106,6 +128,11 @@
}
}
+/*! \brief Interleave MCS1 DL burst bits according to TS 05.03 5.1.5.1.5
+ * \param[in] up 12 input soft coded bits (usf)
+ * \param[in] hc 68 input soft coded bits (header)
+ * \param[in] dc 372 input soft bits (data)
+ * \param[out] iB 456 interleaved soft output bits */
void gsm0503_mcs1_dl_interleave(const ubit_t *up, const ubit_t *hc,
const ubit_t *dc, ubit_t *iB)
{
@@ -139,6 +166,10 @@
gsm0503_xcch_interleave(cp, iB);
}
+/*! \brief Interleave MCS1 UL burst bits according to TS 05.03 5.1.5.2.4
+ * \param[out] hc caller-allocated output buffer for 80 soft coded header bits
+ * \param[out] dc caller-allocated output buffer for 372 soft coded data bits
+ * \param[in] iB 456 interleaved soft input bits */
void gsm0503_mcs1_ul_deinterleave(sbit_t *hc, sbit_t *dc, const sbit_t *iB)
{
int k;
@@ -169,6 +200,10 @@
}
}
+/*! \brief Interleave MCS1 DL burst bits according to TS 05.03 5.1.5.2.4
+ * \param[in] hc 80 input coded bits (header)
+ * \param[in] dc 372 input bits (data)
+ * \param[out] iB 456 interleaved output bits */
void gsm0503_mcs1_ul_interleave(const ubit_t *hc, const ubit_t *dc, ubit_t *iB)
{
int k;
@@ -199,6 +234,11 @@
gsm0503_xcch_interleave(cp, iB);
}
+/*! \brief Interleave MCS5 UL burst bits according to TS 05.03 5.1.9.2.4
+ * \param[in] hc 136 soft coded header input bits
+ * \param[in] dc 1248 soft coded data input bits
+ * \param[out] hi 136 interleaved header output bits
+ * \param[out] di 1248 interleaved data output bits */
void gsm0503_mcs5_ul_interleave(const ubit_t *hc, const ubit_t *dc,
ubit_t *hi, ubit_t *di)
{
@@ -217,6 +257,10 @@
}
}
+/*! \brief De-Interleave MCS5 UL burst bits according to TS 05.03 5.1.9.2.4
+ * \param[out] hc caller-allocated output buffer for 136 soft coded header bits
+ * \param[out] dc caller-allocated output buffer for 1248 soft coded data bits
+ * \param[in] iB interleaved soft input bits */
void gsm0503_mcs5_ul_deinterleave(sbit_t *hc, sbit_t *dc,
const sbit_t *hi, const sbit_t *di)
{
@@ -239,6 +283,11 @@
}
}
+/*! \brief Interleave MCS5 DL burst bits according to TS 05.03 5.1.9.1.5
+ * \param[in] hc 100 soft coded header input bits
+ * \param[in] dc 1248 soft coded data input bits
+ * \param[out] hi 100 interleaved header output bits
+ * \param[out] di 1248 interleaved data output bits */
void gsm0503_mcs5_dl_interleave(const ubit_t *hc, const ubit_t *dc,
ubit_t *hi, ubit_t *di)
{
@@ -257,6 +306,10 @@
}
}
+/*! \brief De-Interleave MCS5 UL burst bits according to TS 05.03 5.1.9.1.5
+ * \param[out] hc caller-allocated output buffer for 100 soft coded header bits
+ * \param[out] dc caller-allocated output buffer for 1248 soft coded data bits
+ * \param[in] iB interleaved soft input bits */
void gsm0503_mcs5_dl_deinterleave(sbit_t *hc, sbit_t *dc,
const sbit_t *hi, const sbit_t *di)
{
@@ -279,6 +332,12 @@
}
}
+/*! \brief Interleave MCS7 DL burst bits according to TS 05.03 5.1.11.1.5
+ * \param[in] hc 124 soft coded header input bits
+ * \param[in] c1 612 soft coded data input bits
+ * \param[in] c2 612 soft coded data input bits
+ * \param[out] hi 124 interleaved header output bits
+ * \param[out] di 1224 interleaved data output bits */
void gsm0503_mcs7_dl_interleave(const ubit_t *hc, const ubit_t *c1,
const ubit_t *c2, ubit_t *hi, ubit_t *di)
{
@@ -302,7 +361,12 @@
}
}
-
+/*! \brief De-Interleave MCS7 DL burst bits according to TS 05.03 5.1.11.1.5
+ * \param[out] hc caller-allocated output buffer for 124 soft coded header bits
+ * \param[out] c1 caller-allocated output buffer for 612 soft coded data bits
+ * \param[out] c2 caller-allocated output buffer for 612 soft coded data bits
+ * \param[in] hi interleaved soft input header bits
+ * \param[in] di interleaved soft input data bits */
void gsm0503_mcs7_dl_deinterleave(sbit_t *hc, sbit_t *c1, sbit_t *c2,
const sbit_t *hi, const sbit_t *di)
{
@@ -330,6 +394,12 @@
}
}
+/*! \brief Interleave MCS7 UL burst bits according to TS 05.03 5.1.11.2.4
+ * \param[in] hc 124 soft coded header input bits
+ * \param[in] c1 612 soft coded data input bits
+ * \param[in] c2 612 soft coded data input bits
+ * \param[out] hi 124 interleaved header output bits
+ * \param[out] di 1224 interleaved data output bits */
void gsm0503_mcs7_ul_interleave(const ubit_t *hc, const ubit_t *c1,
const ubit_t *c2, ubit_t *hi, ubit_t *di)
{
@@ -353,6 +423,12 @@
}
}
+/*! \brief De-Interleave MCS7 UL burst bits according to TS 05.03 5.1.11.2.4
+ * \param[out] hc caller-allocated output buffer for 160 soft coded header bits
+ * \param[out] c1 caller-allocated output buffer for 612 soft coded data bits
+ * \param[out] c2 caller-allocated output buffer for 612 soft coded data bits
+ * \param[in] hi interleaved soft input header bits
+ * \param[in] di interleaved soft input data bits */
void gsm0503_mcs7_ul_deinterleave(sbit_t *hc, sbit_t *c1, sbit_t *c2,
const sbit_t *hi, const sbit_t *di)
{
@@ -380,6 +456,12 @@
}
}
+/*! \brief Interleave MCS8 UL burst bits according to TS 05.03 5.1.12.2.4
+ * \param[in] hc 160 soft coded header input bits
+ * \param[in] c1 612 soft coded data input bits
+ * \param[in] c2 612 soft coded data input bits
+ * \param[out] hi 160 interleaved header output bits
+ * \param[out] di 1224 interleaved data output bits */
void gsm0503_mcs8_ul_interleave(const ubit_t *hc, const ubit_t *c1,
const ubit_t *c2, ubit_t *hi, ubit_t *di)
{
@@ -403,6 +485,13 @@
}
}
+
+/*! \brief De-Interleave MCS8 UL burst bits according to TS 05.03 5.1.12.2.4
+ * \param[out] hc caller-allocated output buffer for 160 soft coded header bits
+ * \param[out] c1 caller-allocated output buffer for 612 soft coded data bits
+ * \param[out] c2 caller-allocated output buffer for 612 soft coded data bits
+ * \param[in] hi interleaved soft input header bits
+ * \param[in] di interleaved soft input data bits */
void gsm0503_mcs8_ul_deinterleave(sbit_t *hc, sbit_t *c1, sbit_t *c2,
const sbit_t *hi, const sbit_t *di)
{
@@ -430,6 +519,12 @@
}
}
+/*! \brief Interleave MCS8 DL burst bits according to TS 05.03 5.1.12.1.5
+ * \param[in] hc 124 soft coded header input bits
+ * \param[in] c1 612 soft coded data input bits
+ * \param[in] c2 612 soft coded data input bits
+ * \param[out] hi 124 interleaved header output bits
+ * \param[out] di 1224 interleaved data output bits */
void gsm0503_mcs8_dl_interleave(const ubit_t *hc, const ubit_t *c1,
const ubit_t *c2, ubit_t *hi, ubit_t *di)
{
@@ -453,6 +548,12 @@
}
}
+/*! \brief De-Interleave MCS8 DL burst bits according to TS 05.03 5.1.12.1.5
+ * \param[out] hc caller-allocated output buffer for 124 soft coded header bits
+ * \param[out] c1 caller-allocated output buffer for 612 soft coded data bits
+ * \param[out] c2 caller-allocated output buffer for 612 soft coded data bits
+ * \param[in] hi interleaved soft input header bits
+ * \param[in] di interleaved soft input data bits */
void gsm0503_mcs8_dl_deinterleave(sbit_t *hc, sbit_t *c1, sbit_t *c2,
const sbit_t *hi, const sbit_t *di)
{
@@ -504,6 +605,9 @@
* Where hl(B) and hn(B) are bits in burst B indicating flags.
*/
+/*! \brief GSM TCH FR/EFR/AFS De-Interleaving and burst mapping
+ * \param[out] cB caller-allocated buffer for 456 unpacked output bits
+ * \param[in] iB 456 unpacked interleaved input bits */
void gsm0503_tch_fr_deinterleave(sbit_t *cB, sbit_t *iB)
{
int j, k, B;
@@ -515,6 +619,9 @@
}
}
+/*! \brief GSM TCH FR/EFR/AFS Interleaving and burst mapping
+ * \param[in] cB caller-allocated buffer for 456 unpacked input bits
+ * \param[out] iB 456 unpacked interleaved output bits */
void gsm0503_tch_fr_interleave(ubit_t *cB, ubit_t *iB)
{
int j, k, B;
@@ -550,6 +657,9 @@
* Where hl(B) and hn(B) are bits in burst B indicating flags.
*/
+/*! \brief GSM TCH HR/AHS De-Interleaving and burst mapping
+ * \param[out] cB caller-allocated buffer for 228 unpacked output bits
+ * \param[in] iB 228 unpacked interleaved input bits */
void gsm0503_tch_hr_deinterleave(sbit_t *cB, sbit_t *iB)
{
int j, k, B;
@@ -561,6 +671,9 @@
}
}
+/*! \brief GSM TCH HR/AHS Interleaving and burst mapping
+ * \param[in] cB caller-allocated buffer for 228 unpacked input bits
+ * \param[out] iB 228 unpacked interleaved output bits */
void gsm0503_tch_hr_interleave(ubit_t *cB, ubit_t *iB)
{
int j, k, B;
@@ -571,3 +684,5 @@
iB[B * 114 + j] = cB[k];
}
}
+
+/*! @} */