diff --git a/lib/decoding/osmocom/coding/CMakeLists.txt b/lib/decoding/osmocom/coding/CMakeLists.txt
index 8e68577..c0a4d92 100644
--- a/lib/decoding/osmocom/coding/CMakeLists.txt
+++ b/lib/decoding/osmocom/coding/CMakeLists.txt
@@ -25,4 +25,3 @@
     gsm0503_parity.c
     gsm0503_tables.c
 )
-
diff --git a/lib/decoding/osmocom/coding/gsm0503.h b/lib/decoding/osmocom/coding/gsm0503.h
index e1c62a6..ccd421a 100644
--- a/lib/decoding/osmocom/coding/gsm0503.h
+++ b/lib/decoding/osmocom/coding/gsm0503.h
@@ -1,13 +1,13 @@
+
 /*
- * gsm0503.h
- *
+ * Copyright (C) 2011-2016 Sylvain Munaut <tnt@246tNt.com>
  * Copyright (C) 2016 sysmocom s.f.m.c. GmbH
  *
  * All Rights Reserved
  *
  * This program 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 2 of the License, or
+ * the Free Software Foundation; either version 3 of the License, or
  * (at your option) any later version.
  *
  * This program is distributed in the hope that it will be useful,
@@ -22,162 +22,264 @@
 
 #pragma once
 
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-
 #include <stdint.h>
-
 #include <osmocom/core/conv.h>
 
-/*! \file gsm0503.h
- * Osmocom convolutional encoder/decoder for xCCH channels, see 3GPP TS 05.03
- */
-
-/*! \brief structure describing convolutional code xCCH
- *
- *  Non-recursive code, flushed, not punctured code.
+/*! structure describing xCCH convolutional code:.
+ * 228 bits blocks, rate 1/2, k = 5
+ * G0 = 1 + D3 + D4
+ * G1 = 1 + D + D3 + D4
  */
 extern const struct osmo_conv_code gsm0503_xcch;
 
-/*! \brief structure describing convolutional code RACH
+/*! structure describing RACH convolutional code.
  */
 extern const struct osmo_conv_code gsm0503_rach;
 
-/*! \brief structure describing convolutional code SCH
+/*! structure describing Extended RACH (11 bit) convolutional code.
+ */
+extern const struct osmo_conv_code gsm0503_rach_ext;
+
+/*! structure describing SCH convolutional code.
  */
 extern const struct osmo_conv_code gsm0503_sch;
 
-/*! \brief structures describing convolutional codes CS2/3
+/*! structure describing CS2 convolutional code:.
+ * G0 = 1 + D3 + D4
+ * G1 = 1 + D + D3 + D4
  */
 extern const struct osmo_conv_code gsm0503_cs2;
+
+/*! structure describing CS3 convolutional code:.
+ * G0 = 1 + D3 + D4
+ * G1 = 1 + D + D3 + D4
+ */
 extern const struct osmo_conv_code gsm0503_cs3;
 
-/*! \brief structure describing convolutional code TCH/FR
+/*! structure describing CS2 convolutional code (non-punctured):.
+ * G0 = 1 + D3 + D4
+ * G1 = 1 + D + D3 + D4
  */
-extern const struct osmo_conv_code gsm0503_tch_fr;
+extern const struct osmo_conv_code gsm0503_cs2_np;
 
-/*! \brief structure describing convolutional code TCH/HR
+/*! structure describing CS3 convolutional code (non-punctured):.
+ * G0 = 1 + D3 + D4
+ * G1 = 1 + D + D3 + D4
  */
-extern const struct osmo_conv_code gsm0503_tch_hr;
+extern const struct osmo_conv_code gsm0503_cs3_np;
 
-/*! \brief structure describing convolutional code TCH/AFS 12.2
+/*! structure describing TCH/AFS 12.2 kbits convolutional code:.
+ * 250 bits block, rate 1/2, punctured
+ * G0/G0 = 1
+ * G1/G0 = 1 + D + D3 + D4 / 1 + D3 + D4
  */
 extern const struct osmo_conv_code gsm0503_tch_afs_12_2;
 
-/*! \brief structure describing convolutional code TCH/AFS 10.2
+/*! structure describing TCH/AFS 10.2 kbits convolutional code:.
+ * G1/G3 = 1 + D + D3 + D4 / 1 + D + D2 + D3 + D4
+ * G2/G3 = 1 + D2 + D4     / 1 + D + D2 + D3 + D4
+ * G3/G3 = 1
  */
 extern const struct osmo_conv_code gsm0503_tch_afs_10_2;
 
-/*! \brief structure describing convolutional code TCH/AFS 7.95
+/*! structure describing TCH/AFS 7.95 kbits convolutional code:.
+ * G4/G4 = 1
+ * G5/G4 = 1 + D + D4 + D6           / 1 + D2 + D3 + D5 + D6
+ * G6/G4 = 1 + D + D2 + D3 + D4 + D6 / 1 + D2 + D3 + D5 + D6
  */
 extern const struct osmo_conv_code gsm0503_tch_afs_7_95;
 
-/*! \brief structure describing convolutional code TCH/AFS 7.4
+/*! structure describing TCH/AFS 7.4 kbits convolutional code:.
+ * G1/G3 = 1 + D + D3 + D4 / 1 + D + D2 + D3 + D4
+ * G2/G3 = 1 + D2 + D4     / 1 + D + D2 + D3 + D4
+ * G3/G3 = 1
  */
 extern const struct osmo_conv_code gsm0503_tch_afs_7_4;
 
-/*! \brief structure describing convolutional code TCH/AFS 6.7
+/*! structure describing TCH/AFS 6.7 kbits convolutional code:.
+ * G1/G3 = 1 + D + D3 + D4 / 1 + D + D2 + D3 + D4
+ * G2/G3 = 1 + D2 + D4     / 1 + D + D2 + D3 + D4
+ * G3/G3 = 1
+ * G3/G3 = 1
  */
 extern const struct osmo_conv_code gsm0503_tch_afs_6_7;
 
-/*! \brief structure describing convolutional code TCH/AFS 5.9
+/*! structure describing TCH/AFS 5.9 kbits convolutional code:.
+ * 124 bits
+ * G4/G6 = 1 + D2 + D3 + D5 + D6 / 1 + D + D2 + D3 + D4 + D6
+ * G5/G6 = 1 + D + D4 + D6       / 1 + D + D2 + D3 + D4 + D6
+ * G6/G6 = 1
+ * G6/G6 = 1
  */
 extern const struct osmo_conv_code gsm0503_tch_afs_5_9;
 
-/*! \brief structure describing convolutional code TCH/AFS 5.15
+/*! structure describing TCH/AFS 5.15 kbits convolutional code:.
+ * G1/G3 = 1 + D + D3 + D4 / 1 + D + D2 + D3 + D4
+ * G1/G3 = 1 + D + D3 + D4 / 1 + D + D2 + D3 + D4
+ * G2/G3 = 1 + D2 + D4     / 1 + D + D2 + D3 + D4
+ * G3/G3 = 1
+ * G3/G3 = 1
  */
 extern const struct osmo_conv_code gsm0503_tch_afs_5_15;
 
-/*! \brief structure describing convolutional code TCH/AFS 4.75
+/*! structure describing TCH/AFS 4.75 kbits convolutional code:.
+ * G4/G6 = 1 + D2 + D3 + D5 + D6 / 1 + D + D2 + D3 + D4 + D6
+ * G4/G6 = 1 + D2 + D3 + D5 + D6 / 1 + D + D2 + D3 + D4 + D6
+ * G5/G6 = 1 + D + D4 + D6       / 1 + D + D2 + D3 + D4 + D6
+ * G6/G6 = 1
+ * G6/G6 = 1
  */
 extern const struct osmo_conv_code gsm0503_tch_afs_4_75;
 
-/*! \brief structure describing convolutional code TCH/AHS 7.95
+/*! structure describing TCH/F convolutional code.
+ */
+extern const struct osmo_conv_code gsm0503_tch_fr;
+
+/*! structure describing TCH/H convolutional code.
+ */
+extern const struct osmo_conv_code gsm0503_tch_hr;
+
+/*! structure describing TCH/AHS 7.95 kbits convolutional code.
  */
 extern const struct osmo_conv_code gsm0503_tch_ahs_7_95;
 
-/*! \brief structure describing convolutional code TCH/AHS 7.4
+/*! structure describing TCH/AHS 7.4 kbits convolutional code.
  */
 extern const struct osmo_conv_code gsm0503_tch_ahs_7_4;
 
-/*! \brief structure describing convolutional code TCH/AHS 6.7
+/*! structure describing TCH/AHS 6.7 kbits convolutional code.
  */
 extern const struct osmo_conv_code gsm0503_tch_ahs_6_7;
 
-/*! \brief structure describing convolutional code TCH/AHS 5.9
+/*! structure describing TCH/AHS 5.9 kbits convolutional code.
  */
 extern const struct osmo_conv_code gsm0503_tch_ahs_5_9;
 
-/*! \brief structure describing convolutional code TCH/AHS 5.15
+/*! structure describing TCH/AHS 5.15 kbits convolutional code.
  */
 extern const struct osmo_conv_code gsm0503_tch_ahs_5_15;
 
-/*! \brief structure describing convolutional code TCH/AHS 4.75
+/*! structure describing TCH/AHS 4.75 kbits convolutional code.
  */
 extern const struct osmo_conv_code gsm0503_tch_ahs_4_75;
 
-/*! \brief structure describing convolutional code EDGE MCS-1 DL HDR
+/*! structure describing EDGE MCS-1 DL header convolutional code:.
+ * 42 bits blocks, rate 1/3, k = 7
+ * G4 = 1 + D2 + D3 + D5 + D6
+ * G7 = 1 + D + D2 + D3 + D6
+ * G5 = 1 + D + D4 + D6
  */
 extern const struct osmo_conv_code gsm0503_mcs1_dl_hdr;
 
-/*! \brief structure describing convolutional code EDGE MCS-1 UL HDR
+/*! structure describing EDGE MCS-1 UL header convolutional code:.
+ * 45 bits blocks, rate 1/3, k = 7
+ * G4 = 1 + D2 + D3 + D5 + D6
+ * G7 = 1 + D + D2 + D3 + D6
+ * G5 = 1 + D + D4 + D6
  */
 extern const struct osmo_conv_code gsm0503_mcs1_ul_hdr;
 
-/*! \brief structure describing convolutional code EDGE MCS-1
+/*! structure describing EDGE MCS-1 data convolutional code:.
+ * 196 bits blocks, rate 1/3, k = 7
+ * G4 = 1 + D2 + D3 + D5 + D6
+ * G7 = 1 + D + D2 + D3 + D6
+ * G5 = 1 + D + D4 + D6
  */
 extern const struct osmo_conv_code gsm0503_mcs1;
 
