.. include:: replace.txt

Wimax NetDevice

---------------

This chapter describes the |ns3| WimaxNetDevice and related models. By

adding WimaxNetDevice objects to |ns3| nodes, one can create models of

802.16-based networks. Below, we list some more details about what

the |ns3| WiMAX models cover but, in summary, the most important features

of the |ns3| model are:

* a scalable and realistic physical layer and channel model 

* a packet classifier for the IP convergence sublayer

* efficient uplink and downlink schedulers

* support for Multicast and Broadcast Service (MBS), and

* packet tracing functionality

The source code for the WiMAX models lives in the directory

``src/devices/wimax``.

There have been two academic papers published on this model:

* M.A. Ismail, G. Piro, L.A. Grieco, and T. Turletti, "An Improved IEEE 802.16

  WiMAX Module for the NS-3 Simulator", SIMUTools 2010 Conference, March 2010.

* J. Farooq and T. Turletti, "An IEEE 802.16 WiMAX module for the NS-3

  Simulator," SIMUTools 2009 Conference, March 2009. 

Scope of the model

******************

From a MAC perspective, there are two basic modes of operation, that of a

Subscriber Station (SS) or a Base Station (BS). These are implemented as two

subclasses of the base class :cpp:class:`ns3::NetDevice`, class

:cpp:class:`SubscriberStationNetDevice` and class

:cpp:class:`BaseStationNetDevice`. As is typical in |ns3|, there is also a

physical layer class :cpp:class:`WimaxPhy` and a channel class

:cpp:class:`WimaxChannel` which serves to hold the references to all of the

attached Phy devices. The main physical layer class is the

:cpp:class:`SimpleOfdmWimaxChannel` class.

Another important aspect of WiMAX is the uplink and downlink scheduler, and

there are three primary scheduler types implemented:

* SIMPLE:  a simple priority based FCFS scheduler

* RTPS:  a real-time polling service (rtPS) scheduler

* MBQOS:  a migration-based uplink scheduler

The following additional aspects of the 802.16 specifications, as well as

physical layer and channel models, are modelled:

* leverages existing |ns3| wireless propagation loss and delay models, as well

  as |ns3| mobility models

* Point-to-Multipoint (PMP) mode and the WirelessMAN-OFDM PHY layer

* Initial Ranging

* Service Flow Initialization

* Management Connection

* Transport Initialization

* UGS, rtPS, nrtPS, and BE connections

The following aspects are not presently modelled but would be good topics for

future extensions:

* OFDMA PHY layer

* Link adaptation

* Mesh topologies

* ARQ

* ertPS connection

* packet header suppression

Using the Wimax models

**********************

The main way that users who write simulation scripts will typically interact

with the Wimax models is through the helper API and through the publicly visible

attributes of the model.

The helper API is defined in ``src/helper/wimax-helper.{cc,h}``.

The example ``examples/wimax/wimax-simple.cc`` contains some basic code that

shows how to set up the model:::

  switch (schedType)

    {

    case 0:

      scheduler = WimaxHelper::SCHED_TYPE_SIMPLE;

      break;

    case 1:

      scheduler = WimaxHelper::SCHED_TYPE_MBQOS;

      break;

    case 2:

      scheduler = WimaxHelper::SCHED_TYPE_RTPS;

      break;

    default:

      scheduler = WimaxHelper::SCHED_TYPE_SIMPLE;

    }

  NodeContainer ssNodes;

  NodeContainer bsNodes;

  ssNodes.Create (2);

  bsNodes.Create (1);

  WimaxHelper wimax;

  NetDeviceContainer ssDevs, bsDevs;

  ssDevs = wimax.Install (ssNodes,

                          WimaxHelper::DEVICE_TYPE_SUBSCRIBER_STATION,

                          WimaxHelper::SIMPLE_PHY_TYPE_OFDM,

                          scheduler);

  bsDevs = wimax.Install (bsNodes, WimaxHelper::DEVICE_TYPE_BASE_STATION, WimaxHelper::SIMPLE_PHY_TYPE_OFDM, scheduler);

