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.