-/*! \brief structure describing convolutional code EDGE MCS-2
+/*! structure describing EDGE MCS-2 data convolutional code:.
+ * 244 bits blocks, rate 1/3, k = 7
+ * G4 = 1 + D2 + D3 + D5 + D6
+ * G7 = 1 + D + D2 + D3 + D6
+ * G5 = 1 + D + D4 + D6
  */
 extern const struct osmo_conv_code gsm0503_mcs2;
 
-/*! \brief structure describing convolutional code EDGE MCS-3
+/*! structure describing EDGE MCS-3 data convolutional code:.
+ * 316 bits blocks, rate 1/3, k = 7
+ * G4 = 1 + D2 + D3 + D5 + D6
+ * G7 = 1 + D + D2 + D3 + D6
+ * G5 = 1 + D + D4 + D6
  */
 extern const struct osmo_conv_code gsm0503_mcs3;
 
-/*! \brief structure describing convolutional code EDGE MCS-4
+/*! structure describing EDGE MCS-4 data convolutional code:.
+ * 372 bits blocks, rate 1/3, k = 7
+ * G4 = 1 + D2 + D3 + D5 + D6
+ * G7 = 1 + D + D2 + D3 + D6
+ * G5 = 1 + D + D4 + D6
  */
 extern const struct osmo_conv_code gsm0503_mcs4;
 
-/*! \brief structure describing convolutional code EDGE MCS-5 DL HDR
+/*! structure describing EDGE MCS-5 DL header convolutional code:.
+ * 39 bits blocks, rate 1/3, k = 7
+ * G4 = 1 + D2 + D3 + D5 + D6
+ * G7 = 1 + D + D2 + D3 + D6
+ * G5 = 1 + D + D4 + D6
  */
 extern const struct osmo_conv_code gsm0503_mcs5_dl_hdr;
 
-/*! \brief structure describing convolutional code EDGE MCS-5 UL HDR
+/*! structure describing EDGE MCS-5 UL header convolutional code:.
+ * 51 bits blocks, rate 1/3, k = 7
+ * G4 = 1 + D2 + D3 + D5 + D6
+ * G7 = 1 + D + D2 + D3 + D6
+ * G5 = 1 + D + D4 + D6
  */
 extern const struct osmo_conv_code gsm0503_mcs5_ul_hdr;
 
-/*! \brief structure describing convolutional code EDGE MCS-5
+/*! structure describing EDGE MCS-5 data convolutional code:.
+ * 468 bits blocks, rate 1/3, k = 7
+ * G4 = 1 + D2 + D3 + D5 + D6
+ * G7 = 1 + D + D2 + D3 + D6
+ * G5 = 1 + D + D4 + D6
  */
 extern const struct osmo_conv_code gsm0503_mcs5;
 
-/*! \brief structure describing convolutional code EDGE MCS-6
+/*! structure describing EDGE MCS-6 data convolutional code:.
+ * 612 bits blocks, rate 1/3, k = 7
+ * G4 = 1 + D2 + D3 + D5 + D6
+ * G7 = 1 + D + D2 + D3 + D6
+ * G5 = 1 + D + D4 + D6
  */
 extern const struct osmo_conv_code gsm0503_mcs6;
 
-/*! \brief structure describing convolutional code EDGE MCS-7 DL HDR
+/*! structure describing EDGE MCS-7 DL header convolutional code:.
+ * 51 bits blocks, rate 1/3, k = 7
+ * G4 = 1 + D2 + D3 + D5 + D6
+ * G7 = 1 + D + D2 + D3 + D6
+ * G5 = 1 + D + D4 + D6
  */
 extern const struct osmo_conv_code gsm0503_mcs7_dl_hdr;
 
-/*! \brief structure describing convolutional code EDGE MCS-7 UL HDR
+/*! structure describing EDGE MCS-7 UL header convolutional code:.
+ * 60 bits blocks, rate 1/3, k = 7
+ * G4 = 1 + D2 + D3 + D5 + D6
+ * G7 = 1 + D + D2 + D3 + D6
+ * G5 = 1 + D + D4 + D6
  */
 extern const struct osmo_conv_code gsm0503_mcs7_ul_hdr;
 
-/*! \brief structure describing convolutional code EDGE MCS-7
+/*! structure describing EDGE MCS-7 data convolutional code:.
+ * 468 bits blocks, rate 1/3, k = 7
+ * G4 = 1 + D2 + D3 + D5 + D6
+ * G7 = 1 + D + D2 + D3 + D6
+ * G5 = 1 + D + D4 + D6
  */
 extern const struct osmo_conv_code gsm0503_mcs7;
 
-/*! \brief structure describing convolutional code EDGE MCS-8
+/*! structure describing EDGE MCS-8 data convolutional code:.
+ * 564 bits blocks, rate 1/3, k = 7
+ * G4 = 1 + D2 + D3 + D5 + D6
+ * G7 = 1 + D + D2 + D3 + D6
+ * G5 = 1 + D + D4 + D6
  */
 extern const struct osmo_conv_code gsm0503_mcs8;
 
-/*! \brief structure describing convolutional code EDGE MCS-9
+/*! structure describing EDGE MCS-9 data convolutional code:.
+ * 612 bits blocks, rate 1/3, k = 7
+ * G4 = 1 + D2 + D3 + D5 + D6
+ * G7 = 1 + D + D2 + D3 + D6
+ * G5 = 1 + D + D4 + D6
  */
 extern const struct osmo_conv_code gsm0503_mcs9;
 
-#ifdef __cplusplus
-}
-#endif
diff --git a/lib/decoding/osmocom/coding/gsm0503_coding.c b/lib/decoding/osmocom/coding/gsm0503_coding.c
index afbba88..3812c9f 100644
--- a/lib/decoding/osmocom/coding/gsm0503_coding.c
+++ b/lib/decoding/osmocom/coding/gsm0503_coding.c
@@ -2,9 +2,12 @@
  * (C) 2013 by Andreas Eversberg <jolly@eversberg.eu>
  * (C) 2015 by Alexander Chemeris <Alexander.Chemeris@fairwaves.co>
  * (C) 2016 by Tom Tsou <tom.tsou@ettus.com>
+ * (C) 2017 by Harald Welte <laforge@gnumonks.org>
  *
  * All Rights Reserved
  *
+ * SPDX-License-Identifier: GPL-2.0+
+ *
  * This program 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 2 of the License, or
@@ -24,32 +27,84 @@
 #include <stdint.h>
 #include <string.h>
 #include <stdlib.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
+#include <errno.h>
 
 #include <osmocom/core/bits.h>
 #include <osmocom/core/conv.h>
-#include <osmocom/core/utils.h>
+//#include <osmocom/core/utils.h>
 #include <osmocom/core/crcgen.h>
 #include <osmocom/core/endian.h>
 
-#include <osmocom/gsm/protocol/gsm_04_08.h>
-#include "gsm0503.h"
+//#include <osmocom/gsm/protocol/gsm_04_08.h>
+#include <osmocom/gprs/protocol/gsm_04_60.h>
+#include <osmocom/gprs/gprs_rlc.h>
+
+#include <osmocom/gsm/gsm0503.h>
 #include <osmocom/codec/codec.h>
 
-#include "gsm0503_interleaving.h"
-#include "gsm0503_mapping.h"
-#include "gsm0503_tables.h"
-#include "gsm0503_coding.h"
-#include "gsm0503_parity.h"
+#include <osmocom/coding/gsm0503_interleaving.h>
+#include <osmocom/coding/gsm0503_mapping.h>
+#include <osmocom/coding/gsm0503_tables.h>
+#include <osmocom/coding/gsm0503_coding.h>
+#include <osmocom/coding/gsm0503_parity.h>
 
-#ifdef __cplusplus
-}
-#endif
+/*! \mainpage libosmocoding Documentation
+ *
+ * \section sec_intro Introduction
+ * This library is a collection of definitions, tables and functions
+ * implementing the GSM/GPRS/EGPRS channel coding (and decoding) as
+ * specified in 3GPP TS 05.03 / 45.003.
+ *
+ * libosmocoding is developed as part of the Osmocom (Open Source Mobile
+ * Communications) project, a community-based, collaborative development
+ * project to create Free and Open Source implementations of mobile
+ * communications systems.  For more information about Osmocom, please
+ * see https://osmocom.org/
+ *
+ * \section sec_copyright Copyright and License
+ * Copyright © 2013 by Andreas Eversberg\n
+ * Copyright © 2015 by Alexander Chemeris\n
+ * Copyright © 2016 by Tom Tsou\n
+ * Documentation Copyright © 2017 by Harald Welte\n
+ * All rights reserved. \n\n
+ * The source code of libosmocoding is licensed under the terms of the GNU
+ * General Public License as published by the Free Software Foundation;
+ * either version 2 of the License, or (at your option) any later
+ * version.\n
+ * See <http://www.gnu.org/licenses/> or COPYING included in the source
+ * code package istelf.\n
+ * The information detailed here is provided AS IS with NO WARRANTY OF
+ * ANY KIND, INCLUDING THE WARRANTY OF DESIGN, MERCHANTABILITY AND
+ * FITNESS FOR A PARTICULAR PURPOSE.
+ * \n\n
+ *
+ * \section sec_tracker Homepage + Issue Tracker
+ * libosmocoding is distributed as part of libosmocore and shares its
+ * project page at http://osmocom.org/projects/libosmocore
+ *
+ * An Issue Tracker can be found at
+ * https://osmocom.org/projects/libosmocore/issues
+ *
+ * \section sec_contact Contact and Support
+ * Community-based support is available at the OpenBSC mailing list
+ * <http://lists.osmocom.org/mailman/listinfo/openbsc>\n
+ * Commercial support options available upon request from
+ * <http://sysmocom.de/>
+ */
 
 
+/*! \addtogroup coding
+ *  @{
+ *
+ *  GSM TS 05.03 coding
+ *
+ *  This module is the "master module" of libosmocoding. It uses the
+ *  various other modules (mapping, parity, interleaving) in order to
+ *  implement the complete channel coding (and decoding) chain for the
+ *  various channel types as defined in TS 05.03 / 45.003.
+ *
+ * \file gsm0503_coding.c */
+
 /*
  * EGPRS coding limits
  */
@@ -76,29 +131,49 @@
 #define EGPRS_DATA_C1		612
 #define EGPRS_DATA_C2		EGPRS_DATA_C1
 
-/* TS 101318 Chapter 5.1: 260 bits + 4bit sig */
-#define GSM_FR_BYTES	33
-/* TS 101318 Chapter 5.2: 112 bits, no sig */
-#define GSM_HR_BYTES	14
-/* TS 101318 Chapter 5.3: 244 bits + 4bit sig */
-#define GSM_EFR_BYTES	31
+/*! union across the three different EGPRS Uplink header types */
+union gprs_rlc_ul_hdr_egprs {
+	struct gprs_rlc_ul_header_egprs_1 type1;
+	struct gprs_rlc_ul_header_egprs_2 type2;
+	struct gprs_rlc_ul_header_egprs_3 type3;
+};
 
