fixeria has uploaded this change for review. ( 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(-)

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 |