Jason BrowneSoftware Engineering ManagerBsquare Corporation

ECE307 Inside the RadioInterface Layer (RIL)

Agenda

What is the RIL?

How does the RIL work?

Using the RIL from Applications

Demo: Putting it all together

RIL differences between Microsoft Windows Embedded CE 6.0 and Microsoft Windows Mobile 6

What is The RIL?

Radio Interface Layer

Abstraction layer for cellular technologies

A stream driver named “RIL”

Main responsibilitiesControlling the Radio Hardware (“AT commands,” for example)Instructing the audio manager to control volume and pathProvide NDIS interface to Radio HardwareProviding an SMS interface to Radio Hardware

Add to image with SYSGEN_CELLCORE_RIL

Cellular ArchitectureApplications / UILogic ModuleWindows APICellular APICore ProviderHW InterfaceRadio Software

SMS API

Router

UDP

SIMAPI

WTLS

WDP

Winsock

Auto Bind LSP

PPP

TCP/IP

NDIS

WWANMiniportfor GPRS

Radio interface Layer (RIL)

MUX Driver

Radio Stack

SIMToolKit UI

SIMTKPolicy

SIMTKTransport

WTP

TAPIExTAPI

Cellular TSP

NDISUIOProtocolDriver

Control Channel

Notification Channel

Data Port(s)

EtcWDPText

RIL Proxy (RIL)

RIL Proxy

RIL functions to RIL_* IOCTLSRIL_Dial() to RIL_IOCTL_DIALPasses these IOCTLs to RIL “driver” through RIL_IOControl()

RIL Proxy

Registration for notifications using callbacksHRESULT RIL_Initialize(

DWORD dwIndex, RILRESULTCALLBACK pfnResult, RILNOTIFYCALLBACK pfnNotify, DWORD dwNotificationClasses, DWORD dwParam, HRIL* lphRil

);

Two callbacksAsynchronous Function ResultsUnsolicited Messages/Notifications

RIL_Initialize() ExampleHANDLE hRingEvent;

