NOT FOR MERGE proxy cache design doc ladders

Change-Id: Ie0093bdb7ddf268d1a5fdf09b201cbd3a347225f

6 files changed, 213 insertions, 0 deletions

diff --git a/doc/manuals/chapters/Makefile b/doc/manuals/chapters/Makefile
new file mode 100644
index 0000000..31d9ca6
--- /dev/null
+++ b/doc/manuals/chapters/Makefile
@@ -0,0 +1,20 @@
+all: \
+	proxy_cache_attach.msc \
+	proxy_cache_more_tuples.msc \
+	proxy_cache_tuple_cache_dry.msc \
+	proxy_cache_periodic_lu.msc \
+	proxy_cache_umts_aka_resync.msc \
+	$(NULL)
+
+png: \
+	proxy_cache.png \
+	proxy_cache_unused.png \
+	lu_attach_and_periodic.png \
+	$(NULL)
+
+%.png: %.msc
+	mscgen -T png -o $@ $<
+
+%.msc: %.ladder
+	@which ladder_to_msc.py || (echo 'PLEASE POINT YOUR $$PATH AT libosmocore/contrib/ladder_to_msc.py' && false)
+	ladder_to_msc.py -i $< -o $@
diff --git a/doc/manuals/chapters/proxy_cache_attach.ladder b/doc/manuals/chapters/proxy_cache_attach.ladder
new file mode 100644
index 0000000..8fc41b4
--- /dev/null
+++ b/doc/manuals/chapters/proxy_cache_attach.ladder
@@ -0,0 +1,39 @@
+{hscale=2}
+ms = MS,BSS
+msc = MSC
+hlr = HLR proxy
+home = Home HLR
+
+ms -> msc	Location Updating Request (IMSI Attach)
+msc -> hlr	Send Auth Info Request
+hlr <> hlr	No proxy cache data available for this subscriber
+hlr () home	mslookup finds the home HLR
+hlr -> home	Send Auth Info Request
+hlr <- home	Send Auth Info Result
+		with 5 auth tuples
+hlr () .	(1) Keep a copy of the auth tuples
+msc <- hlr	Send Auth Info Result
+msc () .	MSC stores 5 auth tuples,
+		uses the first one now,
+		and keeps the rest for later requests
+ms () msc	Authentication
+msc -> hlr	Update Location Request
+hlr -> home	Update Location Request
+hlr <- home	Insert Subscriber Data Request
+		(with subscriber's MSISDN)
+hlr () .	proxy HLR caches the MSISDN
+msc <- hlr	Insert Subscriber Data Request
+msc -> hlr	Insert Subscriber Data Result
+hlr -> home	Insert Subscriber Data Result
+hlr <- home	Update Location Result
+msc <- hlr	Update Location Result
+ms <- msc	Location Updating Accept
+hlr <> .	After successful Update Location, check the cache
+hlr () .	(2) Ask for more auth tuples to cache
+		(amount of tuples configurable)
+hlr -> home	Send Auth Info Request
+hlr <- home	Send Auth Info Result
+hlr () .	store 5 more tuples
+hlr -> home	Send Auth Info Request
+hlr <- home	Send Auth Info Result
+hlr () .	store yet 5 more tuples
diff --git a/doc/manuals/chapters/proxy_cache_more_tuples.ladder b/doc/manuals/chapters/proxy_cache_more_tuples.ladder
new file mode 100644
index 0000000..4f9e773
--- /dev/null
+++ b/doc/manuals/chapters/proxy_cache_more_tuples.ladder
@@ -0,0 +1,31 @@
+{hscale=2}
+ms = MS,BSS
+msc = MSC
+hlr = HLR proxy
+home = Home HLR
+
+ms -> msc	CM Service Request / Paging Response
+msc -> hlr	Send Auth Info Request
+hlr () .	Use already set up proxy path
+hlr <> .	there still are unsent auth tuples
+		in the cache
+hlr () .	(3) Send cached, fresh tuples
+msc <- hlr	Send Auth Info Result
+		containing auth tuples
+		from the proxy cache
+ms () msc	Authentication
+ms () msc	Continue the CM Service / Paging action
+hlr <> .	Note that there are no/few unused tuples in the cache, fill up again
+hlr () .	(4) Ask for more auth tuples to cache
+hlr -> home	Send Auth Info Request
+---		If the home HLR link is not working
+hlr <> .	no link
+		or
+		response timeout
+hlr () .	(5) Set up a timer to retry SAI
+		(a few minutes?)
+hlr <> .	Timer triggers
+hlr -> home	Send Auth Info Request
+---		If the home HLR link is functional
+hlr <- home	Send Auth Info Result
+hlr () .	store 5 more tuples
diff --git a/doc/manuals/chapters/proxy_cache_periodic_lu.ladder b/doc/manuals/chapters/proxy_cache_periodic_lu.ladder
new file mode 100644
index 0000000..7ccfcfc
--- /dev/null
+++ b/doc/manuals/chapters/proxy_cache_periodic_lu.ladder
@@ -0,0 +1,47 @@
+{hscale=2}
+ms = MS,BSS
+msc = MSC
+hlr = HLR proxy
+home = Home HLR
+
+ms -> msc	Location Updating Request (Periodic)
+ms () msc	Authentication,
+		using the next of 5 auth tuples the MSC has stored
+msc -> hlr	Update Location Request
+hlr () .	Use already set up proxy path
+hlr <> .	(8) proxy cache already has all information to answer
+msc <- hlr	Insert Subscriber Data Request
+msc -> hlr	Insert Subscriber Data Result
+msc <- hlr	Update Location Result
+ms <- msc	Location Updating Accept
+hlr () .	(9) Verify Update Location with home HLR
+|||
+---		if the home HLR has no changes and accepts
+hlr -> home	Update Location Request
+hlr <- home	Insert Subscriber Data Request
+hlr -> home	Insert Subscriber Data Result
+hlr <> .	Notice identical MSISDN
+hlr <- home	Update Location Result
+|||
+---		if the home HLR is unreachable
+hlr -> home	Update Location Request
+hlr <> .	no link
+		or
+		response timeout
+hlr () .	Don't care, carry on
+|||
+---		if the home HLR has a modified MSISDN, and accepts
+hlr -> home	Update Location Request
+hlr <- home	Insert Subscriber Data Request
+hlr -> home	Insert Subscriber Data Result
+hlr <> .	Notice changed MSISDN
+msc <- hlr	Insert Subscriber Data Request
+msc -> hlr	Insert Subscriber Data Result
+hlr <- home	Update Location Result
+|||
+---		if the home HLR rejects
+hlr -> home	Update Location Request
+hlr <- home	Update Location Error
+msc <- hlr	Cancel Location Request
+msc -> hlr	Cancel Location Result
+hlr () .	Clear subscriber cache
diff --git a/doc/manuals/chapters/proxy_cache_tuple_cache_dry.ladder b/doc/manuals/chapters/proxy_cache_tuple_cache_dry.ladder
new file mode 100644
index 0000000..a6af3ec
--- /dev/null
+++ b/doc/manuals/chapters/proxy_cache_tuple_cache_dry.ladder
@@ -0,0 +1,21 @@
+{hscale=2}
+ms = MS,BSS
+msc = MSC
+hlr = HLR proxy
+home = Home HLR
+
+ms -> msc	CM Service Request / Paging Response
+msc -> hlr	Send Auth Info Request
+hlr () .	Use already set up proxy path
+hlr <> .	All cached auth tuples have been sent to the MSC before
+---		If no GSM AKA fallback is allowed
+msc <- hlr	Send Auth Info Error
+ms () msc	Detach
+---		If GSM AKA fallback is allowed
+hlr () .	(6) Resend only GSM AKA tuples, already sent earlier
+msc <- hlr	Send Auth Info Result
+		containing GSM AKA auth tuples
+		from the proxy cache
+ms () msc	2G: Authentication
+		3G: Detach
+ms () msc	Continue the CM Service / Paging action
diff --git a/doc/manuals/chapters/proxy_cache_umts_aka_resync.ladder b/doc/manuals/chapters/proxy_cache_umts_aka_resync.ladder
new file mode 100644
index 0000000..00ad36e
--- /dev/null
+++ b/doc/manuals/chapters/proxy_cache_umts_aka_resync.ladder
@@ -0,0 +1,55 @@
+{hscale=2}
+ms = MS,BSS
+msc = MSC
+hlr = HLR proxy
+home = Home HLR
+
+ms -> msc	CM Service Request / Paging Response
+msc -> hlr	Send Auth Info Request
+hlr <> .	there still are unsent auth tuples
+		in the cache
+hlr () .	Send cached, fresh tuples
+msc <- hlr	Send Auth Info Result
+		containing auth tuples
+		from the proxy cache
+ms <- msc	Authentication Request
+ms -> msc	USIM requests UMTS AKA resync
+		Auth Failure with AUTS
+msc -> hlr	Send Auth Info Request
+		containing AUTS IE
+hlr () .	Mark all UMTS AKA tuples as stale
+---		If the home HLR responds in time
+hlr -> home	Send Auth Info Request
+hlr <- home	Send Auth Info Result
+		with 5 auth tuples
+hlr () .	clear tuple cache, store new tuples
+msc <- hlr	Send Auth Info Result
+ms () msc	Authentication
+hlr () .	fill up the tuple cache as necessary
+hlr -> home	Send Auth Info Request
+hlr <- home	Send Auth Info Result
+...
+---		If the home HLR is unreachable
+hlr -> home	Send Auth Info Request
+hlr <> .	no link
+		or
+		response timeout
+hlr () .	Store the AUTS received earlier,
+		and set up a timer to retry SAI
+		(a few minutes?)
+---		If no GSM AKA fallback is allowed
+msc <- hlr	Send Auth Info Error
+ms () msc	Detach
+---		If GSM AKA fallback is allowed
+hlr () .	Resend only GSM AKA tuples, already sent earlier
+msc <- hlr	Send Auth Info Result
+		containing GSM AKA auth tuples
+		from the proxy cache
+ms () msc	2G: Authentication
+		3G: Detach
+---
+hlr <> .	AUTS timer triggers
+hlr -> home	Send Auth Info Request
+hlr <- home	Send Auth Info Result
+hlr () .	clear tuple cache, store new tuples
+hlr () .	continue to fill up the cache as necessary