diff --git a/bsc/BSC_Tests.ttcn b/bsc/BSC_Tests.ttcn
index c66dda7..0fec42b 100644
--- a/bsc/BSC_Tests.ttcn
+++ b/bsc/BSC_Tests.ttcn
@@ -1,5 +1,23 @@
 module BSC_Tests {
 
+/* Integration Tests for OsmoBSC
+ * (C) 2017 by Harald Welte <laforge@gnumonks.org>
+ * All rights reserved.
+ *
+ * Released under the terms of GNU General Public License, Version 2 or
+ * (at your option) any later version.
+ *
+ * This test suite tests OsmoBSC while emulating both multiple BTS + MS as
+ * well as the MSC. See README for more details.
+ *
+ * There are test cases that run in so-called 'handler mode' and test cases
+ * that run directly on top of the BSSAP and RSL CodecPorts.  The "handler mode"
+ * tests abstract the multiplexing/demultiplexing of multiple SCCP connections
+ * and/or RSL channels and are hence suitable for higher-level test cases, while
+ * the "raw" tests directly on top of the CodecPorts are more suitable for lower-
+ * level testing.
+ */
+
 import from General_Types all;
 import from Osmocom_Types all;
 import from GSM_Types all;
@@ -50,37 +68,57 @@
 }
 
 
-
+/* per-BTS state which we keep */
 type record BTS_State {
+	/* component reference to the IPA_Client component used for RSL */
 	IPA_Client rsl
 }
 
 type component test_CT extends BSSAP_Adapter_CT {
+	/* Array of per-BTS state */
 	var BTS_State bts[NUM_BTS];
+	/* array of per-BTS RSL test ports */
 	port IPA_RSL_PT IPA_RSL[NUM_BTS];
 
+	/* component reference to the IPA_Client component used for CTRL to BSC */
 	var IPA_Client ctrl;
+	/* test port for the CTRL interface of the BSC */
 	port IPA_CTRL_PT IPA_CTRL;
 
+	/* are we initialized yet */
 	var boolean g_initialized := false;
+
+	/* global test case guard timer */
 	timer T_guard := 30.0;
 
 }
 
 modulepar {
+	/* IP address at which the BSC can be reached */
 	charstring mp_bsc_ip := "127.0.0.1";
+	/* port number to which to establish the IPA RSL connections */
 	integer mp_bsc_rsl_port := 3003;
+	/* port number to which to establish the IPA CTRL connection */
 	integer mp_bsc_ctrl_port := 4249;
 }
 
 type record IPA_Client {
+	/* IPA Emulation component reference */
 	IPA_Emulation_CT vc_IPA,
+	/* Unit-ID and other CCM parameters to use for IPA client emulation */
 	IPA_CCM_Parameters ccm_pars,
+	/* String identifier for this IPA Client */
 	charstring id,
-
+	/* Associated RSL Emulation Component (if any). Only used in "Handler mode" */
 	RSL_Emulation_CT vc_RSL optional
 }
 
+/*! Start the IPA/RSL related bits for one IPA_Client.
+ *  \param clnt IPA_Client for which to establish
+ *  \param bsc_host IP address / hostname of the BSC
+ *  \param bsc_port TCP port number of the BSC
+ *  \param i number identifying this BTS
+ *  \param handler_mode Start an RSL_Emulation_CT component (true) or not (false) */
 function f_ipa_rsl_start(inout IPA_Client clnt, charstring bsc_host, PortNumber bsc_port, integer i,
 			 boolean handler_mode := false)
 runs on test_CT {
@@ -124,6 +162,7 @@
 	}
 }
 
+/*! Start the CTRL connection to the specified BSC IP+Port */
 function f_ipa_ctrl_start(inout IPA_Client clnt, charstring bsc_host, PortNumber bsc_port, integer i)
 runs on test_CT {
 	timer T := 10.0;
@@ -147,7 +186,7 @@
 	}
 }
 
-
+/* Wait for the OML connection to be brought up by the external osmo-bts-omldummy */
 function f_wait_oml(integer bts_nr, charstring status, float secs_max) runs on test_CT {
 	timer T := secs_max;
 	T.start;
@@ -168,12 +207,14 @@
 	}
 }
 
+/* sleep for given number of (fractional) seconds */
 function f_sleep(float seconds) {
 	timer T := seconds;
 	T.start;
 	T.timeout;
 }
 
+/* global altstep for global guard timer; also takes care of responding RESET witH RESET-ACK */
 altstep as_Tguard() runs on test_CT {
 	var BSSAP_N_UNITDATA_ind ud_ind;
 	[] T_guard.timeout { setverdict(fail, "Timeout of T_guard"); }
@@ -185,6 +226,9 @@
 		}
 }
 
+/* global initialization function
+ * \param nr_bts Number of BTSs we should start/bring up
+ * \param handler_mode Start an RSL_Emulation_CT component (true) or not (false) */
 function f_init(integer nr_bts := NUM_BTS, boolean handler_mode := false) runs on test_CT {
 	var integer i;
 
@@ -211,6 +255,7 @@
 	activate(as_Tguard());
 }
 
+/* expect to receive a RSL message matching a specified templaten on a given BTS / stream */
 function f_exp_ipa_rx(integer bts_nr, template RSL_Message t_rx, float t_secs := 2.0, IpaStreamId sid := IPAC_PROTO_RSL_TRX0)
 runs on test_CT return RSL_Message {
 	var ASP_RSL_Unitdata rx_rsl_ud;
@@ -230,6 +275,7 @@
 	return rx_rsl_ud.rsl;
 }
 
+/* helper function to transmit RSL on a given BTS/stream */
 function f_ipa_tx(integer bts_nr, template RSL_Message t_tx, IpaStreamId sid := IPAC_PROTO_RSL_TRX0)
 runs on test_CT {
 	IPA_RSL[bts_nr].send(ts_ASP_RSL_UD(sid, t_tx));