Radio Layer Interface

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.

Unsolicited

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/.

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:

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.

This is the RIL entry point for solicited commands and must be able to handle the various RIL solicited request types defined in ril.h with the RIL_REQUEST_ prefix.

request is one of RIL_REQUEST_*

data is pointer to data defined for that RIL_REQUEST_*

t should be used in subsequent call to RIL_onResponse

datalen is owned by caller, and should not be modified or freed by callee

Must be completed with a call to RIL_onRequestComplete(). RIL_onRequestComplete() may be called from any thread before or after this function returns. This will always be called from the same thread, so returning here implies that the radio is ready to process another command (whether or not the previous command has completed).

RIL_RadioState (*RIL_RadioStateRequest)();

This function should return the current radio state synchronously.

int (*RIL_Supports)(int requestCode);

This function returns "1" if the specified RIL_REQUEST code is supported and 0 if it is not.

void (*RIL_Cancel)(RIL_Token t);

This function is used to indicate that a pending request should be canceled. This function is called from a separate thread--not the thread that calls RIL_RequestFunc.

On cancel, the callee should do its best to abandon the request and call RIL_onRequestComplete with RIL_Errno CANCELLED at some later point.

Subsequent calls to RIL_onRequestComplete for this request with other results will be tolerated but ignored (that is, it is valid to ignore the cancellation request).

RIL_Cancel calls should return immediately and not wait for cancellation.

const char * (*RIL_GetVersion) (void);

Return a version string for your Vendor RIL

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

Call user-specified callback function on the same thread that RIL_RequestFunc is called. If relativeTime is specified, then it specifies a relative time value at which the callback is invoked. If relativeTime is NULL or points to a 0-filled structure, the callback will be invoked as soon as possible.

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.