diff --git a/configure.ac b/configure.ac
index 2027e9e..c23a90d 100644
--- a/configure.ac
+++ b/configure.ac
@@ -233,6 +233,7 @@ AC_OUTPUT(
     doc/Makefile
     doc/examples/Makefile
     doc/manuals/Makefile
+    doc/charts/Makefile
     contrib/Makefile
     contrib/systemd/Makefile
     contrib/osmo-hnbgw.spec
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 15f36b7..66103ba 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,4 +1,5 @@
 SUBDIRS = \
 	examples \
 	manuals \
+	charts \
 	$(NULL)
diff --git a/doc/charts/Makefile.am b/doc/charts/Makefile.am
new file mode 100644
index 0000000..52b111f
--- /dev/null
+++ b/doc/charts/Makefile.am
@@ -0,0 +1,19 @@
+msc: \
+	$(builddir)/hnbgw_context_map.png \
+	$(NULL)
+
+dot: \
+	$(builddir)/hnbgw_context_map_fsm.png \
+	$(NULL)
+
+$(builddir)/%.png: $(srcdir)/%.msc
+	mscgen -T png -o $@ $<
+
+$(builddir)/%.png: $(srcdir)/%.dot
+	dot -Tpng $< > $@
+
+.PHONY: poll
+# remember current dir: in case the build process removes and recreates the dir, re-enter the new dir
+W := "$(PWD)"
+poll:
+	while true; do $(MAKE) -C $W msc dot; sleep 1; done
diff --git a/doc/charts/hnbgw_context_map.msc b/doc/charts/hnbgw_context_map.msc
new file mode 100644
index 0000000..7a4da55
--- /dev/null
+++ b/doc/charts/hnbgw_context_map.msc
@@ -0,0 +1,109 @@
+msc {
+  hscale="2";
+  hnb[label="HNB"],rua[label="OsmoHNBGW\nRUA FSM / HNBAP"],sccp[label="OsmoHNBGW\nSCCP FSM"],cn[label="CN"];
+
+  hnb <=> rua [label="RANAP/RUA\n(Iuh)"];
+  rua <=> sccp [label="FSM events"];
+  sccp <=> cn [label="RANAP/SCCP/M3UA\n(IuCS, IuPS)"];
+
+  ...;
+  ...;
+  --- [label="Create a new context map (always from HNB)"];
+  hnb => rua [label="RUA Connect\nRANAP InitialUE-Message\nDTAP Location Updating Request"];
+  rua rbox sccp [label="hnbgw_context_map_alloc()"];
+  rua abox rua [label="MAP_RUA_ST_INIT"];
+  sccp abox sccp [label="MAP_SCCP_ST_INIT"];
+  rua rbox rua [label="MAP_RUA_EV_RX_CONNECT\ndata = ranap_msg"];
+  rua abox rua [label="MAP_RUA_ST_CONNECTED"];
+  rua => sccp [label="MAP_SCCP_EV_TX_RANAP_MSG\ndata = ranap_msg"];
+  sccp abox sccp [label="MAP_SCCP_ST_WAIT_CC"];
+  sccp => cn [label="SCCP Connection Request\nRANAP InitialUE-Message\nDTAP Location Updating Request"];
+  ...;
+  sccp <= cn [label="SCCP Connection Confirm"];
+  sccp abox sccp [label="MAP_SCCP_ST_CONNECTED"];
+  --- [label="if SCCP CC with payload"];
+  rua <= sccp [label="MAP_RUA_EV_TX_RANAP_MSG\ndata = ranap_msg"];
+  hnb <= rua [label="RUA DirectTransfer"];
+
+  ...;
+  ...;
+  --- [label="Layer 3 communication"];
+  sccp <= cn [label="SCCP Data Form 1"];
+  rua <= sccp [label="MAP_RUA_EV_TX_RANAP_MSG\ndata = ranap_msg"];
+  hnb <= rua [label="RUA DirectTransfer"];
+  ...;
+  hnb => rua [label="RUA DirectTransfer"];
+  rua => sccp [label="MAP_SCCP_EV_TX_RANAP_MSG\ndata = ranap_msg"];
+  sccp => cn [label="SCCP Data Form 1"];
+
+  ...;
+  ...;
+  --- [label="Usual release"];
+  sccp <= cn [label="SCCP Data Form 1\nIu-ReleaseCommand"];
+  rua <= sccp [label="MAP_RUA_EV_TX_RANAP_MSG\ndata = ranap_msg"];
+  hnb <= rua [label="RUA DirectTransfer\nIu-ReleaseCommand"];
+  ...;
+  hnb => rua [label="RUA Disconnect\nIu-ReleaseComplete"];
+  rua rbox rua [label="MAP_RUA_EV_RX_DISCONNECT"];
+  rua abox rua [label="MAP_RUA_ST_DISCONNECTED"];
+  rua => sccp [label="MAP_SCCP_EV_RAN_DISC\ndata = ranap_msg"];
+  sccp => cn [label="SCCP Data Form 1\nIu-ReleaseComplete\nNOT 'SCCP Released'! See 3GPP TS 48.006 9.2"];
+  sccp abox sccp [label="MAP_SCCP_ST_WAIT_RLSD"];
+  ...;
+  sccp <= cn [label="SCCP Released"];
+  sccp abox sccp [label="MAP_SCCP_ST_DISCONNECTED"];
+  rua rbox sccp [label="map_check_released()"];
+  rua rbox sccp [label="hnbgw_context_map_free()"];
+
+  ...;
+  ...;
+  --- [label="Ungraceful release from CN"];
+  sccp <= cn [label="SCCP Released"];
+  sccp => cn [label="SCCP Release Complete\n(implicit by libosmo-sigtran)"];
+  sccp rbox sccp [label="MAP_SCCP_EV_RX_RELEASED"];
+  sccp note sccp [label="In SCCP there is no \"link loss\".\nIn every case, we will be notified\nvia N-Disconnect prim per SCCP conn."];
+  sccp abox sccp [label="MAP_SCCP_ST_DISCONNECTED"];
+  rua <= sccp [label="MAP_RUA_EV_CN_DISC"];
+  hnb <= rua [label="RUA Disconnect"];
+  rua abox rua [label="MAP_RUA_ST_DISCONNECTED"];
+  rua rbox sccp [label="map_check_released()"];
+  rua rbox sccp [label="hnbgw_context_map_free()"];
+
+  ...;
+  ...;
+  ...;
+  --- [label="PCSTATE handling"];
+  sccp << cn [label="N-PCSTATE.indication\npoint-code unreachable"];
+  sccp note sccp [label="currently ignored"];
+
+  ...;
+  ...;
+  --- [label="Ungraceful release from HNB"];
+  hnb -x rua [label="link loss"];
+  rua rbox rua [label="MAP_RUA_EV_HNB_LINK_LOST"];
+  rua => sccp [label="MAP_SCCP_EV_RAN_DISC"];
+  sccp => cn [label="SCCP Released"];
+  sccp abox sccp [label="MAP_SCCP_ST_DISCONNECTED"];
+  rua abox rua [label="MAP_RUA_ST_DISCONNECTED"];
+  rua rbox sccp [label="map_check_released()"];
+  rua rbox sccp [label="hnbgw_context_map_free()"];
+
+  ...;
+  ...;
+  --- [label="Ungraceful release from HNB De-Register"];
+  hnb => rua [label="HNBAP HNB De-Register"];
+  --- [label="or"];
+  hnb => rua [label="HNBAP HNB Register\n(HNB restarted)"];
+  ---;
+  rua rbox rua [label="MAP_RUA_EV_HNB_LINK_LOST"];
+  hnb <= rua [label="RUA Disconnect"];
+  hnb note rua [label="TODO: does it make sense to send\nRUA Disconnect per context when HNB is/was gone?\nOr has the HNB implicitly discarded these?"];
+  rua abox rua [label="MAP_RUA_ST_DISCONNECTED"];
+  rua => sccp [label="MAP_SCCP_EV_RAN_DISC\nfrom map_rua_disconnected_onenter()"];
+  sccp abox sccp [label="MAP_SCCP_ST_WAIT_RLSD"];
+  rua => sccp [label="MAP_SCCP_EV_RAN_DISC\nto skip waiting for SCCP Released from CN"];
+  sccp => cn [label="SCCP Released"];
+  sccp abox sccp [label="MAP_SCCP_ST_DISCONNECTED"];
+  rua rbox sccp [label="map_check_released()"];
+  rua rbox sccp [label="hnbgw_context_map_free()"];
+}
diff --git a/doc/charts/hnbgw_context_map_fsm.dot b/doc/charts/hnbgw_context_map_fsm.dot
new file mode 100644
index 0000000..c71032b
--- /dev/null
+++ b/doc/charts/hnbgw_context_map_fsm.dot
@@ -0,0 +1,62 @@
+digraph G {
+rankdir=TB
+labelloc=t
+label="hnb_context_map\nRUA and SCCP FSMs"
+
+HNB_connect [label="HNB",shape=box3d]
+rua_to_scu_connect [label="rua_to_scu()",shape=box]
+HNB_DT [label="HNB",shape=box3d]
+rua_to_scu_DT [label="rua_to_scu()",shape=box]
+HNB_DT2 [label="HNB",shape=box3d]
+HNB_disconnect [label="HNB",shape=box3d]
+rua_to_scu_disconnect [label="rua_to_scu()",shape=box]
+CN [shape=box3d]
+CN2 [label="CN",shape=box3d]
+CN3 [label="CN",shape=box3d]
+CN4 [label="CN",shape=box3d]
+
+HNB_connect -> rua_to_scu_connect [label="RUA Connect",style=dotted]
+rua_to_scu_connect -> create [label="(1)",style=dotted]
+create [label="hnbgw_context_map_alloc()",shape=box]
+create -> {RUA_INIT,SCCP_INIT} [label="(1)",style="dashed,bold"]
+
+rua_to_scu_connect -> RUA_CONNECTED [label="(2)\nMAP_RUA_EV_RX_CONNECT",style=dashed]
+RUA_CONNECTED -> SCCP_WAIT_CC [label="(2)\nMAP_SCCP_EV_TX_RANAP_MSG",style=dashed]
+
+RUA_INIT -> RUA_CONNECTED -> RUA_DISCONNECTED [style=bold]
+
+SCCP_INIT -> SCCP_WAIT_CC -> SCCP_CONNECTED -> SCCP_WAIT_RLSD -> SCCP_DISCONNECTED [style=bold]
+SCCP_CONNECTED -> SCCP_DISCONNECTED [label="SCCP RLSD"]
+
+SCCP_WAIT_CC -> CN [label="(2) SCCP CR",style=dotted]
+CN -> SCCP_CONNECTED [label="(3) SCCP CC",style=dashed]
+
+CN4 -> SCCP_CONNECTED [label="(4) SCCP\nData Form 1",style=dotted]
+SCCP_CONNECTED -> RUA_CONNECTED [label="(4)\nMAP_RUA_EV_TX_RANAP_MSG",style=dotted]
+RUA_CONNECTED -> HNB_DT2 [label="(4)\nRUA DirectTransfer",style=dotted]
+
+HNB_DT -> rua_to_scu_DT [label="(5)\nRUA DirectTransfer",style=dotted]
+rua_to_scu_DT -> RUA_CONNECTED [label="(5)\nMAP_RUA_EV_RX_DIRECT_TRANSFER",style=dotted]
+RUA_CONNECTED -> SCCP_CONNECTED [label="(5)\nMAP_SCCP_EV_TX_RANAP_MSG",style=dotted]
+SCCP_CONNECTED -> CN3 [label="(5) SCCP\nData Form 1",style=dotted]
+
+HNB_disconnect -> rua_to_scu_disconnect [label="(6) RUA Id-Disconnect",style=dotted]
+rua_to_scu_disconnect -> RUA_DISCONNECTED [label="(6) MAP_RUA_EV_RX_DISCONNECT",style=dashed]
+RUA_DISCONNECTED -> SCCP_WAIT_RLSD [label="(6) MAP_SCCP_EV_RAN_DISC",style=dashed]
+
+CN2 -> SCCP_DISCONNECTED [label="(7) SCCP RLSD",style=dashed]
+
+{RUA_DISCONNECTED,SCCP_DISCONNECTED} -> release [label="onenter",style="dotted,bold"]
+release [label="map_check_released()",shape=box]
+release -> terminate [label="when both RUA and\nSCCP disconnected",style=dotted]
+terminate [label="hnbgw_context_map_free()",shape=octagon]
+
+subgraph cluster_legend {
+	label=""
+	style=invisible
+	A, B, C, D [style=invisible]
+	A -> B [label="event without\nstate change",style=dotted]
+	C -> D [label="event changes\nstate to...",style=dashed]
+}
+
+}