Main Page  

Networking porting guide

Classification
Document reference
Product documentation
Status
Issued
Version:
1.2
Team
Networking
Author:
Iain Campbell
Owner
Networking team
Approver
Networking technical architect
Comms-infras technical architect
Date:
04th May 2005

Introduction

Purpose and scope

This guide is intended for anyone seeking to customise the Symbian OS networking subsystem for a specific platform or device. It is typically necessary to modify or replace elements of the networking subsystem in devices to adapt the networking subsystem for the licensees device, depending on the mechanism used to connect the Symbian OS networking subsystem to the cellular modem. Exact details of the components that need replacing/customising are found in Customising the Symbian OS network subsystem .
This document refers to the Symbian OS v9.1 networking subsystem,although sections refer to previous versions of the OS.

Network adaptors

Network adaptor is the Symbian OS term for the adaptation layer that takes WAN protocols such as IP, and packages them for transport over a specific bearer, for example. CSD, Ethernet, or GPRS. In 3GPP terms, a network adaptor operates on the TE side of the R interface.
A network adaptor consists of two elements, an agent (agt) and a networking interface (nif).
Agents are resposible for managing the control plane of a connection. They provide an interface to the appropriate control component, for example, ETel in the case of CSD and GPRS, or the Bluetooth stack in the case of Bluetooth PAN profile, to perform connection setup and management functions. They are normally implemented as a state machine, which progresses through a series of states during the lifetime of the connection.
Network interfaces are resposible for managing the data plane of a connection, and perform the framing for all data packets that are transferred. Some nifs are split into two parts, which roughly correspond to the MAC and LLC sublayers in the OSI 7 layer model. This is usually done where a nif supports multiple bearers, but uses the same framing in each case. In the case of the PPP and IP nifs, the lower layer is licensee replaceable, with the inter-layer interface conforming to the baseband channel adaptor (BCA) interface. More details can be found in the section Nif interface to the bearer .
nif_and_agt_model.gif

An overview of the Symbian OS networking subsystem

The following are the main components of the Symbian OS communications subsystem, as relates to network adaptors. For an overview of the Symbian OS networking architecture itself, please read the Comms-Infras and Networking Architectural Descriptions.
3GPP_Release97_NetworkingRefModel.gif

3GPP Release 97 Symbian OS Networking reference model for the cellular modem

3GPP_Release4_NetworkingRefModel.gif

3GPP Release 4 Symbian OS Networking reference model

Customising the Symbian OS network subsystem

The Symbian OS network reference model

The "network reference model" refers to the standard components that are delivered in Symbian OS, which are used by Symbian on their reference platforms. It may be necessary for licensees to customise the subsystem by providing extra components, depending on the feature set of their product.
The Symbian OS networking reference model currently has a choice of two NIFs available for communication with the baseband - a PPP NIF, for basebands that require link layer framing; and an IP NIF for basebands that use a communications channel that already provides framing. CSD and PSD agents are provided for circuit switched connection and primary-context-only packet switched connections. In cases where primary and secondary contexts are in use, the SPUD NIf should be used with the null agent.
Both the PPP NIF and the IP NIF are layered and use plugins conforming to the BCA interface. This allows plugins to be created to interface to the licensees baseband interconnect solution. Symbian provides a BCA plugin to interface to the serial server.
As a result, licensees wishing to include any of these features will have to customise elements of the networking subsystem.

Customising the reference model for a product

Obviously it is desirable to reuse as much Symbian code as possible, unless there is a pressing reason not to. In this section, solutions for maximising code reuse are discussed. In the next section there is a brief discussion of why this might not be desirible, and the other options available.
Depending on the support required for various bearers, varying degrees of customisation of the networking subsystem are required.

Other approaches to customising the Symbian OS networking subsystem

In some cases, for example, where a single processor is used to run both Symbian OS and the phone stack, it is more efficient not to use a protocol such as PPP, and instead just pass the data in a very simple framing protocol without error checking. In this case, it would be necessary to implement a custom nif to perform the appropriate framing. However, it should still be possible to reuse the Symbian PSD agent, providing that it is not a requirement to support secondary contexts.

Implementing a Symbian OS network adaptor

