xapp_rc_ho_kpm

[[TOC]]

Overview

xapp_rc_ho_kpm xApp utilizes the O-RAN standardized service model, RC (Radio Controller) and KPM (Key Performance Management), to facilitate the initiation of mobility procedures. This includes the initiation of mode mobility alongside KPM UE-level measurement reports. The xApp supports the initiation of Handover (HO) for selected UEs towards a target cell.

Note: xApp supports only 1 UE withing 2 cells and 1 GNB

This includes the following stages:

• RC subscription request: create the RC subscription request based on O-RAN specification
• Aperiodic event: create logical event for RC return values
• KPM subscription request: create the KPM subscription request based on O-RAN specification
• Periodic event: create logical event for KPM return values
• RC control request: send RC control request based on O-RAN specification

Sequence Diagram

RC subscription request

• Used Functions:
  • report_sm_xapp_api()

Create an RC subscription request according to the specified format outlined in ORAN.WG3.E2SM-RC-v01.03 (7.4.3 REPORT Service Style 2: Call Process Outcome).

• Event: gen_rc_ev_trigger()

  • Input:

  Parameter	Type in C	Comment
  act_frm	e2sm_rc_ev_trigger_format_e	RC event trigger format enum

  • Output:

  Parameter	Type in C	Comment
  rc_sub.et	e2sm_rc_event_trigger_t	RC event trigger structure

  • Example:

  // Create an event trigger following format 2
  // Call process breakpoint trigger - 9.2.1.1.2
  rc_sub.et = gen_rc_ev_trigger(FORMAT_2_E2SM_RC_EV_TRIGGER_FORMAT);

  Note: The function gen_rc_ev_trigger calls gen_rc_event_trigger_frm_2() to fill the required parameters n according to 9.2.1.1.2 (Call Process Breakpoint) ORAN.WG3.E2SM-RC-v01.03 specification, adhering to the e2sm_rc_event_trigger_t structure with process type id 3 and call break id 1

  Section 9.2.1.1.2

  Call Process Type ID, Mandatory
  Call Breakpoint ID, Mandatory
  Associated E2 Node Info, Optional
  Associated UE Info, Optional

• Action definition: gen_rc_act_def()

  • Input:

    Parameter	Type in C	Comment
    act	sub_oran_sm_t	RC configuration action name and id
    act_frm	e2sm_rc_act_def_format_e	RC action definition format

  • Output:

    Parameter	Type in C	Comment
    rc_sub.ad	e2sm_rc_action_def_t	RC action definition structure

  • Example:

  for (int32_t j = 0; j < args.sub_oran_sm_len; j++) {
    // Define action type based on certain report style
    // Action format 1 is for call process breakpoint style
    act_type = FORMAT_1_E2SM_RC_ACT_DEF;
  
    *rc_sub.ad = gen_rc_act_def((const sub_oran_sm_t)args.sub_oran_sm[j], act_type);
  }

  Note: The function gen_rc_act_def() calls gen_rc_act_def_frm_1() to fill the required parameters n according to Section 9.2.1.2.1 (E2SM-RC Action Definition Format 1) of the O-RAN.WG3.E3SM-RC-v01.03 specification, adhering to the e2sm_rc_action_def_t structure defining action with parameter id 6 (Cell global id) and id 21528 (List of neighbor cells)

  Section 9.2.1.2.1:

  RAN parameter ID, Mandatory
  RAN parameter definition, Optional

---

Aperiodic event

An aperiodic event is the event can happen just once or may occur several time without specific time regularity. In our case, this event is based on different event trigger information element type, adhering to RIC subscription procedure.

RIC subscription procedure
> RC event trigger definition IE style 2 - 7.3.3
> RC action definition IE Format 1 - 9.2.1.2.1

• Used Function
  • sm_cb_{SM-NAME}()
    • sm_cb_rc()

Note: Current received indication messages contains RAN UE ID, Current PCI and Neighbor PCI served as an input for Handover control service. For example:

// Global variable
uint64_t LST_NR_CELL_ID[2] = {0}; 
uint64_t ran_ue_id = 1;

