diff options
| author | Android Partner Docs <noreply@android.com> | 2017-12-13 14:54:50 -0800 |
|---|---|---|
| committer | Clay Murphy <claym@google.com> | 2017-12-13 18:20:47 -0800 |
| commit | f2a1d5fd53891b0cb7d2a1c55e4311bc694170cd (patch) | |
| tree | 02bf4951c677b1321ed7ea0dae7ed0a236f777d0 /en/devices | |
| parent | ec1edb605d9e6f51682a99402a115ad7245e919f (diff) | |
| download | source.android.com-f2a1d5fd53891b0cb7d2a1c55e4311bc694170cd.tar.gz | |
Docs: Changes to source.android.com
- 178962421 Devsite localized content from translation request e87711... by Android Partner Docs <noreply@android.com>
- 178945337 HIDL doc: Suggest better translation to "reader" by Android Partner Docs <noreply@android.com>
- 178916026 Devsite localized content from translation request 05a572... by Android Partner Docs <noreply@android.com>
- 178910606 Devsite localized content from translation request 4f1426... by Android Partner Docs <noreply@android.com>
- 178909389 Devsite localized content from translation request c6e552... by Android Partner Docs <noreply@android.com>
- 178909386 Devsite localized content from translation request df62d7... by Android Partner Docs <noreply@android.com>
- 178857091 Devsite localized content from translation request 6295af... by Android Partner Docs <noreply@android.com>
- 178856700 updated researcher's twitter link by Android Partner Docs <noreply@android.com>
- 178815522 Change misleading leading "#" before a shell commnad to m... by Christina Nguyen <cqn@google.com>
- 178660447 Updating whitelist instructions, some formatting fixes as... by Heidi von Markham <hvm@google.com>
- 178647210 Incorporate Elliott's clarification updates to the A/B OT... by Christina Nguyen <cqn@google.com>
- 178643130 Update systrace guide with bigger screenshots and reworke... by Billy Lamberta <blamb@google.com>
- 178622648 Devsite localized content from translation request af34f0... by Android Partner Docs <noreply@android.com>
- 178622644 Devsite localized content from translation request 517746... by Android Partner Docs <noreply@android.com>
- 178482700 Remove outdated JIT recommendations for low ram. by Android Partner Docs <noreply@android.com>
- 178444767 Updating Git and Repo overview, removing git page by Heidi von Markham <hvm@google.com>
- 178442891 Add Android 8.0 security enhancements by Danielle Roberts <daroberts@google.com>
- 178395150 Devsite localized content from translation request bf46b0... by Android Partner Docs <noreply@android.com>
- 178395145 Devsite localized content from translation request eea056... by Android Partner Docs <noreply@android.com>
- 178252225 Devsite localized content from translation request b00a9b... by Android Partner Docs <noreply@android.com>
- 178152122 Add AOSP links to December bulletins by Danielle Roberts <daroberts@google.com>
- 178140880 Fix link to named anchor by Clay Murphy <claym@google.com>
- 178116086 Update Oreo MR1's API level. by Android Partner Docs <noreply@android.com>
PiperOrigin-RevId: 178962421
Change-Id: I21bb710ff8e7c4c132c41b0d799edf17c7b2fff1
Diffstat (limited to 'en/devices')
22 files changed, 389 insertions, 249 deletions
diff --git a/en/devices/tech/config/perms-whitelist.html b/en/devices/tech/config/perms-whitelist.html index 0ec1f21c..c3de0de0 100644 --- a/en/devices/tech/config/perms-whitelist.html +++ b/en/devices/tech/config/perms-whitelist.html @@ -1,6 +1,6 @@ <html devsite> <head> - <title>Privileged Permission Whitelist Requirement</title> + <title>Privileged Permission Whitelisting</title> <meta name="project_path" value="/_project.yaml" /> <meta name="book_path" value="/_book.yaml" /> </head> @@ -20,173 +20,151 @@ See the License for the specific language governing permissions and limitations under the License. --> - <p> - Historically device implementers had little control over which - signature|privileged permissions could be granted to privileged apps. - Privileged applications are system applications that are located in - <code>/system/priv-app</code> directory on the system image. - </p> - - <p> - Starting in Android 8.0, all privileged apps must be explicitly whitelisted in - system configuration XML files in the <code>/etc/permissions</code> directory. - If they are not, then the device will boot, but the device implementation will - not pass CTS. - </p> - - <h2 id="adding-the-whitelists">Adding the whitelists</h2> - - <p> - Permission whitelists for applications can be listed in a single or multiple XML - files located in the <code>frameworks/base/etc/permissions</code> directory, as follows: - </p> - - <ul> - <li><code>/etc/permissions/privapp-permissions-<OEM_NAME>.xml</code> - <li><code>/etc/permissions/privapp-permissions-<DEVICE_NAME>.xml</code>. - </ul> - - <p> - There is no strict rule for organizing content, it can be decided by the device implementer as - long as all applications from <code>/system/priv-app</code> are whitelisted. For - example, Google has a single whitelist for all privileged applications developed - by Google. - </p> - - <p> - The following organization is recommended: - </p> - - <ul> - <li>Permissions for apps that are already included in AOSP tree are listed in - this file: <code>/etc/permissions/privapp-permissions-platform.xml</code> - <li>Permissions for Google applications are listed in this file: - <code>/etc/permissions/privapp-permissions-google.xml </code> - <li>For other applications, use files of the form: - <code> - /etc/permissions/privapp-permissions-<device_name>.xml</code></li> - </ul> - - <h3 id="whitelist-generation-tool">Whitelist generation tool</h3> - - <p> - A whitelist for all applications available on the system image can be - automatically generated using a command-line tool available in AOSP, at the - following location: - </p> - - <pre - class="prettyprint">development/tools/privapp_permissions/privapp_permissions.py</pre> - - <p> - To generate an initial version of device-specific - <code>privapp-permissions.xml</code>, complete the following steps: - - </p> - <ol> - <li>Build a system image, as follows:<br> - <pre class="devsite-click-to-copy"> -<code class="devsite-terminal">. build/envsetup.sh</code> -<code class="devsite-terminal">lunch product_name</code> -<code class="devsite-terminal">make -j</code></pre> - </li> - - <li>Run the following tool to generate a <code>privapp-permissions.xml - </code>file that lists all signature|privileged permissions that are required to - be whitelisted.<br /> - <pre class="devsite-terminal devsite-click-to-copy">development/tools/privapp_permissions/privapp_permissions.py</pre> - - This tool prints XML content that can be used as a single file or split into - multiple files in <code>/etc/permissions</code>.<br><br> - If device already includes whitelists in the <code>/etc/permissions</code> directory, the tool - prints the difference, that is, only the missing signature|privileged - permissions that need to be added to the whitelist. This is also useful for - audit purposes, when a new version of the app is added, the tool will detect the - additional permissions needed. - </li> - <li>Copy the generated files to the <code>/etc/permissions</code> directory, where the system - will read it during boot.</li> - </ol> - <h3 id="whitelist-format">Whitelist format</h3> - <ul> - <li>Since the implementation is already in AOSP, only customization is needed. - <li>Permissions for apps that are included in AOSP tree are already whitelisted - in <code>/etc/permissions/privapp-permissions-platform.xml</code> - </li> - </ul> - - +<p> + Privileged applications are system applications located in the + <code>/system/priv-app</code> directory on the system image. Historically, + device implementers had little control over which signature|privileged + permissions could be granted to privileged apps. Starting in Android 8.0, + implementors can explicitly whitelist privileged apps in the system + configuration XML files in the <code>/etc/permissions</code> directory. Apps + not explicitly listed in these XML files are not granted privileged + permissions. +</p> + +<h2 id="adding-whitelists">Adding whitelists</h2> +<p> + Permission whitelists for applications can be listed in a single or multiple + XML files located in the <code>frameworks/base/etc/permissions</code> + directory as follows: +</p> + +<ul> + <li><code>/etc/permissions/privapp-permissions-<var>OEM_NAME</var>.xml</code> + <li><code>/etc/permissions/privapp-permissions-<var>DEVICE_NAME</var>.xml</code> +</ul> + +<p>There is no strict rule for organizing content. Device implementers can + determine content structure as long as all applications from + <code>/system/priv-app</code> are whitelisted. For example, Google has a + single whitelist for all privileged applications developed by Google. We + recommend the following organization: +</p> + +<ul> + <li>Permissions for apps that are already included in the Android Open Source + Project (AOSP) tree are listed in + <code>/etc/permissions/privapp-permissions-platform.xml</code>.</li> + <li>Permissions for Google applications are listed in + <code>/etc/permissions/privapp-permissions-google.xml</code>.</li> + <li>For other applications, use files of the form: + <code>/etc/permissions/privapp-permissions-<var>DEVICE_NAME</var>.xml</code>. + </li> +</ul> + +<h3 id="generating-whitelists">Generating whitelists</h3> + +<p> + To automatically generate a whitelist for all applications available on the + system image, use the AOSP command line tool at + <code>development/tools/privapp_permissions/privapp_permissions.py</code>. To + generate an initial version of device-specific + <code>privapp-permissions.xml</code>: +</p> + +<ol> + <li>Build a system image: + <pre class="devsite-click-to-copy"> + <code class="devsite-terminal">. build/envsetup.sh</code> + <code class="devsite-terminal">lunch <var>PRODUCT_NAME</var></code> + <code class="devsite-terminal">make -j</code></pre> + </li> + <li>Run the <code>privapp_permissions.py</code> script to generate a + <code>privapp-permissions.xml</code>file that lists all + signature|privileged permissions required to be whitelisted: + <pre class="devsite-terminal devsite-click-to-copy">development/tools/privapp_permissions/privapp_permissions.py</pre> + This tool prints XML content that can be used as a single file or split into + multiple files in <code>/etc/permissions</code>. + If the device already includes whitelists in the + <code>/etc/permissions</code> directory, the tool prints the differences + only (i.e. the missing signature|privileged permissions to be added to the + whitelist). This is also useful for audit purposes: When a new version of + the app is added, the tool detects the additional permissions needed. + </li> + <li>Copy the generated files to the <code>/etc/permissions</code> directory, + where the system will read those files during boot.</li> +</ol> + +<h3 id="customizing-whitelists">Customizing whitelists</h3> + +<p> + AOSP includes a whitelist implementation that can be customized as needed. + Permissions for apps included in AOSP are already whitelisted in + <code>/etc/permissions/privapp-permissions-platform.xml</code>. +</p> + +<p> + By default, the <code>privapp_permissions.py</code> script generates output + that automatically grants any permission requested by a privileged + application. If there are permissions that should be denied, edit the XML to + use a "deny-permission" tag instead of a "permission" tag. Example: +</p> <pre class="prettyprint"><!-- - This XML file declares which signature|privileged permissions should be granted to privileged - applications that come with the platform + This XML file declares which signature|privileged permissions should be + granted to privileged applications that come with the platform --> <permissions> - <privapp-permissions package="com.android.backupconfirm"> - <permission name="android.permission.BACKUP"/> - <permission name="android.permission.CRYPT_KEEPER"/> - </privapp-permissions> - <privapp-permissions package="com.android.cellbroadcastreceiver"> - <permission name="android.permission.INTERACT_ACROSS_USERS"/> - <permission name="android.permission.MANAGE_USERS"/> - <permission name="android.permission.MODIFY_PHONE_STATE"/> - <permission name="android.permission.READ_PRIVILEGED_PHONE_STATE"/> - <permission name="android.permission.RECEIVE_EMERGENCY_BROADCAST"/> - </privapp-permissions> +<privapp-permissions package="com.android.backupconfirm"> + <permission name="android.permission.BACKUP"/> + <permission name="android.permission.CRYPT_KEEPER"/> +</privapp-permissions> +<privapp-permissions package="com.android.cellbroadcastreceiver"> + <!-- don't allow application to interact across users --> + <deny-permission name="android.permission.INTERACT_ACROSS_USERS"/> + <permission name="android.permission.MANAGE_USERS"/> + <permission name="android.permission.MODIFY_PHONE_STATE"/> + <permission name="android.permission.READ_PRIVILEGED_PHONE_STATE"/> + <permission name="android.permission.RECEIVE_EMERGENCY_BROADCAST"/> +</privapp-permissions> ...</pre> - <h3 id="enabling-logs-to-find-missing-permissions">Enabling logs to find missing - permissions</h3> - <p> - When bringing up a new device, we recommend enabling transitional log-mode at - first, as follows: - </p> - <p> - <strong> <code>ro.control_privapp_permission=log</code> </strong> - - <p> - The violations will be reported in the log file, but permissions will still be - granted. This will keep device in a working state, while providing the list of - violations. - </p> - <p> - Error message format is as follows: - </p> - <p> - - <code>PackageManager: Privileged permission {PERMISSION_NAME} for package - {PACKAGE_NAME} - not in privapp-permissions whitelist</code> - </p> - <p> - All violations must be addressed by adding them to whitelists. Otherwise device - will not pass CTS tests. - </p> - <h2 id="cts-tests-for-whitelists">CTS tests for whitelists</h2> - <p> - Your device implementation will not pass CTS if it contains privileged apps that - do not appear in a whitelist at <code>/etc/permissions.</code> - </p> - <p> - <code>The </code>PrivappPermissionsTest.java test enforces the - signature|privileged permission whitelist, as follows: - </p><ul> - <li>Reports the permissions that are granted into the CTS log. - <li>Ensures all priv permissions are exclusively granted to applications - declared in <code><privapp-permissions>,</code> i.e. it will fail if a - privileged application is requesting signature|privileged permission that is not - whitelisted or a whitelisted permission wasn't granted by the system.</li></ul> - <h2 id="run-time-enforcement-of-whitelists">Run-time enforcement of - whitelists</h2> - <p> - Once the whitelists are in place, run-time enforcement can be enabled by setting - a build property <code>ro.control_privapp_permission=enforce</code>. - </p> - <p> - <strong>Note: </strong>Please note that regardless of - <code>ro.control_privapp_permission</code> property state, only devices with - properly whitelisted privileged permissions for all privileged applications will - pass CTS tests. - </p> +<h3 id="finding-missing-permissions">Finding missing permissions</h3> + +<p> + When bringing up a new device, find missing permissions by enabling + transitional log-mode: +</p> + +<pre class="devsite-click-to-copy">ro.control_privapp_permission=log</pre> + +<p> + Violations are reported in the log file, but permissions are still granted. + This keeps the device in a working state while providing the list of + violations. The error message format is as follows: +</p> + +<pre class="devsite-click-to-copy"> +PackageManager: Privileged permission {PERMISSION_NAME} for package {PACKAGE_NAME} - not in privapp-permissions whitelist +</pre> + +<p> + All violations must be addressed by adding the apps to whitelists. If not + added, the apps will not be granted the missing permissions even if they are + in the priv-app path. +</p> + + +<h2 id="enforcing-whitelists">Enforcing whitelists</h2> + +<p> + After whitelists are in place, enable runtime enforcement by setting the build + property <code>ro.control_privapp_permission=enforce</code>. +</p> + +<aside class="note"><strong>Note:</strong> The + <code>ro.control_privapp_permission</code> property state must adhere to + <a href="/compatibility/android-cdd#9_1_permissions">CDD section 9.1 + requirements</a>.</aside> </body> </html> diff --git a/en/devices/tech/debug/images/perf_trace_binder_trans.png b/en/devices/tech/debug/images/perf_trace_binder_trans.png Binary files differindex 7d9fe135..9eb5b13f 100644 --- a/en/devices/tech/debug/images/perf_trace_binder_trans.png +++ b/en/devices/tech/debug/images/perf_trace_binder_trans.png diff --git a/en/devices/tech/debug/images/perf_trace_fence_end.png b/en/devices/tech/debug/images/perf_trace_fence_end.png Binary files differindex 251701e9..3adbb3d1 100644 --- a/en/devices/tech/debug/images/perf_trace_fence_end.png +++ b/en/devices/tech/debug/images/perf_trace_fence_end.png diff --git a/en/devices/tech/debug/images/perf_trace_fences.png b/en/devices/tech/debug/images/perf_trace_fences.png Binary files differnew file mode 100644 index 00000000..ef65a2ac --- /dev/null +++ b/en/devices/tech/debug/images/perf_trace_fences.png diff --git a/en/devices/tech/debug/images/perf_trace_fm_sf.png b/en/devices/tech/debug/images/perf_trace_fm_sf.png Binary files differindex 82907f99..c3e4f031 100644 --- a/en/devices/tech/debug/images/perf_trace_fm_sf.png +++ b/en/devices/tech/debug/images/perf_trace_fm_sf.png diff --git a/en/devices/tech/debug/images/perf_trace_frame_previous.png b/en/devices/tech/debug/images/perf_trace_frame_previous.png Binary files differindex 8fdc746b..10a79075 100644 --- a/en/devices/tech/debug/images/perf_trace_frame_previous.png +++ b/en/devices/tech/debug/images/perf_trace_frame_previous.png diff --git a/en/devices/tech/debug/images/perf_trace_normal_pipeline.png b/en/devices/tech/debug/images/perf_trace_normal_pipeline.png Binary files differindex 1ede6584..a588e290 100644 --- a/en/devices/tech/debug/images/perf_trace_normal_pipeline.png +++ b/en/devices/tech/debug/images/perf_trace_normal_pipeline.png diff --git a/en/devices/tech/debug/images/perf_trace_pending_frames.png b/en/devices/tech/debug/images/perf_trace_pending_frames.png Binary files differindex ed514351..19eb501a 100644 --- a/en/devices/tech/debug/images/perf_trace_pending_frames.png +++ b/en/devices/tech/debug/images/perf_trace_pending_frames.png diff --git a/en/devices/tech/debug/images/perf_trace_previous_frame.png b/en/devices/tech/debug/images/perf_trace_previous_frame.png Binary files differindex c1c9bb64..0945299e 100644 --- a/en/devices/tech/debug/images/perf_trace_previous_frame.png +++ b/en/devices/tech/debug/images/perf_trace_previous_frame.png diff --git a/en/devices/tech/debug/images/perf_trace_sf_comp_submit.png b/en/devices/tech/debug/images/perf_trace_sf_comp_submit.png Binary files differindex 03bdea1c..f2033f6b 100644 --- a/en/devices/tech/debug/images/perf_trace_sf_comp_submit.png +++ b/en/devices/tech/debug/images/perf_trace_sf_comp_submit.png diff --git a/en/devices/tech/debug/images/perf_trace_sf_latches_pend.png b/en/devices/tech/debug/images/perf_trace_sf_latches_pend.png Binary files differindex 36ca7314..29d7f188 100644 --- a/en/devices/tech/debug/images/perf_trace_sf_latches_pend.png +++ b/en/devices/tech/debug/images/perf_trace_sf_latches_pend.png diff --git a/en/devices/tech/debug/images/perf_trace_sf_wake_sleep.png b/en/devices/tech/debug/images/perf_trace_sf_wake_sleep.png Binary files differindex a0010382..6797fe3a 100644 --- a/en/devices/tech/debug/images/perf_trace_sf_wake_sleep.png +++ b/en/devices/tech/debug/images/perf_trace_sf_wake_sleep.png diff --git a/en/devices/tech/debug/images/perf_trace_sf_woken_et.png b/en/devices/tech/debug/images/perf_trace_sf_woken_et.png Binary files differindex f1ac8e65..1383d425 100644 --- a/en/devices/tech/debug/images/perf_trace_sf_woken_et.png +++ b/en/devices/tech/debug/images/perf_trace_sf_woken_et.png diff --git a/en/devices/tech/debug/images/perf_trace_tl.png b/en/devices/tech/debug/images/perf_trace_tl.png Binary files differindex 9665d1f2..113f3306 100644 --- a/en/devices/tech/debug/images/perf_trace_tl.png +++ b/en/devices/tech/debug/images/perf_trace_tl.png diff --git a/en/devices/tech/debug/images/perf_trace_tl_pxl.png b/en/devices/tech/debug/images/perf_trace_tl_pxl.png Binary files differindex b922d492..55bc94c9 100644 --- a/en/devices/tech/debug/images/perf_trace_tl_pxl.png +++ b/en/devices/tech/debug/images/perf_trace_tl_pxl.png diff --git a/en/devices/tech/debug/images/perf_trace_wake_cpu0.png b/en/devices/tech/debug/images/perf_trace_wake_cpu0.png Binary files differindex 7f60c837..bf7872a5 100644 --- a/en/devices/tech/debug/images/perf_trace_wake_cpu0.png +++ b/en/devices/tech/debug/images/perf_trace_wake_cpu0.png diff --git a/en/devices/tech/debug/images/perf_trace_wake_render_enqueue.png b/en/devices/tech/debug/images/perf_trace_wake_render_enqueue.png Binary files differindex d6ed95c2..44f4e7fe 100644 --- a/en/devices/tech/debug/images/perf_trace_wake_render_enqueue.png +++ b/en/devices/tech/debug/images/perf_trace_wake_render_enqueue.png diff --git a/en/devices/tech/debug/images/perf_traces_fences.png b/en/devices/tech/debug/images/perf_traces_fences.png Binary files differdeleted file mode 100644 index e8662f7b..00000000 --- a/en/devices/tech/debug/images/perf_traces_fences.png +++ /dev/null diff --git a/en/devices/tech/debug/systrace.html b/en/devices/tech/debug/systrace.html index 036bd6da..6d627421 100644 --- a/en/devices/tech/debug/systrace.html +++ b/en/devices/tech/debug/systrace.html @@ -108,9 +108,16 @@ back to sleep, waiting for EventThread wakeup.</li> <p>Let's walk through the frame beginning at 15409ms:</p> -<p><img src="/devices/tech/debug/images/perf_trace_normal_pipeline.png"></p> -<p class="img-caption"><strong>Figure 1.</strong> Normal UI pipeline, -EventThread running.</p> +<figure> + <a href="/devices/tech/debug/images/perf_trace_normal_pipeline.png" + title="Click to enlarge"> + <img src="/devices/tech/debug/images/perf_trace_normal_pipeline.png" + class="screenshot"> + </a> + <figcaption> + <strong>Figure 1.</strong> Normal UI pipeline, EventThread running. + </figcaption> +</figure> <p>Figure 1 is a normal frame surrounded by normal frames, so it's a good starting point for understanding how the UI pipeline works. The UI thread row @@ -141,23 +148,45 @@ sleep slice.</p> <p>While EventThread is running, the UI thread for TouchLatency becomes runnable. To see what woke it, click the blue section:</p> -<p><img src="/devices/tech/debug/images/perf_trace_tl.png"></p> -<p class="img-caption"><strong>Figure 2.</strong> UI thread for -TouchLatency.</p> +<figure> + <a href="/devices/tech/debug/images/perf_trace_tl.png" + title="Click to enlarge"> + <img src="/devices/tech/debug/images/perf_trace_tl.png" class="screenshot"> + </a> + <figcaption> + <strong>Figure 2.</strong> UI thread for TouchLatency. + </figcaption> +</figure> <p>Figure 2 shows the TouchLatency UI thread was woken by tid 6843, which corresponds to EventThread. The UI thread wakes:</p> -<p><img src="/devices/tech/debug/images/perf_trace_wake_render_enqueue.png"></p> -<p class="img-caption"><strong>Figure 3.</strong> UI thread wakes, renders a -frame, and enqueues it for SurfaceFlinger to consume.</p> +<figure> + <a href="/devices/tech/debug/images/perf_trace_wake_render_enqueue.png" + title="Click to enlarge"> + <img src="/devices/tech/debug/images/perf_trace_wake_render_enqueue.png" + class="screenshot"> + </a> + <figcaption> + <strong>Figure 3.</strong> UI thread wakes, renders a frame, and enqueues it + for SurfaceFlinger to consume. + </figcaption> +</figure> <p>If the <code>binder_driver</code> tag is enabled in a trace, you can select a binder transaction to view information on all of the processes involved in that transaction:</p> -<p><img src="/devices/tech/debug/images/perf_trace_binder_trans.png"></p> -<p class="img-caption"><strong>Figure 4.</strong> Binder transaction.</p> +<figure> + <a href="/devices/tech/debug/images/perf_trace_binder_trans.png" + title="Click to enlarge"> + <img src="/devices/tech/debug/images/perf_trace_binder_trans.png" + class="screenshot"> + </a> + <figcaption> + <strong>Figure 4.</strong> Binder transaction. + </figcaption> +</figure> <p>Figure 4 shows that, at 15,423.65ms, Binder:6832_1 in SurfaceFlinger becomes runnable because of tid 9579, which is TouchLatency's RenderThread. You can also @@ -166,9 +195,16 @@ see queueBuffer on both sides of the binder transaction.</p> <p>During the queueBuffer on the SurfaceFlinger side, the number of pending frames from TouchLatency goes from 1 to 2:</p> -<p><img src="/devices/tech/debug/images/perf_trace_pending_frames.png"></p> -<p class="img-caption"><strong>Figure 5.</strong> Pending frames goes from 1 to -2.</p> +<figure> + <a href="/devices/tech/debug/images/perf_trace_pending_frames.png" + title="Click to enlarge"> + <img src="/devices/tech/debug/images/perf_trace_pending_frames.png" + class="screenshot"> + </a> + <figcaption> + <strong>Figure 5.</strong> Pending frames goes from 1 to 2. + </figcaption> +</figure> <p>Figure 5 shows triple-buffering, where there are two completed frames and the app will soon start rendering a third. This is because we've already dropped @@ -178,33 +214,64 @@ further dropped frames.</p> <p>Soon after, SurfaceFlinger's main thread is woken by a second EventThread so it can output the older pending frame to the display:</p> -<p><img src="/devices/tech/debug/images/perf_trace_sf_woken_et.png"></p> -<p class="img-caption"><strong>Figure 6.</strong> SurfaceFlinger's main thread -is woken by a second EventThread.</p> +<figure> + <a href="/devices/tech/debug/images/perf_trace_sf_woken_et.png" + title="Click to enlarge"> + <img src="/devices/tech/debug/images/perf_trace_sf_woken_et.png" + class="screenshot"> + </a> + <figcaption> + <strong>Figure 6.</strong> SurfaceFlinger's main thread is woken by a second + EventThread. + </figcaption> +</figure> <p>SurfaceFlinger first latches the older pending buffer, which causes the pending buffer count to decrease from 2 to 1:</p> -<p><img src="/devices/tech/debug/images/perf_trace_sf_latches_pend.png"></p> -<p class="img-caption"><strong>Figure 7.</strong> SurfaceFlinger first latches -the older pending buffer.</p> +<figure> + <a href="/devices/tech/debug/images/perf_trace_sf_latches_pend.png" + title="Click to enlarge"> + <img src="/devices/tech/debug/images/perf_trace_sf_latches_pend.png" + class="screenshot"> + </a> + <figcaption> + <strong>Figure 7.</strong> SurfaceFlinger first latches the older pending + buffer. + </figcaption> +</figure> <p>After latching the buffer, SurfaceFlinger sets up composition and submits the final frame to the display. (Some of these sections are enabled as part of the <code>mdss</code> tracepoint, so they may not be there on your SOC.)</p> -<p><img src="/devices/tech/debug/images/perf_trace_sf_comp_submit.png"></p> -<p class="img-caption"><strong>Figure 8.</strong> SurfaceFlinger sets up -composition and submits the final frame.</p> +<figure> + <a href="/devices/tech/debug/images/perf_trace_sf_comp_submit.png" + title="Click to enlarge"> + <img src="/devices/tech/debug/images/perf_trace_sf_comp_submit.png" + class="screenshot"> + </a> + <figcaption> + <strong>Figure 8.</strong> SurfaceFlinger sets up composition and submits the + final frame. + </figcaption> +</figure> <p>Next, <code>mdss_fb0</code> wakes on CPU 0. <code>mdss_fb0</code> is the display pipeline's kernel thread for outputting a rendered frame to the display. We can see <code>mdss_fb0</code> as its own row in the trace (scroll down to view).</p> -<p><img src="/devices/tech/debug/images/perf_trace_wake_cpu0.png"></p> -<p class="img-caption"><strong>Figure 9.</strong> <code>mdss_fb0</code> wakes -on CPU 0.</p> +<figure> + <a href="/devices/tech/debug/images/perf_trace_wake_cpu0.png" + title="Click to enlarge"> + <img src="/devices/tech/debug/images/perf_trace_wake_cpu0.png" + class="screenshot"> + </a> + <figcaption> + <strong>Figure 9.</strong> <code>mdss_fb0</code> wakes on CPU 0. + </figcaption> +</figure> <p><code>mdss_fb0</code> wakes up, runs for a bit, enters uninterruptible sleep, then wakes again.</p> @@ -224,9 +291,17 @@ browser.</p> <p>When you first open the systrace, you'll see something like this:</p> -<p><img src="/devices/tech/debug/images/perf_trace_tl_pxl.png"></p> -<p class="img-caption"><strong>Figure 10</strong>. TouchLatency running on Pixel -XL (most options enabled, including mdss and kgsl tracepoints).</p> +<figure> + <a href="/devices/tech/debug/images/perf_trace_tl_pxl.png" + title="Click to enlarge"> + <img src="/devices/tech/debug/images/perf_trace_tl_pxl.png" + class="screenshot"> + </a> + <figcaption> + <strong>Figure 10</strong>. TouchLatency running on Pixel XL (most options + enabled, including mdss and kgsl tracepoints). + </figcaption> +</figure> <p>When looking for jank, check the FrameMissed row under SurfaceFlinger. FrameMissed is a quality-of-life improvement provided by Hardware Composer 2 @@ -236,9 +311,16 @@ case, FrameMissed is correlated with SurfaceFlinger missing one of its extremely-regular runtimes and an unchanged pending-buffer count for the app (<code>com.prefabulated.touchlatency</code>) at a vsync:</p> -<p><img src="/devices/tech/debug/images/perf_trace_fm_sf.png"></p> -<p class="img-caption"><strong>Figure 11</strong>. FrameMissed correlation with -SurfaceFlinger.</p> +<figure> + <a href="/devices/tech/debug/images/perf_trace_fm_sf.png" + title="Click to enlarge"> + <img src="/devices/tech/debug/images/perf_trace_fm_sf.png" + class="screenshot"> + </a> + <figcaption> + <strong>Figure 11</strong>. FrameMissed correlation with SurfaceFlinger. + </figcaption> +</figure> <p>Figure 11 shows a missed frame at 15598.29ms. SurfaceFlinger woke briefly at the vsync interval and went back to sleep without doing any work, which means @@ -252,9 +334,17 @@ SurfaceFlinger wakes and immediately goes to sleep. When viewing the number of pending frames from TouchLatency, there are two frames (a good clue to help figure out what's going on).</p> -<p><img src="/devices/tech/debug/images/perf_trace_sf_wake_sleep.png"></p> -<p class="img-caption"><strong>Figure 12.</strong> SurfaceFlinger wakes and -immediately goes to sleep.</p> +<figure> + <a href="/devices/tech/debug/images/perf_trace_sf_wake_sleep.png" + title="Click to enlarge"> + <img src="/devices/tech/debug/images/perf_trace_sf_wake_sleep.png" + class="screenshot"> + </a> + <figcaption> + <strong>Figure 12.</strong> SurfaceFlinger wakes and immediately goes to + sleep. + </figcaption> +</figure> <p>Because we have frames in SurfaceFlinger, it's not an app issue. In addition, SurfaceFlinger is waking at the correct time, so it's not a SurfaceFlinger @@ -271,17 +361,31 @@ particular events in SurfaceFlinger depends on your SOC and driver stack, so work with your SOC vendor to understand the meaning of fence categories in your traces.</p> -<p><img src="/devices/tech/debug/images/perf_traces_fences.png"></p> -<p class="img-caption"><strong>Figure 13.</strong> <code>mdss_fb0_retire</code> -fences.</p> +<figure> + <a href="/devices/tech/debug/images/perf_trace_fences.png" + title="Click to enlarge"> + <img src="/devices/tech/debug/images/perf_trace_fences.png" + class="screenshot"> + </a> + <figcaption> + <strong>Figure 13.</strong> <code>mdss_fb0_retire</code> fences. + </figcaption> +</figure> <p>Figure 13 shows a frame that was displayed for 33ms, not 16.7ms as expected. Halfway through that slice, that frame should have been replaced by a new one but wasn't. View the previous frame and look for anything interesting:</p> -<p><img src="/devices/tech/debug/images/perf_trace_frame_previous.png"></p> -<p class="img-caption"><strong>Figure 14.</strong> Frame previous to busted -frame.</p> +<figure> + <a href="/devices/tech/debug/images/perf_trace_frame_previous.png" + title="Click to enlarge"> + <img src="/devices/tech/debug/images/perf_trace_frame_previous.png" + class="screenshot"> + </a> + <figcaption> + <strong>Figure 14.</strong> Frame previous to busted frame. + </figcaption> +</figure> <p>Figure 14 shows 14.482ms a frame. The busted two-frame segment was 33.6ms, which is roughly what we would expect for two frames (we render at 60Hz, 16.7ms @@ -290,8 +394,16 @@ suggests that something is very wrong with the display pipe.</p> <p>Investigate exactly where that fence ends to determine what controls it:</p> -<p><img src="/devices/tech/debug/images/perf_trace_fence_end.png"></p> -<p class="img-caption"><strong>Figure 15.</strong> Investigate fence end.</p> +<figure> + <a href="/devices/tech/debug/images/perf_trace_fence_end.png" + title="Click to enlarge"> + <img src="/devices/tech/debug/images/perf_trace_fence_end.png" + class="screenshot"> + </a> + <figcaption> + <strong>Figure 15.</strong> Investigate fence end. + </figcaption> +</figure> <p>A workqueue contains a <code>__vsync_retire_work_handler</code> that is running when the fence changes. Looking through the kernel source, you can see @@ -303,8 +415,16 @@ might not get scheduled accurately.</p> <p>Check the previous frame to determine if that contributed; sometimes jitter can add up over time and eventually cause us to miss a deadline.</p> -<p><img src="/devices/tech/debug/images/perf_trace_previous_frame.png"></p> -<p class="img-caption"><strong>Figure 16.</strong> Previous frame.</p> +<figure> + <a href="/devices/tech/debug/images/perf_trace_previous_frame.png" + title="Click to enlarge"> + <img src="/devices/tech/debug/images/perf_trace_previous_frame.png" + class="screenshot"> + </a> + <figcaption> + <strong>Figure 16.</strong> Previous frame. + </figcaption> +</figure> <p>The runnable line on the kworker isn't visible because the viewer turns it white when it's selected, but the statistics tell the story: 2.3ms of scheduler diff --git a/en/devices/tech/index.html b/en/devices/tech/index.html index 1e2c200b..aafb7e0b 100644 --- a/en/devices/tech/index.html +++ b/en/devices/tech/index.html @@ -40,7 +40,8 @@ Information</a></p> <h2 id="config">Configuration</h2> <p>Getting the most out of Android requires tuning of the <a -href="/devices/tech/config/kernel.html">kernel</a> and +href="/devices/tech/config/kernel.html">kernel</a>, <a +href="/devices/tech/config/renderer.html">OpenGLRenderer</a>, and more. See the subpages of this section for details. <p><a href="/devices/tech/config/index.html">» Configuration Information</a></p> diff --git a/en/devices/tech/ota/ab_updates.html b/en/devices/tech/ota/ab_updates.html index 5dc04c2a..8f680c6e 100644 --- a/en/devices/tech/ota/ab_updates.html +++ b/en/devices/tech/ota/ab_updates.html @@ -36,14 +36,22 @@ <ul> <li> OTA updates can occur while the system is running, without - interrupting the user (including app optimizations that occur after a - reboot). This means users can continue to use their devices during an - OTA—the only downtime during an update is when the device + interrupting the user. Users can continue to use their devices during + an OTA—the only downtime during an update is when the device reboots into the updated disk partition. </li> <li> - If an OTA fails, the device boots into the pre-OTA disk partition and - remains usable. The download of the OTA can be attempted again. + After an update, rebooting takes no longer than a regular reboot. + </li> + <li> + If an OTA fails to apply (for example, because of a bad flash), the + user will not be affected. The user will continue to run the old OS, + and the client is free to re-attempt the update. + </li> + <li> + If an OTA update is applied but fails to boot, the device will reboot + back into the old partition and remains usable. The client is free to + re-attempt the update. </li> <li> Any errors (such as I/O errors) affect only the <strong>unused</strong> @@ -59,7 +67,8 @@ </li> <li> The cache partition is no longer used to store OTA update packages, so - there is no need for sizing the cache partition. + there is no need to ensure that the cache partition is large enough for + future updates. </li> <li> <a href="/security/verifiedboot/dm-verity.html">dm-verity</a> @@ -72,7 +81,73 @@ <h2 id="overview">About A/B system updates</h2> - <p>A/B system updates affect the following:</p> + <p> + A/B updates require changes to both the client and the system. The OTA + package server, however, should not require changes: update packages + are still served over HTTPS. For devices using Google's OTA + infrastructure, the system changes are all in AOSP, and the client code + is provided by Google Play services. OEMs not using Google's OTA + infrastructure will be able to reuse the AOSP system code but will + need to supply their own client. + </p> + + <p> + For OEMs supplying their own client, the client needs to: + </p> + + <ul> + <li> + Decide when to take an update. Because A/B updates happen in the + background, they are no longer user-initiated. To avoid disrupting + users, it is recommended that updates are scheduled when the device + is in idle maintenance mode, such as overnight, and on Wi-Fi. + However, your client can use any heuristics you want. + </li> + <li> + Check in with your OTA package servers and determine whether an + update is available. This should be mostly the same as your existing + client code, except that you will want to signal that the device + supports A/B. (Google's client also includes a + <strong>Check now</strong> button for users to check for the latest + update.) + </li> + <li> + Call <code>update_engine</code> with the HTTPS URL for your update + package, assuming one is available. <code>update_engine</code> will + update the raw blocks on the currently unused partition as it streams + the update package. + </li> + <li> + Report installation successes or failures to your servers, based on + the <code>update_engine</code> result code. If the update is applied + successfully, <code>update_engine</code> will tell the bootloader to + boot into the new OS on the next reboot. The bootloader will fallback + to the old OS if the new OS fails to boot, so no work is required + from the client. If the update fails, the client needs to decide when + (and whether) to try again, based on the detailed error code. For + example, a good client could recognize that a partial ("diff") OTA + package fails and try a full OTA package instead. + </li> + </ul> + + <p>Optionally, the client can:</p> + + <ul> + <li> + Show a notification asking the user to reboot. If you want to + implement a policy where the user is encouraged to routinely update, + then this notification can be added to your client. If the client + does not prompt users, then users will get the update next time they + reboot anyway. (Google's client has a per-update configurable delay.) + </li> + <li> + Show a notification telling users whether they booted into a new + OS version or whether they were expected to do so but fell back to + the old OS version. (Google's client typically does neither.) + </li> + </ul> + + <p>On the system side, A/B system updates affect the following:</p> <ul> <li> @@ -855,23 +930,6 @@ say). With A/B updates, a failure to apply an update does not affect the currently running system. The update can simply be retried later.</p> - <h3>What does GmsCore do?</h3> - - <p>In Google's A/B implementation, the platform APIs and - <code>update_engine</code> provide the mechanism while GmsCore provides the - policy. That is, the platform knows <em>how</em> to apply an A/B update and all - that code is in AOSP (as mentioned above); but it's GmsCore that decides - <em>what</em> and <em>when</em> to apply.</p> - - <p>If you’re not using GmsCore, you can write your own replacement using the - same platform APIs. The platform Java API for controlling - <code>update_engine</code> is <code>android.os.UpdateEngine</code>: - <code><a href="https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/os/UpdateEngine.java" class="external-link">frameworks/base/core/java/android/os/UpdateEngine.java</a></code>. - Callers can provide an <code>UpdateEngineCallback</code> to be notified of status - updates: - <code><a href="https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/os/UpdateEngineCallback.java" class="external-link">frameworks/base/+/master/core/java/android/os/UpdateEngineCallback.java</a></code>. - Refer to the reference files for the core classes to use the interface.</p> - <h3>Which systems on a chip (SoCs) support A/B?</h3> <p>As of 2017-03-15, we have the following information:</p> diff --git a/en/devices/tech/perf/low-ram.html b/en/devices/tech/perf/low-ram.html index 715ff5c1..1a42af85 100644 --- a/en/devices/tech/perf/low-ram.html +++ b/en/devices/tech/perf/low-ram.html @@ -87,23 +87,6 @@ they should turn off specific memory-intensive PRODUCT_PROPERTY_OVERRIDES += ro.config.low_ram=true </pre> -<h3 id="jit">Disable JIT</h3> - - <p>System-wide JIT memory usage is dependent on the number of applications - running and the code footprint of those applications. The JIT establishes a - maximum translated code cache size and touches the pages within it as needed. - JIT costs somewhere between 3M and 6M across a typical running system.<br/> - <br/> - The large apps tend to max out the code cache fairly quickly (which by default - has been 1M). On average, JIT cache usage runs somewhere between 100K and 200K - bytes per app. Reducing the max size of the cache can help somewhat with - memory usage, but if set too low will send the JIT into a thrashing mode. For -the really low-memory devices, we recommend the JIT be disabled entirely.</p> - -<p>This can be achieved by adding the following line to the product makefile:</p> -<pre class="devsite-click-to-copy"> -PRODUCT_PROPERTY_OVERRIDES += dalvik.vm.jit.codecachesize=0 -</pre> <h3 id="launcher">Launcher Configs</h3> |
