Merge history from osmo-gsm-manuals.git

Change-Id: I33ce528bb58a8a730a15cc8a7a74852a14f42921

5 files changed, 487 insertions, 0 deletions

diff --git a/doc/manuals/chapters/configuration.adoc b/doc/manuals/chapters/configuration.adoc
new file mode 100644
index 00000000..6fc61c77
--- /dev/null
+++ b/doc/manuals/chapters/configuration.adoc
@@ -0,0 +1,205 @@
+== Configuring OsmoPCU
+
+Contrary to other network elements (like OsmoBSC, OsmoNITB), the
+OsmoPCU has a relatively simple minimum configuration.
+
+This is primarily because most of the PCU configuration happens
+indirectly from the BSC, who passes the configuation over A-bis OML via
+OsmoBTS and its PCU socket into OsmoPCU.
+
+A minimal OsmoPCU configuration file is provided below for your reference:
+
+.Example: Minimal OsmoPCU configuration file (`osmo-pcu.cfg`)
+----
+pcu
+ flow-control-interval 10 <1>
+ cs 2 <2>
+ alloc-algorithm dynamic <3>
+ alpha 0 <4>
+ gamma 0
+----
+<1> send a BSSGP flow-control PDU every 10 seconds
+<2> start a TBF with the initial coding scheme 2
+<3> dynamically chose between single-slot or multi-slot TBF allocations
+    depending on system load
+<4> disable MS power control loop
+
+However, there are plenty of tuning parameters for people interested to
+optimize PCU throughput or latency according to their requirements.
+
+=== Configuring the Coding Schemes and Rate Adaption
+
+The BSC includes a bit-mask of permitted [E]GPRS coding schemes as part
+of the A-bis OML configuration.  This is passed from the BTS via the PCU
+socket into OsmoPCU.
+
+Some additional parameters can be set as described below.
+
+==== Initial Coding Scheme
+
+You can use the `cs <1-4> [<1-4>]` command at the `pcu` VTY config node
+to set the initial GPRS coding scheme to be used.  The optional second
+value allows to specify a different initial coding scheme for uplink.
+
+==== Maximum Coding Scheme
+
+You can use the `cs max <1-4> [<1-4>]` command at the `pcu` VTY config
+node to set the maximum coding scheme that should be used as part of the
+rate adaption.
+
+==== Rate Adaption Error Thresholds
+
+You can use the `cs threshold <0-100> <0-100>` command at the `pcu` VTY
+config node to determine the upper and lower limit for the error rate
+percentage to use in the rate adaption.  If the upper threshold is
+reached, a lower coding sheme is chosen, and if the lower threshold is
+reached, a higher coding scheme is chosen.
+
+==== Rate Adation Link Quality Thresholds
+
+You can use the `cs link-quality-ranges cs1 <0-35> cs2 <0-35> <0-35> cs3
+<0-35> <0-35> cs4 <0-35>` command at the `pcu` VTY config node to tune
+the link quality ranges for the respective coding schemes.
+
+==== Data Size based CS downgrade Threshold
+
+You can use the `cs downgrade-threshold <1-10000>` command at the `pcu`
+VTY config node to ask the PCU to down-grade the coding scheme if less
+than the specified number of octets are left to be transmitted.
+
+=== Miscellaneous Configuration / Tuning Parameters
+
+==== Downlink TBF idle time
+
+After a down-link TBF is idle (all data in the current LLC downlink
+queue for the MS has been transmitted), we can keep the TBF established
+for a configurable time.  This avoids having to go through a new one or
+two phase TBF establishment once the next data for downlink arrives.
+
+You can use the `dl-tbf-idle-time <1-5000>` to specify that time in
+units of milli-seconds.  The default is 2 seconds.
+
+==== MS idle time
+
+Using the `ms-idle-time <1-7200>` command at the `pcu` VTY config node
+you can configure the number of seconds for which the PCU should keep
+the MS data structure alive before releasing it if there are no active
+TBF for this MS.
+
+The OsmoPCU default value is 60 seconds, which is slightly more than
+what 3GPP TS 24.008 recommends for T3314 (44s).
+
+The MS data structure only consumes memory in the PCU and does not
+require any resources of the air interface.
+
+==== Forcing two-phase access
+
+If the MS is using a single-phase access, you can still force it to
+use a two-phase access using the `two-phase-access` VTY configuration
+command at the `pcu` VTY config node.
+
+=== Configuring BSSGP flow control
+
+BSSGP between SGSN and PCU contains a two-level nested flow control
+mechanism:
+
+. one global flow control instance for the overall (downlink) traffic
+  from the SGSN to this PCU
+. a per-MS flow control instance for each individual MS served by this
+  PCU
+
+Each of the flow control instance is implemented as a TBF (token bucket
+filter).
+
+==== Normal BSSGP Flow Control Tuning parameters
+
+You can use the following commands at the `pcu` VTY config node to tune
+the BSSGP flow control parameters:
+
+`flow-control-interval <1-10>`::
+	configure the interval (in seconds) between subsequent flow
+	control PDUs from PCU to SGSN
+`flow-control bucket-time <1-65534>`::
+	set the target downlink maximum queueing time in centi-seconds.
+	The PCU will attempt to adjust the advertised bucket size to match this
+	target.
+
+==== Extended BSSGP Flow Control Tuning parameters
+
+There are some extended flow control related parameters at the `pcu` VTY
+config node that override the automatic flow control as specified in the
+BSSGP specification.  Use them with care!
+
+`flow-control force-bvc-bucket-size <1-6553500>`::
+	force the BVC (global) bucket size to the given number of octets
+`flow-control force-bvc-leak-rate <1-6553500>`::
+	force the BVC (global) bucket leak rate to the given number of bits/s
+`flow-control force-ms-bucket-size <1-6553500>`::
+	force the per-MS bucket size to the given number of octets
+`flow-control force-ms-leak-rate <1-6553500>`::
+	force the per-MS bucket leak rate to the given number of bits/s
+
+
+=== Configuring LLC queue
+
+The downlink LLC queue in the PCU towards the MS can be tuned with a
+variety of parameters at the `pcu` VTY config node, depending on your
+needs.
+
+`queue lifetime <1-65534>`::
+	Each downlink LLC PDU is assigned a lifetime by the SGSN, which
+	is respected by the PDU *unless* you use this command to
+	override the PDU lifetime with a larger value (in centi-seconds)
+`queue lifetime infinite`::
+	Never drop LLC PDUs, i.e. give them an unlimited lifetime.
+`queue hysteresis <1-65535>`::
+	When the downlink LLC queue is full, the PCU starts dropping
+	packets.  Using this parameter, we can set the lifetime
+	hysteresis in centi-seconds, i.e. it will continue discarding
+	until "lifetime - hysteresis" is reached.
+`queue codel`::
+	Use the 'CoDel' (Controlled Delay) scheduling algorithm, which
+	is designed to overcome buffer bloat.  It will use a default
+	interval of 4 seconds.
+`queue codel interval <1-1000>`::
+	Use the 'CoDel' (Controlled Delay) scheduling algorithm, which
+	is designed to overcome buffer bloat.  Use the specified
+	interval in centi-seconds.
+`queue idle-ack-delay <1-65535>`::
+	Delay the request for an ACK after the last downlink LLC frame
+	by the specified amount of centi-seconds.
+
+
+=== Configuring MS power control
+
+GPRS MS power control works completely different than the close MS power
+control loop in circuit-switched GSM.
+
+Rather than instructing the MS constantly about which transmit power to
+use, some parameters are provided to the MS by which the MS-based power
+control algorithm is tuned.
+
+See 3GPP TS 05.08 for further information on the algorithm and the
+parameters.
+
+You can set those parameters at the `pcu` VTY config node as follows:
+
+`alpha <0-10>`::
+	Alpha parameter for MS power control in units of 0.1.
+	Make sure to set the alpha value at System Information 13 (in
+	the BSC), too!
+`gamma <0-62>`::
+	Set the gamma parameter for MS power control in units of dB.
+
+
+=== Enabling EGPRS
+
+If you would like to test the currently (experimental) EGPRS support of
+OsmoPCU, you can enable it using the `egprs` command at the `pcu` VTY
+config  node.
+
+WARNING: EPGRS functionality is highly experimental at the time of this
+writing.  Please only use if you actively would like to participate in
+the OsmoPCU EGPRS development and/or testing.  You will also need an
+EGPRS capable OsmoBTS+PHY, which means `osmo-bts-sysmo` or
+`osmo-bts-litecell15` with their associated PHY.
diff --git a/doc/manuals/chapters/counters.adoc b/doc/manuals/chapters/counters.adoc
new file mode 100644
index 00000000..7fbb10c6
--- /dev/null
+++ b/doc/manuals/chapters/counters.adoc
@@ -0,0 +1,4 @@
+[[counters]]
+== Counters
+
+include::./counters_generated.adoc[]
diff --git a/doc/manuals/chapters/counters_generated.adoc b/doc/manuals/chapters/counters_generated.adoc
new file mode 100644
index 00000000..2ee425e7
--- /dev/null
+++ b/doc/manuals/chapters/counters_generated.adoc
@@ -0,0 +1,178 @@
+// autogenerated by show asciidoc counters
+These counters and their description based on Osmo-PCU 0.4.0.4-8d55 (Osmo-PCU).
+
+// generating tables for rate_ctr_group
+// rate_ctr_group table BSSGP Peer Statistics
+.bssgp:bss_ctx - BSSGP Peer Statistics 
+[options="header"]
+|===
+| Name | Reference | Description
+| packets:in | <<bssgp:bss_ctx_packets:in>> | Packets at BSSGP Level ( In)
+| packets:out | <<bssgp:bss_ctx_packets:out>> | Packets at BSSGP Level (Out)
+| bytes:in | <<bssgp:bss_ctx_bytes:in>> | Bytes at BSSGP Level   ( In)
+| bytes:out | <<bssgp:bss_ctx_bytes:out>> | Bytes at BSSGP Level   (Out)
+| blocked | <<bssgp:bss_ctx_blocked>> | BVC Blocking count
+| discarded | <<bssgp:bss_ctx_discarded>> | BVC LLC Discarded count
+| status | <<bssgp:bss_ctx_status>> | BVC Status count
+|===
+// rate_ctr_group table NSVC Peer Statistics
+.ns:nsvc - NSVC Peer Statistics 
+[options="header"]
+|===
+| Name | Reference | Description
+| packets:in | <<ns:nsvc_packets:in>> | Packets at NS Level  ( In)
+| packets:out | <<ns:nsvc_packets:out>> | Packets at NS Level  (Out)
+| bytes:in | <<ns:nsvc_bytes:in>> | Bytes at NS Level    ( In)
+| bytes:out | <<ns:nsvc_bytes:out>> | Bytes at NS Level    (Out)
+| blocked | <<ns:nsvc_blocked>> | NS-VC Block count         
+| dead | <<ns:nsvc_dead>> | NS-VC gone dead count     
+| replaced | <<ns:nsvc_replaced>> | NS-VC replaced other count
+| nsei-chg | <<ns:nsvc_nsei-chg>> | NS-VC changed NSEI count  
+| inv-nsvci | <<ns:nsvc_inv-nsvci>> | NS-VCI was invalid count  
+| inv-nsei | <<ns:nsvc_inv-nsei>> | NSEI was invalid count    
+| lost:alive | <<ns:nsvc_lost:alive>> | ALIVE ACK missing count   
+| lost:reset | <<ns:nsvc_lost:reset>> | RESET ACK missing count   
+|===
+// rate_ctr_group table NSVC Peer Statistics
+.ns:nsvc - NSVC Peer Statistics 
+[options="header"]
+|===
+| Name | Reference | Description
+| packets:in | <<ns:nsvc_packets:in>> | Packets at NS Level  ( In)
+| packets:out | <<ns:nsvc_packets:out>> | Packets at NS Level  (Out)
+| bytes:in | <<ns:nsvc_bytes:in>> | Bytes at NS Level    ( In)
+| bytes:out | <<ns:nsvc_bytes:out>> | Bytes at NS Level    (Out)
+| blocked | <<ns:nsvc_blocked>> | NS-VC Block count         
+| dead | <<ns:nsvc_dead>> | NS-VC gone dead count     
+| replaced | <<ns:nsvc_replaced>> | NS-VC replaced other count
+| nsei-chg | <<ns:nsvc_nsei-chg>> | NS-VC changed NSEI count  
+| inv-nsvci | <<ns:nsvc_inv-nsvci>> | NS-VCI was invalid count  
+| inv-nsei | <<ns:nsvc_inv-nsei>> | NSEI was invalid count    
+| lost:alive | <<ns:nsvc_lost:alive>> | ALIVE ACK missing count   
+| lost:reset | <<ns:nsvc_lost:reset>> | RESET ACK missing count   
+|===
+// rate_ctr_group table BTS Statistics
+.bts - BTS Statistics 
+[options="header"]
+|===
+| Name | Reference | Description
+| tbf:dl:alloc | <<bts_tbf:dl:alloc>> | TBF DL Allocated     
+| tbf:dl:freed | <<bts_tbf:dl:freed>> | TBF DL Freed         
+| tbf:dl:aborted | <<bts_tbf:dl:aborted>> | TBF DL Aborted       
+| tbf:ul:alloc | <<bts_tbf:ul:alloc>> | TBF UL Allocated     
+| tbf:ul:freed | <<bts_tbf:ul:freed>> | TBF UL Freed         
+| tbf:ul:aborted | <<bts_tbf:ul:aborted>> | TBF UL Aborted       
+| tbf:reused | <<bts_tbf:reused>> | TBF Reused           
+| tbf:alloc:algo-a | <<bts_tbf:alloc:algo-a>> | TBF Alloc Algo A     
+| tbf:alloc:algo-b | <<bts_tbf:alloc:algo-b>> | TBF Alloc Algo B     
+| tbf:failed:egprs-only | <<bts_tbf:failed:egprs-only>> | TBF Failed EGPRS-only
+| rlc:sent | <<bts_rlc:sent>> | RLC Sent             
+| rlc:resent | <<bts_rlc:resent>> | RLC Resent           
+| rlc:restarted | <<bts_rlc:restarted>> | RLC Restarted        
+| rlc:stalled | <<bts_rlc:stalled>> | RLC Stalled          
+| rlc:nacked | <<bts_rlc:nacked>> | RLC Nacked           
+| rlc:final_block_resent | <<bts_rlc:final_block_resent>> | RLC Final Blk resent 
+| rlc:ass:timedout | <<bts_rlc:ass:timedout>> | RLC Assign Timeout   
+| rlc:ass:failed | <<bts_rlc:ass:failed>> | RLC Assign Failed    
+| rlc:ack:timedout | <<bts_rlc:ack:timedout>> | RLC Ack Timeout      
+| rlc:ack:failed | <<bts_rlc:ack:failed>> | RLC Ack Failed       
+| rlc:rel:timedout | <<bts_rlc:rel:timedout>> | RLC Release Timeout  
+| rlc:late-block | <<bts_rlc:late-block>> | RLC Late Block       
+| rlc:sent-dummy | <<bts_rlc:sent-dummy>> | RLC Sent Dummy       
+| rlc:sent-control | <<bts_rlc:sent-control>> | RLC Sent Control     
+| rlc:dl_bytes | <<bts_rlc:dl_bytes>> | RLC DL Bytes         
+| rlc:dl_payload_bytes | <<bts_rlc:dl_payload_bytes>> | RLC DL Payload Bytes 
+| rlc:ul_bytes | <<bts_rlc:ul_bytes>> | RLC UL Bytes         
+| rlc:ul_payload_bytes | <<bts_rlc:ul_payload_bytes>> | RLC UL Payload Bytes 
+| decode:errors | <<bts_decode:errors>> | Decode Errors        
+| sba:allocated | <<bts_sba:allocated>> | SBA Allocated        
+| sba:freed | <<bts_sba:freed>> | SBA Freed            
+| sba:timedout | <<bts_sba:timedout>> | SBA Timeout          
+| llc:timeout | <<bts_llc:timeout>> | Timedout Frames      
+| llc:dropped | <<bts_llc:dropped>> | Dropped Frames       
+| llc:scheduled | <<bts_llc:scheduled>> | Scheduled Frames     
+| llc:dl_bytes | <<bts_llc:dl_bytes>> | RLC encapsulated PDUs
+| llc:ul_bytes | <<bts_llc:ul_bytes>> | full PDUs received   
+| rach:requests | <<bts_rach:requests>> | RACH requests        
+| 11bit_rach:requests | <<bts_11bit_rach:requests>> | 11BIT_RACH requests  
+| spb:uplink_first_segment | <<bts_spb:uplink_first_segment>> | First seg of UL SPB  
+| spb:uplink_second_segment | <<bts_spb:uplink_second_segment>> | Second seg of UL SPB 
+| spb:downlink_first_segment | <<bts_spb:downlink_first_segment>> | First seg of DL SPB  
+| spb:downlink_second_segment | <<bts_spb:downlink_second_segment>> | Second seg of DL SPB 
+| immediate:assignment_UL | <<bts_immediate:assignment_UL>> | Immediate Assign UL  
+| immediate:assignment_rej | <<bts_immediate:assignment_rej>> | Immediate Assign Rej 
+| immediate:assignment_DL | <<bts_immediate:assignment_DL>> | Immediate Assign DL  
+| channel:request_description | <<bts_channel:request_description>> | Channel Request Desc 
+| pkt:ul_assignment | <<bts_pkt:ul_assignment>> | Packet UL Assignment 
+| pkt:access_reject | <<bts_pkt:access_reject>> | Packet Access Reject 
+| pkt:dl_assignment | <<bts_pkt:dl_assignment>> | Packet DL Assignment 
+| ul:control | <<bts_ul:control>> | UL control Block     
+| ul:assignment_poll_timeout | <<bts_ul:assignment_poll_timeout>> | UL Assign Timeout    
+| ul:assignment_failed | <<bts_ul:assignment_failed>> | UL Assign Failed     
+| dl:assignment_timeout | <<bts_dl:assignment_timeout>> | DL Assign Timeout    
+| dl:assignment_failed | <<bts_dl:assignment_failed>> | DL Assign Failed     
+| pkt:ul_ack_nack_timeout | <<bts_pkt:ul_ack_nack_timeout>> | PUAN Poll Timeout    
+| pkt:ul_ack_nack_failed | <<bts_pkt:ul_ack_nack_failed>> | PUAN poll Failed     
+| pkt:dl_ack_nack_timeout | <<bts_pkt:dl_ack_nack_timeout>> | PDAN poll Timeout    
+| pkt:dl_ack_nack_failed | <<bts_pkt:dl_ack_nack_failed>> | PDAN poll Failed     
+| gprs:downlink_cs1 | <<bts_gprs:downlink_cs1>> | CS1 downlink         
+| gprs:downlink_cs2 | <<bts_gprs:downlink_cs2>> | CS2 downlink         
+| gprs:downlink_cs3 | <<bts_gprs:downlink_cs3>> | CS3 downlink         
+| gprs:downlink_cs4 | <<bts_gprs:downlink_cs4>> | CS4 downlink         
+| egprs:downlink_mcs1 | <<bts_egprs:downlink_mcs1>> | MCS1 downlink        
+| egprs:downlink_mcs2 | <<bts_egprs:downlink_mcs2>> | MCS2 downlink        
+| egprs:downlink_mcs3 | <<bts_egprs:downlink_mcs3>> | MCS3 downlink        
+| egprs:downlink_mcs4 | <<bts_egprs:downlink_mcs4>> | MCS4 downlink        
+| egprs:downlink_mcs5 | <<bts_egprs:downlink_mcs5>> | MCS5 downlink        
+| egprs:downlink_mcs6 | <<bts_egprs:downlink_mcs6>> | MCS6 downlink        
+| egprs:downlink_mcs7 | <<bts_egprs:downlink_mcs7>> | MCS7 downlink        
+| egprs:downlink_mcs8 | <<bts_egprs:downlink_mcs8>> | MCS8 downlink        
+| egprs:downlink_mcs9 | <<bts_egprs:downlink_mcs9>> | MCS9 downlink        
+| gprs:uplink_cs1 | <<bts_gprs:uplink_cs1>> | CS1 Uplink           
+| gprs:uplink_cs2 | <<bts_gprs:uplink_cs2>> | CS2 Uplink           
+| gprs:uplink_cs3 | <<bts_gprs:uplink_cs3>> | CS3 Uplink           
+| gprs:uplink_cs4 | <<bts_gprs:uplink_cs4>> | CS4 Uplink           
+| egprs:uplink_mcs1 | <<bts_egprs:uplink_mcs1>> | MCS1 Uplink          
+| egprs:uplink_mcs2 | <<bts_egprs:uplink_mcs2>> | MCS2 Uplink          
+| egprs:uplink_mcs3 | <<bts_egprs:uplink_mcs3>> | MCS3 Uplink          
+| egprs:uplink_mcs4 | <<bts_egprs:uplink_mcs4>> | MCS4 Uplink          
+| egprs:uplink_mcs5 | <<bts_egprs:uplink_mcs5>> | MCS5 Uplink          
+| egprs:uplink_mcs6 | <<bts_egprs:uplink_mcs6>> | MCS6 Uplink          
+| egprs:uplink_mcs7 | <<bts_egprs:uplink_mcs7>> | MCS7 Uplink          
+| egprs:uplink_mcs8 | <<bts_egprs:uplink_mcs8>> | MCS8 Uplink          
+| egprs:uplink_mcs9 | <<bts_egprs:uplink_mcs9>> | MCS9 Uplink          
+|===
+// generating tables for osmo_stat_items
+NSVC Peer Statistics
+// osmo_stat_item_group table NSVC Peer Statistics
+.ns.nsvc - NSVC Peer Statistics 
+[options="header"]
+|===
+| Name | Reference | Description | Unit
+| alive.delay | <<ns.nsvc_alive.delay>> | ALIVE response time         | ms
+|===
+NSVC Peer Statistics
+// osmo_stat_item_group table NSVC Peer Statistics
+.ns.nsvc - NSVC Peer Statistics 
+[options="header"]
+|===
+| Name | Reference | Description | Unit
+| alive.delay | <<ns.nsvc_alive.delay>> | ALIVE response time         | ms
+|===
+BTS Statistics
+// osmo_stat_item_group table BTS Statistics
+.bts - BTS Statistics 
+[options="header"]
+|===
+| Name | Reference | Description | Unit
+| ms.present | <<bts_ms.present>> | MS Present            | 
+|===
+// generating tables for osmo_counters
+// ungrouped osmo_counters
+.ungrouped osmo counters
+[options="header"]
+|===
+| Name | Reference | Description
+|===
+
+
diff --git a/doc/manuals/chapters/overview.adoc b/doc/manuals/chapters/overview.adoc
new file mode 100644
index 00000000..00314743
--- /dev/null
+++ b/doc/manuals/chapters/overview.adoc
@@ -0,0 +1,67 @@
+== Overview
+
+=== About OsmoPCU
+
+OsmoPCU is the Osmocom implementation of the GPRS PCU (Packet Control
+Unit) element inside the GPRS network.
+
+The OsmoPCU is co-located within the BTS and connects to OsmoBTS via its
+PCU socket interface.
+
+On the other side, OsmoPCU is connected via the Gb interface to the
+SGSN.
+
+[[fig-gprs-pcubts]]
+.GPRS network architecture with PCU in BTS
+[graphviz]
+----
+digraph G {
+	rankdir=LR;
+	MS0 [label="MS"]
+	MS1 [label="MS"]
+	MS0->BTS [label="Um"]
+	MS1->BTS [label="Um"]
+	BTS->BSC [label="Abis"]
+	BSC->MSC [label="A"]
+	BTS->PCU [label="pcu_sock"]
+	PCU->SGSN [label="Gb"]
+	SGSN->GGSN [label="GTP"]
+}
+----
+
+=== Software Components
+
+OsmoPCU consists of a variety of components, including
+
+* Gb interface (NS/BSSGP protocol)
+* `pcu_sock` interface towards OsmoBTS
+* TBF management for uplink and downlink TBF
+* RLC/MAC protocol implementation
+* per-MS context for each MS currently served
+* CSN.1 encoding/decoding routines
+
+==== Gb Implementation
+
+OsmoPCU implements the ETSI/3GPP specified Gb interface, including TS
+08.16 (NS), TS 08.18 (BSSGP) protocols. As transport layer for NS, it
+supports NS/IP (NS encapsulated in UDP/IP).
+
+The actual Gb Implementation is part of the libosmogb library, which is
+in turn part of the libosmocore software package.  This allows the same
+Gb implementation to be used from OsmoPCU, OsmoGbProxy as well as
+OsmoSGSN.
+
+==== `pcu_sock` Interface to OsmoBTS
+
+The interface towards OsmoBTS is called 'pcu_sock' and implemented as a
+set of non-standardized primitives over a unix domain socket.  The
+default file system path for this socket is `/tmp/pcu_bts`.
+
+The PCU socket can be changed on both OmsoBTS and OsmoPCU to a different
+file/path name, primarily to permit running multiple independent BTS+PCU
+pairs on a single Linux machine without having to use filesystem
+namespaces or other complex configurations.
+
+NOTE: If you change the PCU socket path on OsmoBTS by means of the
+`pcu-socket` VTY configuration command, you must ensure to make the
+identical change on the OsmoPCU side.
diff --git a/doc/manuals/chapters/running.adoc b/doc/manuals/chapters/running.adoc
new file mode 100644
index 00000000..d9f78c8b
--- /dev/null
+++ b/doc/manuals/chapters/running.adoc
@@ -0,0 +1,33 @@
+== Running OsmoPCU
+
+The OsmoPCU executable (`osmo-pcu`) offers the following command-line
+options:
+
+
+=== SYNOPSIS
+
+*osmo-pcu* [-h|-V] [-D] [-c 'CONFIGFILE'] [-r 'PRIO'] [-m 'MCC'] [-n 'MNC']
+
+
+=== 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, --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-pcu.cfg` in the current
+	working directory.
+*-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.
+*-m, --mcc 'MCC'*::
+	Use the given MCC instead of that provided by BTS via PCU socket
+*-n, --mnc 'MNC'*::
+	Use the given MNC instead of that provided by BTS via PCU socket