OsmoPCU: past, present and future
=================================
:author:	Pau Espin Pedrol <pespin@sysmocom.de>
:copyright:	2024 by sysmocom - s.f.m.c. GmbH <info@sysmocom.de> (License: CC-BY-SA)
:backend:	slidy
:max-width:	54em

== PCU: GPRS Packet Control Unit

* Forwards LLC data frames between MS and SGSN:
** SNDCP (link:https://www.etsi.org/deliver/etsi_ts/144000_144099/144065/06.06.00_60/ts_144065v060600p.pdf[3GPP TS 44.065]): user plane (IP/UDP/TCP/...)
** GMM (link:https://www.etsi.org/deliver/etsi_ts/124000_124099/124008/16.07.00_60/ts_124008v160700p.pdf[3GPP TS 24.008]): control plane

* Towards the MS (Um): RLC/MAC (link:https://www.etsi.org/deliver/etsi_ts/144000_144099/144060/16.00.00_60/ts_144060v160000p.pdf[3GPP TS 44.060])
* Towards the SGSN (Gb): BSSGP (link:https://www.etsi.org/deliver/etsi_ts/144000_144099/144064/16.00.00_60/ts_144064v160000p.pdf[3GPP TS 44.064]), NS (link:https://www.etsi.org/deliver/etsi_ts/148000_148099/148016/16.00.00_60/ts_148016v160000p.pdf[3GPP TS 48.016])
* Towards the BTS/BSC: Not specified, Osmocom link:https://gitea.osmocom.org/cellular-infrastructure/osmo-pcu/src/branch/master/include/osmocom/pcu/pcuif_proto.h[PCU_IF]

image::gprs_stack.jpg[width="100%"]

== PCU: Location

.Co-located with BTS:
** OsmoBTS (with/without `direct_phy`)

include::pcu_loc_bts_graphviz.adoc[]

.Co-located with BSC:
** Ericsson RBS

include::pcu_loc_bsc_graphviz.adoc[]

== Past:

[role="incremental"]
* It's 2017..2019 AD
* PCU, the Ugly Ducking => no looking at it, no touching it
* Heap of debris, people keep adding stuff on to it _(dramatic exaggeration)_
* Not much architecture/API documentation
* Code lacking spec references backing logic
* C++ (problems with talloc, osmo_*, `llist` ASan false positives, ...)
* Code really entangled:
[role="incremental"]
** Lots of spaghetti code
** Object lifecycle not clear
** No separation between `bts` and `pcu` object
** `tbf`/`dl_tbf`/`ul_tbf` classes in same file
** `tbf`/`GprsMs` object relation mess,`tbf` didn't have an MS object assigned sometimes
** `alloc_algo` resource allocation not logically separated from `tbf` allocation, directly modifying them
* Code lacking use of osmocom infra:
** No FSMs
** Lots of timers not using osmo_tdef
* Existing logging not that useful / difficult to follow
* Really difficult to figure out when certain events or code paths triggered (eg. DL vs UL TBF).

* Functional architectural problems:
** GPRS vs EGPRS mode, exclusive
** No differentiation between CS/MCS L1 capabilities and GPRS/EGPRS (eg using EGPRS with only MCS1..MCS4)
** Not receiving all TDMA blocks (DATA.ind): no fullTDMA clock. Procedures based on wall clock timers.
[role="incremental"]
*** Impossible for PCU scheduler to track T31XY, lost packets, etc.
*** Stuff based on wall clock timers.

== Past: Tests

* No TTCN-3 tests
* Only unit tests:
** Long and difficult to follow/debug
** Using osmo-pcu objects/code in an artifical way, sometimes wrong
** Lots of code in osmo-pcu only used by unit tests => death code

* Modifying code = high risk of breaking stuff, regressions

== Motto 1:

image::one_does_not_simply_change_pcu.jpg[width="100%"]

* Consequence: New bugs and regressions are coming (TM)

== Motto 2:

image::one_does_not_simply_fix_bug_pcu.jpg[width="100%"]

* Consequence: lots of refactoring commits required usually prior to fixing a bug without breaking more stuff

== Chronology (1)

// Refactoring rounds done in iterations: Submit bunch of commits, let them settle and see if regressions show up, next round.
// Refactoring rounds or interesting events, in chronological order:

.The Dark Age:

[role="incremental"]
* _2017_: Attempts at splitting spaghetti code (Max, no ttcn3, regressions sometimes)
* _2017-08-09_: I start coding on osmo-pcu (owning 749/1333 commits since then)
* _2018-03-08_: TTCN3 PCU_Tests added (mostly only NS tests from Harald)

== Chronology (2)

.Refactoring, refactoring, refactoring...

[role="incremental"]
* _2019-09-*_: TTCN3 PCU_Tests testing RLC/MAC (w/ Vadim)
* _2019-09-*_: Move several timers to osmo_tdef; tdef subclass moved to own files
* _2019-12-*_: Support PAGING-CS/PS from SGSN
* _2020-0{1,2,3}-*_: Lots of CSN.1 enc/dec improvements on MS RA Capability (w/ Vadim)
* _2020-05-*_: GprsMs object now allocated before tbf object; C++--
* _2020-06-*_: 11bit RACH support for EGPRS (Vadim)
* _2020-07-*_: PCUIFv10: IPv6 NSVC support, NS2 lib (lynxis)
* _2020-10-*_: More `tbf`/`dl_tbf`/`ul_tbf` untangling, Allocator fixes
* _2020-11-*_: GPRS + EGPRS multiplex support
* _2020-12-16_: Convert lots of C++ classes to C
* _2021-01-*_: Split `pcu` and `bts` objects, C++--
* _2021-01-*_: NACC/RIM support. Frist FSM! `nacc_fsm`
* _2021-02-22_: Multi-slot UL TBF support
* _2021-03-*_: PCUIF: Rx DATA.ind len=0, track TDMA clock on block basis
* _2021-0{3,4}-*_: Introduce PDCH UL Controller (`pdch_ulc`): sb, RRBP polls (other than N+13), sba, etc.
* _2021-05-14_: Initial FSM `tbf_state`! (logic *slowly* moved inside)
* _2021-07-27_: FSMS `tbf_ul_ass_state`, `tbf_dl_ass_state`
* _2021-09-20_: Skip Tx idle blocks over PCUIF: BTS BCCH Tx power reduction
* _2021-11-15_: Release 1.0.0, tons of stuff was moved to FSMs

== Chronology (3)

.Not done refactoring yet:

[role="incremental"]
* _2022-03-31_: LLC schedule with SAPI priority. LLC code C++--
* _2022-10-27_: Refactor GprsMs code assigning TBFs (new APIs). Improved logging.
* _2022-11-17_: Split tbf_fsm as tbf_{ul,dl}_fsm!
* _2023-0{2,3,4}-*_: Ericsson RBS support (Philipp)
* _2023-04-*_: gprs_rlcmac.cpp C++-- (Max)
* _2023-04-*_: Rewrite GprsMs lifecycle (refcounts, etc.), GprsMsStorage merged into BTS.
* _2023-04-*_: Split tbf allocation from resource allocation (`alloc_algo` becomes idempotent).
* _2023-06-*_: Start fixing issues spotted during osmocom-bb gprs implementation
* _2023-08-*_: PCUIFv11: DATA.cnf s/tlli/msg_id/, new paging SAPIs
* _2023-08-22_: Allow modifying default msclass
* _2023-10-05_: PCUIFv12: Signal BTS model in INFO.ind
* _2024-03-25_: More `tbf`/`GprsMs` lifecycle fixes

== Present

.Great:
[role="incremental"]
* We have a TTCN-3 testsuite with 117 test cases (405 commits in osmo-ttcn3-hacks/pcu/)
* Logging is more standarized and provides related context (eg. FSM): easier debug
* Better documented code with spec references backing logic
* More robust code base
* TDMA clock tracking: Proper implementation of T31XY and N31XY
* More efficient: multi-slot UL_TBF, RRBP != N+13, ...
* Closer to multi-BTS per OsmoPCU co-located with OsmoBSC
* Allocation of resources without the need to allocate a TBF: Allows for future TBF load-based reallocation
* Good base for new functionalitites and improvements

.Not so great:
[role="incremental"]
* Refactoring not yet complete
* Limit of 8-TRX per BTS
* BSSGP/NS code in bad shape (focus so far in RLC/MAC)

== Ericsson RBS support

* TODO: Merged, support since when?
* OsmoPCU Co-located with OsmoBSC
* `./configure --enable-er-e1-ccu`
* Enabled in Osmocom OBS package repositories

* TODO: look at related redmine tickets
* TODO: look at related commit history:
* TODO: ask pmaier for review
* TODO:

== Data Model

include::data_model_graphviz.adoc[]

== Code Architecture

[role="incremental"]
* Rx PCUIF `INFO.ind`: when BTS/BSC connects, initial configuration of BTS/TRXs/PDCHs
* Rx PCUIF `DATA.ind`: SAPI=`BCCH` from BTS/BSC with SystemInformation used for configuration

== Code Architecture: Uplink, RACH

[role="incremental"]
. Rx PCUIF `RACH.ind(BTS-TRX-TS,FN,RA)` from BTS/BSC (over `pcu_sock` or `direct_phy`)
. One-phase-access:
[role="incremental"]
.. Allocate resources: MS, UL_TBF (single slot), TFI, USF, ...
.. Tx ImmAss over CCCH
.. Register `TBF_POLL` for the TBF in PDCH ULC
. Two-phase-access:
[role="incremental"]
.. Allocate resources: SBA
.. Register `SBA` in PDCH ULC, Tx ImmAss over CCCH
.. Wait for Pkt Resource Request

== Code Architecture: Uplink, PDTCH

[role="incremental"]
. Rx PCUIF `DATA.ind(BTS-TRX-TS,FN)` SAPI=`PDTCH` from BTS/BSC (over `pcu_sock` or `direct_phy`)
. Update TDMA clock (per BTS), detect FN jumps
. `pdch->rcv_block(data, len, fn, meas)`: Handle block: GPRS vs EPGRS, CTRL vs DATA
.. UL CONTROL:
[role="incremental"]
... Decode whole block
... Handle specifically per msg type (Validate against registered entries in PDCH ULC `TBF_POLL` or `SBA`)
.. UL DATA:
[role="incremental"]
... Decode header => TFI => UL TBF
... Validate against registered entries in PDCH ULC (`TBF_USF`)
... Handle data in TBF
. Expire registered polls up to BTS-TRX-TS included (trigger timeouts)

== Code Architecture Downlink, PDTCH

[role="incremental"]
. Rx PCUIF `RTS.req(BTS-TRX-TS,FN)` SAPI=`PDTCH` from BTS/BSC (over `pcu_sock` or `direct_phy`), FN in the future!
. scheduler: `gprs_rlcmac_rcv_rts_block()`
[role="incremental"]
.. Check if EGPRS can be used due to GPRS-only MS synchronization requirements
.. Figure out USF for dl_block based on PDCH ULC state (SBA, polls), or allow UL data Tx (round-robin)
.. Maybe Tx: DL CTRL block (FSMs, MS/TBF state)
.. Maybe Tx: DL DATA block (TBF state, round-robin, priority)
.. Maybe Tx: Dummy control message
.. Tx PCUIF `DATA.req`


== TTCN-3 testsuite

include::ttcn3_component_diagram.adoc[]

== Future

[role="incremental"]
* Improve TTCN-3 testsuite
* Convert more C++ -> C
* Multi-bts support for BSC-colocated
* >8 TRX per BTS
* Improve BSSGP/NS code
* Clean up L1IF vs PCUIF layers (`direct_phy`)
* Drop dummy ul_tbf objects created during RACH request, instead use some specific type
* Improve `alloc_algo`, reconfigure TBFs to adapt for user load
* Improve scheduler
* Implement TA loop
* ImplementPower loop
* ANR: WIP in a branch, not working (deed90dd0030e6ea32ad4d74386cd91fc2f67436)

== Questions ?

* IRC: #osmocom @ freenode
* link:https://osmocom.org/projects/osmopcu/wiki/OsmoPCU[OsmoPCU redmine project]
* link:https://gitea.osmocom.org/cellular-infrastructure/osmo-pcu[osmo-pcu.git git repository]
* Contributing patches via link:https://osmocom.org/projects/cellular-infrastructure/wiki/Gerrit[Osmocom Gerrit]

* Pau Espin Pedrol <pespin@sysmocom.de>