+/*! union across the three different EGPRS Downlink header types */
+union gprs_rlc_dl_hdr_egprs {
+	struct gprs_rlc_dl_header_egprs_1 type1;
+	struct gprs_rlc_dl_header_egprs_2 type2;
+	struct gprs_rlc_dl_header_egprs_3 type3;
+};
+
+/*! Structure describing a Modulation and Coding Scheme */
 struct gsm0503_mcs_code {
+	/*! Modulation and Coding Scheme (MSC) number */
 	uint8_t mcs;
+	/*! Length of Uplink Stealing Flag (USF) in bits */
 	uint8_t usf_len;
 
 	/* Header coding */
+	/*! Length of header (bits) */
 	uint8_t hdr_len;
+	/*! Length of header convolutional code */
 	uint8_t hdr_code_len;
+	/*! Length of header code puncturing sequence */
 	uint8_t hdr_punc_len;
+	/*! header convolutional code */
 	const struct osmo_conv_code *hdr_conv;
+	/*! header puncturing sequence */
 	const uint8_t *hdr_punc;
 
 	/* Data coding */
+	/*! length of data (bits) */
 	uint16_t data_len;
+	/*! length of data convolutional code */
 	uint16_t data_code_len;
+	/*! length of data code puncturing sequence */
 	uint16_t data_punc_len;
+	/*! data convolutional code */
 	const struct osmo_conv_code *data_conv;
+	/*! data puncturing sequences */
 	const uint8_t *data_punc[3];
 };
 
@@ -113,7 +188,7 @@
 
 	if (n_bits_total || n_errors) {
 		coded_len = osmo_conv_encode(code, output, recoded);
-		OSMO_ASSERT(sizeof(recoded) / sizeof(recoded[0]) >= coded_len);
+		//OSMO_ASSERT(sizeof(recoded) / sizeof(recoded[0]) >= coded_len);
 	}
 
 	/* Count bit errors */
@@ -132,7 +207,13 @@
 	return res;
 }
 
