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 .
-
-
-
-
-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 Release 97 Symbian OS Networking reference model for the cellular modem
-
-
-
3GPP Release 4 Symbian OS Networking reference model
-
-
Nifman - the Symbian OS network interface manager. Nifman is the controlling entity for the network adapter, it is responsible for loading the agent, and/or NIF. It manages the overall link layer connection state.
-
-
-
Netcon - the Symbian OS network controller. Netcon is responsible for selecting an appropriate network link layer connection for a client, based on the supplied preferences. Upon completing the selection of an appropriate connection, it provides this information to nifman, which then either starts a connection (if the client's request requires a new one), or attaches the client to an existing connection.
-
-
-
Agent Dialog - which is not shown in the diagrams above is the component that provides UI-level interaction from the networking subsystem, and the implementation of which is provided by each UI (eg. S60, UIQ). The code in the networking directory provides this facility for textshell and TechView. Information for which this component will prompt include IAP and/or SNAP, usernames and passwords, and requests to reconnect.
-
-
-
QoS framework/GUQoS - the Symbian OS IP QoS modules. The QoS framework provides a framework for handling link-layer QoS for IP related protocols in Symbian OS. GUQoS, the GPRS/UMTS Quality of Service module, provides a plugin to the QoS framework. It handles link layer QoS control over a GPRS/UMTS network by negotiating the creation and control of secondary PDP contexts via SPUD.
-
-
-
TCPIP6 - the Symbian OS TCP/IP stack. Supports both IPv4 and IPv6.
-
-
-
SPUD - the Symbian OS secondary PDP context UMTS driver. SPUD is a NIF which provides support for both primary and secondary contexts. It communicates with the baseband by loading NIFs beneath it - one NIF for the primary context, and one NIF per secondary context. It interfaces with GUQos and ETel to perform the management of the secondary contexts.
-
-
-
-Commsdat - the communications database. A DBMS database containing all the settings used by the networking subsystem. The connection settings in the database are divided into two main types:
-
-
-
-"Bearer" tables - Bearers describe basic attributes at the physical layer, such as serial port speeds, and modem init strings.
-
-"Service" tables - Services describe details of a service that runs over a bearer, such as a connection to a dial-up ISP. In this example, the dial-up ISP service table would contain such settings as a phone number, username, password, and the protocols supported by that ISP eg. IPv4, IPv6.
-
-
-
-
-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.
-
-
CSD connections
- To support CSD connections, some modification of the supplied components might be necessary. Symbian OS is supplied with a ppp.nif and a csd.agt, so no new NIF or AGT needs to be written. However, depending upon the method used to interface between Symbian OS and the phone stack, a new CSY may be necessary. The current PPP implementation expects to talk to C32BCA which is a wrapper around a serial port (ie. a CSY using the RComm interface), so if the TSY also wishes to use a serial port then multiple physical serial ports, or some form of multiplexing CSY will be necessary. Multiplexing CSYs based around 3GPP 027.010 are available for licensing for Symbian OS.
-
-
-
GPRS - single primary PDP context
- The requirements for supporting a single primary PDP context are the same as those for supporting CSD, but there is an additional requirement on the phone side - that it must contain a PPP server to terminate the PPP connection from Symbian OS. The phone side server then transfers packets between the PPP link and the GPRS network. It is possible to use a solution that does not use PPP, however, this would require creating a nif from scratch.
-
-
-
GPRS - multiple primary PDP contexts
- To support multiple primary PDP contexts it is necessary to support multiple serial ports between each instance of PPP (representing a context), and the phone side PPP server. This either requires multiple physical serial ports between Symbian OS and the phone side OS, which limits the number of contexts available to the number of serial ports assigned for this purpose, or use of a multiplexing CSY, such as the 027.010 multiplexing CSY discussed earlier. Note that these details should be hidden behind a BCA.
-
-
-
GPRS - multiple primary and secondary PDP contexts
- In the case where secondary PDP contexts are required, the user can configure the system to use the SPUD module which supports primary and multiple secondary PDP contexts. The details of this module and using secondary PDP contexts is described in section Using secondary PDP context UMTS driver .
-
-
-
QOS policies
- The QoS framework can be configured using the qos ini file. The QoS policies can be loaded from a policy file which is specified in the ini file. The Policy file can be used to add flowspec policies, modulespec policies and extension policies. As the policy configuration tool is not yet implemented, the policy file is the only way to add QoS modules to the framework.
-
-
-
3GSM (aka UMTS, W-CDMA)
- W-CDMA appears similar to GPRS at this level, and therefore all the statements contained within this document that refer to GPRS are applicable to W-CDMA.
-
-
-
CDMA2000
- CDMA2000 support is currently under development within Symbian. Further details will be added as they become available.
-
-
-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:
-
-
GPRS - One nif/agent per primary context
-
W-CDMA - as GPRS
-
CDMA2000 - one nif/agent per PPP link layer; and CDMA2000 specs state that only one PPP link layer can be present on the air interface
-
Ethernet - one nif/agent per Ethernet link layer
-
Bluetooth PAN profile - one nif/agent per PAN profile network
-
-
-Writing an agent
-
Types of agent
In their very basic form, an agent has the following responsibilities:
-
-
Interface with some connection provider (eg. ETel for CSD and GPRS connections, Bluetooth stack for BT PAN connections) for the purpose of controlling the connection.
-
Store, and provide access to, connection settings. Agents may use a variety of methods for storing settings, including a .ini file for simple agents, or using commsdat for more complicated ones.
-
-
-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.
-
-
CNifAgentBase The most basic base class. Agents should derive from CNifAgentBase if they will only ever connect to a single access point (eg. one ISP) which cannot be altered by the user. In this case they can use a simple .ini file to store the settings for this access point.
-
-
-
CAgentBase The base class for a more advanced agent. Agents should derive from CAgentBase if they required access to settings in commsdat, and (optionally) allow user programs to override the settings on a per-connection basis. CAgentBase handles all the details of accessing commsdat, as well as handling overrides and interaction with netcon, meaning that the agent implementation just needs to handle the creation and control of the connection.
-
-
-
CStateMachineAgentBase The base class for porting agent extensions from Symbian OS v6.1. However, as there is currently no other base class that provides a state machine framework, this is also the de facto base class for implementing agents that require a state machine. Alternately, an agent is free to implement its own state machine in whichever way it wishes - use of this class is not required. For details of implementing agents using the agx state machine framework, see The v6.1 agent extension (.agx) base classes .
-
-
-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:
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().
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:
-
-
CNifIfBase This is the base class for each binder layer.
-
-
-
CNifIfLink This is the base class for the link layer
-
-
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
-
CNifIfBase::BindL
-
-
-
CNifIfBase::Open
-
CNifIfBase::Close
-
-
-
CNifIfBase::Send
-
-
-
CNifIfBase::Control - if the nif is to support any functionality that cannot be accessed through the existing API eg. fetching interface configuration.
-
CNifIfBase::Info
-
CNifIfBase::Notification
-
CNifIfBase::State
-
-
-
CNifIfLink
-
CNifIfLink::Start
-
CNifIfLink::Stop
-
-
-
CNifIfLink::AuthenticateComplete
-
-
-
CNifIfLink::GetBinderL
-
-
-
CNifIfLink::Restart - if the nif supports binder layer restart without link layer restart, eg. PPP
-
-
-
-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
-
-
-
-
-
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:
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.
-
-
-
-
Once the agent has completed the connection, the nif is then started.
-
-
-
-
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.
-
-
-
-
-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.
-
-
-
-
-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.
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.
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.
- 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
-
-1.3-rc2
-
-
-
-
-
-
-
-
-
-
-
1.3-rc2
-
-