Porting a Sample Radio Interface Layer (RIL) to a New Platform

 

Porting a Sample Radio Interface Layer (RIL) to a New Platform

Send Feedback on this topic to the authors

Technical Articles

by Intrinsyc Europe Limited

Updated July 2004

Applies to:

    Windows Mobile Version 5.0

Summary

This paper presents a comprehensive review of the Windows Mobile Radio Interface Layer, RIL, including the following topics

• Overview of a RIL development project
• Best practices during development and testing
• Typical platform implementation modifications
• New features included in Windows Mobile 5.0

Throughout the paper emphasis is placed on providing examples of typical changes required when you port a sample RIL to a new platform.

This paper is aimed at project managers responsible for RIL projects and engineers responsible for porting a RIL to a new system. The information presented is based on experiences gained by porting the RIL to a variety of platforms and modems.

This is a preliminary document and may be changed substantially prior to final commercial release of the software described herein.

Contents

Introduction
RIL Overview
RIL Modem Interface
Development Environment
Platform Implementation
Testing
New Features in Windows Mobile 5.0
Summary
For More Information

Introduction

The Radio Interface Layer (RIL) provides a key component of the underlying technology that is critical for enabling wireless voice or data applications that use Windows Mobile software to communicate seamlessly with a GSM/GPRS or CDMA2000 1X modem.

The RIL interfaces between the CellCore layer in Windows Mobile and the radio protocol stack within the wireless baseband system, or modem. The RIL abstracts the details of the hardware dependent components of a Windows Mobile-based device. This allows OEMs to integrate a variety of modems into their equipment, and thereby offer an opportunity for product differentiation.

The Windows Mobile 5.0 Adaptation Kit supplied to OEMs contains a sample RIL device driver developed for specific devices from Siemens, TI, and TTPCOM. However, there are a variety of modems available to the designer with new devices coming to market almost continuously. All modems generally conform to internationally recognized standards with regard to items like feature set and interface. Therefore, it is possible to include a generic sample RIL driver that can be used as the starting point for a RIL porting project.

The RIL, regardless of modem specific implementation details, must also conform to the interfaces provided and supported by the upper layers, for example: TAPI, SIM API, Short Message Service (SMS) API. Conformance to the general CellCore environment allows the sample RIL to include the required architecture. For example, the sample RIL can include command queue buffering, call back mechanisms, URC notifications, as well as other required architecture features to reduce the complexity of the project.

The sample RIL also includes code to support all the telephony features supported by Windows Mobile. These include: voice calls, data connections (circuit switched, CSD, and packet switched, for example, GPRS), SMS messages, network features (call forwarding, call barring, voice mail), SIM ToolKit, and more. These features are supported in a variety of upper layer user interfaces, for example in the Dialer, SMS Manager, as well as others.

A RIL porting project is concerned not with the general implementation of these many features, but with the specific differences between the hardware implementation on the target platform and the reference platform for which the sample Windows Mobile RIL was originally developed.

The following table shows the phases into which a RIL porting project is usually divided with associated estimated timescales.

Phase	Time in weeks
Modem specific changes	2 – 6 man weeks
Platform specific changes	2 – 8 man weeks
Test and debug	4 – 6 man weeks
Operator approvals	4 – 8 weeks elapsed time
LTK submission	4 weeks elapsed time

The extent of the modem-specific changes is dependent upon the differences between the selected modem and the reference modem supported by the sample RIL. This can vary considerably with a corresponding impact on timescales. Examples are provided in the Platform Implementation section of this document.

Platform support -- implementation details and testing, debugging, integration on the platform -- often presents the most challenging aspect of the project, especially if the platform is still under development during RIL integration.

Generally, a RIL port requires one engineer for development with a second engineer to test and assist with debugging and LTK submission. For radio modems, the basic AT command set has evolved and expanded over many years to support new network features that were not originally available. These result in a complex, feature-rich recipe from which the RIL developer selects the most applicable ingredients. It is advisable for the RIL development engineer to have access to a technical contact at the modem vendor throughout the course of the project as the development process can be somewhat iterative in nature.

A Windows Mobile-based device is required to pass the Logo Test Kit (LTK) program before the product can be shipped. The LTK subjects the device to a range of telephony tests that cover all telephony features expected to be supported by the device. It is unusual to pass 100% of the tests without some modification to the RIL, and in some cases the modem feature set may not support all test cases. This leads to the granting of a waiver for the product. The LTK requires resources to be available to perform the tests prior to submission, RIL modifications, and liaising with both Microsoft and the NSTL Lab conducting the approval process. The LTK process is covered in more detail later in this paper.

Operator approvals are usually required to be undertaken by the OEM. The timescales for operator approvals can differ considerably and depend on whether the end product is a handset (many months) or a vertical market device, for example a rugged PDA-like device with an embedded modem. It is common for vertical market devices to be approved on 2 or 3 networks that will be used by the OEMs initial customers. Whereas handsets need to be approved on a variety of networks.

RIL Overview

The RIL provides the interface between the system software and the radio stack that reside within the modem. The system software includes all elements of the Operating System, Windows Mobile. These elements include but are not limited to: TAPI or ExTAPI, SIM Manager, SMS Manager, Dialler, and customer or 3rd party applications.

The RIL services system requests radio functions, including voice, data, and SMS, and provides asynchronous notifications of changes to the system, including signal strength, coverage, incoming voice calls, and incoming SMS messages.

Telephony services within Windows Mobile are defined by the Operating System, each function or service is ideally independent of both the modem and the modem and applications processor interface.

The RIL is designed and built so that Windows Mobile provides a standard interface, API set, and set of call back mechanisms that can be used across different platforms, with the specific details hidden from the remainder of the system.

The overall architecture is presented in Figure 1, Telephony Architecture.

As this diagram shows. all of the interaction between Windows Mobile and the radio stack is through the RIL with the exception of a Point-to-Point Protocol (PPP) connection, that initially uses the RIL to set up the connection and then bypasses the RIL path to allow direct connection to the virtual serial port that is connected to the modem.

The RIL is split into two separate components, a RIL driver that processes AT commands and events, and a RIL proxy that performs arbitration between the multiple clients for access to the single RIL driver. This is shown in Figure 2, RIL Proxy Interface.A separate instance of the RIL proxy is loaded by each RIL client and provides a unique handle to each client. The handle is used to ensure that the RIL invokes the appropriate clients call back mechanism. The RIL proxy does not need modification by the OEM and therefore will not be discussed further in this document.

RIL Modem Interface

The RIL allows hardware abstraction by accepting service requests from the upper layers, mainly from TAPI and ExTAPI, and converts those requests into commands that are supported by the modem, and commands that exchange information over a modem and host processor interface.

The original modem system design dates back over 3 decades and provided a single communications channel over which both AT commands and data were routed. This requires a time consuming switching mechanism between command mode and data mode, and essentially allows only single processes to be active at any time. Advances in networks,for example 2.5G and 3G, now provide multiple simultaneous services, for example data connection to browse the Web, send and receive email, send and receive SMS messages, originate and answer voice calls, poll signal strength, and more. Network advances have outstripped modem interface advances to such a degree that it is necessary to expend effort to maximize throughput by providing support for a multiplexer device driver and multiplexer support in the RIL itself.

Network advances have necessitated modem architecture evolution so that it is usually necessary to expend effort on the modem interface

Some modems provide other interfaces, for example high speed UARTs, USB, and shared memory. The same principles apply to high speed UARTs and USB ports. Access to the modem is still through a standard device driver, serial or USB, with no specific RIL or MUX related functions. A shared memory implementation requires considerable changes to the RIL and is outside the scope of this document.

The simplest interface methods are those that employ a UART or UARTs as depicted in Figure 3, Virtual Serial Port Configurations.

One UART, One COM

This configuration is the simplest configuration that utilizes a single UART, and results in lowest cost and smallest real estate, and is connected to a single UART in the modem. This configuration is no longer supported as it imposes throughput constraints on 2.5G and 3G systems because the modem must be periodically switched between data and command mode.

One UART, Two COM