-static int _xcch_decode_cB(uint8_t *l2_data, sbit_t *cB,
+/*! convenience wrapper for decoding coded bits
+ *  \param[out] l2_data caller-allocated buffer for L2 Frame
+ *  \param[in] cB 456 coded (soft) bits as per TS 05.03 4.1.3
+ *  \param[out] n_errors Number of detected errors
+ *  \param[out] n_bits_total Number of total coded bits
+ *  \returns 0 on success; -1 on CRC error */
+static int _xcch_decode_cB(uint8_t *l2_data, const sbit_t *cB,
 	int *n_errors, int *n_bits_total)
 {
 	ubit_t conv[224];
@@ -151,7 +232,11 @@
 	return 0;
 }
 
-static int _xcch_encode_cB(ubit_t *cB, uint8_t *l2_data)
+/*! convenience wrapper for encoding to coded bits
+ *  \param[out] cB caller-allocated buffer for 456 coded bits as per TS 05.03 4.1.3
+ *  \param[out] l2_data to-be-encoded L2 Frame
+ *  \returns 0 */
+static int _xcch_encode_cB(ubit_t *cB, const uint8_t *l2_data)
 {
 	ubit_t conv[224];
 
@@ -167,7 +252,14 @@
 /*
  * GSM xCCH block transcoding
  */
-int gsm0503_xcch_decode(uint8_t *l2_data, sbit_t *bursts,
+
+/*! Decoding of xCCH data from bursts to L2 frame
+ *  \param[out] l2_data caller-allocated output data buffer
+ *  \param[in] bursts four GSM bursts in soft-bits
+ *  \param[out] n_errors Number of detected errors
+ *  \param[out] n_bits_total Number of total coded bits
+ */
+int gsm0503_xcch_decode(uint8_t *l2_data, const sbit_t *bursts,
 	int *n_errors, int *n_bits_total)
 {
 	sbit_t iB[456], cB[456];
@@ -181,7 +273,12 @@
 	return _xcch_decode_cB(l2_data, cB, n_errors, n_bits_total);
 }
 
-int gsm0503_xcch_encode(ubit_t *bursts, uint8_t *l2_data)
+/*! Encoding of xCCH data from L2 frame to bursts
+ *  \param[out] bursts caller-allocated burst data (unpacked bits)
+ *  \param[in] l2_data L2 input data (MAC block)
+ *  \returns 0
+ */
+int gsm0503_xcch_encode(ubit_t *bursts, const uint8_t *l2_data)
 {
 	ubit_t iB[456], cB[456], hl = 1, hn = 1;
 	int i;
@@ -202,7 +299,14 @@
  * GSM PDTCH block transcoding
  */
 
-int gsm0503_pdtch_decode(uint8_t *l2_data, sbit_t *bursts, uint8_t *usf_p,
+/*! Decode GPRS PDTCH
+ *  \param[out] l2_data caller-allocated buffer for L2 Frame
+ *  \param[in] bursts burst input data as soft unpacked bits
+ *  \param[out] usf_p uplink stealing flag
+ *  \param[out] n_errors number of detected bit-errors
+ *  \param[out] n_bits_total total number of dcoded bits
+ *  \returns 0 on success; negative on error */
+int gsm0503_pdtch_decode(uint8_t *l2_data, const sbit_t *bursts, uint8_t *usf_p,
 	int *n_errors, int *n_bits_total)
 {
 	sbit_t iB[456], cB[676], hl_hn[8];
@@ -219,7 +323,7 @@
 
 		if (i == 0 || k < best) {
 			best = k;
-			cs = i+1;
+			cs = i + 1;
 		}
 	}
 
@@ -246,7 +350,7 @@
 				cB[i] = 0;
 		}
 
-		osmo_conv_decode_ber(&gsm0503_cs2, cB,
+		osmo_conv_decode_ber(&gsm0503_cs2_np, cB,
 			conv, n_errors, n_bits_total);
 
 		for (i = 0; i < 8; i++) {
@@ -281,7 +385,7 @@
 				cB[i] = 0;
 		}
 
-		osmo_conv_decode_ber(&gsm0503_cs3, cB,
+		osmo_conv_decode_ber(&gsm0503_cs3_np, cB,
 			conv, n_errors, n_bits_total);
 
 		for (i = 0; i < 8; i++) {
@@ -351,7 +455,13 @@
 	return -1;
 }
 
-int gsm0503_pdtch_encode(ubit_t *bursts, uint8_t *l2_data, uint8_t l2_len)
+
+/*! GPRS DL message encoding
+ *  \param[out] bursts caller-allocated buffer for unpacked burst bits
+ *  \param[in] l2_data L2 (MAC) block to be encoded
+ *  \param[in] l2_len length of l2_data in bytes, used to determine CS
+ *  \returns 0 on success; negative on error */
+int gsm0503_pdtch_encode(ubit_t *bursts, const uint8_t *l2_data, uint8_t l2_len)
 {
 	ubit_t iB[456], cB[676];
 	const ubit_t *hl_hn;
@@ -378,7 +488,7 @@
 
 		memcpy(conv, gsm0503_usf2six[usf], 6);
 
-		osmo_conv_encode(&gsm0503_cs2, conv, cB);
+		osmo_conv_encode(&gsm0503_cs2_np, conv, cB);
 
 		for (i = 0, j = 0; i < 588; i++)
 			if (!gsm0503_puncture_cs2[i])
@@ -396,7 +506,7 @@
 
 		memcpy(conv, gsm0503_usf2six[usf], 6);
 
-		osmo_conv_encode(&gsm0503_cs3, conv, cB);
+		osmo_conv_encode(&gsm0503_cs3_np, conv, cB);
 
 		for (i = 0, j = 0; i < 676; i++)
 			if (!gsm0503_puncture_cs3[i])
@@ -435,8 +545,12 @@
  * GSM TCH/F FR/EFR transcoding
  */
 
+/*! assemble a FR codec frame in format as used inside RTP
+ *  \param[out] tch_data Codec frame in RTP format
+ *  \param[in] b_bits Codec frame in 'native' format
+ *  \param[in] net_order FIXME */
 static void tch_fr_reassemble(uint8_t *tch_data,
-	ubit_t *b_bits, int net_order)
+	const ubit_t *b_bits, int net_order)
 {
 	int i, j, k, l, o;
 
@@ -468,7 +582,7 @@
 }
 
 static void tch_fr_disassemble(ubit_t *b_bits,
-	uint8_t *tch_data, int net_order)
+	const uint8_t *tch_data, int net_order)
 {
 	int i, j, k, l, o;
 
@@ -495,7 +609,8 @@
 	}
 }
 
-static void tch_hr_reassemble(uint8_t *tch_data, ubit_t *b_bits)
+/* assemble a HR codec frame in format as used inside RTP */
+static void tch_hr_reassemble(uint8_t *tch_data, const ubit_t *b_bits)
 {
 	int i, j;
 
@@ -506,7 +621,7 @@
 		tch_data[j >> 3] |= (b_bits[i] << (7 - (j & 7)));
 }
 
-static void tch_hr_disassemble(ubit_t *b_bits, uint8_t *tch_data)
+static void tch_hr_disassemble(ubit_t *b_bits, const uint8_t *tch_data)
 {
 	int i, j;
 
@@ -514,7 +629,8 @@
 		b_bits[i] = (tch_data[j >> 3] >> (7 - (j & 7))) & 1;
 }
 
-static void tch_efr_reassemble(uint8_t *tch_data, ubit_t *b_bits)
+/* assemble a EFR codec frame in format as used inside RTP */
+static void tch_efr_reassemble(uint8_t *tch_data, const ubit_t *b_bits)
 {
 	int i, j;
 
@@ -525,7 +641,7 @@
 		tch_data[j >> 3] |= (b_bits[i] << (7 - (j & 7)));
 }
 
-static void tch_efr_disassemble(ubit_t *b_bits, uint8_t *tch_data)
+static void tch_efr_disassemble(ubit_t *b_bits, const uint8_t *tch_data)
 {
 	int i, j;
 
@@ -533,7 +649,8 @@
 		b_bits[i] = (tch_data[j >> 3] >> (7 - (j & 7))) & 1;
 }
 
-static void tch_amr_reassemble(uint8_t *tch_data, ubit_t *d_bits, int len)
+/* assemble a AMR codec frame in format as used inside RTP */
+static void tch_amr_reassemble(uint8_t *tch_data, const ubit_t *d_bits, int len)
 {
 	int i, j;
 
@@ -543,7 +660,7 @@
 		tch_data[j >> 3] |= (d_bits[i] << (7 - (j & 7)));
 }
 
-static void tch_amr_disassemble(ubit_t *d_bits, uint8_t *tch_data, int len)
+static void tch_amr_disassemble(ubit_t *d_bits, const uint8_t *tch_data, int len)
 {
 	int i, j;
 
@@ -551,7 +668,8 @@
 		d_bits[i] = (tch_data[j >> 3] >> (7 - (j & 7))) & 1;
 }
 
-static void tch_fr_d_to_b(ubit_t *b_bits, ubit_t *d_bits)
+/* re-arrange according to TS 05.03 Table 2 (receiver) */
+static void tch_fr_d_to_b(ubit_t *b_bits, const ubit_t *d_bits)
 {
 	int i;
 
@@ -559,7 +677,8 @@
 		b_bits[gsm610_bitorder[i]] = d_bits[i];
 }
 
-static void tch_fr_b_to_d(ubit_t *d_bits, ubit_t *b_bits)
+/* re-arrange according to TS 05.03 Table 2 (transmitter) */
+static void tch_fr_b_to_d(ubit_t *d_bits, const ubit_t *b_bits)
 {
 	int i;
 
@@ -567,7 +686,8 @@
 		d_bits[i] = b_bits[gsm610_bitorder[i]];
 }
 
-static void tch_hr_d_to_b(ubit_t *b_bits, ubit_t *d_bits)
+/* re-arrange according to TS 05.03 Table 3a (receiver) */
+static void tch_hr_d_to_b(ubit_t *b_bits, const ubit_t *d_bits)
 {
 	int i;
 
@@ -582,7 +702,8 @@
 		b_bits[map[i]] = d_bits[i];
 }
 
-static void tch_hr_b_to_d(ubit_t *d_bits, ubit_t *b_bits)
+/* re-arrange according to TS 05.03 Table 3a (transmitter) */
+static void tch_hr_b_to_d(ubit_t *d_bits, const ubit_t *b_bits)
 {
 	int i;
 	const uint16_t *map;
@@ -596,7 +717,8 @@
 		d_bits[i] = b_bits[map[i]];
 }
 
-static void tch_efr_d_to_w(ubit_t *b_bits, ubit_t *d_bits)
+/* re-arrange according to TS 05.03 Table 6 (receiver) */
+static void tch_efr_d_to_w(ubit_t *b_bits, const ubit_t *d_bits)
 {
 	int i;
 
@@ -604,7 +726,8 @@
 		b_bits[gsm660_bitorder[i]] = d_bits[i];
 }
 
-static void tch_efr_w_to_d(ubit_t *d_bits, ubit_t *b_bits)
+/* re-arrange according to TS 05.03 Table 6 (transmitter) */
+static void tch_efr_w_to_d(ubit_t *d_bits, const ubit_t *b_bits)
 {
 	int i;
 
@@ -612,7 +735,8 @@
 		d_bits[i] = b_bits[gsm660_bitorder[i]];
 }
 
-static void tch_efr_protected(ubit_t *s_bits, ubit_t *b_bits)
+/* extract the 65 protected class1a+1b bits */
+static void tch_efr_protected(const ubit_t *s_bits, ubit_t *b_bits)
 {
 	int i;
 
@@ -620,7 +744,7 @@
 		b_bits[i] = s_bits[gsm0503_gsm_efr_protected_bits[i] - 1];
 }
 
-static void tch_fr_unreorder(ubit_t *d, ubit_t *p, ubit_t *u)
+static void tch_fr_unreorder(ubit_t *d, ubit_t *p, const ubit_t *u)
 {
 	int i;
 
@@ -633,7 +757,7 @@
 		p[i] = u[91 + i];
 }
 
-static void tch_fr_reorder(ubit_t *u, ubit_t *d, ubit_t *p)
+static void tch_fr_reorder(ubit_t *u, const ubit_t *d, const ubit_t *p)
 {
 	int i;
 
@@ -646,19 +770,19 @@
 		u[91 + i] = p[i];
 }
 
-static void tch_hr_unreorder(ubit_t *d, ubit_t *p, ubit_t *u)
+static void tch_hr_unreorder(ubit_t *d, ubit_t *p, const ubit_t *u)
 {
 	memcpy(d, u, 95);
 	memcpy(p, u + 95, 3);
 }
 
-static void tch_hr_reorder(ubit_t *u, ubit_t *d, ubit_t *p)
+static void tch_hr_reorder(ubit_t *u, const ubit_t *d, const ubit_t *p)
 {
 	memcpy(u, d, 95);
 	memcpy(u + 95, p, 3);
 }
 
-static void tch_efr_reorder(ubit_t *w, ubit_t *s, ubit_t *p)
+static void tch_efr_reorder(ubit_t *w, const ubit_t *s, const ubit_t *p)
 {
 	memcpy(w, s, 71);
 	w[71] = w[72] = s[69];
@@ -672,55 +796,66 @@
 	memcpy(w + 252, p, 8);
 }
 
-static void tch_efr_unreorder(ubit_t *s, ubit_t *p, ubit_t *w)
+static void tch_efr_unreorder(ubit_t *s, ubit_t *p, const ubit_t *w)
 {
 	int sum;
 
 	memcpy(s, w, 71);
 	sum = s[69] + w[71] + w[72];
-	s[69] = (sum > 2);
+	s[69] = (sum >= 2);
 	memcpy(s + 71, w + 73, 50);
 	sum = s[119] + w[123] + w[124];
-	s[119] = (sum > 2);
+	s[119] = (sum >= 2);
 	memcpy(s + 121, w + 125, 53);
 	sum = s[172] + w[178] + w[179];
 	s[172] = (sum > 2);
 	memcpy(s + 174, w + 180, 50);
-	sum = s[220] + w[230] + w[231];
-	s[222] = (sum > 2);
+	sum = s[222] + w[230] + w[231];
+	s[222] = (sum >= 2);
 	memcpy(s + 224, w + 232, 20);
 	memcpy(p, w + 252, 8);
 }
 
-static void tch_amr_merge(ubit_t *u, ubit_t *d, ubit_t *p, int len, int prot)
+static void tch_amr_merge(ubit_t *u, const ubit_t *d, const ubit_t *p, int len, int prot)
 {
 	memcpy(u, d, prot);
 	memcpy(u + prot, p, 6);
 	memcpy(u + prot + 6, d + prot, len - prot);
 }
 
-static void tch_amr_unmerge(ubit_t *d, ubit_t *p,
-	ubit_t *u, int len, int prot)
+static void tch_amr_unmerge(ubit_t *d, ubit_t *p, const ubit_t *u, int len, int prot)
 {
 	memcpy(d, u, prot);
-	memcpy(p, u+prot, 6);
+	memcpy(p, u + prot, 6);
 	memcpy(d + prot, u + prot + 6, len - prot);
 }
 
-int gsm0503_tch_fr_decode(uint8_t *tch_data, sbit_t *bursts,
+/*! Perform channel decoding of a FR/EFR channel according TS 05.03
+ *  \param[out] tch_data Codec frame in RTP payload format
+ *  \param[in] bursts buffer containing the symbols of 8 bursts
+ *  \param[in] net_order FIXME
+ *  \param[in] efr Is this channel using EFR (1) or FR (0)
+ *  \param[out] n_errors Number of detected bit errors
+ *  \param[out] n_bits_total Total number of bits
+ *  \returns length of bytes used in \a tch_data output buffer */
+int gsm0503_tch_fr_decode(uint8_t *tch_data, const sbit_t *bursts,
 	int net_order, int efr, int *n_errors, int *n_bits_total)
 {
 	sbit_t iB[912], cB[456], h;
 	ubit_t conv[185], s[244], w[260], b[65], d[260], p[8];
 	int i, rv, len, steal = 0;
 
-	for (i=0; i<8; i++) {
+	/* map from 8 bursts to interleaved data bits (iB) */
+	for (i = 0; i < 8; i++) {
 		gsm0503_tch_burst_unmap(&iB[i * 114],
 			&bursts[i * 116], &h, i >> 2);
 		steal -= h;
 	}
+	/* we now have the bits of the four bursts (interface 4 in
+	 * Figure 1a of TS 05.03 */
 
 	gsm0503_tch_fr_deinterleave(cB, iB);
+	/* we now have the coded bits c(B): interface 3 in Fig. 1a */
 
 	if (steal > 0) {
 		rv = _xcch_decode_cB(tch_data, cB, n_errors, n_bits_total);
@@ -733,12 +868,15 @@
 	}
 
 	osmo_conv_decode_ber(&gsm0503_tch_fr, cB, conv, n_errors, n_bits_total);
+	/* we now have the data bits 'u': interface 2 in Fig. 1a */
 
+	/* input: 'conv', output: d[ata] + p[arity] */
 	tch_fr_unreorder(d, p, conv);
 
 	for (i = 0; i < 78; i++)
 		d[i + 182] = (cB[i + 378] < 0) ? 1 : 0;
 
+	/* check if parity of first 50 (class 1) 'd'-bits match 'p' */
 	rv = osmo_crc8gen_check_bits(&gsm0503_tch_fr_crc3, d, 50, p);
 	if (rv) {
 		/* Error checking CRC8 for the FR part of an EFR/FR frame */
@@ -747,11 +885,17 @@
 
 	if (efr) {
 		tch_efr_d_to_w(w, d);
+		/* we now have the preliminary-coded bits w(k) */
 
 		tch_efr_unreorder(s, p, w);
+		/* we now have the data delivered to the preliminary
+		 * channel encoding unit s(k) */
 
+		/* extract the 65 most important bits according TS 05.03 3.1.1.1 */
 		tch_efr_protected(s, b);
 
+		/* perform CRC-8 on 65 most important bits (50 bits of
+		 * class 1a + 15 bits of class 1b) */
 		rv = osmo_crc8gen_check_bits(&gsm0503_tch_efr_crc8, b, 65, p);
 		if (rv) {
 			/* Error checking CRC8 for the EFR part of an EFR frame */
@@ -772,7 +916,13 @@
 	return len;
 }
 
-int gsm0503_tch_fr_encode(ubit_t *bursts, uint8_t *tch_data,
+/*! Perform channel encoding on a TCH/FS channel according to TS 05.03
+ *  \param[out] bursts caller-allocated output buffer for bursts bits
+ *  \param[in] tch_data Codec input data in RTP payload format
+ *  \param[in] len Length of \a tch_data in bytes
+ *  \param[in] net_order FIXME
+ *  \returns 0 in case of success; negative on error */
+int gsm0503_tch_fr_encode(ubit_t *bursts, const uint8_t *tch_data,
 	int len, int net_order)
 {
 	ubit_t iB[912], cB[456], h;
@@ -830,7 +980,14 @@
 	return 0;
 }
 
-int gsm0503_tch_hr_decode(uint8_t *tch_data, sbit_t *bursts, int odd,
+/*! Perform channel decoding of a HR(v1) channel according TS 05.03
+ *  \param[out] tch_data Codec frame in RTP payload format
+ *  \param[in] bursts buffer containing the symbols of 8 bursts
+ *  \param[in] odd Odd (1) or even (0) frame number
+ *  \param[out] n_errors Number of detected bit errors
+ *  \param[out] n_bits_total Total number of bits
+ *  \returns length of bytes used in \a tch_data output buffer */
+int gsm0503_tch_hr_decode(uint8_t *tch_data, const sbit_t *bursts, int odd,
 	int *n_errors, int *n_bits_total)
 {
 	sbit_t iB[912], cB[456], h;
@@ -900,7 +1057,12 @@
 	return 15;
 }
 
-int gsm0503_tch_hr_encode(ubit_t *bursts, uint8_t *tch_data, int len)
+/*! Perform channel encoding on a TCH/HS channel according to TS 05.03
+ *  \param[out] bursts caller-allocated output buffer for bursts bits
+ *  \param[in] tch_data Codec input data in RTP payload format
+ *  \param[in] len Length of \a tch_data in bytes
+ *  \returns 0 in case of success; negative on error */
+int gsm0503_tch_hr_encode(ubit_t *bursts, const uint8_t *tch_data, int len)
 {
 	ubit_t iB[912], cB[456], h;
 	ubit_t conv[98], b[112], d[112], p[3];
@@ -937,12 +1099,12 @@
 
 		gsm0503_tch_fr_interleave(cB, iB);
 
-		for (i=0; i<6; i++) {
+		for (i = 0; i < 6; i++) {
 			gsm0503_tch_burst_map(&iB[i * 114],
 				&bursts[i * 116], &h, i >> 2);
 		}
 
-		for (i=2; i<4; i++) {
+		for (i = 2; i < 4; i++) {
 			gsm0503_tch_burst_map(&iB[i * 114 + 456],
 				&bursts[i * 116], &h, 1);
 		}
@@ -955,7 +1117,18 @@
 	return 0;
 }
 
-int gsm0503_tch_afs_decode(uint8_t *tch_data, sbit_t *bursts,
+/*! Perform channel decoding of a TCH/AFS channel according TS 05.03
+ *  \param[out] tch_data Codec frame in RTP payload format
+ *  \param[in] bursts buffer containing the symbols of 8 bursts
+ *  \param[in] codec_mode_req is this CMR (1) or CMC (0)
+ *  \param[in] codec array of active codecs (active codec set)
+ *  \param[in] codecs number of codecs in \a codec
+ *  \param ft Frame Type; Input if \a codec_mode_req = 1, Output *  otherwise
+ *  \param[out] cmr Output in \a codec_mode_req = 1
+ *  \param[out] n_errors Number of detected bit errors
+ *  \param[out] n_bits_total Total number of bits
+ *  \returns length of bytes used in \a tch_data output buffer */
+int gsm0503_tch_afs_decode(uint8_t *tch_data, const sbit_t *bursts,
 	int codec_mode_req, uint8_t *codec, int codecs, uint8_t *ft,
 	uint8_t *cmr, int *n_errors, int *n_bits_total)
 {
@@ -1150,7 +1323,17 @@
 	return len;
 }
 
-int gsm0503_tch_afs_encode(ubit_t *bursts, uint8_t *tch_data, int len,
+/*! Perform channel encoding on a TCH/AFS channel according to TS 05.03
+ *  \param[out] bursts caller-allocated output buffer for bursts bits
+ *  \param[in] tch_data Codec input data in RTP payload format
+ *  \param[in] len Length of \a tch_data in bytes
+ *  \param[in] codec_mode_req Use CMR (1) or FT (0)
+ *  \param[in] codec Array of codecs (active codec set)
+ *  \param[in] codecs Number of entries in \a codec
+ *  \param[in] ft Frame Type to be used for encoding (index to \a codec)
+ *  \param[in] cmr Codec Mode Request (used in codec_mode_req = 1 only)
+ *  \returns 0 in case of success; negative on error */
+int gsm0503_tch_afs_encode(ubit_t *bursts, const uint8_t *tch_data, int len,
 	int codec_mode_req, uint8_t *codec, int codecs, uint8_t ft,
 	uint8_t cmr)
 {
@@ -1310,7 +1493,19 @@
 	return -1;
 }
 
-int gsm0503_tch_ahs_decode(uint8_t *tch_data, sbit_t *bursts, int odd,
+/*! Perform channel decoding of a TCH/AFS channel according TS 05.03
+ *  \param[out] tch_data Codec frame in RTP payload format
+ *  \param[in] bursts buffer containing the symbols of 8 bursts
+ *  \param[in] odd Is this an odd (1) or even (0) frame number?
+ *  \param[in] codec_mode_req is this CMR (1) or CMC (0)
+ *  \param[in] codec array of active codecs (active codec set)
+ *  \param[in] codecs number of codecs in \a codec
+ *  \param ft Frame Type; Input if \a codec_mode_req = 1, Output *  otherwise
+ *  \param[out] cmr Output in \a codec_mode_req = 1
+ *  \param[out] n_errors Number of detected bit errors
+ *  \param[out] n_bits_total Total number of bits
+ *  \returns length of bytes used in \a tch_data output buffer */
+int gsm0503_tch_ahs_decode(uint8_t *tch_data, const sbit_t *bursts, int odd,
 	int codec_mode_req, uint8_t *codec, int codecs, uint8_t *ft,
 	uint8_t *cmr, int *n_errors, int *n_bits_total)
 {
@@ -1513,7 +1708,17 @@
 	return len;
 }
 
-int gsm0503_tch_ahs_encode(ubit_t *bursts, uint8_t *tch_data, int len,
+/*! Perform channel encoding on a TCH/AHS channel according to TS 05.03
+ *  \param[out] bursts caller-allocated output buffer for bursts bits
+ *  \param[in] tch_data Codec input data in RTP payload format
+ *  \param[in] len Length of \a tch_data in bytes
+ *  \param[in] codec_mode_req Use CMR (1) or FT (0)
+ *  \param[in] codec Array of codecs (active codec set)
+ *  \param[in] codecs Number of entries in \a codec
+ *  \param[in] ft Frame Type to be used for encoding (index to \a codec)
+ *  \param[in] cmr Codec Mode Request (used in codec_mode_req = 1 only)
+ *  \returns 0 in case of success; negative on error */
+int gsm0503_tch_ahs_encode(ubit_t *bursts, const uint8_t *tch_data, int len,
 	int codec_mode_req, uint8_t *codec, int codecs, uint8_t ft,
 	uint8_t cmr)
 {
@@ -1676,46 +1881,140 @@
  * b(0) = MSB of PLMN colour code
  * b(5) = LSB of BS colour code
  */
-static int rach_apply_bsic(ubit_t *d, uint8_t bsic)
+static inline void rach_apply_bsic(ubit_t *d, uint8_t bsic, uint8_t start)
 {
 	int i;
 
 	/* Apply it */
 	for (i = 0; i < 6; i++)
-		d[8 + i] ^= ((bsic >> (5 - i)) & 1);
-
-	return 0;
+		d[start + i] ^= ((bsic >> (5 - i)) & 1);
 }
 
-int gsm0503_rach_decode(uint8_t *ra, sbit_t *burst, uint8_t bsic)
+static inline int16_t rach_decode_ber(const sbit_t *burst, uint8_t bsic, bool is_11bit,
+				      int *n_errors, int *n_bits_total)
 {
-	ubit_t conv[14];
+	ubit_t conv[17];
+	uint8_t ra[2] = { 0 }, nbits = is_11bit ? 11 : 8;
 	int rv;
 
-	osmo_conv_decode(&gsm0503_rach, burst, conv);
+	osmo_conv_decode_ber(is_11bit ? &gsm0503_rach_ext : &gsm0503_rach, burst, conv,
+			     n_errors, n_bits_total);
 
-	rach_apply_bsic(conv, bsic);
+	rach_apply_bsic(conv, bsic, nbits);
 
-	rv = osmo_crc8gen_check_bits(&gsm0503_rach_crc6, conv, 8, conv + 8);
+	rv = osmo_crc8gen_check_bits(&gsm0503_rach_crc6, conv, nbits, conv + nbits);
 	if (rv)
 		return -1;
 
-	osmo_ubit2pbit_ext(ra, 0, conv, 0, 8, 1);
+	osmo_ubit2pbit_ext(ra, 0, conv, 0, nbits, 1);
+
+	return is_11bit ? osmo_load16le(ra) : ra[0];
+}
+
+/*! Decode the Extended (11-bit) RACH according to 3GPP TS 45.003
+ *  \param[out] ra output buffer for RACH data
+ *  \param[in] burst Input burst data
+ *  \param[in] bsic BSIC used in this cell
+ *  \returns 0 on success; negative on error (e.g. CRC error) */
+int gsm0503_rach_ext_decode(uint16_t *ra, const sbit_t *burst, uint8_t bsic)
+{
+	int16_t r = rach_decode_ber(burst, bsic, true, NULL, NULL);
+
+	if (r < 0)
+		return r;
+
+	*ra = r;
 
 	return 0;
 }
 
-int gsm0503_rach_encode(ubit_t *burst, uint8_t *ra, uint8_t bsic)
+/*! Decode the (8-bit) RACH according to TS 05.03
+ *  \param[out] ra output buffer for RACH data
+ *  \param[in] burst Input burst data
+ *  \param[in] bsic BSIC used in this cell
+ *  \returns 0 on success; negative on error (e.g. CRC error) */
+int gsm0503_rach_decode(uint8_t *ra, const sbit_t *burst, uint8_t bsic)
 {
-	ubit_t conv[14];
+	int16_t r = rach_decode_ber(burst, bsic, false, NULL, NULL);
+	if (r < 0)
+		return r;
 
-	osmo_pbit2ubit_ext(conv, 0, ra, 0, 8, 1);
+	*ra = r;
+	return 0;
+}
 
-	osmo_crc8gen_set_bits(&gsm0503_rach_crc6, conv, 8, conv + 8);
+/*! Decode the Extended (11-bit) RACH according to 3GPP TS 45.003
+ *  \param[out] ra output buffer for RACH data
+ *  \param[in] burst Input burst data
+ *  \param[in] bsic BSIC used in this cell
+ *  \param[out] n_errors Number of detected bit errors
+ *  \param[out] n_bits_total Total number of bits
+ *  \returns 0 on success; negative on error (e.g. CRC error) */
+int gsm0503_rach_ext_decode_ber(uint16_t *ra, const sbit_t *burst, uint8_t bsic,
+				int *n_errors, int *n_bits_total)
+{
+	int16_t r = rach_decode_ber(burst, bsic, true, n_errors, n_bits_total);
+	if (r < 0)
+		return r;
 
-	rach_apply_bsic(conv, bsic);
+	*ra = r;
+	return 0;
+}
 
-	osmo_conv_encode(&gsm0503_rach, conv, burst);
+/*! Decode the (8-bit) RACH according to TS 05.03
+ *  \param[out] ra output buffer for RACH data
+ *  \param[in] burst Input burst data
+ *  \param[in] bsic BSIC used in this cell
+ *  \param[out] n_errors Number of detected bit errors
+ *  \param[out] n_bits_total Total number of bits
+ *  \returns 0 on success; negative on error (e.g. CRC error) */
+int gsm0503_rach_decode_ber(uint8_t *ra, const sbit_t *burst, uint8_t bsic,
+			    int *n_errors, int *n_bits_total)
+{
+	int16_t r = rach_decode_ber(burst, bsic, false, n_errors, n_bits_total);
+
+	if (r < 0)
+		return r;
+
+	*ra = r;
+
+	return 0;
+}
+
+/*! Encode the (8-bit) RACH according to TS 05.03
+ *  \param[out] burst Caller-allocated output burst buffer
+ *  \param[in] ra Input RACH data
+ *  \param[in] bsic BSIC used in this cell
+ *  \returns 0 on success; negative on error */
+int gsm0503_rach_encode(ubit_t *burst, const uint8_t *ra, uint8_t bsic)
+{
+	return gsm0503_rach_ext_encode(burst, *ra, bsic, false);
+}
+
+/*! Encode the Extended (11-bit) or regular (8-bit) RACH according to 3GPP TS 45.003
+ *  \param[out] burst Caller-allocated output burst buffer
+ *  \param[in] ra11 Input RACH data
+ *  \param[in] bsic BSIC used in this cell
+ *  \param[in] is_11bit whether given RA is 11 bit or not
+ *  \returns 0 on success; negative on error */
+int gsm0503_rach_ext_encode(ubit_t *burst, uint16_t ra11, uint8_t bsic, bool is_11bit)
+{
+	ubit_t conv[17];
+	uint8_t ra[2] = { 0 }, nbits = 8;
+
+	if (is_11bit) {
+		osmo_store16le(ra11, ra);
+		nbits = 11;
+	} else
+		ra[0] = (uint8_t)ra11;
+
+	osmo_pbit2ubit_ext(conv, 0, ra, 0, nbits, 1);
+
+	osmo_crc8gen_set_bits(&gsm0503_rach_crc6, conv, nbits, conv + nbits);
+
+	rach_apply_bsic(conv, bsic, nbits);
+
+	osmo_conv_encode(is_11bit ? &gsm0503_rach_ext : &gsm0503_rach, conv, burst);
 
 	return 0;
 }
@@ -1723,7 +2022,12 @@
 /*
  * GSM SCH transcoding
  */
-int gsm0503_sch_decode(uint8_t *sb_info, sbit_t *burst)
+
+/*! Decode the SCH according to TS 05.03
+ *  \param[out] sb_info output buffer for SCH data
+ *  \param[in] burst Input burst data
+ *  \returns 0 on success; negative on error (e.g. CRC error) */
+int gsm0503_sch_decode(uint8_t *sb_info, const sbit_t *burst)
 {
 	ubit_t conv[35];
 	int rv;
@@ -1739,7 +2043,11 @@
 	return 0;
 }
 
-int gsm0503_sch_encode(ubit_t *burst, uint8_t *sb_info)
+/*! Encode the SCH according to TS 05.03
+ *  \param[out] burst Caller-allocated output burst buffer
+ *  \param[in] sb_info Input SCH data
+ *  \returns 0 on success; negative on error */
+int gsm0503_sch_encode(ubit_t *burst, const uint8_t *sb_info)
 {
 	ubit_t conv[35];
 
@@ -1751,3 +2059,5 @@
 
 	return 0;
 }
+
+/*! @} */
diff --git a/lib/decoding/osmocom/coding/gsm0503_coding.h b/lib/decoding/osmocom/coding/gsm0503_coding.h
index 5e3e9db..98038f8 100644
--- a/lib/decoding/osmocom/coding/gsm0503_coding.h
+++ b/lib/decoding/osmocom/coding/gsm0503_coding.h
@@ -1,68 +1,83 @@
-/*
- * (C) 2013 by Andreas Eversberg <jolly@eversberg.eu>
- * (C) 2015 by Alexander Chemeris <Alexander.Chemeris@fairwaves.co>
- * (C) 2016 by Tom Tsou <tom.tsou@ettus.com>
- *
- * All Rights Reserved
- *
- * This program 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 2 of the License, or
- * (at your option) any later version.
- *
- * This program 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 this program; if not, write to the Free Software Foundation, Inc.,
- * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+/*! \file gsm0503_coding.h
+ *  GSM TS 05.03 coding
  */
 
 #pragma once
 
 #include <stdint.h>
+
+#include <osmocom/core/defs.h>
 #include <osmocom/core/bits.h>
 
+/*! \addtogroup coding
+ *  @{
+ * \file gsm0503_coding.h */
+
 #define GSM0503_GPRS_BURSTS_NBITS	(116 * 4)
 #define GSM0503_EGPRS_BURSTS_NBITS	(348 * 4)
-#define NUM_BYTES(N) ((N + 8 - 1) / 8)
 
+enum gsm0503_egprs_mcs {
+	EGPRS_MCS0,
+	EGPRS_MCS1,
+	EGPRS_MCS2,
+	EGPRS_MCS3,
+	EGPRS_MCS4,
+	EGPRS_MCS5,
+	EGPRS_MCS6,
+	EGPRS_MCS7,
+	EGPRS_MCS8,
+	EGPRS_MCS9,
+	EGPRS_NUM_MCS,
+};
 
-
-int gsm0503_xcch_encode(ubit_t *bursts, uint8_t *l2_data);
-int gsm0503_xcch_decode(uint8_t *l2_data, sbit_t *bursts,
+int gsm0503_xcch_encode(ubit_t *bursts, const uint8_t *l2_data);
+int gsm0503_xcch_decode(uint8_t *l2_data, const sbit_t *bursts,
 	int *n_errors, int *n_bits_total);
 
-int gsm0503_pdtch_encode(ubit_t *bursts, uint8_t *l2_data, uint8_t l2_len);
-int gsm0503_pdtch_decode(uint8_t *l2_data, sbit_t *bursts, uint8_t *usf_p,
+int gsm0503_pdtch_encode(ubit_t *bursts, const uint8_t *l2_data, uint8_t l2_len);
+int gsm0503_pdtch_decode(uint8_t *l2_data, const sbit_t *bursts, uint8_t *usf_p,
 	int *n_errors, int *n_bits_total);
 
-int gsm0503_tch_fr_encode(ubit_t *bursts, uint8_t *tch_data, int len,
+int gsm0503_pdtch_egprs_encode(ubit_t *bursts, const uint8_t *l2_data,
+	uint8_t l2_len);
+int gsm0503_pdtch_egprs_decode(uint8_t *l2_data, const sbit_t *bursts,
+	uint16_t nbits, uint8_t *usf_p, int *n_errors, int *n_bits_total);
+
+int gsm0503_tch_fr_encode(ubit_t *bursts, const uint8_t *tch_data, int len,
 	int net_order);
-int gsm0503_tch_fr_decode(uint8_t *tch_data, sbit_t *bursts, int net_order,
+int gsm0503_tch_fr_decode(uint8_t *tch_data, const sbit_t *bursts, int net_order,
 	int efr, int *n_errors, int *n_bits_total);
 
-int gsm0503_tch_hr_encode(ubit_t *bursts, uint8_t *tch_data, int len);
-int gsm0503_tch_hr_decode(uint8_t *tch_data, sbit_t *bursts, int odd,
+int gsm0503_tch_hr_encode(ubit_t *bursts, const uint8_t *tch_data, int len);
+int gsm0503_tch_hr_decode(uint8_t *tch_data, const sbit_t *bursts, int odd,
 	int *n_errors, int *n_bits_total);
 
-int gsm0503_tch_afs_encode(ubit_t *bursts, uint8_t *tch_data, int len,
+int gsm0503_tch_afs_encode(ubit_t *bursts, const uint8_t *tch_data, int len,
 	int codec_mode_req, uint8_t *codec, int codecs, uint8_t ft,
 	uint8_t cmr);
-int gsm0503_tch_afs_decode(uint8_t *tch_data, sbit_t *bursts,
+int gsm0503_tch_afs_decode(uint8_t *tch_data, const sbit_t *bursts,
 	int codec_mode_req, uint8_t *codec, int codecs, uint8_t *ft,
 	uint8_t *cmr, int *n_errors, int *n_bits_total);
 
-int gsm0503_tch_ahs_encode(ubit_t *bursts, uint8_t *tch_data, int len,
+int gsm0503_tch_ahs_encode(ubit_t *bursts, const uint8_t *tch_data, int len,
 	int codec_mode_req, uint8_t *codec, int codecs, uint8_t ft, uint8_t cmr);
-int gsm0503_tch_ahs_decode(uint8_t *tch_data, sbit_t *bursts, int odd,
+int gsm0503_tch_ahs_decode(uint8_t *tch_data, const sbit_t *bursts, int odd,
 	int codec_mode_req, uint8_t *codec, int codecs, uint8_t *ft,
 	uint8_t *cmr, int *n_errors, int *n_bits_total);
 
-int gsm0503_rach_encode(ubit_t *burst, uint8_t *ra, uint8_t bsic);
-int gsm0503_rach_decode(uint8_t *ra, sbit_t *burst, uint8_t bsic);
+int gsm0503_rach_ext_encode(ubit_t *burst, uint16_t ra, uint8_t bsic, bool is_11bit);
+int gsm0503_rach_encode(ubit_t *burst, const uint8_t *ra, uint8_t bsic) OSMO_DEPRECATED("Use gsm0503_rach_ext_encode() instead");
 
-int gsm0503_sch_encode(ubit_t *burst, uint8_t *sb_info);
-int gsm0503_sch_decode(uint8_t *sb_info, sbit_t *burst);
+int gsm0503_rach_decode(uint8_t *ra, const sbit_t *burst, uint8_t bsic)
+	OSMO_DEPRECATED("Use gsm0503_rach_decode_ber() instead");
+int gsm0503_rach_decode_ber(uint8_t *ra, const sbit_t *burst, uint8_t bsic,
+			    int *n_errors, int *n_bits_total);
+int gsm0503_rach_ext_decode(uint16_t *ra, const sbit_t *burst, uint8_t bsic)
+	OSMO_DEPRECATED("Use gsm0503_rach_ext_decode_ber() instead");
+int gsm0503_rach_ext_decode_ber(uint16_t *ra, const sbit_t *burst, uint8_t bsic,
+				int *n_errors, int *n_bits_total);
+
+int gsm0503_sch_encode(ubit_t *burst, const uint8_t *sb_info);
+int gsm0503_sch_decode(uint8_t *sb_info, const sbit_t *burst);
+
+/*! @} */
diff --git a/lib/decoding/osmocom/coding/gsm0503_interleaving.c b/lib/decoding/osmocom/coding/gsm0503_interleaving.c
index 333e105..d5008d0 100644
--- a/lib/decoding/osmocom/coding/gsm0503_interleaving.c
+++ b/lib/decoding/osmocom/coding/gsm0503_interleaving.c
@@ -1,9 +1,12 @@
 /*
  * (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
  *
+ * SPDX-License-Identifier: GPL-2.0+
+ *
  * This program 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 2 of the License, or
@@ -23,11 +26,17 @@
 #include <string.h>
 
 #include <osmocom/core/bits.h>
-#include "gsm0503_tables.h"
-#include "gsm0503_interleaving.h"
+#include <osmocom/coding/gsm0503_tables.h>
+#include <osmocom/coding/gsm0503_interleaving.h>
 
-/*
- * GSM xCCH interleaving and burst mapping
+/*! \addtogroup interleaving
+ *  @{
+ * 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.
+ *
+ * GSM xCCH interleaving and burst mapping:
  *
  * Interleaving:
  *
@@ -46,8 +55,34 @@
  *      e(B, 58) = h_n(B)
  *
  * Where hl(B) and hn(B) are bits in burst B indicating flags.
- */
+ *
+ * GSM TCH HR/AHS interleaving and burst mapping:
+ *
+ * Interleaving:
+ *
+ * Given 288 coded input bits, form 4 blocks of 114 bits,
+ * where even bits of the first 2 blocks and odd bits of the last 2 blocks
+ * are used:
+ *
+ *      i(B, j) = c(n, k)       k = 0, ..., 227
+ *                              n = 0, ..., N, N + 1, ...
+ *                              B = B_0 + 2n + b
+ *                              j, b = table[k];
+ *
+ * Mapping on Burst:
+ *
+ *      e(B, j) = i(B, j)
+ *      e(B, 59 + j) = i(B, 57 + j)     j = 0, ..., 56
+ *      e(B, 57) = h_l(B)
+ *      e(B, 58) = h_n(B)
+ *
+ * Where hl(B) and hn(B) are bits in burst B indicating flags.
+ *
+ * \file gsm0503_interleaving.c */
 
+/*! 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,7 +94,10 @@
 	}
 }
 
-void gsm0503_xcch_interleave(ubit_t *cB, ubit_t *iB)
+/*! 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(const ubit_t *cB, ubit_t *iB)
 {
 	int j, k, B;
 
@@ -70,6 +108,11 @@
 	}
 }
 
+/*! 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 +149,11 @@
 	}
 }
 
+/*! 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 +187,10 @@
 	gsm0503_xcch_interleave(cp, iB);
 }
 
+/*! 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 +221,10 @@
 	}
 }
 
+/*! 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 +255,11 @@
 	gsm0503_xcch_interleave(cp, iB);
 }
 
+/*! 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 +278,10 @@
 	}
 }
 
+/*! 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 +304,11 @@
 	}
 }
 
+/*! 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 +327,10 @@
 	}
 }
 
+/*! 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 +353,12 @@
 	}
 }
 
+/*! 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 +382,12 @@
 	}
 }
 
-
+/*! 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 +415,12 @@
 	}
 }
 
+/*! 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 +444,12 @@
 	}
 }
 
+/*! 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 +477,12 @@
 	}
 }
 
+/*! 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 +506,13 @@
 	}
 }
 
+
+/*! 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 +540,12 @@
 	}
 }
 
+/*! 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 +569,12 @@
 	}
 }
 
+/*! 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,7 +626,10 @@
  * Where hl(B) and hn(B) are bits in burst B indicating flags.
  */
 
-void gsm0503_tch_fr_deinterleave(sbit_t *cB, sbit_t *iB)
+/*! 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, const sbit_t *iB)
 {
 	int j, k, B;
 
@@ -515,7 +640,10 @@
 	}
 }
 
-void gsm0503_tch_fr_interleave(ubit_t *cB, ubit_t *iB)
+/*! 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(const ubit_t *cB, ubit_t *iB)
 {
 	int j, k, B;
 
@@ -526,31 +654,10 @@
 	}
 }
 
-/*
- * GSM TCH HR/AHS interleaving and burst mapping
- *
- * Interleaving:
- *
- * Given 288 coded input bits, form 4 blocks of 114 bits,
- * where even bits of the first 2 blocks and odd bits of the last 2 blocks
- * are used:
- *
- *      i(B, j) = c(n, k)       k = 0, ..., 227
- *                              n = 0, ..., N, N + 1, ...
- *                              B = B_0 + 2n + b
- *                              j, b = table[k];
- *
- * Mapping on Burst:
- *
- *      e(B, j) = i(B, j)
- *      e(B, 59 + j) = i(B, 57 + j)     j = 0, ..., 56
- *      e(B, 57) = h_l(B)
- *      e(B, 58) = h_n(B)
- *
- * Where hl(B) and hn(B) are bits in burst B indicating flags.
- */
-
-void gsm0503_tch_hr_deinterleave(sbit_t *cB, sbit_t *iB)
+/*! 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, const sbit_t *iB)
 {
 	int j, k, B;
 
@@ -561,7 +668,10 @@
 	}
 }
 
-void gsm0503_tch_hr_interleave(ubit_t *cB, ubit_t *iB)
+/*! 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(const ubit_t *cB, ubit_t *iB)
 {
 	int j, k, B;
 
@@ -571,3 +681,5 @@
 		iB[B * 114 + j] = cB[k];
 	}
 }
+
+/*! @} */
diff --git a/lib/decoding/osmocom/coding/gsm0503_interleaving.h b/lib/decoding/osmocom/coding/gsm0503_interleaving.h
index 05c0365..05b5e27 100644
--- a/lib/decoding/osmocom/coding/gsm0503_interleaving.h
+++ b/lib/decoding/osmocom/coding/gsm0503_interleaving.h
@@ -1,37 +1,23 @@
-/*
- * (C) 2013 by Andreas Eversberg <jolly@eversberg.eu>
- * (C) 2016 by Tom Tsou <tom.tsou@ettus.com>
- *
- * All Rights Reserved
- *
- * This program 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 2 of the License, or
- * (at your option) any later version.
- *
- * This program 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 this program; if not, write to the Free Software Foundation, Inc.,
- * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+/*! \file gsm0503_interleaving.h
+ *  GSM TS 05.03 interleaving.
  */
 
-
 #pragma once
 
 #include <osmocom/core/bits.h>
 
+/*! \addtogroup interleaving
+ *  @{
+ * \file gsm0503_interleaving.h */
+
 void gsm0503_xcch_deinterleave(sbit_t *cB, const sbit_t *iB);
-void gsm0503_xcch_interleave(ubit_t *cB, ubit_t *iB);
+void gsm0503_xcch_interleave(const ubit_t *cB, ubit_t *iB);
 
-void gsm0503_tch_fr_deinterleave(sbit_t *cB, sbit_t *iB);
-void gsm0503_tch_fr_interleave(ubit_t *cB, ubit_t *iB);
+void gsm0503_tch_fr_deinterleave(sbit_t *cB, const sbit_t *iB);
+void gsm0503_tch_fr_interleave(const ubit_t *cB, ubit_t *iB);
 
-void gsm0503_tch_hr_deinterleave(sbit_t *cB, sbit_t *iB);
-void gsm0503_tch_hr_interleave(ubit_t *cB, ubit_t *iB);
+void gsm0503_tch_hr_deinterleave(sbit_t *cB, const sbit_t *iB);
+void gsm0503_tch_hr_interleave(const ubit_t *cB, ubit_t *iB);
 
 void gsm0503_mcs1_ul_deinterleave(sbit_t *hc, sbit_t *dc, const sbit_t *iB);
 void gsm0503_mcs1_ul_interleave(const ubit_t *hc,
@@ -71,3 +57,5 @@
 	const sbit_t *hi, const sbit_t *di);
 void gsm0503_mcs8_dl_interleave(const ubit_t *hc, const ubit_t *c1,
 	const ubit_t *c2, ubit_t *hi, ubit_t *di);
+
+/*! @} */
diff --git a/lib/decoding/osmocom/coding/gsm0503_mapping.c b/lib/decoding/osmocom/coding/gsm0503_mapping.c
index 45275bf..f7532eb 100644
--- a/lib/decoding/osmocom/coding/gsm0503_mapping.c
+++ b/lib/decoding/osmocom/coding/gsm0503_mapping.c
@@ -4,6 +4,8 @@
  *
  * All Rights Reserved
  *
+ * SPDX-License-Identifier: GPL-2.0+
+ *
  * This program 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 2 of the License, or
@@ -23,7 +25,17 @@
 #include <string.h>
 
 #include <osmocom/core/bits.h>
-#include "gsm0503_mapping.h"
+#include <osmocom/coding/gsm0503_mapping.h>
+
+/*! \addtogroup mapping
+ *  @{
+ *
+ *  GSM TS 05.03 burst mapping
+ *
+ *  This module contains burst mapping routines as specified in 3GPP TS
+ *  05.03 / 45.003.
+ *
+ * \file gsm0503_mapping.c */
 
 void gsm0503_xcch_burst_unmap(sbit_t *iB, const sbit_t *eB,
 	sbit_t *hl, sbit_t *hn)
@@ -38,7 +50,7 @@
 		*hn = eB[58];
 }
 
-void gsm0503_xcch_burst_map(ubit_t *iB, ubit_t *eB, const ubit_t *hl,
+void gsm0503_xcch_burst_map(const ubit_t *iB, ubit_t *eB, const ubit_t *hl,
 	const ubit_t *hn)
 {
 	memcpy(eB,      iB,      57);
@@ -50,7 +62,7 @@
 		eB[58] = *hn;
 }
 
-void gsm0503_tch_burst_unmap(sbit_t *iB, sbit_t *eB, sbit_t *h, int odd)
+void gsm0503_tch_burst_unmap(sbit_t *iB, const sbit_t *eB, sbit_t *h, int odd)
 {
 	int i;
 
@@ -70,7 +82,7 @@
 	}
 }
 
-void gsm0503_tch_burst_map(ubit_t *iB, ubit_t *eB, const ubit_t *h, int odd)
+void gsm0503_tch_burst_map(const ubit_t *iB, ubit_t *eB, const ubit_t *h, int odd)
 {
 	int i;
 
@@ -80,13 +92,8 @@
 			eB[i] = iB[i];
 		for (i = 58 - odd; i < 114; i += 2)
 			eB[i + 2] = iB[i];
-	}
-
-	if (h) {
-		if (!odd)
-			eB[58] = *h;
-		else
-			eB[57] = *h;
+		if (h)
+			eB[odd ? 57 : 58] = *h;
 	}
 }
 
@@ -289,3 +296,5 @@
 	eB[191] = t[12];
 	eB[194] = t[13];
 }
+
+/*! @} */
diff --git a/lib/decoding/osmocom/coding/gsm0503_mapping.h b/lib/decoding/osmocom/coding/gsm0503_mapping.h
index 417a94f..f391e8d 100644
--- a/lib/decoding/osmocom/coding/gsm0503_mapping.h
+++ b/lib/decoding/osmocom/coding/gsm0503_mapping.h
@@ -1,27 +1,15 @@
-/*
- * (C) 2013 by Andreas Eversberg <jolly@eversberg.eu>
- * (C) 2016 by Tom Tsou <tom.tsou@ettus.com>
- *
- * All Rights Reserved
- *
- * This program 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 2 of the License, or
- * (at your option) any later version.
- *
- * This program 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 this program; if not, write to the Free Software Foundation, Inc.,
- * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+/*! \file gsm0503_mapping.c
+ *  GSM TS 05.03 burst mapping.
  */
- 
+
 #pragma once
 
 #include <osmocom/core/bits.h>
+//#include "bits.h"
+
+/*! \addtogroup mapping
+ *  @{
+ * \file gsm0503_mapping.h */
 
 void gsm0503_xcch_burst_unmap(sbit_t *iB, const sbit_t *eB,
 	sbit_t *hl, sbit_t *hn);
@@ -52,3 +40,5 @@
 	sbit_t *hi, sbit_t *up, int B);
 
 void gsm0503_mcs5_burst_swap(sbit_t *eB);
+
+/*! @} */
diff --git a/lib/decoding/osmocom/coding/gsm0503_parity.c b/lib/decoding/osmocom/coding/gsm0503_parity.c
index 50977f7..874114f 100644
--- a/lib/decoding/osmocom/coding/gsm0503_parity.c
+++ b/lib/decoding/osmocom/coding/gsm0503_parity.c
@@ -4,6 +4,8 @@
  *
  * All Rights Reserved
  *
+ * SPDX-License-Identifier: GPL-2.0+
+ *
  * This program 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 2 of the License, or
@@ -22,10 +24,19 @@
 #include <stdint.h>
 
 #include <osmocom/core/crcgen.h>
-#include "gsm0503_parity.h"
+#include <osmocom/coding/gsm0503_parity.h>
 
-/*
- * GSM (SACCH) parity (FIRE code)
+/*! \addtogroup parity
+ *  @{
+ *
+ *  GSM TS 05.03 parity
+ *
+ *  This module contains parity/crc code definitions for the various
+ *  parity/crc schemes as defined in 3GPP TS 05.03 / 45.003
+ *
+ * \file gsm0503_parity.c */
+
+/*! GSM (SACCH) parity (FIRE code)
  *
  * g(x) = (x^23 + 1)(x^17 + x^3 + 1)
  *      = x^40 + x^26 + x^23 + x^17 + x^3 + a1
@@ -37,8 +48,7 @@
 	.remainder = 0xffffffffffULL,
 };
 
-/*
- * GSM PDTCH CS-2, CS-3, CS-4 parity
+/*! GSM PDTCH CS-2, CS-3, CS-4 parity
  *
  * g(x) = x^16 + x^12 + x^5 + 1
  */
@@ -49,8 +59,7 @@
 	.remainder = 0xffff,
 };
 
-/*
- * EDGE MCS header parity
+/*! EDGE MCS header parity
  *
  */
 const struct osmo_crc8gen_code gsm0503_mcs_crc8_hdr = {
@@ -60,8 +69,7 @@
 	.remainder = 0xff,
 };
 
-/*
- * EDGE MCS data parity
+/*! EDGE MCS data parity
  *
  */
 const struct osmo_crc16gen_code gsm0503_mcs_crc12 = {
@@ -71,8 +79,7 @@
 	.remainder = 0x0fff,
 };
 
-/*
- * GSM RACH parity
+/*! GSM RACH parity
  *
  * g(x) = x^6 + x^5 + x^3 + x^2 + x^1 + 1
  */
@@ -83,8 +90,7 @@
 	.remainder = 0x3f,
 };
 
-/*
- * GSM SCH parity
+/*! GSM SCH parity
  *
  * g(x) = x^10 + x^8 + x^6 + x^5 + x^4 + x^2 + 1
  */
@@ -95,8 +101,7 @@
 	.remainder = 0x3ff,
 };
 
-/*
- * GSM TCH FR/HR/EFR parity
+/*! GSM TCH FR/HR/EFR parity
  *
  * g(x) = x^3 + x + 1
  */
@@ -107,8 +112,7 @@
 	.remainder = 0x7,
 };
 
-/*
- * GSM TCH EFR parity
+/*! GSM TCH EFR parity
  *
  * g(x) = x^8 + x^4 + x^3 + x^2 + 1
  */
@@ -119,8 +123,7 @@
 	.remainder = 0x00,
 };
 
-/*
- * GSM AMR parity
+/*! GSM AMR parity
  *
  * g(x) = x^6 + x^5 + x^3 + x^2 + x^1 + 1
  */
@@ -130,3 +133,5 @@
 	.init = 0x00,
 	.remainder = 0x3f,
 };
+
+/*! @} */
diff --git a/lib/decoding/osmocom/coding/gsm0503_parity.h b/lib/decoding/osmocom/coding/gsm0503_parity.h
index 6d8a062..28a5444 100644
--- a/lib/decoding/osmocom/coding/gsm0503_parity.h
+++ b/lib/decoding/osmocom/coding/gsm0503_parity.h
@@ -1,28 +1,15 @@
-/*
- * (C) 2013 by Andreas Eversberg <jolly@eversberg.eu>
- * (C) 2016 by Tom Tsou <tom.tsou@ettus.com>
- *
- * All Rights Reserved
- *
- * This program 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 2 of the License, or
- * (at your option) any later version.
- *
- * This program 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 this program; if not, write to the Free Software Foundation, Inc.,
- * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+/*! \file gsm0503_parity.h
+ *  GSM TS 05.03 parity.
  */
- 
+
 #pragma once
 
 #include <osmocom/core/crcgen.h>
 
+/*! \addtogroup parity
+ *  @{
+ * \file gsm0503_parity.h */
+
 const struct osmo_crc64gen_code gsm0503_fire_crc40;
 const struct osmo_crc16gen_code gsm0503_cs234_crc16;
 const struct osmo_crc8gen_code gsm0503_mcs_crc8_hdr;
@@ -32,3 +19,5 @@
 const struct osmo_crc8gen_code gsm0503_tch_fr_crc3;
 const struct osmo_crc8gen_code gsm0503_tch_efr_crc8;
 const struct osmo_crc8gen_code gsm0503_amr_crc6;
+
+/*! @} */
diff --git a/lib/decoding/osmocom/coding/gsm0503_tables.c b/lib/decoding/osmocom/coding/gsm0503_tables.c
index d4cabcc..5fe634b 100644
--- a/lib/decoding/osmocom/coding/gsm0503_tables.c
+++ b/lib/decoding/osmocom/coding/gsm0503_tables.c
@@ -4,6 +4,8 @@
  *
  * All Rights Reserved
  *
+ * SPDX-License-Identifier: GPL-2.0+
+ *
  * This program 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 2 of the License, or
@@ -22,7 +24,18 @@
 #include <stdint.h>
 
 #include <osmocom/core/bits.h>
-#include "gsm0503_tables.h"
+#include <osmocom/coding/gsm0503_tables.h>
+
+/*! \addtogroup tables
+ *  @{
+ *
+ *  GSM TS 05.03 tables.
+ *
+ *  This module contains various tables defining parts of 3GPP TS 05.03
+ *  / 45.003, primarily for the purpose of (de)puncturing, interleaving,
+ *  etc.
+ *
+ * \file gsm0503_tables.c */
 
 const ubit_t gsm0503_pdtch_hl_hn_ubit[4][8] = {
 	{ 1,1, 1,1, 1,1, 1,1 },
@@ -1692,7 +1705,7 @@
 	{ 86 ,0 }, { 87 ,2 }, { 110,0 }, { 111,2 }, { 4  ,0 }, { 5  ,2 },
 	{ 82 ,1 }, { 83 ,3 }, { 52 ,0 }, { 53 ,2 }, { 58 ,1 }, { 59 ,3 },
 	{ 28 ,0 }, { 29 ,2 }, { 34 ,1 }, { 35 ,3 }, { 76 ,0 }, { 77 ,2 },
-	{ 10 ,1 }, { 12 ,3 }, { 100,0 }, { 101,2 }, { 16 ,0 }, { 17 ,2 },
+	{ 10 ,1 }, { 11 ,3 }, { 100,0 }, { 101,2 }, { 16 ,0 }, { 17 ,2 },
 	{ 106,1 }, { 107,3 }, { 64 ,0 }, { 65 ,2 }, { 70 ,1 }, { 71 ,3 },
 	{ 94 ,1 }, { 95 ,3 }, { 40 ,0 }, { 41 ,2 }, { 46 ,1 }, { 47 ,3 },
 	{ 22 ,1 }, { 23 ,3 }, { 88 ,0 }, { 89 ,2 }, { 112,0 }, { 113,2 },
@@ -1730,3 +1743,5 @@
 	{ 0,0,1,0,0,1,1,0,1, 1,0,1,1,1,1,1,1,1, 0,1,1,0,1,0,0,0,1, 0,0,1,1,1,0,1,0,0, },
 	{ 0,1,1,0,1,0,1,1,1, 0,1,0,1,0,1,1,1,1, 0,0,0,1,1,1,1,1,0, 0,1,0,0,1,0,0,1,1, },
 };
+
+/*! @} */
diff --git a/lib/decoding/osmocom/coding/gsm0503_tables.h b/lib/decoding/osmocom/coding/gsm0503_tables.h
index 4976c81..c442549 100644
--- a/lib/decoding/osmocom/coding/gsm0503_tables.h
+++ b/lib/decoding/osmocom/coding/gsm0503_tables.h
@@ -1,28 +1,16 @@
-/*
- * (C) 2013 by Andreas Eversberg <jolly@eversberg.eu>
- * (C) 2016 by Tom Tsou <tom.tsou@ettus.com>
- *
- * All Rights Reserved
- *
- * This program 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 2 of the License, or
- * (at your option) any later version.
- *
- * This program 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 this program; if not, write to the Free Software Foundation, Inc.,
- * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+/*! \file gsm0503_tables.h
+ *  GSM TS 05.03 tables.
  */
 
 #pragma once
 
 #include <stdint.h>
 #include <osmocom/core/bits.h>
+//#include "bits.h"
+
+/*! \addtogroup tables
+ *  @{
+ * \file gsm0503_tables.h */
 
 extern const ubit_t gsm0503_pdtch_hl_hn_ubit[4][8];
 extern const ubit_t gsm0503_pdtch_edge_hl_hn_ubit[3][8];
@@ -69,3 +57,5 @@
 extern const sbit_t gsm0503_ahs_ic_sbit[4][4];
 extern const uint8_t gsm0503_tch_hr_interleaving[228][2];
 extern const ubit_t gsm0503_mcs5_usf_precode_table[8][36];
+
+/*! @} */