lte: Document changes related to LTE handover failure

CHANGES.md

@@ -68,6 +68,11 @@ Changes from ns-3.36 to ns-3.37
 * Lr-wpan: **LrWpanPhy** now change to TRX_OFF after a CSMA-CA failure when the RxOnWhenIdle flag is set to false in the **LrWpanMac**.
 * The **Channel** attribute of `WifiNetDevice` is deprecated because it became ambiguous with the introduction of multiple links per device. The **Channel** attribute of `WifiPhy` can be used instead.
 * The O2I Low/High Building Penetration Losses will add losses in the pathloss calculation when buildings are present and a UE results to be in O2I state. In order to not consider these losses, they can be disabled by setting BuildingPenetrationLossesEnabled to false.
+* Support for four types of UE handover failure are now modeled:
+  * A HO failure is triggered if eNB cannot allocate non-contention-based preamble.
+  * Handover joining timeout is now handled.
+  * Handover leaving timeout is now handled.
+  * Upon RACH failure during HO, the UE will perform cell selection again.
 
 Changes from ns-3.36 to ns-3.36.1
 ---------------------------------

RELEASE_NOTES.md

@@ -29,6 +29,7 @@ Release 3-dev
 - (lr-wpan) Adds support for PAN Id compression (IEEE 802.15.4-2006 (7.5.6.1))
 - (utils) `utils/bench-simulator` has been moved to `utils/bench-scheduler` to better reflect what it actually tests
 - (utils) `utils/bench-scheduler` has been enhanced to test multiple schedulers.
+- (lte) LTE handover failure is now handled for joining and leaving timeouts, RACH failure, and preamble allocation failure.
 
 ### Bugs fixed
 

src/lte/doc/source/lte-testing.rst

@@ -1422,6 +1422,23 @@ computation, utilizing the fact that the handover will be delayed when this
 computation is broken. In the default simulation configuration, the handover
 delay observed because of a broken RA-RNTI computation is typically 6 ms.
 
+Handover failure
+----------------
+
+The test suite ``lte-handover-failure`` tests the proper operation of a number
+of handover failure cases by inducing the conditions leading to the following
+eight failure modes:
+
+1. Maximum number of RACH transmissions exceeded from UE to target eNB 
+2. Non-allocation of non-contention-based preamble at the target eNB, due to the maximum number reached
+3. HANDOVER JOINING timeout before reception of RRC CONNECTION RECONFIGURATION at source eNB
+4. HANDOVER JOINING timeout before completion of non-contention RACH process to target eNB
+5. HANDOVER JOINING timeout before reception of RRC CONNECTION RECONFIGURATION COMPLETE at target eNB
+6. HANDOVER LEAVING timeout before reception of RRC CONNECTION RECONFIGURATION at source eNB
+7. HANDOVER LEAVING timeout before completion of non-contention RACH process to target eNB
+8. HANDOVER LEAVING timeout before reception of RRC CONNECTION RECONFIGURATION COMPLETE attarget eNB
+
+Both Ideal and Real RRC models are checked by this test suite.
 
 Selection of target cell in handover algorithm
 ----------------------------------------------

src/lte/doc/source/lte-user.rst

@@ -1617,14 +1617,36 @@ like this::
    Config::Connect ("/NodeList/*/DeviceList/*/LteUeRrc/HandoverEndOk",
                     MakeCallback (&NotifyHandoverEndOkUe));
 
+Handover failure events can also be traced by trace sink functions with
+a similar signature as above (including IMSI, cell ID, and RNTI). Four
+different failure events are traced:
+
+1. HandoverFailureNoPreamble: Handover failure due to non allocation of 
+   non-contention-based preamble at eNB
+2. HandoverFailureMaxRach: Handover failure due to maximum RACH attempts
+3. HandoverFailureLeaving: Handover leaving timeout at source eNB
+4. HandoverFailureJoining: Handover joining timeout at target eNB 
+
+Similarly, one can hook up methods to the corresponding trace sources
+like this::
+
+   Config::Connect ("/NodeList/*/DeviceList/*/LteEnbRrc/HandoverFailureNoPreamble",
+                    MakeCallback (&NotifyHandoverFailureNoPreamble));
+   Config::Connect ("/NodeList/*/DeviceList/*/LteEnbRrc/HandoverFailureMaxRach",
+                    MakeCallback (&NotifyHandoverFailureMaxRach));
+   Config::Connect ("/NodeList/*/DeviceList/*/LteEnbRrc/HandoverFailureLeaving",
+                    MakeCallback (&NotifyHandoverFailureLeaving));
+   Config::Connect ("/NodeList/*/DeviceList/*/LteEnbRrc/HandoverFailureJoining",
+                    MakeCallback (&NotifyHandoverFailureJoining));
+
 The example program ``src/lte/examples/lena-x2-handover.cc``
-illustrates how the all above instructions can be integrated in a
+illustrates how the above instructions can be integrated in a
 simulation program. You can run the program like this::
 
    ./ns3 run lena-x2-handover
 
 and it will output the messages printed by the custom handover trace
-hooks. In order additionally visualize some meaningful logging
+hooks. In order to additionally print out some meaningful logging
 information, you can run the program like this::
 
     NS_LOG=LteEnbRrc:LteUeRrc:EpcX2 ./ns3 run lena-x2-handover