Custom Service Models

Custom Service Models

MAC

This SM has data related to the MAC 5G sublayer. Concretely, the following parameters are provided per UE:

  uint64_t dl_aggr_tbs; // Downlink (DL) aggregated Transport Block size
  uint64_t ul_aggr_tbs; // Uplink (UL) aggregated Transport Block size
  uint64_t dl_aggr_bytes_sdus;
  uint64_t ul_aggr_bytes_sdus;
  uint64_t dl_curr_tbs; // DL current Transport Block size
  uint64_t ul_curr_tbs;
  uint64_t dl_sched_rb; // DL Scheduled Resource blocks
  uint64_t ul_sched_rb;
 
  float pusch_snr; // PUSCH SNR
  float pucch_snr; // PUCCH SNR
  float dl_bler; // DL bler
  float ul_bler; // UL bler
  uint32_t dl_harq[5]; 
  uint32_t ul_harq[5];
  uint32_t dl_num_harq;
  uint32_t ul_num_harq;

  uint32_t rnti; // Radio Network Temporary Identifier 
  uint32_t dl_aggr_prb; // DL Aggregated PRBs
  uint32_t ul_aggr_prb;
  uint32_t dl_aggr_sdus; // DL aggregated SDUs
  uint32_t ul_aggr_sdus;
  uint32_t dl_aggr_retx_prb; // DL aggregated retransmitted PRB 
  uint32_t ul_aggr_retx_prb;

  uint32_t bsr; // Buffer Status Report
  uint16_t frame; // Last frame number
  uint16_t slot; // Last slot number

  uint8_t wb_cqi; // Wideband Channel Quality Indicator 
  uint8_t dl_mcs1; // MCS1 PT-RS
  uint8_t ul_mcs1; 
  uint8_t dl_mcs2; 
  uint8_t ul_mcs2; 
  int8_t phr; // Power Head Room

RLC

