fixeria has submitted this change. (
https://gerrit.osmocom.org/c/osmo-ttcn3-hacks/+/42372?usp=email )
Change subject: s1gw: add README.md
......................................................................
s1gw: add README.md
Change-Id: Ib5c1326c4260bf552b561a42f7ff9d3f28f89579
---
A s1gw/README.md
1 file changed, 154 insertions(+), 0 deletions(-)
Approvals:
laforge: Looks good to me, approved
pespin: Looks good to me, but someone else must approve
osmith: Looks good to me, but someone else must approve
Jenkins Builder: Verified
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 |
--
To view, visit https://gerrit.osmocom.org/c/osmo-ttcn3-hacks/+/42372?usp=email
To unsubscribe, or for help writing mail filters, visit
https://gerrit.osmocom.org/settings?usp=email
Gerrit-MessageType: merged
Gerrit-Project: osmo-ttcn3-hacks
Gerrit-Branch: master
Gerrit-Change-Id: Ib5c1326c4260bf552b561a42f7ff9d3f28f89579
Gerrit-Change-Number: 42372
Gerrit-PatchSet: 2
Gerrit-Owner: fixeria <[email protected]>
Gerrit-Reviewer: Jenkins Builder
Gerrit-Reviewer: fixeria <[email protected]>
Gerrit-Reviewer: laforge <[email protected]>
Gerrit-Reviewer: osmith <[email protected]>
Gerrit-Reviewer: pespin <[email protected]>
