1 <html devsite> 2 <head> 3 <title>RIL Refactoring</title> 4 <meta name="project_path" value="/_project.yaml" /> 5 <meta name="book_path" value="/_book.yaml" /> 6 </head> 7 <body> 8 <!-- 9 Copyright 2017 The Android Open Source Project 10 11 Licensed under the Apache License, Version 2.0 (the "License"); 12 you may not use this file except in compliance with the License. 13 You may obtain a copy of the License at 14 15 http://www.apache.org/licenses/LICENSE-2.0 16 17 Unless required by applicable law or agreed to in writing, software 18 distributed under the License is distributed on an "AS IS" BASIS, 19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 20 See the License for the specific language governing permissions and 21 limitations under the License. 22 --> 23 24 25 26 <p>Android 7.0 included a refactoring of the Radio Interface Layer (RIL), using a set of 27 subfeatures to improve RIL functionality. Partner code changes are required to implement these 28 features, which are optional but encouraged. Refactoring changes are backward compatible, so prior 29 implementations of the refactored features continue to work.</p> 30 31 <p>The following subfeatures are included in the RIL refactoring feature. You 32 can implement any or all of the subfeatures:</p> 33 34 <ul> 35 <li>Enhanced RIL error codes: Code can return more specific error codes 36 than the existing <code>GENERIC_FAILURE</code> code. This enhances error 37 troubleshooting by providing more specific information about the cause 38 of errors.</li> 39 40 <li>Enhanced RIL versioning: The RIL versioning mechanism is enhanced to 41 provide more accurate and easier to configure version information.</li> 42 43 <li>Redesigned RIL communication using wakelocks: RIL communication using 44 wakelocks is enhanced to improve device battery performance.</li> 45 </ul> 46 47 <h2 id="examples">Examples and source</h2> 48 49 <p>Documentation for RIL versioning is also in code comments in <a 50 href="https://android.googlesource.com/platform/hardware/ril/+/master/include/telephony/ril.h"><code>https://android.googlesource.com/platform/hardware/ril/+/master/include/telephony/ril.h</code></a>.</p> 51 52 <h2 id="implementation">Implementation</h2> 53 54 <p>The following sections describe how to implement the subfeatures of the 55 RIL refactoring feature.</p> 56 57 <h3 id="errorcodes">Implementing enhanced RIL error codes</h3> 58 59 <h4 id="errorcodes-problem">Problem</h4> 60 61 <p>Almost all RIL request calls can return the <code>GENERIC_FAILURE</code> 62 error code in response to an error. This is an issue with all solicited 63 responses returned by the OEMs. It is difficult to debug an issue from 64 the bug report if the same <code>GENERIC_FAILURE</code> error code is 65 returned by RIL calls for different reasons. It can take considerable time 66 for vendors to even identify what part of the code could have returned a 67 <code>GENERIC_FAILURE</code> code.</p> 68 69 <h4 id="errorcodes-solution">Solution</h4> 70 71 <p>OEMs should return a distinct error code value associated 72 with each of the different errors that are currently categorized as 73 <code>GENERIC_FAILURE</code>.</p> 74 75 <p>If OEMs do not want to publicly reveal their custom error codes, they may 76 return errors as a distinct set of integers (for example, from 1 to x) that 77 are mapped as <code>OEM_ERROR_1</code> to <code>OEM_ERROR_X</code>. The 78 vendor should make sure each such masked error code returned maps to a unique 79 error reason in their code. The purpose of doing this is 80 to speed up debugging RIL issues whenever generic errors are returned 81 by the OEM. It can take too much time to identify what exactly caused 82 <code>GENERIC_FAILURE</code>, and sometimes it's impossible to figure out.<p> 83 84 <p>In <code>ril.h</code>, more error codes are 85 added for enums <code>RIL_LastCallFailCause</code> and 86 <code>RIL_DataCallFailCause</code> so that vendor code avoids returning 87 generic errors like <code>CALL_FAIL_ERROR_UNSPECIFIED</code> and 88 <code>PDP_FAIL_ERROR_UNSPECIFIED</code>.</p> 89 90 <h3 id="version">Implementing enhanced RIL versioning</h3> 91 92 <h4 id="version-problem">Problem</h4> 93 94 <p>RIL versioning is not accurate enough. The mechanism for vendors to 95 report their RIL version is not clear, causing vendors to report an incorrect 96 version. A workaround method of estimating the version is used, but it can 97 be inaccurate.</p> 98 99 <h4 id="version-solution">Solution</h4> 100 101 <p>There is a documented section in <code>ril.h</code> describing what a 102 particular RIL version value corresponds to. Each 103 RIL version is documented, including what changes correspond 104 to that version. Vendors must update their version in code when making 105 changes corresponding to that version, and return that version while doing 106 <code>RIL_REGISTER</code>.</p> 107 108 <h3 id="wakelocks">Implementing redesigned RIL communication using 109 wakelocks</h3> 110 111 <h4 id="wakelocks-prob-sum">Problem summary</h4> 112 113 <p>Timed wakelocks are used in RIL communication in an imprecise way, 114 which negatively affects battery performance. RIL requests can be either 115 solicited or unsolicited. Solicited requests should be classified as one of 116 the following:</p> 117 118 <ul> 119 <li>synchronous: Those that do not take considerable time to respond back. For 120 example, <code>RIL_REQUEST_GET_SIM_STATUS</code>.</li> 121 122 <li>asynchronous: Those that take considerable time to respond back. For 123 example, <code>RIL_REQUEST_QUERY_AVAILABLE_NETWORKS</code>.</li> 124 </ul> 125 126 <p>Follow these steps to implement redesigned wakelocks:</p> 127 128 <ol> 129 <li> 130 Classify solicited RIL commands as either synchronous or asynchronous 131 depending on how much time they take to respond. 132 <p>Here are some things to consider while making 133 that decision:</p> 134 135 <ul> 136 <li>As explained in the solution of asynchronous solicited RIL requests, 137 because the requests take considerable time, RIL Java releases the wakelock 138 after receiving ack from vendor code. This might cause the application 139 processor to go from idle to suspend state. When the response is available 140 from vendor code, RIL Java (the application processor) will re-acquire the 141 wakelock and process the response, and later go to idle state again. This 142 process of moving from idle to suspend state and back to idle can consume 143 a lot of power.</li> 144 145 <li>If the response time isn't long enough then holding the wakelock and 146 staying in idle state for the entire time it takes to respond can be more 147 power efficient than going in suspend state by releasing the wakelock and 148 then waking up when the response arrives. So vendors should use 149 platform-specific power measurement to find out the threshold value of time 't' when 150 power consumed by staying in idle state for the entire time 't' consumes 151 more power than moving from idle to suspend and back to idle in same time 152 't'. When that time 't' is discovered, RIL commands that take more than time 153 't' can be classified as asynchronous, and the rest of the RIL commands can 154 be classified as synchronous.</li> 155 </ul> 156 </li> 157 158 <li>Understand the RIL communications scenarios described in the <a 159 href="#ril-comm-scenarios">RIL communication scenarios</a> section.</li> 160 161 <li>Follow the solutions in the scenarios by modifying your code to handle 162 RIL solicited and unsolicited requests.</li> 163 </ol> 164 165 <h4 id="ril-comm-scenarios">RIL communication scenarios</h4> 166 167 <p>For implementation details of the functions used in the 168 following diagrams, see the source code of <code>ril.cpp</code>: 169 <code>acquireWakeLock()</code>, <code>decrementWakeLock()</code>, 170 <code>clearWakeLock(</code>)</p> 171 172 <h5>Scenario 1: RIL request from Java APIs and solicited asynchronous response 173 to that request</h5> 174 175 <p><img src="images/ril-refactor-scenario-1.png"></p> 176 177 <h6>Problem</h6> 178 179 <p>If the RIL solicited response is expected to take considerable time (for 180 example, <code>RIL_REQUEST_GET_AVAILABLE_NETWORKS</code>), then wakelock 181 is held for a long time on the Application processor side, which is a 182 problem. Also, modem problems result in a long wait.</p> 183 184 <h6>Solution part 1</h6> 185 186 <p>In this scenario, wakelock equivalent is held by Modem code (RIL request 187 and asynchronous response back).</p> 188 189 <p><img src="images/ril-refactor-scenario-1-solution-1.png"></p> 190 191 <p>As shown in the above sequence diagram:</p> 192 193 <ol> 194 <li>RIL request is sent, and the modem needs to acquire wakelock to process 195 the request.</li> 196 197 <li>The modem code sends acknowledgement that causes the Java side to decrement 198 the wakelock counter and release it if the wakelock counter value is 0.</li> 199 200 <li>After the modem processes the request, it sends an interrupt to the 201 vendor code that acquires wakelock and sends a response to ril.cpp. ril.cpp 202 then acquires wakelock and sends a response to the Java side.</li> 203 204 <li>When the response reaches the Java side, wakelock is acquired and response 205 is sent back to caller.</li> 206 207 <li>After that response is processed by all modules, acknowledgement is 208 sent back to <code>ril.cpp</code> over a socket. <code>ril.cpp</code> then 209 releases the wakelock that was acquired in step 3.</li> 210 </ol> 211 212 <p>Note that the wakelock timeout duration for the request-ack sequence 213 would be smaller than the currently used timeout duration because the ack 214 should be received back fairly quickly.</p> 215 216 <h6>Solution part 2</h6> 217 218 <p>In this scenario, wakelock is not held by modem and response is quick 219 (synchronous RIL request and response).</p> 220 221 <p><img src="images/ril-refactor-scenario-1-solution-2.png"></p> 222 223 <p>As shown in the above sequence diagram:</p> 224 225 <ol> 226 <li>RIL request is sent by calling <code>acquireWakeLock()</code> on the 227 Java side.</li> 228 229 <li>Vendor code doesn't need to acquire wakelock and can process the request 230 and respond quickly.</li> 231 232 <li>When the response is received by the Java side, 233 <code>decrementWakeLock()</code> is called, which decreases wakelock counter 234 and releases wakelock if the counter value is 0.</li> 235 </ol> 236 237 <p>Note that this synchronous vs. asynchronous behavior is hardcoded for a 238 particular RIL command and decided on a call-by-call basis.</p> 239 240 <h5>Scenario 2: RIL unsolicited response</h5> 241 242 <p><img src="images/ril-refactor-scenario-2.png"></p> 243 244 <p>As shown in the above diagram, RIL unsolicited responses have a wakelock 245 type flag in the response that indicates whether a wakelock needs to be 246 acquired or not for the particular response received from the vendor. If 247 the flag is set, then a timed wakelock is set and response is sent over a 248 socket to the Java side. When the timer expires, the wakelock is released.</p> 249 250 <h6>Problem</h6> 251 252 <p>The timed wakelock illustrated in Scenario 2 could be too long or too 253 short for different RIL unsolicited responses.</p> 254 255 <h6>Solution</h6> 256 257 <p><img src="images/ril-refactor-scenario-2-solution.png"></p> 258 259 <p>As shown, the problem can be solved by sending an acknowledgement from 260 the Java code to the native side (<code>ril.cpp</code>), instead of holding 261 a timed wakelock on the native side while sending an unsolicited response.</p> 262 263 <h2 id="validation">Validation</h2> 264 265 <p>The following sections describe how to validate the implementation of 266 the RIL refactoring feature's subfeatures.</p> 267 268 <h3 id="validate-error">Validating enhanced RIL error codes</h3> 269 270 <p>After adding new error codes to replace the <code>GENERIC_FAILURE</code> 271 code, verify that the new error codes are returned by the RIL call instead 272 of <code>GENERIC_FAILURE</code>.</p> 273 274 <h3 id="validate-version">Validating enhanced RIL versioning</h3> 275 276 <p>Verify that the RIL version corresponding to your RIL code is returned 277 during <code>RIL_REGISTER</code> rather than the <code>RIL_VERSION</code> 278 defined in <code>ril.h</code>.</p> 279 280 <h3 id="validate-wakelocks">Validating redesigned wakelocks</h3> 281 282 <p>Verify that RIL calls are identified as synchronous or asynchronous.</p> 283 284 <p>Because battery power consumption can be hardware/platform dependent, 285 vendors should do some internal testing to find out if using the new wakelock 286 semantics for asynchronous calls leads to battery power savings.</p> 287 288 </body> 289 </html> 290
