6 files changed, 143 insertions, 201 deletions
diff --git a/en/devices/tech/connect/images/ril-refactor-scenario-1-solution-1.png b/en/devices/tech/connect/images/ril-refactor-scenario-1-solution-1.png
index c3b406f8..c252daad 100644
--- a/en/devices/tech/connect/images/ril-refactor-scenario-1-solution-1.png
+++ b/en/devices/tech/connect/images/ril-refactor-scenario-1-solution-1.png
diff --git a/en/devices/tech/connect/images/ril-refactor-scenario-1-solution-2.png b/en/devices/tech/connect/images/ril-refactor-scenario-1-solution-2.png
index c144afcf..6871336e 100644
--- a/en/devices/tech/connect/images/ril-refactor-scenario-1-solution-2.png
+++ b/en/devices/tech/connect/images/ril-refactor-scenario-1-solution-2.png
diff --git a/en/devices/tech/connect/images/ril-refactor-scenario-1.png b/en/devices/tech/connect/images/ril-refactor-scenario-1.png
index f35fec9d..2d4e4b06 100644
--- a/en/devices/tech/connect/images/ril-refactor-scenario-1.png
+++ b/en/devices/tech/connect/images/ril-refactor-scenario-1.png
diff --git a/en/devices/tech/connect/images/ril-refactor-scenario-2-solution.png b/en/devices/tech/connect/images/ril-refactor-scenario-2-solution.png
index d25ace5c..565ac214 100644
--- a/en/devices/tech/connect/images/ril-refactor-scenario-2-solution.png
+++ b/en/devices/tech/connect/images/ril-refactor-scenario-2-solution.png
diff --git a/en/devices/tech/connect/images/ril-refactor-scenario-2.png b/en/devices/tech/connect/images/ril-refactor-scenario-2.png
index d52c1746..85d44a51 100644
--- a/en/devices/tech/connect/images/ril-refactor-scenario-2.png
+++ b/en/devices/tech/connect/images/ril-refactor-scenario-2.png
diff --git a/en/devices/tech/connect/ril.html b/en/devices/tech/connect/ril.html
index 6367fb1f..56e7f9b9 100644
--- a/en/devices/tech/connect/ril.html
+++ b/en/devices/tech/connect/ril.html
@@ -23,267 +23,209 @@
 
 
 
-<p>Android 7.0 included a refactoring of the Radio Interface Layer (RIL), using a set of
-subfeatures to improve RIL functionality. Partner code changes are required to implement these
-features, which are optional but encouraged. Refactoring changes are backward compatible, so prior
-implementations of the refactored features continue to work.</p>
+<p>Android 7.0 refactored the Radio Interface Layer (RIL) using a set of
+features to improve RIL functionality. Partner code changes are required to
+implement these features, which are optional but encouraged. Refactoring changes
+are backward compatible, so prior implementations of the refactored features
+continue to work.</p>
 
-<p>The following subfeatures are included in the RIL refactoring feature. You
-can implement any or all of the subfeatures:</p>
+<p>RIL refactoring includes the following improvements:</p>
 
 <ul>
-<li>Enhanced RIL error codes: Code can return more specific error codes
-than the existing <code>GENERIC_FAILURE</code> code. This enhances error
-troubleshooting by providing more specific information about the cause
-of errors.</li>
-
-<li>Enhanced RIL versioning: The RIL versioning mechanism is enhanced to
-provide more accurate and easier to configure version information.</li>
-
-<li>Redesigned RIL communication using wakelocks: RIL communication using
-wakelocks is enhanced to improve device battery performance.</li>
+<li><strong>RIL error codes.</strong> Enables specific error codes
+in addition to the existing <code>GENERIC_FAILURE</code> code. This aids in
+error troubleshooting by providing more specific information about the cause of
+errors.</li>
+<li><strong>RIL versioning.</strong> Provides more accurate and easier
+to configure version information.</li>
+<li><strong>RIL communication using wakelocks.</strong> Improves
+device battery performance.</li>
 </ul>
 
-<h2 id="examples">Examples and source</h2>
-
-<p>Documentation for RIL versioning is also in code comments in <a
-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>
-
-<h2 id="implementation">Implementation</h2>
+<p>You can implement any or all of the above improvements. For more details,
+refer to code comments on RIL versioning in
+<a 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>
 