int WINAPI WinMain(){ hRingEvent=CreateEvent(NULL,FALSE,FALSE,NULL);

hRIL = RIL_Initialize(1, MyRILResult, MyRILNotify,RIL_NCLASS_CALLCTRL,

dwParam,&hRil);

WaitForSingleObject(hRingEvent,INFINITE); MessageBox(NULL,TEXT("Ring"),TEXT("The Phone is

Ringing!"),MB_OK);}

RIL_Initialize() Examplevoid CALLBACK MyRILResult( DWORD dwCode, // result code HRESULT hrCmdID, // Command ID const void* lpData, // result data DWORD cbData, // size of lpData DWORD dwParam // parameter passed // to <RIL_Initialize>) { // At this time we do nothing. We could put

any initial RIL request handling in here. RETAILMSG(1,(TEXT("TEST Result : I : RIL

Result - dwCode = 0x%08x\n"),dwCode));}

RIL_Initialize() Examplevoid CALLBACK MyRILNotify( DWORD dwCode, // notification code const void* lpData, // notification data DWORD cbData, // size of lpData DWORD dwParam // parameter passed // to <RIL_Initialize>){ switch (dwCode) { case RIL_NOTIFY_RING: {

SetEvent(hRingEvent); }

}}

RIL Proxy

Filters for notificationsHRESULT RIL_EnableNotifications(

HRIL hRil,DWORD dwNotificationClasses

); HRESULT RIL_DisableNotifications(

HRIL hRil,DWORD dwNotificationClasses

);

Get notificationsIOCTL_RIL_GETNEXTNOTIFICATION

RIL Proxy

RIL_NCLASS_FUNCRESULT – Function Results

RIL_NCLASS_CALLCTRL – Call Control

RIL_NCLASS_MESSAGE – Messaging

RIL_NCLASS_NETWORK – Network Related

RIL_NCLASS_SUPSERVICE – Supplementary Service

RIL_NCLASS_PHONEBOOK - Phonebook

RIL_NCLASS_SIMTOOLKIT – SIM Toolkit

RIL_NCLASS_MISC – Miscellaneous

RIL_NCLASS_RADIOSTATE – Radio State

RIL_NCLASS_VGCSVBS – Voice Group Call and Voice Broadcast Call

RIL_NCLASS_DEVSPECIFIC – Device Specific

Notification classes

RIL Driver

RIL_Init()Called during boot up

RIL_DeInit()Called when driver is unloaded. (Rarely occurs.)

RIL_Open()Called when RIL_Initialize() is called

RIL_Read(), RIL_Write(), RIL_Seek()

RIL_Powerup(), RIL_PowerDown()Old style Power management functions

RIL_IOControl()Most of the functionality is created using this Entrypoint

RIL Bootup Process in Microsoft Windows Mobile 6

Phone Client (dialer, SMS API, Call Progress, etc.); calls RIL_Initialize()

Fails since RIL not ready

Regenum calls RIL_Init()Open communication to Radio Hardware (COM port)

Phone Client calls RIL_InitializeCalls RIL_OpenCalls IOCTL_RIL_NOTIFICATIONS

Initializes Notification Data Structures

Calls IOCTL_RIL_REGISTERWITHCPMRegister with Call Progress Monitor. (Undocumented not needed.)

RIL Bootup Process in Windows Mobile 6

Phone Client Continues to CallCalls PhoneFeature Levels

IOCTL_PHGFL_LOCKFACILITYIOCTL_PHGFL_UNIQUECALLTRACKINGIOCTL_INTLPLUSIOCTL_PHGFL_SMSUNICODEIOCTL_PHGFL_SUPPORTMOSMSIOCTL_PHGFL_GSM dwCode=0x0300248

RIL Bootup Process in WM 6

Phone Client Calls RIL_GETCURRENTPRIVACYSTATUS

RIL_CALLPRIVACY_STANDARDRIL_CALLPRIVACY_ENHANCED

Phone Client Calls RIL_IOCTL_GETCURRENTSYSTEMTYPE

RIL_SYSTEMTYPE_NONE RIL_SYSTEMTYPE_IS95ARIL_SYSTEMTYPE_IS95BRIL_SYSTEMTYPE_1XRTTPACKETRIL_SYSTEMTYPE_GSMRIL_SYSTEMTYPE_GPRS

RIL Bootup Process in Windows Mobile 6

RIL proxy scans for notifications usingIOCTL_RIL_GETNEXTNOTIFICATION

Simple Dialing Commands

HRESULT RIL_Dial(HRIL hRil,LPCSTR lpszAddress,DWORD dwType,DWORD dwOptions

);

AddressString telephone number

TypesRIL_CALLTYPE_VOICE RIL_CALLTYPE_DATA

OptionsRIL_DIALOPT_RESTRICTID RIL_DIALOPT_PRESENTID

Simple Dialing Commands

HRESULT RIL_Answer( HRIL hRil

);

HRESULT RIL_Hangup( HRIL hRil

);

Advanced Call Management

HRESULT RIL_ManageCalls(HRIL hRil,DWORD dwCommand,DWORD dwID

);

CommandsRIL_CALLCMD_RELEASEHELD

RIL_CALLCMD_RELEASEACTIVE_ACCEPTHELD

RIL_CALLCMD_RELEASECALL

RIL_CALLCMD_HOLDACTIVE_ACCEPTHELD

RIL_CALLCMD_HOLDALLBUTONE

RIL_CALLCMD_ADDHELDTOCONF

RIL_CALLCMD_ADDHELDTOCONF_DISCONNECT

RIL_CALLCMD_INVOKECCBS

RIL OEM Extensions

Very similar to IOControl

HRESULT RIL_DevSpecific(HRIL hRil, const BYTE* lpbParams,DWORD dwSize BYTE* pbAsyncResults =

NULL,DWORD dwAsyncResultsSize;DWORD* pcbAsyncResults = NULL,DWORD dwTimeOut;

);

RIL Call List

RIL_GetCallList( HRIL hRIL );

typedef struct { DWORD cbSize; DWORD dwParams; DWORD dwID; DWORD dwDirection; DWORD dwStatus; DWORD dwType; DWORD dwMultiparty;RILADDRESS raAddress; WCHAR

wszDescription[MAXLENGTH_DESCRIPTION]; DWORD dwDisconnectCode; DWORD dwPriority;

} RILCALLINFO;

GPRS Calls are not on this list

Audio Driver/RIL ConnectionsRIL to Audio Driver Connection

Accessory Audio Control

Uses RIL_Get/SetAudioDevices, RIL_Get/SetAudioMuting, RIL_Get/SetAudioGain,

Easier to create a separate Audio Manager to handle all audio cases than to integrate this directly into the RIL

Audio Manager controls PrioritizationPath logicVolume control

SMS

Sending an SMS MessageHRESULT RIL_SendMsg(

HRIL hRil, const RILMESSAGE* lpMessage, DWORD dwOptions

);

Receiving an SMS MessageRIL_NOTIFY_MESSAGE

lpData Pointer points to a RILMESSAGE

NDIS Miniport

Newer data connection model

“Always on”

Uses NDIS to RIL interface to provide the RIL-based data transport to the operating system

NDIS Miniport Driver talks to RIL

Operating system believes that this is just an NDIS Driver

Uses special RIL NDIS callback functionsRILNDISTRANSMITTCALLBACKRILNDISRECEIVECALLBACKRILNDISSTATUSCALLBACK

RASDIAL for Internet Connections

TAPI calls the RIL SetBearerServiceOptions() function with a pointer to RILBEARERSVCINFO structure to set :

RIL_SPEED_9600_V32 RIL_BSVCNAME_DATACIRCUIT_ASYNC_UDI_MODEM RIL_BSVCCE_NONTRANSPARENT

The return value should be RIL_RESULT_OK.

TAPI then calls RIL Dial"T14255551212“RIL_CALLTYPE_DATARIL_DIALOPT_NONE.

RASDIAL for Internet Connections

The RIL driver generates RIL_NOTIFY_DATASVCNEGOTIATED notification with lpData pointing to a RILSERVICEINFO structure set to asynchronous non-transparentNotification ignored

The RIL driver generates RIL_NOTIFY_CONNECT notification pointing to a RILCONNECTINFO structure with dwCallType member set to RIL_CALLTYPE_DATA and the dwBaudRate member set to 9600 (or the actual rate of connection)

RASDIAL for Internet Connections

The driver returns RIL_RESULT_OK for the dial command with lpData = NULL.

RAS opens the data port and starts the Point-to-Point Protocol (PPP) negotiation.

RASDIAL for Internet Connections

TAPI calls RIL GetCallList to verify that the call is active. This step may occur multiple times.

The return value should be RIL_RESULT_OK with lpData pointing a RILCALLINFO structure with the following values

dwID 1 dwDirection RIL_CALLDIR_OUTGOING dwStatus RIL_CALLSTAT_ACTIVE dwType RIL_CALLTYPE_DATA dwMultiparty RIL_CALL_SINGLEPARTY raAddress "14255551212"

Using The RIL from TAPI

The application calls the Telephony API (TAPI) lineMakeCall or lineDial functions to initiate the call

The TSP creates a new TAPI call in the dialing state

The TSP calls the RIL SetAudioDevices function to set the RIL_AUDIO_HANDSET constant as the device for both Transmit (TX) and Receive (RX) audio

Returns RIL_RESULT_OK

Using The RIL from TAPI

The TSP calls the RIL Dial function using the IOCTL_RIL_DIAL IOCTL. This causes RIL_IOControl to be called with IOCTL_RIL_DIAL

The RIL driver issues a dial command to the radio. The radio acknowledges that the dial is initiated.

The RIL driver returns RIL_RESULT_OK for the dial command

Using The RIL from TAPI

The RIL driver generates RIL_NOTIFY_CONNECT and RIL_CALLTYPE_VOICE constants

The TSP calls RIL GetCallListwaits for the RIL_CALLSTAT_ACTIVE mode

Returns RIL_RESULT_OK with a RILCALLINFO structure with the following values

DwID 1 DwDirection RIL_CALLDIR_OUTGOING DwStatus RIL_CALLSTAT_ACTIVE DwType RIL_CALLTYPE_VOICE DwMultiparty RIL_CALL_SINGLEPARTY RaAddress "14255551212"

RIL: Putting it All Together

Demo

Differences between Windows Embedded CE 6 and Windows Mobile 6

Windows Mobile has WAP-capable browser

Windows Mobile has built-in Dialer, Contacts, Call History, SMS Client, Call Progress, etc.

Windows Embedded CE 6.0 has renamed the libraries to reflect the MDD/PDD architecture

Windows Mobile has a Connection Manager

Summary

RIL abstracts the Radio Hardware

Clients use RIL proxy to connect to RIL

Clients use RIL functions and receive RIL notifications

RIL provides both voice and data interfaces

While You're Here

Fill out your session evaluationEnter to win a Windows Mobile® phone or Zune™

The Battle BeginsStay tuned for the Sumo Robotics competition

at the Tao attendee party

Meet the geeksThe Expert Cabana is packed with MEDC speakers and MVPs

© 2007 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries.

The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date

of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.