static void sm_cb_rc(sm_ag_if_rd_t const *rd, global_e2_node_id_t const* e2_node){
loop sequence of params:
  loop sequence of UE: 
     if (cur_ue_id->ue_id.type == GNB_UE_ID_E2SM) {
         ran_ue_id = *cur_ue_id->ue_id.gnb.ran_ue_id; // Store the current ran_ue_id

     for (size_t t = 0; t < cur_ue_id->sz_seq_ran_param; t++){
       if(cur_ran_param->ran_param_id == 6){
         // Cell Global ID
         // 9.3.36
         // O-RAN.WG3.E2SM-R003
         // 6.2.2.50 
         sscanf(cell_global_id, "%ld", &LST_NR_CELL_ID[0]); // index 0 is global_cell_id
       }
       // ...
       // UE information
       // List of Neighbor cells
       // 8.1.1.17
       Loop list of cells:
       if(cur_ran_param->ran_param_id == 21528) {
          LST_NR_CELL_ID[cell_idx + 1] = nr_pci; // From 1->N: neighbor cell
       }
     }
   }
}

KPM subscription request

• Used Functions:
  • report_sm_xapp_api()

Design the KPM subscription logic to produce the subscription request data in accordance with the format specified in O-RAN.WG3.E2SM-KPM-v02.00.03 (7.4.5 REPORT Service Style 4: Common condition-based, UE-level Measurement).

• Event: gen_ev_trig()

  • Input:

  Parameter	Type in C	Comment
  period	uint64_t	Periodic timer

  • Output:

  Parameter	Type in C	Comment
  kpm_sub.ev_trg_def	kpm_event_trigger_def_t	KPM event trigger structure

  • Example:

  // Read period timer from configuration file
  uint64_t period_ms = args.sub_oran_sm[j].time;
  
  kpm_sub.ev_trg_def = gen_ev_trig(period_ms);

  Note: The function gen_ev_trig support only E2SM-KPM Event Trigger Definition Format 1 (Section 8.2.1.1.1)

  Section 8.2.1.1.1

  Reporting Period, Mandatory

• Action definition: gen_act_def()

  • Input:

    Parameter	Type in C	Comment
    action	sub_oran_sm_t	KPM configuration action name and id
    act_frm	format_action_def_e	KPM format action definition
    period_ms	uint32_t	Collection interval of measurements
    cell_id	size_t	Cell id extracted from RC sub for handover

  • Output:

    Parameter	Type in C	Comment
    kpm_sub.ad.ad	kpm_act_def_t	KPM action definition structure

  • Example:

  // Loop current cell extracted from RC sub
  for(int cell_idx = 0; cell_idx < num_cells; cell_idx++) {
    // Loop configuration subscription action id and name
    for (int32_t j = 0; j < args.sub_oran_sm_len; j++) {
      // Define action type based on certain report style
      // Action format 4 is for UE level measurement style 
      act_type = FORMAT_4_ACTION_DEFINITION;
    
      // Read period timer from configuration file
      uint64_t period_ms = args.sub_oran_sm[j].time;
  
      *kpm_sub.ad = gen_act_def((const sub_oran_sm_t)args.sub_oran_sm[j], act_type, period_ms, cell_idx);
    }
  }

  Note: The function gen_act_def() calls gen_act_def_frmt_4() to fill the required parameters n according to Section 8.2.1.2.4 (E2SM-KPM Action Definition Format 4) of the O-RAN.WG3.E2SM-KPM-v02.00.03 specification, adhering to the kpm_act_def_t structure.

  Section 8.2.1.2.4:

  Matching Condition, Optional 
  > Test information, Mandatory 
  > Logical OR, Optional
  Subscription Information, Mandatory 

---

Periodic event

• Used Function
  • sm_cb_{SM-NAME}()
    • sm_cb_kpm()

Note: This function is designed to receive indication messages from the KPM service model with the objective of monitoring UEs across various cells. Additionally, by examining the sm_cb_kpm(), it becomes possible to determine the specific UE and its associated cell.

For example: We create two callback functions for two cells measuring UE information inside each cell

