doc: update/fix FSM charts
These reflect the plan for refactoring, and will be implemented by
I82e3f918295daa83274a4cf803f046979f284366 and
Id7a4407d9b63be05ce63f5f2768b7d7e3d5c86fb
Change-Id: I29e31b753e23a4207662e0e385a337e7df836f45
diff --git a/doc/handover.msc b/doc/handover.msc
index 7529de6..1a2580a 100644
--- a/doc/handover.msc
+++ b/doc/handover.msc
@@ -1,123 +1,82 @@
# Handover between cells, intra-BSC
msc {
- hscale=3;
- ms [label="MS via BTS"], bsc_lchan[label="BSC lchan FSM"], bsc_gscon[label="BSC conn FSM"],
- bsc_mgcp[label="BSC mgcp FSM"], mgw_msc[label="MGW/MSC"];
+ hscale=2;
+ ms [label="MS via BTS"], lchan[label="BSC lchan FSM"], ho[label="BSC Handover FSM"],
+ gscon[label="BSC conn FSM"], msc_[label="MSC"];
- ms note mgw_msc [label="intra-BSC Handover sequence"];
+ ms note msc_ [label="intra-BSC Handover"];
- bsc_gscon abox bsc_gscon [label="ST_ACTIVE"];
- bsc_gscon box bsc_gscon [label="bsc_handover_start(): init conn->ho"];
- bsc_gscon -> bsc_gscon [label="GSCON_EV_HO_START (intra-BSC)"];
- bsc_gscon abox bsc_gscon [label="ST_HANDOVER_\nWAIT_LCHAN"];
- bsc_lchan <- bsc_gscon [label="lchan_activate(lchan, FOR_HANDOVER)"];
+ gscon abox gscon [label="ST_ACTIVE"];
+
+ ms => ho [label="Measurement Report"];
+ ho box ho [label="Handover Decision"];
+ ho box ho [label="handover_request\n(struct handover_out_req)"];
+ ho note gscon [label="To make sure the conn FSM permits a handover, trigger an event:"];
+ ho -> gscon [label="GSCON_EV_HANDOVER_START\ndata=handover_out_req"];
+ gscon abox gscon [label="ST_HANDOVER"];
+ ho <- gscon [label="handover_start\n(handover_out_req)"];
+ ho box ho [label="handover_start_intra_bsc()"];
+ ho abox ho [label="allocate\nHO_ST_NOT_STARTED"];
+
...;
- --- [label="on lchan FSM error or timeout"];
- bsc_lchan -> bsc_gscon [label="GSCON_EV_LCHAN_ALLOC_ERROR"];
- bsc_gscon box bsc_gscon [label="handover_end(fail)"];
- ms note bsc_gscon [label="MS happily continues on the old lchan."];
- bsc_gscon abox bsc_gscon [label="ST_ACTIVE"];
- --- [label="END: 'on error'"];
+ ...;
+ --- [label="On any error or timeout"];
+ ho box ho [label="handover_end(fail)"];
+ ho -> gscon [label="GSCON_EV_HANDOVER_END"];
+ gscon abox gscon [label="ST_ACTIVE"];
+ ms note gscon [label="MS happily continues on the old lchan."];
+ --- [label="END: 'On any error or timeout'"];
...;
...;
- --- [label="IF lchan FSM decides that it is an lchan for speech"];
- bsc_lchan -> bsc_gscon [label="GSCON_EV_ENSURE_MGW_ENDPOINT"];
- --- [label="IF there is an MGW endpoint for the BTS already (conn->user_plane.fi_bts)"];
- bsc_gscon box bsc_gscon [label="handover_created_mgw_endpoint = false"];
- bsc_gscon -> bsc_lchan [label="LCHAN_EV_MGW_ENDPOINT_AVAILABLE"];
- --- [label="ELSE: no MGW endpoint for the BTS side yet"];
- bsc_gscon abox bsc_gscon [label="ST_HANDOVER_\nWAIT_CRCX_BTS"];
- bsc_gscon box bsc_gscon [label="handover_created_mgw_endpoint = true"];
- bsc_gscon -> bsc_mgcp [label="mgcp_conn_create()"];
- bsc_mgcp => mgw_msc [label="CRCX (for BTS)"];
- bsc_mgcp abox bsc_mgcp [label="ST_CRCX_RESP (MGCP_MGW_TIMEOUT = 4s)"];
- bsc_gscon note bsc_mgcp [label="conn FSM relies on mgcp FSM timeout"];
- ...;
- --- [label="On Timeout"];
- bsc_mgcp note bsc_mgcp [label="On timeout, the MGCP FSM will terminate, emitting the parent_term
- event set upon mgcp_conn_create():"];
- bsc_mgcp -> bsc_gscon [label="GSCON_EV_MGW_FAIL_BTS"];
- bsc_gscon note bsc_gscon [label="GSCON_EV_MGW_FAIL_BTS is handled by the conn FSM allstate
- handler. It sets conn->user_plane.fi_bts = NULL."];
- bsc_gscon -> bsc_lchan [label="LCHAN_EV_MGW_ENDPOINT_ERROR"];
- bsc_lchan note bsc_gscon [label="conn FSM error handler exits and relies on the lchan FSM
- signalling error, which should actually happen immediately:"];
- bsc_gscon <- bsc_lchan [label="GSCON_EV_LCHAN_ALLOC_ERROR"];
- bsc_gscon box bsc_gscon [label="handover_end(fail)"];
- --- [label="IF handover_created_mgw_endpoint == true"];
- bsc_gscon -> bsc_mgcp [label="mgcp_conn_delete()"];
- ---;
- ms note bsc_gscon [label="MS happily continues on the old lchan."];
- bsc_gscon abox bsc_gscon [label="ST_ACTIVE"];
- --- [label="END: 'On Timeout'"];
- ...;
+ ho box ho [label="lchan_select_by_type()"];
+ ho abox ho [label="HO_ST_WAIT_\nLCHAN_ACTIVE"];
+ lchan <- ho [label="lchan_activate(FOR_HANDOVER)"];
+ lchan rbox lchan [label="(most details omitted, see lchan_fsm diagrams)"];
- bsc_mgcp <= mgw_msc [label="CRCX OK (for BTS)"];
- bsc_mgcp box bsc_mgcp [label="libosmo-mgcp-client fsm_crcx_resp_cb()"];
- bsc_mgcp abox bsc_mgcp [label="ST_READY"];
- bsc_mgcp -> bsc_gscon [label="GSCON_EV_MGW_CRCX_RESP_BTS"];
- bsc_gscon abox bsc_gscon [label="ST_HANDOVER_\nWAIT_LCHAN"];
- bsc_gscon -> bsc_lchan [label="LCHAN_EV_MGW_ENDPOINT_AVAILABLE"];
- --- [label="END: lchan FSM decides that it is an lchan for speech"];
+ ...;
+ ...;
+ --- [label="On lchan error or timeout"];
+ lchan -> ho [label="HO_EV_LCHAN_ERROR"];
+ ho rbox gscon [label="same as above"];
+ --- [label="END: 'On lchan error or timeout'"];
...;
...;
- bsc_lchan -> bsc_gscon [label="GSCON_EV_LCHAN_ACTIVE"];
- bsc_gscon abox bsc_gscon [label="ST_HANDOVER_\nWAIT_DETECT\nT3103"];
- bsc_gscon box bsc_gscon [label="gsm48_send_ho_cmd()"];
- ms <= bsc_gscon [label="RR Handover Command"];
-
+ lchan abox lchan [label="LCHAN_ST_WAIT_ACTIV_ACK"];
+ ms <= lchan [label="RSL Chan Activ"];
...;
- --- [label="On timeout"];
- bsc_lchan <- bsc_gscon [label="NEW lchan: LCHAN_EV_RELEASE"];
- ms <=> bsc_lchan [label="release procedure (async)"];
- bsc_gscon box bsc_gscon [label="handover_end(fail)"];
- --- [label="IF handover_created_mgw_endpoint == true"];
- bsc_gscon -> bsc_mgcp [label="mgcp_conn_delete()"];
- ---;
- ms note bsc_gscon [label="MS happily continues on the old lchan."];
- bsc_gscon abox bsc_gscon [label="ST_ACTIVE"];
- --- [label="END: On timeout"];
+ ms => lchan [label="RSL Chan Activ ACK"];
+ lchan -> ho [label="HO_EV_LCHAN_ACTIVE"];
+ ho abox ho [label="HO_ST_WAIT_\nRR_HO_DETECT"];
...;
- ms => bsc_gscon [label="RR Handover Detect"];
-
- bsc_gscon abox bsc_gscon [label="ST_HANDOVER_\nWAIT_MDCX_BTS\ncontinue T3103"];
- bsc_gscon -> bsc_lchan [label="OLD lchan: LCHAN_EV_RELEASE"];
- ms <=> bsc_lchan [label="release procedure (async)"];
- bsc_lchan note bsc_gscon [label="officially take over new lchan: conn->lchan = ho->new_lchan"];
- bsc_gscon -> bsc_mgcp [label="mgcp_conn_modify()"];
- bsc_mgcp note bsc_mgcp [label="mgcp FSM that was established for old lchan, for BTS side"];
- bsc_mgcp abox bsc_mgcp [label="ST_MDCX_RESP"];
- bsc_mgcp => mgw_msc [label="MDCX (for BTS)"];
+ ms => ho [label="RR Handover Detect\nHO_EV_RR_HO_DETECT"];
+ lchan note ho [label="At this point we should start to switch the MGW over to the new lchan.
+ But this is not implemented yet, as was not before introducing these FSMs."];
+ ho abox ho [label="HO_ST_WAIT_\nRR_HO_COMPLETE"];
...;
- --- [label="Should the Handover Complete arrive early"];
- ms => bsc_gscon [label="RR Handover Complete"];
- bsc_gscon box bsc_gscon [label="handover_complete_received = true"];
- ---;
+ lchan note ho [label="The lchan FSM will continue with RSL and RTP while the HO FSM waits.
+ HO_EV_LCHAN_ESTABLISHED means that both RSL and RTP are established.
+ Usually, RTP will be done first, and the HO_EV_LCHAN_ESTABLISHED may be
+ received even before HO_EV_RR_HO_COMPLETE.
+ ho_fsm_wait_lchan_established_onenter() decides whether to wait or not."];
...;
- --- [label="On timeout of the mgcp FSM"];
- bsc_gscon note mgw_msc [label="MGCP FSM terminates"];
- bsc_gscon <- bsc_mgcp [label="GSCON_EV_MGW_FAIL_BTS"];
- bsc_lchan note bsc_gscon [label="The phone has already taken on the new lchan, but now we happen
- to not be able to use it. The only sensible thing is to end the conn."];
- bsc_gscon abox bsc_gscon [label="ST_WAIT_CLEAR_CMD"];
- bsc_gscon => mgw_msc [label="BSSMAP Clear Request\n(Equipment Failure)"];
- bsc_lchan <- bsc_gscon [label="NEW lchan: LCHAN_EV_RELEASE"];
- ms <=> bsc_lchan [label="release procedure (async)"];
- bsc_gscon -> bsc_mgcp [label="mgcp_conn_delete()"];
+ ms => lchan [label="RSL EST IND"];
+ lchan -> ho [label="HO_EV_LCHAN_ESTABLISHED",ID="(may come as early as this, or...)"];
+ ms => ho [label="RR Handover Complete (from EST IND)\n HO_EV_RR_HO_COMPLETE"];
+ ho abox ho [label="HO_ST_WAIT_\nLCHAN_ESTABLISHED"];
...;
- bsc_mgcp <= mgw_msc [label="MDCX OK"];
- bsc_mgcp abox bsc_mgcp [label="ST_READY"];
- bsc_mgcp -> bsc_gscon [label="GSCON_EV_MGW_MDCX_RESP_BTS"];
- --- [label="IF !handover_complete_received"];
- bsc_gscon abox bsc_gscon [label="ST_HANDOVER_\nWAIT_COMPLETE\ncontinue T3103"];
- --- [label="ELSE"];
- bsc_gscon -> bsc_gscon [label="gscon_handover_post_complete()"];
- ---;
+ lchan rbox lchan [label="when lchan FSM is done with setting up RTP"];
+ lchan -> ho [label="HO_EV_LCHAN_ESTABLISHED",ID="(...may come only now)"];
+ ho abox ho [label="HO_ST_WAIT_\nMGW_ENDPOINT_TO_MSC"];
+ ho -> gscon [label="gscon_connect_mgw_to_msc()"];
...;
- ms => bsc_gscon [label="RR Handover Complete"];
- bsc_gscon box bsc_gscon [label="gscon_handover_post_complete()"];
- bsc_gscon note bsc_gscon [label="handover_end(success), conn->ho = NULL"];
- bsc_gscon abox bsc_gscon [label="ST_ACTIVE"];
+ ho <- gscon [label="HO_EV_MSC_MGW_OK"];
+ ho box ho [label="handover_end(OK)"];
+ ho -> gscon [label="gscon_change_primary_lchan()"];
+ lchan <- gscon [label="LCHAN_RTP_EV_ESTABLISHED"];
+ ho -> gscon [label="GSCON_EV_HANDOVER_END"];
+ gscon abox gscon [label="ST_ACTIVE"];
+ ho box ho [label="detach from parent to not fire another meaningless GSCON_EV_HANDOVER_END"];
+ ho abox ho [label="terminate"];
}