Nif and agent overview

Nif and agent factories
Nifs and agents are packaged in individual polymorphic DLLs, with a .nif or .agt extension respectively. The dll should contain a factory class, either CNifIfFactory or CNifAgentFactory, which implements a NewInterfaceL() call to create new instances of the nif or agent. The DLL exports a single function at ordinal 1, which creates an instance of the appropriate factory object.
There should be one instance of a nif/agent pair for each logical interface on the device. This means that for an interface that carries multiple protocols, such as a PPP link carrying IPv4 and IPv6, there would be a single instance of the nif/agent. However, if there were a situation where there were multiple link layers running over the same physical bearer; for example, a GPRS network with connections to multiple APNs; there would be multiple instances of the nif/agent combination. This distintion can be quite a subtle one in some cases - this is a list of the rules for nif/agent creation that Symbian have drawn up so far:

Writing an agent

Types of agent
In their very basic form, an agent has the following responsibilities:

Agent base classes

There are three possible Symbian-provided agent base classes. Depending upon the needs of the agent being created, it should derive from exactly one of these base classes, whichever is most appropriate for the required functionality.

The v6.1 agent extension (.agx) base classes

There are two main classes in the agx state machine framework - CAgentSMBase and CAgentStateBase.
CAgentSMBase is the base class for the state machine - it holds pointers to commsdat, and the Agent Dialog.
CAgentStateBase is the base class for individual agent states.

Agent interface to nifman

The interface from the agent to nifman is the MNifAgentNotify class. A pointer to the class implementation in nifman is held in the CNifAgentBase class, and is initialised by the base class during agent startup.

Additional agent APIs to implement

There is an additional API that an agent may choose to support - MNifAgentExtendedManagementInterface. This has two main areas - it allows agents to report detailed information about the connection, such as the bearer type and bearer specific information; and it extends the concept of a connection to include subconnections. For more details on the concept of connections and subconnections as implemented in Symbian OS, see .
If an agent implements the extended management interface, it should return a pointer to the appropriate class using the TPckg argument when the following method is called:
                        CNifAgentBase::Control(KCOLAgent, KCOGetAgentEMIPtr, TPckg<MNifAgentExtendedManagementInterface*>);

In order to override the compatibility layer that is provided for nifs and agents that do not implement the extended management interface, both the nif and agent involved in a connection must support the extended management interfaces. The API that nifs must implement is described in Additional nif APIs to implement .

Sequence diagrams for agent startup

When a network adaptor is started, the agent is the first component to be brought up. The sequence diagram below shows the actions that are performed by the framework when the connection is started. As far as the agent is concerned the only method that needs implementing is Connect().
seqdig-agentstart.gif
The next stage in connection startup can be seen in Sequence diagrams for nif startup .

Writing a nif

The Symbian OS framework for a network interface (nif) mandates two types of object - a link layer object for global management of the nif, and one or more binder layer objects which provide an endpoint for a layer 3 protocol. The link layer is treated as the nif's global management object, as there is only one per nif instance - this acts as the interface to the nif's control plane. Each binder layer will be responsible for a single protocol type, which will be demultiplexed by the link layer of the nif.
If a nif is a very simple implementation which is only going to handle a single layer 3 protocol type, and the implementator wishes to perform all operations in a single class, it is possible to derive solely from the link layer base class, and return a pointer to this when asked for the binder layer object. This is possible because the link layer base class is derived from the binder layer base class to allow simple implementations using the minimum number of classes.
When designing a nif, it may be useful to consider whether the framing employed by the protocol can be reused over several transport layers - for example, Ethernet framing is used over both Ethernet networks, IR-LAN networks, and Bluetooth PAN networks. Thus the nif is split into two parts - a 802.3 module, which performs the framing; and a packet driver layer, which provides an interface between the framing layer and the bearer layer, which will either be an Ethernet device driver, IrDA socket, or Ethernet bridge and series of Bluetooth sockets.

Nif base classes

The main classes that should be implemented by a nif are:
Functions to implement
The functions below are the ones that a nif should implement. For BC reasons, there are some methods which are virtual, rather than pure virtual, that a nif must implement. These are detailed below.
CNifIfBase
CNifIfLink