This configuration utilizes a single UART addressable through two logical and virtual serial ports. This requires support for a multiplexer in both the host system and in the modem itself. The GSM standards define a multiplexer specification that, if adhered to by modem vendors, results in a portable multiplexer device driver. However, this is not always the case and it may be necessary to match the multiplexer capabilities and operation with those supported by the selected modem. Some modems comply fully with the GSM standard, some implement a subset of the GSM standard and some implement proprietary solutions. The effort required to provide a fully functional system with acceptable performance and feature set increases as the modem implementation departs further from the full GSM specification. The development time for MUX support should not be underestimated.

Two UART, Two COM

This configuration provides maximum performance because the potential bottleneck presented by the multiplexer is minimized. In practice, the multiplexer bottleneck is not an issue when this configuration is used on GPRS networks where the maximum throughput rarely exceeds 50 kbps. However, higher speed networks like CDMA, EDGE, and W-CDMA are performance-limited by the multiplexer and care must be taken to ensure that the product performance targets can be achieved by the selected implementation.

Figure 4, RIL and Modem Interface shows the lowest level details of how the RIL communicates with the modem.

This diagram shows that the RIL does not communicate directly with the modem. The final link to the modem is usually the standard serial driver provided by the OEMs platform. The key to flexibility and the reduction of the complexity within the RIL is to migrate the port handling to the MUX driver. This approach is appropriate for both single and dual UART implementations. The RIL should acquire the virtual COM port assignments (VCP) from a registry entry that allows portability between platforms. A link between the RIL and the MUX, for example, a set of IOCTLs, should be implemented to allow the RIL to signal port switching. This approach allows the RIL to continue to use the same VCPs when it sends and receives data independent of the physical ports used on the modem for AT commands or data. Port switching is still required although it appears that RIL and PPP use a constant VCP. This is due to the following architectural issues with the modem.

For example, the modem can be configured for data on port 1, and AT commands on port 2. Once a modem port has been configured for data it may not be used for commands. However, for a data connection to be established on a modem port, that port must be configured by using AT commands, therefore, the original AT command port is no longer available for commands that require the use of a second port for commands. This situation arises regardless of which port is initially configured for AT commands.

A more subtle issue can arise with the Unsolicited Response Codes (URCs ) associated with incoming SMS messages. Some modems insist on associating a single port for both SMS configuration, +CSMS used to select phase 2 or phase 2+ SMS support, and SMS URCs. This is not an issue until port switching described earlier is invoked to set up a data call. At this time, the AT command port, also used for URCs, has changed. However this is a different port than the one used to set up SMSs. This leads to a port mismatch that results in loss of incoming SMS notifications. The solution to this is to reaffirm the SMS configuration on the newly assigned AT command port. This modification must be applied to the RIL to ensure that the SIM card does not fill up with unread SMS messages. It is only the SMS notification that is an issue, not the ability of the modem to receive SMS messages.

The preceding issues are dependant on the specific implementation details of each modem. Care must be taken to architect the system and the port usage for the particular modem selected.

In summary, the implementations described here require suitable support in the RIL to match the modem interface details, the modem port and function assignment, and the multiplexer that must be considered as part of the RIL integration project with its associated time and effort implications.

Development Environment

The development environment is key to ensuring a timely delivery of a quality product, this is particularly important for radio and RIL projects. Typically, the platform is not yet designed and debugged when software resources are available to develop the RIL. Since this leads to a serial development program the project timescale is extended, increasing time to market that imposes a limiting factor on the success of the product. Fortunately this situation can be avoided.

The Windows Mobile development environment includes an emulator that allows a Windows Mobile-based image to be built for execution on a standard PC. Developers can include their own drivers and modules into the system image and run under emulation on the PC. The emulator allows access to the standard interfaces supported by the PC, for example keyboard, serial ports, and more. Most modem vendors provide a modem development board which consists of a modem, SIM card interface (GSM), antenna and serial port(s). Connecting the modem development board to the PC emulator by using a standard serial interface presents the developer with a working system in the absence of the target platform, and this allows the majority of RIL development to be undertaken early in the product development project. Indeed, this is the method used by modem vendors who wish to develop a generic RIL for their particular modem and have a competitive advantage in that their customers are provided with a working base platform.

This approach allows the developer to create and debug a RIL that supports the standard features required by Windows Mobile-based devices, for example voice calls, SMS (GSM), data connections, and more. The emulator environment can also be used for testing and even running the LTK tests. See the Testing section for further details. This environment should be used as the standard development environment, however, it cannot support platform specific features nor can it highlight issues with the platform design, this can only be undertaken when the target platform is available. However, the advantages of adopting this approach are not to be underestimated.

When porting the RIL from the emulator environment to the target platform it is good practice to use build directives within the source code for platform specific features. This has two advantages, firstly, it is a simple build process to revert to the emulator version to verify if faults uncovered are due to the platform implementation or are a problem with the generic implementation, and secondly, a common code base can be used to support different product family variations, greatly reducing multi-product development timescales.

Build Environment

When developing the RIL driver it is useful to setup the build environment to build the RIL separately to the main platform build, this considerably improves the speed of development, because the developer only needs to build a single driver. This also eliminates the need to have the real platform source code available as the RIL can be built under the emulator or Hornet reference platforms.

The first step in creating this build environment is to create a desktop shortcut that uses the bldplat batch file to create a build command prompt window, for example, D:/Pak/PGrine/bldplat.bat -w -cpu ARMV4 -p HORNET -sku GSM -retail.

A retail build window can be used as the RIL debug output is actually controlled by the registry and the WINCESHIP build flag.

The shortcut can then be run to open up the build window with all the relevant platform settings.

Assuming that the full platform image has previously been built the developer can then simply set the current directory to the RIL driver source code directory and type Build –cf to build the RIL driver.

The driver DLL produced can then be copied from the release directory to either a device or into the release directory of the main platform build for inclusion into the OS image.

Usually the build environment is set up with the WINCESHIP environment variable set that limits the RIL debug output to include only the AT commands and responses. When debugging, the developer can clear this flag and set the required debug output level in the target registry.

The following example debug trace shows the lowest level of debug output selected when WINCESHIP is set.

RilDrv: Sending cmd: ATE0V0
RilDrv: Accumulated response: 0
RilDrv: Sending cmd: ATE0V0Q0X4&C1&W
RilDrv: Accumulated response: 0
RilDrv: Sending cmd: AT+CFUN=1;+CMEE=1;+CRC=1;+CREG=1;+CGREG=1;+FCLASS=0;+CLIP=1;+CSCS="GSM"
RilDrv: Accumulated response: 0
RilDrv: Sending cmd: AT+CMGF=0
RilDrv: Accumulated response: 0
RilDrv: Sending cmd: AT+CPIN?
RilDrv: Accumulated response: +CPIN: READY
RilDrv: Accumulated response: +CPIN: READY0
RilDrv: Sending cmd: AT+COPS=0
RilDrv: Accumulated response: 0

Clearing WINCESHIP selects a higher debug output level that shows the API calls and internal RIL operation.

Debug Environment

There are usually several stages of debugging when developing a RIL driver dependent upon the stage of the product, namely:

• Emulator or reference platform
• Prototype device
• Production device
• Approvals/Logo testing

As the product matures debugging can become a problem because the production device may not have the components required to easily facilitate debugging. Therefore, as with most other software development, the majority of debugging needs to be undertaken on reference or prototype devices.

Emulator or Reference Platform

Before target hardware becomes available it is useful to use the Microsoft emulator and/or a reference platform together with the relevant modem to start development of the RIL driver.

The reference platform will usually have an Ethernet debug connection and possibly hardware debug tools. These will allow easy download and single stepping of code on the target device.

The emulator provides the simplest debug mechanism because both the platform code and target device exist on the developers machine and allow drivers and applications to be quickly updated and debugged.

At this stage in development it is usual to debug the AT command strings and their responses.

Prototype Device

The prototype device will be similar to a reference platform in that it should provide an Ethernet debug interface, or one similar, to facilitate debugging of the platform software.

This type of device will allow the developer to work on the hardware and platform specific features, for example modem power control, modem interfacing, and more.

