Initial minimal OsmoHNBGW user manual

This adds a very basic OsmoHNBGW user manual with an "overview" and
"running" chapter.  It still misses any information on configuration.

Change-Id: I54825a4ce5a457f87b0618332347eed8ea54afcb
Closes: OS#2588

6 files changed, 191 insertions, 0 deletions

diff --git a/.gitignore b/.gitignore
index f662e2a..49b2cfb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -43,3 +43,8 @@ include/osmocom/hnbap/hnbap_ies_defs.h
 include/osmocom/rua/rua_ies_defs.h
 include/osmocom/ranap/ranap_ies_defs.h
 include/osmocom/sabp/sabp_ies_defs.h
+
+doc/manuals/build
+doc/manuals/common
+doc/manuals/generated
+doc/manuals/*.pdf
diff --git a/doc/manuals/Makefile.am b/doc/manuals/Makefile.am
index 91aa8f8..7a76e90 100644
--- a/doc/manuals/Makefile.am
+++ b/doc/manuals/Makefile.am
@@ -1,9 +1,16 @@
 EXTRA_DIST = \
+	     osmohnbgw-usermanual.adoc \
+	     osmohnbgw-usermanual-docinfo.xml \
+	     chapters \
 	     osmohnbgw-vty-reference.xml \
 	     regen_doc.sh \
 	     vty
 
 if BUILD_MANUALS
+  ASCIIDOC = osmohnbgw-usermanual.adoc
+  ASCIIDOC_DEPS = $(srcdir)/chapters/*.adoc
+  include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.asciidoc.inc
+
   VTY_REFERENCE = osmohnbgw-vty-reference.xml
   include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.vty-reference.inc
 
diff --git a/doc/manuals/chapters/overview.adoc b/doc/manuals/chapters/overview.adoc
new file mode 100644
index 0000000..2368b4f
--- /dev/null
+++ b/doc/manuals/chapters/overview.adoc
@@ -0,0 +1,56 @@
+[[overview]]
+== Overview
+
+
+[[intro_overview]]
+=== About OsmoHNBGW
+
+OsmoHNBGW implements the Home NodeB Gateway function in the 3G network architecture.  It serves 
+as a gateway between the classic 3G core network (CN) domain with its IuCS and IuPS interface
+and the femtocell based RAN.
+
+A typical 3G network consisting of Osmocom components will look as illustrated in the following
+diagram:
+
+[[fig-3g]]
+.Typical 3G network architecture used with OsmoHNBGW
+----
+        +------------+           +--------+          +----------+          +---------+
+ UE <-->| hNodeB     |<--Iuh---->| HNB-GW |<--IuCS-->| OsmoMSC  |<--GSUP-->| OsmoHLR |
+ UE <-->| femto cell |     ...-->|        |    ...-->|          |          |         |
+        |            |           |        |          +----------+          +---------|
+        +------------+<--GTP-U   |        |
+                              \  |        |          +------+           +------+
+                              |  |        |<--IuPS-->| SGSN |<--GTP-C-->| GGSN |
+                              |  +--------+    ...-->|      |   GTP-U-->|      |
+                              |                      +------+  /        +------+
+                              \_______________________________/
+----
+
+The HNB-GW performs a translation interface between the IuCS/IuPS interfaces on the one hand
+side, and the Iuh interface on the or ther hand:
+
+----
+                      Iuh                         IuCS/IuPS
+
+NAS                   +----+----+                 +----+----+
+Non-Access Stratum    | CC | MM |                 | CC | MM |
+- - - - - - - - - - - +----+----+-------+         +----+----+
+                      | RANAP   |       |    H    | RANAP   |
+Access Stratum        +---------+ HNBAP |    N    +---------+ - - SCCP USER SAP
+                      | RUA     |       |    B    | SUA     |  \
+                      +---------+-------+    -    +---------+  |
+                      |        SCTP     |    G    | SCTP    |  } SIGTRAN
+                      +-----------------+    W    +---------+  |
+                      |        IP       |         | IP      |  /
+                      +-----------------+         +---------+
+----
+
+On the femtocell (Home NodeB) side, OsmoHNBGW implements the Iuh interface as specified by 3GPP.
+
+=== The Iuh interface
+
+Iuh consists of the following sub-layers:
+
+- HNBAP (Home NodeB Application Part)
+- RUA (RANAP User Adaptation, between RANAP and SCTP
diff --git a/doc/manuals/chapters/running.adoc b/doc/manuals/chapters/running.adoc
new file mode 100644
index 0000000..41909e2
--- /dev/null
+++ b/doc/manuals/chapters/running.adoc
@@ -0,0 +1,37 @@
+== Running OsmoHNBGW
+
+The OsmoHNBGW executable (`osmo-hnbgw`) offers the following command-line
+arguments:
+
+=== SYNOPSIS
+
+*osmo-hnbgw* [-h|-V] [-d 'DBGMASK'] [-D] [-c 'CONFIGFILE'] [-s] [-T] [-e 'LOGLEVEL']
+
+=== OPTIONS
+
+*-h, --help*::
+	Print a short help message about the supported options
+*-V, --version*::
+	Print the compile-time version number of the OsmoHNBGW 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-msc.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 more information.
+*-T, --timestamp*::
+	Enable time-stamping of log messages to stderr. This has mostly
+	been deprecated by VTY based logging configuration, see
+	<<logging>> for more 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 more information.
diff --git a/doc/manuals/osmohnbgw-usermanual-docinfo.xml b/doc/manuals/osmohnbgw-usermanual-docinfo.xml
new file mode 100644
index 0000000..404d2a1
--- /dev/null
+++ b/doc/manuals/osmohnbgw-usermanual-docinfo.xml
@@ -0,0 +1,51 @@
+<revhistory>
+  <revision>
+    <revnumber>1</revnumber>
+    <date>November 30th, 2019</date>
+    <authorinitials>HW</authorinitials>
+    <revremark>
+      Initial version
+    </revremark>
+  </revision>
+</revhistory>
+
+<authorgroup>
+  <author>
+    <firstname>Harald</firstname>
+    <surname>Welte</surname>
+    <email>hwelte@sysmocom.de</email>
+    <authorinitials>HW</authorinitials>
+    <affiliation>
+      <shortaffil>sysmocom</shortaffil>
+      <orgname>sysmocom - s.f.m.c. GmbH</orgname>
+      <jobtitle>Managing Director</jobtitle>
+    </affiliation>
+  </author>
+</authorgroup>
+
+<copyright>
+  <year>2019</year>
+  <holder>sysmocom - s.f.m.c. GmbH</holder>
+</copyright>
+
+<legalnotice>
+  <para>
+	Permission is granted to copy, distribute and/or modify this
+	document under the terms of the GNU Free Documentation License,
+	Version 1.3 or any later version published by the Free Software
+	Foundation; with the Invariant Sections being just 'Foreword',
+	'Acknowledgements' and 'Preface', with no Front-Cover Texts,
+	and no Back-Cover Texts.  A copy of the license is included in
+	the section entitled "GNU Free Documentation License".
+  </para>
+  <para>
+	The Asciidoc source code of this manual can be found at
+	<ulink url="http://git.osmocom.org/osmo-hnbgw/">
+		http://git.osmocom.org/osmo-hnbgw/
+	</ulink>
+	and of the common chapters at
+	<ulink url="http://git.osmocom.org/osmo-gsm-manuals/">
+		http://git.osmocom.org/osmo-gsm-manuals/
+	</ulink>
+  </para>
+</legalnotice>
diff --git a/doc/manuals/osmohnbgw-usermanual.adoc b/doc/manuals/osmohnbgw-usermanual.adoc
new file mode 100644
index 0000000..3f3c9c3
--- /dev/null
+++ b/doc/manuals/osmohnbgw-usermanual.adoc
@@ -0,0 +1,35 @@
+:gfdl-enabled:
+:program-name: OsmoHNBGW
+
+OsmoHNBGW User Manual
+=====================
+Harald Welte <hwelte@sysmocom.de>
+
+
+include::./common/chapters/preface.adoc[]
+
+include::{srcdir}/chapters/overview.adoc[]
+
+include::{srcdir}/chapters/running.adoc[]
+
+// include::{srcdir}/chapters/control.adoc[]
+
+// include::./common/chapters/counters-overview.adoc[]
+
+// include::{srcdir}/chapters/counters.adoc[]
+
+include::./common/chapters/vty.adoc[]
+
+include::./common/chapters/logging.adoc[]
+
+// include::{srcdir}/chapters/net.adoc[]
+
+// include::./common/chapters/control_if.adoc[]
+
+include::./common/chapters/port_numbers.adoc[]
+
+include::./common/chapters/bibliography.adoc[]
+
+include::./common/chapters/glossary.adoc[]
+
+include::./common/chapters/gfdl.adoc[]