initial checkin of manuals to public repo

The manuals existed in different form for several years in an internal
sysmocom repository.  However, since they had just recently been
converted from docboox-xml to asciidoc and all files have been
re-shuffled for enabling the public release, there's not much point in
keeping the history with git-filter-branch.

5 files changed, 914 insertions, 0 deletions

diff --git a/doc/manuals/chapters/architecture.adoc b/doc/manuals/chapters/architecture.adoc
new file mode 100644
index 00000000..aca5bb95
--- /dev/null
+++ b/doc/manuals/chapters/architecture.adoc
@@ -0,0 +1,120 @@
+== OsmoBTS software architecture
+
+=== OsmoBTS PHY interface abstraction
+
+The OsmoBTS PHY interface serves as an internal abstraction layer
+between given PHY hardware (as provided by the bts_model) and the actual
+logical transceivers (TRXs) of a BTS inside the OsmoBTS code base.
+
+
+==== PHY link
+
+A PHY link is a physical connection / link towards a given PHY.  This
+might be, for example,
+
+* a set of file descriptors to device nodes in the /dev/ directory
+  (sysmobts, litecell15)
+* a packet socket for sending raw Ethernet frames to an OCTPHY
+* a set of UDP sockets for interacting with OsmoTRX
+
+Each PHY interface has a set of attribute/parameters and a list of 1 to
+n PHY instances.
+
+PHY links are numbered 0..n globally inside OsmoBTS.
+
+Each PHY link is configured via the VTY using its individual top-level
+vty node.  Given the different bts-model / phy specific properties, the
+VTY configuration options (if any) of the PHY instance differ between
+BTS models.
+
+The PHY links and instances must be configured above the BTS/TRX nodes
+in the configuration file.  If the file is saved via the VTY, the code
+automatically ensures this.
+
+
+==== PHY instance
+
+A PHY instance is an instance of a PHY, accessed via a PHY link.
+
+In the case of osmo-bts-sysmo and osmo-bts-trx, there is only one
+instance in every PHY link.  This is due to the fact that the API inside
+that PHY link does not permit for distinguishing multiple different
+logical TRXs.
+
+Other PHY implementations like the OCTPHY however do support addressing
+multiple PHY instances via a single PHY link.
+
+PHY instances are numbered 0..n inside each PHY link.
+
+Each PHY instance is configured via the VTY as a separate node beneath each
+PHY link.  Given the different bts-model / phy specific properties, the
+VTY configuration options (if any) of the PHY instance differ between
+BTS models.
+
+
+==== Mapping PHY instances to TRXs
+
+Each TRX node in the VTY must use the 'phy N instance M' command in
+order to specify which PHY instance is allocated to this specific TRX.
+
+=== Internal control flow
+
+==== start-up / sequencing during OsmoBTS start
+
+.Control flow at OsmoBTS start-up procedure
+[options="header",cols="10%,35%,55%"]
+|===
+| section | function | description
+| bts-specific | main() | Entering main() from glibc
+| common | bts_main() | initialization of talloc contexts
+| common | bts_log_init() | initialization of logging
+| common | handle_options() | common option parsing
+| bts-specific | bts_model_handle_options() | model-specific option parsing
+| common | gsm_bts_alloc() | allocation of BTS/TRX/TS data structures
+| common | vty_init() | Initialziation of VTY core, libosmo-abis and osmo-bts VTY
+| common | main() | Setting of scheduler RR priority (if configured)
+| common | main() | Initialization of GSMTAP (if configured)
+| common | bts_init() | configuration of defaults in bts/trx/s object
+| bts-specific | bts_model_init | ?
+| common | abis_init() | Initialization of libosmo-abis
+| common | vty_read_config_file() | Reading of configuration file
+| bts-specific | bts_model_phy_link_set_defaults() | Called for every PHY link created
+| bts-specific | bts_model_phy_instance_set_defaults() | Called for every PHY Instance created
+| common | bts_controlif_setup() | Initialization of Control Interface
+| bts-specific | bts_model_ctrl_cmds_install() | Install model-specific control interface commands
+| common | telnet_init() | Initialization of telnet interface
+| common | pcu_sock_init() | Initializaiton of PCU socket
+| common | main() | Installation of signal handlers
+| common | abis_open() | Start of the A-bis connection to BSC
+| common | phy_links_open() | Iterate over list of configured PHY links
+| bts-specific | bts_model_phy_link_open() | Open each of the configured PHY links
+| common | write_pid_file() | Generate the pid file
+| common | osmo_daemonize() | Fork as daemon in background (if configured)
+| common | bts_main() | Run main loop until global variable quit >= 2
+|===
+
+
+==== At time of OML establishment
+
+.Control flow at time of OML establishment
+[options="header",cols="10%,35%,55%"]
+|===
+| section | function | description
+| bts-specific | bts_model_oml_estab() | Called by core once OML link is established
+| bts-specific | bts_model_check_oml() | called each time OML sets some attributes on a MO, checks if attributes are valid
+| bts-specific | bts_model_apply_oml() | called each time OML sets some attributes on a MO, stores attribute contents in data structures
+| bts-specific | bts_model_opstart() | for NM_OC_BTS, NM_OC_SITE_MANAGER, NM_OC_GPRS_NSE, NM_OC_GPRS_CELL, NMO_OC_GPRS_NSVC
+| bts-specific | bts_model_opstart() | for NM_OC_RADIO_CARRIER for each trx
+| bts-specific | bts_model_opstart() | for NM_OC_BASEB_TRANSC for each trx
+| bts-specific | bts_model_opstart() | for NM_OC_CHANNEL for each timeslot on each trx
+| bts-specific | bts_model_change_power() | change transmit power for each trx (power ramp-up/ramp-down)
+|===
+
+==== At time of RSL connection loss
+
+.Control flow at time of RSL connection loss
+[options="header",cols="10%,35%,55%"]
+|===
+| section | function | description
+| bts-specific | bts_model_abis_close() | called when either one of the RSL links or the OML link are down
+|===
diff --git a/doc/manuals/chapters/bts-models.adoc b/doc/manuals/chapters/bts-models.adoc
new file mode 100644
index 00000000..5a967f61
--- /dev/null
+++ b/doc/manuals/chapters/bts-models.adoc
@@ -0,0 +1,405 @@
+== OsmoBTS hardware support
+
+OsmoBTS consists of a generic part common to all BTS, and a
+hardware-specific _common_ part, and a _hardware-specific_ part.  The
+hardware specific part is generally referred to as the _bts_model_ code.
+
+The common part includes the core BTS architecture as well as code for
+implementing the external interfaces such Abis, control, PCU socket and
+GSMTAP.
+
+The bts_model parts include support for driving one particular
+implementation of a GSM physical layer (PHY).  Such a physical layer
+implementation can come in many forms.  Sometimes it runs on a general
+purpose CPU, sometimes on a dedicated ARM core, a dedicated DSP, a
+combination of DSP and FPGA.
+
+Every PHY implementation offers some kind of primitives by which the PHY
+can be controlled, and by which the PHY exchanges data with the higher
+layers of the protocol stack in the OsmoBTS code.
+
+The PHY-specific primitives are encapsulated in the bts_model code, and
+offered as a PHY-independent _L1SAP_ interface towards the common part of
+OsmoBTS.
+
+In addition, each bts_model implements a set of functions that the
+common part calls.  Those functions are pre-fixed by bts_model_.
+
+Each bts_model may offer
+
+* model-specific VTY commands for both configuration and run-time interaction
+* model-specific command line arguments
+* model-specific control interface commands
+
+== `osmo-bts-sysmo` for sysmocom sysmoBTS
+
+The sysmocom sysmoBTS is a range of GSM BTSs basd around an embedded
+system implementing the PHY in a combination of DSP+FPGA.  The PHY is
+configured by a set of primitives described by header files.  Those
+primitives are exchanged ove a set of message queues exposed on the
+Linux-running ARM core via device nodes in `/dev/msgq/`.  Internally,
+the message queues map to shared memory between the Linux-running ARM
+core and the DSP running the PHY implementation.
+
+The OsmoBTS bts_model code for the sysmoBTS can be found in the
+`src/osmo-bts-sysmo` sub-directory of the OsmoBTS code base.
+
+`osmo-bts-sysmo` has been the primary target platform for
+OsmoBTS for many years and is thus the most feature-complete and mature
+platform supported by OsmoBTS at this point.
+
+The sysmoBTS PHY supports a direct PHY interface to OsmoPCU, reducing
+the latency and amount of primitives that OsmoBTS would otherwise need
+to pass through from the PHY message queues to the PCU socket and
+vice-versa.
+
+
+=== `osmo-bts-sysmo` specific command line arguments
+
+*--dsp-trace 'DSPMASK'*::
+	Set the DSP trace flags (a single hexadecimal 32bit value).
+	This has been deprecated by VTY based commands, see
+	<<osmo-bts-sysmo-dsp-trace>> for further information.
+*--pcu-direct*::
+	Indicate that an external PCU (e.g. OsmoPCU) will directly
+	open the DSP messge queues to the PHY / PH-SAP, and only MPH
+	primitives are passed via OsmoBTS.
+
+
+=== `osmo-bts-sysmo` specific VTY commands
+
+For a auto-generated complete syntax reference of the VTY commands,
+please see the associated _OsmoBTS VTY reference manual_
+<<vty-ref-osmobts>>.  The section
+below only lists the most important commands.
+
+==== at the 'SHOW' node
+
+===== `show trx 0 clock-source`
+
+Display the currently active clock source configuration for the TRX
+
+[[osmo-bts-sysmo-dsp-trace]]
+===== `show trx 0 dsp-trace-flags`
+
+Show the currently active DSP trace flags for the TRX
+
+===== `trx 0 dsp-trace-flag`
+
+Use this command to enable/disable/configure the DSP tracing flags that
+define what debug messages will appear on `/dev/rtfifo/dsp_trace`.
+
+==== at the 'ENABLE' node
+
+===== `trx 0 tx-power <-110-100>`
+
+Change the current TRX transmit power to the given value in dBm.
+
+===== `trx 0 rf-clock-info reset`
+
+Part of the clock calibration procedure:
+Reset the clock correction value.
+
+===== `trx 0 rf-clock-info correct`
+
+Part of the clock calibration procedure:
+Apply the current measured correction value between the reference clock
+and the local clock.
+
+==== at the 'PHY instance' node
+
+==== `clock-calibration eeprom`
+
+Obtain clock calibration value from EEPROM.
+
+==== `clock-calibration default`
+
+Use hardware default clock calibration value.
+
+==== `clock-calibration <-4095-4095>`
+
+Use specified clock calibration value (not EEPROM/default).
+
+==== `clock-source (tcxo|ocxo|ext|gps)`
+
+Specify the clock source for the PHY:
+
+tcxo::
+	Use the TCXO.  This is the default on sysmoBTS 2050.
+ocxo::
+	Use the OCXO (only valid on units equipped with OCXO). This is
+	the default on all sysmoBTS 1002/1020/1100 and SOB-BTS.
+ext::
+	Use the external clock input.
+gps::
+	Use the clock derived from GPS.  You shouldn't use this clock
+	directly, but rather use the TCXO and regularly re-calibrate
+	against GPS.
+
+==== `trx-calibration-path PATH`
+
+Use calibration files from the given 'PATH', rather tan calibration
+values from the EEPROM.
+
+=== `osmo-bts-sysmo` specific control interface commands
+
+==== trx.0.clock-info
+
+Obtain information on the current clock status:
+
+----
+bsc_control.py -d localhost -p 4238 -g trx.0.clock-info
+Got message: GET_REPLY 1 trx.0.clock-info -100,ocxo,0,0,gps
+----
+
+which is to be interpreted as:
+
+* current clock correction value is -100 ppb
+* current clock source is OCXO
+* deviation between clock source and calibration source is 0 ppb
+* resolution of clock error measurement is 0 ppt (0 means no result yet)
+* current calibration source is GPS
+
+When this attribute is set, any value passed on is discarded, but the clock
+calibration process is re-started.
+
+==== trx.0.clock-correction
+
+This attribute can get and set the current clock correction value:
+
+----
+bsc_control.py -d localhost -p 4238 -g trx.0.clock-correction
+Got message: GET_REPLY 1 trx.0.clock-correction -100
+----
+
+----
+bsc_control.py -d localhost -p 4238 -s trx.0.clock-correction -- -99
+Got message: SET_REPLY 1 trx.0.clock-correction success
+----
+
+
+== `osmo-bts-trx` for OsmoTRX
+
+OsmoTRX is a C-language implementation of the GSM radio modem,
+originally developed as the 'Transceiver' part of OpenBTS.  This radio
+modem offers an interface based on top of UDP streams.
+
+The OsmoBTS bts_model code for OsmoTRX is called
+`osmo-bts-trx`.  It implements the UDP stream interface of
+OsmoTRX, so both parts can be used together to implement a complete GSM
+BTS based on general-purpose computing SDR.
+
+As OsmoTRX is general-purpose software running on top of Linux, it is
+thus not tied to any specific physical hardware.   At the time of this
+writing, OsmoTRX supports a variety of Ettus USRP SDRs via the UHD
+driver, as well as the Fairwaves UmTRX and derived products.
+
+OsmoTRX is not a complete GSM PHY but 'just' the radio modem.  This
+means that all of the Layer 1 functionality such as scheduling,
+convolutional coding, etc. is actually also implemented inside OsmoBTS.
+
+As such, the boundary between OsmoTRX and `osmo-bts-trx` is at
+a much lower interface, which is an internal interface of other more
+traditional GSM PHY implementations.
+
+Besides OsmoTRX, there are also other implementations (both Free
+Software and proprietary) that implement the same UDP stream based radio
+modem interface.
+
+
+=== `osmo-bts-trx` specific VTY commands
+
+For a auto-generated complete syntax reference of the VTY commands,
+pleas see the associated _OsmoBTS VTY reference manual_
+<<vty-ref-osmobts>>.  The section below only lists the most important
+commands.
+
+==== at the 'SHOW' node
+
+===== `show transceivers`
+
+Display information about configured/connected OsmoTRX transceivers in
+human-readable format to current VTY session.
+
+==== at the 'PHY' configuration node
+
+===== `osmotrx ip HOST`
+
+Set the IP addess of the OsmoTRX transceiver to which we should connect
+to.
+
+===== `osmotrx base-port (local|remote) <0-65535>`
+
+Configure the base UDP port for the OsmoTRX interface for either the
+local (OsmoBTS) or remote (OsmoTRX) side of the UDP flows.
+
+===== `osmotrx fn-advance <0-30>`
+
+Set the number of frames to be transmitted to transceiver in advance of
+current GSM frame number.
+
+===== `osmotrx rts-advance <0-30>`
+
+Set the number of frames to be requested from PCU in advance of current
+frame number.  Do not change this unless you have a good reason!
+
+===== `osmotrx rx-gain <0-50>`
+
+Set the receiver gain (configured in the hardware) in dB.
+
+===== `osmotrx tx-attenuation <0-50>`
+
+Set the transmitter attenuation (configured in the hardware) in dB.
+
+===== `osmotrx tx-attenuation oml`
+
+Use the Value in the A-bis OML Attribute `MAX_POWER_REDUCTION` as
+transmitter attenuation.
+
+==== at the 'PHY Instance' configuration node
+
+===== `slotmask (1|0) (1|0) (1|0) (1|0) (1|0) (1|0) (1|0) (1|0)`
+
+Configure which timeslots should be active on this TRX.  Normally all
+timeslots are enabled, unless you are running on a cpu-constrained
+deeply embedded system.
+
+===== `osmotrx maxdly <0-31>`
+
+Set the maximum delay for received symbols (in number of GSM symbols).
+
+
+== `osmo-bts-octphy` for Octasic OCTPHY-2G
+
+The Octasic OCTPHY-2G is a GSM PHY implementation inside an Octasic
+proprietary 24-core DSP called OCTDSP.
+
+This DSP has a built-in Gigabit Ethernet interface, over which it
+exchanges PHY-layer primitives in raw Ethernet frames with the upper
+layers running on another CPU attached to the same Ethernet.  Those
+primitives are described in a set of C-language header files.
+
+OsmoBTS implements the raw Ethernet frame based primitives as well as
+the associated transport protocol (OKTPKT/OCTVC1) in the
+`osmo-btso-octphy` bts_model code.
+
+You can run the `osmo-bts-octphy` on any system connected to the same
+Ethernet as the OCTDSP running the OCTPHY.  This can be either an
+embedded ARM or x86 SoM part of the OCTBTS hardware, or it can be any
+other Linux system attached via an Ethernet switch.
+
+Each OCTDSP running OCTSDR-2G offers a set of primitives part of a
+OCTPKT session, which is mapped to an OsmoBTS PHY link.  Depending on
+the OCTSDR-2G software version, you may create multiple software TRX by
+creating multiple OsmoBTS PHY instances inside that PHY link.
+
+Multiple DSPs may exsist in one circuit board, then each of the DSPs is
+interfaced by one OsmoBTS PHY link, and each of them may have one or
+more OsmoBTS PHY instances creating a Multi-TRX configuration.
+
+
+== `osmo-bts-litecell15` for Nutaq/Nuran LiteCell 1.5
+
+The Nutaq/Nuran LiteCell 1.5 implements a dual-transceiver GSM BTS based
+on a mixed ARM/DSP/FPGA architecture.  The PHY layer is implemented on
+DSP/FPGA and similar to that of the sysmoBTS:  It exchanges primitives
+described in a set of C-language header files over message queues
+between the ARM and the DSP.
+
+This interface is implemented in the `osmo-bts-litecell15` bts_model of
+OsmoBTS.  You would run `osmo-bts-litecell15` on the ARM/Linux processor
+of the Litecell 1.5.
+
+The two transceivers of the Litecell 1.5 each have their own set of DSP
+message queues.  Each set of message queues is wrapped into one OsmoBTS
+PHY link, offering one OsmoBTS PHY instance.
+
+The Litecell 1.5 PHY supports a direct PHY interface to OsmoPCU,
+reducing the latency and amount of primitives that OsmoBTS would
+otherwise need to pass through from the PHY message queues to the PCU
+socket and vice-versa.
+
+=== `osmo-bts-trx` specific VTY commands
+
+For a auto-generated complete syntax reference of the VTY commands,
+please see the associated _OsmoBTS VTY reference manual_
+<<vty-ref-osmobts>>.  The section below only lists the most important
+commands.
+
+==== at the 'SHOW' node
+
+===== `show phy <0-255> system-information`
+
+Show information about the hardware platform, DSP and OCTPHY-2G software
+version.
+
+===== `show phy <0-255> rf-port-stats <0-1>`
+
+Show information about the RF port interfaces.
+
+===== `show phy <0-255> clk-sync-stats`
+
+Show information about the clock synchronization manager.
+
+==== at the 'PHY' configuration node
+
+===== `octphy hw-addr HWADDR`
+
+Specify the Ethernet hardware address (mac address) of the DSP running
+the OCTPHY-2G software for this PHY link.
+
+===== `octphy net-device NAME`
+
+Specify the Ethernet network device (like `eth0`) through which the DSP
+can be reached from OsmoBTS.
+
+===== `octphy rf-port-index <0-255>`
+
+Specify which RF port should be used for this PHY link.
+
+===== `octphy rx-gain <0-73>`
+
+Configure the receiver gain in dB.
+
+===== `octphy tx-attenuation <0-359>`
+
+Configure the transmitter attenuation in quarter-dB
+
+
+
+
+== `osmo-bts-virtual` for Virtual Um Interface
+
+This is a special BTS model used for research, simulation and testing.
+Rather than communicating over a wireless RF interface, the GSM Um
+messages are encapsulated over GSMTAP/UDP/IP.
+
+At the time of writing, this functionality is not fully completed.  It
+is the idea to adopt the OsmocomBB MS-side GSM implementation to
+interface with this virtual Um interface, so that many instances of
+virtual MS can connect to some instances of OsmoBTS, testing MS, BTS,
+BSC and core network functionality.
+
+=== `osmo-bts-trx` specific VTY commands
+
+For a auto-generated complete syntax reference of the VTY commands,
+please see the associated _OsmoBTS VTY reference manual_
+<<vty-ref-osmobts>>.  The section below only lists the most important
+commands.
+
+==== at the 'PHY' config node
+
+===== `virtual-um net-device NETDEV`
+
+Configure the network device used for sending/receiving the virtual Um
+interface messages (e.g. `eth0`).
+
+===== `virtual-um udp-port <0-65535>`
+
+Configure the UDP port used for sending/receiving the virtual Um
+interface messages (default: GSMTAP 2775).
+
+===== `virtual-um multicast-group GROUP`
+
+Configure the IP multicast group used for sending/receiving the virtual
+Um interface messages.
diff --git a/doc/manuals/chapters/configuration.adoc b/doc/manuals/chapters/configuration.adoc
new file mode 100644
index 00000000..a2d06249
--- /dev/null
+++ b/doc/manuals/chapters/configuration.adoc
@@ -0,0 +1,154 @@
+== BTS Configuration
+
+The role of the BTS is to handle the GSM radio interface.  When the BTS
+application is starting, the A-bis OML connection is established towards
+the BSC.  Almost all BTS configuration (such as ARFCN, channel
+configuration, transmit power, etc.) will be sent from the BSC to the
+BTS via OML messages.  After OML start-up has competed, the BSC will
+instruct the BTS to establish the RSL connections.
+
+Given that most configuration is downloaded from the BSC into the BTS at
+start-up time, only some very basic settings have to be made in the
+OsmoBTS software.
+
+
+=== Command Line Options
+
+Ths OsmoBTS executables (`osmo-bts-sysmo`, `osmo-bts-trx`,
+`osmo-bts-octphy`, `osmo-bts-litecell15`, ...) share the following
+generic command line options:
+
+==== SYNOPSIS
+*osmo-bts-sysmo* [-h|-V] [-d 'DBGMASK'] [-D] [-c 'CONFIGFILE' ] [-s] [-T] [-e 'LOGLEVEL'] [-r 'PRIO'] [-i 'GSMTAP-IP'] [-t <1-255>]
+
+==== OPTIONS
+*-h, --help*::
+	Print a short help message about the supported options
+*-V, --version*::
+	Print the compile-time version number of the OsmoBTS program
+*-d, --debug 'DBGMASK','DBGLEVELS'*::
+	Set the log subsystems and levels for logging to stderr. This
+	has mostly been superseded by VTY-based logging configuration,
+	see <<logging>> for further information.
+*-D, --daemonize*::
+	Fork the process as a daemon into background.
+*-c, --config-file 'CONFIGFILE'*::
+	Specify the file and path name of the configuration file to be
+	used. If none is specified, use `osmo-bts.cfg` in the current
+	working directory.
+*-s, --disable-color*::
+	Disable colors for logging to stderr. This has mostly been
+	deprecated by VTY based logging configuration, see <<logging>>
+	for further information.
+*-T, --timestamp*::
+	Enable time-stamping of log messages to stderr. This has mostly
+	been deprecated by VTY based logging configuration, see
+	<<logging>> for further information.
+*-e, --log-level 'LOGLEVEL'*::
+	Set the global log level for logging to stderr. This has mostly
+	been deprecated by VTY based logging configuration, see
+	<<logging>> for further information.
+*-r, --realtime 'PRIO'*::
+	Enable use of the Linux kernel realtime priority scheduler with
+	the specified priority.
+	It is recommended you use this option on low-performance
+	embedded systems or systems that encounter high non-GSM/GPRS
+	load.
+*-i, --gsmtap-ip 'GSMTAP-IP'*::
+	Specify the destination IP address for GSMTAP messages.
+*-t, --trx-num <1-255>*::
+	Specify the number of TRX supported by this BTS.
+
+There may be additional, hardware specific command line options by the
+different bts_model implementations.
+
+
+=== Configuration using the VTY
+
+Most configuration as well as run-time monitoring and system
+introspection is implemented using a command-line based interface
+called _VTY_. A full reference syntax of all existing VTY command is
+available as a separate document.
+
+See <<vty>> for further information on the VTY.
+
+
+==== Required BTS/TRX configuration
+
+There are some settings that have to be configured locally in the
+sysmoBTS, as they cannot be set remotely from the BSC. Those
+settings are stored in the OsmoBTS configuration file, which commonly
+is stored in `/etc/osmocom/osmo-bts.cfg`.
+
+.Example Minimal configuration file
+----
+!
+! OsmoBTS (0.0.1.100-0455) configuration saved from vty
+!!
+!
+phy 0 <1>
+ instance 0 <2>
+bts 0 <3>
+ band DCS1800
+ ipa unit-id 1801 0 <4>
+ oml remote-ip 192.168.100.11 <5>
+ trx 0 <6>
+  phy 0 instance 0 <7>
+----
+<1> You must configure at least one PHY link by means of the PHY node
+<2> You must configure at least one PHY instance in the PHY link
+<3> There is always exactly one BTS (`bts 0`) configured in OsmoBTS
+<4> The `ipa unit-id` is what is used to identify this BTS to the BSC
+<6> The OML Remote IP is the IP address of the BSC, to which the BTS shall connect to.
+<6> There must be at least one trx (`trx 0`) in each BTS
+<7> Every TRX must be mapped to a specific PHY instance this way
+
+For a full reference of all available VTY configuration parameters,
+please refer to the OsmoBTS VTY Reference document.
+
+[[gsmtap]]
+==== Configuring GSMTAP tracing
+
+In addition to being able to obtain pcap protocol traces of the A-bis
+communication and the text-based logging from the OsmoBTS
+software, there is also the capability of tracing all communication on
+the radio interface. To do so, OsmoBTS can encapsulate
+MAC blocks (23byte messages at the L2-L1 interface) into _GSMTAP_ and send
+them via UDP/IP. At that point, they can be captured with utilities like
+*tcpdump* or *tshark* for further analysis by the *wireshark* protocol
+analyzer.
+
+In order to activate this feature, you first need to make sure to start
+OsmoBTS using the `-i` or `--gsmtap-ip` command line option, specifying
+the destination IP address for the GSMTAP messages.  In most cases,
+using 127.0.0.1 for passing the messages over the loopback (`lo`) device
+will be sufficient.
+
+OsmoBTS can selectively trace such messages by their L1 SAPI, for both
+Rx and Tx. For a complete list of L1 SAPI values, please refer to the
+_OsmoBTS VTY reference manual_ <<vty-ref-osmobts>>.
+
+For example, to enable GSMTAP tracing for messages on all SDCCH
+channels, you can use the gsmtap-sapi sdcch command at the CONFIG TRX
+node of the OsmoBTS VTY.
+
+.Example: Enabling  GSMTAP for SDCCH
+----
+OsmoBTS> enable
+OsmoBTS# configure terminal
+OsmoBTS(config)# bts
+OsmoBTS(bts)# trx 0
+OsmoBTS(trx)# gsmtap-sapi sdcch
+OsmoBTS(trx)# write <1>
+----
+<1> the `write` command will make the configuration persistent in the
+configuration file.  This is not required if you wish to enable GSMTAP
+only in the current session of OsmoBTS.
+
+De-activation can be performed similarly by using the `no gsmtap-sapi
+sdcch` command at the `trx` node of the OsmoBTS VTY.
+
+From the moment they are enabled via VTY, GSMTAP messages will be
+generated and sent in UDP encapsulation to the IANA-registered UDP port
+for GSMTAP (4729) at the IP address specified in the command line
+argument.
diff --git a/doc/manuals/chapters/interfaces.adoc b/doc/manuals/chapters/interfaces.adoc
new file mode 100644
index 00000000..f5bf1b20
--- /dev/null
+++ b/doc/manuals/chapters/interfaces.adoc
@@ -0,0 +1,130 @@
+== OsmoBTS Interfaces
+
+OsmoBTS offers a set of interfaces to interact with external entities:
+
+* A-bis/IP interface to talk to the BSC
+* bts_model specific PHY interface
+* VTY interface
+* Osmocom control interface
+* GSMTAP interface
+* PCU interface
+
+
+=== OsmoBTS Abis/IP Interface
+
+OsmoBTS implements the GSM A-bis interface as described in the relevant
+3GPP specifications:
+
+* A-bis RSL according to 3GPP TS 08.58
+* A-bis OML according to 3GPP TS 12.21
+
+As the 3GPP specified A-bis only over E1 interfaces and not over IP,
+significant enhancements and modifications have been performed as opposed
+to the 3GPP specifications.  Nevertheless, the implementation tries to
+stay as close a possible to the 3GPP specifications.
+
+Please see the _OsmoBTS Abis Protocol Specification_
+<<osmobts-abis-spec>> for more information on this subject.
+
+
+=== bts_model specific PHY interface
+
+This interface is specific to the bts_model that OsmoBTS was compiled
+for.  It can take any form as required by the respective hardware.
+
+Please see the PHY documentation of your respective BTS hardware for more
+details.
+
+
+=== OsmoBTS VTY Interface
+
+See <<vty>> for further information.
+
+
+=== OsmoBTS Control Interface
+
+The general structure of the Omsocom control interface is described in
+<<common-control-if>>.
+
+The number of control interface commands/attributes is currently quite
+limited and largely depends on the bts_model used.
+
+==== trx.N.thermal-attenuation
+
+The idea of this paramter is to attenuate the system output power as part of
+thermal management.  In some cases the PA might be passing a critical level,
+so an external control process can use this attribute to reduce the system
+output power.
+
+Please note that all values in the context of transmit power calculation
+are integers in milli-dB (1/10000 bel), so the below example is setting
+the attenuation at 3 dB:
+
+----
+bsc_control.py -d localhost -p 4238 -s trx.0.thermal-attenuation 3000
+Got message: SET_REPLY 1 trx.0.thermal-attenuation 3000
+----
+
+----
+bsc_control.py -d localhost -p 4238 -g trx.0.thermal-attenuation
+Got message: GET_REPLY 1 trx.0.thermal-attenuation 3000
+----
+
+
+
+=== OsmoBTS GSMTAP Interface
+
+GSMTAP is a standard created by Osmocom to UDP-encapsulate GSM protocol
+messages normally communicated over non-IP interfaces for the primary
+purpose of protocol analysis in the wireshark dissector.
+
+The initial purpose was to encapsulate GSM Um frames including some
+meta-data like ARFCN and GSM frame number into something that can be
+parsed and dispatched within the wireshark dissector.
+
+This interface has since been extended to many other
+GSM/GPRS/UMTS interfaces and protocols, and even to TETRA and GMR.
+
+In OsmoBTS, it is possible to export both uplink and downlink Um
+messages via GSMTAP.  There is a set of VTY configuration options to
+specify for which logical channels of the Um interface GSMTAP messages
+shall be emitted, and to which destination IP address they shall be
+sent.
+
+Using GSMTAP it is possible to place a virtual tap at the air interface
+between BTS and MS, without going through the trouble of setting up an
+actual radio receiver at the same frequencies.  Also, GSMTAP export is
+performed before the Um air-interface encryption (A5) is performed, so
+all frames are always in plain text.
+
+Please refer to <<gsmtap>> for more information on how to configure and
+use this interface.
+
+
+=== OsmoBTS PCU Socket Interface
+
+In order to assist the provisioning of GPRS services over the same radio
+interface as circuit-switched GSM, OsmoBTS exposes a Unix domain socket
+based interface towards OsmoPCU.
+
+OsmoPCU is the Osmocom implementation of the GPRS Packet Control Unit
+(PCU), which is co-located with the BTS in the Osmocom implementation.
+Contrary to that, many classic E1-based implementations of the GSM RAN
+co-locate the PCU with the BSC.  However, the GSM specifications keep
+the location up to the implementor.
+
+The PCU socket interface serves the following purposes:
+
+* to pass PCU relevant configuration from BTS to PCU
+* to forward paging requests from BTS to PCU
+* to forward RACH Requests from BTS to PCU
+
+Depending on your bts_model, the PCU may also be passing actual
+PH-DATA.request / PH-DATA.indication / PH-RTS.indication primitives for
+the PDCH.  This is considered sub-optimal, and some BTS models offer a
+direct interface by which the PCU can exchange those primitives directly
+with the PHY.
+
+The default PCU socket interface name is `/tmp/pcu_sock`, but this can
+be overridden by the @pcu-socket@ VTY command in the BTS configuration
+VTY node.
diff --git a/doc/manuals/chapters/overview.adoc b/doc/manuals/chapters/overview.adoc
new file mode 100644
index 00000000..6b6b8284
--- /dev/null
+++ b/doc/manuals/chapters/overview.adoc
@@ -0,0 +1,105 @@
+== Overview
+
+=== About this manual
+
+This manual should help you getting started with the OsmoBTS software.
+It will cover aspects of configuring and running OsmoBTS as well as some
+introduction about its internal architecture and external interfaces.
+
+=== About OsmoBTS
+
+OsmoBTS is an implementation of a GSM BTS (Base Transceiver Station).  A
+BTS serves  as the interface between the Um radio interface towards
+phones  and the wired Abis interface towards the BSC (Base Station
+Controller).  It also implements the network side of the Layer 2 of the
+Um radio interface: The LAPDm protocol.
+
+OsmoBTS is licensed as Free and Open Source Software (FOSS) under _GNU
+AGPLv3_ <<gnu-agplv3>>.  It is developed as one GSM network
+infrastructure component part of the overall Osmocom project.
+
+As perhaps the first implementation of a GSM BTS ever in the industry,
+OsmoBTS is implemented in a vendor-independent way and supports a large
+variety of transceiver hardware and physical layer implementations from
+many vendors.
+
+=== Credits
+
+OsmoBTS was originally developed in 2011 by Andreas Eversberg and Harald
+Welte.  It has since been maintained by Harald Welte and Holger Freyther
+at sysmocom.
+
+=== OsmoBTS in the Osmocom GSM network architecture
+
+OsmoBTS can be used in combination with the various other GSM network
+elements developed under the umbrella of the Osmocom project.
+
+Typical configurations either use OsmoBTS with OsmoBSC, or with
+OsmoNITB, as can be seen in the following figures.
+
+[[fig-gsm-classic]]
+.Classic GSM archtiecture using OsmoBTS with OsmoBTS components
+[graphviz]
+----
+digraph G {
+	rankdir=LR;
+	MS0 [label="MS"]
+	MS1 [label="MS"]
+	MS2 [label="MS"]
+	MS3 [label="MS"]
+	BTS0 [label="OsmoBTS"]
+	BTS1 [label="OsmoBTS"]
+	BSC [label="OsmoBSC"]
+	MSC [label="MSC/VLR"]
+	HLR [label="HLR/AUC"]
+	MS0->BTS0 [label="Um"]
+	MS1->BTS0 [label="Um"]
+	MS2->BTS1 [label="Um"]
+	MS3->BTS1 [label="Um"]
+	BTS0->BSC [label="Abis"]
+	BTS1->BSC [label="Abis"]
+	BSC->MSC [label="A"]
+	MSC->HLR [label="C"]
+	MSC->EIR [label="F"]
+	MSC->SMSC
+}
+----
+
+
+[[fig-gsm-nitb]]
+.GSM architecture using OsmoBTS + OsmoNITB
+[graphviz]
+----
+digraph G {
+	rankdir=LR;
+	MS0 [label="MS"]
+	MS1 [label="MS"]
+	MS2 [label="MS"]
+	MS3 [label="MS"]
+	BTS0 [label="OsmoBTS"]
+	BTS1 [label="OsmoBTS"]
+	MS0->BTS0 [label="Um"]
+	MS1->BTS0 [label="Um"]
+	MS2->BTS1 [label="Um"]
+	MS3->BTS1 [label="Um"]
+	BTS0->BSC [label="Abis"]
+	BTS1->BSC [label="Abis"]
+	subgraph cluster_nitb {
+		label = "OsmoNITB";
+		BSC
+		MSC [label="MSC/VLR"]
+		HLR [label="HLR/AUC"]
+		BSC->MSC [label="A"]
+		MSC->HLR [label="C"]
+		MSC->EIR [label="F"]
+		MSC->SMSC;
+	}
+}
+----
+
+If intended by the user, it is of course also possible to implement an
+OsmoBTS-compatible Abis-over-IP interface in any third party BSC.  The
+Abis/IP interface and its protocol are documented in the _OsmoBTS
+Abis Protocol Specification_ <<osmobts-abis-spec>>.  However, be advised
+that such a configuration is currently not officially supported by
+Osmocom.