initial skeleton
Change-Id: I706aa9e11a646aad71bb310fa552d0bdb5084d4b
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..2b65598
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,20 @@
+SUBDIRS = \
+ examples \
+ manuals \
+ $(NULL)
+
+msc: \
+ $(NULL)
+
+dot: \
+ $(NULL)
+
+$(builddir)/%.png: $(srcdir)/%.msc
+ mscgen -T png -o $@ $<
+
+$(builddir)/%.png: $(srcdir)/%.dot
+ dot -Tpng $< > $@
+
+.PHONY: poll
+poll:
+ while true; do $(MAKE) msc dot; sleep 1; done
diff --git a/doc/examples/Makefile.am b/doc/examples/Makefile.am
new file mode 100644
index 0000000..f4acac8
--- /dev/null
+++ b/doc/examples/Makefile.am
@@ -0,0 +1,30 @@
+OSMOCONF_FILES = \
+ osmo-smlc/osmo-smlc.cfg
+
+osmoconfdir = $(sysconfdir)/osmocom
+osmoconf_DATA = $(OSMOCONF_FILES)
+
+EXTRA_DIST = $(OSMOCONF_FILES)
+
+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-smlc/osmo-smlc.cfg b/doc/examples/osmo-smlc/osmo-smlc.cfg
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/doc/examples/osmo-smlc/osmo-smlc.cfg
diff --git a/doc/manuals/Makefile.am b/doc/manuals/Makefile.am
new file mode 100644
index 0000000..5aa75fe
--- /dev/null
+++ b/doc/manuals/Makefile.am
@@ -0,0 +1,25 @@
+EXTRA_DIST = \
+ osmosmlc-usermanual.adoc \
+ osmosmlc-usermanual-docinfo.xml \
+ osmosmlc-vty-reference.xml \
+ chapters \
+ regen_doc.sh \
+ vty
+
+if BUILD_MANUALS
+ ASCIIDOC = osmosmlc-usermanual.adoc
+ include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.asciidoc.inc
+ osmosmlc-usermanual.pdf: $(srcdir)/chapters/*.adoc $(srcdir)/chapters/*.dot
+
+ VTY_REFERENCE = osmosmlc-vty-reference.xml
+
+ BUILT_REFERENCE_XML = $(builddir)/vty/smlc_vty_reference.xml
+ $(builddir)/vty/smlc_vty_reference.xml: $(top_builddir)/src/osmo-smlc/osmo-smlc
+ mkdir -p $(builddir)/vty
+ $(top_builddir)/src/osmo-smlc/osmo-smlc --vty-ref-xml > $@
+
+ include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.vty-reference.inc
+
+ OSMO_REPOSITORY = osmo-smlc
+ include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.common.inc
+endif
diff --git a/doc/manuals/chapters/overview.adoc b/doc/manuals/chapters/overview.adoc
new file mode 100644
index 0000000..b0132ad
--- /dev/null
+++ b/doc/manuals/chapters/overview.adoc
@@ -0,0 +1,10 @@
+[[overview]]
+== Overview
+
+This manual should help you getting started with OsmoSMLC. It will cover
+aspects of configuring and running the OsmoSMLC.
+
+[[intro_overview]]
+=== About OsmoSMLC
+
+OsmoSMLC is the Osmocom implementation of a Serving Mobile Location Center.
diff --git a/doc/manuals/chapters/running.adoc b/doc/manuals/chapters/running.adoc
new file mode 100644
index 0000000..0a3174e
--- /dev/null
+++ b/doc/manuals/chapters/running.adoc
@@ -0,0 +1,79 @@
+== Running OsmoSMLC
+
+The OsmoSMLC executable (`osmo-smlc`) offers the following command-line
+arguments:
+
+=== SYNOPSIS
+
+*osmo-smlc* [-h|-V] [-d 'DBGMASK'] [-D] [-c 'CONFIGFILE'] [-s] [-T] [-e 'LOGLEVEL'] [-l 'IP'] [-r 'RFCTL']
+
+=== OPTIONS
+
+*-h, --help*::
+ Print a short help message about the supported options
+*-V, --version*::
+ Print the compile-time version number of the 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-smlc.cfg` in the current
+ working directory.
+*-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.
+
+=== Multiple instances
+
+Running multiple instances of `osmo-smlc` on the same host is possible if all
+interfaces (VTY, CTRL) are separated using the appropriate configuration
+options. The IP based interfaces are binding to local host by default. In order
+to separate the processes, the user has to bind those services to specific but
+different IP addresses and/or ports.
+
+The VTY and the Control interface can be bound to IP addresses from the loopback
+address range, for example:
+
+----
+line vty
+ bind 127.0.0.2
+ctrl
+ bind 127.0.0.2
+----
+
+For the following links, OsmoSMLC acts as a client and does not listen/bind to a
+specific interface, and will hence not encounter conflicts for multiple instances
+running on the same interface:
+
+- The SCCP/M3UA links are established by OsmoSMLC contacting an STP.
+
+To run multiple OsmoSMLC instances on the same network, each SMLC
+has to configure a distinct point-code. See <<cs7_config>>.
+
+
+=== Configure primary links
+
+==== Connect to an STP
+
+===== Configure SCCP/M3UA (AoIP)
+
+OsmoSMLC acts as client to contact an STP instance and establish an SCCP/M3UA
+link.
+
+An example configuration of OsmoSMLC's Lb SCCP link, assuming the SMLC at
+point-code 1.23.6 via an SG listening for M3UA at 127.0.0.1:2905:
+
+----
+cs7 instance 0
+ point-code 1.23.6
+ asp asp-clnt-msc-0 2905 0 m3ua
+ remote-ip 127.0.0.1
+ sctp-role client
+----
+
+This configuration is explained in detail in <<cs7_config>>.
diff --git a/doc/manuals/osmosmlc-usermanual-docinfo.xml b/doc/manuals/osmosmlc-usermanual-docinfo.xml
new file mode 100644
index 0000000..b39d11b
--- /dev/null
+++ b/doc/manuals/osmosmlc-usermanual-docinfo.xml
@@ -0,0 +1,63 @@
+<revhistory>
+ <revision>
+ <revnumber>1</revnumber>
+ <date>August 2020</date>
+ <authorinitials>HW</authorinitials>
+ <revremark>
+ Initial OsmoSMLC manual
+ </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>
+ <author>
+ <firstname>Neels</firstname>
+ <surname>Hofmeyr</surname>
+ <email>nhofmeyr@sysmocom.de</email>
+ <authorinitials>NH</authorinitials>
+ <affiliation>
+ <shortaffil>sysmocom</shortaffil>
+ <orgname>sysmocom - s.f.m.c. GmbH</orgname>
+ <jobtitle>Senior Developer</jobtitle>
+ </affiliation>
+ </author>
+</authorgroup>
+
+<copyright>
+ <year>2012-2020</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-gsm-manuals/">
+ http://git.osmocom.org/osmo-gsm-manuals/
+ </ulink>
+ and
+ <ulink url="http://git.osmocom.org/osmo-smlc/">
+ http://git.osmocom.org/osmo-smlc/
+ </ulink>
+
+ </para>
+</legalnotice>
diff --git a/doc/manuals/osmosmlc-usermanual.adoc b/doc/manuals/osmosmlc-usermanual.adoc
new file mode 100644
index 0000000..1717659
--- /dev/null
+++ b/doc/manuals/osmosmlc-usermanual.adoc
@@ -0,0 +1,37 @@
+:gfdl-enabled:
+:program-name: OsmoSMLC
+
+OsmoSMLC User Manual
+====================
+Harald Welte <hwelte@sysmocom.de>
+
+
+include::./common/chapters/preface.adoc[]
+
+include::{srcdir}/chapters/overview.adoc[]
+
+include::{srcdir}/chapters/running.adoc[]
+
+include::./common/chapters/vty.adoc[]
+
+include::./common/chapters/logging.adoc[]
+
+include::./common/chapters/cs7-config.adoc[]
+
+include::./common/chapters/counters-overview.adoc[]
+
+// include::{srcdir}/chapters/counters.adoc[]
+
+include::./common/chapters/control_if.adoc[]
+
+// include::{srcdir}/chapters/control.adoc[]
+
+include::{srcdir}/chapters/osmux_bsc.adoc[]
+
+include::./common/chapters/port_numbers.adoc[]
+
+include::./common/chapters/bibliography.adoc[]
+
+include::./common/chapters/glossary.adoc[]
+
+include::./common/chapters/gfdl.adoc[]
diff --git a/doc/manuals/osmosmlc-vty-reference.xml b/doc/manuals/osmosmlc-vty-reference.xml
new file mode 100644
index 0000000..38085b7
--- /dev/null
+++ b/doc/manuals/osmosmlc-vty-reference.xml
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ex:ts=2:sw=42sts=2:et
+ -*- tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*-
+-->
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML 5.0//EN"
+"http://docbook.org/xml/5.0/dtd/docbook.dtd" [
+<!ENTITY chapter-vty SYSTEM "./common/chapters/vty.xml" >
+<!ENTITY sections-vty SYSTEM "generated/docbook_vty.xml" >
+]>
+
+<book>
+ <info>
+ <revhistory>
+ <revision>
+ <revnumber>v1</revnumber>
+ <date>21st August 2020</date>
+ <authorinitials>hw</authorinitials>
+ <revremark>Initial</revremark>
+ </revision>
+ </revhistory>
+
+ <title>OsmoSMLC VTY Reference</title>
+
+ <copyright>
+ <year>2020</year>
+ </copyright>
+
+ <legalnotice>
+ <para>This work is copyright by <orgname>sysmocom - s.f.m.c. GmbH</orgname>. All rights reserved.
+ </para>
+ </legalnotice>
+ </info>
+
+ <!-- Main chapters-->
+ &chapter-vty;
+</book>
+
diff --git a/doc/manuals/regen_doc.sh b/doc/manuals/regen_doc.sh
new file mode 100755
index 0000000..175b17e
--- /dev/null
+++ b/doc/manuals/regen_doc.sh
@@ -0,0 +1,17 @@
+#!/bin/sh -x
+
+if [ -z "$DOCKER_PLAYGROUND" ]; then
+ echo "You need to set DOCKER_PLAYGROUND"
+ exit 1
+fi
+
+SCRIPT=$(realpath "$0")
+MANUAL_DIR=$(dirname "$SCRIPT")
+
+COMMIT=${COMMIT:-$(git log -1 --format=format:%H)}
+
+cd "$DOCKER_PLAYGROUND/scripts" || exit 1
+
+OSMO_SMLC_BRANCH=$COMMIT ./regen_doc.sh osmo-smlc 4271 \
+ "$MANUAL_DIR/chapters/counters_generated.adoc" \
+ "$MANUAL_DIR/vty/smlc_vty_reference.xml"
diff --git a/doc/manuals/vty/smlc_vty_dditions.xml b/doc/manuals/vty/smlc_vty_dditions.xml
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/doc/manuals/vty/smlc_vty_dditions.xml