// Call back function for cell 0 in LST_NR_CELL_ID
// If Current UE active in cell 0 => sm_cb_kpm_1 will be called from e2 agent 
// Otherwise, sm_cb_kpm1 will not be called
static
void sm_cb_kpm_1(sm_ag_if_rd_t const* rd, global_e2_node_id_t const* e2_node){
 assert(rd != NULL);
 assert(e2_node != NULL);
 assert(rd->type == INDICATION_MSG_AGENT_IF_ANS_V0);
 assert(rd->ind.type == KPM_STATS_V3_0);
 printf("\nKPM CB - NR Cell ID %ld\n", LST_NR_CELL_ID[0]);
 print_kpm_ind(rd, e2_node);
}

---

RC control request

Develop your xApp logic to generate control request data following the structure outlined in O-RAN.WG3.E3SM-RC-v01.03 (8.4.4.1 Handover control).

- Header: `gen_rc_ctrl_hdr()`
  Input:

  | Parameter        | Type in C            | Comment                                                      |
  |------------------|----------------------|--------------------------------------------------------------|
  | `hdr_frm`        | `e2sm_rc_ctrl_hdr_e` | Format of header for RIC Control Request                     |
  | `ue_id`          | `ue_id_e2sm_t`       | UE ID used on E2 interface (6.2.2.6, O-RAN.WG3.E3SM-v02.01)  |
  | `ric_style_type` | `uint32_t`           | Control service style type (7.6.1, O-RAN.WG3.E3SM-RC-v01.03) |
  | `ctrl_act_id`    | `uint16_t`           | Control action ID ((7.6.2.1, O-RAN.WG3.E3SM-RC-v01.03)       |

    - Output:

      | Parameter     | Type in C            | Comment                       |
      |---------------|----------------------|-------------------------------|
      | `rc_ctrl.hdr` | `e2sm_rc_ctrl_hdr_t` | Header of RIC Control Request |

    - Example:
  ```c
  // Define a RC control reuqest data
  rc_ctrl_req_data_t rc_ctrl = {0};
  
  // Define header's format
  e2sm_rc_ctrl_hdr_e hdr_frm = FORMAT_1_E2SM_RC_CTRL_HDR

  // Generate UE ID, utilized by the RAN function to identify the UE to be controlled
  ue_id_e2sm_t ue_id = gen_rc_ue_id(GNB_UE_ID_E2SM);
  
  // Define control service style type
  // Note: 3 is mapped to Connected Mode Mobility Control
  uint32_t ric_style_type = 3;
  
  // Define control action ID
  // Note: 6 is mapped to handover control
  uint16_t ctrl_act_id = 1;

  rc_ctrl.hdr = gen_rc_ctrl_hdr(hdr_frm, ue_id, ric_style_type, ctrl_act_id);
  ```

• Message: gen_rc_ctrl_msg()

  • Input:

    Parameter	Type in C	Comment
    msg_frm	e2sm_rc_ctrl_msg_e	Format of message for RIC Control Request

  • Output:

    Parameter	Type in C	Comment
    rc_ctrl.msg	e2sm_rc_ctrl_msg_t	Message of RIC Control Request

  • Example:

  rc_ctrl.msg = gen_rc_ctrl_msg(FORMAT_1_E2SM_RC_CTRL_MSG);

  Note: The function gen_rc_ctrl_msg() calls gen_rc_ctrl_msg_frmt_1_slice_level_PRB_quota() to fill the required parameters n accordance with Section 8.4.4.1 (Handover control) of the O-RAN.WG3.E3SM-RC-v01.03 specification, adhering to the e2sm_rc_ctrl_msg_frmt_1_t structure.

  Section 8.4.4.1:

  Target Primary Cell ID, STRUCTURE (len 1)
  > CHOICE Target Cell, STRUCTURE (len 2)
  >>  NR Cell, STRUCTURE (len 1)
  >>> NR CGI, ELEMENT(len 1)
  >>  E-ULTRA Cell, STRUCTURE (len 1)
  >>> E-ULTRA CGI, ELEMENT