7 files changed, 466 insertions, 0 deletions
diff --git a/openbsc/doc/BS11-OML.txt b/openbsc/doc/BS11-OML.txt
new file mode 100644
index 000000000..e5c3299c9
--- /dev/null
+++ b/openbsc/doc/BS11-OML.txt
@@ -0,0 +1,31 @@
+The Siemens BS-11 supports the following additional GSM 12.21 OML operations:
+
+
+CREATE OBJECT
+
+abis_om_fom_hdr.obj_class can be 
+A3:
+A5: ALCO, BBSIG, CCLK, GPSU, LI, PA
+A8: EnvaBTSE
+A9: BPORT
+
+the abis_om_obj_inst.trx_nr field indicates the index of object, whereas the
+abis_om_fom_hdr.bts_nr indicates the type of the object.
+
+enum abis_bs11_objtype {
+	BS11_OBJ_ALCO		= 0x01,
+	BS11_OBJ_BBSIG		= 0x02,	/* obj_class: 0,1 */
+	BS11_OBJ_TRX1		= 0x03,	/* only DEACTIVATE TRX1 */
+	BS11_OBJ_CCLK		= 0x04,
+	BS11_OBJ_GPSU		= 0x06,
+	BS11_OBJ_LI		= 0x07,
+	BS11_OBJ_PA		= 0x09,	/* obj_class: 0, 1*/
+};
+
+In case of CREATE ENVABTSE, the abis_om_obj_inst.trx_nr indicates the EnvaBTSEx
+number.
+
+In case of A9 (CREAETE BPORT), the abis_om_obj_inst.bts_nr indicates which BPORT
+shall be used.
+
+
diff --git a/openbsc/doc/call-routing.txt b/openbsc/doc/call-routing.txt
new file mode 100644
index 000000000..3402f9e33
--- /dev/null
+++ b/openbsc/doc/call-routing.txt
@@ -0,0 +1,25 @@
+Call routing in OpenBSC
+
+Flow of events:
+
+ # MO call initiated by MS, CHANNEL RQD, IMMEDIATE ASSIGN
+ # MS sends CC SETUP message, we assume already on TCH/H FACCH
+ # OpenBSC does a subscriber lookup based on the target extension
+  * If a subscriber is found:
+   # send CALL PROCEEDING message to MO
+   # page the MT subscriber and ask itI to ask for TCH/H
+   # once paging completes, we have the TCH/H for the MT end
+   # send SETUP to MT
+   # receive CALL CONFIRMED from MT
+   # set-up the TRAU mux mapping between the E1 subslots for both TCH/H
+   # receive ALERTING from MT, route ALERTING to MO
+   # receive CONNECT from MT, confirm to MT with CONNECT_ACK
+   # send a CONNECT message to MO, receive CONNECT_ACK from MO
+ * If subscriber is not found:
+  # send RELEASE COMPLETE with apropriate cause to MO (1: unalloacated 3: no route)
+  
+
+
+Thoughts about RR/MM:
+
+* we allocate RR/MM entities on demand, when we need them
diff --git a/openbsc/doc/channel_release.txt b/openbsc/doc/channel_release.txt
new file mode 100644
index 000000000..bacf09c8d
--- /dev/null
+++ b/openbsc/doc/channel_release.txt
@@ -0,0 +1,74 @@
+
+GSM 04.08 7.1.7 / 9.1.7		RR CHANNEL RELESE
+
+RSL 08.58 3.4 / ?		RLL Link Release Request
+
+RSL 08.58 4.6 / 8.4.5		DEACTivate SACCH
+	* Deactivate SACCH according to Channel Release Proc 04.08
+	* to be sent after RR CHANNEL RELEASE is sent to MS
+
+RSL 08.58 4.7 / 8.4.14		RF CHANnel RELease
+	* tells the BTS to release a radio channel
+	* "when an activated radio channel is no longer needed"
+	* BTS responds with RF CHANnel RELease ACKnowledge
+
+
+GSM 04.08 3.4.13: RR connection release procedure
+
+* network sends RR CHANNEL RELEASE to MS on the DCCH
+  * start T3109
+  * deactivate SACCH
+* MS disconnects main signalling link (by sending DISC)
+  * all other data links are disconnected by local end link release
+* network receives DISC (BTS sends RLL REL IND to BSC)
+  * stop T3109
+  * start T3111 
+* when T3111 times out, the network can reuse the channls
+* if T3109 times out, the network deactivates the channels 
+  and can reuse them
+  * this probably means simply RF CHANnel RELease
+
+
+== Implementation in OpenBSC ==
+
+chan_alloc.c:lchan_auto_release()
+	* checks if use count still > 0 (abort)
+	* calls gsm48_send_rr_release()
+		* which calls rsl_deact_sacch()
+	* calls rsl_release_request()
+		* which sends RLL Link Release request
+	
+RX of RELease INDication:
+	* call rsl_rf_chan_release() (send RF_CHAN_REL)
+
+RX of RELease CONFimem:
+	* call rsl_rf_chan_release() (send RF_CHAN_REL)
+
+* RX of RF_CHAN_REL_ACK
+	* call lchan_free()
+		* subscr_put()
+		* delete release_timer
+
+
+=== Integration with SMS ===
+
+* RX of CP_ERROR or unimplemented MT
+	* trigger trans_free() which will lchan_auto_release()
+
+* CP TC1* expired while waiting for CP-ACK
+	* trigger trans_free() which will lchan_auto_release()
+
+* RX of RP_ERROR
+	* trigger trans_free() which will lchan_auto_release()
+	
+* TX of CP-ACK in MT DELIVER
+	* trigger trans_free() which will lchan_auto_release()
+
+* RX of CP-ACK in MO SUBMIT
+	* trigger trans_free() which will lchan_auto_release()
+	
+* RX of RP-ACK in MT DELIVER (and no more messages)
+	* trigger rsl_release_request() for SAPI3
+
+* RX of RP-SMMA in MT DELIVER (and no more messages)
+	* trigger rsl_release_request() for SAPI3
diff --git a/openbsc/doc/e1-data-model.txt b/openbsc/doc/e1-data-model.txt
new file mode 100644
index 000000000..8594fe456
--- /dev/null
+++ b/openbsc/doc/e1-data-model.txt
@@ -0,0 +1,172 @@
+E1 related data model
+
+This data model describes the physical relationship of the individual
+parts in the network, it is not the logical/protocol side of the GSM
+network.
+
+A BTS is connected to the BSC by some physical link.  It could be an actual
+E1 link, but it could also be abis-over-IP with a mixture of TCP and RTP/UDP.
+
+To further complicate the fact, multiple BTS can share one such pysical
+link.  On a single E1 line, we can easily accomodate up to three BTS with
+two TRX each.
+
+Thus, it is best for OpenBSC to have some kind of abstraction layer.  The BSC's
+view of a BTS connected to it.  We call this 'bts_link'.  A bts_link can be
+* all the TCP and UDP streams of a Abis-over-IP BTS
+* a set of E1 timeslots for OML, RSL and TRAU connections on a E1 link
+* a serial line exclusively used for OML messages (T-Link)
+
+A bts_link can be registered with the OpenBSC core at runtime.
+
+struct trx_link {
+	struct gsm_bts_trx *trx;
+};
+
+struct bts_link {
+	struct gsm_bts *bts;
+	struct trx_link trx_links[NUM_TRX];
+};
+
+Interface from stack to input core:
+======================================================================
+int abis_rsl_sendmsg(struct msgb *msg);
+	send a message through a RSL link to the TRX specified by the caller in
+	msg->trx.
+
+int abis_rsl_rcvmsg(struct msgb *msg);
+	receive a message from a RSL link from the TRX specified by the
+	caller in msg->trx.
+
+int abis_nm_sendmsg(struct msgb *msg);
+	send a message through a OML link to the BTS specified by the caller in
+	msg->trx->bts.  The caller can just use bts->c0 to get the first TRX
+	in a BTS. (OML messages are not really sent to a TRX but to the BTS)
+
+int abis_nm_rcvmsg(struct msgb *msg);
+	receive a message from a OML link from the BTS specified by the caller
+	in msg->trx->bts.  The caller can just use bts->c0 to get the first
+	TRX in a BTS.
+
+int abis_link_event(int event, void *data);
+	signal some event (such as layer 1 connect/disconnect) from the
+	input core to the stack.
+
+int subch_demux_in(mx, const u_int8_t *data, int len);
+	receive 'len' bytes from a given E1 timeslot (TRAU frames)
+
+int subchan_mux_out(mx, u_int8_t *data, int len);
+	obtain 'len' bytes of output data to be sent on E1 timeslot
+
+Intrface by Input Core for Input Plugins
+======================================================================
+
+int btslink_register_plugin();
+
+
+Configuration for the E1 input module
+======================================================================
+
+BTS
+	BTS number
+	number of TRX
+	OML link
+		E1 line number
+		timeslot number
+		[subslot number]
+		SAPI
+		TEI
+	for each TRX
+		RSL link
+			E1 line number
+			timeslot number
+			[subslot number]
+			SAPI
+			TEI
+		for each TS
+			E1 line number
+			timeslot number
+			subslot number
+
+
+E1 input module data model
+======================================================================
+
+
+enum e1inp_sign_type {
+	E1INP_SIGN_NONE,
+	E1INP_SIGN_OML,
+	E1INP_SIGN_RSL,
+};
+
+struct e1inp_sign_link {
+	/* list of signalling links */
+	struct llist_head list;
+
+	enum e1inp_sign_type type;
+
+	/* trx for msg->trx of received msgs */	
+	struct gsm_bts_trx *trx;
+
+	/* msgb queue of to-be-transmitted msgs */
+	struct llist_head tx_list;
+
+	/* SAPI and TEI on the E1 TS */
+	u_int8_t sapi;
+	u_int8_t tei;
+}
+
+enum e1inp_ts_type {
+	E1INP_TS_TYPE_NONE,
+	E1INP_TS_TYPE_SIGN,
+	E1INP_TS_TYPE_TRAU,
+};
+
+/* A timeslot in the E1 interface */
+struct e1inp_ts {
+	enum e1inp_ts_type type;
+	struct e1inp_line *line;
+	union {
+		struct {
+			struct llist_head sign_links;
+		} sign;
+		struct {
+			/* subchannel demuxer for frames from E1 */
+			struct subch_demux demux;
+			/* subchannel muxer for frames to E1 */
+			struct subch_mux mux;
+		} trau;
+	};
+	union {
+		struct {
+			/* mISDN driver has one fd for each ts */
+			struct bsc_fd;
+		} misdn;
+	} driver;
+};
+
+struct e1inp_line {
+	unsigned int num;
+	char *name;
+
+	struct e1inp_ts ts[NR_E1_TS];
+
+	char *e1inp_driver;
+	void *driver_data;
+};
+
+/* Call from the Stack: configuration of this TS has changed */
+int e1inp_update_ts(struct e1inp_ts *ts);
+
+/* Receive a packet from the E1 driver */
+int e1inp_rx_ts(struct e1inp_ts *ts, struct msgb *msg,
+		u_int8_t tei, u_int8_t sapi);
+
+/* Send a packet, callback function in the driver */
+int e1driver_tx_ts(struct e1inp_ts *ts, struct msgb *msg)
+
+
+struct e1inp_driver {
+	const char *name;
+	int (*want_write)(struct e1inp_ts *ts);
+};
diff --git a/openbsc/doc/gsm-hopping.txt b/openbsc/doc/gsm-hopping.txt
new file mode 100644
index 000000000..591093999
--- /dev/null
+++ b/openbsc/doc/gsm-hopping.txt
@@ -0,0 +1,54 @@
+according to GSM 05.02:
+
+general parameters from CCCH:
+* CA cell allocation of ARFCN's (System Information / BCCH)
+* FN: TDMA frame number (t1,t2,t3') in SCH
+
+specific parameters from channel assignment:
+* MA: mobile allocation, defines set of ARFCN's, up to 64
+* MAIO: index
+* HSN: hopping sequence generator number (0..64)
+
+
+hopping sequence generation (6.2.3):
+
+u_int8_t rntable[114] = {
+	 48,  98,  63,   1,  36,  95,  78, 102,  94,  73,
+	  0,  64,  25,  81,  76,  59, 124,  23, 104, 100,
+	101,  47, 118,  85,  18,  56,  96,  86,  54,   2,
+	 80,  34, 127,  13,   6,  89,  57, 103,  12,  74,
+	 55, 111,  75,  38, 109,  71, 112,  29,  11,  88,
+	 87,  19,   3,  68, 110,  26,  33,  31,   8,  45,
+	 82,  58,  40, 107,  32,   5, 106,  92,  62,  67,
+	 77, 108, 122,  37,  60,  66, 121,  42,  51, 126,
+	117, 114,   4,  90,  43,  52,  53, 113, 120,  72,
+	 16,  49,   7,  79, 119,  61,  22,  84,   9,  97,
+	125,  99,  17, 123
+};
+
+/* mai=0 represents lowest ARFCN in the MA */
+
+
+u_int8_t hopping_mai(u_int8_t hsn, u_int32_t fn, u_int8_t maio,
+		     u_int8_t t1, u_int8_t t2, u_int8_t t3_)
+{
+	u_int8_t mai;
+
+	if (hsn == 0) /* cyclic hopping */
+		mai = (fn + maio) % n;
+	else {
+		u_int32_t m, m_, t_, s;
+
+		m = t2 + rntable[(hsn xor (t1 % 64)) + t3];
+		m_ = m % (2^NBIN);
+		t_ = t3 % (2^NBIN);
+		if (m_ < n then)
+			s = m_;
+		else
+			s = (m_ + t_) % n;
+		mai = (s + maio) % n;
+	}
+
+	return mai;
+}
+
diff --git a/openbsc/doc/handover.txt b/openbsc/doc/handover.txt
new file mode 100644
index 000000000..ac19e8725
--- /dev/null
+++ b/openbsc/doc/handover.txt
@@ -0,0 +1,89 @@
+Ideas about a handover algorithm
+======================================================================
+
+This is mostly based on the results presented in Chapter 8 of "Performance
+Enhancements in a Frequency Hopping GSM Network" by Thomas Toftegaard Nielsen
+and Joeroen Wigard. 
+
+
+=== Reasons for performing handover ===
+
+Section 2.1.1: Handover used in their CAPACITY simulation:
+
+1) Interference Handover
+
+Average RXLEV is satisfactory high, but average RXQUAL too low indicates
+interference to the channel.  Handover should be made.
+
+2) Bad Quality
+
+Averaged RXQUAL is lower than a threshold
+
+3) Low Level / Signal Strength
+
+Average RXLEV is lower than a threshold
+
+4) Distance Handover
+
+MS is too far away from a cell (measured by TA)
+
+5) Power budget / Better Cell
+
+RX Level of neighbor cell is at least "HO Margin dB" dB better than the
+current serving cell.
+
+=== Ideal parameters for HO algorithm ===
+
+Chapter 8, Section 2.2, Table 24:
+
+Window RXLEV averaging:		10 SACCH frames (no weighting)
+Window RXQUAL averaging:	1 SACCH frame (no averaging)
+Level Threashold:		1 of the last 1 AV-RXLEV values < -110dBm
+Quality Threshold:		3 of the last 4 AV-RXQUAL values >= 5
+Interference Threshold:		1 of the last AV-RXLEV > -85 dBm &
+				3 of the last 4 AV-RXQUAL values >= 5
+Power Budget:			Level of neighbor cell > 3 dB better
+Power Budget Interval:		Every 6 SACCH frames (6 seconds ?!?)
+Distance Handover:		Disabled
+Evaluation rule 1:		RXLEV of the candidate cell a tleast -104 dBm
+Evaluation rule 2:		Level of candidate cell > 3dB better own cell
+Timer Successful HO:		5 SACCH frames
+Timer Unsuccessful HO:		1 SACCH frame
+
+In a non-frequency hopping case, RXQUAL threshold can be decreased to
+RXLEV >= 4
+
+When frequency hopping is enabled, the following additional parameters
+should be introduced:
+
+* No intra-cell handover
+* Use a HO Margin of 2dB
+
+=== Handover Channel Reservation ===
+
+In loaded network, each cell should reserve some channels for handovers,
+rather than using all of them for new call establishment.  This reduces the
+need to drop calls due to failing handovers, at the expense of failing new call
+attempts.
+
+=== Dynamic HO Margin ===
+
+The handover margin (hysteresis) should depend on the RXQUAL. Optimal results
+were achieved with the following settings:
+* RXQUAL <= 4: 9 dB
+* RXQUAL == 5: 6 dB
+* RXQUAL >= 6: 1 dB
+
+
+
+== Actual Handover on a protocol level ==
+
+After the BSC has decided a handover shall be done, it has to
+
+# allocate a channel at the new BTS
+# allocate a handover reference
+# activate the channel on the BTS side using RSL CHANNEL ACTIVATION,
+  indicating the HO reference
+# BTS responds with CHAN ACT ACK, including GSM frame number
+# BSC sends 04.08 HO CMD to MS using old BTS
+
diff --git a/openbsc/doc/oml-interface.txt b/openbsc/doc/oml-interface.txt
new file mode 100644
index 000000000..8ddcfea5c
--- /dev/null
+++ b/openbsc/doc/oml-interface.txt
@@ -0,0 +1,21 @@
+oml interface design notes
+
+problems:
+
+* there is no way how to tag a command sent to the BTS, with the response
+  having the same tag to identify the originator of the command
+* therefore, we can have e.g. both the BSC and the OML interface send a
+  SET ATTRIBUTE message, where the responses would end up at the wrong
+  query.
+
+the only possible solutions i can imagine:
+* have some kind of exclusive locking, where the OML interface gets blocked
+  from the BSC and is exclusively assigned to the OML console until all commands
+  of the OML console have terminated.  This can either be done explicitly
+  dynamically or on demand
+
+* use the OML interface synchronously, i.e. always wait for the response from
+  the BTS before
+
+* unilateral / unsolicited messages need to be broadcasted to both the BSC and
+  the OML console