This SM has data related to the RLC 5G sublayer. Concretely, the following parameters are provided per UE:

  /* PDU stats */
  /* TX */
  uint32_t txpdu_pkts;         /* aggregated number of transmitted RLC PDUs */
  uint32_t txpdu_bytes;        /* aggregated amount of transmitted bytes in RLC PDUs */
  uint32_t txpdu_wt_ms;        /* TODO: aggregated head-of-line tx packet waiting time to be transmitted (i.e. send to the MAC layer) */
  uint32_t txpdu_dd_pkts;      /* aggregated number of dropped or discarded tx packets by RLC */
  uint32_t txpdu_dd_bytes;     /* aggregated amount of bytes dropped or discarded tx packets by RLC */
  uint32_t txpdu_retx_pkts;    /* aggregated number of tx pdus/pkts to be re-transmitted (only applicable to RLC AM) */
  uint32_t txpdu_retx_bytes;   /* aggregated amount of bytes to be re-transmitted (only applicable to RLC AM) */
  uint32_t txpdu_segmented;    /* aggregated number of segmentations */
  uint32_t txpdu_status_pkts;  /* aggregated number of tx status pdus/pkts (only applicable to RLC AM) */
  uint32_t txpdu_status_bytes; /* aggregated amount of tx status bytes  (only applicable to RLC AM) */
  uint32_t txbuf_occ_bytes;    /* (IMPLEMENTED) transmitting bytes currently in buffer */
  uint32_t txbuf_occ_pkts;     /* TODO: current tx buffer occupancy in terms of number of packets (average: NOT IMPLEMENTED) */

  /* txbuf_wd_ms: the time window for which the txbuf  occupancy value is obtained - NOT IMPLEMENTED */

  /* RX */
  uint32_t rxpdu_pkts;         /* aggregated number of received RLC PDUs */
  uint32_t rxpdu_bytes;        /* amount of bytes received by the RLC */
  uint32_t rxpdu_dup_pkts;     /* aggregated number of duplicate packets */
  uint32_t rxpdu_dup_bytes;    /* aggregated amount of duplicated bytes */
  uint32_t rxpdu_dd_pkts;      /* aggregated number of rx packets dropped or discarded by RLC */
  uint32_t rxpdu_dd_bytes;     /* aggregated amount of rx bytes dropped or discarded by RLC */
  uint32_t rxpdu_ow_pkts;      /* aggregated number of out of window received RLC pdu */
  uint32_t rxpdu_ow_bytes;     /* aggregated number of out of window bytes received RLC pdu */
  uint32_t rxpdu_status_pkts;  /* aggregated number of rx status pdus/pkts (only applicable to RLC AM) */
  uint32_t rxpdu_status_bytes; /* aggregated amount of rx status bytes  (only applicable to RLC AM) */
  /* rxpdu_rotout_ms: flag indicating rx reordering  timeout in ms - NOT IMPLEMENTED */
  /* rxpdu_potout_ms: flag indicating the poll retransmit time out in ms - NOT IMPLEMENTED */
  /* rxpdu_sptout_ms: flag indicating status prohibit timeout in ms - NOT IMPLEMENTED */
  uint32_t rxbuf_occ_bytes;    /* (IMPLEMENTED) received bytes currently in buffer */
  uint32_t rxbuf_occ_pkts;     /* TODO: current rx buffer occupancy in terms of number of packets (average: NOT IMPLEMENTED) */

  /* SDU stats */
  /* TX */
  uint32_t txsdu_pkts;         /* number of SDUs delivered */
  uint64_t txsdu_bytes;        /* (UPDATED) number of SDUs bytes successfully transmitted so far (counter) */
  /* Average time for an SDU to be passed to MAC:
   * Actually measures the time it takes for THE FULL SDU to be passed to MAC FOR THE FIRST TIME.
   * Since the MAC schedules in advance, it does not measure the time of
   * transmission over the air, just the time to reach the MAC layer.
   * => to control it, 'txsdu_hol_waittime' that measures the current HOL-delay is added.
   */
  double txsdu_avg_time_to_tx; /* (100ms-windowed) per-packet sojourn (SDU to PDU) in microseconds */
  uint32_t txsdu_wt_us;        /* HOL delay of the current radio bearer, in microseconds */

  /* RX */
  uint32_t rxsdu_pkts;         /* number of SDUs received */
  uint64_t rxsdu_bytes;        /* (UPDATED) number of SDUs bytes arrived so far (counter) */
  uint32_t rxsdu_dd_pkts;      /* number of dropped or discarded SDUs */
  uint32_t rxsdu_dd_bytes;     /* number of bytes of SDUs dropped or discarded */

  uint32_t rnti;
  uint8_t mode;               /* 0: RLC AM, 1: RLC UM, 2: RLC TM */
  uint8_t rbid; // Radio Bearer ID

PDCP

This SM has data related to the PDCP 5G sublayer. Concretely, the following parameters are provided per UE:

  uint32_t txpdu_pkts;     /* aggregated number of tx packets */
  uint32_t txpdu_bytes;    /* aggregated bytes of tx packets */
  uint32_t txpdu_sn;       /* current sequence number of last tx packet (or TX_NEXT) */
  uint32_t rxpdu_pkts;     /* aggregated number of rx packets */
  uint32_t rxpdu_bytes;    /* aggregated bytes of rx packets */
  uint32_t rxpdu_sn;       /* current sequence number of last rx packet (or  RX_NEXT) */
  uint32_t rxpdu_oo_pkts;       /* aggregated number of out-of-order rx pkts  (or RX_REORD) */
  uint32_t rxpdu_oo_bytes; /* aggregated amount of out-of-order rx bytes */
  uint32_t rxpdu_dd_pkts;  /* aggregated number of duplicated discarded packets */
  uint32_t rxpdu_dd_bytes; /* aggregated amount of discarded packets' bytes */
  uint32_t rxpdu_ro_count; /* this state variable indicates the COUNT value */
  uint32_t txsdu_pkts;     /* number of SDUs delivered */
  uint32_t txsdu_bytes;    /* number of bytes of SDUs delivered */
  uint32_t rxsdu_pkts;     /* number of SDUs received */
  uint32_t rxsdu_bytes;    /* number of bytes of SDUs received */
  uint32_t rnti;
  uint8_t  mode;               /* 0: PDCP AM, 1: PDCP UM, 2: PDCP TM */
  uint8_t  rbid;

