Osmocom Libraries » libosmocore

As presented in the OsmoDevCon 2024, I am documenting my GSMTAPv3 proposal. I will start from structural definitions and the C APIs will be following in the later time.

GSMTAPv3 will consist of global header and type-specific header. The former consists of all required metadata and the latter consists of information required/related to the selected PDU type.

Global Header¶

Each packets are starting with the following global header.

/* GSMTAPv2 incompatible, bigger header space */
struct gsmtap_hdr_v3 {
  uint8_t version;         /* set to 0x03 */
  uint16_t hdr_len;        /* number of 32bit words including TLVs */
  uint8_t reserved;        /* should not be interpreted by the implementation */

  uint16_t type;           /* type of the PDU, see below */
  uint16_t sub_type;

  uint8_t metadata[0];     /* type-specific metadata structure */
}

/* GSMTAPv2 compatible, but header is limited to 1024 bytes */
struct gsmtap_hdr_v3 {
  uint8_t version;         /* set to 0x03 */
  uint8_t hdr_len;         /* number of 32bit words including TLVs */
  uint8_t protective_type; /* set to 0xff for GSMTAPv2 compatibility */
  uint8_t reserved;        /* should not be interpreted by the implementation */

  uint16_t type;           /* type of the PDU, see below */
  uint16_t sub_type;

  uint8_t metadata[0];     /* type-specific metadata structure */
}

Types are grouped by the first octet, and the second octet indicates each individual type. Constants in the parenthesis are equivalent type of the GSMTAPv2.

• 0x00: Common and non-3GPP Protocols
  • 0x00: Osmocore logging (GSMTAP_TYPE_OSMOCORE_LOG)
  • 0x01: ISO 7816 Smartcard (GSMTAP_TYPE_SIM)
  • 0x02: Baseband diagnostic frames (GSMTAP_TYPE_QC_DIAG, but not limited to the Qualcomm)
  • 0x03: TETRA I1 (GSMTAP_TYPE_TETRA_I1)
  • 0x04: TETRA I1 Burst (GSMTAP_TYPE_TETRA_I1_BURST)
  • 0x05: WiMAX Burst (GSMTAP_TYPE_WMX_BURST)
  • 0x06: GMR1 Um (GSMTAP_TYPE_GMR1_UM)
  • 0x07: E1/T1 (GSMTAP_TYPE_E1T1)
• 0x01: Same as 0x00, Reserved for future usage
• 0x02: GSM
  • 0x00: Um (GSMTAP_TYPE_UM, 04.07)
  • 0x01: Um Burst (GSMTAP_TYPE_UM_BURST)
  • 0x02: Gb RLC/MAC (44.060)
  • 0x03: Gb LLC (GSMTAP_TYPE_GB_LLC, 44.064)
  • 0x04: Gb SNDCP (GSMTAP_TYPE_GB_SNDCP, 44.065)
  • 0x05: Abis (GSMTAP_TYPE_ABIS, 24.008)
  • 0x06: RLP (GSMTAP_TYPE_GSM_RLP, 24.022)
• 0x03: WCDMA
  • 0x00: MAC (25.321)
  • 0x01: RLC (25.322)
  • 0x02: PDCP (25.323)
  • 0x03: RRC (GSMTAP_TYPE_UMTS_RRC, 25.331)
  • 0x04: NAS (24.008)
• 0x04: LTE
  • 0x00: MAC (GSMTAP_TYPE_LTE_MAC, 36.321)
  • 0x01: RLC (36.322)
  • 0x02: PDCP (36.323)
  • 0x03: RRC (GSMTAP_TYPE_LTE_RRC, 36.331)
  • 0x04: NAS (GSMTAP_TYPE_LTE_NAS, 24.301)
• 0x05: NR
  • 0x00: MAC (38.321)
  • 0x01: RLC (38.322)
  • 0x02: PDCP (38.323)
  • 0x03: RRC (38.331)
  • 0x04: NAS (24.501)

Type-specific Metadata¶

Each metadata is stored through T16L16V format. Following classes of metadata are considered.

• Network frequency and cell information
  • Channel number – ARFCN, UARFCN, EARFCN, NR-ARFCN
  • Band indicator (usually numbers overlap except GSM)
  • BSIC, PSC, PCI
• Ciphering and integrity protection key
  • K_NASint, K_NASenc, K_RRCint, K_RRCenc, K_UPenc, K_UPint
  • Attached key is assumed valid until a new key is attached
  • May have different length according to the generation
• Additional context information
  • Generation time, device name, etc.
  • Packet timestamp
  • Packet comment
• Signal status
  • e.g. signal_dbm, snr_db, antenna_nr
  • RSSI, RSRP, RSRQ, SINR, MIMO type, etc
  • Synchronous on base station, asynchronous on UE

Some metadata must be provided to ensure proper decoding of the included PDU (e.g. RRC channel type, MAC/RLC/PDCP context). If some mandatory data is not available it is required to indicate it as a separate value than zero. The exact definition of the mandatory data depends on the PDU type.

Other Design Points¶

• Segmentation is handled through IP.