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

1 files changed, 116 insertions, 1 deletions

diff --git a/src/coding/gsm0503_interleaving.c b/src/coding/gsm0503_interleaving.c
index 22ad6f69..61d4fdc6 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 @@ void gsm0503_xcch_deinterleave(sbit_t *cB, const sbit_t *iB)
 	}
 }
 
+/*! \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 @@ void gsm0503_xcch_interleave(ubit_t *cB, ubit_t *iB)
 	}
 }
 
+/*! \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 @@ void gsm0503_mcs1_dl_deinterleave(sbit_t *u, sbit_t *hc,
 	}
 }
 
+/*! \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 @@ void gsm0503_mcs1_dl_interleave(const ubit_t *up, const ubit_t *hc,
 	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 @@ void gsm0503_mcs1_ul_deinterleave(sbit_t *hc, sbit_t *dc, const sbit_t *iB)
 	}
 }
 
+/*! \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 @@ void gsm0503_mcs1_ul_interleave(const ubit_t *hc, const ubit_t *dc, ubit_t *iB)
 	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 @@ void gsm0503_mcs5_ul_interleave(const ubit_t *hc, const ubit_t *dc,
 	}
 }
 
+/*! \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 @@ void gsm0503_mcs5_ul_deinterleave(sbit_t *hc, sbit_t *dc,
 	}
 }
 
+/*! \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 @@ void gsm0503_mcs5_dl_interleave(const ubit_t *hc, const ubit_t *dc,
 	}
 }
 
+/*! \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 @@ void gsm0503_mcs5_dl_deinterleave(sbit_t *hc, sbit_t *dc,
 	}
 }
 
+/*! \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 @@ void gsm0503_mcs7_dl_interleave(const ubit_t *hc, const ubit_t *c1,
 	}
 }
 
-
+/*! \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 @@ void gsm0503_mcs7_dl_deinterleave(sbit_t *hc, sbit_t *c1, sbit_t *c2,
 	}
 }
 
+/*! \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 @@ void gsm0503_mcs7_ul_interleave(const ubit_t *hc, const ubit_t *c1,
 	}
 }
 
+/*! \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 @@ void gsm0503_mcs7_ul_deinterleave(sbit_t *hc, sbit_t *c1, sbit_t *c2,
 	}
 }
 
+/*! \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 @@ void gsm0503_mcs8_ul_interleave(const ubit_t *hc, const ubit_t *c1,
 	}
 }
 
+
+/*! \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 @@ void gsm0503_mcs8_ul_deinterleave(sbit_t *hc, sbit_t *c1, sbit_t *c2,
 	}
 }
 
+/*! \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 @@ void gsm0503_mcs8_dl_interleave(const ubit_t *hc, const ubit_t *c1,
 	}
 }
 
+/*! \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 @@ void gsm0503_mcs8_dl_deinterleave(sbit_t *hc, sbit_t *c1, sbit_t *c2,
  * 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 @@ void gsm0503_tch_fr_deinterleave(sbit_t *cB, sbit_t *iB)
 	}
 }
 
+/*! \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 @@ void gsm0503_tch_fr_interleave(ubit_t *cB, ubit_t *iB)
  * 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 @@ void gsm0503_tch_hr_deinterleave(sbit_t *cB, sbit_t *iB)
 	}
 }
 
+/*! \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 @@ void gsm0503_tch_hr_interleave(ubit_t *cB, ubit_t *iB)
 		iB[B * 114 + j] = cB[k];
 	}
 }
+
+/*! @} */