| |
| <html> |
| <head> |
| <meta http-equiv="content-type" content="text/html; charset=utf-8"/> |
| <title>Android - Porting Guide</title> |
| <script src="http://www.google.com/uds/api?file=uds.js&v=1.0&key=internal-codesite" type="text/javascript"></script> |
| <script src="http://code.google.com/js/jquery.js" type="text/javascript"></script> |
| <script type="text/javascript">var _tocPath_ = 'http://code.google.com/android/_toc.ezt';</script> |
| <script src="http://code.google.com/js/codesite.pack.01312008.js" type="text/javascript"></script> |
| <script language="JavaScript"> |
| function resizeHeight() { |
| if(document.getElementById && !(document.all)) { |
| height= document.getElementById('doxygen').contentDocument.body.scrollHeight + 20; |
| document.getElementById('doxygen').style.height = height; |
| } |
| else if(document.all) { |
| height= document.frames('doxygen').document.body.scrollHeight + 20; |
| document.all.doxygen.style.height = height; |
| } |
| } |
| </script> |
| <link href="http://code.google.com/css/codesite.pack.01312008.css" type="text/css" rel="stylesheet"> |
| </link> |
| |
| <!--[if IE]><link rel="stylesheet" type="text/css" href="/css/iehacks.css" /><![endif]--> |
| <script src="http://code.google.com/android/assets/search_autocomplete.js"></script> |
| <link rel="stylesheet" type="text/css" href="http://code.google.com/css/semantic_headers.css" /> |
| <link rel="stylesheet" type="text/css" href="http://code.google.com/android/assets/style.css" /> |
| <script> |
| jQuery(document).ready(function() { |
| jQuery("pre").addClass("prettyprint"); |
| }); |
| </script> |
| <style type="text/css"> |
| <!-- |
| h1,h2,h3 { |
| color: #000000; |
| } |
| --> |
| </style> |
| </head> |
| <body class="gc-documentation"> |
| <div id="gc-container"> |
| <a name="top"></a> |
| <div id="skipto"> </div> |
| <div id="langpref"> |
| <!--<a class="dropdown" href="/">English</a> <span>|</span> <a href="/more/">Site Directory</a> --> |
| |
| </div> |
| <div id="gc-header"> |
| <div id="logo"><a href="http://code.google.com/android/index.html"><img src="http://code.google.com/android/images/logo_android.gif" alt="Android"/></a></div> |
| <div id="search" style="inline"> |
| <div id="searchForm" class="searchForm" style="height: 44px;"> |
| <!--previously form was here--> |
| </div> |
| <!-- end searchForm --> |
| <noscript> |
| <style type="text/css"> |
| .searchForm { |
| display : none !important; |
| } |
| .searchForm2 { |
| display : inline !important; |
| } |
| </style> |
| </noscript> |
| |
| <div id="searchForm2" class="searchForm2" style="display:none"> |
| <form id="searchbox_001456098540849067467:6whlsytkdqg" action="http://www.google.com/cse"> |
| <input type="hidden" name="cx" value="001456098540849067467:6whlsytkdqg" /> |
| <input type="hidden" name="cof" value="FORID:0" /> |
| <input type="text" name="q" maxlength="2048" size="41" autocomplete="off" title="Google Code Search"/> |
| <input type="submit" name="sa" value="Search" title="Search"/> |
| <br/> |
| <div class="greytext">e.g. "ajax apis" or "open source"</div> |
| |
| </form> |
| </div> |
| <!-- end searchForm2 --> |
| </div> |
| <!-- end search --> |
| </div> |
| <!-- end gc-header --> |
| <div id="searchControl" class="search-control"></div> |
| <!--[if IE]><iframe id="backiFrame" name="backiFrame" src='/dummy.html' style="display:none"></iframe><![endif]--> |
| <div id="codesiteContent"> |
| <a name="gc-topnav-anchor"></a> |
| <div id="gc-topnav"> |
| |
| <h1>Android Platform Development Kit</h1> |
| <ul class="gc-topnav-tabs"> |
| <li id="sdk_link"> <a href="http://code.google.com/android/index.html" title="Android Software Development Kit">SDK</a> </li> |
| <li id="docs_link"> <a href="index.html" title="Official Android documentation">Docs</a> </li> |
| <li id="faq_link"> <a href="http://code.google.com/android/kb/index.html" title="Answers to frequently asked questions about Android">FAQ</a> </li> |
| |
| <li> <a href="http://android-developers.blogspot.com/" title="Official Android blog">Blog</a> </li> |
| <li> <a href="http://code.google.com/android/groups.html" title="Android developer forum">Group</a> </li> |
| <li> <a href="http://code.google.com/android/terms.html" title="Android terms of service">Terms</a> </li> |
| <li> <a href="mailto:android-pdk-feedback@google.com?subject=PDK%20Feedback&body=(filed%20from:%20telephony.html%20v0.6%20-%2025%20November%202008)%0D%0A%0D%0ASUMMARY:%0D%0A%0D%0A%0D%0A%0D%0ASTEPS%20TO%20REPRODUCE:%0D%0A%0D%0A%0D%0A%0D%0AADDITIONAL%20NOTES:">Report a Problem</a> </li> |
| |
| </ul> |
| </div> |
| <!-- end gc-topnav --> |
| <div class="g-section g-tpl-180"> |
| <a name="gc-toc"></a> |
| <div class="g-unit g-first" id="gc-toc"> |
| <ul> |
| <li> |
| <h1><a href="index.html">Documentation</a></h1> |
| <ul> |
| <li> <strong>Introduction</strong> |
| |
| <ul> |
| <li><a href="system_requirements.html">Device Requirements</a></li> |
| </ul> |
| </li> |
| <li> <strong>Dev Environment Setup</strong> |
| <ul> |
| <li><a href="build_system.html">Build System</a></li> |
| </ul> |
| </li> |
| <li> <strong>Basic Bring up</strong> |
| |
| <ul> |
| <li><a href="build_new_device.html">Building New Device</a></li> |
| <li><a href="bring_up.html">Bring up</a></li> |
| <li><a href="keymaps_keyboard_input.html">Keymaps and Keyboard</a></li> |
| <li><a href="display_drivers.html">Display Drivers</a></li> |
| </ul> |
| </li> |
| |
| <li> <strong>Multimedia</strong> |
| <ul> |
| <li><a href="audio_sub_system.html">Audio</a></li> |
| <li><a href="camera.html">Camera</a></li> |
| </ul> |
| </li> |
| <li> <strong>Power Management</strong> |
| |
| <ul> |
| <li><a href="power_management.html">Power Management</a></li> |
| </ul> |
| </li> |
| |
| <li> <strong>Networking</strong> |
| <ul> |
| <li><a href="wifi.html">Wi-Fi</a></li> |
| <li><a href="gps.html">GPS</a></li> |
| <li><a href="bluetooth.html">Bluetooth</a></li> |
| </ul> |
| </li> |
| |
| <li> <strong>Telephony</strong> |
| <ul> |
| <li><a href="telephony.html">Radio Interface Layer</a></li> |
| |
| </ul> |
| </li> |
| <li> <strong>Testing</strong> |
| <ul> |
| <li><a href="instrumentation_testing.html">Instrumentation Testing</a></li> |
| </ul> |
| |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| <a name="gc-pagecontent"></a> |
| <div class="g-unit" id="gc-pagecontent"> |
| <div id="jd-content"> |
| <div class="jd-descr"> |
| |
| |
| <a name="androidPowerTelephony"></a><h1>Radio Layer Interface</h1> |
| |
| |
| |
| <a name="toc"/> |
| <div style="padding:10px"> |
| <a href="#androidTelephonyIntro">Introduction</a><br/> |
| <a href="#androidTelephonyRILInitialization">RIL Initialization</a><br/> |
| <a href="#androidTelephonyRILIntro">RIL Interaction</a><br/><div style="padding-left:40px"> |
| |
| <a href="#androidTelephonyRILSolicited">Solicited</a><br/> |
| <a href="#androidTelephonyRILUnsolicited">Unsolicited</a><br/></div> |
| <a href="#androidTelephonyRILImplementing">Implementing the RIL</a><br/><div style="padding-left:40px"> |
| |
| <a href="#androidTelephonyRILInit">RIL_Init</a><br/></div> |
| <a href="#androidTelephonyRILFunctions">RIL Functions</a><br/><div style="padding-left:40px"> |
| |
| <a href="#androidRilFunctionsSolicited">RIL Solicited Command Requests</a><br/> |
| <a href="#androidRilFunctionsUnsolicited">RIL Unsolicited Commands</a><br/></div></div></font></div> |
| |
| <a name="androidTelephonyIntro"></a><h2>Introduction</h2> |
| |
| <p>Android's Radio Interface Layer (RIL) provides an abstraction layer between Android telephony services (<a href="http://code.google.com/android/reference/android/telephony/package-descr.html">android.telephony</a>) and radio hardware. The RIL is radio agnostic, and includes support for Global System for Mobile communication (GSM)-based radios. </P> |
| |
| |
| <p>The diagram below illustrates the RIL in the context of Android's Telephony system architecture.</p> |
| <p><img src="telephony.gif"></p> |
| |
| Solid elements represent Android blocks and dashed elements represent partner-specific blocks. |
| |
| <p>The RIL consists of two primary components:</p> |
| <p><ul> |
| <li><b>RIL Daemon</b>: The RIL daemon initializes the Vendor RIL, processes all communication from Android telephony services, and dispatches calls to the Vendor RIL as solicited commands.</li> |
| <li><b>Vendor RIL</b>: The radio-specific Vendor RIL of <code>ril.h</code> that processes all communication with radio hardware and dispatches calls to the RIL Daemon (<code>rild</code>) through unsolicited commands.</li> |
| </ul> |
| </p> |
| |
| |
| <a name="androidTelephonyRILInitialization"></a><h2>RIL Initialization</h2> |
| |
| <p>Android initializes the telephony stack and the Vendor RIL at startup as described in the sequence below:</p> |
| <p><ol> |
| <li>RIL daemon reads <code>rild.lib</code> path and <code>rild.libargs</code> system properties to determine the Vendor RIL library to use and any initialization arguments to provide to the Vendor RIL</li> |
| <li>RIL daemon loads the Vendor RIL library and calls <code>RIL_Init</code> to initialize the RIL and obtain a reference to RIL functions</li> |
| <li>RIL daemon calls <code>RIL_register</code> on the Android telephony stack, providing a reference to the Vendor RIL functions</li></ol> |
| </p> |
| <p>See the RIL Daemon source code at <code>//device/commands/rild/rild.c</code> for details.</p> |
| |
| |
| <a name="androidTelephonyRILIntro"></a><h2>RIL Interaction</h2> |
| |
| <p>There are two forms of communication that the RIL handles:</p> |
| <ul> |
| <li>Solicited commands: Solicited commands originated by RIL lib, such as <code>DIAL</code> and <code>HANGUP</code>.</li> |
| <li>Unsolicited responses: Unsolicited responses that originate from the baseband, such as <code>CALL_STATE_CHANGED</code> and <code>NEW_SMS</code>.</li> |
| </ul> |
| |
| |
| <a name="androidTelephonyRILSolicited"></a><h3>Solicited</h3> |
| |
| <p>The following snippet illustrates the interface for solicited commands:</p> |
| <pre class="prettify"> |
| 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); |
| </pre> |
| <p>There are over sixty solicited commands grouped by the following families:</p> |
| <p> |
| <ul> |
| <li>SIM PIN, IO, and IMSI/IMEI (11)</li> |
| <li>Call status and handling (dial, answer, mute…) (16)</li> |
| <li>Network status query (4)</li> |
| <li>Network setting (barring, forwarding, selection…) (12)</li> |
| <li>SMS (3)</li> |
| <li>PDP connection (4)</li> |
| <li>Power and reset (2)</li> |
| <li>Supplementary Services (5)</li> |
| <li>Vendor defined and support (4)<br/> |
| </li> |
| </ul> |
| </p> |
| <p>The following diagram illustrates a solicited call in Android.</p> |
| <p><img src="telephony_solicted_example.gif"></p> |
| |
| |
| <a name="androidTelephonyRILUnsolicited"></a><h3>Unsolicited</h3> |
| |
| <p>The following snippet illustrates the interface for unsolicited commands:</p> |
| <pre class="prettify"> |
| void OnUnsolicitedResponse (int unsolResponse, void *data, size_t datalen); |
| </pre> |
| <p>There are over ten unsolicited commands grouped by the following families:</p> |
| <p> |
| <ul> |
| <li>Network status changed (4)</li> |
| <li>New SMS notify (3)</li> |
| <li>New USSD notify (2)</li> |
| <li>Signal strength or time changed (2)</li> |
| </ul> |
| </p> |
| <p>The following diagram illustrates an unsolicited call in Android.</p> |
| <p><img src="telephony_unsolicted_example.gif"></p> |
| |
| |
| <a name="androidTelephonyRILImplementing"></a><h2>Implementing the RIL</h2> |
| |
| <p>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 (<code>/include/telephony/ril.h</code>).</p> |
| <p>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 <code>/commands/reference-ril/</code>.</p> |
| <p>Compile your Vendor RIL as a shared library using the convention <code>libril-<companyname>-<RIL version>.so</code>, for example, libril-acme-124.so, where:</p> |
| <p><ul> |
| <li><b>libril</b>: all vendor RIL implementations start with 'libril'</li> |
| <li><b><companyname></b>: a company-specific abbreviation</li> |
| <li><b><RIL version></b>: RIL version number</li> |
| <li><b>so</b>: file extension</li> |
| </ul> |
| </p> |
| |
| |
| <a name="androidTelephonyRILInit"></a><h3>RIL_Init</h3> |
| |
| <p>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.</p> |
| |
| <pre class="prettify"> |
| RIL_RadioFunctions *RIL_Init (RIL_Env* env, int argc, char **argv); |
| </pre> |
| |
| <p>RIL_Init should return a RIL_RadioFunctions structure containing the handles to the radio functions:</p> |
| <pre class="prettify"> |
| type structure { |
| int RIL_version; |
| RIL_RequestFunc onRequest; |
| RIL_RadioStateRequest onStateRequest; |
| RIL_Supports supports; |
| RIL_Cancel onCancel; |
| RIL_GetVersion getVersion; |
| } |
| RIL_RadioFunctions; |
| </pre> |
| |
| |
| <a name="androidTelephonyRILFunctions"></a><h2>RIL Functions</h2> |
| |
| <p><code>ril.h</code> defines RIL states and variables, such as <code>RIL_UNSOL_STK_CALL_SETUP</code>, <code>RIL_SIM_READY</code>, <code>RIL_SIM_NOT_READY</code>, as well as the functions described in the tables below. Skim the header file (<code>/device/include/telephony/ril.h</code>) for details.</p> |
| |
| |
| <a name="androidRilFunctionsSolicited"></a><h3>RIL Solicited Command Requests</h3> |
| |
| <p>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 <code>ril.h</code> with the <code>RIL_REQUEST_</code> prefix. Check the header file for details.</p> |
| <p><table> |
| <tr><th scope="col">Name</th><th scope="col">Description</th></tr> |
| <tr> |
| <td valign="top"><code> void (*RIL_RequestFunc) (int request, void *data, size_t datalen, RIL_Token t);</code></td> |
| <td valign="top"> |
| <p>This is the RIL entry point for solicited commands and must be able to handle the various RIL solicited request types defined in <code>ril.h</code> with the <code>RIL_REQUEST_</code> prefix.</p> |
| <ul> |
| <li><code>request</code> is one of <code>RIL_REQUEST_*</code></li> |
| <li><code>data</code> is pointer to data defined for that <code>RIL_REQUEST_*</code></l> |
| <li><code>t</code> should be used in subsequent call to <code>RIL_onResponse</code></li> |
| <li><code>datalen</code> is owned by caller, and should not be modified or freed by callee</li> |
| </ul> |
| <p>Must be completed with a call to <code>RIL_onRequestComplete()</code>. <code>RIL_onRequestComplete()</code> 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).</p></td> |
| </tr> |
| <tr> |
| <td valign="top"><code> RIL_RadioState (*RIL_RadioStateRequest)();</code></td> |
| <td valign="top">This function should return the current radio state synchronously.</td> |
| </tr> |
| <tr> |
| <td valign="top"><code> int (*RIL_Supports)(int requestCode);</code></td> |
| <td valign="top">This function returns "1" if the specified <code>RIL_REQUEST</code> code is supported and 0 if it is not.</td> |
| </tr> |
| <tr> |
| <td valign="top"><code> void (*RIL_Cancel)(RIL_Token t);</code></td> |
| <td valign="top"><p>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 <code>RIL_RequestFunc</code>.</p> |
| <p>On cancel, the callee should do its best to abandon the request and call <code>RIL_onRequestComplete</code> with <code>RIL_Errno CANCELLED</code> at some later point.</p> |
| <p>Subsequent calls to <code>RIL_onRequestComplete</code> for this request with other results will be tolerated but ignored (that is, it is valid to ignore the cancellation request).</p> |
| <p><code>RIL_Cancel</code> calls should return immediately and not wait for cancellation.</p></td> |
| </tr> |
| <tr> |
| <td valign="top"><code> const char * (*RIL_GetVersion) (void);</code></td> |
| <td valign="top">Return a version string for your Vendor RIL</td> |
| </tr> |
| </table> |
| |
| |
| <p>The vendor RIL uses the following callback methods to communicate back to the Android RIL daemon.</p> |
| <p> |
| <table> |
| <tr> |
| <th scope="col">Name</th> |
| <th scope="col">Description</th> |
| </tr> |
| <tr> |
| <td><code>void RIL_onRequestComplete(RIL_Token t, RIL_Errno e, void *response, size_t responselen);</code></td> |
| <td><ul> |
| <li><code>t</code> is parameter passed in on previous call to <code>RIL_Notification</code> routine.</li> |
| <li>If <code>e</code> != SUCCESS, then response can be null and is ignored</li> |
| <li><code>response</code> is owned by caller, and should not be modified or freed by callee</li> |
| <li><code>RIL_onRequestComplete</code> will return as soon as possible</li> |
| </ul></td> |
| </tr> |
| <tr> |
| <td><code>void RIL_requestTimedCallback (RIL_TimedCallback callback, void *param, const struct timeval *relativeTime);</code></td> |
| <td>Call user-specified callback function on the same thread that <code>RIL_RequestFunc</code> is called. If <code>relativeTime</code> is specified, then it specifies a relative time value at which the callback is invoked. If <code>relativeTime</code> is NULL or points to a 0-filled structure, the callback will be invoked as soon as possible.</td> |
| </tr> |
| </table></p> |
| |
| |
| <a name="androidRilFunctionsUnsolicited"></a><h3>RIL Unsolicited Commands</h3> |
| |
| <p>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 <code>ril.h</code> for details. </p> |
| <p> |
| <table> |
| <tr> |
| <th scope="col">Name</th> |
| <th scope="col">Description</th> |
| </tr> |
| <tr> |
| <td><code>void RIL_onUnsolicitedResponse(int unsolResponse, const void *data, size_t datalen);</code></td> |
| <td><ul> |
| <li><code>unsolResponse</code> is one of <code>RIL_UNSOL_RESPONSE_*</code></li> |
| <li><code>data</code> is pointer to data defined for that <code>RIL_UNSOL_RESPONSE_*</code></li> |
| <li><code>data</code> is owned by caller, and should not be modified or freed by callee</li> |
| </ul></td> |
| </tr> |
| </table></p> |
| |
| |
| <p><span class="lh2"><a name="androidFooter"></a></span> |
| |
| </div> |
| </div> |
| <!-- end gc-pagecontent --> |
| </div> |
| <!-- end gooey wrapper --> |
| </div> |
| <!-- end codesearchresults --> |
| <div id="gc-footer" dir="ltr"> |
| <div class="text"> ©2008 Google<!-- - <a href="/">Code Home</a> - <a href="http://www.google.com/accounts/TOS">Site Terms of Service</a> - <a href="http://www.google.com/privacy.html">Privacy Policy</a> - <a href="/more">Site Directory</a> --></div> |
| </div> |
| <!-- end gc-footer --> |
| </div> |
| <!-- end gc-containter --> |
| <script src="http://www.google-analytics.com/ga.js" type="text/javascript"> |
| </script> |
| <script type="text/javascript"> |
| try { |
| var pageTracker = _gat._getTracker("UA-18071-1"); |
| pageTracker._setAllowAnchor(true); |
| pageTracker._initData(); |
| pageTracker._trackPageview(); |
| } catch(e) {} |
| </script> |
| <div id="jd-build-id"> v0.6 - 25 November 2008</div> |
| </div></div></div></body> |
| </html> |
| |