-<p>The following sections describe how to implement the subfeatures of the
-RIL refactoring feature.</p>
-
-<h3 id="errorcodes">Implementing enhanced RIL error codes</h3>
-
-<h4 id="errorcodes-problem">Problem</h4>
+<h2 id="errorcodes">Implementing enhanced RIL error codes</h2>
 
 <p>Almost all RIL request calls can return the <code>GENERIC_FAILURE</code>
 error code in response to an error. This is an issue with all solicited
-responses returned by the OEMs. It is difficult to debug an issue from
-the bug report if the same <code>GENERIC_FAILURE</code> error code is
+responses returned by the OEMs, which can make it difficult to debug an issue
+from the bug report if the same <code>GENERIC_FAILURE</code> error code is
 returned by RIL calls for different reasons. It can take considerable time
 for vendors to even identify what part of the code could have returned a
 <code>GENERIC_FAILURE</code> code.</p>
 
-<h4 id="errorcodes-solution">Solution</h4>
-
-<p>OEMs should return a distinct error code value associated
-with each of the different errors that are currently categorized as
-<code>GENERIC_FAILURE</code>.</p>
-
-<p>If OEMs do not want to publicly reveal their custom error codes, they may
-return errors as a distinct set of integers (for example, from 1 to x) that
-are mapped as <code>OEM_ERROR_1</code> to <code>OEM_ERROR_X</code>. The
-vendor should make sure each such masked error code returned maps to a unique
-error reason in their code. The purpose of doing this is
-to speed up debugging RIL issues whenever generic errors are returned
-by the OEM. It can take too much time to identify what exactly caused
-<code>GENERIC_FAILURE</code>, and sometimes it's impossible to figure out.<p>
-
-<p>In <code>ril.h</code>, more error codes are
-added for enums <code>RIL_LastCallFailCause</code> and
-<code>RIL_DataCallFailCause</code> so that vendor code avoids returning
-generic errors like <code>CALL_FAIL_ERROR_UNSPECIFIED</code> and
+<p>In Android 7.x and higher, OEMs can return a distinct error code value
+associated with each different error that is currently categorized as
+<code>GENERIC_FAILURE</code>. OEMs that do not want to publicly reveal their
+custom error codes can return errors as a distinct set of integers (such as 1 to
+x) mapped as <code>OEM_ERROR_1</code> to <code>OEM_ERROR_X</code>. Vendors
+should ensure each such masked error code returned maps to a unique error reason
+in the code. Using specific error codes can speed up RIL debugging whenever
+generic errors are returned by the OEM, as it can often take too much time to
+identify the exact cause of a <code>GENERIC_FAILURE</code> error code (and
+sometimes it's impossible to figure out).<p>
+
+<p>In addition, <code>ril.h</code> adds more error codes for the enums
+<code>RIL_LastCallFailCause</code> and <code>RIL_DataCallFailCause</code> so
+vendor code can avoid returning generic errors such as
+<code>CALL_FAIL_ERROR_UNSPECIFIED</code> and
 <code>PDP_FAIL_ERROR_UNSPECIFIED</code>.</p>
 
-<h3 id="version">Implementing enhanced RIL versioning</h3>
+<h3 id="validate-error">Validating enhanced RIL error codes</h3>
 
-<h4 id="version-problem">Problem</h4>
+<p>After adding new error codes to replace the <code>GENERIC_FAILURE</code>
+code, verify the new error codes are returned by the RIL call instead
+of <code>GENERIC_FAILURE</code>.</p>
 
-<p>RIL versioning is not accurate enough. The mechanism for vendors to
-report their RIL version is not clear, causing vendors to report an incorrect
-version. A workaround method of estimating the version is used, but it can
-be inaccurate.</p>
+<h2 id="version">Implementing enhanced RIL versioning</h2>
 
-<h4 id="version-solution">Solution</h4>
+<p>RIL versioning in older Android releases was problematic: the version itself
+was imprecise, the mechanism for reporting a RIL version was unclear (causing
+some vendors to report an incorrect version), and the workaround for estimating
+the version was prone to inaccuracy.</p>
 
-<p>There is a documented section in <code>ril.h</code> describing what a
-particular RIL version value corresponds to. Each
-RIL version is documented, including what changes correspond
-to that version. Vendors must update their version in code when making
-changes corresponding to that version, and return that version while doing
+<p>In Android 7.x and higher, <code>ril.h</code> documents all RIL version
+values, describes the corresponding RIL version, and lists all changes for that
+version. When making changes that correspond to a RIL version, vendors must
+update their version in code and return that version in
 <code>RIL_REGISTER</code>.</p>
 
-<h3 id="wakelocks">Implementing redesigned RIL communication using
-wakelocks</h3>
-
-<h4 id="wakelocks-prob-sum">Problem summary</h4>
-
-<p>Timed wakelocks are used in RIL communication in an imprecise way,
-which negatively affects battery performance. RIL requests can be either
-solicited or unsolicited. Solicited requests should be classified as one of
-the following:</p>
+<h3 id="validate-version">Validating enhanced RIL versioning</h3>
 
-<ul>
-<li>synchronous: Those that do not take considerable time to respond back. For
-example, <code>RIL_REQUEST_GET_SIM_STATUS</code>.</li>
+<p>Verify that the RIL version corresponding to your RIL code is returned
+during <code>RIL_REGISTER</code> (rather than the <code>RIL_VERSION</code>
+defined in <code>ril.h</code>).</p>
 
-<li>asynchronous: Those that take considerable time to respond back. For
-example, <code>RIL_REQUEST_QUERY_AVAILABLE_NETWORKS</code>.</li>
-</ul>
+<h2 id="wakelocks">Implementing RIL communication using wakelocks</h2>
 
-<p>Follow these steps to implement redesigned wakelocks:</p>
+<p>Timed wakelocks are used in RIL communication in an imprecise way,
+which negatively affects battery performance. In Android 7.x and higher, you can
+improve performance by classifying RIL requests and updating code to handle
+wakelocks differently for different request types.</p>
 
-<ol>
-<li>
-Classify solicited RIL commands as either synchronous or asynchronous
-depending on how much time they take to respond.
-<p>Here are some things to consider while making
-that decision:</p>
+<h3 id="classifying">Classifying RIL requests</h3>
+<p>RIL requests can be either solicited or unsolicited. Vendors should further
+classify solicited requests as one of the following:</p>
 
 <ul>
-<li>As explained in the solution of asynchronous solicited RIL requests,
-because the requests take considerable time, RIL Java releases the wakelock
-after receiving ack from vendor code. This might cause the application
-processor to go from idle to suspend state. When the response is available
-from vendor code, RIL Java (the application processor) will re-acquire the
-wakelock and process the response, and later go to idle state again. This
-process of moving from idle to suspend state and back to idle can consume
-a lot of power.</li>
-
-<li>If the response time isn't long enough then holding the wakelock and
-staying in idle state for the entire time it takes to respond can be more
-power efficient than going in suspend state by releasing the wakelock and
-then waking up when the response arrives. So vendors should use
-platform-specific power measurement to find out the threshold value of time 't' when
-power consumed by staying in idle state for the entire time 't' consumes
-more power than moving from idle to suspend and back to idle in same time
-'t'. When that time 't' is discovered, RIL commands that take more than time
-'t' can be classified as asynchronous, and the rest of the RIL commands can
-be classified as synchronous.</li>
-</ul>
+<li><strong>synchronous</strong>. Requests that do not take considerable time to
+respond back. For example, <code>RIL_REQUEST_GET_SIM_STATUS</code>.</li>
+ <li><strong>asynchronous</strong>. Requests that take considerable time to
+respond back. For example, <code>RIL_REQUEST_QUERY_AVAILABLE_NETWORKS</code>.
 </li>
+</ul>
 
-<li>Understand the RIL communications scenarios described in the <a
-href="#ril-comm-scenarios">RIL communication scenarios</a> section.</li>
-
-<li>Follow the solutions in the scenarios by modifying your code to handle
-RIL solicited and unsolicited requests.</li>
-</ol>
-
-<h4 id="ril-comm-scenarios">RIL communication scenarios</h4>
-
-<p>For implementation details of the functions used in the
-following diagrams, see the source code of <code>ril.cpp</code>:
-<code>acquireWakeLock()</code>, <code>decrementWakeLock()</code>,
-<code>clearWakeLock(</code>)</p>
-
-<h5>Scenario 1: RIL request from Java APIs and solicited asynchronous response
-to that request</h5>
+<p>Asynchronous solicited RIL requests can take considerable time. After
+receiving an ack from vendor code, RIL Java releases the wakelock, which might
+cause the application processor to go from idle to suspend state. When the
+response is available from vendor code, RIL Java (the application processor)
+re-acquires the wakelock, processes the response, then returns to idle. Such
+moving from idle to suspend to idle can consume a lot of power.</p>
+
+<p>If the response time isn't long enough, holding the wakelock and staying in
+idle for the entire time it takes to respond can be more power efficient than
+going into suspend state by releasing the wakelock and waking when the response
+arrives. Vendors should use platform-specific power measurements to determine
+the threshold value of time <var>T</var> when the power consumed by
+staying in idle for the entire time <var>T</var> is greater than the power
+consumed by moving from idle to suspend and to idle in same time <var>T</var>.
+When time <var>T</var> is known, RIL commands that take more than time
+<var>T</var> can be classified as asynchronous and the remaining commands
+classified as synchronous.</p>
+
+<h3 id="ril-comm-scenarios">RIL communication scenarios</h3>
+<p>The following diagrams illustrate common RIL communication scenarios and
+provide solutions for modifying code to handle RIL solicited and unsolicited
+requests.</p>
+
+<p class="note"><strong>Note:</strong> For implementation details on functions
+used in the following diagrams, refer to the <code>acquireWakeLock()</code>,
+<code>decrementWakeLock()</code>, and <code>clearWakeLock(</code>) methods in
+<code>ril.cpp</code>.</p>
+
+<h4>Scenario: RIL request and solicited asynchronous response</h4>
+
+<p>In this scenario, if the RIL solicited response is expected to take
+considerable time (i.e. a response to
+<code>RIL_REQUEST_GET_AVAILABLE_NETWORKS</code>), the wakelock is held for a
+long time on the application processor side. Modem problems can also result in a
+long wait.</p>
 
 <p><img src="images/ril-refactor-scenario-1.png"></p>
+<figcaption><strong>Figure 1.</strong> RIL solicited asynchronous
+response.</figcaption>
 
-<h6>Problem</h6>
-
-<p>If the RIL solicited response is expected to take considerable time (for
-example, <code>RIL_REQUEST_GET_AVAILABLE_NETWORKS</code>), then wakelock
-is held for a long time on the Application processor side, which is a
-problem. Also, modem problems result in a long wait.</p>
-
-<h6>Solution part 1</h6>
-
-<p>In this scenario, wakelock equivalent is held by Modem code (RIL request
-and asynchronous response back).</p>
+<p><strong>Solution 1:</strong> The modem holds the wakelock for the RIL request
+and asynchronous response.</p>
 
 <p><img src="images/ril-refactor-scenario-1-solution-1.png"></p>
-
-<p>As shown in the above sequence diagram:</p>
+<figcaption><strong>Figure 2.</strong> Wakelock held by modem.</figcaption>
 
 <ol>
-<li>RIL request is sent, and the modem needs to acquire wakelock to process
-the request.</li>
-
-<li>The modem code sends acknowledgement that causes the Java side to decrement
-the wakelock counter and release it if the wakelock counter value is 0.</li>
-
-<li>After the modem processes the request, it sends an interrupt to the
-vendor code that acquires wakelock and sends a response to ril.cpp. ril.cpp
-then acquires wakelock and sends a response to the Java side.</li>
-
-<li>When the response reaches the Java side, wakelock is acquired and response
-is sent back to caller.</li>
-
-<li>After that response is processed by all modules, acknowledgement is
-sent back to <code>ril.cpp</code> over a socket. <code>ril.cpp</code> then
-releases the wakelock that was acquired in step 3.</li>
+<li>RIL request is sent and the modem acquires wakelock to process that
+request.</li>
+<li>Modem sends acknowledgement that causes the Java side to decrement
+the wakelock counter and release it when the counter value is 0.
+<p class="note"><strong>Note:</strong> The wakelock timeout duration for the
+request-ack sequence would be smallerthan the currently used timeout duration
+because the ack should be received fairly quickly.</p>
+</li>
+<li>After processing the request, the modem sends an interrupt to the vendor
+code that acquires wakelock and sends a response to ril.cpp, which in turn
+acquires wakelock and sends a response to the Java side.</li>
+<li>When the response reaches the Java side, wakelock is acquired and a response
+is returned to the caller.</li>
+<li>After the response is processed by all modules, acknowledgement is
+sent (via socket) back to <code>ril.cpp</code>, which then releases the wakelock
+acquired in step 3.</li>
 </ol>
 
-<p>Note that the wakelock timeout duration for the request-ack sequence
-would be smaller than the currently used timeout duration because the ack
-should be received back fairly quickly.</p>
-
-<h6>Solution part 2</h6>
-
-<p>In this scenario, wakelock is not held by modem and response is quick
-(synchronous RIL request and response).</p>
+<p><strong>Solution 2:</strong> The modem does not hold the wakelock and the
+response is quick (synchronous RIL request and response). The synchronous vs.
+asynchronous behavior is hardcoded for a specific RIL command and decided on a
+call-by-callbasis.</p>
 
 <p><img src="images/ril-refactor-scenario-1-solution-2.png"></p>
-
-<p>As shown in the above sequence diagram:</p>
+<figcaption><strong>Figure 3.</strong> Wakelock not held by modem.</figcaption>
 
 <ol>
 <li>RIL request is sent by calling <code>acquireWakeLock()</code> on the
 Java side.</li>
-
 <li>Vendor code doesn't need to acquire wakelock and can process the request
 and respond quickly.</li>
-
 <li>When the response is received by the Java side,
 <code>decrementWakeLock()</code> is called, which decreases wakelock counter
 and releases wakelock if the counter value is 0.</li>
 </ol>
 
-<p>Note that this synchronous vs. asynchronous behavior is hardcoded for a
-particular RIL command and decided on a call-by-call basis.</p>
-
-<h5>Scenario 2: RIL unsolicited response</h5>
+<h4>Scenario: RIL unsolicited response</h4>
+<p>In this scenario, RIL unsolicited responses have a wakelock type flag in the
+that indicates whether a wakelock needs to be acquired for the vendor response.
+If the flag is set, a timed wakelock is set and the response is sent over a
+socket to the Java side. When the timer expires, the wakelock is released. The
+timed wakelock could be too long or too short for different RIL unsolicited
+responses.</p>
 
 <p><img src="images/ril-refactor-scenario-2.png"></p>
+<figcaption><strong>Figure 4.</strong> RIL unsolicited response.</figcaption>
 
-<p>As shown in the above diagram, RIL unsolicited responses have a wakelock
-type flag in the response that indicates whether a wakelock needs to be
-acquired or not for the particular response received from the vendor. If
-the flag is set, then a timed wakelock is set and response is sent over a
-socket to the Java side. When the timer expires, the wakelock is released.</p>
-
-<h6>Problem</h6>
-
-<p>The timed wakelock illustrated in Scenario 2 could be too long or too
-short for different RIL unsolicited responses.</p>
-
-<h6>Solution</h6>
+<p><strong>Solution:</strong> An acknowledgement is sent from the Java code to
+the native side (<code>ril.cpp</code>) instead of holding a timed wakelock on
+the native side while sending an unsolicited response.</p>
 
 <p><img src="images/ril-refactor-scenario-2-solution.png"></p>
+<figcaption><strong>Figure 5.</strong> Using ack instead of timed wakelock.
+</figcaption>
 
-<p>As shown, the problem can be solved by sending an acknowledgement from
-the Java code to the native side (<code>ril.cpp</code>), instead of holding
-a timed wakelock on the native side while sending an unsolicited response.</p>
-
-<h2 id="validation">Validation</h2>
-
-<p>The following sections describe how to validate the implementation of
-the RIL refactoring feature's subfeatures.</p>
-
-<h3 id="validate-error">Validating enhanced RIL error codes</h3>
-
-<p>After adding new error codes to replace the <code>GENERIC_FAILURE</code>
-code, verify that the new error codes are returned by the RIL call instead
-of <code>GENERIC_FAILURE</code>.</p>
-
-<h3 id="validate-version">Validating enhanced RIL versioning</h3>
-
-<p>Verify that the RIL version corresponding to your RIL code is returned
-during <code>RIL_REGISTER</code> rather than the <code>RIL_VERSION</code>
-defined in <code>ril.h</code>.</p>
 
 <h3 id="validate-wakelocks">Validating redesigned wakelocks</h3>
 
-<p>Verify that RIL calls are identified as synchronous or asynchronous.</p>
-
-<p>Because battery power consumption can be hardware/platform dependent,
-vendors should do some internal testing to find out if using the new wakelock
-semantics for asynchronous calls leads to battery power savings.</p>
+<p>Verify that RIL calls are identified as synchronous or asynchronous. Because
+battery power consumption can be hardware/platform dependent, vendors should do
+some internal testing to find out if using the new wakelock semantics for
+asynchronous calls leads to battery power savings.</p>
 
   </body>
 </html>