Nif interface to nifman

The interface from the nif to nifman is the MNifIfNotify class. A pointer to this interface is held in the CNifIfBase and CNifIfLink classes, and is initialised by the base classes during nif startup.

Nif interface to the bearer

nif-bearer-interface.gif
BCA hides the R-Interface realization - specific interface from the NIF. Therefore, the same NIF binary can be used with different physical realizations of R-Interface, provided that a suitable implementation of BCA exists.

Additional nif APIs to implement

There is an additional API that a nif may choose to support - MNifIfExtendedManagementInterface. This has two main areas - it allows nifs to report statistical information, such as the number of bytes sent and received; and it extends the concept of a connection to include subconnections. For more details on the concept of connections and subconnections as implemented in Symbian OS, see .
If a nif implements the extended management interface, it should return a pointer to it when the following method is called:
                        CNifIfLink::Control(KCOLInterface, KCOGetNifEMIPtr, TPckg<MNifIfExtendedManagementInterface*>);

In order to override the compatibility layer that is provided for nifs and agents that do not implement the extended management interface, both the nif and agent involved in a connection must support the extended management interfaces. The API that agents must implement is described in Additional agent APIs to implement .

Sequence diagrams for nif startup

After the agent has signalled the initial stage of connection startup (ServiceStarted), the nif is loaded by nifman.
seqdig-nifload.gif
Once the agent has completed the connection, the nif is then started.
seqdig-nifstart.gif
Once the nif has brought the link up, it signals the attached layer 3 protocols to indicate the link is ready. It also sends a signal to nifman to inidicate that the link layer is up, and nifman uses this information to perform a series of actions (eg. starting the idle timers). Finally, the nif sends a progress notification which is delivered via nifman and esock to any applications that have subscribed to progress notifications for this link.
seqdig-niflinkup.gif

Using secondary PDP context UMTS driver

The applications that require secondary PDP context will be making use of the SPUD module. However, this interaction is indirect and through the use of the QoS Framework API. The diagram below shows the interaction between the networking modules and SPUD for using multiple PDP contexts.
spud_interaction.gif

Implementing the interface to ETel

The interface between the agent or nif (depending on implementation) and ETel is through the RPacketContext API. Details of this API, along with a description of how to use it, can be found in the Symbian OS SDK documentation.

Implementing the interface to GUQoS

The interface from GUQoS to the nif is through the Control() call on the CNifIfBase-derived object in the nif. The interface from the nif back to GUQoS is through the MEventNotify class. To allow access to the MEventNotify class, the nif should include umtsnifcontrolif.h from /epoc32/include. It should also link against umtsif.lib.
To allow easy migration to the future QoS framework, nif designers would be advised to encapsulate all the functionality that interfaces to ETel (to perform context activation and control) in a seperate module within the nif. Doing this will make migration to the new scheme much easier. It is also recommended that nif designers implement a simple tunnelling scheme to route requests received by their CNifIfBase class from GUQoS to their context control class(es), and that they store the MEventNotify pointer within the context control class(es). Alternately, this tunnelling scheme could be used to pass the commands to the agent, which would then perform the appropriate action.
Declaring which QoS module to use
On nif startup, the QoS framework will query the nif's Control() method to find out the name of the QoS plugin that the nif requires.
                                CNifIfBase::Control(KSOLInterface, KSoIfControllerPlugIn , TSoIfControllerInfo);

The TSoIfControllerInfo structure should be filled in as follows 

                                _LIT(KUmtsPlugInName, "guqos");

                                TSoIfControllerInfo controllerInfo;
                                controllerInfo.iPlugIn = KUmtsPlugInName;
                                controllerInfo.iProtocolId = 360;

GUQoS event handler registration
The GUQoS module will then attempt to register its event handler class with the nif. This class is used by the nif to report events asynchronously to GUQoS.
                                CNifIfBase::Control(KSOLInterface, KRegisterEventHandler, TNifEvent);

The TNifEvent class contains the pointer to the MEventNotify pointer, and should be extracted and stored: 

                                TNifEvent& opt = *static_cast<TNifEvent*>(aOption.Ptr());

                                iEvent  = static_cast<MNifEvent*>(opt.iEvent);

