Software platform and coding structure

The OAI software is obtained from EURECOM’s GitLab server [EUR17b], which is also where most of the information regarding the platform is, i.e. tutorials and frequently asked questions. It is divided in several branches, with master and develop being the most used. The master branch contains a stable version of the code, usually a few months old, while the develop branch contains a weekly updated version of the code, proving to be unstable at times. To retrieve the source code, a Git client is required. The installation process will be fully described in Appendix C.

In order to be able to contribute and commit code to the Git repository, one has to be added as a developer first. Then, if the defined coding guidelines were respected, a merge request can be submitted. Each Friday, a temporary integration branch is created, where all the potential commits are merged. After running a series of tests, they will either be accepted and pushed into the develop branch, or rejected and excluded from the integration branch.

The community is very active. The way for everyone to communicate is through mailing lists. The questions are visible to all subscribers, which is great for problem solving and solution sharing. Considering that the information regarding OAI is scattered all over its websites, or sometimes not updated or existent at all, it is of the utmost importance to be subscribed to the mailing list.

Because of the licensing model, the OAI source code is divided in two different reposito- ries, openairinterface5g (eNB/UE RAN) and openair-cn (EPC), detailed in the following sections 3.3.1.1 and 3.3.1.2.

3.3.1.1 openairinterface5g

The source code for the eNB and UE radio access networks can be found in openairinterface5g and the functional units it implements are shown in Figure 3.3. Initially, the UE belonged to a different project, openair1B, which aimed to build a OAI UE with basic functionalities (fully integrated and stable with OAI eNB and EPC). It was merged with the openairinterface5g after its completion, in December 2016.

Figure 3.3: Functional units implemented by openairinterface5g The structure of the source code is organized as follows [EUR17b]:

ˆ cmake targets: Build utilities to compile (simulation, emulation and real-time plat- forms) and generated build files. It contains the “mother” build oai script, used to build the eNB and UE softmodems.

ˆ targets: eNB and UE top-level wrapper for use with/without hardware in emulated and real-time modes. It is also where the hardware specific code is located (drivers, tools, etc.).

ˆ openair1: Basic DSP routines for implementing a subset of Release 12 LTE specifica- tions. It contains the PHY layer and PHY abstraction software.

ˆ openair2: RLC, MAC, PDCP, RRC and X2AP implementations. ˆ openair3: S1AP, NAS and GTPV1-U, for both eNB and UE.

ˆ common/utils: Some common utilities, such as the InTer-Task Interface (ITTI). The E-UTRAN is configurable for a wide array of parameters according to the user’s needs, like the E-UTRA band of the transceiver, its downlink/uplink frequency, number of resource blocks, number of antennas, duplex modes, power control and so on. For the eNB, this is achievable through the use of configuration files, available in Appendix C. The OAI UE doesn’t have a configuration file per se, meticulous modifications have to be made in several files. The whole process is also explained in Appendix C, a guide on how to install and run the OAI platform detailing all the steps and changes required for the platform to work.

eNB configuration The parameter configuration file for the eNB (in Appendix C) is di- vided in six main sections:

ˆ Main parameters: Configuration of the base station identity, TAC, MCC and MNC. ˆ PHY parameters: Configuration of the physical layer parameters - E-UTRA band, downlink/uplink frequency, power control, number of TX/RX antennas, TX/RX gain, hopping, frame type and so on.

ˆ Special Radio Bearer (SRB) parameters: Configuration of special radio bearers parameters - poll retransmission timer, reordering timer, etc..

ˆ MME parameters: Configuration of MME parameters - IPv4/IPv6 addressing. ˆ Network interfaces: Configuration of network interfaces - eNB S1-U IPv4 address,

eNB S1-MME IPv4 address and the interface names.

ˆ Log configuration: Choosing logger’s level and verbosity on the terminal by taking into account all the layers and components of the network - hardware (HW), PHY, MAC, RLC, PDCP and RRC.

Only one configuration file can be used when running the eNB wrapper. After configu- ration, the eNB is ready to be built and executed. The UE configuration will be described next.

UE configuration The parameter configurations for the OAI UE (in Appendix C) are scattered through several files, which all come together in the building process. The two most important files are related to the NAS protocol. One of them defines all the Public Land Mobile Network (PLMN) network operators the UE will be able to recognize. The other is an USIM card data generator, which allows the user to define the OAI UE’s simulated user and USIM card parameters, such as the IMEI, K and OPc, as well as a selection of known PLMNs from the previously described file.

Some other parameters are fed to the UE when executing the wrapper on a Linux terminal. These include the frequency band it’s going to operate in, duplex mode (TDD or FDD), number of resource blocks, transmission and reception gain and so forth.

This completes the E-UTRAN software implementation description. The EPC will be described next.

3.3.1.2 openair-cn

openair-cn provides the source code for the core network entities S-GW, P-GW, HSS and MME. S-GW and P-GW are actually combined in a single entity, commonly named SPGW. Each entity runs as their own process and each procedure or protocol is run as a thread in these processes [Mar16].

The communication in MME and SPGW is made by means of ITTI, an intra-process com- munication system for message passing [Flo17]. Each interface adapter or protocol instance is assigned its own task and each task is woken up by events (messages, timers). HSS uses a threading architecture provided by the Diameter library, instead.

Each EPC network entity and its configuration in OAI will be discussed in the following sections.

HSS configuration HSS contains a database and a S6a thread. Prior to building the HSS, MySQL needs to be installed, so the network subscribers information can be programmed into a database, including the IMSI, IMEI, Mobile Station International Subscriber Directory Number (MSISDN), K, OPc and APN. This represents the AuC. Any user that tries to register to the network and whose information is not in the database will automatically be rejected.

freeDiameter [fre11] is also installed. It is an open-source Diameter implementation and it is used for S6a signalling.

Two main configuration files are required, one for MySQL and the other for freeDiameter. The first file is used to configure the MySQL server address, user name, password chosen during the installation process and name of the database where the network subscribers’ information will be stored. The second provides the parameters needed for the Diameter protocol, such as the Fully Qualified Domain Name (FQDN) and the location of some required TLS1certificates.

MME configuration Just like HSS, MME also runs a S6a thread that uses freeDiameter. The main configuration file is divided in two sections, MME and S-GW. As the P-GW and S-GW selections are not implemented yet, a mechanism is needed to replace it. Currently, only one PDN, one P-GW and one S-GW are supported. So, a S-GW IPv4 address for the S11 interface is assigned directly in the configuration file.

MME’s main section allows for customization of the Diameter realm of the MME, the maximum number of operating eNBs or UEs, if the Emergency Attach is supported, etc.. Other sections include choosing the message queue size for ITTI, the S1AP outcome timer, the Globally Unique MME Identifier (GUMMEI) and TAI configuration parameters, the NAS integrity and ciphering algorithms preference order, the network interfaces for S1-C and S11 and logging configuration.

SPGW configuration As the S-GW and P-GW nodes are combined, the interfaces S5/S8 supposed to connect the two aren’t used. SPGW makes use of the GTP module provided by Osmocom.

The SPGW configuration file is divided into S-GW and P-GW. The first allows for con- figuration of the network interfaces for S11 and S1-U, ITTI message queue size and logging options. The latter allows for customization of DNS addresses, SGi network interface, a pool of IP addresses available for UEs and if the outgoing UE traffic should be masqueraded - Source Network Address Translation (SNAT).

Now that the software platform was described, the hardware requirements to run OAI will be discussed.