NOT FOR MERGE proxy cache design doc ladders
Change-Id: Ie0093bdb7ddf268d1a5fdf09b201cbd3a347225f
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