s1gw: add README.md

Change-Id: Ib5c1326c4260bf552b561a42f7ff9d3f28f89579
---
A s1gw/README.md
1 file changed, 154 insertions(+), 0 deletions(-)


git pull ssh://gerrit.osmocom.org:29418/osmo-ttcn3-hacks refs/changes/72/42372/1

diff --git a/s1gw/README.md b/s1gw/README.md
new file mode 100644
index 0000000..8bdeeca
--- /dev/null
+++ b/s1gw/README.md
@@ -0,0 +1,154 @@
+# What is this?
+
+This is a TTCN-3 testsuite for osmo-s1gw.
+
+## What is osmo-s1gw?
+
+**OsmoS1GW** is an S1AP gateway (proxy) between eNBs and an MME.
+It terminates S1AP SCTP connections from eNBs on one side, forwards
+S1AP to/from the MMEs on the other, and coordinates user-plane bearer
+setup with a UPF via PFCP.  It is implemented in Erlang.
+
+```
+eNB --[S1AP/SCTP]--> S1GW --[S1AP/SCTP]--> MME
+                      |
+                   [PFCP/UDP]
+                      |
+                     UPF
+```
+
+Network address layout in tests:
+- eNB-facing: S1GW=127.0.1.1, eNB(s)=127.0.1.10+
+- MME-facing: S1GW=127.0.2.1, MME=127.0.2.10+
+- UPF-facing: S1GW=127.0.3.1, UPF=127.0.3.10
+- StatsD: 127.0.4.10:8125, REST: 127.0.0.1:8080
+
+## Running the testsuite
+
+```bash
+# From repo root:
+./testenv.py run s1gw
+
+# Build only:
+make s1gw
+
+# Run manually (osmo-s1gw must already be running):
+cd s1gw
+../start-testsuite.sh s1gw/S1GW_Tests S1GW_Tests.cfg
+
+# Single test case:
+../start-testsuite.sh s1gw/S1GW_Tests S1GW_Tests.cfg S1GW_Tests.TC_e_rab_setup
+```
+
+## Module Overview
+
+| File | Purpose |
+|---|---|
+| `S1GW_Tests.ttcn` | Top-level test cases, `f_init_*`, control block |
+| `S1GW_ConnHdlr.ttcn` | Per-eNB connection handler; all protocol helper functions |
+| `S1AP_Server.ttcn` | MME emulator; routes S1AP PDUs to ConnHdlr subscribers |
+| `S1GW_UEMux.ttcn` | UE multiplexer for multi-UE tests (128 concurrent UEs, by default) |
+| `S1GW_REST_Types.ttcn` | JSON/REST data types for management API |
+| `S1GW_REST_Functions.ttcn` | REST helper functions (metrics, PFCP, MME/E-RAB mgmt) |
+
+## Architecture & Key Patterns
+
+### Component Hierarchy
+
+```
+test_CT  (extends StatsD_Checker_CT, http_CT)
+  ├── S1AP_Server_CT    (MME emulator, one instance)
+  ├── PFCP_Emulation_CT (UPF emulator, one instance)
+  └── ConnHdlr [0..N]   (one per emulated eNB)
+        └── UEMux_CT / UEMuxUE_CT  (only in TC_uemux_* tests)
+```
+
+`test_CT` starts in `f_init()`, which brings up the REST interface,
+S1AP server, PFCP emulation, and StatsD checker before spawning any
+ConnHdlr instances.
+
+### ConnHdlr Lifecycle
+
+Every test case follows this lifecycle via `f_TC_exec()`:
+
+```
+f_ConnHdlr_spawn()
+  → f_ConnHdlr_s1ap_connect()     # TCP/SCTP connect to S1GW eNB-facing port
+  → f_ConnHdlr_s1ap_register()    # register with S1AP_Server
+  → f_ConnHdlr_s1ap_setup()       # S1AP SetupRequest/Response exchange
+  → [test body runs]
+  → f_ConnHdlr_s1ap_disconnect()
+  → f_ConnHdlr_s1ap_unregister()
+```
+
+Multi-eNB tests spawn N ConnHdlr instances, run them in parallel
+via `interleave`, then join.
+
+### E-RAB Parameter Tracking (`ERab` / `ERabList`)
+
+Each bearer is tracked with transport endpoints for all four forwarding
+directions (access↔core in both send/receive), plus UPF PFCP SEIDs and
+TEID/IP combos.  These are populated during setup and then asserted
+during modification/release to verify S1GW correctly translates addresses.
+
+```ttcn
+type record ERab {
+    ERabParams u2c,   -- UPF→Core side (what S1GW programs into UPF)
+    ERabParams c2u,   -- Core→UPF side
+    ERabParams a2u,   -- Access→UPF side
+    ERabParams u2a,   -- UPF→Access side
+    ERabParams u2cm,  -- modified variant
+    ERabParams u2am,  -- modified variant
+    OCT8 pfcp_loc_seid,
+    OCT8 pfcp_rem_seid
+}
+```
+
+### PFCP Session Mutex
+
+`f_ConnHdlr_erab_setup_req()` acquires a mutex before establishing the
+PFCP session.  This serialises concurrent E-RAB setups across eNBs
+because the initial PFCP trigger uses SEID=0, which cannot be
+unambiguously routed without locking.
+
+### Bidirectional PDU Helpers
+
+All S1AP send/receive functions come in two directional variants:
+
+- `f_ConnHdlr_tx_s1ap_from_enb()` / `f_ConnHdlr_rx_s1ap_from_enb()` — eNB -> S1GW -> MME direction
+- `f_ConnHdlr_tx_s1ap_from_mme()` / `f_ConnHdlr_rx_s1ap_from_mme()` — MME -> S1GW -> eNB direction
+
+Similarly for PFCP: `f_ConnHdlr_pfcp_expect()`, `f_ConnHdlr_pfcp_reply()`.
+
+### Test Case Parameterisation
+
+Test bodies are passed as function references to `f_TC_exec()`, which handles ConnHdlr
+spawn/teardown. This lets the same test body run with varying eNB count or E-RAB count
+just by changing parameters — e.g. `TC_e_rab_setup` and `TC_e_rab_setup_multi` share
+`f_TC_e_rab_setup`.
+
+### StatsD Validation
+
+Many tests call `f_statsd_expect()` at the end to assert S1GW exported the right metrics
+(connection counts, forwarded packet counters, PFCP association state). These expectations
+are declared with `StatsDExpect` records before the test body runs and checked after.
+
+### REST Interface
+
+`S1GW_REST_Functions.ttcn` wraps HTTP GET/POST calls for inspecting and controlling live
+S1GW state (PFCP association, MME pool, E-RAB list).  Used both for supplementary assertions
+(e.g. verifying StatsD metrics are consistent with REST state) and as the primary mechanism
+in REST-focused test cases.
+
+## Test Case Groups
+
+| Group | What's Covered |
+|---|---|
+| Connection | eNB connect/disconnect, MME-initiated teardown, MME unavailable |
+| E-RAB | Bearer setup/release/modify in both directions, PFCP rejection |
+| Initial Context | Attach bearer setup, UE context lifecycle |
+| UE Mux | Concurrent multi-UE operation (128 UEs) via UEMux |
+| Handover | X2/S1 handover preparation, resource allocation, partial failure |
+| PFCP | UPF heartbeat exchange |
+| MME Pool | MME fallback on rejection/timeout, impatient eNB disconnect during pool selection |
+| REST | MME pool listing, runtime add/delete, fallback after runtime delete |

