Radio_Layer_Interface

Radio Layer Interface

Introduction RIL Initialization RIL Interaction Solicited Unsolicited

Implementing the RIL RIL_Init

RIL Functions

RIL Solicited Command Requests RIL Unsolicited Commands

Introduction

Android's Radio Interface Layer (RIL) provides an abstraction layer between Android

telephony services (android.telephony) and radio hardware. The RIL is radio agnostic, and includes support for Global System for Mobile communication (GSM)-based radios. The diagram below illustrates the RIL in the context of Android's Telephony system architecture.

Solid elements represent Android blocks and dashed elements represent partner-specific proprietary blocks.

The RIL consists of two primary components:

 RIL Daemon: The RIL daemon initializes the Vendor RIL, processes all communication from Android telephony services, and dispatches calls to the Vendor RIL as solicited commands.

 Vendor RIL: The radio-specific Vendor RIL of ril.h that processes all communication with radio hardware and dispatches calls to the RIL Daemon (rild) through unsolicited commands.

RIL Initialization

Android initializes the telephony stack and the Vendor RIL at startup as described in the sequence below:

1. RIL daemon reads rild.lib path and rild.libargs system properties to determine the Vendor RIL library to use and any initialization arguments to provide to the Vendor RIL

2. RIL daemon loads the Vendor RIL library and calls RIL_Init to initialize the RIL and obtain a reference to RIL functions

3. RIL daemon calls RIL_register on the Android telephony stack, providing a reference to the Vendor RIL functions

See the RIL Daemon source code at //device/commands/rild/rild.c for details.

RIL Interaction

There are two forms of communication that the RIL handles:

 Solicited commands: Solicited commands originated by RIL lib, such as DIAL and HANGUP.

 Unsolicited responses: Unsolicited responses that originate from the baseband, such as CALL_STATE_CHANGED and NEW_SMS.

Solicited

The following snippet illustrates the interface for solicited commands:

void OnRequest (int request_id, void *data, size_t datalen, RIL_Token t);

void OnRequestComplete (RIL_Token t, RIL_Error e, void *response, size_t responselen);

There are over sixty solicited commands grouped by the following families:  SIM PIN, IO, and IMSI/IMEI (11)

 Call status and handling (dial, answer, mute…) (16)  Network status query (4)

 Network setting (barring, forwarding, selection…) (12)  SMS (3)

 PDP connection (4)  Power and reset (2)

 Supplementary Services (5)  Vendor defined and support (4)

The following diagram illustrates a solicited call in Android.

Unsolicited

The following snippet illustrates the interface for unsolicited commands:

void OnUnsolicitedResponse (int unsolResponse, void *data, size_t datalen);

There are over ten unsolicited commands grouped by the following families:  Network status changed (4)  New SMS notify (3)  New USSD notify (2)

 Signal strength or time changed (2)

The following diagram illustrates an unsolicited call in Android. Implementing the RIL To implement a radio-specific RIL, create a shared library that implements a set of functions required by Android to process radio requests. The required functions are defined in the RIL header (/include/telephony/ril.h).

The Android radio interface is radio-agnostic and the Vendor RIL can use any protocol to communicate with the radio. Android provides a reference Vendor RIL, using the Hayes AT command set, that you can use as a quick start for telephony testing and a guide for commercial vendor RILs. The source code for the reference RIL is found at /commands/reference-ril/.

Compile your Vendor RIL as a shared library using the

convention libril--.so, for example, libril-acme-124.so, where:

 libril: all vendor RIL implementations start with 'libril'  : a company-specific abbreviation  : RIL version number  so: file extension

RIL_Init

Your Vendor RIL must define a RIL_Init function that provides a handle to the functions which will process all radio requests.

RIL_Init will be called by the Android RIL Daemon at boot time to initialize the RIL.

RIL_RadioFunctions *RIL_Init (RIL_Env* env, int argc, char **argv);

RIL_Init should return a RIL_RadioFunctions structure containing the handles to the radio functions:

type structure {

int RIL_version;

RIL_RequestFunc onRequest;

RIL_RadioStateRequest onStateRequest; RIL_Supports supports; RIL_Cancel onCancel;

RIL_GetVersion getVersion; }

RIL_RadioFunctions;

RIL Functions

ril.h defines RIL states and variables, such

as RIL_UNSOL_STK_CALL_SETUP, RIL_SIM_READY, RIL_SIM_NOT_READY, as well as the functions described in the tables below. Skim the header file (/device/include/telephony/ril.h) for details.

RIL Solicited Command Requests

The vendor RIL must provide the functions described in the table below to handle solicited commands. The RIL solicited command request types are defined in ril.h with the RIL_REQUEST_ prefix. Check the header file for details. Na

Description me vThis is the RIL entry point for solicited o

icommands and must be able to handle the various RIL solicited request types defined d

in ril.h with the RIL_REQUEST_prefix. (

 request is one of RIL_REQUEST_* * data is pointer to data defined for R

Ithat RIL_REQUEST_* L t should be used in subsequent call _

Rto RIL_onResponse e datalen is owned by caller, and should not qbe modified or freed by callee u

eMust be completed with a call

sto RIL_onRequestComplete(). RIL_onRequestCotmplete() may be called from any thread F

before or after this function returns. This u

will always be called from the same n

cthread, so returning here implies that the )

radio is ready to process another command

((whether or not the previous command has icompleted).

n

t request, void *data, size_t datalen, RIL_Token t); RThis function should return the current Iradio state synchronously. L_RadioState (*RIL_RadioStateRequest)(); iThis function returns \"1\" if the nspecified RIL_REQUEST code is supported tand 0 if it is not. (*RIL_Supports)(int requestCode); vThis function is used to indicate that a o

ipending request should be canceled. This function is called from a separate thread--d

not the thread that callsRIL_RequestFunc. (

On cancel, the callee should do its best to *

abandon the request and R

IcallRIL_onRequestComplete with RIL_Errno LCANCELLED at some later point. _

Subsequent calls C

ato RIL_onRequestComplete for this request nwith other results will be tolerated but c

eignored (that is, it is valid to ignore the lcancellation request).

)RIL_Cancel calls should return immediately (

and not wait for cancellation. RIL_Token t);

cReturn a version string for your Vendor oRIL nst char * (*RIL_GetV

ersion) (void);

The vendor RIL uses the following callback methods to communicate back to the Android RIL daemon. Na

Description me

void RIL_onRequ

e t is parameter passed in on previous scall to RIL_Notification routine. t

 If e != SUCCESS, then response can C

obe null and is ignored m response is owned by caller, and should p

not be modified or freed by callee l

e RIL_onRequestComplete will return as tsoon as possible e(RIL_Token t, R

IL_Errno e, void *response, size_t responselen); void

Call user-specified callback function on Rthe same thread thatRIL_RequestFunc is Icalled. If relativeTime is specified, then it L

specifies a relative time value at which _

rthe callback is invoked. If relativeTime is eNULL or points to a 0-filled structure, qthe callback will be invoked as soon as upossible. estT

imedCallback (RIL_TimedCallback callback, void *param, const struc

t timeval *relativeTime);

RIL Unsolicited Commands

The functions listed in the table below are call-back functions used by the Vendor RIL to invoke unsolicited commands on the Android platform. See ril.h for details. Name Description  unsolResponse is one void of RIL_UNSOL_RESPONSE_* RIL_onUnsolicitedRes data is pointer to data defined ponse(int for unsolRespothatRIL_UNSOL_RESPONSE_* nse, const void *data,  data is owned by caller, and size_t should not be modified or datalen); freed by callee ©2008 Google