Osmocom Home NodeB Gateway, for attaching femtocells to the 3G CN (OsmoMSC, OsmoSGSN) https://osmocom.org/projects/osmohnbgw
Go to file
Neels Hofmeyr ed424d5be4 context map: introduce RUA and SCCP FSMs to fix leaks
Refactor the entire RUA <-> SCCP connection-oriented message forwarding:
- conquer confusion about hnbgw_context_map release behavior, and
- eradicate SCCP connection leaks.

Finer points:

== Context map state ==
So far, we had a single context map state and some flags to keep track
of both the RUA and the SCCP connections. It was easy to miss connection
cleanup steps, especially on the SCCP side.
Instead, the two FSMs clearly define the RUA and SCCP conn states
separately, and each side takes care of its own release needs for all
possible scenarios.
- When both RUA and SCCP are released, the context map is discarded.
- A context map can stay around to wait for proper SCCP release, even if
  the RUA side has lost the HNB connection.
- Completely drop the async "context mapper garbage collection", because
  the FSMs clarify the release and free steps, synchronously.
- We still keep a (simplified) enum for global context map state, but
  this is only used so that VTY reporting remains mostly unchanged.

== Context map cleanup confusion ==
The function context_map_hnb_released() was the general cleanup function
for a context map. Instead, add separate context_map_free().

