Documentation for lte-handover-target test suite

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

@@ -1305,3 +1305,39 @@ by Random Access during the handover procedure. The test cases verify this
 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.
+
+
+Selection of target cell in handover algorithm
+----------------------------------------------
+
+eNodeB may utilize :ref:`sec-handover-algorithm` to automatically create
+handover decisions during simulation. The decision includes the UE which should
+do the handover and the target cell where the UE should perform handover to.
+
+The test suite ``lte-handover-target`` verifies that the handover algorithm is
+making the right decision, in particular, in choosing the right target cell. It
+consists of several short test cases for different network topology (2x2 grid
+and 3x2 grid) and types of handover algorithm (legacy handover algorithm and
+strongest cell handover algorithm).
+
+Each test case is a simulation of a micro-cell environment with the following
+parameter:
+
+ - EPC is enabled
+ - several circular (isotropic antenna) micro-cell eNodeBs in a rectangular grid
+   layout, with 130 m distance between each adjacent point 
+ - 1 static UE, positioned close to and attached to the source cell
+ - no control channel error model
+ - no application installed
+ - no channel fading
+ - default path loss model (Friis)
+ - 1s simulation duration
+
+To trigger a handover, the test case "shutdowns" the source cell at +0.5s
+simulation time. This is done by setting the source cell's Tx power to a very
+low value. As a result, the handover algorithm notices that the UE deserves a
+handover and several neighbouring cells become candidates of target cell at the
+same time.
+
+The test case then verifies that the handover algorithm, when faced with more
+than one options of target cells, is able to choose the right one.

src/lte/test/test-lte-x2-handover-measures.cc

@@ -715,10 +715,35 @@ static LteX2HandoverMeasuresTestSuite g_lteX2HandoverMeasuresTestSuiteInstance;
 /**
  * \brief Testing a handover algorithm, verifying that it selects the right
  *        target cell when more than one options available.
+ *
+ * Part of the `lte-handover-target` test suite.
+ *
+ * The test case will run a 1-second LTE-EPC simulation using the parameters
+ * provided to the constructor function.
+ *
+ * \sa ns3::LteX2HandoverTargetTestSuite
  */
 class LteX2HandoverTargetTestCase : public TestCase
 {
 public:
+  /**
+   * \brief Construct a new test case and providing input parameters for the
+   *        simulation.
+   * \param name the name of the test case, to be displayed in the test result
+   * \param uePosition the point in (x, y, z) coordinate where the UE will be
+   *                   placed in the simulation
+   * \param gridSizeX number of eNodeBs in a row
+   * \param gridSizeY number of eNodeBs in a column
+   * \param sourceCellId the cell ID of the eNodeB which the UE will be
+   *                     initially attached to in the beginning of simulation,
+   *                     and also the eNodeB which will "shutdown" in the
+   *                     middle of simulation
+   * \param targetCellId the cell ID of the expected eNodeB where the UE will
+   *                     perform handover to after the "shutdown" of the source
+   *                     cell
+   * \param handoverAlgorithmType the type of handover algorithm to be used in
+   *                              all eNodeBs
+   */
   LteX2HandoverTargetTestCase (std::string name, Vector uePosition,
                                uint8_t gridSizeX, uint8_t gridSizeY,
                                uint16_t sourceCellId, uint16_t targetCellId,
@@ -727,7 +752,8 @@ public:
   virtual ~LteX2HandoverTargetTestCase ();
 
   /**
-   * \brief Triggers when eNodeB starts a handover.
+   * \brief Triggers when an eNodeB starts a handover and then verifies that
+   *        the handover has the right source and target cells.
    *
    * The trigger is set up beforehand by connecting to the
    * `LteEnbRrc::HandoverStart` trace source.
@@ -736,14 +762,23 @@ public:
                               uint16_t sourceCellId, uint16_t rnti,
                               uint16_t targetCellId);
 
+  /**
+   * \brief A trigger that can be scheduled to "shutdown" the cell pointed by
+   *        `m_sourceCellId` by reducing its power to 1 dB.
+   */
   void CellShutdownCallback ();
 
 private:
   /**
-   * \brief Simulate a micro-cell network in a rectangular grid.
+   * \brief Run a simulation of a micro-cell network using the parameters
+   *        provided to the constructor function.
    */
   virtual void DoRun ();
 
+  /**
+   * \brief Called at the end of simulation and verifies that a handover has
+   *        occurred in the simulation.
+   */
   virtual void DoTeardown ();
 
   // simulation parameters
@@ -771,6 +806,20 @@ LteX2HandoverTargetTestCase::LteX2HandoverTargetTestCase (std::string name, Vect
     m_hasHandoverOccurred (false)
 {
   NS_LOG_INFO (this << " name=" << name);
+
+  // SANITY CHECK
+
+  uint16_t nEnb = gridSizeX * gridSizeY;
+
+  if ((sourceCellId < 0) && (sourceCellId > nEnb))
+    {
+      NS_FATAL_ERROR ("Invalid source cell ID " << sourceCellId);
+    }
+
+  if ((targetCellId < 0) && (targetCellId > nEnb))
+    {
+      NS_FATAL_ERROR ("Invalid target cell ID " << targetCellId);
+    }
 }
 
 
@@ -984,7 +1033,7 @@ public:
 
 
 LteX2HandoverTargetTestSuite::LteX2HandoverTargetTestSuite ()
-  : TestSuite ("lte-x2-handover-target", SYSTEM)
+  : TestSuite ("lte-handover-target", SYSTEM)
 {
   // LogComponentEnable ("LteX2HandoverMeasuresTest", LOG_PREFIX_ALL);
   // LogComponentEnable ("LteX2HandoverMeasuresTest", LOG_LEVEL_ALL);