This example shows that there are two subscriber stations and one base station

created. The helper method ``Install`` allows the user to specify the scheduler

type, the physical layer type, and the device type.

Different variants of ``Install`` are available; for instance, the example

``examples/wimax/wimax-multicast.cc`` shows how to specify a non-default channel

or propagation model:::

  channel = CreateObject<SimpleOfdmWimaxChannel> ();

  channel->SetPropagationModel (SimpleOfdmWimaxChannel::COST231_PROPAGATION);

  ssDevs = wimax.Install (ssNodes,

                          WimaxHelper::DEVICE_TYPE_SUBSCRIBER_STATION,

                          WimaxHelper::SIMPLE_PHY_TYPE_OFDM,

                          channel,

                          scheduler);

  Ptr<WimaxNetDevice> dev = wimax.Install (bsNodes.Get (0),

                                           WimaxHelper::DEVICE_TYPE_BASE_STATION,

                                           WimaxHelper::SIMPLE_PHY_TYPE_OFDM,

                                           channel,

                                           scheduler);

Mobility is also supported in the same way as in Wifi models; see the

``examples/wimax/wimax-multicast.cc``.

Another important concept in WiMAX is that of a service flow. This is a

unidirectional flow of packets with a set of QoS parameters such as traffic

priority, rate, scheduling type, etc. The base station is responsible for

issuing service flow identifiers and mapping them to WiMAX connections. The

following code from ``examples/wimax/wimax-multicast.cc`` shows how this is

configured from a helper level:::

 ServiceFlow MulticastServiceFlow = wimax.CreateServiceFlow (ServiceFlow::SF_DIRECTION_DOWN,

                                                              ServiceFlow::SF_TYPE_UGS,

                                                              MulticastClassifier);

  bs->GetServiceFlowManager ()->AddMulticastServiceFlow (MulticastServiceFlow, WimaxPhy::MODULATION_TYPE_QPSK_12);

Wimax Attributes

****************

The WimaxNetDevice makes heavy use of the |ns3| :ref:`Attributes` subsystem for

configuration and default value management.  Presently, approximately 60 values

are stored in this system.

For instance, class :cpp:class:`ns-3::SimpleOfdmWimaxPhy` exports these

attributes:

* NoiseFigure:  Loss (dB) in the Signal-to-Noise-Ratio due to non-idealities in the receiver.

* TxPower:  Transmission power (dB)

* G:  The ratio of CP time to useful time

* txGain:  Transmission gain (dB)

* RxGain:  Reception gain (dB)

* Nfft:  FFT size

* TraceFilePath:  Path to the directory containing SNR to block error rate files

For a full list of attributes in these models, consult the Doxygen page that

lists all attributes for |ns3|.

Wimax Tracing

*************

|ns3| has a sophisticated tracing infrastructure that allows users to hook into

existing trace sources, or to define and export new ones.  

Many |ns3| users use the built-in Pcap or Ascii tracing, and the