GTP

This SM has data related to the GTP interface in 5G. Concretely, the following parameters are provided per UE:

  // ngu tunnel stats
  uint32_t rnti; // user id
  uint32_t teidgnb; // tunnel id from gnb
  uint32_t teidupf; // tunnel id from upf
  uint8_t qfi; // QoS flow indicator

SLICE

This SM provides data related to RAN slicing for radio resources in the 5G MAC sublayer. For RAN slicing, we adopt the concept of a two-level MAC scheduling framework to implement the 5G MAC scheduler on top of OpenAirInterface (OAI). The MAC scheduler operates in two levels:

• Slice-level scheduler allocates radio resources across different slices (e.g., DRBs).
• UE-level scheduler allocates radio resources across UEs within the same slice.

Concretely, the following parameters are provided:

• Indication message

  // Slice sm indication message
  typedef struct {
    slice_conf_t slice_conf;       // Slice configuration in the 5G MAC sublayer
    ue_slice_conf_t ue_slice_conf; // UE-to-slice association information
    int64_t tstamp;                // Timestamp (µs)
  } slice_ind_msg_t;

• Control message

  // Slice sm control message
  typedef struct {
    slice_ctrl_msg_e type; // Control message type
    slice_ctrl_msg_u u;    // Configuration for the selected control type
  } slice_ctrl_msg_t;
  
  // Slice control message type
  typedef enum{
    SLICE_CTRL_SM_V0_ADD,              // Add or modify a slice configuration
    SLICE_CTRL_SM_V0_DEL,              // Delete a slice configuration
    SLICE_CTRL_SM_V0_UE_SLICE_ASSOC,   // Associate a UE with slice(s)
    SLICE_CTRL_SM_V0_UE_SLICE_DEASSOC, // De-associate a UE from slice(s)
  
    SLICE_CTRL_SM_V0_END
  } slice_ctrl_msg_e;
  
  // Configuration for the selected control type
  typedef union{
    slice_conf_t add_mod_slice;  // Slice configuration to add or modify
    del_slice_conf_t del_slice;  // Slice deletion configuration
    ue_slice_conf_t ue_slice;    // UE-to-slice (de)association configuration
  } slice_ctrl_msg_u;

