Imported 1.2.1

11 files changed, 615 insertions, 0 deletions

diff --git a/doc/BS11-OML.txt b/doc/BS11-OML.txt
new file mode 100644
index 0000000..e5c3299
--- /dev/null
+++ b/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/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..5a23107
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,3 @@
+SUBDIRS = \
+	examples \
+	$(NULL)
diff --git a/doc/e1-data-model.txt b/doc/e1-data-model.txt
new file mode 100644
index 0000000..509004f
--- /dev/null
+++ b/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 uint8_t *data, int len);
+	receive 'len' bytes from a given E1 timeslot (TRAU frames)
+
+int subchan_mux_out(mx, uint8_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 */
+	uint8_t sapi;
+	uint8_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 osmo_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,
+		uint8_t tei, uint8_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/doc/examples/Makefile.am b/doc/examples/Makefile.am
new file mode 100644
index 0000000..530c3fa
--- /dev/null
+++ b/doc/examples/Makefile.am
@@ -0,0 +1,22 @@
+CFG_FILES = find $(srcdir) -name '*.cfg*' | sed -e 's,^$(srcdir),,'
+
+dist-hook:
+	for f in $$($(CFG_FILES)); do \
+		j="$(distdir)/$$f" && \
+		mkdir -p "$$(dirname $$j)" && \
+		$(INSTALL_DATA) $(srcdir)/$$f $$j; \
+	done
+
+install-data-hook:
+	for f in $$($(CFG_FILES)); do \
+		j="$(DESTDIR)$(docdir)/examples/$$f" && \
+		mkdir -p "$$(dirname $$j)" && \
+		$(INSTALL_DATA) $(srcdir)/$$f $$j; \
+	done
+
+uninstall-hook:
+	@$(PRE_UNINSTALL)
+	for f in $$($(CFG_FILES)); do \
+		j="$(DESTDIR)$(docdir)/examples/$$f" && \
+		$(RM) $$j; \
+	done
diff --git a/doc/examples/osmo-bsc/osmo-bsc-minimal.cfg b/doc/examples/osmo-bsc/osmo-bsc-minimal.cfg
new file mode 100644
index 0000000..850e29c
--- /dev/null
+++ b/doc/examples/osmo-bsc/osmo-bsc-minimal.cfg
@@ -0,0 +1,33 @@
+network
+ network country code 901
+ mobile network code 70
+ bts 0
+  type sysmobts
+  band GSM-1800
+  location_area_code 23
+  ip.access unit_id 1800 0
+  trx 0
+   rf_locked 0
+   arfcn 868
+   nominal power 23
+   timeslot 0
+    phys_chan_config CCCH+SDCCH4
+   timeslot 1
+    phys_chan_config SDCCH8
+   timeslot 2
+    phys_chan_config TCH/F
+   timeslot 3
+    phys_chan_config TCH/F
+   timeslot 4
+    phys_chan_config TCH/F
+   timeslot 5
+    phys_chan_config TCH/F
+   timeslot 6
+    phys_chan_config TCH/F
+   timeslot 7
+    phys_chan_config TCH/F
+e1_input
+ e1_line 0 driver ipa
+msc 0
+ allow-emergency deny
+ codec-list hr3
diff --git a/doc/examples/osmo-bsc/osmo-bsc.cfg b/doc/examples/osmo-bsc/osmo-bsc.cfg
new file mode 100644
index 0000000..a5ff1ea
--- /dev/null
+++ b/doc/examples/osmo-bsc/osmo-bsc.cfg
@@ -0,0 +1,99 @@
+! osmo-bsc default configuration
+! (assumes STP to run on 127.0.0.1 and uses default point codes)
+!
+e1_input
+ e1_line 0 driver ipa
+network
+ network country code 1
+ mobile network code 1
+ encryption a5 0
+ neci 1
+ paging any use tch 0
+ handover 0
+ handover algorithm 1
+ handover1 window rxlev averaging 10
+ handover1 window rxqual averaging 1
+ handover1 window rxlev neighbor averaging 10
+ handover1 power budget interval 6
+ handover1 power budget hysteresis 3
+ handover1 maximum distance 9999
+ dyn_ts_allow_tch_f 0
+ periodic location update 30
+ bts 0
+  type sysmobts
+  band DCS1800
+  cell_identity 0
+  location_area_code 1
+  base_station_id_code 63
+  ms max power 15
+  cell reselection hysteresis 4
+  rxlev access min 0
+  radio-link-timeout 32
+  channel allocator ascending
+  rach tx integer 9
+  rach max transmission 7
+  channel-descrption attach 1
+  channel-descrption bs-pa-mfrms 5
+  channel-descrption bs-ag-blks-res 1
+  early-classmark-sending forbidden
+  ip.access unit_id 0 0
+  oml ip.access stream_id 255 line 0
+  neighbor-list mode manual-si5
+  neighbor-list add arfcn 100
+  neighbor-list add arfcn 200
+  si5 neighbor-list add arfcn 10
+  si5 neighbor-list add arfcn 20
+  codec-support fr
+  gprs mode none
+  no force-combined-si
+  trx 0
+   rf_locked 0
+   arfcn 871
+   nominal power 23
+   ! to use full TRX power, set max_power_red 0
+   max_power_red 20
+   rsl e1 tei 0
+   timeslot 0
+    phys_chan_config CCCH+SDCCH4
+    hopping enabled 0
+   timeslot 1
+    phys_chan_config TCH/F
+    hopping enabled 0
+   timeslot 2
+    phys_chan_config TCH/F
+    hopping enabled 0
+   timeslot 3
+    phys_chan_config TCH/F
+    hopping enabled 0
+   timeslot 4
+    phys_chan_config TCH/F
+    hopping enabled 0
+   timeslot 5
+    phys_chan_config TCH/F
+    hopping enabled 0
+   timeslot 6
+    phys_chan_config TCH/F
+    hopping enabled 0
+   timeslot 7
+    phys_chan_config TCH/F
+    hopping enabled 0
+msc 0
+ no bsc-welcome-text
+ no bsc-msc-lost-text
+ no bsc-grace-text
+ type normal
+ allow-emergency allow
+ amr-config 12_2k forbidden
+ amr-config 10_2k forbidden
+ amr-config 7_95k forbidden
+ amr-config 7_40k forbidden
+ amr-config 6_70k forbidden
+ amr-config 5_90k allowed
+ amr-config 5_15k forbidden
+ amr-config 4_75k forbidden
+ mgw remote-ip 127.0.0.1
+ mgw remote-port 2427
+ mgw endpoint-range 1 31
+bsc
+ mid-call-timeout 0
+ no missing-msc-text
diff --git a/doc/examples/osmo-bsc/osmo-bsc_custom-sccp.cfg b/doc/examples/osmo-bsc/osmo-bsc_custom-sccp.cfg
new file mode 100644
index 0000000..0666be3
--- /dev/null
+++ b/doc/examples/osmo-bsc/osmo-bsc_custom-sccp.cfg
@@ -0,0 +1,86 @@
+! osmo-bsc configuration example for custom SCCP addresses
+!
+e1_input
+ e1_line 0 driver ipa
+network
+ network country code 1
+ mobile network code 1
+ encryption a5 0
+ neci 1
+ paging any use tch 0
+ handover 0
+ handover algorithm 1
+ handover1 window rxlev averaging 10
+ handover1 window rxqual averaging 1
+ handover1 window rxlev neighbor averaging 10
+ handover1 power budget interval 6
+ handover1 power budget hysteresis 3
+ handover1 maximum distance 9999
+ dyn_ts_allow_tch_f 0
+ periodic location update 30
+ bts 0
+  type sysmobts
+  band DCS1800
+  cell_identity 0
+  location_area_code 1
+  base_station_id_code 63
+  ms max power 15
+  cell reselection hysteresis 4
+  rxlev access min 0
+  radio-link-timeout 32
+  channel allocator ascending
+  rach tx integer 9
+  rach max transmission 7
+  channel-descrption attach 1
+  channel-descrption bs-pa-mfrms 5
+  channel-descrption bs-ag-blks-res 1
+  early-classmark-sending forbidden
+  ip.access unit_id 0 0
+  oml ip.access stream_id 255 line 0
+  neighbor-list mode manual-si5
+  neighbor-list add arfcn 100
+  neighbor-list add arfcn 200
+  si5 neighbor-list add arfcn 10
+  si5 neighbor-list add arfcn 20
+  codec-support fr
+  gprs mode none
+  no force-combined-si
+  trx 0
+   rf_locked 0
+   arfcn 871
+   nominal power 23
+   ! to use full TRX power, set max_power_red 0
+   max_power_red 20
+   rsl e1 tei 0
+   timeslot 0
+    phys_chan_config CCCH+SDCCH4
+    hopping enabled 0
+   timeslot 1
+    phys_chan_config TCH/F
+    hopping enabled 0
+   timeslot 2
+    phys_chan_config TCH/F
+    hopping enabled 0
+   timeslot 3
+    phys_chan_config TCH/F
+    hopping enabled 0
+   timeslot 4
+    phys_chan_config TCH/F
+    hopping enabled 0
+   timeslot 5
+    phys_chan_config TCH/F
+    hopping enabled 0
+   timeslot 6
+    phys_chan_config TCH/F
+    hopping enabled 0
+   timeslot 7
+    phys_chan_config TCH/F
+    hopping enabled 0
+cs7 instance 0
+ point-code 0.42.1
+ !asp asp-clnt-OsmoBSC 2905 0 m3ua
+ ! remote-ip 10.23.24.1  ! where to reach the STP
+ sccp-address msc_remote
+  point-code 0.23.1
+msc 0
+ msc-addr msc_remote
diff --git a/doc/examples/osmo-bsc_nat/black-list.cfg b/doc/examples/osmo-bsc_nat/black-list.cfg
new file mode 100644
index 0000000..d36179d
--- /dev/null
+++ b/doc/examples/osmo-bsc_nat/black-list.cfg
@@ -0,0 +1 @@
+678012512671923:6:6:
diff --git a/doc/examples/osmo-bsc_nat/bscs.cfg b/doc/examples/osmo-bsc_nat/bscs.cfg
new file mode 100644
index 0000000..176debe
--- /dev/null
+++ b/doc/examples/osmo-bsc_nat/bscs.cfg
@@ -0,0 +1,13 @@
+nat
+ bsc 0
+  token lol
+  location_area_code 1234
+  description bsc
+  max-endpoints 32
+  paging forbidden 0
+ bsc 1
+  token wat
+  location_area_code 5678
+  description bsc
+  max-endpoints 32
+  paging forbidden 0
diff --git a/doc/examples/osmo-bsc_nat/osmo-bsc_nat.cfg b/doc/examples/osmo-bsc_nat/osmo-bsc_nat.cfg
new file mode 100644
index 0000000..e835e06
--- /dev/null
+++ b/doc/examples/osmo-bsc_nat/osmo-bsc_nat.cfg
@@ -0,0 +1,66 @@
+!
+! OsmoBSCNAT (0.12.0.266-2daa9) configuration saved from vty
+!!
+!
+log stderr
+  logging filter all 1
+  logging color 1
+  logging timestamp 0
+  logging level all debug
+  logging level rll notice
+  logging level cc notice
+  logging level mm notice
+  logging level rr notice
+  logging level rsl notice
+  logging level nm info
+  logging level mncc notice
+  logging level pag notice
+  logging level meas notice
+  logging level sccp notice
+  logging level msc notice
+  logging level mgcp notice
+  logging level ho notice
+  logging level db notice
+  logging level ref notice
+  logging level gprs debug
+  logging level ns info
+  logging level bssgp debug
+  logging level llc debug
+  logging level sndcp debug
+  logging level nat notice
+  logging level ctrl notice
+  logging level smpp debug
+  logging level lglobal notice
+  logging level llapd notice
+  logging level linp notice
+  logging level lmux notice
+  logging level lmi notice
+  logging level lmib notice
+  logging level lsms notice
+!
+line vty
+ no login
+!
+mgcp
+  bind ip 0.0.0.0
+  bind port 2427
+  rtp bts-base 4000
+  rtp net-base 16000
+  rtp ip-dscp 0
+  no rtcp-omit
+  sdp audio-payload number 126
+  sdp audio-payload name AMR/8000
+  loop 0
+  number endpoints 1
+  call-agent ip 127.0.0.1
+  rtp transcoder-base 0
+  transcoder-remote-base 4000
+nat
+ msc ip 127.0.0.1
+ msc port 5000
+ timeout auth 2
+ timeout ping 20
+ timeout pong 5
+ ip-dscp 0
+ bscs-config-file bscs.cfg
+ access-list bla imsi-allow ^11$
diff --git a/doc/handover.txt b/doc/handover.txt
new file mode 100644
index 0000000..ac19e87
--- /dev/null
+++ b/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
+