WimaxHelper has similar APIs:::

    AsciiTraceHelper ascii;

    WimaxHelper wimax;

    wimax.EnablePcap ("wimax-program", false);

    wimax.EnableAsciiAll (ascii.CreateFileStream ("wimax-program.tr");

Unlike other helpers, there is also a special ``EnableAsciiForConnection()``

method that limits the ascii tracing to a specific device and connection.

These helpers access the low level trace sources that exist in the WiMAX

physical layer, net device, and queue models. Like other |ns3| trace sources,

users may hook their own functions to these trace sources if they want to do

customized things based on the packet events. See the Doxygen List of trace

sources for a complete list of these sources.

Wimax MAC model

***************

The 802.16 model provided in |ns3| attempts to provide an accurate MAC and PHY

level implementation of the 802.16 specification with the Point-to-Multipoint

(PMP) mode and the WirelessMAN-OFDM PHY layer. The model is mainly composed of

three layers:

* The convergence sublayer (CS)

* The MAC CP Common Part Sublayer (MAC-CPS)

* Physical (PHY) layer

The following figure :ref:`WimaxArchitecture` shows the relationships of these

models.

.. _wimax-architecture:

.. figure:: figures/WimaxArchitecture.*

   WiMAX architecture.

the Convergence Sublayer ++++++++++++++++++++++++

The Convergence sublayer (CS) provided with this module implements the Packet

CS, designed to work with the packet-based protocols at higher layers. The CS is

responsible of receiving packet from the higher layer and from peer stations,

classifying packets to appropriate connections (or service flows) and processing

packets. It keeps a mapping of transport connections to service flows. This

enables the MAC CPS identifying the Quality of Service (QoS) parameters

associated to a transport connection and ensuring the QoS requirements. The CS

currently employs an IP classifier.

IP Packet Classifier ++++++++++++++++++++

An IP packet classifier is used to map incoming packets to appropriate

connections based on a set of criteria. The classifier maintains a list of

mapping rules which associate an IP flow (src IP address and mask, dst IP

address and mask, src port range, dst port range and protocol) to one of the

service flows.  By analyzing the IP and the TCP/UDP headers the classifier will

append the incoming packet (from the upper layer) to the queue of the

appropriate WiMAX connection. Class :cpp:class:`IpcsClassifier` and class

:cpp:class:`IpcsClassifierRecord` implement the classifier module for both SS

and BS

The MAC Common Part Sublayer (CPS) is the main sublayer of the IEEE 802.16 MAC

and performs the fundamental functions of the MAC. The module implements the

Point-Multi-Point (PMP) mode. In PMP mode BS is responsible of managing

communication among multiple SSs. The key functionalities of the MAC CPS include

framing and addressing, generation of MAC management messages, SS initialization

and registration, service flow management, bandwidth management and scheduling

services.  Class :cpp:class:`WimaxNetDevice` represents the MAC layer of a WiMAX

network device. This class extends the class :cpp:class:`NetDevice` of the |ns3|

API that provides abstraction of a network device. Class

:cpp:class:`WimaxNetDevice` is further extended by class

:cpp:class:`BaseStationNetDevice` and class

:cpp:class:`SubscriberStationNetDevice`, defining MAC layers of BS and SS,

respectively.  Besides these main classes, the key functions of MAC are

distributed to several other classes.

Framing and Management Messages

+++++++++++++++++++++++++++++++

The module implements a frame as a fixed duration of time, i.e., frame

boundaries are defined with respect to time. Each frame is further subdivided

into downlink (DL) and uplink (UL) subframes. The module implements the Time

Division Duplex (TDD) mode where DL and UL operate on same frequency but are

separated in time. A number of DL and UL bursts are then allocated in DL and UL

subframes, respectively. Since the standard allows sending and receiving bursts

of packets in a given DL or UL burst, the unit of transmission at the MAC layer

is a packet burst. The module implements a special PacketBurst data structure

for this purpose. A packet burst is essentially a list of packets. The BS

downlink and uplink schedulers, implemented by class :cpp:class:`BSScheduler`

and class :cpp:class:`UplinkScheduler`, are responsible of generating DL and UL

subframes, respectively. In the case of DL, the subframe is simulated by

transmitting consecutive bursts (instances PacketBurst). In case of UL, the

subframe is divided, with respect to time, into a number of slots. The bursts

transmitted by the SSs in these slots are then aligned to slot boundaries. The

frame is divided into integer number of symbols and Physical Slots (PS) which

helps in managing bandwidth more effectively. The number of symbols per frame

depends on the  underlying implementation of the PHY layer. The size of a DL or

UL burst is specified in units of symbols.

Network Entry and Initialization

++++++++++++++++++++++++++++++++

The network entry and initialization phase is basically divided into two

sub-phases, (1) scanning and synchronization and (2) initial ranging. The entire

phase is performed by the LinkManager component of SS and BS. Once an SS wants

to join the network, it first scans the downlink frequencies to search for a

suitable channel. The search is complete as soon as it detects a PHY frame. The

next step is to establish synchronization with the BS. Once SS receives a

Downlink-MAP (DL-MAP) message the synchronization phase is complete and it

remains synchronized as long as it keeps receiving DL-MAP and  Downlink Channel

Descriptor (DCD) messages. After the synchronization is established, SS waits

for a Uplink Channel Descriptor (UCD) message to acquire uplink channel

parameters. Once acquired, the first sub-phase of the network entry and

initialization is complete. Once synchronization is achieved, the SS waits for a

UL-MAP message to locate a special grant, called initial ranging interval, in

the UL subframe. This grant is allocated by the BS Uplink Scheduler at regular

intervals. Currently this interval is set to 0.5 ms, however the user is enabled

to modify its value from the simulation script.

Connections and Addressing

++++++++++++++++++++++++++

All communication at the MAC layer is carried in terms of connections. The

standard defines a connection as a unidirectional mapping between the SS and

BS's MAC entities for the transmission of traffic. The standard defines two

types of connections: management connections for transmitting control messages

and transport connections for data transmission. A connection is identified by a

16-bit Connection Identifier (CID).  Class :cpp:class:`WimaxConnection` and

class :cpp:class:`Cid` implement the connection and CID, respectively. Note that

each connection maintains its own transmission queue where packets to transmit

on that connection are queued. The ConnectionManager component of BS is

responsible of creating and managing connections for all SSs.

The two key management connections defined by the standard, namely the Basic and

Primary management connections, are created and allocated to the SS during the

ranging process. Basic connection plays an important role throughout the

operation of SS also because all (unicast) DL and UL grants are directed towards

SS's Basic CID. In addition to management connections, an SS may have one or

more transport connections to send data packets. The Connection Manager

component of SS manages the connections associated to SS. As defined by the

standard, a management connection is bidirectional, i.e., a pair of downlink and

uplink connections is represented by the same CID. This feature is implemented

in a way that one connection (in DL direction) is created by the BS and upon

receiving the CID the SS then creates an identical connection (in UL direction)

with the same CID.

Scheduling Services

+++++++++++++++++++

The module supports the four scheduling services defined by the 802.16-2004

standard:

* Unsolicited Grant Service (UGS)

* Real-Time Polling Services (rtPS)

* Non Real-Time Polling Services (nrtPS)

* Best Effort (BE)

These scheduling services behave differently with respect to how they request

bandwidth as well as how the it is granted. Each service flow is associated to

exactly one scheduling service, and the QoS parameter set associated to a

service flow actually defines the scheduling service it belongs to. When a

service flow is created the UplinkScheduler calculates necessary parameters such

as grant size and grant interval based on QoS parameters associated to it.

WiMAX Uplink Scheduler Model

++++++++++++++++++++++++++++

Uplink Scheduler at the BS decides which of the SSs will be assigned uplink

allocations based on the QoS parameters associated to a service flow (or

scheduling service) and bandwidth requests from the SSs. Uplink scheduler

together with Bandwidth Manager implements the complete scheduling service

functionality. The standard defines up to four scheduling services (BE, UGS,

rtPS, nrtPS) for applications with different types of QoS requirements. The

service flows of these scheduling services behave differently with respect to

how they request for bandwidth as well as how the bandwidth is granted. The

module supports all four scheduling services. Each service flow is associated to

exactly one transport connection and one scheduling service. The QoS parameters

associated to a service flow actually define the scheduling service it belongs

to. Standard QoS parameters for UGS, rtPS, nrtPS and BE services, as specified

in Tables 111a to 111d of the 802.16e amendment, are supported. When a service

flow is created the uplink scheduler calculates necessary parameters such as

grant size and allocation interval based on QoS parameters associated to it.

The current WiMAX module provides three different versions of schedulers.

* The first one is a simple priority-based First Come First Serve (FCFS).  For

  the real-time services (UGS and rtPS) the BS then allocates grants/polls on

  regular basis based on the calculated interval. For the non real-time services

  (nrtPS and BE) only minimum reserved bandwidth is guaranteed if available

  after servicing real-time flows. Note that not all of these parameters are

  utilized by the uplink scheduler. Also note that currently only service flow

  with fixed-size packet size are supported, as currently set up in simulation

  scenario with OnOff application of fixed packet size. This scheduler is

  implemented by class :cpp:class:`BSSchedulerSimple` and class

  :cpp:class:`UplinkSchedulerSimple`.

* The second one is similar to first scheduler except by rtPS service flow. All

  rtPS Connections are able to transmit all packet in the queue according to the

  available bandwidth. The bandwidth saturation control has been implemented to

  redistribute the effective available bandwidth to all rtPS that have at least

  one packet to transmit. The remaining bandwidth is allocated to nrtPS and BE

  Connections. This scheduler is implemented by class

  :cpp:class:`BSSchedulerRtps` and class

  :cpp:class:`UplinkSchedulerRtps`.

* The third one is a Migration-based Quality of Service uplink scheduler This

  uplink scheduler uses three queues, the low priority queue, the intermediate

  queue and the high priority queue. The scheduler serves the requests in

  strict priority order from the high priority queue to the low priority queue.

  The low priority queue stores the bandwidth requests of the BE service flow.

  The intermediate queue holds bandwidth requests sent by rtPS and by nrtPS

  connections. rtPS and nrtPS requests can migrate to the high priority queue to

  guarantee that their QoS requirements are met. Besides the requests migrated

  from the intermediate queue, the high priority queue stores periodic grants

  and unicast request opportunities that must be scheduled in the following

  frame. To guarantee the maximum delay requirement, the BS assigns a deadline

  to each rtPS bandwidth request in the intermediate queue. The minimum

  bandwidth requirement of both rtPS and nrtPS connections is guaranteed over a

  window of duration T. This scheduler is implemented by class

  :cpp:class:`UplinkSchedulerMBQoS`.

WiMAX Outbound Schedulers Model

+++++++++++++++++++++++++++++++

Besides the uplink scheduler these are the outbound schedulers at BS and SS side

(BSScheduler and SSScheduler). The outbound schedulers decide which of the

packets from the outbound queues will be transmitted in a given allocation. The

outbound scheduler at the BS schedules the downlink traffic, i.e., packets to be

transmitted to the SSs in the downlink subframe. Similarly the outbound

scheduler at a SS schedules the packet to be transmitted in the uplink

allocation assigned to that SS in the uplink subframe. All three schedulers have

been implemented to work as FCFS scheduler, as they allocate grants starting

from highest priority scheduling service to the lower priority one (UGS> rtPS>

nrtPS> BE). The standard does not suggest any scheduling algorithm and instead

leaves this decision up to the manufacturers. Of course more sophisticated

algorithms can be added later if required.

WimaxChannel and WimaxPhy models

********************************

The module implements the Wireless MAN OFDM PHY specifications as the more

relevant for implementation as it is the schema chosen by the WiMAX Forum. This

specification is designed for non-light-of-sight (NLOS) including fixed and

mobile broadband wireless access. The proposed model uses a 256 FFT processor,

with 192 data subcarriers. It supports all the seven modulation and coding

schemes specified by Wireless MAN-OFDM. It is composed of two parts: the channel

model and the physical model.

Channel model

*************

The channel model we propose is implemented by the class

:cpp:class:`SimpleOFDMWimaxChannel` which extends the class

:cpp:class:`wimaxchannel`. The channel entity has a private structure named

m_phyList which handles all the physical devices connected to it. When a

physical device sends a packet (FEC Block) to the channel, the channel handles

the packet, and then for each physical device connected to it, it calculates the

propagation delay, the path loss according to a given propagation model and

eventually forwards the packet to the receiver device.  The channel class uses

the method `GetDistanceFrom()` to calculate the distance between two physical

entities according to their 3D coordinates. The delay is

computed as `delay = distance/C`, where `C` is the speed of the light. 

Physical model

**************

The physical layer performs two main operations: (i) It receives a burst from a

channel and forwards it to the MAC layer, (ii) it receives a burst from the MAC

layer and transmits it on the channel. In order to reduce the simulation

complexity of the WiMAX physical layer, we have chosen to model offline part of

the physical layer. More specifically we have developed an OFDM simulator to

generate trace files used by the reception process to evaluate if a FEC block

can be correctly decoded or not.

Transmission Process: A burst is a set of WiMAX MAC PDUs. At the sending

process, a burst is converted into bit-streams and then splitted into smaller

FEC blocks which are then sent to the channel with a power equal P_tx.

Reception Process: The reception process includes the following operations:

#. Receive a FEC block from the channel.

#. Calculate the noise level.

#. Estimate the signal to noise ratio (SNR) with the following formula.

#. Determine if a FEC block can be correctly decoded.

#. Concatenate received FEC blocks to reconstruct the original burst.

#. Forward the burst to the upper layer.

The developed process to evaluate if a FEC block can be correctly received or

not uses pre-generated traces.  The trace files are generated by an external

OFDM simulator (described later). A class named SNRToBlockErrorRateManager

handles a repository containing seven trace files (one for each modulation and

coding scheme). A repository is specific for a particular channel model.

A trace file is made of 6 columns. The first column provides the SNR value (1),

whereas the other columns give respectively the bit error rate BER (2), the

block error rate BlcER(3), the standard deviation on BlcER, and the confidence

interval (4 and 5).  These trace files are loaded into memory by the

SNRToBlockErrorRateManager entity at the beginning of the simulation.

Currently, The first process uses the first and third columns to determine if a

FEC block is correctly received. When the physical layer receives a packet with

an SNR equal to SNR_rx, it asks the SNRToBlockErrorRateManager to return the

corresponding block error rate BlcER. A random number RAND between 0 and 1 is

then generated. If RAND is greater than BlcER, then the block is correctly

received, otherwise the block is considered erroneous and is ignored.

The module provides defaults SNR to block error rate traces in default-traces.h.

The traces have been generated by an External WiMAX OFDM simulator. The

simulator is based on an external mathematics and signal processing library IT++

and includes : a random block generator, a Reed Solomon (RS) coder, a

convolutional coder, an interleaver, a 256 FFT-based OFDM modulator, a

multi-path channel simulator and an equalizer. The multipath channel is

simulated using the TDL_channel class of the IT++ library.

Users can configure the module to use their own traces generated by another OFDM

simulator or ideally by performing experiments in real environment. For this

purpose, a path to a repository containing trace files should be provided.  If

no repository is provided the traces form default-traces.h will be loaded. A

valid repository should contain 7 files, one for each modulation and coding

scheme.

The names of the files should respect the following format: modulation0.txt for

modulation 0, modulation1.txt for modulation 1 and so on...  The file format

should be as follows::

    SNR_value1   BER  Blc_ER  STANDARD_DEVIATION  CONFIDENCE_INTERVAL1  CONFIDENCE_INTERVAL2

    SNR_value2   BER  Blc_ER  STANDARD_DEVIATION  CONFIDENCE_INTERVAL1  CONFIDENCE_INTERVAL2

     ...          ...  ...     ...                 ...                   ...

     ...          ...  ...     ...                 ...                   ...