• Slice configuration (to add or modify) in the 5G MAC sublayer

  // Slice configuration in the 5G MAC sublayer
  typedef struct {
    ul_dl_slice_conf_t dl;   // Downlink slice configuration
    ul_dl_slice_conf_t ul;   // Uplink slice configuration
  } slice_conf_t;

  // Uplink/Downlink slice configuration
  typedef struct{
    uint32_t len_slices;     // Number of configured slices
    fr_slice_t* slices;      // Array of slice configurations
  
    uint32_t len_sched_name; // Length of the slice-level scheduling algorithm name
    char* sched_name;        // Slice-level scheduling algorithm name (e.g., NVS, EDF, eEDF, PR, ePR)
  } ul_dl_slice_conf_t ;

  // Per-slice configuration
  typedef struct{
    uint32_t id;           // Slice identifier
  
    uint32_t len_label;    // Length of the slice label string
    char* label;           // Slice lable
  
    uint32_t len_sched;    // Length of the UE-level scheduling algorithm name
    char* sched;           // UE-level scheduling algorithm name (e.g, PF)
  
    slice_params_t params; // Slice configuration parameters
  } fr_slice_t;

  // Slice configuation parameters
  typedef struct{
    slice_algorithm_e type; // Slice-level scheduling algorithm type (enum)
    slice_params_u u;       // Parameters for the selected slice-level scheduling algorithm
  } slice_params_t;
  
  // Slice-level scheduling algorithm type
  typedef enum{
    SLICE_ALG_SM_V0_NONE = 0,    // Default algorithm (no slicing)
    SLICE_ALG_SM_V0_STATIC = 1,  // Static slicing algorithm (not supported in OAI 5G)
    SLICE_ALG_SM_V0_NVS = 2,     // Network Virtualization Substrate (NVS) algorithm
                                 // Ref: https://ieeexplore.ieee.org/document/6117098
    SLICE_ALG_SM_V0_SCN19 = 3,   // SCN19 algorithm (extension of NVS, not supported in OAI 5G)
                                 // Ref: https://ieeexplore.ieee.org/document/9349762 
    SLICE_ALG_SM_V0_EDF = 4,     // Early Deadline First (EDF) algorithm
                                 // Ref: https://ieeexplore.ieee.org/document/8624268
    SLICE_ALG_SM_V0_EEDF = 5,    // Enhanced Early Deadline First (eEDF) algorithm
    SLICE_ALG_SM_V0_PR = 6,      // Policy-Ratio algorithm (based on 3GPP TS 28.541 RRM Policy Ratio)
    SLICE_ALG_SM_V0_EPR = 7,     // Enhanced Policy-Ratio (ePR) algorithm
  
    SLICE_ALG_SM_V0_END
  } slice_algorithm_e;
  
  // Parameters for the selected slice-level scheduling algorithm
  typedef union{
    static_slice_t sta;
    nvs_slice_t nvs;
    scn19_slice_t scn19;
    edf_slice_t edf;
    eedf_slice_t eedf;
    pr_slice_t pr;
    pr_slice_t epr;
  } slice_params_u;

  The following describes the detailed parameters of the slice-level scheduling algorithms supported by the BubbleRAN OAI 5G MAC scheduler:

  • NVS algorithm

    // NVS algorithm parameters
    typedef struct{
      nvs_slice_conf_e conf; // NVS slice configuration type
      nvs_slice_u u;         // Parameters for the selected configuration type
    } nvs_slice_t ;
    
    // NVS slice configuration type
    typedef enum {
      SLICE_SM_NVS_V0_RATE,     // NVS - Rate: reserves a minimum rate (mbps_required) relative to a reference rate (mbps_reference).
                                // Ensures minimum throughput but may limit resource use under poor channel conditions.
      SLICE_SM_NVS_V0_CAPACITY, // NVS - Capacity: reserves a fixed share (pct_reserved) of the total available resources.
                                // Guarantees a proportion of resources regardless of rate.
    
      SLICE_SM_NVS_V0_END
    } nvs_slice_conf_e;
    
    // Parameters for the selected configuration type
    typedef union{
      nvs_rate_t rate;          // Parameters for NVS - Rate
      nvs_capacity_t capacity;  // Parameters for NVS - Capacity
    } nvs_slice_u;
    
    // Parameters for NVS - Rate
    typedef struct{
      nvs_rate_req_u u1;  // First parameter for NVS - Rate
      nvs_rate_ref_u u2;  // Second parameter for NVS - Rate
    } nvs_rate_t; 
    
    // First parameter for NVS - Rate
    typedef union {
      float mbps_required; // minimum rate
    } nvs_rate_req_u;
    
    // Second parameter for NVS - Rate
    typedef union {
      float mbps_reference; // reference rate
    } nvs_rate_ref_u;
    
    // Parameters for NVS - Capacity
    typedef union{
      float pct_reserved;
    } nvs_capacity_u;

  • EDF algorithm

    // EDF algorithm parameters
    typedef struct{
      // Basic procedure
      int32_t deadline;        // Scheduled deadline (in time slots / TTI units)
      int32_t guaranteed_prbs; // Guaranteed quota of Physical Resource Blocks (PRBs) within the deadline
    } edf_slice_t ;

  • eEDF algorithm

    // eEDF algorithm parameters
    typedef struct{
      eedf_slice_conf_e conf; // eEDF slice configuration type
      eedf_slice2_t u;        // Parameters for the selected configuration type
    } eedf_slice_t ;
    
    // eEDF slice configuration type
    typedef enum {
      SLICE_SM_EEDF_V0_STATIC, // eEDF - Static: reserves a fixed number of PRBs
      SLICE_SM_EEDF_V0_RATE,   // eEDF - Rate: guarantees a minimum rate within a deadline
    
      SLICE_SM_EEDF_V0_END
    } eedf_slice_conf_e;
    
    // Parameters for the selected configuration type
    typedef union{
      eedf_static_t fixed; // Parameters for eEDF - Static
      eedf_rate_t rate;    // Parameters for eEDF - Rate
    } eedf_slice2_t;
    
    // Parameters for eEDF - Static
    typedef struct{
      int16_t reserved_prbs;            // Number of PRBs reserved for the slice
      eedf_static_type_t reserved_type; // Reservation policy: HARD or SOFT
    } eedf_static_t;
    
    // Type for eEDF - Static
    typedef enum {
      EEDF_STATIC_HARD, // PRBs are always reserved, even if the slice has no data
      EEDF_STATIC_SOFT, // PRBs are released if the slice has no data to transmit
    
      END_EEDF_STATIC
    } eedf_static_type_t;
    
    // Parameters for eEDF - Rate
    typedef struct{
      int32_t deadline;         // Scheduled deadline (in time slots / TTI units)
      int32_t guaranteed_rate;  // Guaranteed rate to be achieved within the deadline
    } eedf_rate_t;

  • PR and ePR algorithm

    // PR and ePR algorithm parameters
    typedef struct{
      uint8_t max_ratio;           // RRMPolicyMaxRatio (dedicated + prioritized + shared):
                                   // upper bound of the total resource share
      uint8_t min_ratio;           // RRMPolicyMinRatio (dedicated + prioritized):
                                   // minimum guaranteed resource share
      uint8_t dedicated_ratio;     // RRMPolicyDedicatedRatio (dedicated only, non-shareable):
                                   // strictly reserved resource share
    } pr_slice_t;