Setting up a new secondary context
When GUQoS gets a request for a QoS channel that it cannot already satisfy, it requests that the nif create a new context.
                                CNifIfBase:: Control(KSOLInterface, KContextCreate, aOpt)

is called to create secondary PDP context. The nif should then call: 

                                TContextParameters iParameters;
                                iParameters.iReasonCode = KErrNone;
                                iParameters.iContextInfo.iStatus = RPacketContext::EStatusUnknown;   
                                TPckg<TContextParameters> paraPckg(iParameter);

                                MNifEvent::RaiseEvent(reinterpret_cast<CProtocolBase*>(CNifIfBase*), KSecondaryContextCreated, TPckg<TContextParameters>);

when the context has been created (note: creation is an action distinct from activation).

Setting the Traffic Flow Template (TFT) on a context
To set the required TFT on a context, GUQoS will call:
                                Control(KSOLInterface, KContextTFTModify, TPckg<TContextParameters>);

When the nif has completed the operation, it should update the TContextParameters structure appropriately, then call: 

                                MNifEvent::RaiseEvent(reinterpret_cast<CProtocolBase*>(CNifIfBase*), KContextTFTModifiedEvent, TPckg<TContextParameters>);

Altering the QoS on a context
To alter the QoS settings on a context, GUQoS will call:
                                Control(KSOLInterface, KContextQoSSet, TPckg<TContextParameters>);

When the nif has completed the operation, it should update the TContextParameters structure appropriately, then call: 

                                MNifEvent::RaiseEvent(reinterpret_cast<CProtocolBase*>(CNifIfBase*), KContextQoSSetEvent, TPckg<TContextParameters>);

Activating a secondary context
To trigger the activation of the secondary context, GUQoS will call:
                                Control(KSOLInterface, KContextActivate, TPckg<TContextParameters>);

When the nif has completed the operation, it should update the TContextParameters structure appropriately, then call: 

                                MNifEvent::Event(reinterpret_cast<CProtocolBase*>(CNifIfBase*), KContextActivateEvent, TPckg<TContextParameters>);

Assigning packets to contexts

Packets are assigned to a context by a QoS module that operates as a hook into the TCP/IP stack. Each packet has a context identifier inserted in the port field of the destination address entry in the RMBufPktInfo header that is at the start of the RMBufChain containing the packet. This can be read by the nif, and the packet associated with the appropriate context. Similarly, on receiving a packet, the nif should insert the context ID into the port field of the source address field of the RMBufPacketInfo header.
Assigning context IDs
Obviously this means that the nif must share the context ID numbering with the GUQoS module. Context IDs are assigned by the nif when it activates the context, and are passed back to the GUQoS module as part of the KSecondaryContextCreated event.

Further information

People

Contributors

		Lucy Carroll

Reviewers

		Drew Reed, Patrik Bannura, Nadeem Wahid, Lucy Carroll, Steve Larkin

Distribution

References

		GUQoS design doc, Nokia Research Centre; v0.05

Open Issues

Timescale for delivery of new QoS solution, and Symbian-supplied nif and agent to support it.

Glossary

		Agt - AGenT, the component that implements that layer 2 control plane in Symbian OS
		BCA - Baseband Channel Adaptor, provides an abstract interface for a bearer service
		Nif - Network InterFace, the component that implements the layer 2 data plane in Symbian OS
		Network adaptor - the collective term for a nif and agent

Document history

		0.1,	Draft,	Iain Campbell,	Initial version
		0.2,	Draft,	Iain Campbell,	Extended QoS section to include additional info
		0.3,	Draft,	Iain Campbell,	Updated after review comments from Nadeem and Lucy; added sequence diagrams
		1.0,	Issued,	Iain campbell,	First version issued
		1.1,	Issued, Iain Campbell,	Minor typographical updates
		1.2,	Draft,	Dino Livanos,	Updated for OS v9.1

Document review date

Any time changes are made to the nif and agent architecture and/or APIs

Copyright (c) Symbian Software Ltd. 2003 - 2005. All rights reserved.
Generated on Fri May 27 13:11:59 2005 for npg2 by doxygen1.3-rc2