aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorNeels Hofmeyr <neels@hofmeyr.de>2017-07-04 23:08:44 +0200
committerNeels Hofmeyr <neels@hofmeyr.de>2017-08-27 17:40:52 +0200
commited3157ce46cde0f3973a5ee0a0a53909f361ae7c (patch)
tree072f9b723003554bead716390f6ed8bf7351d103 /doc
parent2758330b6ab37ff30afca8306080f0e82ef5a732 (diff)
move openbsc/* to repos root
This is the first step in creating this repository from the legacy openbsc.git. Like all other Osmocom repositories, keep the autoconf and automake files in the repository root. openbsc.git has been the sole exception, which ends now. Change-Id: I9c6f2a448d9cb1cc088cf1cf6918b69d7e69b4e7
Diffstat (limited to 'doc')
-rw-r--r--doc/BS11-OML.txt31
-rw-r--r--doc/Makefile.am3
-rw-r--r--doc/call-routing.txt25
-rw-r--r--doc/channel_release.txt95
-rw-r--r--doc/e1-data-model.txt172
-rw-r--r--doc/examples/Makefile.am22
-rw-r--r--doc/examples/osmo-bsc/osmo-bsc.cfg106
-rw-r--r--doc/examples/osmo-bsc_mgcp/mgcp.cfg19
-rw-r--r--doc/examples/osmo-bsc_nat/black-list.cfg1
-rw-r--r--doc/examples/osmo-bsc_nat/bscs.config13
-rw-r--r--doc/examples/osmo-bsc_nat/osmo-bsc_nat.cfg66
-rw-r--r--doc/examples/osmo-gbproxy/osmo-gbproxy-legacy.cfg44
-rw-r--r--doc/examples/osmo-gbproxy/osmo-gbproxy.cfg25
-rw-r--r--doc/examples/osmo-gtphub/gtphub-example.txt90
-rw-r--r--doc/examples/osmo-gtphub/osmo-gtphub-1iface.cfg25
-rw-r--r--doc/examples/osmo-gtphub/osmo-gtphub.cfg25
-rw-r--r--doc/examples/osmo-nitb/bs11/openbsc-1bts-2trx-hopping.cfg164
-rw-r--r--doc/examples/osmo-nitb/bs11/openbsc-1bts-2trx.cfg84
-rw-r--r--doc/examples/osmo-nitb/bs11/openbsc-2bts-2trx.cfg148
-rw-r--r--doc/examples/osmo-nitb/bs11/openbsc.cfg56
-rw-r--r--doc/examples/osmo-nitb/nanobts/openbsc-multitrx.cfg99
-rw-r--r--doc/examples/osmo-nitb/nanobts/openbsc.cfg77
-rw-r--r--doc/examples/osmo-nitb/nokia/openbsc_nokia_3trx.cfg117
-rw-r--r--doc/examples/osmo-nitb/rbs2308/openbsc.cfg220
-rw-r--r--doc/examples/osmo-nitb/sysmobts/openbsc.cfg77
-rw-r--r--doc/examples/osmo-sgsn/osmo-sgsn.cfg26
-rw-r--r--doc/gsm-hopping.txt54
-rw-r--r--doc/handover.txt89
-rw-r--r--doc/ipa-sccp.txt94
-rw-r--r--doc/oml-interface.txt22
-rw-r--r--doc/osmo-nitb-data_structures.dot33
-rw-r--r--doc/paging.txt48
32 files changed, 2170 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/call-routing.txt b/doc/call-routing.txt
new file mode 100644
index 0000000..3402f9e
--- /dev/null
+++ b/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/doc/channel_release.txt b/doc/channel_release.txt
new file mode 100644
index 0000000..c9cdfeb
--- /dev/null
+++ b/doc/channel_release.txt
@@ -0,0 +1,95 @@
+
+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 ==
+
+There are two possible reasons a gsm_subscriber_connection
+will be released. One is a network failure, the other is
+the completion of an operation/transaction.
+
+=== Failure ===
+The BSC API will call the gsm_04_08.c:gsm0408_clear_request callback
+and the MSC part will release all transactions, operations and such
+and the channels will be released as error case.
+
+=== Success ===
+Every time an 'operation' or 'transaction' is finished msc_release_connection
+will be called and it will determine if the gsm_subscriber_connection can
+be released.
+
+In case it can be released bsc_api.c:gsm0808_clear will be called
+which will release all lchan's associated with the connection. For the
+primary channel a SACH Deactivate will be send with the release
+reason NORMAL RELEASE.
+
+
+bsc_api.c:gsm0808_clear
+ * Release a channel used for handover
+ * Release the primary lchan with normal release, SACH deactivate
+
+chan_alloc.c:lchan_release(chan, sacch_deactivate, reason)
+ * Start the release procedure. It is working in steps with callbacks
+ coming from the abis_rsl.c code.
+ * Release all SAPI's > 0 as local end (The BTS should send a
+ REL_CONF a message)
+ * Send SACH Deactivate on SAPI=0 if required.
+ * Start T3109 (stop it when the main signalling link is disconnected)
+ or when the channel released. On timeout start the error handling.
+ * abis_rsl.c schedules the RSL_MT_RF_CHAN_REL once all SAPI's are
+ released and after T3111 has timed out or there is an error.
+
+RX of RELease INDication:
+ * Calls internal rsl_handle_release which might release the RF.
+
+RX of RELease CONFirmation:
+ * Calls internal rsl_handle_release which might release the RF.
+
+* RX of RF_CHAN_REL_ACK
+ * call lchan_free()
+
+
+=== Integration with SMS ===
+
+* RX of CP_ERROR or unimplemented MT
+ * trigger trans_free() which will msc_release_connection()
+
+* CP TC1* expired while waiting for CP-ACK
+ * trigger trans_free() which will msc_release_connection()
+
+* RX of RP_ERROR
+ * trigger trans_free() which will msc_release_connection()
+
+* TX of CP-ACK in MT DELIVER
+ * trigger trans_free() which will msc_release_connection()
+
+* RX of CP-ACK in MO SUBMIT
+ * trigger trans_free() which will msc_release_connection()
+
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.cfg b/doc/examples/osmo-bsc/osmo-bsc.cfg
new file mode 100644
index 0000000..56e4724
--- /dev/null
+++ b/doc/examples/osmo-bsc/osmo-bsc.cfg
@@ -0,0 +1,106 @@
+!
+! OsmoBSC (0.9.14+gitr1+3d331c0062bb0c9694dbd4d1eab7adc58138c3ae) configuration saved from vty
+!!
+password foo
+!
+!
+line vty
+ no login
+!
+e1_input
+ e1_line 0 driver ipa
+network
+ network country code 1
+ mobile network code 1
+ short name OsmoBSC
+ long name OsmoBSC
+ auth policy closed
+ location updating reject cause 13
+ encryption a5 0
+ neci 1
+ paging any use tch 0
+ rrlp mode none
+ mm info 1
+ handover 0
+ handover window rxlev averaging 10
+ handover window rxqual averaging 1
+ handover window rxlev neighbor averaging 10
+ handover power budget interval 6
+ handover power budget hysteresis 3
+ handover maximum distance 9999
+ timer t3101 10
+ timer t3103 0
+ timer t3105 0
+ timer t3107 0
+ timer t3109 0
+ timer t3111 0
+ timer t3113 60
+ timer t3115 0
+ timer t3117 0
+ timer t3119 0
+ timer t3122 0
+ timer t3141 0
+ subscriber-keep-in-ram 0
+ bts 0
+ type nanobts
+ band DCS1800
+ cell_identity 0
+ location_area_code 1
+ training_sequence_code 7
+ base_station_id_code 63
+ ms max power 15
+ cell reselection hysteresis 4
+ rxlev access min 0
+ channel allocator ascending
+ rach tx integer 9
+ rach max transmission 7
+ dtx uplink force
+ dtx downlink
+ 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
+ gprs mode none
+ trx 0
+ rf_locked 0
+ arfcn 871
+ nominal power 23
+ 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
+ ip.access rtp-base 4000
+ timeout-ping 20
+ timeout-pong 5
+ dest 192.168.100.11 6666 0
+ access-list-name msc-list
+ no access-list-name
+bsc
+ no access-list-name
+ access-list-name bsc-list
diff --git a/doc/examples/osmo-bsc_mgcp/mgcp.cfg b/doc/examples/osmo-bsc_mgcp/mgcp.cfg
new file mode 100644
index 0000000..791497f
--- /dev/null
+++ b/doc/examples/osmo-bsc_mgcp/mgcp.cfg
@@ -0,0 +1,19 @@
+!
+! MGCP configuration hand edited
+! !
+password foo
+!
+line vty
+ no login
+!
+mgcp
+! local ip 213.167.134.14
+ bts ip 172.16.252.43
+ bind ip 127.0.0.1
+ bind port 2427
+ rtp base 4000
+ rtp force-ptime 20
+ sdp audio payload number 98
+ sdp audio payload name AMR/8000
+ number endpoints 31
+ loop 1
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.config b/doc/examples/osmo-bsc_nat/bscs.config
new file mode 100644
index 0000000..176debe
--- /dev/null
+++ b/doc/examples/osmo-bsc_nat/bscs.config
@@ -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..6b48e97
--- /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.config
+ access-list bla imsi-allow ^11$
diff --git a/doc/examples/osmo-gbproxy/osmo-gbproxy-legacy.cfg b/doc/examples/osmo-gbproxy/osmo-gbproxy-legacy.cfg
new file mode 100644
index 0000000..15fd74a
--- /dev/null
+++ b/doc/examples/osmo-gbproxy/osmo-gbproxy-legacy.cfg
@@ -0,0 +1,44 @@
+!
+! OsmoGbProxy (UNKNOWN) configuration saved from vty
+!!
+!
+log stderr
+ logging filter all 1
+ logging color 1
+ logging timestamp 0
+ logging level all debug
+ logging level gprs debug
+ logging level ns info
+ logging level bssgp 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
+!
+ns
+ nse 666 nsvci 666
+ nse 666 remote-role sgsn
+! nse 666 encapsulation framerelay-gre
+! nse 666 remote-ip 172.16.1.70
+! nse 666 fr-dlci 666
+ timer tns-block 3
+ timer tns-block-retries 3
+ timer tns-reset 3
+ timer tns-reset-retries 3
+ timer tns-test 30
+ timer tns-alive 3
+ timer tns-alive-retries 10
+ encapsulation udp local-port 23000
+! encapsulation framerelay-gre enabled 1
+gbproxy
+ sgsn nsei 666
+ core-mobile-country-code 666
+ core-mobile-network-code 6
+ core-access-point-name none match-imsi ^666066|^66607
+ tlli-list max-length 200
diff --git a/doc/examples/osmo-gbproxy/osmo-gbproxy.cfg b/doc/examples/osmo-gbproxy/osmo-gbproxy.cfg
new file mode 100644
index 0000000..0c3917a
--- /dev/null
+++ b/doc/examples/osmo-gbproxy/osmo-gbproxy.cfg
@@ -0,0 +1,25 @@
+!
+! Osmocom Gb Proxy (0.9.0.404-6463) configuration saved from vty
+!!
+!
+line vty
+ no login
+!
+gbproxy
+ sgsn nsei 101
+ns
+ nse 101 nsvci 101
+ nse 101 remote-role sgsn
+ nse 101 encapsulation udp
+ nse 101 remote-ip 192.168.100.239
+ nse 101 remote-port 7777
+ timer tns-block 3
+ timer tns-block-retries 3
+ timer tns-reset 3
+ timer tns-reset-retries 3
+ timer tns-test 30
+ timer tns-alive 3
+ timer tns-alive-retries 10
+ encapsulation framerelay-gre enabled 0
+ encapsulation framerelay-gre local-ip 0.0.0.0
+ encapsulation udp local-port 23000
diff --git a/doc/examples/osmo-gtphub/gtphub-example.txt b/doc/examples/osmo-gtphub/gtphub-example.txt
new file mode 100644
index 0000000..9c65f92
--- /dev/null
+++ b/doc/examples/osmo-gtphub/gtphub-example.txt
@@ -0,0 +1,90 @@
+Here is a simple setup to test GTPHub operations. The IP addresses picked will
+work well only on a system that creates local addresses (127.0.0.123) on the
+fly (like linux) -- you may pick of course different IP addresses.
+
+Overview of the example setup:
+
+ sgsnemu gtphub ggsn
+ 127.0.0.1 <--> 127.0.0.3 127.0.0.4 <--> 127.0.0.2
+
+Prerequisites: openggsn.
+
+Have a local directory where you store config files and from which you launch
+the GSNs and the hub (they will store restart counter files in that dir).
+In it, have these config files:
+
+ggsn.conf:
+
+ # GGSN local address
+ listen 127.0.0.2
+
+ # End User Addresses are picked from this range
+ net 10.23.42.0/24
+
+ pcodns1 8.8.8.8
+
+ logfile /tmp/foo
+
+gtphub.conf:
+
+ gtphub
+ bind-to-sgsns 127.0.0.3
+ bind-to-ggsns 127.0.0.4
+ ggsn-proxy 127.0.0.2
+ end
+
+
+(
+You may omit the ggsn-proxy if GRX ares is working, or if you add the GRX
+address and GGSN IP address to /etc/hosts something like:
+
+ 127.0.0.2 internet.mnc070.mcc901.gprs
+
+)
+
+
+Once the config files are in place, start the programs, in separate terminals.
+GGSN and SGSN need to be started with root priviliges to be able to create tun
+interfaces. GTPHub may run as unprivileged user.
+
+The LD_LIBRARY_PATH below may be needed if OpenGGSN installed to /usr/local.
+
+
+1. GGSN:
+
+ sudo -s
+ cd <your-test-dir>
+ LD_LIBRARY_PATH=/usr/local/lib /usr/local/bin/ggsn -f -c ./ggsn.conf
+
+2. GTPHub:
+
+ cd <your-test-dir>
+ path/to/openbsc/openbsc/src/gprs/osmo-gtphub -c gtphub.conf #-e 1 #for DEBUG level
+
+3. SGSN tests:
+
+ sudo -s
+ cd <your-test-dir>
+ /usr/local/bin/sgsnemu --createif -l 127.0.0.1 -r 127.0.0.3 --imsi 420001214365100 --contexts=3
+
+Add more SGSNs using different IMSIs and local ports (if the same IMSI is used,
+the GGSN will reuse TEIs and tunnels will be discarded automatically):
+
+ /usr/local/bin/sgsnemu --createif -l 127.0.0.11 -r 127.0.0.3 --imsi 420001214365300 --contexts=3
+
+This shows the basic setup of GTPHub. Testing internet traffic via sgsnemu
+still needs some effort to announce a mobile subscriber or the like (I have
+used a real BTS, osmo-sgsn and a testing SIM in a web phone, instead).
+
+The core capability of GTPHub is to manage more than two GSNs, e.g. an SGSN
+contacting various GGSNs over the single GTPHub link. You would configure the
+SGSN to use one fixed GGSN (sending to gtphub) and gtphub will resolve the
+GGSNs once it has received the messages. So the SGSN may be behind NAT (add
+"sgsn-use-sender" to gtphub.conf) and communicate to various GGSNs over a
+single link to gtphub.
+
+I hope this helps to get you going.
+Any suggestions/patches are welcome!
+
+~Neels
+
diff --git a/doc/examples/osmo-gtphub/osmo-gtphub-1iface.cfg b/doc/examples/osmo-gtphub/osmo-gtphub-1iface.cfg
new file mode 100644
index 0000000..3913d2c
--- /dev/null
+++ b/doc/examples/osmo-gtphub/osmo-gtphub-1iface.cfg
@@ -0,0 +1,25 @@
+!
+! Osmocom gtphub configuration
+!
+! This file is used for VTY tests, referenced by openbsc/osmoappdesc.py
+! For the test, try to use most config commands.
+!
+
+line vty
+ no login
+
+gtphub
+ ! Local addresses to listen on and send from, both on one interface.
+ ! The side towards SGSN uses nonstandard ports.
+ bind-to-sgsns ctrl 127.0.0.1 12123 user 127.0.0.1 12153
+ ! The GGSN side with standard ports.
+ bind-to-ggsns 127.0.0.1
+
+ ! Proxy: unconditionally direct all traffic to...
+ sgsn-proxy 127.0.0.4
+
+ ! Proxy with nonstandard ports or separate IPs:
+ ggsn-proxy ctrl 127.0.0.3 2123 user 127.0.0.5 2152
+
+ ! Add a name server for GGSN resolution
+ grx-dns-add 192.168.0.1
diff --git a/doc/examples/osmo-gtphub/osmo-gtphub.cfg b/doc/examples/osmo-gtphub/osmo-gtphub.cfg
new file mode 100644
index 0000000..0dc4150
--- /dev/null
+++ b/doc/examples/osmo-gtphub/osmo-gtphub.cfg
@@ -0,0 +1,25 @@
+!
+! Osmocom gtphub configuration
+!
+
+line vty
+ no login
+
+gtphub
+ ! Local addresses to listen on and send from, each on standard ports
+ ! 2123 and 2152. Setting these addresses is mandatory.
+ bind-to-sgsns 127.0.0.1
+ bind-to-ggsns 127.0.0.2
+
+ ! Local nonstandard ports or separate IPs:
+ !bind-to-sgsns ctrl 127.0.0.1 2342 user 127.0.0.1 4223
+
+ ! Proxy: unconditionally direct all traffic to...
+ !ggsn-proxy 127.0.0.3
+ !sgsn-proxy 127.0.0.4
+
+ ! Proxy with nonstandard ports or separate IPs:
+ !ggsn-proxy ctrl 127.0.0.3 2123 user 127.0.0.5 2152
+
+ ! Add a name server for GGSN resolution
+ !grx-dns-add 192.168.0.1
diff --git a/doc/examples/osmo-nitb/bs11/openbsc-1bts-2trx-hopping.cfg b/doc/examples/osmo-nitb/bs11/openbsc-1bts-2trx-hopping.cfg
new file mode 100644
index 0000000..6730644
--- /dev/null
+++ b/doc/examples/osmo-nitb/bs11/openbsc-1bts-2trx-hopping.cfg
@@ -0,0 +1,164 @@
+!
+! OpenBSC (0.9.0.845-57c4) configuration saved from vty
+!!
+password foo
+!
+line vty
+ no login
+!
+e1_input
+ e1_line 0 driver misdn
+network
+ network country code 1
+ mobile network code 1
+ short name OpenBSC
+ long name OpenBSC
+ auth policy closed
+ location updating reject cause 13
+ encryption a5 0
+ neci 1
+ rrlp mode none
+ mm info 0
+ handover 0
+ handover window rxlev averaging 10
+ handover window rxqual averaging 1
+ handover window rxlev neighbor averaging 10
+ handover power budget interval 6
+ handover power budget hysteresis 3
+ handover maximum distance 9999
+ timer t3101 10
+ timer t3103 0
+ timer t3105 0
+ timer t3107 0
+ timer t3109 4
+ timer t3111 0
+ timer t3113 60
+ timer t3115 0
+ timer t3117 0
+ timer t3119 0
+ timer t3141 0
+ bts 0
+ type bs11
+ band GSM900
+ cell_identity 0
+ location_area_code 1
+ training_sequence_code 7
+ base_station_id_code 63
+ ms max power 15
+ cell reselection hysteresis 4
+ rxlev access min 0
+ channel allocator descending
+ rach tx integer 9
+ rach max transmission 7
+ oml e1 line 0 timeslot 1 sub-slot full
+ oml e1 tei 25
+ gprs mode none
+ trx 0
+ rf_locked 0
+ arfcn 121
+ nominal power 24
+ max_power_red 12
+ rsl e1 line 0 timeslot 1 sub-slot full
+ rsl e1 tei 1
+ timeslot 0
+ phys_chan_config CCCH
+ hopping enabled 0
+ e1 line 0 timeslot 1 sub-slot full
+ timeslot 1
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 2 sub-slot 1
+ timeslot 2
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 2 sub-slot 2
+ timeslot 3
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 2 sub-slot 3
+ timeslot 4
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 3 sub-slot 0
+ timeslot 5
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 3 sub-slot 1
+ timeslot 6
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 3 sub-slot 2
+ timeslot 7
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 3 sub-slot 3
+ trx 1
+ rf_locked 0
+ arfcn 119
+ nominal power 24
+ max_power_red 12
+ rsl e1 line 0 timeslot 1 sub-slot full
+ rsl e1 tei 2
+ timeslot 0
+ phys_chan_config SDCCH8
+ hopping enabled 1
+ hopping sequence-number 0
+ hopping maio 0
+ hopping arfcn add 117
+ hopping arfcn add 119
+ timeslot 1
+ phys_chan_config TCH/F
+ hopping enabled 1
+ hopping sequence-number 0
+ hopping maio 0
+ hopping arfcn add 117
+ hopping arfcn add 119
+ e1 line 0 timeslot 4 sub-slot 1
+ timeslot 2
+ phys_chan_config TCH/F
+ hopping enabled 1
+ hopping sequence-number 0
+ hopping maio 0
+ hopping arfcn add 117
+ hopping arfcn add 119
+ e1 line 0 timeslot 4 sub-slot 2
+ timeslot 3
+ phys_chan_config TCH/F
+ hopping enabled 1
+ hopping sequence-number 0
+ hopping maio 0
+ hopping arfcn add 117
+ hopping arfcn add 119
+ e1 line 0 timeslot 4 sub-slot 3
+ timeslot 4
+ phys_chan_config TCH/F
+ hopping enabled 1
+ hopping sequence-number 0
+ hopping maio 0
+ hopping arfcn add 117
+ hopping arfcn add 119
+ e1 line 0 timeslot 5 sub-slot 0
+ timeslot 5
+ phys_chan_config TCH/F
+ hopping enabled 1
+ hopping sequence-number 0
+ hopping maio 0
+ hopping arfcn add 117
+ hopping arfcn add 119
+ e1 line 0 timeslot 5 sub-slot 1
+ timeslot 6
+ phys_chan_config TCH/F
+ hopping enabled 1
+ hopping sequence-number 0
+ hopping maio 0
+ hopping arfcn add 117
+ hopping arfcn add 119
+ e1 line 0 timeslot 5 sub-slot 2
+ timeslot 7
+ phys_chan_config TCH/F
+ hopping enabled 1
+ hopping sequence-number 0
+ hopping maio 0
+ hopping arfcn add 117
+ hopping arfcn add 119
+ e1 line 0 timeslot 5 sub-slot 3
diff --git a/doc/examples/osmo-nitb/bs11/openbsc-1bts-2trx.cfg b/doc/examples/osmo-nitb/bs11/openbsc-1bts-2trx.cfg
new file mode 100644
index 0000000..ca5689f
--- /dev/null
+++ b/doc/examples/osmo-nitb/bs11/openbsc-1bts-2trx.cfg
@@ -0,0 +1,84 @@
+!
+! OpenBSC configuration saved from vty
+! !
+password foo
+!
+line vty
+ no login
+!
+e1_input
+ e1_line 0 driver misdn
+network
+ network country code 1
+ mobile network code 1
+ short name OpenBSC
+ long name OpenBSC
+ timer t3101 10
+ timer t3113 60
+ bts 0
+ type bs11
+ band GSM900
+ cell_identity 1
+ location_area_code 1
+ training_sequence_code 7
+ base_station_id_code 63
+ oml e1 line 0 timeslot 1 sub-slot full
+ oml e1 tei 25
+ trx 0
+ arfcn 121
+ max_power_red 0
+ rsl e1 line 0 timeslot 1 sub-slot full
+ rsl e1 tei 1
+ timeslot 0
+ phys_chan_config CCCH+SDCCH4
+ e1 line 0 timeslot 1 sub-slot full
+ timeslot 1
+ phys_chan_config SDCCH8
+ e1 line 0 timeslot 2 sub-slot 1
+ timeslot 2
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 2 sub-slot 2
+ timeslot 3
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 2 sub-slot 3
+ timeslot 4
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 3 sub-slot 0
+ timeslot 5
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 3 sub-slot 1
+ timeslot 6
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 3 sub-slot 2
+ timeslot 7
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 3 sub-slot 3
+ trx 1
+ arfcn 123
+ max_power_red 0
+ rsl e1 line 0 timeslot 1 sub-slot full
+ rsl e1 tei 2
+ timeslot 0
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 4 sub-slot 0
+ timeslot 1
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 4 sub-slot 1
+ timeslot 2
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 4 sub-slot 2
+ timeslot 3
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 4 sub-slot 3
+ timeslot 4
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 5 sub-slot 0
+ timeslot 5
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 5 sub-slot 1
+ timeslot 6
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 5 sub-slot 2
+ timeslot 7
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 5 sub-slot 3
diff --git a/doc/examples/osmo-nitb/bs11/openbsc-2bts-2trx.cfg b/doc/examples/osmo-nitb/bs11/openbsc-2bts-2trx.cfg
new file mode 100644
index 0000000..4f194c0
--- /dev/null
+++ b/doc/examples/osmo-nitb/bs11/openbsc-2bts-2trx.cfg
@@ -0,0 +1,148 @@
+!
+! OpenBSC configuration saved from vty
+! !
+password foo
+!
+line vty
+ no login
+!
+network
+ network country code 1
+ mobile network code 1
+ short name OpenBSC
+ long name OpenBSC
+ timer t3101 10
+ timer t3113 60
+ bts 0
+ type bs11
+ band GSM900
+ cell_identity 1
+ location_area_code 1
+ training_sequence_code 7
+ base_station_id_code 63
+ oml e1 line 0 timeslot 1 sub-slot full
+ oml e1 tei 25
+ trx 0
+ arfcn 121
+ max_power_red 0
+ rsl e1 line 0 timeslot 1 sub-slot full
+ rsl e1 tei 1
+ timeslot 0
+ phys_chan_config CCCH+SDCCH4
+ e1 line 0 timeslot 1 sub-slot full
+ timeslot 1
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 2 sub-slot 1
+ timeslot 2
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 2 sub-slot 2
+ timeslot 3
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 2 sub-slot 3
+ timeslot 4
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 3 sub-slot 0
+ timeslot 5
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 3 sub-slot 1
+ timeslot 6
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 3 sub-slot 2
+ timeslot 7
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 3 sub-slot 3
+ trx 1
+ arfcn 123
+ max_power_red 0
+ rsl e1 line 0 timeslot 1 sub-slot full
+ rsl e1 tei 2
+ timeslot 0
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 4 sub-slot 0
+ timeslot 1
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 4 sub-slot 1
+ timeslot 2
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 4 sub-slot 2
+ timeslot 3
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 4 sub-slot 3
+ timeslot 4
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 5 sub-slot 0
+ timeslot 5
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 5 sub-slot 1
+ timeslot 6
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 5 sub-slot 2
+ timeslot 7
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 5 sub-slot 3
+ bts 1
+ type bs11
+ band GSM900
+ location_area_code 2
+ training_sequence_code 7
+ base_station_id_code 63
+ oml e1 line 1 timeslot 6 sub-slot full
+ oml e1 tei 25
+ trx 0
+ arfcn 122
+ max_power_red 0
+ rsl e1 line 1 timeslot 6 sub-slot full
+ rsl e1 tei 1
+ timeslot 0
+ phys_chan_config CCCH+SDCCH4
+ e1 line 1 timeslot 7 sub-slot 0
+ timeslot 1
+ phys_chan_config SDCCH8
+ e1 line 1 timeslot 7 sub-slot 1
+ timeslot 2
+ phys_chan_config TCH/F
+ e1 line 1 timeslot 7 sub-slot 2
+ timeslot 3
+ phys_chan_config TCH/F
+ e1 line 1 timeslot 7 sub-slot 3
+ timeslot 4
+ phys_chan_config TCH/F
+ e1 line 1 timeslot 8 sub-slot 0
+ timeslot 5
+ phys_chan_config TCH/F
+ e1 line 1 timeslot 8 sub-slot 1
+ timeslot 6
+ phys_chan_config TCH/F
+ e1 line 1 timeslot 8 sub-slot 2
+ timeslot 7
+ phys_chan_config TCH/F
+ e1 line 1 timeslot 8 sub-slot 3
+ trx 1
+ arfcn 124
+ max_power_red 0
+ rsl e1 line 1 timeslot 6 sub-slot full
+ rsl e1 tei 2
+ timeslot 0
+ phys_chan_config TCH/F
+ e1 line 1 timeslot 9 sub-slot 0
+ timeslot 1
+ phys_chan_config TCH/F
+ e1 line 1 timeslot 9 sub-slot 1
+ timeslot 2
+ phys_chan_config TCH/F
+ e1 line 1 timeslot 9 sub-slot 2
+ timeslot 3
+ phys_chan_config TCH/F
+ e1 line 1 timeslot 9 sub-slot 3
+ timeslot 4
+ phys_chan_config TCH/F
+ e1 line 1 timeslot 10 sub-slot 0
+ timeslot 5
+ phys_chan_config TCH/F
+ e1 line 1 timeslot 10 sub-slot 1
+ timeslot 6
+ phys_chan_config TCH/F
+ e1 line 1 timeslot 10 sub-slot 2
+ timeslot 7
+ phys_chan_config TCH/F
+ e1 line 1 timeslot 10 sub-slot 3
diff --git a/doc/examples/osmo-nitb/bs11/openbsc.cfg b/doc/examples/osmo-nitb/bs11/openbsc.cfg
new file mode 100644
index 0000000..6c47a90
--- /dev/null
+++ b/doc/examples/osmo-nitb/bs11/openbsc.cfg
@@ -0,0 +1,56 @@
+!
+! OpenBSC configuration saved from vty
+! !
+password foo
+!
+line vty
+ no login
+!
+e1_input
+ e1_line 0 driver misdn
+network
+ network country code 1
+ mobile network code 1
+ short name OpenBSC
+ long name OpenBSC
+ timer t3101 10
+ timer t3113 60
+ bts 0
+ type bs11
+ band GSM900
+ cell_identity 1
+ location_area_code 1
+ training_sequence_code 7
+ base_station_id_code 63
+ oml e1 line 0 timeslot 1 sub-slot full
+ oml e1 tei 25
+ trx 0
+ arfcn 121
+ max_power_red 0
+ rsl e1 line 0 timeslot 1 sub-slot full
+ rsl e1 tei 1
+ timeslot 0
+ phys_chan_config CCCH+SDCCH4
+ e1 line 0 timeslot 1 sub-slot full
+ timeslot 1
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 2 sub-slot 1
+ timeslot 2
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 2 sub-slot 2
+ timeslot 3
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 2 sub-slot 3
+ timeslot 4
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 3 sub-slot 0
+ timeslot 5
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 3 sub-slot 1
+ timeslot 6
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 3 sub-slot 2
+ timeslot 7
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 3 sub-slot 3
+
diff --git a/doc/examples/osmo-nitb/nanobts/openbsc-multitrx.cfg b/doc/examples/osmo-nitb/nanobts/openbsc-multitrx.cfg
new file mode 100644
index 0000000..3277bea
--- /dev/null
+++ b/doc/examples/osmo-nitb/nanobts/openbsc-multitrx.cfg
@@ -0,0 +1,99 @@
+!
+! OpenBSC configuration saved from vty
+! !
+password foo
+!
+line vty
+ no login
+!
+e1_input
+ e1_line 0 driver ipa
+network
+ network country code 1
+ mobile network code 1
+ short name OpenBSC
+ long name OpenBSC
+ auth policy closed
+ location updating reject cause 13
+ encryption a5 0
+ neci 1
+ rrlp mode none
+ mm info 0
+ handover 0
+ handover window rxlev averaging 10
+ handover window rxqual averaging 1
+ handover window rxlev neighbor averaging 10
+ handover power budget interval 6
+ handover power budget hysteresis 3
+ handover maximum distance 9999
+ timer t3101 10
+ timer t3103 0
+ timer t3105 0
+ timer t3107 0
+ timer t3109 4
+ timer t3111 0
+ timer t3113 60
+ timer t3115 0
+ timer t3117 0
+ timer t3119 0
+ timer t3141 0
+ bts 0
+ type nanobts
+ band DCS1800
+ cell_identity 0
+ location_area_code 1
+ training_sequence_code 7
+ base_station_id_code 63
+ ms max power 15
+ cell reselection hysteresis 4
+ rxlev access min 0
+ channel allocator ascending
+ rach tx integer 9
+ rach max transmission 7
+ ip.access unit_id 1800 0
+ oml ip.access stream_id 255 line 0
+ gprs mode none
+ trx 0
+ rf_locked 0
+ arfcn 871
+ nominal power 23
+ max_power_red 0
+ rsl e1 tei 0
+ 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
+ trx 1
+ rf_locked 0
+ arfcn 873
+ nominal power 23
+ max_power_red 0
+ rsl e1 tei 0
+ timeslot 0
+ phys_chan_config SDCCH8
+ timeslot 1
+ phys_chan_config TCH/F
+ 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
diff --git a/doc/examples/osmo-nitb/nanobts/openbsc.cfg b/doc/examples/osmo-nitb/nanobts/openbsc.cfg
new file mode 100644
index 0000000..cfc1be6
--- /dev/null
+++ b/doc/examples/osmo-nitb/nanobts/openbsc.cfg
@@ -0,0 +1,77 @@
+!
+! OpenBSC configuration saved from vty
+! !
+password foo
+!
+line vty
+ no login
+!
+e1_input
+ e1_line 0 driver ipa
+network
+ network country code 1
+ mobile network code 1
+ short name OpenBSC
+ long name OpenBSC
+ auth policy closed
+ location updating reject cause 13
+ encryption a5 0
+ neci 1
+ rrlp mode none
+ mm info 1
+ handover 0
+ handover window rxlev averaging 10
+ handover window rxqual averaging 1
+ handover window rxlev neighbor averaging 10
+ handover power budget interval 6
+ handover power budget hysteresis 3
+ handover maximum distance 9999
+ timer t3101 10
+ timer t3103 0
+ timer t3105 0
+ timer t3107 0
+ timer t3109 4
+ timer t3111 0
+ timer t3113 60
+ timer t3115 0
+ timer t3117 0
+ timer t3119 0
+ timer t3141 0
+ bts 0
+ type nanobts
+ band DCS1800
+ cell_identity 0
+ location_area_code 1
+ training_sequence_code 7
+ base_station_id_code 63
+ ms max power 15
+ cell reselection hysteresis 4
+ rxlev access min 0
+ channel allocator ascending
+ rach tx integer 9
+ rach max transmission 7
+ ip.access unit_id 1801 0
+ oml ip.access stream_id 255 line 0
+ gprs mode none
+ trx 0
+ rf_locked 0
+ arfcn 514
+ nominal power 23
+ max_power_red 20
+ rsl e1 tei 0
+ 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
diff --git a/doc/examples/osmo-nitb/nokia/openbsc_nokia_3trx.cfg b/doc/examples/osmo-nitb/nokia/openbsc_nokia_3trx.cfg
new file mode 100644
index 0000000..90386be
--- /dev/null
+++ b/doc/examples/osmo-nitb/nokia/openbsc_nokia_3trx.cfg
@@ -0,0 +1,117 @@
+!
+! OpenBSC configuration saved from vty
+! !
+password foo
+!
+line vty
+ no login
+!
+e1_input
+ e1_line 0 driver misdn
+network
+ network country code 1
+ mobile network code 1
+ short name OpenBSC
+ long name OpenBSC
+ timer t3101 10
+ timer t3113 60
+ bts 0
+ type nokia_site
+ band GSM1800
+ cell_identity 1
+ location_area_code 1
+ base_station_id_code 63
+ training_sequence_code 7
+
+ oml e1 line 0 timeslot 1 sub-slot full
+ oml e1 tei 1
+
+ trx 0
+ arfcn 866
+ max_power_red 24
+ rsl e1 line 0 timeslot 2 sub-slot full
+ rsl e1 tei 1
+ timeslot 0
+ phys_chan_config CCCH+SDCCH4
+ e1 line 0 timeslot 6 sub-slot full
+ timeslot 1
+ phys_chan_config SDCCH8
+ e1 line 0 timeslot 6 sub-slot 1
+ timeslot 2
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 6 sub-slot 2
+ timeslot 3
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 6 sub-slot 3
+ timeslot 4
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 7 sub-slot 0
+ timeslot 5
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 7 sub-slot 1
+ timeslot 6
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 7 sub-slot 2
+ timeslot 7
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 7 sub-slot 3
+
+ trx 1
+ arfcn 870
+ max_power_red 24
+ rsl e1 line 0 timeslot 3 sub-slot full
+ rsl e1 tei 2
+ timeslot 0
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 8 sub-slot 0
+ timeslot 1
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 8 sub-slot 1
+ timeslot 2
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 8 sub-slot 2
+ timeslot 3
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 8 sub-slot 3
+ timeslot 4
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 9 sub-slot 0
+ timeslot 5
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 9 sub-slot 1
+ timeslot 6
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 9 sub-slot 2
+ timeslot 7
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 9 sub-slot 3
+
+ trx 2
+ arfcn 874
+ max_power_red 24
+ rsl e1 line 0 timeslot 4 sub-slot full
+ rsl e1 tei 3
+ timeslot 0
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 10 sub-slot 0
+ timeslot 1
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 10 sub-slot 1
+ timeslot 2
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 10 sub-slot 2
+ timeslot 3
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 10 sub-slot 3
+ timeslot 4
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 11 sub-slot 0
+ timeslot 5
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 11 sub-slot 1
+ timeslot 6
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 11 sub-slot 2
+ timeslot 7
+ phys_chan_config TCH/F
+ e1 line 0 timeslot 11 sub-slot 3
diff --git a/doc/examples/osmo-nitb/rbs2308/openbsc.cfg b/doc/examples/osmo-nitb/rbs2308/openbsc.cfg
new file mode 100644
index 0000000..0226920
--- /dev/null
+++ b/doc/examples/osmo-nitb/rbs2308/openbsc.cfg
@@ -0,0 +1,220 @@
+!
+! OpenBSC (0.9.11.308-62d46) configuration saved from vty
+!!
+password foo
+!
+line vty
+ no login
+!
+network
+ network country code 262
+ mobile network code 42
+ short name OpenBSC
+ long name OpenBSC
+ auth policy closed
+ location updating reject cause 13
+ encryption a5 0
+ neci 0
+ paging any use tch 0
+ rrlp mode none
+ mm info 0
+ handover 0
+ handover window rxlev averaging 10
+ handover window rxqual averaging 1
+ handover window rxlev neighbor averaging 10
+ handover power budget interval 6
+ handover power budget hysteresis 3
+ handover maximum distance 9999
+ timer t3101 10
+ timer t3103 0
+ timer t3105 0
+ timer t3107 0
+ timer t3109 4
+ timer t3111 0
+ timer t3113 60
+ timer t3115 0
+ timer t3117 0
+ timer t3119 0
+ timer t3122 0
+ timer t3141 0
+ subscriber-keep-in-ram 0
+ bts 0
+ type rbs2000
+ band GSM900
+ cell_identity 0
+ location_area_code 1
+ training_sequence_code 7
+ base_station_id_code 63
+ ms max power 15
+ cell reselection hysteresis 4
+ rxlev access min 0
+ channel allocator descending
+ rach tx integer 9
+ rach max transmission 7
+ oml e1 line 0 timeslot 1 sub-slot full
+ oml e1 tei 62
+ neighbor-list mode automatic
+ gprs mode none
+ is-connection-list add 4 512 12
+ is-connection-list add 16 524 12
+ is-connection-list add 28 536 12
+ is-connection-list add 40 548 12
+ trx 0
+ rf_locked 0
+ arfcn 55
+ nominal power 24
+ max_power_red 12
+ rsl e1 line 0 timeslot 1 sub-slot full
+ rsl e1 tei 0
+ timeslot 0
+ phys_chan_config CCCH+SDCCH4
+ hopping enabled 0
+ e1 line 0 timeslot 1 sub-slot full
+ timeslot 1
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 2 sub-slot 1
+ timeslot 2
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 2 sub-slot 2
+ timeslot 3
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 2 sub-slot 3
+ timeslot 4
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 3 sub-slot 0
+ timeslot 5
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 3 sub-slot 1
+ timeslot 6
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 3 sub-slot 2
+ timeslot 7
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 3 sub-slot 3
+ trx 1
+ rf_locked 0
+ arfcn 57
+ nominal power 24
+ max_power_red 12
+ rsl e1 line 0 timeslot 4 sub-slot full
+ rsl e1 tei 1
+ timeslot 0
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 5 sub-slot 0
+ timeslot 1
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 5 sub-slot 1
+ timeslot 2
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 5 sub-slot 2
+ timeslot 3
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 5 sub-slot 3
+ timeslot 4
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 6 sub-slot 0
+ timeslot 5
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 6 sub-slot 1
+ timeslot 6
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 6 sub-slot 2
+ timeslot 7
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 6 sub-slot 3
+ trx 2
+ rf_locked 0
+ arfcn 59
+ nominal power 24
+ max_power_red 12
+ rsl e1 line 0 timeslot 7 sub-slot full
+ rsl e1 tei 2
+ timeslot 0
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 8 sub-slot 0
+ timeslot 1
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 8 sub-slot 1
+ timeslot 2
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 8 sub-slot 2
+ timeslot 3
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 8 sub-slot 3
+ timeslot 4
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 9 sub-slot 0
+ timeslot 5
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 9 sub-slot 1
+ timeslot 6
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 9 sub-slot 2
+ timeslot 7
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 9 sub-slot 3
+ trx 3
+ rf_locked 0
+ arfcn 61
+ nominal power 24
+ max_power_red 12
+ rsl e1 line 0 timeslot 10 sub-slot full
+ rsl e1 tei 3
+ timeslot 0
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 11 sub-slot 0
+ timeslot 1
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 11 sub-slot 1
+ timeslot 2
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 11 sub-slot 2
+ timeslot 3
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 11 sub-slot 3
+ timeslot 4
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 12 sub-slot 0
+ timeslot 5
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 12 sub-slot 1
+ timeslot 6
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 12 sub-slot 2
+ timeslot 7
+ phys_chan_config TCH/F
+ hopping enabled 0
+ e1 line 0 timeslot 12 sub-slot 3
+
+e1_input
+ e1_line 0 driver dahdi
diff --git a/doc/examples/osmo-nitb/sysmobts/openbsc.cfg b/doc/examples/osmo-nitb/sysmobts/openbsc.cfg
new file mode 100644
index 0000000..7c078f6
--- /dev/null
+++ b/doc/examples/osmo-nitb/sysmobts/openbsc.cfg
@@ -0,0 +1,77 @@
+!
+! OpenBSC configuration saved from vty
+! !
+password foo
+!
+line vty
+ no login
+!
+e1_input
+ e1_line 0 driver ipa
+network
+ network country code 1
+ mobile network code 1
+ short name OpenBSC
+ long name OpenBSC
+ auth policy closed
+ location updating reject cause 13
+ encryption a5 0
+ neci 1
+ rrlp mode none
+ mm info 1
+ handover 0
+ handover window rxlev averaging 10
+ handover window rxqual averaging 1
+ handover window rxlev neighbor averaging 10
+ handover power budget interval 6
+ handover power budget hysteresis 3
+ handover maximum distance 9999
+ timer t3101 10
+ timer t3103 0
+ timer t3105 0
+ timer t3107 0
+ timer t3109 4
+ timer t3111 0
+ timer t3113 60
+ timer t3115 0
+ timer t3117 0
+ timer t3119 0
+ timer t3141 0
+ bts 0
+ type sysmobts
+ band DCS1800
+ cell_identity 0
+ location_area_code 1
+ training_sequence_code 7
+ base_station_id_code 63
+ ms max power 15
+ cell reselection hysteresis 4
+ rxlev access min 0
+ channel allocator ascending
+ rach tx integer 9
+ rach max transmission 7
+ ip.access unit_id 1801 0
+ oml ip.access stream_id 255 line 0
+ gprs mode none
+ trx 0
+ rf_locked 0
+ arfcn 514
+ nominal power 23
+ max_power_red 20
+ rsl e1 tei 0
+ 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
diff --git a/doc/examples/osmo-sgsn/osmo-sgsn.cfg b/doc/examples/osmo-sgsn/osmo-sgsn.cfg
new file mode 100644
index 0000000..4955983
--- /dev/null
+++ b/doc/examples/osmo-sgsn/osmo-sgsn.cfg
@@ -0,0 +1,26 @@
+!
+! Osmocom SGSN configuration
+!
+!
+line vty
+ no login
+!
+sgsn
+ gtp local-ip 127.0.0.1
+ ggsn 0 remote-ip 127.0.0.1
+ ggsn 0 gtp-version 1
+!
+ns
+ timer tns-block 3
+ timer tns-block-retries 3
+ timer tns-reset 3
+ timer tns-reset-retries 3
+ timer tns-test 30
+ timer tns-alive 3
+ timer tns-alive-retries 10
+ encapsulation udp local-ip 127.0.0.1
+ encapsulation udp local-port 23000
+ encapsulation framerelay-gre enabled 0
+!
+bssgp
+!
diff --git a/doc/gsm-hopping.txt b/doc/gsm-hopping.txt
new file mode 100644
index 0000000..c964963
--- /dev/null
+++ b/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):
+
+uint8_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 */
+
+
+uint8_t hopping_mai(uint8_t hsn, uint32_t fn, uint8_t maio,
+ uint8_t t1, uint8_t t2, uint8_t t3_)
+{
+ uint8_t mai;
+
+ if (hsn == 0) /* cyclic hopping */
+ mai = (fn + maio) % n;
+ else {
+ uint32_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/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
+
diff --git a/doc/ipa-sccp.txt b/doc/ipa-sccp.txt
new file mode 100644
index 0000000..5d6719e
--- /dev/null
+++ b/doc/ipa-sccp.txt
@@ -0,0 +1,94 @@
+
+IPA SCCP message flow in the BSC
+
+February, 2013 Holger Hans Peter Freyther
+
+CONTENTS
+
+1. SCCP inside the IPA header
+2. Supported SCCP message types
+3. Receiving SCCP messages
+4. Sending SCCP messages
+
+
+1. SCCP inside the IPA header
+
+Many Soft-MSCs implement something that is called SCCP/lite. This means
+that SCCP messages are transported inside a small multiplexing protocol
+over TCP/IP. This is an alternative to a full SIGTRAN implementation.
+
+The multiplexing protocol is the same as used with the sysmoBTS and the
+ip.access nanoBTS. It is a three byte header with two bytes for the length
+in network byte order and one byte for the type. The type to be used for
+SCCP is 0xFD.
+
+ struct ipa_header {
+ uint16_t length_in_network_order;
+ uint8_t type;
+ } __attribute__((packed));
+
+
+
+2. Supported SCCP message types
+
+To implement GSM 08.08 only a subset of SCCP messages need to be implemented.
+For transporting paging and reset messages SCCP UDT messages are used. For
+the connections with a Mobile Station (MS) a SCCP connection is opened. This
+means that the SCCP CR, SCCP CC, SCCP CREF, SCCP RLC, SCCP RLSD, SCCP DT1
+and SCCP IT messages are supported.
+
+
+3. Receiving SCCP UDT messages
+
+This is an illustration of the flow of messages. The IPA multiplexing protocol
+is used for various protocols. This means there is a central place where the
+multiplexing stream terminates. The stream is terminated in the osmo_bsc_msc.c
+file and the ipaccess_a_fd_cb method. For SCCP messages the SCCP dispatching
+sccp_system_incoming method is called. This function is implemented in the
+libosmo-sccp library.
+
+To receive UDT messages osmo_bsc_sccp.c:osmo_bsc_sccp_init is using the
+sccp_set_read function to register a callback for UDT messages. The callback
+is msc_sccp_read and it is calling bsc_handle_udt that is implemented in the
+osmo_bsc_bssap.c. This function will handle the GSM 08.08 BSSAP messages.
+Currently only the reset acknowledge and the paging messages are handled.
+
+The BSC currently does not accept incoming SCCP messages and is only opening
+SCCP connections to the MSC. When opening a connection the callbacks for state
+changes (connection confirmed, released, release complete) are set and a routine
+for handling incoming data. This registration is done in the osmo_bsc_sccp.c
+file and the bsc_create_new_connection method. The name of the callback is
+msc_outgoing_sccp_data and this will call bsc_handle_dt1 that is implemented
+in the osmo_bsc_bssap.c file. This will forward the messages to the right
+Mobile Station (MS).
+
+
+4. Sending SCCP messages
+
+There are three parts to sending that will be explained below. The first part
+is to send an entire SCCP frame (which includes the GSM 08.08 data) to the
+MSC. This is done by first registering the low level sending. sccp_system_init
+is called with the function that is responsible for sending a message. The
+msc_sccp_write_ipa will call the msc_queue_write function with the data and
+the right MSC connection. Below the msc_queue_write the IPA header will be
+prepended to the msg and then send to the MSC.
+
+The BSC supports multiple different A-link connections, the decision to pick
+the right MSC is done in this method. It is either done via the SCCP connection
+or the ctx pointer.
+
+When the BSC is starting a BSS RESET message will be sent to the MSC. The reset
+is created in osmo_bsc_msc.c:initialize_if_needed and sccp_write is called with
+the GSM 08.08 data and the connection to use. The libosmo-sccp library will
+embed it into a SCCP UDT message and call the msc_sccp_write_ipa method.
+
+When a new SCCP connection is to be created the bsc_create_new_connection
+in the osmo_bsc_sccp.c file. The sccp_connection_socket method will create
+the context for a SCCP connection. The state and data callback will be used
+to be notified about data and changes. Once the connection is configured the
+bsc_open_connection will be called that will ask the libosmo-sccp library to
+create a SCCP CR message using the sccp_connection_connect method. For active
+connections the sccp_connection_write method will be called.
+
+
+
diff --git a/doc/oml-interface.txt b/doc/oml-interface.txt
new file mode 100644
index 0000000..02bead7
--- /dev/null
+++ b/doc/oml-interface.txt
@@ -0,0 +1,22 @@
+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 BTS has 10s to ACK/NACK a command. We do not run any timers.
+
+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
diff --git a/doc/osmo-nitb-data_structures.dot b/doc/osmo-nitb-data_structures.dot
new file mode 100644
index 0000000..81955e8
--- /dev/null
+++ b/doc/osmo-nitb-data_structures.dot
@@ -0,0 +1,33 @@
+digraph G {
+ net [label="gsm_network"]
+ bts [label="gsm_bts"]
+ trx [label="gsm_bts_trx"]
+ ts [label="gsm_bts_trx_ts"]
+ lchan [label="gsm_lchan"]
+ sub [label="gsm_subscriber"]
+ subcon [label="gsm_subscriber_conn"]
+ sccpcon [label="osmo_bsc_sccp_con"]
+ subgrp [label="gsm_subscriber_group"]
+
+ net -> bts
+ bts -> trx
+ trx -> ts
+ ts -> lchan
+
+ lchan -> ts
+ ts -> trx
+ trx -> bts
+ bts -> net
+
+ lchan -> subcon
+
+ subcon -> sub
+ subcon -> sccpcon
+ subcon -> lchan
+ subcon -> lchan [label="ho_lchan"]
+ subcon -> bts
+ subcon -> lchan [label="secondary_lchan"]
+
+ sub -> subgrp
+ subgrp -> net
+}
diff --git a/doc/paging.txt b/doc/paging.txt
new file mode 100644
index 0000000..c597c22
--- /dev/null
+++ b/doc/paging.txt
@@ -0,0 +1,48 @@
+
+GSM Paging implementation in OpenBSC
+
+== Code structure ==
+
+The code is implemented in the libbsc/paging.c file. The external
+interface is documented/specified in the include/openbsc/paging.h
+header file. The code is used by the NITB and BSC application.
+
+
+== Implementation ==
+
+Paging can be initiated in two ways. The standard way is to page by
+LAC. Each BTS has its own list/queue of outstanding paging operation.
+When a subscriber is paged one "struct paging_request" per BTS will
+be allocated and added to the tail of the list. The BTS is supposed
+to be configured to not repeat the paging.
+
+A paging_request will remain in the queue until a paging response or at
+the expiry of the T3113. Every 500 milliseconds a RSL paging command is
+send to the BTS. The 500 milliseconds is a throttling to not crash the
+ip.access nanoBTS. Once one paging_request has been handled it will be
+put at the end of the queue/list and the available slots for the BTS
+will be decreased.
+
+The available slots will be updated based on the paging load information
+element of the CCCH Load indication. If no paging slots are considered
+to be available and no load indication is sent a timer is started. The
+current timeout is 500 milliseconds and at the expiry of the timer the
+available slots will be set to 20.
+
+OpenBSC has the " paging free <-1-1024>" configuration option. In case
+there are less free channels than required no paging request will be
+sent to the BTS. Instead it will be attempted to send the paging request
+at the next timeout (500 milliseconds).
+
+== Limitation ==
+
+The paging throughput could be higher but this has lead to crashes on the
+ip.access nanoBTS in the past.
+
+== Configuration ==
+
+=== ip.access nanoBTS ===
+
+The current CCCH Load indication threshold is 10% and the period is 1 second.
+The code can be found inside the src/libbsc/bts_ipaccess_nanobts.c inside the
+nanobts_attr_bts array.