• UE-to-slice (de)association information/configuration

  // UE-to-slice (de)association information/configuration
  typedef struct {
    uint32_t          len_ue_slice; // Number of connected UEs
    ue_slice_assoc_t* ues;          // Array of UE-to-slice (de)association entries
  } ue_slice_conf_t;
  
  // UE-to-slice association entry
  typedef struct {
    uint32_t   len_dl;   // Number of (de)associated downlink slices
    uint32_t*  dl_id;    // Array of (de)associated downlink slice identifiers
    uint32_t   ul_id;    // (De)Associated uplink slice identifier
    uint16_t   rnti;     // UE's Radio Network Temporary Identifier (RNTI)
  } ue_slice_assoc_t;

• Slice deletion configuration

  // Slice deletion configuration
  typedef struct{
    uint32_t len_dl;     // Number of downlink slices
    uint32_t* dl;        // Array of donwlink slice to be deleted
    uint32_t len_ul;     // Number of uplink slices
    uint32_t* ul;        // Array of uplink slice to be deleted
  } del_slice_conf_t;

ISAC

This SM has data related to ISAC SM. Concretely, the following parameters are provided:

typedef struct {
  int64_t tstamp;
  uint64_t len_srs_iq; // amount of I/Q samples
  // Flexible Array Member
  int16_t srs_iq[]; // Estimated SRS IQ samples 
} isac_ind_msg_t;

TC

This SM is experimental for the moment.