== Free context maps separately from HNB ==
When a HNB releases, talloc_steal() the context maps out of the HNB
specific hnb_ctx, so that they are not freed along with the HNB state,
possibly leaving SCCP connections afloat.
(It is still nice to normally keep context maps as talloc children of
their respective hnb_ctx, so talloc reports show which belongs to

So far, context map handling found the global hnb_gw pointer via
map->hnb_ctx->gw. But in fact, a HNB may disappear at any point in time.
Instead, use a separate hnb_gw pointer in map->gw.

== RUA procedure codes vs. SCCP prims ==
So far, the RUA rx side composed SCCP prims to pass on:

 RUA rx ---SCCP-prim--> RANAP handling ---SCCP-prim--> SCCP tx

That is a source of confusion: a RUA procedure code should not translate
1:1 to SCCP prims, especially for RUA id-Disconnect (see release charts
Instead, move SCCP prim composition over to the SCCP side, using FSM
events to forward:

 RUA rx --event--> RUA FSM --event--> SCCP FSM --SCCP-prim--> SCCP tx
         +RANAP             +RANAP              +RANAP

 RUA tx <--RUA---- RUA FSM <--event-- SCCP FSM <--event-- SCCP rx
          +RANAP             +RANAP              +RANAP

Hence choose the correct prim according to the SCCP FSM state.
- in hnbgw_rua.c, use RUA procedure codes, not prim types.
- via the new FSM events' data args, pass msgb containing RANAP PDUs.

== Fix SCCP Release behavior ==
So far, the normal conn release behavior was

 HNB                 HNBGW                   CN
  | --id-Disconnect--> | ---SCCP-Released--> |  Iu-ReleaseComplete
  |                    | <--SCCP-RLC-------- |  (no data)

Instead, the SCCP release is now in accordance with 3GPP TS 48.006 9.2
'Connection release':

 The MSC sends a SCCP released message. This message shall not contain
 any user data field.


 HNB                 HNBGW                    CN
  | --id-Disconnect--> | ---Data-Form-1(!)--> |  Iu-ReleaseComplete
  |                    | <--SCCP-Released---- |  (no data)
  |                    | ---SCCP-RLC--------> |  (no data)

(Side note, the final SCCP Release Confirm step is taken care of
implicitly by libosmo-sigtran's sccp_scoc.c FSM.)

If the CN fails to respond with SCCP-Released, on new X31 timeout,
osmo-hnbgw will send an SCCP Released to the CN as fallback.

== Memory model for message dispatch ==
So far, an osmo_scu_prim aka "oph" was passed between RUA and SCCP
handling code, and the final dispatch freed it. Every error path had to
take care not to leak any oph.
Instead, use a much easier and much more leakage proof memory model,
inspired by fixeria:
- on rx, dispatch RANAP msgb that live in OTC_SELECT.
- no code path needs to msgb_free() -- the msgb is discarded via
  OTC_SELECT when handling is done, error or no error.
- any code path may also choose to store the msgb for async dispatch,
  using talloc_steal(). The user plane mapping via MGW and UPF do that.
- if any code path does msgb_free(), that would be no problem either
  (but none do so now, for simplicity).

== Layer separation ==
Dispatch *all* connection-oriented RUA tx via the RUA FSM and SCCP tx
via the SCCP FSM, do not call rua_tx_dt() or osmo_sccp_user_sap_down()

== Memory model for decoded ranap_message IEs ==
Use a talloc destructor to make sure that the ranap_message IEs are
always implicitly freed upon talloc_free(), so that no code path can
possibly forget to do so.

== Implicit cleanup by talloc ==
Use talloc scoping to remove a bunch of explicit cleanup code. For
example, make a chached message a talloc child of its handler:
  talloc_steal(mgw_fsm_priv, message);
  mgw_fsm_priv->ranap_rab_ass_req_message = message;
and later implicitly free 'message' by only freeing the handler:

Related: SYS#6297
Change-Id: I6ff7e36532ff57c6f2d3e7e419dd22ef27dafd19
2023-02-24 15:19:24 +01:00
contrib Bump version: → 1.4.0 2023-02-07 18:05:47 +01:00
debian Bump version: → 1.4.0 2023-02-07 18:05:47 +01:00
doc add design charts for new context map FSMs 2023-02-23 02:03:20 +01:00
include context map: introduce RUA and SCCP FSMs to fix leaks 2023-02-24 15:19:24 +01:00
src context map: introduce RUA and SCCP FSMs to fix leaks 2023-02-24 15:19:24 +01:00
tests fix deprecation: use ranap_cn_rx_co_decode2() 2023-02-23 01:17:11 +01:00
.gitignore Initial structure + import code from osmo-iuh.git 2022-01-04 19:48:52 +01:00
.gitreview Initial structure + import code from osmo-iuh.git 2022-01-04 19:48:52 +01:00
AUTHORS Initial structure + import code from osmo-iuh.git 2022-01-04 19:48:52 +01:00
COPYING Initial structure + import code from osmo-iuh.git 2022-01-04 19:48:52 +01:00
Makefile.am Initial structure + import code from osmo-iuh.git 2022-01-04 19:48:52 +01:00
README.md update URLs (git -> https; gitea) 2022-06-18 14:02:41 +02:00
TODO-RELEASE Deprecate 'sccp cr max-payload-len', remove SCCP CR limit code 2023-02-15 03:34:43 +01:00
configure.ac add design charts for new context map FSMs 2023-02-23 02:03:20 +01:00
git-version-gen Initial structure + import code from osmo-iuh.git 2022-01-04 19:48:52 +01:00
osmoappdesc.py Initial structure + import code from osmo-iuh.git 2022-01-04 19:48:52 +01:00


osmo-hnbgw - Osmocom hNodeB Implementation

This repository contains a C-language implementation of a 3G Home NodeB Gateway (OsmoHNBGW). It is part of the Osmocom Open Source Mobile Communications project.

You can use it to interface Iuh-speaking Home NodeB (HnodeB), such as osmo-hnodeb or ip.access nano3g, to Iu-speaking MSCs and SGSNs.


The official homepage of the project is https://osmocom.org/projects/osmohnbgw/wiki

GIT Repository

You can clone from the official osmo-hnbgw.git repository using

git clone https://gitea.osmocom.org/cellular-infrastructure/osmo-hnbgw

There is a web interface at https://gitea.osmocom.org/cellular-infrastructure/osmo-hnbgw


User Manuals and VTY reference manuals are [optionally] built in PDF form as part of the build process.

Pre-rendered PDF version of the current "master" can be found at User Manual as well as the VTY Reference Manual

Mailing List

Discussions related to osmo-hnbgw are happening on the openbsc@lists.osmocom.org mailing list, please see https://lists.osmocom.org/mailman/listinfo/openbsc for subscription options and the list archive.

Please observe the Osmocom Mailing List Rules when posting.


Our coding standards are described at https://osmocom.org/projects/cellular-infrastructure/wiki/Coding_standards

We us a gerrit based patch submission/review process for managing contributions. Please see https://osmocom.org/projects/cellular-infrastructure/wiki/Gerrit for more details

The current patch queue for osmo-hnbgw can be seen at https://gerrit.osmocom.org/#/q/project:osmo-hnbgw+status:open