Production Device

The production device is the final stage in the development process and is unlikely to contain the same debugging facilities as the prototype device.

Therefore it is sometimes useful to redirect the RIL debug output to a file on either the device itself or on the developers PC via ActiveSync if no other form of debug connection is available.

The debug statements in the RIL source code are macros, hence it is simple to redirect the output strings to a file instead of the normal output routines.

Approvals and Logo Testing

Approvals and/or Logo testing usually occur after the main development process is completed and is performed on a full production device. Although a full debug interface may not be required at this stage some form of error reporting is usually required, hence, redirecting the RIL output to a file over an ActiveSync connection can be useful.

Enabling some form of debug output on a device can have effects on performance which in turn can affect the overall performance of the device during testing, therefore if debug output is required it is usually best to have a fast debug connection utilizing Ethernet or USB.

The ActiveSync connection can be a good way of sending debug information to the host PC without including an additional hardware interface specifically for debug output.

Platform Implementation

The RIL source code is usually based on the sample RIL provided by Microsoft in the adaptation kit under /public/cellcore/ril/driver, which provides all the mechanisms required to support a standard AT command based modem. For a non-AT command based modem it may be more efficient to redesign the RIL.

The sample RIL provides support for Siemens, TI, and TTPCom based modems, hence modifications will be required to adapt the RIL to the selected modem if not based on one of the above.

Although most modems conform to the GSM or CDMA specifications most manufacturers implement these specifications in similar but not identical ways, hence, although the AT commands may be the same, the actual behavior of the commands may differ. For example AT+COPS=0 on some modems block until the modem has registered (or failed to register) on the network, whereas other modems respond immediately and register in the background.

The Logo Test Kit assumes a particular modem behavior, hence, some modems will require RIL modifications to match the expected behavior.

The most common areas that require modification for each modem and/or platform are:

• Power Management
• Audio Management
• SMS handling
• SIM toolkit
• Own number

Power Management

The power management of the radio is a combination of modem specific and platform specific methods, for example the modem may support power saving modes by using AT commands and/or the platform may provide hardware power control to the modem. These two methods each have their own issues that need to be addressed in the RIL driver.

The AT command options associated with power management are already handled by the sample RIL to some extent in the SetEquipmentState RIL API functions, usually by using the AT+CFUN command. Any proprietary AT commands, or extensions, can also be handled within these functions to provide low power operation.

If any of the low power AT commands stop the AT command parser in the modem, then a mechanism for reawakening the modem will need to be implemented and the RIL may also need to be reinitialized if any of the modem settings are lost.

The hardware power control is a little more complicated as both the RIL and radio will need to be reinitialized when the power to the radio is cycled.

It is necessary to ensure that the OS does not attempt to access the modem while it is powered off and also forces CellCore components, for example SIM manager, to reinitialize when power is reapplied to the modem. When power is required to be physically removed from the modem, on calling SetEquipmentState with the RIL_EQSTATE_MINIMUM power state set, the following sample code needs to be executed after the modem has been powered down.

res.dwReadyState = 0;
g_dwGPRSRegStatus = RIL_REGSTAT_UNREGISTERED;
g_dwRegStatus = RIL_REGSTAT_UNREGISTERED;
pnd = new CNotificationData;
if (pnd) 
{
   if (!pnd->InitFromRealBlob(RIL_NOTIFY_REGSTATUSCHANGED, &g_dwRegStatus, sizeof(DWORD)))
   {
      delete pnd;
      pnd = NULL;
   }
}
pHandle->GetDevice()->BroadcastNotification(pnd);
// Notify the OS of the change in radio power state.
pHandle->GetDevice()->BroadcastRealBlobNotification(RIL_NOTIFY_RADIOEQUIPMENTSTATECHANGED, (void*)&res, res.cbSize);
Sleep(200);
// Signal that RIL is no longer ready.
pHandle->GetDevice()->StopReadyStateQuery();
pHandle->GetDevice()->SendReadyStateNotification(RIL_READYSTATE_NONE, TRUE);
UpdateSIMState(RIL_E_RADIOOFF);

When reapplying power to the modem by requesting the RIL_EQSTATE_FULL state the first AT command sent to the modem should have the CMDOPT_REINIT flag set to force the RIL to reinitialize both the modem and itself.

The RIL driver could also be made to be a power managed driver by adding the .NET power management IOCTLs as would be done for a standard stream device driver. This will allow the radio to be easily powered off and on (or put into a low power mode) during suspend and resume respectively, as well as integrating with the standard power management support in the OS. The power management IOCTLs could either put the modem into a low power mode using AT commands or switch off the power to the modem as described above.

The following sample code shows the power management IOCTLs that need to be added to the RIL driver to make it a power managed device:

BOOL RIL_IOControl(DWORD dwOpenData, DWORD dwCode, PBYTE pBufIn, DWORD dwLenIn, PBYTE pBufOut, DWORD dwLenOut, PDWORD pdwActualOut)
{
   . . .
   // Handle the power management IOCTLs.
   case IOCTL_POWER_CAPABILITIES:
   {
      TBD_OUTPUT(TBDCT_INFO, TBDOL_INFORMATION, TEXT("RIL_IoControl: IOCTL_POWER_CAPABILITIES"));
      // Copy the supported power modes to the output buffer.
      memcpy(pBufOut,  pHandle->GetDevice()->GetPwrCapabilies(), sizeof(POWER_CAPABILITIES) );
      dwOutUsed = sizeof(POWER_CAPABILITIES);
      fRet = TRUE;
      break;
   }
   case IOCTL_POWER_SET:
   {
      DWORD dwPwrState;
      DWORD dwError;
      dwPwrState = *(DWORD *)pBufIn;
      TBD_OUTPUT(TBDCT_INFO, TBDOL_INFORMATION, TEXT("RIL_IoControl: IOCTL_POWER_SET (0x%X)"), dwPwrState);
      // Set the requested power mode.
      pHandle->GetDevice()->SetCurrentPwrState(dwPwrState);
      fRet = TRUE;
      break;
   }
   case IOCTL_POWER_QUERY:
   {
      TBD_OUTPUT(TBDCT_INFO, TBDOL_INFORMATION, TEXT("RIL_IoControl: IOCTL_POWER_QUERY"));
      fRet = TRUE;
      break;
   }
   case IOCTL_POWER_GET:
   {
      TBD_OUTPUT(TBDCT_INFO, TBDOL_INFORMATION, TEXT("RIL_IoControl: IOCTL_POWER_GET"));
      // Get the current power mode.
      *(DWORD *)pBufIn = pHandle->GetDevice()->GetCurrentPwrState();
      dwOutUsed = sizeof(DWORD);
      fRet = TRUE;
      break;
   }

The actions performed by these power management functions are implementation specific and would either send a power saving AT command or switch the power to the modem on or off depending on the power mode requested.

Audio Management

The RIL is responsible for adjusting the volume of the voice signals from the modem and selecting which audio device is currently in use. This is normally undertaken using AT commands to adjust the modem settings, however, some platforms may have external audio hardware to make these changes and in these cases the RIL will need to either access the hardware directly or, preferably, to access another device driver.

The following APIs show the audio support functions within the RIL.

Function	Description
HRESULT RILDrv_GetAudioGain(DWORD dwParam)	Retrieves the current incoming and outgoing voice level settings.
HRESULT RILDrv_SetAudioGain(DWORD dwParam, const RILGAININFO* lpGainInfo);	Sets the volume of both the incoming and outgoing voice levels.
HRESULT RILDrv_SetAudioDevices(DWORD dwParam, const RILAUDIODEVICEINFO* lpAudioDeviceInfo);	Selects the type of audio device currently in use (either. Handset, Headset, Speakerphone, or Carkit)
HRESULT RILDrv_GetAudioMuting(DWORD dwParam);	Retrieves the current muting settings.
HRESULT RILDrv_SetAudioMuting(DWORD dwParam, BOOL fEnable);	Enables or disables the muting of the outgoing voice signal.

The OS will normally call the gain setting functions when the user adjusts the volume slider during a voice call, but they will also be called when the current audio device is changed as each device requires a different relative volume.

The audio device is normally selected via the profiles subsystem as there is a different profile for each audio device and a particular profile is selected when its device is either inserted or selected.

The profiles subsystem is included by default in the Windows Mobile-based Smartphone version of the OS, however, when developing for Windows Mobile-based Pocket PC the OEM either has to implement the audio profiles or an alternative method can be devised.

One way of implementing this is to create an audio device manager that monitors the state of each audio device and calls the RIL to change settings when either the device is inserted or the user selects a different audio device via a control panel.

SMS handling

The sample RIL supports GSM SMS phase 2 mode 2, however, if this is not supported by the modem then the handling of SMS messages requires modification. For example, to support SMS phase 2+ additional code with the RIL is required to send the SMS acknowledge AT command (+CNMA) after each incoming SMS notification.

SIM toolkit

The SIM toolkit support in the sample RIL is designed around the Condat and TTPCom AT command set. Many modem manufacturers implement their own proprietary AT command extensions for SIM toolkit commands, hence, some work may be required to convert the radio command to what the OS is expecting. This can be quite complex if the modem implements vastly different SIM toolkit functionality as considerable changes to the parsing of the commands will need to be added within the RIL.

The standard SIM toolkit functions implemented in the RIL are:

HRESULT RILDrv_GetSimToolkitProfile(DWORD dwParam);
HRESULT RILDrv_SetSimToolkitProfile(DWORD dwParam, const BYTE* lpbProfile, DWORD dwSize);
HRESULT RILDrv_SendSimToolkitCmdResponse(DWORD dwParam, const RILSIMTOOLKITRSP* pRsp, LPBYTE pDetails, const DWORD dwDetailSize);
HRESULT RILDrv_TerminateSimToolkitSession(DWORD dwParam, DWORD dwCause);
HRESULT RILDrv_SendSimToolkitEventDownload(DWORD dwParam, const DWORD dwEvent, LPBYTE pData, const DWORD dwDataSize);

The RIL is required to pass the following notifications to the OS to inform it of various events, the OS will then call the preceding APIs to perform the required actions:

Notification	Description
RIL_NOTIFY_SIMTOOLKITCMD	Indicates that a SAT command is waiting to be executed.
RIL_NOTIFY_SIMTOOLKITSESSIONEND	Indicates that the current SAT session has been terminated.
RIL_NOTIFY_SIMTOOLKITCALLSETUP	Indicates that the SIM application wants to make a call.

If the SIMUI component detects any user interaction with the user interface, for example select a menu option, this is transmitted to the SIM application by means of the RILDrv_SendSimToolkitCmdResponse API.

The SIMUI can also terminate the current SAT session by calling the RILDrv_TerminateSimToolkitSession API.

The SIMUI will also transmit Event Download events by calling the RILDrv_SendSimToolkitEventDownload API.

Usually the modem uses an unsolicited notification of some form to indicate to the RIL that a SAT command is waiting. If this is not the case then the OS can be configured to poll for SAT commands by setting the appropriate option in the RIL_CAPSTYPE_SIMTOOLKITNOTIFICATIONS of the RILDrv_GetDevCaps API. If polling for SAT commands is needed, support for the RIL_FetchSimToolkitCmd API will also need to be implemented within the RIL. The RILDrv_GetDevCaps. The RILDrv_GetDevCaps structure is also used to determine which SAT commands are to be executed by the OS and which will be executed by the radio.

Own Number

Many modems do not implement the +CNUM AT command. When the +CNUM AT command is not implemented, it can cause problems when the OS attempts to fetch the modems own phone number. This is because the phone application in Control Panel will display unavailable. To avoid this, the RIL can be modified to obtain the own number from the SIM phonebook by selecting the own number phonebook, however, this is SIM/Network operator dependent, hence, some SIM cards may not include any entries in this phonebook.

The following simple example shows how to fetch the own number without using +CNUM:

DWORD CRilHandle::FetchOwnNumber()
{
   APIINFO apiiInfo;
   APIID apiid;
   CCommand* pCmd;
   char szCmd[MAX_PATH];
   // Clear the global list of subscriber numbers
   memset((void*)&g_rsi[0], 0x00, sizeof(RILSUBSCRIBERINFO));
   // Get the information about this API.
   apiid = APIID_OWNNUMBER;
   memset(&apiiInfo,0,sizeof(apiiInfo));
   GetAPIInfo(apiid, apiiInfo);
   // Select the own number phonebook.
   pCmd = new CCommand;
   if (!pCmd || !pCmd->Init(NULL, "AT+CPBS=/"ON/"/r", NULL, CMDOPT_NONE, apiiInfo.dwExecTime, apiiInfo.dwTimeout, NULL, NULL, 0, 0, 0, apiid))
   {
      TBD_OUTPUT(TBDCT_INFO, TBDOL_ERROR, (TEXT("FetchOwnNumber : Unable to construct or Init CCommand")));
   }
   g_pCmdQ->Put(pCmd, INFINITE);
   // Check if there are any phonebook entries.
   pCmd = new CCommand;
   if (!pCmd || !pCmd->Init(NULL, "AT+CPBR=?/r", NULL, CMDOPT_NONE, apiiInfo.dwExecTime, apiiInfo.dwTimeout, NULL, ParseGetNumPBEntries, 0, 0, 0, apiid))
   {
      TBD_OUTPUT(TBDCT_INFO, TBDOL_ERROR, (TEXT("FetchOwnNumber : Unable to construct or Init CCommand")));
   }
   g_pCmdQ->Put(pCmd, INFINITE);
   // Wait for command to complete.
   if(WAIT_OBJECT_0==WaitForSingleObject(g_hCPBREvent, 2000)) break;
   // Read the list of numbers.
   (void)_snprintfz(szCmd, MAX_PATH, "AT+CPBR=1,%d/r", g_iNumPBEntries);
   pCmd = new CCommand;
   if (!pCmd || !pCmd->Init(NULL, szCmd, NULL, CMDOPT_NONE, apiiInfo.dwExecTime, apiiInfo.dwTimeout, NULL, ParseGetOwnPBEntries, 0, 0, 0, apiid))
   {
      TBD_OUTPUT(TBDCT_INFO, TBDOL_ERROR, (TEXT("FetchOwnNumber : Unable to construct or Init CCommand")));
   }
   g_pCmdQ->Put(pCmd, INFINITE);
   pCmd = new CCommand;
   // Reset to using normal SIM phonebook.
   if (!pCmd || !pCmd->Init(NULL, "AT+CPBS=/"SM/"/r", NULL, CMDOPT_NONE, apiiInfo.dwExecTime, apiiInfo.dwTimeout, NULL, NULL, 0, 0, 0, apiid))
   {
      TBD_OUTPUT(TBDCT_INFO, TBDOL_ERROR, (TEXT("FetchOwnNumber : Unable to construct or Init CCommand")));
   }
   g_pCmdQ->Put(pCmd, INFINITE);
  return 0;
}

Additional modifications

In addition to adapting the RIL driver to the modem, the following additional modifications can be made to enhance the platform or radio functionality.

• Hardware abstraction layer

  One useful change to the RIL is to add another software layer below the RIL to handle all hardware specific functionality, this can be important where the source code to the RIL cannot be shipped but the customer requires some level of platform dependent modification.

  This extra layer would be in the form of a standard DLL which the RIL can load using LoadLibrary and would provide an API for accessing the radio hardware.

  The main functionality included in this layer would be

  • Radio power control
  • Audio routing
  • Audio codec control

  A simple example API could look something like this

  BOOL HAL_SwitchRadioPower(BOOL fRadioPower);
  BOOL HAL_IsRadioPowerOn(void);
  BOOL HAL_SetAudioPath(DWORD dwTxAudioMode, DWORD dwRxAudioMode);
  BOOL HAL_SetTxAudioVolume(DWORD dwAudioMode, DWORD dwVolume);
  BOOL HAL_SetRxAudioVolume(DWORD dwAudioMode, DWORD dwVolume);

  The RIL would call these APIs at the appropriate point within the standard RIL APIs.

• GSM 27.10 Multiplexer

  The GSM 27.10 multiplexer is a useful extension to the standard modem interface as it can provide multiple concurrent channels to the modem allowing the RIL to perform several functions simultaneously.

  The main advantage of the multiplexer is that it allows AT commands to be sent to the modem without interrupting the data stream during an active data connection. This simplifies the handling of voice calls and SMS during a data connection.

  The multiplexer essentially emulates a dual serial port modem as it provides several virtual modem/COM port interfaces to the upper layers whilst using a single physical serial interface.

  The multiplexer is usually implemented as standard stream device driver and is similar to a serial driver and the RIL and TCP/IP stack each open their own instance of the virtual COM port interface.

  Additional interfaces can be opened for specific purposes, for example, unsolicited notifications.

  As the multiplexer presents a standard COM port interface there is little additional modification required to the RIL to support the multiplexer.

  If any additional functionality is required from the multiplexer then the standard IOCTL interface can be used to perform the required operation.

  For example, the following IOCTLs would normally be implemented to control the multiplexer.

  • IOCTL_MUX_ENABLE - Enable the multiplexer in the modem and establish the channels
  • IOCTL_MUX_DISABLE - Free the channels and disable the multiplexer in the modem

  The individual channels would normally be configured when opening the associated virtual COM port with one DLCI being allocated to each port. These channels would then be established by the enable IOCTL described above which, in turn, would be called by the RIL after initialization.

  Additional IOCTLs could be added to dynamically establish additional data link connection identifiers (DLCIs) if required.

• RIL Extensions

  The standard RIL API can be extended using the RIL_DevSpecific API.

  A pointer to a parameter block is passed to this function. The first DWORD in this block is used as a function ID to call a specific function. The remainder of the parameter block is passed to that function as its parameters.

  An example parameter block could look something like this:

  typedef struct tagRILDevSpecificParams {
     DWORD dwFunctionID;
     BYTE *lpInputParameters;
     BYTE *lpOutputParameters;
  } RIL_DEVSPECIFIC_PARAMS;

  The two-byte pointers would point to a buffer of parameters to be passed to the given function in a similar way to the standard IOCTL interface.

  These additional RIL functions can implement proprietary AT commands for specific OEM radio applications.

  A wrapper DLL can also be created to present a simpler API to the application layer, this DLL would contain all the RIL calls required to access the RIL APIs thus removing this burden from applications and also hiding the RIL API from the upper layers.

  The wrapper DLL could provide a TAPI like API in the form of lineXXXXXXX style functions.

  A popular RIL extension for many modem manufacturers is to provide a generic AT command function that allows any AT command to be sent from an application directly to the modem. This type of extension is normally only used for GSM approvals and modem testing and would not normally be allowed in normal operation as this type of function could adversely affect the CellCore stack.

• Version control

  Another useful addition to the RIL is to add a version resource to the build, this allows the version number to be easily viewed from Windows Explorer and can be accessed by other applications. This resource can also be linked to the standard RIL version IOCTL to maintain compatibility with the existing version control. The version number can then be read and displayed by a Control Panel Applet (CPL).

  This technique can also be applied to all the other DLLs associated with the RIL, the RIL will then be able to check the version numbers of the extension DLLs to ensure the correct version is installed.

Testing

RIL testing is split into the following main sections

• Standard development testing
• Operator testing
• Logo Test Kit (LTK) testing
• Radio quality metric testing

Standard development testing

This requires test procedures and test suites to be developed in the same way as any development project with the tests and test environments being designed to match the specific project. RIL projects generally require the following test environments to be applied as early as possible during the development process.

Test Procedures

Although Microsoft provides a test environment it is good practice to create a project specific test procedure. Experience has shown that creating an extensive test procedure results in a smoother passage through LTK testing in that all basic issues and most combinatorial test issues have already been resolved prior to running the LTK.

It is imperative that a comprehensive test procedure be created to ensure that all boundary conditions and combinatorial conditions are correctly handled. The asynchronous nature of wireless networks requires consideration to be given to unpredictable events or sequences of events. Such examples include:

• Incoming voice call,SMS, and voice mail notifications during other activities, for example, actively downloading data during a GPRS connection.
• Out of coverage during a data call.
• No SIM card present.
• Unit power down during voice or data calls.

The general robustness of the system needs to be qualified with repeated tests. It is necessary to perform repeated tests to ensure good testing practices are adhered to, however, wireless networks are not static and not totally predicable, some failures to connect, dropped calls, etc. are to be expected. Although these issues should be minimal, it should be realized they do exist and care should be taken when interpreting the results to ensure network issues are not mistaken for platform implementation problems.

Examples of repetitive tests include:

• Originate 50 voice calls in succession.
• Send 50 SMS / MMS (where MMS is supported) messages in succession and check all 50 have been received at the target number.
• Receive 50 SMS / MMS messages ensuring all are received correctly and SIM card overflow does not occur.
• Web page browsing with automatic refresh enabled and active for 10 hours.
• Receive 50 SMS / MMS messages during an active data connection.

Emulator

The emulator coupled to a modem development station provides an ideal initial test environment ahead of the platform itself being available. The emulator can be used for most testing aspects, for example, voice, data, SMS, live networks, test networks, and LTK. The availability of this test environment should be maximized during the development phase.

Modem vendors usually use the emulator as their test environment when subjecting the device to the LTK radio tests. However, OEMs with specific platforms into which the modem is embedded must fully test on the platform both during in-house proving and formal LTK submission. See sub-topic, "Platform Specific".

Platform Specific

It is unlikely that some platform-specific features can be tested on the emulator, for example audio profiling external to the modem, audio path routing, power management, and others.

It is imperative to test on the target platform as soon as possible to ensure not only that platform-specific features are working correctly but also to ensure the overall system performance is acceptable.

The system performance aspects include:

• RF Performance

  RF performance is key to any wireless product. A poorly designed RF implementation can result in degraded system performance with loss of service under low signal strength conditions. The emulator system usually has a modem development station in its own enclosure and use of an external antenna that masks RF issues. The emulator provides a useful reference system against which the target platform can be measured to help identify if the problem lies with the platform or the generic RIL implementation.

• Battery

  The emulator environment is mains-powered, which masks any potential issues associated with supply voltage, power supply noise, and voltage reservoir effects. It is necessary to test the target platform on battery power and wall charger and external supply.

Operator Testing

Although internationally agreed specifications exist for both GSM / GPRS and CDMA networks many development and deployment issues are associated with differences between networks. It is not uncommon to find that some of the supplementary features are supported differently across a range of networks, for example, call forwarding, call baring, conference calling, SMS delivery notifications, etc., and in exceptional circumstances GPRS connection methods can differ, for example, a small number of servers attempt to authenticate the user at the time the AT+CGACT command is sent rather than authenticating at the time of connection.

Testing should be conducted on the network(s) known to be used when the product is deployed. However, it is good practice to repeat the tests on as wide a range of networks as possible depending on network availability. It is common practice to purchase a number of SIM cards for a variety of networks (GSM) or have subscriptions to a number of CDMA carriers to be used exclusively for RIL testing. It is also advisable to use both contract and pre-pay SIM cards. The cost of the live network testing should not be underestimated, it is likely that hundreds of voice calls, data connections and SMS messages will be undertaken over the project lifecycle.

Live network testing is the most representative test environment, however, it is also advisable to make use of test stations during the development. This is mandatory if the modem is not yet certified, although this is rarely the case. The test station should also be used to ensure compliance with Emergency Number support, emergency agencies are not impressed with false calls, and in some countries it is a criminal offence to place a false emergency call. The test station can be used to exercise the system under extreme conditions, for example, receive 1,000 SMS messages, receive 100s of voice calls, receive SMS messages during GPRS connections, and so on. Combining a test station with automated test software on the target platform provides a powerful test environment not achievable on live networks. Test stations are expensive ($10,000s) however, they do represent an invaluable test capability and should be used where possible.

Logo Test Kit (LTK) testing

LTK testing is a key part of the Windows Mobile test environment. A product must be subjected to and pass the LTK before the product can be shipped. Although the LTK is not designed to be a replacement for in-house test procedures it provides an out of the box test suite that can be used to test the RIL immediately.

The LTK for Windows Mobile-based devices includes the Microsoft radio test suite which uses a single test program, Radiotest.exe, and an associated test condition file Radiotest.ini.

The Microsoft radio test suite is intended as a simple mechanism to test basic wireless scenarios, for example:

• Packet data throughput and stability
• Incoming / outgoing voice call reliability
• Supplementary services
• SIM management

The radio test suite is fully configurable and permits either a broad coverage test to be run or specific scenarios. The ability to run tests randomly is also included, this is particularly useful for identifying combinatorial issues.

The tests included in Radiotest.exe and a sample test run output are shown in figures 7 and 8. The TARGET value represents the percentage pass rate required to pass a specific test. Networks can cause errors and failures that should not be confused with failures of the equipment under test, hence, the Radiotest.exe accounts for this by allowing typically 5% - 10% failure rates on most tests.

The LTK process includes the following:

• In-house execution

  The LTK is a useful test tool during development to be used when appropriate. However, the tests must be formally executed and recorded prior to formal NSTL submission, and the appropriate resources and time need to be allocated for this task. Any issues arising should be discussed with Microsoft and need to be either resolved or handled with waivers.

• Waivers

  Ideally all devices and systems should pass the full compliment of LTK tests. However, this is not always possible. If a non-compliance occurs, it is necessary to discuss the issue with Microsoft and reach agreement. It is possible that a waiver will be granted for a specific test issue, for example, the modem only supports SMS Phase II+, whereas the LTK specifically tests for SMS Phase II.

• Formal Submission

  The Microsoft radio test suite is an OEM verify test case whereby each OEM runs the test cases, saves the log, and submits that log to NSTL for final approval. To remain independent and impartial, the NSTL team will not issue accreditation unless all tests are passed or Microsoft has issued waivers for agreed, specific non-compliances.

  Details of the NSTL submission requirements and conditions can be found at http://www.nstl.com/logoprogram/win_ce_logoprograms.html.

Radio Quality Metric Testing

Microsoft provides another test executable, Radiometrics.exe, that is similar to Radiotest.exe. The Radiometrics.exe test provides additional functionality to derive quality metrics, for example, the missed call rate. Different INI files are used to derive different metrics.

INI File	Test Functionality
call_hold_conf_metric.ini	25 conference calls, 25 calls to a busy number, 25 dial and hang-up and 25 incoming calls.
general_func_metric.ini	One call to each CellCore API, similar to LTK test.
general_stress_metric.ini	24-hour test consisting of random API calls.
gprs_perf_metric.ini	20MB transfer with connect/disconnect every 1MB.
gprs_stability_metric.ini	~=13MB transfer in small blocks with intermittent sleeps, voice calls and connect/disconnect.
sms.ini	Send and receive 100 multipart messages.
supp_service_metric.ini	25 calls to each SS API.
voice_call_metric.ini	1000 outgoing/incoming phone calls.

Microsoft uses the Radiometrics.exe as a mechanism to determine relative quality of specific radio modules and firmware. Upon receipt of a module or build the entire suite detailed above will be run using the network available in Redmond and bugs discovered logged with the vendor.

New Features in Windows Mobile 5.0

The mobile device market is rapidly evolving worldwide with the deployment of new network technologies, new operator services, and new applications. To keep pace with these market forces, Windows Mobile software must adapt and innovate. Windows Mobile 5.0 includes substantial new features some of which directly impact CellCore and RIL drivers.

WWAN NDIS Packet Data Interface

Microsoft Smartphone 2002 products create GPRS and 1x data connections on demand. The connections provide modest data throughput, are required infrequently, and are discarded when idle or when a voice call is active. The dial-up modem model traditionally used with CDMA and GSM radio modules is adequate to support this level of data connectivity.

In Windows Mobile 2003-based Smartphone Microsoft improved the behavior so that GPRS and 1x data calls would not be discarded when the device is idle or during a voice call. This reduced the number of times the user or an application would have to wait for a data connection to be dialed before transferring packets. The dial-up modem model is still used in this release.

Going forward, Windows Mobile software is moving to an always-connected model for GPRS and 1x data connections. The system software will maintain, within certain parameters, that these data connections are constantly connected and available for use by applications. This is closer to the model of a traditional Ethernet or WiFi interface. Additionally, as packet data rates increase, the overhead associated with PPP becomes a factor.

For these reasons Microsoft is adding support for wireless packet data connections to transition to the Network Driver Interface Specification (NDIS).

Microsoft will provide a Wireless Wide Area Network (WWAN) miniport driver implementation suitable for use with cellular radio packet interfaces. The source code will be provided for this component as part of the Adaptation Kit, and it will be modifiable by Adaptation Kit licensees. Modification will not be typically required because all radio specific details of the implementation will be encapsulated in the RIL driver.

One instance of the WWAN miniport driver will be bound to NDISUIO for the purposes of configuration and control of WWAN connections. Other instances of the WWAN miniport will be created for each of the various packet connections exposed by the cellular radio. This will allow the RIL driver to expose multiple IP interfaces simultaneously. Documentation of NDISUIO is readily available in MSDN.

The RIL driver will typically need a new channel to communicate packets to the cellular radio. This channel can take the form of a shared memory buffer, MUX packet channel, or other packet transport means. AT commands are not suitable for the transfer of packets.

WWAN NDIS Buffer Management

In order to ensure high packet throughput, it is important to minimize the number of buffer copies, allocations, and deletes. For this reason Microsoft has carefully designed the interface between the WWAN miniport driver and the RIL driver to allow for buffer reuse, and to eliminate the need to copy packet buffers in memory. RIL drivers should be implemented with the same goal in mind.

When an IP packet is sent from the WWAN miniport driver to the RIL driver, it is passed in to RIL_NDIS_SendPacket as a list of pointers to buffers. The asynchronous completion of this function indicates to the WWAN miniport that the buffers are no longer required, and may be reused or destroyed.

When an IP packet is received from the RIL driver, it is passed up with a RIL_NOTIFY_NDIS_PACKETRECEIVED notification and a corresponding list of pointers to buffers. These buffers must not be modified or destroyed by the RIL driver until the WWAN miniport has indicated that the buffers are no longer needed. This is indicated by using RIL_NDIS_ReceivePacketDone.

WWAN NDIS Flow Control

Flow control will be used to prevent the WWAN miniport from flooding the RIL driver with outbound packets. When the RIL driver hits a high water mark it can prevent further packets from being transmitted via RIL_NOTIFY_NDIS_XFERSTATUSCHANGED RIL_NDIS_XOFF. When some packets have been sent and a low water mark is reached then the RIL driver can request more packets by using RIL_NOTIFY_NDIS_XFERSTATUSCHANGED RIL_NDIS_XON. The high and low water marks will vary for each RIL implementation, and should be tuned to the characteristics of the packet radio network.

WWAN NDIS Multiple APN Support

Microsoft is adding support to Windows Mobile software for multiple data connection scenarios. This will include support for more than one concurrent active GPRS context via the WWAN NDIS packet interface. RIL drivers will report the maximum number of simultaneous active contexts via a capability.

Always On Connection Support

Connection Manager is the component responsible for determining when data connections should be established and torn down. In was originally designed to bring up data connections upon request from an application, and to terminate the connection when the application had completed its transaction.

With operator and end user requirements evolving and the continuing trend to more affordable data plans, it makes sense to move to an always-connected data model. Microsoft is altering Connection Manager to align with this model.

Always On Configuration

Connections are provisioned using XML. To allow configuration of Always On connections, a new parameter is supported for the following connection types:

• NDIS based GPRS
• PPP based GPRS
• PPP based CDMA 1x
• Ethernet adapters
• WiFi adapters
• Desktop pass-through (DTPT)

By default the Windows Mobile connection control panel will configure one Internet GPRS or 1x call as always on, and all Ethernet, WiFi, and DTPT connections as always on.

The following sample XML shows how to configure an Internet GPRS entry as always on using WAP provisioning.

Always On connection availability

There are circumstances when always on connections will not be available because of the lack of some required resource, or because Connection Manager has determined that it is appropriate to bring the connection down. Some of these circumstances are summarized in the following list:

• When the connection requires network coverage and that coverage is lost. For example, when the user turns off the radio by enabling Airplane Mode.
• When Connection Manager determines that the always on connection must be brought down to free up the cellular radio for use by another higher priority connection request. For example, an always on GPRS call to the internet may be brought down to allow a circuit-switched RAS call to the work network.
• When Connection Manager determines that the always on connection must be brought down for security reasons.
• When a remote disconnect occurs due to network error or remote timeout
• When a connect attempt fails.

Connection manager will attempt to establish any disconnected always on connections based on events occurring in the system such as the following:

• The device boots up.
• A network card gets an IP address.
• The device registers on a network.
• GPRS attaches.
• The device is cradled.
• Connection configuration for an always-on connection changes.
• After a failed connection attempt a timer interval expires causing a retry.
• When a connection that was using the cellular radio is disconnected.

Piggyback Connections

Connection manager allows for applications to request to be informed whenever a connection is available. These connections requests are referred to as piggyback connection requests because they cannot cause a connection to be established on their own, instead they must depend on another application to dial the data connection.

The always on feature changes for Connection Manager allow these piggyback requests to be connected whenever an always on connection is available even if no other application is using that connection. This means whenever a network card is available or an always on GPRS connection is established, piggyback requests will be connected.

Multiple Connection Support

Historically Connection Manager has tried to avoid multiple IP interfaces being available at the same time. This was done for security reasons and also to ensure that there is no ambiguity in how packets should be routed.

Connection Manager is being redesigned to support multiple simultaneous data connections. This will allow for multiple APN GPRS support, and for scenarios such as concurrent GPRS and WiFi connections.

To make this work, Microsoft has created a new module AutoBind_LSP.dll.

AutoBind LSP

The AutoBind LSP is a WinSock Layered Service Provider (LSP). When an application makes a Connection Manager connection request, Connection Manager determines which IP interface the application should use to reach the destination network requested. Connection manager passes this information along with the process ID to the AutoBind LSP.

If the application does not explicitly bind its sockets to an interface, then the AutoBind LSP will implicitly bind the sockets to the interface specified by Connection Manager, ensuring that the packets sent over the socket will take the correct route to reach the intended destination.

It is still possible for applications to override this behavior by explicitly binding sockets to the desired interface before connecting. In this way it is possible for a single application to have open sockets on multiple IP interfaces.

Secure Connections

In an environment where there are multiple IP interfaces available simultaneously, there is a possibility that applications or the operating system may route packets between interfaces. If one of the interfaces is behind a firewall or disconnected entirely from the public Internet, bridging packets may introduce a security threat.

In order to mitigate this threat, Connection Manager is adding the concept of secure connections. When Connection Manager needs to connect a secure connection, it first disconnects all other IP interfaces. If other IP interfaces appear during a secure call, then Connection Manager disconnects the new IP interface. If Connection Manager is unable to disconnect an IP interface before or during a secure call, then Connection manager will fail the disconnect and fail the secure call.

The method of disconnection varies by connection type, but includes hanging up RAS calls, deactivating GPRS contexts, and unbinding network interfaces.

Connections can be provisioned through XML to be secure, as shown in the following sample WAP provisioning XML for a VPN connection to work.

Call Progress Notifications

The ability to notify the upper layer software of changes in call state has been added to Windows Mobile 5.0 through a notification mechanism.

When call progress notifications are available, the CellCore TAPI Service Provider will greatly reduce the amount of polling it does of the RIL driver for call status. The frequency of CLCC and CPAS enquiries is greatly reduced which results in enhanced overall reliability and system performance.

The capability of the RIL to support call progress notifications is tested by the upper layers through a new capabilities RIL_CAPSTYPE_CALLPROGRESSNOTIFICATION that has been added to the RILDrv_GetDevCaps in caps.cpp.

Although it is not mandatory, all parties creating derivative RIL drivers are strongly encouraged to implement this feature.

The sample RIL provides examples for two types of implementation based on different modems.

%CPI Implementation

The first example, for TI based radios, uses the %CPI notification. The CPI notification contains detailed information about the call state and is a superset of information provided in the CLCC response. The sample RIL driver requests that notification is sent using mode 3 of the CPI response that contains the highest level of detail. This is requested at initialization with the AT command string %CPI=3. In this mode the notifications are of the format:

%CPI:,,,,,[],[],[],[], [],

where the parameters are defined as follows.

Parameter	Description
cld	Integer call identification number as described in GSM 02.30
msgType	Layer 3 message type
ibt	Status of the usage of in-band tones
tch	Traffic channel assignment
dir	Direction of call
mode	Call mode (voice/data/fax/etc.)
number	Number of connected call
toa	Type of address
alpha	Alpha identifier of call if in phonebook
cause	call control cause value (generally used for disconnect codes)
line	Line 1 or 2

The information is parsed and put into a RILCALLINFO structure that is the same type used to store information received in the call list response (+CLCC). This structure has been extended in Windows Mobile 5.0 to include the disconnect code element.

Single Notification Code Implementation

The second example in the sample RIL works with TTPCom based radios. This is a much simpler notification that indicates, via a single integer code, that a call state change has taken place. This is enabled at initialization by the AT command +EXUNSOL="UR",1.

The notifications are of the format:

+CGURC: 

The following table shows the possible values that event code can be set to, and describes what each value means.

Value	Description
0	Active call cleared with held calls
1	Attempting to make an MO call
2	MO Call has failed for some reason
3	MO call is ringing
4	MT call is queued (Call waiting?)
5	M0 call now connected
6	M0/MT call has disconnected
7	MO/MT call hung up
8	MO call emergency only
9	MO call No Answer
10	MO call Busy

Only events 2, 5, 6 and 10 are processed by the RIL driver. For events, 0, 1, 2, 3, 4, 5, 6, 7, 8 and 9, a simple notification is sent upstream, RIL_NOTIFY_CALLSTATECHANGED. This will trigger a poll for the call list that allows the upper layers to identify the change in call state.

For the Busy condition, event 10, the RIL driver sends up a RILCALLINFO structure with the disconnect code appropriately set.

Connection Manager Provisioning

The main goal of this feature is to simplify the Connection Manager XML provisioning model and also make it consistent between Windows Mobile-based Smartphone and Pocket PC. This is done by enabling continuous provisioning of connectivity settings through the standardized OMA DM SyncML based connectivity objects. The SyncML connectivity objects provide a much simpler and, at the same time, a very scalable XML definition to add new types of network settings. It also enables some key operator requirements that are not supported by current XML such as mapping specific applications or port numbers to specific network connectoids.

Support will also be provided for existing Connection Manager XML and APIs to enable boot-strapping and preserve backward compatibility.

Provisioning Scenarios supported

Scenario 1: Provisioning of cellular and other data connections

This includes provisioning of the following types of connections:

• CSD connections on GSM and CDMA networks,
• GPRS connections,
• 1xRTT connections,
• WiFi based connections,
• Desktop Passthrough (DTPT) connections.

  The current provisioning mechanism defines a unique XML characteristic for each connection type listed above. The OMA DM standard defines a SyncML object called NAP that cane be used to configure various data connection types and distinguish them based on bearer types.

  Scenario 2: Provisioning of destination networks based on URL domains

  Current provisioning XML defines an XML characteristic (CM_Networks) to specify destination networks that can be reached by multiple connectoids and proxy/VPN connections. It also defines another XML characteristic (CM_Mappings) to specify the URL Domain mappings for each of these destination networks that is used to determine which URLs can be accessed through each of these networks.

  In the new XML model, a new object called ACCESS is defined that signifies one or more domains (the collection of which can be considered a destination network) which can be reached by multiple connectoids in some cases (for example, Internet) or only be reached by a particular connectoid (for example, MMS). It can also support having multiple work networks (for example, MS-Corporate, Boeing-Corporate) that can be reached by different sets of network connectoids. Because ACCESS enables specifying multiple domains under each entry, it can be used to add as many URL exceptions as required for each defined network in addition to the standard URL mappings.

  Another advantage of using ACCESS is that, in addition to supporting URL domain mapping based destination networks, ACCESS also supports destination networks based on specific applications or port numbers. This is covered in next scenario.

  Scenario 3: Provisioning of application specific and port number specific connection preferences

  The new connectivity object ACCESS enables specifying the data connections to be used by individual applications or any applications using specific port numbers. Current provisioning mechanism does not provide any means to specify connection preferences on an application specific or a port number specific basis.

  Scenario 4: Provisioning of proxy and VPN connections

  Current provisioning XML uses special characteristics called CM_ProxyEntries and CM_VPNEntries to define proxy and VPN connections respectively.

  SyncML defines a characteristic called PROXY to define proxy connections. PROXY can be used to define proxy connections that apply to one or more connectoids. Thus a proxy to Internet from Corporate Network can be provisioned by listing all the connectoids that connect to Corporate Network under PROXY. Also a new object called VPNDEF has been defined to support VPN connection settings.

  Scenario 5: Provisioning of Connection Planner

  Current provisioning XML enables provisioning of connection planner including cache time, retry count, and connection preferences for each destination network. This data is used by Connection Manager for setting up and releasing connections.

  Connection Planner is a completely Microsoft-specific component used by the Connection Manager in the decision-making logic for establishing connections, so a proprietary XML object called CMPLANNER has been defined to support planner related entries.

SIM ToolKit Changes

There have been two main changes to SIM ToolKit support in Windows Mobile 5.0

• Redesign of RIL/SIM toolkit layer interaction
• SIM toolkit 99 support

RIL/SIM ToolKit Interaction

The initial implementation of SAT support in Windows Mobile-based Pocket PC/Smartphone was written specifically for one radio vendors implementation, which resulted in radio specific code being in layers above the RIL and the need for a specific SAT component for every different radio stack implementation. With this original approach, as the number of radio stacks supported grew, supporting SAT was becoming more and more difficult. To solve the problem, SAT was re-architected to move all radio specific support and parsing down to the RIL layer and a generic SAT interface between the RIL and SAT layers was created. This allows for radio specific code to be completely contained within the RIL and support for additional radio implementations will require changes only within RIL without requiring customization of the upper level SAT component.

The previous release and the current release of the SIM ToolKit architectures are shown in the following illustration.

RIL Changes

Previously, the RIL performed only basic unpacking of the SIM toolkit commands and shuttled the raw, radio specific data to the SIM toolkit layer. Now, full parsing of the SIM toolkit radio commands happens within the RIL that creates a generic flat structure of the data to be passed to the SIM toolkit layer.

Communication between RIL and SIM ToolKit

RIL communication to the SIM toolkit layer is mainly through the RIL_NOTIFY_SIMTOOLKITCMD event. This event now passes up the following data:

typedef struct rilsimtoolkitcmd_tag
{   DWORD cbSize;              // Structure and text size in bytes
    DWORD dwParams;            // Bit field of valid parameters in the structure
    DWORD dwId;                // ID number of command
    DWORD dwTag;               // Command tag (with comprehension bit)
    DWORD dwType;              // Type of command (DISPLAY TEXT, etc.)
    DWORD dwQualifier;         // Command details qualifier
    DWORD dwError;             // Error when parsing command
    DWORD dwDetailsOffset;     // Offset to details command information
    DWORD dwDetailsSize;
} RILSIMTOOLKITCMD;

The RILSIMTOOLKITCMD encompasses the basic SIM Toolkit information common to most commands. More specific details for the command type are contained at the details offset. Each supported command type will have a specific details structure that is needs to be created and attached in the RIL_NOTIFY_SIMTOOLKITCMD notification.

Example of the details structure used for DISPLAY TEXT, GET INPUT, GET INKEY:

typedef struct simtext_tag
{   DWORD cbSize;              // Structure size in bytes
    DWORD dwParams;            // Indicates valid parameters
    DWORD dwFlags;             // Contains SIMTEXT_* flags
    DWORD dwMinResponse;       // Minimum response length
    DWORD dwMaxResponse;       // Maximum response length
    DWORD dwTextSize;          // Size of text message in bytes
    DWORD dwTextOffset;        // Offset from start of this in bytes
    DWORD dwDefaultTextSize;   // Size of default text message bytes
    DWORD dwDefaultTextOffset; // Offset from start of this structure
                               // in bytes
    DWORD dwIconIdentifier;    // Identifier for Icon to use.
    DWORD dwIconQualifier;     // Qualifier designating how the icon
                               // should be used.
} SIMTEXT, FAR *LPSIMTEXT;

Basic API Calls from SIM ToolKit to RIL

For SIM toolkit command responses and other communication from the device to the SIM, the RIL is now also responsible for taking the response data from the SIM toolkit layer and creating the radio specific command response.

For command responses, the SIM toolkit layer on the device will make the following call, where pDetails is an optional structure of detailed information based on the command type.

HRESULT RIL_SendSimToolkitCmdResponse(HRIL hRil,
                 const RILSIMTOOLKITRSP* pRsp,
                 const LPBYTE pDetails,
                 DWORD dwDetailSize);

typedef struct rilsimtoolkitrsp_tag
{   DWORD cbSize;              // Structure and text size in bytes
    DWORD dwParams;            // Indicates valid parameters
    DWORD dwId;                // ID number of command
    DWORD dwTag;               // Command tag (with comprehension bit)
    DWORD dwType;              // Type of command (DISPLAY TEXT, etc.)
    DWORD dwQualifier;         // Command details qualifier
    DWORD dwResponse;          // Command result from SIM toolkit layer
    DWORD dwAdditionalInfo;    // Additional command result information
} RILSIMTOOLKITRSP;

// Details structure for GET INPUT and GET INKEY
typedef struct simtkitrsptext_tag
{   DWORD cbSize;              // Structure and text size in bytes
    DWORD dwParams;            // Indicates valid parameters
    DWORD dwDCS;               // Indicates requested data encoding 
                               // scheme for text
    DWORD dwYesNo;             // Yes/No response
    DWORD dwTextOffset;        // Offset from structure for text
    DWORD dwTextSize;          // Size of text
} SIMTKITRSPTEXT, FAR *LPSIMTKITRSPTEXT;

SIM ToolKit Rel. 1999 Support

Windows Mobile 5.0 includes support for SIM toolkit Rel.1999:

• Class B : Run AT command
• Class C : Launch Browser
• Class E : Data Channels

There are changes in the SIM toolkit layer to support the following proactive commands:

• Setup Event List
• Run AT Command ^*
• Send DTMF ^*
• Language Notification
• Launch Browser
• Open Channel ^*
• Close Channel ^*
• Receive Data ^*
• Send Data ^*
• Icon support
• Display Text: Immediate Response support.
• Get Inkey: Yes/No support
• Event Download support

^* Functionality handled within the radio with possible notifications and user interaction handled by the device.

Other Rel 99 commands are handled completely by radio.

Summary

The Microsoft sample RIL provided to Windows Mobile licensees contains both modem implementation details and the architecture necessary to interface with both the modem and CellCore, and as such provides the starting point for a RIL adaptation project.

The duration and complexity of the project depends on the degree to which the modem departs from the Microsoft sample modem support and platform specific features the OEM wishes to implement, typical modifications to the sample RIL include, SIM ToolKit, power management, audio profile support, SMS. This paper provides examples of typical modifications required.

Generically, wireless networks have a number of asynchronous events resulting in a variety of potential timing issues. Differences between specific networks add further complexity and opportunity for additional problems. It is therefore critical that sufficient testing across a range of networks be undertaken. The Microsoft radio test suite offers an out of the box test environment that should be applied as early as possible in the project cycle.

Additional feature support in Windows Mobile 5.0, for example, SIM ToolKit, GSM 27.10MUX, etc., has extended the reach of the sample RIL, which should result in a better fit between the sample RIL and a wider range of modems currently available.

For More Information

See the following resources for further information:

GSM /GPRS specifications can be found at http://www.3gpp.org.

Windows Mobile developers MSDN site can be found at this Microsoft Web site.