diff options
| author | Android Partner Docs <noreply@android.com> | 2017-10-11 14:15:38 -0700 |
|---|---|---|
| committer | Clay Murphy <claym@google.com> | 2017-10-11 19:19:53 -0700 |
| commit | 640dc96c73017d3bd2e2c507adcff02046ccfd3f (patch) | |
| tree | 25296dfcb38dae95ee022015e64e78bbe646ff9c | |
| parent | 4ede9c52630a6da877e7ca9c1c3801a34ddb7179 (diff) | |
| download | source.android.com-640dc96c73017d3bd2e2c507adcff02046ccfd3f.tar.gz | |
Docs: Changes to source.android.com
- 171873304 Update documentation for types-only minor version package. by Android Partner Docs <noreply@android.com>
- 171849317 Update CTS/CTS-Verifier downloads for CTS-Oct-2017 Releases by Android Partner Docs <noreply@android.com>
- 171727609 Updating panic button to 8.0 by hvm <hvm@google.com>
- 171724554 Fixing typo by hvm <hvm@google.com>
- 171604727 Removed gerund form to match TOC bar on left. by cqn <cqn@google.com>
- 171576699 Small editorial changes to make content more skimmable. by cqn <cqn@google.com>
- 171546973 Add Clang toolchain to home News section by claym <claym@google.com>
- 171540129 Corrected a typo from "has" to "have" in CTS public setup... by Android Partner Docs <noreply@android.com>
- 171354973 Clean-up edits for consistency on the HCI Requirements do... by cqn <cqn@google.com>
- 171242784 Explain Clang is lone supported toolchain going forward by claym <claym@google.com>
- 171198827 Added researcher acknowledgement by Android Partner Docs <noreply@android.com>
- 171178686 Added researcher acknowledgement by Android Partner Docs <noreply@android.com>
- 171169962 Added missing " to jit-workflow.png by daroberts <daroberts@google.com>
- 171167568 Announce KASAN+KCOV on the home page by daroberts <daroberts@google.com>
- 171093616 Updated Researcher acknowledgement by Android Partner Docs <noreply@android.com>
- 171086588 Add Building a Pixel kernel with KASAN +KCOV by daroberts <daroberts@google.com>
- 171084549 Move CVE-2017-0710 to Google devices section by Android Partner Docs <noreply@android.com>
- 171063850 Removed duped content that is now in /source/view-patches... by cqn <cqn@google.com>
- 171061697 Create a /source/view-patches page so that the nav does n... by cqn <cqn@google.com>
- 171050148 Update home page with October 2017 security release by daroberts <daroberts@google.com>
- 171028732 Devsite localized content from translation request 5cdc34... by Android Partner Docs <noreply@android.com>
- 170937091 Add tags for October security backport releases (these do... by Android Partner Docs <noreply@android.com>
- 170911440 Remove CVE-2017-0605 from bulletin by Android Partner Docs <noreply@android.com>
- 170883975 Add AOSP links to the Oct 2017 Android Security bulletin by daroberts <daroberts@google.com>
- 170883918 Add AOSP links to Oct 2017 Pixel bulletin by daroberts <daroberts@google.com>
PiperOrigin-RevId: 171873304
Change-Id: I51cdbbbf00bdf43374c06638a8db4f8e87dbcdf7
22 files changed, 1186 insertions, 616 deletions
diff --git a/en/_index.yaml b/en/_index.yaml index 0db4bd62..0e214003 100644 --- a/en/_index.yaml +++ b/en/_index.yaml @@ -72,29 +72,29 @@ landing_page: image_path: /images/android_stack.png - heading: News items: - - heading: China Site Availability + - heading: Clang is the supported toolchain description: > - This site has been released in China at source.android.google.cn. All - non-reference materials have also been translated into Simplified - Chinese for ease of use. + Android 8.0 and later support only Clang/LLVM for building the Android + platform. See the new Build toolchain section of Requirements for + additional details. buttons: - - label: September 14th, 2017 - path: https://source.android.google.cn/ - - heading: September Security Bulletin + - label: October 6th, 2017 + path: /source/requirements#toolchain + - heading: Testing with KASAN+KCOV description: > - The September 2017 Android Security Bulletin has been published along - with links to associated fixes and new build numbers to support the - September security release. + KASAN-sanitized and KCOV-instrumented code helps developers and testers + detect runtime memory errors and obtain code coverage information. buttons: - - label: September 13th, 2017 - path: /security/bulletin/2017-09-01 - - heading: Bluetooth Documentation Suite + - label: October 4th, 2017 + path: /devices/tech/debug/kasan-kcov + - heading: October Security Bulletin description: > - Bluetooth documentation has been greatly expanded to include - descriptions of services, low energy advertising, debugging, and more. + The October 2017 Android and Pixel/Nexus Security Bulletins have been + published along with links to associated fixes and new build numbers + to support the October security release. buttons: - - label: August 29th, 2017 - path: /devices/bluetooth/ + - label: October 3rd, 2017 + path: /security/bulletin/2017-10-01 - classname: devsite-landing-row-100 tf-row-centered items: - buttons: diff --git a/en/compatibility/cts/downloads.html b/en/compatibility/cts/downloads.html index bc1b12e1..231b7bb9 100644 --- a/en/compatibility/cts/downloads.html +++ b/en/compatibility/cts/downloads.html @@ -50,77 +50,77 @@ href="https://dl.google.com/dl/android/cts/android-cts-verifier-8.0_r1-linux_x86 <h2 id="android-71">Android 7.1</h2> <p>Android 7.1 is the release of the development milestone code-named Nougat-MR1. The source code for the following tests can be synced with the -'android-cts-7.1_r9' tag in the open-source tree.</p> +'android-cts-7.1_r10' tag in the open-source tree.</p> <ul> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-7.1_r9-linux_x86-arm.zip">Android -7.1 R9 Compatibility Test Suite (CTS) - ARM</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-7.1_r10-linux_x86-arm.zip">Android +7.1 R10 Compatibility Test Suite (CTS) - ARM</a></li> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-7.1_r9-linux_x86-x86.zip">Android -7.1 R9 Compatibility Test Suite (CTS) - x86</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-7.1_r10-linux_x86-x86.zip">Android +7.1 R10 Compatibility Test Suite (CTS) - x86</a></li> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-verifier-7.1_r9-linux_x86-arm.zip">Android -7.1 R9 CTS Verifier - ARM</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-verifier-7.1_r10-linux_x86-arm.zip">Android +7.1 R10 CTS Verifier - ARM</a></li> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-verifier-7.1_r9-linux_x86-x86.zip">Android -7.1 R9 CTS Verifier - x86</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-verifier-7.1_r10-linux_x86-x86.zip">Android +7.1 R10 CTS Verifier - x86</a></li> </ul> <h2 id="android-70">Android 7.0</h2> <p>Android 7.0 is the release of the development milestone code-named Nougat. The source code for the following tests can be synced with the -'android-cts-7.0_r13' tag in the open-source tree.</p> +'android-cts-7.0_r14' tag in the open-source tree.</p> <ul> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-7.0_r13-linux_x86-arm.zip">Android -7.0 R13 Compatibility Test Suite (CTS) - ARM</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-7.0_r14-linux_x86-arm.zip">Android +7.0 R14 Compatibility Test Suite (CTS) - ARM</a></li> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-7.0_r13-linux_x86-x86.zip">Android -7.0 R13 Compatibility Test Suite (CTS) - x86</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-7.0_r14-linux_x86-x86.zip">Android +7.0 R14 Compatibility Test Suite (CTS) - x86</a></li> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-verifier-7.0_r13-linux_x86-arm.zip">Android -7.0 R13 CTS Verifier - ARM</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-verifier-7.0_r14-linux_x86-arm.zip">Android +7.0 R14 CTS Verifier - ARM</a></li> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-verifier-7.0_r13-linux_x86-x86.zip">Android -7.0 R13 CTS Verifier - x86</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-verifier-7.0_r14-linux_x86-x86.zip">Android +7.0 R14 CTS Verifier - x86</a></li> </ul> <h2 id="android-60">Android 6.0</h2> <p>Android 6.0 is the release of the development milestone code-named Marshmallow. The source code for the following tests can be synced with the -'android-cts-6.0_r22' tag in the open-source tree.</p> +'android-cts-6.0_r23' tag in the open-source tree.</p> <ul> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-6.0_r22-linux_x86-arm.zip">Android -6.0 R22 Compatibility Test Suite (CTS) - ARM</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-6.0_r23-linux_x86-arm.zip">Android +6.0 R23 Compatibility Test Suite (CTS) - ARM</a></li> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-6.0_r22-linux_x86-x86.zip">Android -6.0 R22 Compatibility Test Suite (CTS) - x86</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-6.0_r23-linux_x86-x86.zip">Android +6.0 R23 Compatibility Test Suite (CTS) - x86</a></li> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-verifier-6.0_r22-linux_x86-arm.zip">Android -6.0 R22 CTS Verifier - ARM</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-verifier-6.0_r23-linux_x86-arm.zip">Android +6.0 R23 CTS Verifier - ARM</a></li> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-verifier-6.0_r22-linux_x86-x86.zip">Android -6.0 R22 CTS Verifier - x86</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-verifier-6.0_r23-linux_x86-x86.zip">Android +6.0 R23 CTS Verifier - x86</a></li> </ul> <h2 id="android-51">Android 5.1</h2> <p>Android 5.1 is the release of the development milestone code-named Lollipop-MR1. The source code for the following tests can be synced with the -'android-cts-5.1_r23' tag in the open source tree.</p> +'android-cts-5.1_r24' tag in the open source tree.</p> <ul> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-5.1_r23-linux_x86-arm.zip">Android -5.1 R23 Compatibility Test Suite (CTS) - ARM</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-5.1_r24-linux_x86-arm.zip">Android +5.1 R24 Compatibility Test Suite (CTS) - ARM</a></li> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-5.1_r23-linux_x86-x86.zip">Android -5.1 R23 Compatibility Test Suite (CTS) - x86</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-5.1_r24-linux_x86-x86.zip">Android +5.1 R24 Compatibility Test Suite (CTS) - x86</a></li> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-verifier-5.1_r23-linux_x86-arm.zip">Android -5.1 R23 CTS Verifier - ARM</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-verifier-5.1_r24-linux_x86-arm.zip">Android +5.1 R24 CTS Verifier - ARM</a></li> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-verifier-5.1_r23-linux_x86-x86.zip">Android -5.1 R23 CTS Verifier - x86</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-verifier-5.1_r24-linux_x86-x86.zip">Android +5.1 R24 CTS Verifier - x86</a></li> </ul> <h2 id="android-50">Android 5.0</h2> diff --git a/en/compatibility/cts/setup.html b/en/compatibility/cts/setup.html index 9069b8b3..16cc43a0 100644 --- a/en/compatibility/cts/setup.html +++ b/en/compatibility/cts/setup.html @@ -208,7 +208,7 @@ one with at least speed class 10 or higher to ensure it can pass the CTS.</em> <h3 id=developer_uicc>Developer UICC</h3> -<p>In order to run CTS carrier API tests, the device needs to has a SIM card +<p>In order to run CTS carrier API tests, the device needs to have a SIM card with carrier privilege rules on it. See <a href="/devices/tech/config/uicc.html#prepare_uicc">Preparing the UICC</a>.</p> diff --git a/en/devices/_toc-tech.yaml b/en/devices/_toc-tech.yaml index 76f2621e..22d8fa9a 100644 --- a/en/devices/_toc-tech.yaml +++ b/en/devices/_toc-tech.yaml @@ -103,6 +103,8 @@ toc: path: /devices/tech/debug/asan - title: LLVM Sanitizers path: /devices/tech/debug/sanitizers + - title: Build kernel with KASAN+KCOV + path: /devices/tech/debug/kasan-kcov - title: Using GDB path: /devices/tech/debug/gdb - title: Native Memory Use diff --git a/en/devices/architecture/hidl/versioning.html b/en/devices/architecture/hidl/versioning.html index aed6f9fe..20ea34b4 100644 --- a/en/devices/architecture/hidl/versioning.html +++ b/en/devices/architecture/hidl/versioning.html @@ -499,7 +499,7 @@ AND </li> <li>"Inherit at least one interface with the same name": There exists an interface <code>package@major.minor::IFoo</code> that extends -<code>package@major.(minor-1)::IFoo</code>; +<code>package@major.(minor-1)::IFoo</code> (if the previous package has an interface); <br><br> AND <br><br> diff --git a/en/devices/bluetooth/hci_requirements.html b/en/devices/bluetooth/hci_requirements.html index 217850dc..43ffefbd 100644 --- a/en/devices/bluetooth/hci_requirements.html +++ b/en/devices/bluetooth/hci_requirements.html @@ -1,6 +1,11 @@ -<html devsite> <head> <title>HCI Requirements</title> <meta name="project_path" - value="/_project.yaml" /> <meta name="book_path" value="/_book.yaml" /> - </head> <body> +<html devsite> + <head> + <title>HCI Requirements</title> + <meta name="project_path" value="/_project.yaml" /> + <meta name="book_path" value="/_book.yaml" /> + </head> + + <body> <!-- Copyright 2017 The Android Open Source Project @@ -21,55 +26,62 @@ Bluetooth controller.</p> <p>This document provides a list of Bluetooth (BT) and Bluetooth Low - Energy (BLE) requirements. The aim is for Host BT stack vendors and BT - controller vendors to conform to these platform requirements in order to - use the feature set described below</p> - - <p>The Bluetooth Core 4.1 Specification, referred to in this document as - the "BT 4.1 core specification," is available on the <a - href="https://www.bluetooth.org/en-us/specification/adopted-specifications">Bluetooth - SIG website</a> along with other adopted documents.</p> + Energy (BLE) HCI requirements. The aim is for Host BT stack vendors and + BT controller vendors to conform to these platform requirements in order + to use the feature set described below.</p> + + <p>This document refers to the Bluetooth Core 4.1 Specification as the + "spec." The Bluetooth Core 4.1 Specification is available on the + <a href="https://www.bluetooth.org/en-us/specification/adopted-specifications"> + Bluetooth SIG website</a> along with other adopted documents.</p> + <h2 id="general-design-overview">General design overview</h2> + <h3 id="chip-capabilities-and-configuration">Chip capabilities and configuration</h3> - <p>Android, as an open platform, has a matrix of software + + <p>As an open platform, Android has a matrix of software releases, OEMs, vendors, and platform and chip capabilities.</p> <p>To manage the varying landscape and to manage migrations, a design philosophy of allowing BT controllers to expose their capabilities - (beyond the standard BT 4.1 core specification) is described in this - document. The host BT stack can then use these capabilities to - determine which features to enable.</p> + (beyond the standard Bluetooth Core 4.1 Specification) is described + in this document. The host BT stack can then use these capabilities + to determine which features to enable.</p> <h3 id="supporting-open-standards">Supporting open standards</h3> <p> One goal of Android is to support open standards after ratification in a Bluetooth specification. If a feature described below becomes available in standard HCI methods in a future Bluetooth specification, we will lean towards making that approach the default.</p> + <h2 id="vendor-specific-capabilities">Vendor-specific capabilities</h2> <p>Vendor-specific command: <code>LE_Get_Vendor_Capabilities_Command</code></p> - <p>OCF (OpCode Command Field): 0x153</p> + <p>OpCode Command Field (OCF): 0x153</p> <table> <tr> - <th>Command Parameter</th> + <th>Command parameter</th> <th>Size</th> <th>Purpose</th> </tr> <tr> <td></td> <td>NA</td> - <td>Empty command parameter list</td> + <td>Empty Command parameter list</td> </tr> </table> + <p> A Command Complete event will be generated for this command.</p> + <table> <tr> - <th>Return Parameter</th> - <th>Size</th> <th>Purpose</th> + <th>Return parameter</th> + <th>Size</th> + <th>Purpose</th> </tr> <tr> <td><code>Status</code></td> @@ -84,8 +96,8 @@ <tr> <td><code>offloaded_resolution_of_private-address</code></td> <td>1 octet</td> - <td>BT chip capability of RPA; if supported by a chip, - it needs enablement by the host.<br/> + <td>BT chip capability of RPA.<br/> + If supported by a chip, it needs enablement by the host.<br/> 0 = Not capable<br/> 1 = Capable</td> </tr> @@ -102,7 +114,7 @@ <tr> <td><code>filtering_support</code></td> <td>1 octet</td> - <td>Support for filtering in the controller.<br/> + <td>Support for filtering in the controller<br/> 0 = Not supported<br/> 1 = Supported</td> </tr> @@ -114,7 +126,7 @@ <tr> <td><code>activity_energy_info_support</code></td> <td>1 octet</td> - <td>Supports reporting of activity and energy information.<br/> + <td>Supports reporting of activity and energy information<br/> 0 = Not capable<br/> 1 = Capable</td> </tr> @@ -122,9 +134,9 @@ <td><code>version_supported</code></td> <td>2 octets<br/> [0x00, 0x60]</td> - <td>Specifies the version of the Google feature spec supported.<br/> - byte[0] = major number<br/> - byte[1] = minor number</td> + <td>Specifies the version of the Google feature spec supported<br/> + byte[0] = Major number<br/> + byte[1] = Minor number</td> </tr> <tr> <td><code>total_num_of_advt_tracked</code></td> @@ -146,14 +158,14 @@ <td><code>LE_address_generation_offloading_support</code></td> <td>1 octet</td> <td>0 = Not supported<br/> - 1 = supported</td> + 1 = Supported</td> </tr> </table> <p>The <code>max_advt_instances parameter</code> represents the total advertisement instances in the controller. The range of <code>advt_instance</code> IDs will be 0 to - <code>max_advt_instances-1</code>.</p> + <code>max_advt_instances</code> minus 1.</p> <p>An advertisement instance with an ID equal to 0 will map to an existing (default/standard) HCI instance. When operating on a @@ -161,6 +173,7 @@ used.</p> <h2 id="multi-advertiser-support">Multi-advertiser support</h2> + <p>The objectives of multi-advertiser support are the following:</p> <ul> @@ -182,7 +195,7 @@ <table> <tr> - <th>Command Parameter</th> + <th>Command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -201,7 +214,7 @@ <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -222,17 +235,18 @@ </table> <h4 - id="le_multi_advt_command-set_advt_param_multi_sub_cmd">LE_Multi_Advt_Command: - Set_Advt_Param_Multi_Sub_Cmd</h4> - <p>Base reference (referred to below as "spec"): - The BT 4.1 core specification, page 964 (LE Set Advertising + id="le_multi_advt_command-set_advt_param_multi_sub_cmd"> + LE_Multi_Advt_Command: Set_Advt_Param_Multi_Sub_Cmd</h4> + + <p>Base reference: + Bluetooth Core 4.1 Specification, page 964 (LE Set Advertising Parameter Command)</p> <p>Sub OCF: 0x01</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -312,7 +326,7 @@ <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -332,14 +346,14 @@ id="le_multi_advt_command-set_advt_data_multi_sub_cmd">LE_Multi_Advt_Command: Set_Advt_Data_Multi_Sub_Cmd</h4> - <p>Base reference: The BT 4.1 core specification, page 969 (LE Set - Advertising Data Command)</p> + <p>Base reference: Bluetooth Core 4.1 Specification, page 969 + (LE Set Advertising Data Command)</p> <p>Sub OCF: 0x02</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -369,7 +383,7 @@ <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -388,14 +402,15 @@ <h4 id="le_multi_advt_command-set_scan_resp_data_multi_sub_cmd">LE_Multi_Advt_Command: Set_Scan_Resp_Data_Multi_Sub_Cmd</h4> - <p>Base reference: The BT 4.1 core specification, page 970 + + <p>Base reference: Bluetooth Core 4.1 Specification, page 970 (LE Set Scan Response Data Command)</p> <p>Sub OCF: 0x03</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -425,7 +440,7 @@ <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -444,19 +459,19 @@ <h4 id="le_multi_advt_command-set_random_addr_multi_sub_cmd">LE_Multi_Advt_Command: Set_Random_Addr_Multi_Sub_Cmd</h4> - <p>Base reference: The BT 4.1 core specification, page 963 (LE Set - Random Address Command)</p> + <p>Base reference: Bluetooth Core 4.1 Specification, page 963 + (LE Set Random Address Command)</p> <p>Sub OCF: 0x04</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> <tr> - <td>Random Address</td> + <td><code>Random Address</code></td> <td>Per spec</td> <td>Per spec</td> </tr> @@ -472,7 +487,7 @@ <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -491,14 +506,14 @@ <h4 id="le_multi_advt_command-set_advt_enable_multi_sub_cmd">LE_Multi_Advt_Command: Set_Advt_Enable_Multi_Sub_Cmd</h4> - <p>Base reference: The BT 4.1 core specification, page 971 (LE Set - Advertise Enable Command in that core specification)</p> + <p>Base reference: Bluetooth Core 4.1 Specification, page 971 + (LE Set Advertise Enable Command in that core specification)</p> <p>OCF: 0x05</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -520,7 +535,7 @@ <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -538,8 +553,8 @@ <h2 id="offloaded-resolution-of-private-address">Offloaded resolution of private address</h2> - <p> This feature allows the resolution of a private address in the - controller firmware or hardware, which provides the following benefits: + <p> This feature resolves a private address in the controller firmware + or hardware, which provides the following benefits: </p> <ul> @@ -553,7 +568,7 @@ <table> <tr> - <th>Command Parameter</th> + <th>Command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -585,7 +600,7 @@ <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -597,8 +612,8 @@ Suggested HCI status values:<br/> 0x00 Success<br/> 0x01 Unknown command (if not supported)<br/> - 0x12 Invalid command parameters (if any - parameters are outside the given range)</td> + 0x12 Invalid command parameters (if any parameters are outside + the given range)</td> </tr> </table> @@ -607,7 +622,7 @@ <table> <tr> - <th>Command Parameter</th> + <th>Command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -626,7 +641,7 @@ <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -653,7 +668,7 @@ <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -667,15 +682,15 @@ <p>RPA offload is required to be enabled by the host, based on the chip capability. Refer to the - <code>LE_Get_Vendor_Capabilities_Command.</code> Each chip can have - a varying <code>max_irk_list_sz </code>in the firmware. </p> + <code>LE_Get_Vendor_Capabilities_Command</code>. Each chip can have + a varying <code>max_irk_list_sz</code> in the firmware.</p> <p>A Command Complete event will be generated for this command. </p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -696,7 +711,7 @@ <p>Sub OCF: 0x02</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -723,7 +738,7 @@ <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -750,7 +765,7 @@ <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -763,8 +778,7 @@ <tr> <td><code>LE_Device_Address</code></td> <td>6 octets</td> - <td>Public or random address that associates to - the IRK</td> + <td>Public or random address that associates to the IRK</td> </tr> </table> @@ -772,7 +786,7 @@ <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -798,7 +812,7 @@ <p>Sub OCF: 0x04</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -813,7 +827,7 @@ <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -841,7 +855,7 @@ <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -857,7 +871,7 @@ <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -933,7 +947,7 @@ <table> <tr> - <th>Command Parameter</th> + <th>Command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -952,7 +966,7 @@ <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -972,12 +986,12 @@ </table> <h4 - id="le_batch_scan_command-enable-customer-specific-feature">LE_Batch_Scan_Command: - Enable Customer Specific feature</h4> + id="le_batch_scan_command-enable-customer-specific-feature"> + LE_Batch_Scan_Command: Enable Customer Specific feature</h4> <p>Sub OCF: 0x01</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -992,7 +1006,7 @@ <p>A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1012,32 +1026,32 @@ </table> <h4 - id="le_batch_scan_command-set-batch-scan-storage-param-subcommand">LE_Batch_Scan_Command: - Set Batch Scan Storage Param subcommand</h4> + id="le_batch_scan_command-set-batch-scan-storage-param-subcommand"> + LE_Batch_Scan_Command: Set Batch Scan Storage Param subcommand</h4> <p>Sub OCF: 0x02</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> <tr> <td><code>Batch_Scan_Full_Max</code></td> <td>1 octet</td> - <td>Max storage space (in %) allocated to full style [Range: - 0-100]</td> + <td>Max storage space (in %) allocated to full style<br/> + [Range: 0-100]</td> </tr> <tr> <td><code>Batch_Scan_Truncated_Max</code></td> <td>1 octet</td> - <td>Max storage space (in %) allocated to truncated style [Range: - 0-100]</td> + <td>Max storage space (in %) allocated to truncated style<br/> + [Range: 0-100]</td> </tr> <tr> <td><code>Batch_Scan_Notify_Threshold</code></td> <td>1 octet</td> <td>Setup notification level (in %) for individual storage pool - [Range: 0-100].<br/> + <br/>[Range: 0-100]<br/> Setting to 0 will disable notification. Vendor-specific HCI event is generated (Storage threshold breach subevent)</td> @@ -1047,7 +1061,7 @@ <p>A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1064,12 +1078,12 @@ </table> <h4 - id="le_batch_scan_command-set-batch-scan-param-subcommand">LE_Batch_Scan_Command: - Set Batch Scan Param subcommand</h4> + id="le_batch_scan_command-set-batch-scan-param-subcommand"> + LE_Batch_Scan_Command: Set Batch Scan Param subcommand</h4> <p>Sub OCF: 0x03</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1110,24 +1124,25 @@ unique key for Truncated style = {<code>BD_ADDR,</code> scan_interval}. This means only one <code>BD_ADDR will</code> be recorded for each scan interval. The record to keep for Truncated - mode is the following: {<code>BD_ADDR,</code> Tx Power, RSSI, + mode is the following: {<code>BD_ADDR</code>, Tx Power, RSSI, Timestamp} </p> <p> When Full mode is enabled, active scanning will be used and Scan Responses will be recorded. The Full style unique key = {MAC, Ad packet}, irrespective of scan interval. The record to keep for Full - mode is {<code>BD_ADDR,</code> Tx Power, RSSI, Timestamp, Ad packet, - Scan Response}. In Full style, the same AD packet, when seen - multiple times across different scan intervals, is recorded only - once. However, in Truncated mode, it is the visibility of - <code>BA_ADDR </code>across different scan intervals that is of - interest (once per scan interval). The RSSI is the averaged value of - all duplicates of a unique advertisement within a scan interval.</p> + mode is {<code>BD_ADDR</code>, Tx Power, RSSI, Timestamp, Ad + packet, Scan Response}. In Full style, the same AD packet, when + seen multiple times across different scan intervals, is recorded + only once. However, in Truncated mode, it is the visibility of + <code>BA_ADDR</code> across different scan intervals that is of + interest (once per scan interval). The RSSI is the averaged value + of all duplicates of a unique advertisement within a scan interval. + </p> <p>A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1148,7 +1163,7 @@ <p>Sub OCF: 0x04</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1159,28 +1174,30 @@ 0x02 – Full mode data</td> </tr> </table> + <p>A Command Complete event will be generated for this command. - When the host issues this command, all the results in the controller - may not fit in one Command Complete event. The host will iterate - issuing this command until the corresponding results in the Command - Complete event indicate 0 in the number of records, which indicates - the controller has no more records to communicate to the host. Each - Command Complete event could contain multiple records of only one - type of data (Full or Truncated).</p> - - <p>Controller and host time references are not synchronized. Thus - the timestamp needs special explanation. The unit of the timestamp - is 50ms. The value of the timestamp is based off when the - <code>Read_Batch_Scan_Results_Sub_cmd </code>is given by the host. - If a command arrival time is <code>T_c</code> in the firmware, then - the actual time the timestamp was taken in the firmware is - <code>T_fw.</code> The reporting time will be: (<code>T_c</code> - - <code>T_fw)</code>. <code>T_c</code> and <code>T_fw </code>are in - the firmware time domain. This lets the host compute how long ago - the event happened.</p> + When the host issues this command, all the results in the + controller may not fit in one Command Complete event. The host + will iterate issuing this command until the corresponding results + in the Command Complete event indicate 0 in the number of records, + which indicates the controller has no more records to communicate + to the host. Each Command Complete event could contain multiple + records of only one type of data (Full or Truncated).</p> + + <p>Controller and host time references are not synchronized. The + unit of the timestamp is 50ms. The value of the timestamp is + based off when the <code>Read_Batch_Scan_Results_Sub_cmd</code> + is given by the host. If a command arrival time is + <code>T_c</code> in the firmware, then the actual time the + timestamp was taken in the firmware is <code>T_fw</code>. The + reporting time will be: (<code>T_c</code> - <code>T_fw</code>). + <code>T_c</code> and <code>T_fw </code>are in the firmware time + domain. This lets the host compute how long ago the event + happened.</p> + <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1214,7 +1231,7 @@ Tx_Pwr[0]: 1 octet<br/> RSSI[0] : 1 octet<br/> Timestamp[0]: 2 octets<br/> - [multiple records (<code>num_of_records)</code> + [multiple records (<code>num_of_records</code>) with above format]<br/> <br/> <span style="text-decoration:underline;">Full @@ -1229,9 +1246,10 @@ Scan_data_resp_len[0]: 1 octet<br/> Scan_data_resp[0]: <code>Scan_data_resp </code>octets<br/> [multiple records with above format - (<code>num_of_records)]</code></td> + (<code>num_of_records</code>)]</td> </tr> </table> + <h2 id="advertising-packet-content-filter">Advertising Packet Content Filter</h2> <p>Use this to enable/disable/setup the @@ -1241,7 +1259,7 @@ <p>OCF: 0x157</p> <table> <tr> - <th>Command Parameter</th> + <th>Command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1261,7 +1279,7 @@ <p>A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1289,7 +1307,7 @@ <p>Sub OCF: 0x00</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1303,7 +1321,7 @@ <p>A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1323,15 +1341,16 @@ <td>Enable/disable is set via <code>APCF_enable</code></td> </tr> </table> + <h4 - id="le_apcf_command-set_filtering_parameters_sub_cmd">LE_APCF_Command: - set_filtering_parameters_sub_cmd</h4> + id="le_apcf_command-set_filtering_parameters_sub_cmd"> + LE_APCF_Command: set_filtering_parameters_sub_cmd</h4> <p>This subcommand is used to add or delete a filter specification or clear a filter list for on-chip filtering.</p> <p>Sub OCF: 0x01</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1347,8 +1366,8 @@ </tr> <tr> <td><code>APCF_Filter_Index</code></td> - <td>1 octet</td> <td>Filter index (0, - <code>max_filter-1)</code></td> + <td>1 octet</td> + <td>Filter index (0, <code>max_filter-1</code>)</td> </tr> <tr> <td><code>APCF_Feature_Selection</code></td> @@ -1365,9 +1384,9 @@ <tr> <td><code>APCF_List_Logic_Type</code></td> <td>2 octets</td> - <td>Logic operation for each feature selection - (per bit position) specified in - <code>APCF_Feature_Selection.</code><br/> + <td>Logic operation for each feature selection (per-bit + position) specified in <code>APCF_Feature_Selection</code>. + <br/> Valid only when a feature is enabled.<br/> Bit position value:<br/> 0: OR<br/> @@ -1384,14 +1403,15 @@ <td>0x00: OR<br/> 0x01: AND<br/> Note: The logic type is N/A for the first three fields - of <code>APCF_Feature_Selection,</code> which is always "AND" - logic. They are only applicable for (Bit 3 Bit 6) - four fields of <code>APCF_Feature_Selection.</code></td> + of <code>APCF_Feature_Selection</code>, which is always "AND" + logic. They are only applicable for (Bit 3 - Bit 6) + four fields of <code>APCF_Feature_Selection</code>.</td> </tr> <tr> <td><code>rssi_high_thresh</code></td> <td>1 octet</td> - <td>[In dBm] the advertiser is considered seen only if the + <td>[in dBm]<br/> + The advertiser is considered seen only if the signal is higher than the RSSI high threshold. Otherwise, the firmware must behave as if it never saw it.</td> </tr> @@ -1405,8 +1425,8 @@ <tr> <td><code>onfound_timeout</code></td> <td>2 octets</td> - <td>Valid only if <code>delivery_mode </code>is - <code>on_found</code><br/> + <td>Valid only if <code>delivery_mode</code> is + <code>on_found</code>.<br/> [in milliseconds]<br/> Time for firmware to linger and collect additional advertisements before reporting.</td> @@ -1415,19 +1435,20 @@ <td><code>onfound_timeout_cnt</code></td> <td>1 octet</td> <td>Valid only if <code>delivery_mode</code> is - <code>on_found</code><br/> + <code>on_found</code>.<br/> [count]<br/> If an advertisement in <code>onFound</code> lingers in - firmware for the <code>onfound_timeout </code>duration, + firmware for the <code>onfound_timeout</code> duration, it will collect a few advertisements and the count is checked. If the count exceeds <code>onfound_timeout_cnt</code>, - it's reported <code>OnFound</code>, + it's reported <code>OnFound</code> immediately thereafter.</td> </tr> <tr> <td><code>rssi_low_thresh</code></td> <td>1 octet</td> <td>Valid only if <code>delivery_mode</code> - is <code>on_found</code> [in dBm].<br/> + is <code>on_found</code>.<br/> + [in dBm]<br/> The advertiser packet is considered as not seen if the RSSI of the received packet is not above the RSSI low threshold.</td> @@ -1436,17 +1457,18 @@ <td><code>onlost_timeout</code></td> <td>2 octets</td> <td>Valid only if <code>delivery_mode</code> is - <code>on_found</code><br/> + <code>on_found</code>.<br/> [in milliseconds]<br/> If an advertisement, after being found, is not seen - contiguously for the <code>lost_timeout </code>period, - it will be reported lost. Reporting of lost is immediate.</td> + contiguously for the <code>lost_timeout</code> period, + it will immediately be reported lost.</td> </tr> <tr> <td><code>num_of_tracking_entries</code></td> <td>2 octets</td> <td>Valid only if <code>delivery_mode</code> is - <code>on_found</code><br/> [count]<br/> + <code>on_found</code>.<br/> + [count]<br/> Total number of advertisers to track per filter.</td> </tr> </table> @@ -1454,55 +1476,60 @@ <p> RSSI values must use 2's complement to represent negative values. </p> - <p> Host shall be able to configure multiple filters with + <p>Host shall be able to configure multiple filters with <code>APCF_Application_Address_type</code> set to 0x02 (for all broadcaster addresses) to manage various filter combinations. </p> <p> Filtering, batching and reporting are inter-related concepts. Every advertisement and related scan response will have to go through all the filters, one after the other. Thus, resulting - actions (<code>delivery_mode)</code> are closely tied to filtering. + actions (<code>delivery_mode</code>) are closely tied to filtering. The delivery modes are the following: - <code>report_immediately,</code> <code>batch</code>, and - <code>onFound.</code> The <code>OnLost</code> value is related to + <code>report_immediately</code>, <code>batch</code>, and + <code>onFound</code>. The <code>OnLost</code> value is related to <code>OnFound</code> in the sense that it will come after - <code>OnFound</code> when lost. </p> + <code>OnFound</code> when lost.</p> - <p> The following processing flow depicts the conceptual model. - </p> + <p> This processing flow depicts the conceptual model:</p> <img src="images/bt_filter_batch_report.png"> <p> When an advertisement (or scan response) frame is received, it - is applied to all the filters in serial order. It's possible that an - advertisement can cause immediate reporting based on one filter and - batching of the same due to a different filter action. </p> - - <p> RSSI level thresholds (high and low) give the ability to control - when the frame is visible for filter processing, even when a valid - packet is received by the controller. In case of delivery mode being - set to immediate or batched, the RSSI of an considered for further - controller processing. Different apps need different reporting and - batching behavior. This allows multiple apps to have direct - reporting and/or batching of results in firmware, concurrently. An - example is a case when a batch scan is active from one app and later - a regular LE scan is issued by another app. Before a batch scan is - issued, the framework/app sets appropriate filters. Later, when the - second app issues a regular scan, previous batching continues. - However, due to the regular scan, it is akin to conceptually adding - a null filter (along with all the existing filters) along with the - LE scan command. The LE scan command parameters take precedence when - active. When the regular LE scan is disabled, the controller will - revert back to a previous batch scan, if it existed. </p> + is applied to all the filters in serial order. It's possible that + an advertisement can cause immediate reporting based on one filter + and batching of the same due to a different filter action.</p> + + <p> RSSI level thresholds (high and low) give the ability to + control when the frame is visible for filter processing, even + when a valid packet is received by the controller. In case of + delivery mode being set to immediate or batched, the RSSI of a + frame is considered for further controller processing. Different + apps need different reporting and batching behavior. This allows + multiple apps to have direct reporting and/or batching of + results in firmware, concurrently. An example is a case when a + batch scan is active from one app and later a regular LE scan is + issued by another app. Before a batch scan is issued, the + framework/app sets appropriate filters. Later, when the second + app issues a regular scan, previous batching continues. However, + due to the regular scan, it is akin to conceptually adding a + null filter (along with all the existing filters) along with the + LE scan command. The LE scan command parameters take precedence + when active. When the regular LE scan is disabled, the controller + will revert back to a previous batch scan, if it existed.</p> + <p> The <code>OnFound</code> delivery mode is based on configured - filters. A combination that triggers a filter's action to succeed is - considered the entity to track for <code>onLost</code>. The - corresponding event is the LE Advt tracking subevent. </p> + filters. A combination that triggers a filter's action to succeed + is considered the entity to track for <code>onLost</code>. The + corresponding event is the LE Advt tracking subevent.</p> + <p> The <code>OnFound/OnLost</code> transition for a filter (if enabled) will look like the following: </p> <img src="images/bt_onfound_onlost.png"> - <p> A Command Complete event will be generated for this command.</p> + + <p> + A Command Complete event will be generated for this command.</p> + <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1530,12 +1557,14 @@ <h4 id="le_apcf_command-broadcast_address_sub_cmd">LE_APCF_Command: broadcast_address_sub_cmd</h4> + <p>This subcommand is used to add or delete an advertiser address or to clear the advertiser address list for on-chip filtering.</p> + <p>Sub OCF: 0x02</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1553,7 +1582,7 @@ <tr> <td><code>APCF_Filter_Index</code></td> <td>1 octet</td> - <td>Filter index (0, <code>max_filter-1)</code></td> + <td>Filter index (0, <code>max_filter-1</code>)</td> </tr> <tr> <td><code>APCF_Broadcaster_Address</code></td> @@ -1573,7 +1602,7 @@ <p>A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1607,7 +1636,7 @@ <p>Sub OCF: 0x03</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1645,7 +1674,7 @@ <p> A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1679,7 +1708,7 @@ <p>Sub OCF: 0x04</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1710,13 +1739,13 @@ <td>2,4,16 octet</td> <td>The Solicitation UUID Mask (16-bit, 32-bit, or 128-bit) to add to the list. It should have the same - length as the <code>APCF_UUID.</code></td> + length as the <code>APCF_UUID</code>.</td> </tr> </table> <p>A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1745,12 +1774,12 @@ <h4 id="le_apcf_command-local_name_sub_cmd">LE_APCF_Command: local_name_sub_cmd</h4> - <p>This subcommand is used to add or delete a local name string or + <p>This sub-command is used to add or delete a local name string or to clear the local name string list for on-chip filtering.</p> <p>Sub OCF: 0x05</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1776,15 +1805,18 @@ <td>A character string for local name.<br/> <br/> Notes:<br/> - i) Currently the max number of characters in a local name - string is 29<br/> - ii) Not applicable when action is "Clear" (0x2)</td> + <ul> + <li>Currently the max number of characters in a local name + string is 29</li> + <li>Not applicable when action is "Clear" (0x2)</li> + </ul> + </td> </tr> </table> <p>A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1807,7 +1839,7 @@ <td><code>APCF_AvailableSpaces</code></td> <td>1 octet</td> <td>Number of free entries still available in the Local name - table.</td> + table</td> </tr> </table> @@ -1819,7 +1851,7 @@ <p>Sub OCF: 0x06</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1845,9 +1877,12 @@ <td>A character string for manufacturer data.<br/> <br/> Notes:<br/> - i) Currently the max number of characters in a local name - string is 29<br/> - ii) Not applicable when action is "Clear" (0x2)</td> + <ul> + <li>Currently the max number of characters in a local name + string is 29</li> + <li>Not applicable when action is "Clear" (0x2)</li> + </ul> + </td> </tr> <tr> <td><code>APCF_ManData_Mask</code></td> @@ -1861,7 +1896,7 @@ <p>A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1876,14 +1911,15 @@ <td>0x06 - APCF Manufacturer Data</td> </tr> <tr> - <td><code>APCF_Action</code></td> <td>1 octet</td> + <td><code>APCF_Action</code></td> + <td>1 octet</td> <td>Echo back command's <code>APCF_Action</code></td> </tr> <tr> <td><code>APCF_AvailableSpaces</code></td> <td>1 octet</td> <td>Number of free entries still available in the Manufacturer - Data table.</td> + Data table</td> </tr> </table> @@ -1894,7 +1930,7 @@ <p>Sub OCF: 0x07</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1920,9 +1956,12 @@ <td>A character string for service data.<br/> <br/> Notes:<br/> - i) Currently the max number of characters in a local name - string is 29<br/> - ii) Not applicable when action is "Clear" (0x2)</td> + <ul> + <li>Currently the max number of characters in a local name + string is 29</li> + <li>Not applicable when action is "Clear" (0x2)</li> + </ul> + </td> </tr> <tr> <td><code>APCF_LocName_Mandata_or_SerData_Mask</code></td> @@ -1935,7 +1974,7 @@ <p>A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1958,17 +1997,17 @@ <td><code>APCF_AvailableSpaces</code></td> <td>1 octet</td> <td>Number of free entries still available for Service Data - table.</td> + table</td> </tr> </table> <h2 id="controller-activity-and-energy-information-command">Controller activity and energy information command</h2> <p>The objective of this information is for higher host system - functions to analyzethe total activities of all components, including - the BT controller and itsmacro state, in conjunction with what is - happening in the apps and framework. Todo this, the following - information is required from the BT stack and thecontroller: </p> + functions to analyze the total activities of all components, including + the BT controller and its macro state, in conjunction with what is + happening in the apps and framework. To do this, the following + information is required from the BT stack and the controller: </p> <ul> <li>BT stack: Reporting the current macro-operational state of the controller</li> @@ -1982,14 +2021,16 @@ <li>Active: [ACL link on, SCO link ongoing, sniff mode]</li> </ul> <p>The activities that the controller keeps track of over its life are - Tx time, Rx time, idle time, and total energy consumed. They are cleared - when read from the host.</p> - <p>Vendor-specific command: - <code>LE_Get_Controller_Activity_Energy_Info</code> </p> + Tx time, Rx time, idle time, and total energy consumed. They are + cleared when read from the host.</p> + + <h3 id="le_get_controller_activity_energy_info"> + LE_Get_Controller_Activity_Energy_Info</h3> + <p>This is a vendor-specific command.</p>p> <p>OCF: 0x159</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -2002,7 +2043,7 @@ <p>A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -2029,30 +2070,30 @@ <tr> <td><code>total_energy_used</code></td> <td>4 octets</td> - <td>Total energy used [product of current (mA), voltage (V) and time - (ms)]</td> + <td>Total energy used [product of current (mA), voltage (V) and + time (ms)]</td> </tr> </table> <h2 id="le-extended-set-scan-parameters-command">LE extended set scan parameters command</h2> <p>This command can be used to enable a larger scan window and interval - in the controller. Per the BT 4.1 core specification, a scan window and + in the controller. Per the BT Core 4.1 Specification, a scan window and interval have an upper bound limit of 10.24 seconds, which hampers applications' longer scan intervals beyond 10.24 seconds.</p> - <p>Base reference: The BT 4.1 core specification, page 973 (LE Set Scan + <p>Base reference: BT Core 4.1 Specification, page 973 (LE Set Scan Parameters Command)</p> <p>OCF: 0x15A</p> <table> <tr> - <th>Cmd Parameter</th> + <th>Command Parameter</th> <th>Size</th> <th>Purpose</th> </tr> <tr> <td><code>LE_Ex_Scan_Type</code></td> <td>1 octet</td> - <td>0x00 - Passive scanning. No <code>SCAN_REQ </code>packets shall + <td>0x00 - Passive scanning. No <code>SCAN_REQ</code> packets shall be sent (default).<br/> 0x01 - Active scanning. <code>SCAN_REQ</code> packets may be sent.</td> @@ -2060,8 +2101,8 @@ <tr> <td><code>LE_Ex_Scan_Interval</code></td> <td>4 octets</td> - <td>Defined as the time interval from when the Controller started its - last LE scan until it begins the subsequent LE scan.<br/> + <td>Defined as the time interval from when the Controller started + its last LE scan until it began the subsequent LE scan.<br/> Range: 0x0004 to 0x00FFFFFF<br/> Default: 0x0010 (10 ms)<br/> Time = N * 0.625 ms<br/> @@ -2071,7 +2112,8 @@ <td><code>LE_Ex_Scan_Window</code></td> <td>4 octets</td> <td>The duration of the LE scan. <code>LE_Scan_Window</code> - shall be less than or equal to <code>LE_Scan_Interval</code>.<br/> + shall be less than or equal to <code>LE_Scan_Interval</code>. + <br/> Range: 0x0004 to 0xFFFF<br/> Default: 0x0010 (10 ms)<br/> Time = N * 0.625 ms<br/> @@ -2090,15 +2132,14 @@ Directed advertising packets which are not addressed for this device shall be ignored.<br/> 0x01 - Ignore advertisement packets from devices not - in the White List Only list.<br/> - Directed advertising packets which are not addressed for this - device shall be ignored.</td> + in the White List Only list. Directed advertising packets which + are not addressed for this device shall be ignored.</td> </tr> </table> <p>A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -2113,16 +2154,16 @@ command</h2> <p>The objective of this information element is to acquire controller debug information by a host, in binary form, for post-processing and - analysis. This helps debug on-field issues and provides engineers with a - toolkit to log information for analysis. A Controller can provide the - information when requested by a host via the event (Controller Debug Info - sub event) or autonomously when desired by the controller. Example uses - could be to report firmware state information, crash dump information, - logging information, etc.</p> + analysis. This helps debug on-field issues and provides engineers with + a toolkit to log information for analysis. A Controller can provide the + information when requested by a host via the event (Controller Debug + Info sub-event) or autonomously when desired by the controller. + Example uses could be to report firmware state information, crash dump + information, logging information, etc.</p> <p>OCF: 0x15B</p> <table> <tr> - <th>Cmd Parameter</th> + <th>Command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -2135,7 +2176,7 @@ <p>A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -2147,9 +2188,9 @@ </table> <h2 id="hci-event-vendor-specific">HCI event (vendor-specific)</h2> <p>Vendor-specific HCI events are required in some cases. Refer to - Figure 5.4 on page 486 of the BT 4.1 core specification. Event - parameter 0 will always contain the first sub-event code, based on which - the rest of the HCI event is decoded.</p> + Figure 5.4 on page 486 of the BT Core 4.1 Specification. Event + parameter 0 will always contain the first sub-event code, based on + which the rest of the HCI event is decoded.</p> <table> <tr> <th>Event Parameter</th> @@ -2170,7 +2211,7 @@ </table> <h3 id="storage-threshold-breach-subevent">Storage threshold breach - subevent</h3> + sub-event</h3> <p>This event indicates that the storage threshold has been breached. </p> <p>Sub-event code = 0x54</p> @@ -2186,8 +2227,8 @@ <td></td> </tr> </table> - <h3 id="le-multi-advertising-state-change-subevent">LE multi-advertising - state change subevent</h3> + <h3 id="le-multi-advertising-state-change-sub-event">LE + multi-advertising state change sub-event</h3> <p>This event indicates that an advertising instance has changed its state. At this time, this event is only used to indicate which @@ -2195,15 +2236,16 @@ <p>Sub-event code = 0x55</p> <table> <tr> - <th>Sub-event Parameter</th> + <th>Sub-event parameter</th> <th>Size</th> <th>Purpose</th> </tr> <tr> <td><code>Advertising_instance</code></td> <td>1 octet</td> - <td>Identifies the specific advertising instance.<br/> - Valid values are 0 through <code>max_advt_instances</code> -1</td> + <td>Identifies the specific advertising instance<br/> + Valid values are 0 through <code>max_advt_instances</code>-1 + </td> </tr> <tr> <td><code>State_Change_Reason</code></td> @@ -2218,20 +2260,20 @@ </tr> </table> - <h3 id="le-advertisement-tracking-subevent">LE advertisement tracking - subevent</h3> + <h3 id="le-advertisement-tracking-sub-event">LE advertisement tracking + sub-event</h3> <p>This event indicates when an advertiser is found or lost.</p> <p>Sub event code = 0x56</p> <table> <tr> - <th>Sub Event Parameter</th> + <th>Sub-event Parameter</th> <th>Size</th> <th>Purpose</th> </tr> <tr> <td><code>APCF_Filter_Index</code></td> <td>1 octet</td> - <td>Filter Index (0, <code>max_filter-1)</code></td> + <td>Filter Index (0, <code>max_filter</code>-1)</td> </tr> <tr> <td><code>Advertiser_State</code></td> @@ -2242,9 +2284,9 @@ <tr> <td><code>Advt_Info_Present</code></td> <td>1 octet</td> - <td>0x00: Advertiser information (<code>Advt_Info)</code> + <td>0x00: Advertiser information (<code>Advt_Info</code>) present<br/> - 0x01: Advertiser information (<code>Advt_Info)</code> not + 0x01: Advertiser information (<code>Advt_Info</code>) not present</td> </tr> <tr> @@ -2269,18 +2311,18 @@ <code>Adv_packet_len</code> octets<br/> <code>Scan_data_resp_len[0]</code>: 1 octet<br/> <code>Scan_data_resp[0]</code>: - <code>Scan_data_resp </code>octets</td> + <code>Scan_data_resp</code> octets</td> </tr> </table> - <h3 id="controller-debug-info-subevent">Controller debug info - subevent</h3> + <h3 id="controller-debug-info-sub-event">Controller debug info + sub-event</h3> <p>This event is used by a Controller to provide binary debug information to a host.</p> - <p>Sub event code = 0x57</p> + <p>Sub-event code = 0x57</p> <table> <tr> - <th>Sub Event Parameter</th> + <th>Sub-event Parameter</th> <th>Size</th> <th>Purpose</th> </tr> diff --git a/en/devices/tech/connect/emergency-affordance.html b/en/devices/tech/connect/emergency-affordance.html index eee981b7..64e0bb82 100644 --- a/en/devices/tech/connect/emergency-affordance.html +++ b/en/devices/tech/connect/emergency-affordance.html @@ -23,23 +23,24 @@ -<p>All mobile devices sold in India from the 1st January 2017 will need to -provide a panic button to meet Indian Department of Telecommunications (DoT) -requirements.</p> - -<p>An Emergency Affordance feature has been developed to provide a reference -implementation of the panic button for Android devices to address these -regulatory requirements. This will be enabled by default in future Android -releases but must be patched into existing builds. Currently, this feature is -exclusively targeted at devices that are sold in the Indian market but can be +<p>All mobile devices sold in India from January 1st, 2017 must provide a +panic button to meet Indian Department of Telecommunications (DoT) requirements. +To address these regulatory requirements, Android includes a reference +implementation of the Emergency Affordance feature to enable a panic button on +Android devices.</p> + +<p>This feature is enabled by default in Android 8.0 and higher releases, but +must be patched into existing builds of earlier releases. Currently, this +feature is exclusively targeted at devices sold in the Indian market but can be included on all devices sold throughout the world as the feature has no effect outside India.</p> -<h2 id="examples-source">Examples and source</h2> <p>The Emergency Affordance -feature is implemented in the Android Open Source Project (AOSP) <a -href="https://android.googlesource.com/platform/frameworks/base/">frameworks/base</a> -project. It is available in the master branch and will be enabled by default in -future Android releases.</p> +<h2 id="examples-source">Examples and source</h2> +<p>The Emergency Affordance feature is implemented in the Android Open Source +Project (AOSP) +<a href="https://android.googlesource.com/platform/frameworks/base/">frameworks/base</a> +project. It is available in the master branch and is enabled by default in +Android 8.0 and higher releases.</p> <p>This feature is currently available in the following branches and commits. This information is provided to enable device manufacturers to easily patch the @@ -48,7 +49,8 @@ implement the AOSP reference emergency affordance feature can cherry-pick the commits from the applicable branches into their own builds.</p> <p class="table-caption" id="cherry-picks-reference-implementation"> - <strong>Table 1.</strong> Cherry-picks for AOSP reference emergency affordance feature</p> +<strong>Table 1.</strong> Cherry-picks for AOSP reference emergency affordance +feature</p> <table> <tbody> <tr> @@ -86,7 +88,7 @@ Fixed an issue where the emergency affordance would show on tablets </td> </tr> <tr> -<td class="style1">lollipop-mr1-dev</td> +<td>lollipop-mr1-dev</td> <td><a href="https://android-review.googlesource.com/#/c/284743/">5fbc86b</a> Added Emergency affordance feature<br> <a href="https://android-review.googlesource.com/#/c/287382/">1b60879</a> @@ -99,32 +101,40 @@ Fixed an issue where the emergency affordance would show on tablets </tbody> </table> -<h2 id="implementation">Implementation</h2> <p>The Emergency Affordance feature -makes no changes to the APIs exposed through the Android SDK. When enabled and -activated, it provides two triggers that can initiate an emergency call to -112, which is the single emergency number to be used in India and mandated by -the DoT regulations.<br> An emergency call is initiated by either:</p> <ul> -<li>Long pressing the <strong>EMERGENCY</strong> button on the lockscreen -(Figure 1)</li> <li>Tapping the <strong>Emergency</strong> option from the -<em>Global Action Menu</em> (Figure 2), accessed by long pressing the power -key.</li> </ul> +<h2 id="implementation">Implementation</h2> +<p>The Emergency Affordance feature makes no changes to the APIs exposed through +the Android Software Development Kit (SDK). When enabled and activated, the +feature provides two triggers that can initiate an emergency call to 112, which +is the single emergency number to be used in India and mandated by the Indian +DoT regulations.</p> +<p>An emergency call is initiated by either:</p> +<div style="width:80%"> <table> - <tr> - <td width="50%"><img src="/devices/tech/connect/images/emergency-button.png" alt="emergency -button" width="246" id="emergency-button" /> -<p class="img-caption"> - <strong>Figure 1.</strong> Long press the <strong>EMERGENCY</strong> button, -highlighted with a red box, on the lock screen.</p></td> - <td width="50%"><img src="/devices/tech/connect/images/emergency-option.png" alt="emergency -option" width="247" id="emergency-option" /> -<p class="img-caption"> - <strong>Figure 2.</strong> Tap the <strong>Emergency</strong> action item on -the <em>Global Action Menu</em>.</p></td> - </tr> +<tr> +<th width="50%">Long pressing the <strong>EMERGENCY</strong> button<br> on the +lockscreen</th> +<th width="50%">Tapping the <strong>Emergency</strong> option<br> in the +Global Action Menu</th> +</tr> +<tr> +<td style="text-align: center"> +<img src="/devices/tech/connect/images/emergency-button.png" alt="emergency +button"> +<figcaption><strong>Figure 1.</strong> <strong>EMERGENCY</strong> button on +lockscreen.</figcaption></td> +<td style="text-align: center"> +<img src="/devices/tech/connect/images/emergency-option.png" alt="emergency +option"> +<figcaption><strong>Figure 2.</strong> <strong>Emergency</strong> action on +Global Action Menu (accessed by long pressing the power key). +</figcaption></td> +</tr> </table> +</div> -<p>This feature introduces the following internal components:</p> <ul> +<p>This feature introduces the following internal components:</p> +<ul> <li>EmergencyAffordanceManager <pre class="devsite-click-to-copy"> frameworks/base/core/java/com/android/internal/policy/EmergencyAffordanceManager.java @@ -137,37 +147,43 @@ frameworks/base/services/core/java/com/android/server/emergency/EmergencyAfforda </li> </ul> -<h3 id="EmergencyAffordanceManager">EmergencyAffordanceManager</h3> <p>The -EmergencyAffordanceManager provides an internal API to use the Emergency +<h3 id="EmergencyAffordanceManager">EmergencyAffordanceManager</h3> +<p>The EmergencyAffordanceManager provides an internal API to use the Emergency Affordance feature. It provides methods for initiating the emergency call and -querying at runtime if the feature should be enabled.</p> <ul> <li><code>void -performEmergencyCall()</code> - Initiates an emergency call</li> -<li><code>boolean needsEmergencyAffordance()</code> - Determines if the feature -should be active</li> </ul> <p>The feature may be permanently disabled at build -time by changing the <code>EmergencyAffordanceManager.ENABLED</code> constant -to <code>false</code>. This will cause <code>needsEmergencyAffordance()</code> -to always return false and prevent the <code>EmergencyAffordanceService</code> -from starting.</p> - -<h3 id="EmergencyAffordanceService">EmergencyAffordanceService</h3> <p>The -<code>EmergencyAffordanceService</code> is a system service that monitors the -Mobile Country Code (MCC) of all the detected cellular networks and the MCC of -the installed SIM cards. If any of the installed SIM cards or detected cellular -networks have a MCC matching one of India's MCCs (404,405) then the feature -will be enabled. This means the feature can be enabled in India even if no SIM -card is present. It is assumed the mobile network will permit registration for -emergency calls even without a SIM card installed. The feature will remain -enabled until a non-India SIM is installed and none of the detected networks -have a matching MCC.</p> +querying at runtime if the feature should be enabled.</p> +<ul> +<li><code>void performEmergencyCall()</code>. Initiates an emergency call.</li> +<li><code>boolean needsEmergencyAffordance()</code>. Determines if the feature +should be active.</li> +</ul> + +<p>The feature may be permanently disabled at build time by changing the +<code>EmergencyAffordanceManager.ENABLED</code> constant to <code>false</code>. +This will cause <code>needsEmergencyAffordance()</code> to always return false +and prevent the <code>EmergencyAffordanceService</code> from starting.</p> + +<h3 id="EmergencyAffordanceService">EmergencyAffordanceService</h3> +<p>The <code>EmergencyAffordanceService</code> is a system service that monitors +the Mobile Country Code (MCC) of all the detected cellular networks and the MCC +of the installed SIM cards. If any of the installed SIM cards or detected +cellular networks have a MCC matching one of India's MCCs (404 or 405) then the +feature will be enabled. This means the feature can be enabled in India even if +no SIM card is present. It is assumed the mobile network will permit +registration for emergency calls even without a SIM card installed. The feature +will remain enabled until a non-India SIM is installed and none of the detected +networks have a matching MCC.</p> <p>The following resources and settings affect the behavior of the Emergency -Affordance feature. If the config type is "Resource" it is an internal resource -defined in <code>frameworks/base/core/res/res/values/config.xml</code>. If -config type is "Setting" it is a setting stored in the systems settings -provider.</p> +Affordance feature. If the config type is:</p> +<ul> +<li><strong>Resource</strong>, it is an internal resource defined in +<code>frameworks/base/core/res/res/values/config.xml</code>.</li> +<li><strong>Setting</strong>, it is a setting stored in the systems settings +provider.</li> +</ul> <p class="table-caption" id="settings-affecting behavior"> - <strong>Table 2.</strong> Settings affecting behavior of emergency affordance +<strong>Table 2.</strong> Settings affecting behavior of emergency affordance feature</p> <table> <tbody> @@ -201,7 +217,7 @@ Type: String<br> Default: unset</td> </tr> <tr> -<td>Setting </td> +<td>Setting</td> <td>force_emergency_affordance</td> <td>Global setting, whether the emergency affordance should be shown regardless of device state. This is intended only for testing.<br> @@ -211,19 +227,25 @@ Default: unset --> 0</td> </tbody> </table> -<h3 id="112">Enable emergency calls to '112'</h3> <p>The emergency affordance -feature connects the call using the emergency dialer so that the call can be -connected when the lock screen is active. The emergency dialer only connects -calls to the list of numbers provided by the Radio Interface Layer (RIL), -through the system property 'ril.ecclist', when no SIM is installed and -'<code>ril.ecclist<<i>SimSlotNumber</i>></code>' when a SIM is inserted -and <code><i><SimSlotNumber></i></code> is the slot ID of the default -subscriber.<br> Device manufacturers using the emergency affordance feature -must ensure that devices in India always enable 112 as an emergency number in -the RIL.</p> - -<h2 id="validation">Validation</h2> <p>While testing, on a debuggable build, -the number that is called can be changed with the following command:</p> +<h3 id="112">Enable emergency calls to 112</h3> +<p>The emergency affordance feature connects the call using the emergency +dialer so that the call can be connected when the lock screen is active. The +emergency dialer connects calls only to the list of numbers provided by the +Radio Interface Layer (RIL) through the system property:</p> + +<ul> +<li><code>ril.ecclist</code> when no SIM is installed.</li> +<li><code>ril.ecclist<var>SimSlotNumber</var></code> when a SIM is inserted +and <code><var>SimSlotNumber</var></code> is the slot ID of the default +subscriber.</li> +</ul> + +<p>Device manufacturers using the emergency affordance feature must ensure that +devices in India always enable 112 as an emergency number in the RIL.</p> + +<h2 id="validation">Validation</h2> +<p>While testing on a debuggable build, the number that is called can be changed +with the following command:</p> <pre class="devsite-terminal devsite-click-to-copy"> adb shell settings put global emergency_affordance_number <var>NUMBER_TO_CALL</var> </pre> @@ -243,43 +265,47 @@ detected or an Indian SIM card being inserted.</p> adb shell settings put global force_emergency_affordance 1 </pre> -<p>During testing it is recommend that at least the following cases are -tested.</p> +<p>At a minimum, it is recommend to test the following cases:</p> -<ul> <li>Once activated, long pressing the <strong>EMERGENCY</strong> button on -the lockscreen (Figure 1) initiates a call the specified emergency number.</li> +<ul> +<li>Once activated, long pressing the <strong>EMERGENCY</strong> button on +the lockscreen (Figure 1) initiates a call to the specified emergency number. +</li> <li>Once activated, the <strong>Emergency</strong> item on the Global Action -Menu is present and that tapping it initiates a call to the specified emergency -number.</li> <li>The feature <b>is not</b> <b>activated</b> in the absence of a +Menu is present and tapping it initiates a call to the specified emergency +number.</li> +<li>The feature <strong>is not activated</strong> in the absence of a detected Indian Mobile Network with a non-India SIM card installed.</li> -<li>The feature <b>is activated</b> on the device whilst an Indian SIM card is -installed, regardless of the detected mobile networks.</li> <li>The feature -<b>is</b> <b>activated</b> on the device whilst an in the presence of a Indian -Mobile Network regardless of the SIM cards installed.</li> </ul> +<li>The feature <strong>is activated</strong> on the device when an Indian SIM +card is installed, regardless of the detected mobile networks.</li> +<li>The feature <strong>is activated</strong> on the device in the presence of +an Indian Mobile Network, regardless of the SIM cards installed.</li> +</ul> -<p>If a device includes supports multiple SIM cards then testing should ensure -that the SIM MCC detection works correctly in each SIM slot. The feature is not -governed by Android compatibility, so there are no CTS tests for it.</p> +<p>If a device includes supports multiple SIM cards, testing should ensure +that the SIM MCC detection works correctly in each SIM slot. The Emergency +Affordance feature is not governed by Android compatibility, so there are no +Compatibility Test Suite (CTS) tests for it.</p> <h2 id="faq">Frequently Asked Questions</h2> -<h5 id="q-112">Q. The emergency number '112' has not been commissioned yet in -India, should it still be used?</h5> - -<p>'112' is the number that will be used in India as the Public Safety -Answering Point (PSAP) as defined by the Integrated Emergency Communications -and Response Systems (IECRS). Until the PSAP is commissioned all calls to '112' -will be routed to the existing '100' emergency number.</p> - -<h5 id="q-other-triggers">Q. What about other triggers like "triple" pressing -the power button?</h5> <p>Device manufacturer may choose to implement -additional triggers. Triple tapping the hardware power button is also an -approved trigger action by the India DoT. However, this trigger is not -supported in the AOSP reference implementation as a number of other widely used -applications use the power button gestures, including repeated tapping of the -power button. These applications might interfere with the emergency dialer, or -the user may accidentally trigger the panic button while trying to trigger -actions in these applications.</p> +<h5 id="q-112">Q. The emergency number 112 has not been commissioned yet in +India. Should it still be used?</h5> +<p>112 is the number that will be used in India as the Public Safety Answering +Point (PSAP) as defined by the Integrated Emergency Communications and Response +Systems (IECRS). Until the PSAP is commissioned, all calls to 112 will be routed +to the existing 100 emergency number (though this is the responsibility of the +carrier, not Android).</p> + +<h5 id="q-other-triggers">Q. What about other triggers such as triple-pressing +the power button?</h5> +<p>Device manufacturers may choose to implement additional triggers. However, +while the Indian DoT approves triple-tapping the hardware power button, this +trigger is <strong>not supported</strong> in the AOSP reference implementation +as some widely used applications (e.g. the Camera app) use power button gestures +that include repeated tapping of the power button. Such applications might +interfere with the emergency dialer or the user may accidentally trigger the +panic button while trying to trigger actions in these applications.</p> </body> </html> diff --git a/en/devices/tech/dalvik/jit-compiler.html b/en/devices/tech/dalvik/jit-compiler.html index c105fd06..f9d16f82 100644 --- a/en/devices/tech/dalvik/jit-compiler.html +++ b/en/devices/tech/dalvik/jit-compiler.html @@ -86,7 +86,7 @@ similar to shared libraries. <h2 id="jit-workflow">JIT workflow</h2> -<img src=./images/jit-workflow.png" alt="JIT architecture"/> +<img src="./images/jit-workflow.png" alt="JIT architecture"/> <figcaption><strong>Figure 4.</strong> JIT data flow.</figcaption> <ul> diff --git a/en/devices/tech/debug/kasan-kcov.html b/en/devices/tech/debug/kasan-kcov.html new file mode 100644 index 00000000..20ba7fce --- /dev/null +++ b/en/devices/tech/debug/kasan-kcov.html @@ -0,0 +1,410 @@ +<html devsite> + <head> + <title>Building a Pixel kernel with KASAN+KCOV</title> + <meta name="project_path" value="/_project.yaml" /> + <meta name="book_path" value="/_book.yaml" /> + </head> + <body> + <!-- + Copyright 2017 The Android Open Source Project + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + --> + +<p> +Kernel Address Sanitizer (<a +href="https://www.kernel.org/doc/html/latest/dev-tools/kasan.html">KASAN</a>) +helps kernel developers and testers find runtime memory-related bugs, such as +out-of-bound read or write operations, and use-after-free issues. While KASAN +isn't enabled on production builds due to its runtime performance +penalties and memory usage increment, it is still a valuable tool for testing +debug builds. +</p> +<p> +When used with another runtime tool called Kernel Coverage (<a +href="https://lwn.net/Articles/671640/">KCOV</a>), KASAN-sanitized and +KCOV-instrumented code helps developers and testers to detect runtime memory +errors and obtain code coverage information. In the scenario of kernel fuzz +testing, e.g. via <a href="https://github.com/google/syzkaller">syzkaller</a>, +KASAN helps to determine the root cause of crashes, and KCOV provides code +coverage information to the fuzzing engine to help in test-case or corpus +deduplication. +</p> +<p> +This page does not discuss the inner workings or mechanics of KASAN. Rather, it +serves as a guide to build and modify the Android Open Soure Project (AOSP) and +Pixel's kernel source to boot with KASAN and KCOV turned on. +</p> +<h2 id="setting-up-your-build-environment">Setting up your build +environment</h2> +<p> +Follow the steps in the <a +href="/source/requirements">Downloading and +Building</a> section to set up your build environment. +</p> +<h2 id="building-aosp">Building AOSP</h2> +<p> +Download the <a href="/source/downloading">Android source code</a>. For the +purpose of building KASAN images, choose a stable build that is not in active +development. Often, the latest available release/stable branch is a good choice. +More information about build and branch can be found at <a +href="/source/build-numbers#source-code-tags-and-builds">Source +Code Tags and Builds</a>. +</p> + +<p> +After you have successfully checked out the source code, download the necessary +device blobs that correspond to the device and branch you are using from <a +href="https://developers.google.com/android/drivers">Driver Binaries for +Nexus and Pixel Devices</a>. Download both the vendor image and the set of +binaries from the System-on-Chip (SOC) manufacturer. Then, unarchive the +downloaded tarballs, run the scripts they contain, and accept the licenses. +</p> +<aside class="note"> +<strong>Tip</strong>: Double check that you have the <a +href="/source/initializing#installing-the-jdk">right +version of JDK</a> installed on your system before proceeding further. +</aside> +<p> +Then clean up, set up your build environment, and choose your build target, +following the steps in +<a href="/source/building#cleaning-up">Preparing to Build</a>. +</p> + +<p> +To establish a working base, make your first build without modifications: +</p> + +<pre class="devsite-click-to-copy"> +<code class="devsite-terminal" data-terminal-prefix="~/src/aosp$ ">make -j48</code> +</pre> +<p> +Flash your build result to a test device (for example, marlin) and let it boot: +</p> + + +<pre class="devsite-click-to-copy"> +<code class="devsite-terminal" data-terminal-prefix="~/src/aosp$ ">cd out/target/product/marlin</code> +<code class="devsite-terminal" data-terminal-prefix="~/src/aosp/out/target/product/marlin$ ">ANDROID_PRODUCT_OUT=`pwd` fastboot flashall -w</code> +</pre> +<p> +After booting to the homescreen, you might see a pop-up that says: +</p> +<p> +<code>There's an internal problem with your device. Contact your manufacturer +for details.</code> This pop-up likely means that the build fingerprint of your +vendor and your system partition do not match. Because this build is just for +development and testing, and not a release build, just ignore it. +</p> +<h2 id="building-the-kernel">Building the kernel</h2> +<p>To build the kernel, you need to check out the correct source code, +cross-compile it, and then build the kernel image in the correct AOSP +directory.</p> +<h3 id="checking-out-kernel-source-code">Checking out kernel source code</h3> +<p> +Create a directory to store the kernel source code and clone the AOSP kernel git +repository to your local storage. +</p> + + +<pre class="devsite-click-to-copy"> +<code class="devsite-terminal devsite-click-to-copy">mkdir ~/src/marlin-kernel-src</code> +<code class="devsite-terminal devsite-click-to-copy">cd ~/src/marlin-kernel-src</code> +<code class="devsite-terminal devsite-click-to-copy" data-terminal-prefix="~/src/marlin-kernel-src$ ">git clone https://android.googlesource.com/kernel/msm</code> +</pre> +<p> +After you are done, there should be an empty directory named <code>msm</code>. +</p> +<p> +Enter the <code>msm</code> directory and <code>git checkout</code> the branch +that corresponds to the source code you are building. For the list of available +branches and tags, see the <a href="https://android.googlesource.com/kernel/msm/">Android msm +kernel source tree</a>. +</p> + + +<pre class="devsite-click-to-copy"> +<code class="devsite-terminal devsite-click-to-copy" data-terminal-prefix="~/src/marlin-kernel-src$ ">cd msm</code> +<code class="devsite-terminal devsite-click-to-copy" data-terminal-prefix="~/src/marlin-kernel-src$ ">git checkout <var>TAG_NAME</var></code> +</pre> +<p> +After completing this step, the <code>msm</code> directory should have content. +</p> +<h3 id="performing-cross-compilation">Performing cross compilation</h3> +<p> +Next you need to compile the Android kernel. +</p> +<h5 id="setting-up-your-cross-compiler">Setting up your cross-compiler</h5> +<p> +To build the kernel, you need to set up a cross-compiler. The current +recommended and tested toolchain is Android's NDK toolchain latest stable +version. To download the Android NDK, visit the official <a +href="https://developer.android.com/ndk/downloads/index.html">Android NDK +website</a>. Download the appropriate zip archive for your platform, and unzip +it. This results in a directory resembling +<code>android-ndk-<var>NDK_VERSION</var></code>. +</p> +<h5 id="downloading-the-lz4c-tool">Downloading the LZ4c tool</h5> +<p> +The Pixel kernel uses <a hre="//lz4.github.io/lz4/">LZ4 compression</a>, +so the <code>lz4c</code> tool is required when you build your kernel. If you +use Ubuntu, install the <code>lz4c</code> tool by: +</p> + + +<pre class="devsite-terminal devsite-click-to-copy">sudo apt-get install liblz4-tool +</pre> +<h4 id="building-your-kernel">Building your kernel</h4> +<p> +Set up your build environment from the <code>marlin-kernel-src/msm</code> +directory with: +</p> + + +<pre> +<code class="devsite-terminal devsite-click-to-copy" data-terminal-prefix="marlin-kernel-src/msm$ ">export ARCH=arm64</code> +<code class="devsite-terminal devsite-click-to-copy" data-terminal-prefix="marlin-kernel-src/msm$ ">export CROSS_COMPILE=<var>PATH_TO_NDK</var>/android-ndk-<var>NDK_VERSION</var>/toolchains/aarch64-linux-android-<var>TOOLCHAIN_VERSION</var>/prebuilt/linux-x86_64/bin/aarch64-linux-android-</code> +</pre> +<p> +Then build an unmodified version of your kernel to establish a working base: +</p> + + +<pre class="devsite-click-to-copy"> +<code class="devsite-terminal devsite-click-to-copy" data-terminal-prefix="marlin-kernel-src/msm$ ">make marlin_defconfig</code> +<code class="devsite-terminal devsite-click-to-copy" data-terminal-prefix="marlin-kernel-src/msm$ ">make -j48</code> +</pre> +<p> +The result of the build process can be found at: +<code>arch/arm64/boot/Image.lz4-dtb</code> +</p> +<h4 id="rebuilding-the-boot-image-in-aosp">Rebuilding the boot image in +AOSP</h4> +<p> +After you have built the kernel image, copy the result over into AOSP's +<code>device/google/marlin-kernel</code> directory, with: +</p> + + +<pre class="devsite-click-to-copy"> +<code class="devsite-terminal devsite-click-to-copy" data-terminal-prefix="~/src/aosp$ ">cp ${marlin-kernel-src}/msm/arch/arm64/boot/Image.lz4-dtb device/google/marlin-kernel</code> +<code class="devsite-terminal devsite-click-to-copy" data-terminal-prefix="~/src/aosp$ ">source build/envsetup.sh</code> +<code class="devsite-terminal devsite-click-to-copy" data-terminal-prefix="~/src/aosp$ ">lunch aosp_marlin-userdebug</code> +<code class="devsite-terminal devsite-click-to-copy" data-terminal-prefix="~/src/aosp$ ">make -j48</code> +</pre> +<p> +After a successful build, flash the target device with: +</p> + + +<pre class="devsite-click-to-copy"> +<code class="devsite-terminal devsite-click-to-copy" data-terminal-prefix="~/src/aosp$ ">cd out/target/product/marlin</code> +<code class="devsite-terminal devsite-click-to-copy" data-terminal-prefix="~/src/aosp/out/target/product/marlin$ ">fastboot flashall -w</code> +</pre> +<p> +After flashing, your device should boot. Verify the image you flashed to +the device is the kernel image you built by checking <code>Kernel +version</code> under <code>Settings -> System -> About phone</code> +after the device finishes booting. +</p> +<h2 id="modifying-the-kernel">Modifying the kernel</h2> +<h3 id="enabling-kasan-and-kcov-compile-options">Enabling KASAN and KCOV compile +options</h3> +<p> +KASAN and KCOV codes are guarded by compilation flags, which are not turned on +for normal builds. To enable them, add KASAN and KCOV options to the config +file, but drop the LZ4 config. +</p> +<p> +To do this, make a copy of the default config file, for example, +<code>marlin_defconfig</code>: +</p> + + +<pre class="devsite-click-to-copy"> +<code class="devsite-terminal devsite-click-to-copy" data-terminal-prefix="marlin-kernel-src/msm$ ">cd arch/arm64/configs</code> +<code class="devsite-terminal devsite-click-to-copy" data-terminal-prefix="marlin-kernel-src/msm/arch/arm64/configs$ ">cp marlin_defconfig marlin-kasan_defconfig</code> +</pre> +<p> +In the new config file, remove this flag <code>CONFIG_KERNEL_LZ4=y</code> and +add these flags: +</p> + +<pre class="devsite-click-to-copy">CONFIG_KASAN=y +CONFIG_KASAN_INLINE=y +CONFIG_KCOV=y +CONFIG_SLUB=y +CONFIG_SLUB_DEBUG=y +</pre> + +<h2 id="recompiling-the-kernel-with-new-configuration">Recompiling the kernel +with new configuration</h2> +<p> +After you've finished modifying your copy of the config file, recompile the +kernel. +</p> +<h3 id="reconfiguring-the-kernel">Reconfiguring the kernel</h3> +<p> +Set up your <a href="/source/building-kernels#building">build environment</a>. +Build your modified <code>defconfig</code> and check if the newly added flags +are present in the produced <code>.config</code> file. +</p> + + +<pre class="devsite-click-to-copy"> +<code class="devsite-terminal devsite-click-to-copy" data-terminal-prefix="marlin-kernel-src/msm$ ">make marlin-kasan_defconfig</code> +<code class="devsite-terminal devsite-click-to-copy" data-terminal-prefix="marlin-kernel-src/msm$ ">grep KASAN .config +CONFIG_HAVE_ARCH_<strong>KASAN</strong>=y +CONFIG_<strong>KASAN</strong>=y +# CONFIG_<strong>KASAN</strong>_OUTLINE is not set +CONFIG_<strong>KASAN</strong>_INLINE=y</code> +</pre> +<p> +You should see the KASAN flags. Compile your kernel: +</p> + + +<pre class="devsite-terminal devsite-click-to-copy" data-terminal-prefix="marlin-kernel-src/msm$ ">make -j48 +</pre> +<h3 id="checking-the-modified-kernel-image">Checking the modified kernel +image</h3> +<p> +After a successful compilation, navigate to the <code>arch/arm64/boot</code> +directory to view the compilation results. Generally, the +<code>Image.gz-dtb</code> is about 23MB and larger than that of a standard build. +</p> + + +<pre class="devsite-click-to-copy"> +<code class="devsite-terminal devsite-click-to-copy" data-terminal-prefix="marlin-kernel-src/msm$ ">cd arch/arm64/boot</code> +<code class="devsite-terminal devsite-click-to-copy" data-terminal-prefix="marlin-kernel-src/msm/arch/arm64/boot$ ">ls -lh Image.gz-dtb +-rw-r--r-- 1 username groupname 23M Aug 11 13:59 Image.gz-dtb</code> +</pre> +<p> +To see if KCOV was properly compiled, perform additional analysis on the +produced <code>vmlinux</code> at the root of the kernel source tree. If you run +an <code>objdump</code> on vmlinux, you should see numerous calls to +<code>__sanitizer_cov_trace_pc()</code>. +</p> + + +<pre class="devsite-click-to-copy"> +<code class="devsite-terminal devsite-click-to-copy" data-terminal-prefix="marlin-kernel-src$ ">sh -c '${CROSS_COMPILE}objdump -d vmlinux' | grep sanitizer +ffffffc000082030: 94040658 bl ffffffc000183990 <__sanitizer_cov_trace_pc> +ffffffc000082050: 94040650 bl ffffffc000183990 <__sanitizer_cov_trace_pc> +ffffffc000082078: 94040646 bl ffffffc000183990 <__sanitizer_cov_trace_pc> +ffffffc000082080: 94040644 bl ffffffc000183990 <__sanitizer_cov_trace_pc> +ffffffc0000820ac: 94040639 bl ffffffc000183990 <__sanitizer_cov_trace_pc> +</code></pre> +<h2 id="modifying-aosp-code">Modifying AOSP code</h2> +<p> +Before plugging in the new boot image, you need to adjust certain parameters in +AOSP's source code that govern how the device boots. This is mainly necessary to +ensure the new (inflated) image boots properly. +</p> +<h3 id="adjusting-board-parameters">Adjusting board parameters</h3> +<p> +Adjust the boot parameters defined in the device's <code>BoardConfig.mk</code> +file. It is located at <code>device/google/marlin/marlin</code> relative to the +root of your AOSP source code. +</p> + + +<pre class="devsite-click-to-copy"> +<code class="devsite-terminal devsite-click-to-copy" data-terminal-prefix="~/src/aosp$ ">cd device/google/marlin/marlin</code> +<code class="devsite-terminal devsite-click-to-copy" data-terminal-prefix="~/src/aosp/device/google/marlin/marlin$ ">vim BoardConfig.mk</code> +</pre> +<aside class="caution"> +<p> +<strong>Caution</strong>: Make sure you have a backup of the original +<code>BoardConfig.mk</code> file before proceeding, in case something goes +wrong. +</p> +<p> +The adjustments to be made can be summarized as follows through a +<code>git diff</code> result: +</p> + + +<pre>diff --git a/marlin/BoardConfig.mk b/marlin/BoardConfig.mk +index 31533fb9..81caf05d 100644 +--- a/marlin/BoardConfig.mk ++++ b/marlin/BoardConfig.mk +@@ -116,15 +116,10 @@ BOARD_EGL_CFG := device/google/marlin/egl.cfg + + BOARD_KERNEL_BASE := 0x80000000 + BOARD_KERNEL_PAGESIZE := 4096 +<var>-ifneq ($(filter marlin_kasan, $(TARGET_PRODUCT)),)</var> + BOARD_KERNEL_OFFSET := 0x80000 + BOARD_KERNEL_TAGS_OFFSET := 0x02500000 + BOARD_RAMDISK_OFFSET := 0x02700000 + BOARD_MKBOOTIMG_ARGS := --kernel_offset $(BOARD_KERNEL_OFFSET) --ramdisk_offset $(BOARD_RAMDISK_OFFSET) --tags_offset $(BOARD_KERNEL_TAGS_OFFSET) +<var>-else +-BOARD_KERNEL_TAGS_OFFSET := 0x02000000 +-BOARD_RAMDISK_OFFSET := 0x02200000 +-endif</var> + + TARGET_KERNEL_ARCH := arm64 + TARGET_KERNEL_HEADER_ARCH := arm64 +</pre> +</aside> + +<p> +If you do not wish to modify the <code>BoardConfig.mk</code> +file, you could instead create a new lunch target that contains the name +<code>marlin_kasan</code>. For more information about this process, see +<a href="/source/add-device">Adding a New Device</a>. +</p> + +<h3 id="adjusting-the-kernel-target-in-the-local-makefile">Adjusting the kernel +target in the local Makefile</h3> +<p> +The new kernel uses LZ4 compression to improve speed, but KASAN requires gzip +for better compression ratio. To accommodate this, tell the build machinery +which kernel to bundle into the final target by modifying where the +<code>LOCAL_KERNEL</code> variable points to in +<code>device/google/marlin/device-common.mk</code>. +</p> +<h2 id="rebuilding-boot-image">Rebuilding the boot image</h2> +<p> +To rebuild the boot image, copy the new kernel image into the AOSP tree in the +device-specific folder (e.g. <code>device/google/marlin-kernel</code>). Make +sure this is where the build system expects the kernel target image to be +at, according to how you modified it earlier. +</p> +<p> +Next, rebuild your flashable images, similar to how you <a +href="#building-aosp">built AOSP</a> earlier. Upon successful build, flash all +built images as usual. +</p> +<h2 id="booting-your-device-with-a-modified-kernel-image">Booting your device +with a modified kernel image</h2> +<p> +You should now have a build that boots and enters the home screen. From here, +check the device's <code>dmesg</code> output for a "<code>KernelAddressSanitizer +initialized</code>" message in the very early boot stage. That message means +KASAN is initialized during boot time. Also, you can confirm +<code>/sys/kernel/debug/kcov</code> is present on the device (you will have to +be root to do that). +</p> +<h2 id="troubleshooting">Troubleshooting</h2> +<p> +You can experiment with different kernel versions, starting with a standard +build as a working base, before turning on KASAN+KCOV compile options. When +things break, first check if the bootloader and baseband version on your device +matches those required by the new build. Finally, you might have to +catch up with a newer branch of the Android tree altogether if you venture too +far ahead with the kernel version. +</p> +</body> +</html> diff --git a/en/devices/tech/display/widgets-shortcuts.html b/en/devices/tech/display/widgets-shortcuts.html index 17af11ac..ac152384 100644 --- a/en/devices/tech/display/widgets-shortcuts.html +++ b/en/devices/tech/display/widgets-shortcuts.html @@ -38,7 +38,7 @@ </p> <ul> <li><b><a - href="https://developer.android.com/reference/android/content/pm/ShortcutManager.html">ShortuctManager.java</a></b><br> + href="https://developer.android.com/reference/android/content/pm/ShortcutManager.html">ShortcutManager.java</a></b><br> Publish Pinned shortcut section in header. <li><b>Intent.java</b><br>Javadoc for ACTION_CREATE_SHORTCUT.</li> <li><b>AppWidgetManager.java</b><br>Javadoc for requestPinAppWidget.</li> diff --git a/en/security/bulletin/2017-05-01.html b/en/security/bulletin/2017-05-01.html index c92e4ffd..9fa83bc4 100644 --- a/en/security/bulletin/2017-05-01.html +++ b/en/security/bulletin/2017-05-01.html @@ -22,7 +22,7 @@ --> -<p><em>Published May 01, 2017 | Updated August 17, 2017</em></p> +<p><em>Published May 01, 2017 | Updated October 03, 2017</em></p> <p>The Android Security Bulletin contains details of security vulnerabilities affecting Android devices. Alongside the bulletin, we have released a security @@ -935,43 +935,6 @@ QC-CR#826589</a></td> <p>* Supported Google devices on Android 7.1.1 or later that have installed all available updates are not affected by this vulnerability.</p> - -<h3 id="eop-in-kernel-trace-subsystem">Elevation of privilege vulnerability in -kernel trace subsystem</h3> - -<p>An elevation of privilege vulnerability in the kernel trace subsystem could -enable a local malicious application to execute arbitrary code within the -context of the kernel. This issue is rated as Critical due to the possibility -of a local permanent device compromise, which may require reflashing the -operating system to repair the device.</p> - -<table> - <col width="19%"> - <col width="20%"> - <col width="10%"> - <col width="23%"> - <col width="17%"> - <tr> - <th>CVE</th> - <th>References</th> - <th>Severity</th> - <th>Updated Google devices</th> - <th>Date reported</th> - </tr> - <tr> - <td>CVE-2017-0605</td> - <td>A-35399704<br> - <a -href="https://source.codeaurora.org/quic/la//kernel/msm-3.10/commit/?id=2161ae9a70b12cf18ac8e5952a20161ffbccb477"> -QC-CR#1048480</a></td> - <td>Critical</td> - <td>Nexus 5X, Nexus 6, Nexus 6P, Nexus 9, Pixel, Pixel XL, Pixel C, Android -One, Nexus Player</td> - <td>Feb 15, 2017</td> - </tr> -</table> - - <h3 id="vulnerabilities-in-qualcomm-components">Vulnerabilities in Qualcomm components</h3> @@ -3060,6 +3023,7 @@ belongs. These prefixes map as follows:</p> <li>August 10, 2017: Bulletin revised to include additional AOSP link for CVE-2017-0493.</li> <li>August 17, 2017: Bulletin revised to update reference numbers.</li> +<li>October 03, 2017: Bulletin revised to remove CVE-2017-0605.</li> </ul> </body> </html> diff --git a/en/security/bulletin/2017-07-01.html b/en/security/bulletin/2017-07-01.html index 19141843..cf74c941 100644 --- a/en/security/bulletin/2017-07-01.html +++ b/en/security/bulletin/2017-07-01.html @@ -687,13 +687,6 @@ kernel</a></td> <td>SCSI driver</td> </tr> <tr> - <td>CVE-2017-0710</td> - <td>A-34951864<a href="#asterisk">*</a></td> - <td>EoP</td> - <td>Moderate</td> - <td>TCB</td> - </tr> - <tr> <td>CVE-2017-7308</td> <td>A-36725304<br> <a href="//git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=2b6867c2ce76c596676bec7d2d525af525fdc6e2">Upstream kernel</a> @@ -1445,6 +1438,32 @@ site</a>.</p> <td>July 05, 2017</td> </tr> </table> + +<p>Google device updates also contain patches for these security +vulnerabilities, if applicable:</p> + +<table> + <col width="17%"> + <col width="19%"> + <col width="9%"> + <col width="14%"> + <col width="39%"> + <tr> + <th>CVE</th> + <th>References</th> + <th>Type</th> + <th>Severity</th> + <th>Component</th> + </tr> + <tr> + <td>CVE-2017-0710</td> + <td>A-34951864<a href="#asterisk">*</a></td> + <td>EoP</td> + <td>Moderate</td> + <td>TCB</td> + </tr> +</table> + <h2 id="acknowledgements">Acknowledgements</h2> <p>We would like to thank these researchers for their contributions:</p> @@ -1503,7 +1522,7 @@ Ltd.</td> </tr> <tr> <td>CVE-2017-0665</td> - <td><a href="mailto:arnow117@gmail.com">Hanxiang Wen</a>, Mingjian Zhou (<a + <td><a href="mailto:zc1991@mail.ustc.edu.cn">Chi Zhang</a>,<a href="mailto:arnow117@gmail.com">Hanxiang Wen</a>, Mingjian Zhou (<a href="//twitter.com/Mingjian_Zhou">@Mingjian_Zhou</a>), and Xuxian Jiang of <a href="//c0reteam.org">C0RE Team</a></td> </tr> @@ -1749,7 +1768,7 @@ site</a>.</p> <td>September 19, 2017</td> <td>Updated acknowledgements for CVE-2017-0710.</td> </tr> - <tr> + <tr> <td>1.5</td> <td>September 26, 2017</td> <td>Updated acknowledgements for CVE-2017-0681.</td> diff --git a/en/security/bulletin/2017-09-01.html b/en/security/bulletin/2017-09-01.html index 56c94f05..f4346d78 100644 --- a/en/security/bulletin/2017-09-01.html +++ b/en/security/bulletin/2017-09-01.html @@ -20,7 +20,7 @@ See the License for the specific language governing permissions and limitations under the License. --> - <p><em>Published September 5, 2017 | Updated September 28, 2017</em></p> + <p><em>Published September 5, 2017 | Updated October 5, 2017</em></p> <p>The Android Security Bulletin contains details of security vulnerabilities affecting Android devices. Security patch levels of September 05, 2017 or later @@ -1155,6 +1155,11 @@ Zhou (<a href="https://twitter.com/Mingjian_Zhou">@Mingjian_Zhou</a>), and Xuxian Jiang of <a href="http://c0reteam.org">C0RE Team</a></td> </tr> <tr> + <td>CVE-2017-0755</td> + <td>Dawei Peng of Alibaba Mobile Security Team + (<a href="http://weibo.com/u/5622360291">weibo: Vinc3nt4H</a>)</td> + </tr> + <tr> <td>CVE-2017-0775, CVE-2017-0774, CVE-2017-0771</td> <td>Elphet and Gong Guang of Alpha Team, Qihoo 360 Technology Co. Ltd.</td> </tr> diff --git a/en/security/bulletin/2017-10-01.html b/en/security/bulletin/2017-10-01.html index 6ca5f4f6..dce1e591 100644 --- a/en/security/bulletin/2017-10-01.html +++ b/en/security/bulletin/2017-10-01.html @@ -20,7 +20,7 @@ See the License for the specific language governing permissions and limitations under the License. --> - <p><em>Published October 2, 2017</em></p> +<p><em>Published October 2, 2017 | Updated October 3, 2017</em></p> <p>The Android Security Bulletin contains details of security vulnerabilities affecting Android devices. Security patch levels of October 05, 2017 or later @@ -29,9 +29,9 @@ level, see <a href="https://support.google.com/pixelphone/answer/4457705#pixel_p Check & update your Android version</a>.</p> <p>Android partners are notified of all issues at least a month before -publication. Source code patches for these issues will be released -to the Android Open Source Project (AOSP) repository in the next 48 hours. -We will revise this bulletin with the AOSP links when they are available.</p> +publication. Source code patches for these issues have been released to the +Android Open Source Project (AOSP) repository and linked from this bulletin. +This bulletin also includes links to patches outside of AOSP.</p> <p>The most severe of these issues is a critical severity vulnerability in media framework that could enable a remote attacker using a specially crafted file to @@ -121,7 +121,7 @@ additional permissions.</p> </tr> <tr> <td>CVE-2017-0806</td> - <td>A-62998805</td> + <td><a href="https://android.googlesource.com/platform/frameworks/base/+/b87c968e5a41a1a09166199bf54eee12608f3900">A-62998805</a></td> <td>EoP</td> <td>High</td> <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0</td> @@ -148,42 +148,42 @@ a privileged process.</p> </tr> <tr> <td>CVE-2017-0809</td> - <td>A-62673128</td> + <td><a href="https://android.googlesource.com/platform/frameworks/av/+/552a3b5df2a6876d10da20f72e4cc0d44ac2c790">A-62673128</a></td> <td>RCE</td> <td>Critical</td> <td>4.4.4, 5.0.2, 5.1.1, 6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0</td> </tr> <tr> <td>CVE-2017-0810</td> - <td>A-38207066</td> + <td><a href="https://android.googlesource.com/platform/external/libmpeg2/+/7737780815fe523ad7b0e49456eb75d27a30818a">A-38207066</a></td> <td>RCE</td> <td>Critical</td> <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0</td> </tr> <tr> <td>CVE-2017-0811</td> - <td>A-37930177</td> + <td><a href="https://android.googlesource.com/platform/external/libhevc/+/25c0ffbe6a181b4a373c3c9b421ea449d457e6ed">A-37930177</a></td> <td>RCE</td> <td>Critical</td> <td>5.0.2, 5.1.1, 6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0</td> </tr> <tr> <td>CVE-2017-0812</td> - <td>A-62873231</td> + <td><a href="https://android.googlesource.com/device/google/dragon/+/7df7ec13b1d222ac3a66797fbe432605ea8f973f">A-62873231</a></td> <td>EoP</td> <td>High</td> <td>7.0, 7.1.1, 7.1.2, 8.0</td> </tr> <tr> <td>CVE-2017-0815</td> - <td>A-63526567</td> + <td><a href="https://android.googlesource.com/platform/frameworks/av/+/f490fc335772a9b14e78997486f4a572b0594c04">A-63526567</a></td> <td>ID</td> <td>Moderate</td> <td>4.4.4, 5.0.2, 5.1.1, 6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0</td> </tr> <tr> <td>CVE-2017-0816</td> - <td>A-63662938</td> + <td><a href="https://android.googlesource.com/platform/frameworks/av/+/f490fc335772a9b14e78997486f4a572b0594c04">A-63662938</a></td> <td>ID</td> <td>Moderate</td> <td>4.4.4, 5.0.2, 5.1.1, 6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0</td> @@ -210,7 +210,8 @@ process.</p> </tr> <tr> <td>CVE-2017-14496</td> - <td>A-64575136</td> + <td><a href="https://android.googlesource.com/platform/external/dnsmasq/+/ff755ca73c98a1f2706fe86996e4bf6215054834">A-64575136</a> + [<a href="https://android.googlesource.com/platform/external/dnsmasq/+/68a974de72b5091ce608815a349daaeb05cdeab5">2</a>]</td> <td>RCE</td> <td>High</td> <td>4.4.4, 5.0.2, 5.1.1, 6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0</td> @@ -502,6 +503,11 @@ Acknowledgements</a> page.</p> <td>October 2, 2017</td> <td>Bulletin published.</td> </tr> + <tr> + <td>1.1</td> + <td>October 3, 2017</td> + <td>Bulletin revised to include AOSP links.</td> + </tr> </table> </body> </html> diff --git a/en/security/bulletin/pixel/2017-10-01.html b/en/security/bulletin/pixel/2017-10-01.html index fd8eb49d..05e9d059 100644 --- a/en/security/bulletin/pixel/2017-10-01.html +++ b/en/security/bulletin/pixel/2017-10-01.html @@ -1,6 +1,6 @@ <html devsite> <head> - <title>Pixel/Nexus Security Bulletin—October 2017</title> + <title>Pixel / Nexus Security Bulletin—October 2017</title> <meta name="project_path" value="/_project.yaml" /> <meta name="book_path" value="/_book.yaml" /> </head> @@ -20,9 +20,9 @@ See the License for the specific language governing permissions and limitations under the License. --> - <p><em>Published October 2, 2017</em></p> +<p><em>Published October 2, 2017 | Updated October 3, 2017</em></p> -<p>The Pixel/ Nexus Security Bulletin contains details of security vulnerabilities +<p>The Pixel / Nexus Security Bulletin contains details of security vulnerabilities and functional improvements affecting <a href="https://support.google.com/pixelphone/answer/4457705#pixel_phones&nexus_devices"> supported Google Pixel and Nexus devices</a> (Google devices). For @@ -56,16 +56,14 @@ Google Developer site</a>.</p> </ul> <h2 id="patches">Security patches</h2> -Vulnerabilities are -grouped under the component that they affect. There is a description of the -issue and a table with the CVE, associated references, +Vulnerabilities are grouped under the component that they affect. There is a +description of the issue and a table with the CVE, associated references, <a href="#type">type of vulnerability</a>, <a href="/security/overview/updates-resources.html#severity">severity</a>, and updated Android Open Source Project (AOSP) versions (where applicable). -When available, we link the public -change that addressed the issue to the bug ID, like the AOSP change list. When -multiple changes relate to a single bug, additional references are linked to -numbers following the bug ID.</p> +When available, we link the public change that addressed the issue to the bug +ID, like the AOSP change list. When multiple changes relate to a single bug, +additional references are linked to numbers following the bug ID.</p> <h3 id="framework">Framework</h3> @@ -84,14 +82,15 @@ numbers following the bug ID.</p> </tr> <tr> <td>CVE-2017-0807</td> - <td>A-35056974</td> + <td>A-35056974<a href="#asterisk">*</a></td> <td>EoP</td> <td>High</td> <td>4.4.4, 5.0.2, 5.1.1, 6.0, 6.0.1, 7.0, 7.1.1, 7.1.2</td> </tr> <tr> <td>CVE-2017-0808</td> - <td>A-62301183</td> + <td><a href="https://android.googlesource.com/platform/libcore/+/809681f310663288e83587089abb7715c68f6924">A-62301183</a> + [<a href="https://android.googlesource.com/platform/libcore/+/100a8006a7baab1bb62820eb62577c0b0849fbc3">2</a>]</td> <td>ID</td> <td>Moderate</td> <td>7.0, 7.1.1, 7.1.2, 8.0</td> @@ -115,14 +114,14 @@ numbers following the bug ID.</p> </tr> <tr> <td>CVE-2017-0813</td> - <td>A-36531046</td> + <td><a href="https://android.googlesource.com/platform/frameworks/av/+/7fa3f552a6f34ed05c15e64ea30b8eed53f77a41">A-36531046</a></td> <td>DoS</td> <td>Moderate</td> <td>7.0, 7.1.1, 7.1.2</td> </tr> <tr> <td rowspan="2">CVE-2017-0814</td> - <td rowspan="2">A-62800140</td> + <td rowspan="2"><a href="https://android.googlesource.com/platform/external/tremolo/+/eeb4e45d5683f88488c083ecf142dc89bc3f0b47">A-62800140</a></td> <td>ID</td> <td>Moderate</td> <td>7.0, 7.1.1, 7.1.2, 8.0</td> @@ -134,14 +133,14 @@ numbers following the bug ID.</p> </tr> <tr> <td>CVE-2017-0817</td> - <td>A-63522430</td> + <td><a href="https://android.googlesource.com/platform/frameworks/av/+/d834160d9759f1098df692b34e6eeb548f9e317b">A-63522430</a></td> <td>ID</td> <td>Moderate</td> <td>4.4.4, 5.0.2, 5.1.1, 6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0</td> </tr> <tr> <td rowspan="2">CVE-2017-0818</td> - <td rowspan="2">A-63581671</td> + <td rowspan="2"><a href="https://android.googlesource.com/platform/frameworks/av/+/d07f5c14e811951ff9b411ceb84e7288e0d04aaf">A-63581671</a></td> <td>NSI</td> <td>NSI</td> <td>7.0, 7.1.1, 7.1.2, 8.0</td> @@ -153,7 +152,7 @@ numbers following the bug ID.</p> </tr> <tr> <td rowspan="2">CVE-2017-0819</td> - <td rowspan="2">A-63045918</td> + <td rowspan="2"><a href="https://android.googlesource.com/platform/external/libhevc/+/87fb7909c49e6a4510ba86ace1ffc83459c7e1b9">A-63045918</a></td> <td>NSI</td> <td>NSI</td> <td>7.0, 7.1.1, 7.1.2, 8.0</td> @@ -165,7 +164,7 @@ numbers following the bug ID.</p> </tr> <tr> <td rowspan="2">CVE-2017-0820</td> - <td rowspan="2">A-62187433</td> + <td rowspan="2"><a href="https://android.googlesource.com/platform/frameworks/av/+/8a3a2f6ea7defe1a81bb32b3c9f3537f84749b9d">A-62187433</a></td> <td>NSI</td> <td>NSI</td> <td>7.0, 7.1.1, 7.1.2, 8.0</td> @@ -194,14 +193,14 @@ numbers following the bug ID.</p> </tr> <tr> <td>CVE-2017-0822</td> - <td>A-63787722</td> + <td><a href="https://android.googlesource.com/platform/frameworks/base/+/c574568aaede7f652432deb7707f20ae54bbdf9a">A-63787722</a></td> <td>EoP</td> <td>Moderate</td> <td>6.0.1, 7.0, 7.1.1, 7.1.2, 8.0</td> </tr> <tr> <td>CVE-2017-0823</td> - <td>A-37896655</td> + <td><a href="https://android.googlesource.com/platform/hardware/ril/+/cd5f15f588a5d27e99ba12f057245bfe507f8c42">A-37896655</a></td> <td>ID</td> <td>Moderate</td> <td>4.4.4, 5.0.2, 5.1.1, 6.0, 6.0.1, 7.0, 7.1.1, 7.1.2</td> @@ -670,6 +669,11 @@ are not required for declaring a security patch level. <td>October 2, 2017</td> <td>Bulletin published.</td> </tr> + <tr> + <td>1.1</td> + <td>October 3, 2017</td> + <td>Bulletin revised to include AOSP links.</td> + </tr> </table> </body> </html> diff --git a/en/security/overview/acknowledgements.html b/en/security/overview/acknowledgements.html index d444a357..2179f646 100644 --- a/en/security/overview/acknowledgements.html +++ b/en/security/overview/acknowledgements.html @@ -153,6 +153,11 @@ href="http://c0reteam.org/">C0RE Team</a></td> <td>CVE-2017-0397, CVE-2017-0405, CVE-2017-0410, CVE-2017-0826</td> </tr> <tr> + <td>Dawei Peng of Alibaba Mobile Security Team + (<a href="http://weibo.com/u/5622360291">weibo: Vinc3nt4H</a>)</td> + <td>CVE-2017-0755</td> + </tr> + <tr> <td>Daxing Guo (<a href="https://twitter.com/freener0">@freener0</a>) of Xuanwu Lab, Tencent</td> <td>CVE-2017-0386, CVE-2017-0553, CVE-2017-0585, CVE-2017-0706</td> diff --git a/en/source/_toc.yaml b/en/source/_toc.yaml index 09c42a32..8572b0ac 100644 --- a/en/source/_toc.yaml +++ b/en/source/_toc.yaml @@ -58,7 +58,7 @@ toc: - title: Submitting Patches path: /source/submit-patches - title: View Patches - path: http://android-review.googlesource.com + path: /source/view-patches - title: Life of a Bug path: /source/life-of-a-bug - title: Reporting Bugs diff --git a/en/source/build-numbers.html b/en/source/build-numbers.html index 7db85331..e9809170 100644 --- a/en/source/build-numbers.html +++ b/en/source/build-numbers.html @@ -773,33 +773,41 @@ site:</p> <td>Pixel XL, Pixel</td> </tr> <tr> + <td>NBD92N</td> + <td>android-7.0.0_r34</td> + <td>Nougat</td> + <td></td> + </tr> + <tr> <td>NBD92G</td> <td>android-7.0.0_r33</td> <td>Nougat</td> <td>Nexus 6</td> - <tr> + </tr> <tr> <td>NBD92F</td> <td>android-7.0.0_r32</td> <td>Nougat</td> <td>Nexus 6</td> - <tr> + </tr> <tr> <td>NBD92E</td> <td>android-7.0.0_r31</td> <td>Nougat</td> <td>Nexus 6</td> - <tr> + </tr> <tr> <td>NBD92D</td> <td>android-7.0.0_r30</td> <td>Nougat</td> <td>Nexus 6</td> + </tr> <tr> <td>NBD91Z</td> <td>android-7.0.0_r29</td> <td>Nougat</td> <td>Nexus 6</td> + </tr> <tr> <td>NBD91Y</td> <td>android-7.0.0_r28</td> @@ -897,6 +905,12 @@ site:</p> <td>Nexus 5X, Nexus 9 (volantis), Nexus Player, Pixel C</td> </tr> <tr> + <td>MOI10E</td> + <td>android-6.0.1_r81</td> + <td>Marshmallow</td> + <td></td> + </tr> + <tr> <td>MOB31Z</td> <td>android-6.0.1_r80</td> <td>Marshmallow</td> diff --git a/en/source/requirements.html b/en/source/requirements.html index 97f86788..e57a270f 100644 --- a/en/source/requirements.html +++ b/en/source/requirements.html @@ -97,6 +97,20 @@ other blobs below. See <a branches</li> </ul> + <h3 id=toolchain>Build toolchain</h3> + + <p>Android 8.0 and later support only <a +href="https://developer.android.com/ndk/guides/standalone_toolchain.html#working_with_clang">Clang/LLVM</a> + for building the Android platform. Join the <a +href="https://groups.google.com/forum/#!forum/android-llvm">android-llvm</a> + group to pose questions and get help. Report NDK/compiler issues at the <a +href="https://github.com/android-ndk/ndk">NDK GitHub</a>.</p> + +<p>For the +<a href="https://developer.android.com/ndk/guides/index.html">Native +Development Kit (NDK)</a> and legacy kernels, GCC 4.9 included +in the AOSP master branch (under <code>prebuilts/</code>) may also be used.</p> + <h3 id=older-versions>Packages for older versions</h3> <p>The sections below provide relevant operating systems and JDK packages for diff --git a/en/source/submit-patches.html b/en/source/submit-patches.html index 5620209e..c61fb2c7 100644 --- a/en/source/submit-patches.html +++ b/en/source/submit-patches.html @@ -74,7 +74,7 @@ repo start <var>NAME</var> . </pre> <p>You can start several independent branches at the same time in the same repository. The branch NAME is local to your workspace and will not be included -on gerrit or the final source tree.</p> +on Gerrit or the final source tree.</p> <h3 id="make-your-change">Make your change</h3> <p>Once you have modified the source files (and validated them, please) commit the changes to your local repository:</p> @@ -90,7 +90,7 @@ guidelines for writing changelist descriptions: </p> <li> <p>Start with a one-line summary (50 characters maximum), followed by a blank line. -This format is used by git and gerrit for various displays.</p> +This format is used by git and Gerrit for various displays.</p> </li> <li> @@ -115,9 +115,9 @@ which is likely to take up multiple lines. <p>A unique change ID and your name and email as provided during <code>repo init</code> will be automatically added to your commit message. </p> -<h3 id="upload-to-gerrit">Upload to gerrit</h3> +<h3 id="upload-to-gerrit">Upload to Gerrit</h3> <p>Once you have committed your change to your personal history, upload it -to gerrit with</p> +to Gerrit with</p> <pre class="devsite-terminal devsite-click-to-copy"> repo upload </pre> @@ -131,14 +131,14 @@ for your patch.</p> <h3 id="uploading-a-replacement-patch">Uploading a replacement patch</h3> <p>Suppose a reviewer has looked at your patch and requested a small modification. You can amend your commit within git, which will result in a -new patch on gerrit with the same change ID as the original.</p> +new patch on Gerrit with the same change ID as the original.</p> <aside class="note"><b>Note:</b> If you have made other commits since uploading this patch, you will need to manually move your git HEAD.</aside> <pre class="devsite-click-to-copy"> <code class="devsite-terminal">git add -A</code> <code class="devsite-terminal">git commit --amend</code> </pre> -<p>When you upload the amended patch, it will replace the original on gerrit +<p>When you upload the amended patch, it will replace the original on Gerrit and in your local git history.</p> <h3 id="resolving-sync-conflicts">Resolving sync conflicts</h3> @@ -169,90 +169,6 @@ Gerrit automatically merges the change into the public repository. Other users will be able to run <code>repo sync</code> to pull the update into their local client.</p> -<h2 id="for-reviewers-and-verifiers">For reviewers and verifiers</h2> - -<h3 id="reviewing-a-change">Reviewing a change</h3> -<p>If you are assigned to be the Approver for a change, you need to determine -the following:</p> -<ul> -<li> -<p>Does this change fit within this project's stated purpose?</p> -</li> -<li> -<p>Is this change valid within the project's existing architecture?</p> -</li> -<li> -<p>Does this change introduce design flaws that will cause problems in -the future?</p> -</li> -<li> -<p>Does this change follow the best practices that have been established -for this project?</p> -</li> -<li> -<p>Is this change a good way to perform the described function?</p> -</li> -<li> -<p>Does this change introduce any security or instability risks?</p> -</li> -</ul> -<p>If you approve of the change, mark it with LGTM ("Looks Good to Me") -within Gerrit.</p> -<h3 id="verifying-a-change">Verifying a change</h3> -<p>If you are assigned to be the Verifier for a change, you need to do the -following:</p> -<ul> -<li> -<p>Patch the change into your local client using one of the Download -commands.</p> -</li> -<li> -<p>Build and test the change.</p> -</li> -<li> -<p>Within Gerrit use Publish Comments to mark the commit as "Verified" or -"Fails," and add a message explaining what problems were identified.</p> -</li> -</ul> - -<h3 id="downloading-changes-from-gerrit">Downloading changes from Gerrit</h3> -<p>A submission that has been verified and merged will be downloaded with -the next <code>repo sync</code>. If you wish to download a specific change -that has not yet been approved, run</p> -<pre class="devsite-terminal devsite-click-to-copy"> -repo download <var>TARGET CHANGE</var> -</pre> -<p>where TARGET is the local directory into which the change should be -downloaded and CHANGE is the -change number as listed in <a -href="https://android-review.googlesource.com/">Gerrit</a>. For more -information, -see the <a href="/source/using-repo.html">Repo reference</a>.</p> -<h3 id="how-do-i-become-a-verifier-or-approver">How do I become a Verifier -or Approver?</h3> -<p>In short, contribute high-quality code to one or more of the Android -projects. -For details about the different roles in the Android Open Source community and -who plays them, see <a href="/source/roles.html">Project -Roles</a>.</p> -<h3 id="diffs-and-comments">Diffs and comments</h3> -<p>To open the details of the change within Gerrit, click on the "Id number" -or "Subject" of a change. To compare the established code with the updated -code, click the file name under "Side-by-side diffs."</p> -<h3 id="adding-comments">Adding comments</h3> -<p>Anyone in the community can use Gerrit to add inline comments to code -submissions. A good comment will be relevant to the line or section of code -to which it is attached in Gerrit. It might be a short and constructive -suggestion about how a line of code could be improved, or it might be an -explanation from the author about why the code makes sense the way it is.</p> -<p>To add an inline comment, double-click the relevant line of the code -and write your comment in the text box that opens. When you click Save, -only you can see your comment.</p> -<p>To publish your comments so that others using Gerrit will be able to see -them, click the Publish Comments button. Your comments will be emailed to -all relevant parties for this change, including the change owner, the patch -set uploader (if different from the owner), and all current reviewers.</p> -<p><a name="upstream-projects"></a></p> <h2 id="upstream-projects">Upstream Projects</h2> <p>Android makes use of a number of other open source projects, such as the Linux kernel and WebKit, as described in diff --git a/en/source/view-patches.html b/en/source/view-patches.html new file mode 100644 index 00000000..6b69f3cc --- /dev/null +++ b/en/source/view-patches.html @@ -0,0 +1,142 @@ +<html devsite> + <head> + <title>View Patches</title> + <meta name="project_path" value="/_project.yaml" /> + <meta name="book_path" value="/_book.yaml" /> + </head> + <body> + <!-- + Copyright 2017 The Android Open Source Project + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + --> + + <p> + If you want to view all patches to the Android Open Source Project, or + if you are reviewing or verifying a change, look in the <a + href="https://www.google.com/url?sa=D&q=https%3A%2F%2Fandroid-review.googlesource.com%2F%23%2Fq%2Fstatus%3Aopen%2BOR%2Bstatus%3Aclosed"> + AOSP Gerrit</a>. For more information on how to find a specific change, see <a + href="https://gerrit-review.googlesource.com/Documentation/user-search.html"> + Gerrit Code Review - Searching Changes</a>. + </p> + + <h2 id="reviewing-a-change">Reviewing a change</h2> + + <p> + If you are assigned to be the <em>Reviewer</em> for a change, you need + to determine the following: + </p> + + <ul> + <li>Does this change fit within this project's stated purpose?</li> + <li>Is this change valid within the project's existing architecture? + </li> + <li>Does this change introduce design flaws that will cause problems in + the future?</li> + <li>Does this change follow the best practices that have been + established for this project?</li> + <li>Is this change a good way to perform the described function?</li> + <li>Does this change introduce any security or instability risks?</li> + </ul> + + <p> + If you approve of the change, mark it with LGTM ("Looks Good to Me") + within Gerrit. + </p> + + <h2 id="verifying-a-change">Verifying a change</h2> + + <p> + If you are assigned to be the <em>Verifier</em> for a change, you need + to do the following: + </p> + + <ul> + <li>Patch the change into your local client using one of the Download + commands.</li> + <li>Build and test the change.</li> + <li>Within Gerrit select the <strong>Reply</strong> button. This + brings up a comment box where you can mark the change as + <em>Verified</em> or not, and add a message explaining what problems + were identified.</li> + </ul> + + <h2 id="downloading-changes-from-gerrit">Downloading changes from Gerrit + </h2> + + <p> + A submission that has been verified and merged will be downloaded with + the next <code>repo sync</code>. If you wish to download a specific + change that has not yet been approved, run + </p> + + + <pre + class="devsite-terminal devsite-click-to-copy"> +repo download <var>TARGET CHANGE</var></pre> + + <p> where <code><var>TARGET</var></code> is the local directory into + which the change should be downloaded and + <code><var>CHANGE</var></code> is the change number as listed in + Gerrit. For more information, see the <a + href="https://source.android.com/source/using-repo.html">Repo reference + </a>. + </p> + + <h2 id="how-do-i-become-a-verifier-or-reviewer">How do I become a Verifier + or Reviewer?</h2> + + <p> + In short, contribute high-quality code to one or more of the Android + projects. For details about the different roles in the Android Open + Source community and who plays them, see <a + href="https://source.android.com/source/roles.html">Project Roles</a>. + </p> + + <h2 id="diffs-and-comments">Diffs and comments</h2> + + <p> + To open the details of the change within Gerrit, click on the <em>Id + number</em> or <em>Subject</em> of a change. To compare the + established code with the updated code, click the file name under + <em>Side-by-side diffs</em>. + </p> + + <h2 id="adding-comments">Adding comments</h2> + + <p> + Anyone in the community can use Gerrit to add inline comments to code + submissions. A good comment will be relevant to the line or section of + code to which it is attached in Gerrit. It might be a short and + constructive suggestion about how a line of code could be improved, or + it might be an explanation from the author about why the code makes + sense the way it is. + </p> + + <p> + To add an inline comment, double-click the relevant line of the code + and write your comment in the text box that opens. When you click + <strong>Save</strong>, only you can see your comment. + </p> + + <p> + To publish your comments so that others using Gerrit will be able to + see them, click the Publish Comments button. Your comments will be + emailed to all relevant parties for this change, including the change + owner, the patch set uploader (if different from the owner), and all + current reviewers. + </p> + + </body> + +</html> diff --git a/zh-cn/devices/drm.html b/zh-cn/devices/drm.html index ba19cc5c..d43655dc 100644 --- a/zh-cn/devices/drm.html +++ b/zh-cn/devices/drm.html @@ -20,42 +20,43 @@ limitations under the License. --> -<img style="float: right; margin: 0px 15px 15px 15px;" src="images/ape_fwk_hal_drm.png" alt="Android DRM HAL 图标"/> +<img style="float: right; margin: 0px 15px 15px 15px;" src="images/ape_fwk_hal_drm.png" alt="安卓 DRM HAL 图标"/> -<p>本文档概要介绍了 Android DRM 框架，并介绍了 DRM 插件必须实现的接口。本文档不提供可由 DRM 方案定义的稳健性规则或合规性规则的相关说明。</p> +<p>本文档概要介绍了安卓数字版权管理 (DRM) 框架，并介绍了 DRM 插件必须实现的接口。本文档不提供可由 DRM 方案定义的稳健性规则或合规性规则的相关说明。</p> <h2 id="introduction">简介</h2> -<p>Android 平台提供了一个可扩展的 DRM 框架，以便应用根据与受版权保护的内容相关的许可限制条件来管理这些内容。DRM 框架支持多种 DRM 方案；设备具体支持哪些 DRM 方案由设备制造商决定。Android 3.0 中引入的 DRM 框架为应用开发者提供了一个统一接口，并隐藏了 DRM 操作的复杂性。DRM 框架为受保护和不受保护的内容提供了一致的操作模式。DRM 方案可以定义非常复杂的许可元数据使用模型。DRM 框架提供了 DRM 内容与许可之间的关联，并处理权限管理。这样可以将媒体播放器从受 DRM 保护或不受保护的内容中提取出来。请参阅 <a href="https://developer.android.com/reference/android/media/MediaDrm.html">MediaDrm</a>，了解如何使用该类来获取用于解密受保护的媒体流的密钥。</p> +<p>安卓平台提供了一个可扩展的 DRM 框架，以便应用根据与受版权保护的内容关联的许可限制条件来管理这些内容。DRM 框架支持多种 DRM 方案；设备具体支持哪些 DRM 方案由设备制造商决定。安卓 3.0 中引入的 DRM 框架为应用开发者提供了一个统一接口，并隐藏了 DRM 操作的复杂性。DRM 框架为受保护和不受保护的内容提供了一致的操作模式。DRM 方案可以定义非常复杂的许可元数据使用模型。DRM 框架提供了 DRM 内容与许可之间的关联，并处理权限管理。这样可以将媒体播放器从受 DRM 保护或不受保护的内容中提取出来。请参阅 <a href="https://developer.android.com/reference/android/media/MediaDrm.html">MediaDrm</a>，了解如何使用该类来获取用于解密受保护的媒体流的密钥。</p> - <img src="/devices/images/ape_fwk_drm.png" alt="Android DRM HAL"/> + <img src="/devices/images/ape_fwk_drm.png" alt="安卓 DRM HAL"/> <p class="img-caption"><strong>图 1. </strong> DRM 硬件抽象层</p> -<p>提供丰富数字内容的能力对于移动设备用户来说非常重要。为保证内容的广泛覆盖面，Android 开发者和数字内容发布者需要在整个 Android 生态系统中实现受支持的一致的 DRM。为了使此类数字内容适用于 Android 设备并确保至少有一个一致的 DRM 可用于所有设备，Google 在 Android 兼容设备上提供了无需支付许可费用的 DRM。在 Android 3.0 及更高版本的平台上，DRM 插件与 Android DRM 框架集成在一起，并且可以使用由硬件支持的保护功能来保护付费内容和用户凭据。 +<p>提供丰富数字内容的能力对于移动设备用户来说非常重要。为保证内容的广泛覆盖面，安卓开发者和数字内容发布者需要在整个安卓生态系统中支持一致的 DRM 实现。为了让这类数字内容适用于安卓设备，并确保至少有一个一致的 DRM 可用于所有设备，Google 会在兼容的安卓设备上提供无需支付许可费用的 DRM。在安卓 3.0 及更高版本的平台上，DRM 插件会与安卓 DRM 框架集成在一起，并可使用受硬件支持的保护功能来确保付费内容和用户凭据的安全。 </p> -<p>DRM 插件提供的内容保护取决于底层硬件平台的安全性和内容保护功能。设备的硬件功能包括硬件安全启动，可建立加密密钥的安全性和保护的信任链。设备的内容保护功能包括设备内加密帧的保护和通过可信输出保护机制实现的内容保护。并非任意硬件平台都支持上述所有的安全性和内容保护功能。安全性绝不会在堆栈的单个位置实现，而是依赖于硬件、软件和服务的集成。将硬件安全性功能、可信启动机制以及用于处理安全性功能的隔离安全操作系统组合使用是交付安全设备的关键。</p> +<p> +DRM 插件提供的内容保护功能取决于底层硬件平台的安全性和内容保护功能。设备的硬件功能包括硬件安全启动，可建立加密密钥的安全性和保护的信任链。设备的内容保护功能包括设备内加密帧的保护和通过可信输出保护机制实现的内容保护。并非任意硬件平台都支持上述所有的安全性和内容保护功能。安全性绝不会在堆栈的单个位置实现，而是依赖于硬件、软件和服务的集成。将硬件安全性功能、可信启动机制以及用于处理安全性功能的隔离安全操作系统组合使用是交付安全设备的关键。</p> <h2 id="architecture">架构</h2> <p>DRM 框架与实现无关，可在方案特定的 DRM 插件中提取特定 DRM 方案实现的详情。DRM 框架包括可执行以下操作的简单 API：处理复杂的 DRM 操作、向在线 DRM 服务注册用户和设备、从许可中提取限制信息、将 DRM 内容与其许可相关联，以及最终解密 DRM 内容。</p> -<p>Android DRM 框架在以下两个架构层中实现：</p> +<p>安卓 DRM 框架在以下两个架构层中实现：</p> <ul> -<li>DRM framework API：通过 Android 应用框架提供给应用，并通过适用于标准应用的 Dalvik VM 运行。</li> +<li>DRM framework API：通过安卓应用框架提供给应用，并通过适用于标准应用的 Dalvik VM 运行。</li> <li>本机代码 DRM 管理器：用于实现 DRM 框架，并为 DRM 插件（代理）提供接口，以便处理各种 DRM 方案的版权管理和解密操作。</li> </ul> - <img src="images/ape_fwk_drm_2.png" alt="Android DRM 框架"/> + <img src="images/ape_fwk_drm_2.png" alt="安卓 DRM 框架"/> <p class="img-caption"><strong>图 2. </strong> DRM 框架</p> -<p>有关详情，请参阅 <a href="http://developer.android.com/reference/android/drm/package-summary.html">Android DRM 文件包参考</a>。</p> +<p>有关详情，请参阅<a href="http://developer.android.com/reference/android/drm/package-summary.html">安卓 DRM 文件包参考</a>。</p> <h2 id="plug-ins">插件</h2> <p>如下图所示，DRM 框架使用插件架构来支持各种 DRM 方案。DRM 管理器服务在一个独立进程中运行，以确保隔离执行 DRM 插件。从 DrmManagerClient 到 DrmManagerService 的每个 API 调用都需要使用 binder IPC 机制来跨越进程边界。DrmManagerClient 提供了 Java 编程语言实现，作为运行时应用的通用接口；此外，它还提供了 DrmManagerClient 本机实现作为本机模块的接口。DRM 框架的调用者仅访问 DrmManagerClient，无需了解每个 DRM 方案。</p> - <img src="images/ape_fwk_drm_plugins.png" alt="Android DRM 插件"/> + <img src="images/ape_fwk_drm_plugins.png" alt="安卓 DRM 插件"/> <p class="img-caption"><strong>图 3. </strong> 带有插件的 DRM 框架</p> @@ -64,7 +65,7 @@ /system/lib/drm/plugins/native/ </pre> -<img src="images/ape_fwk_drm_plugins_life.png" alt="Android DRM 插件生命周期"/> +<img src="images/ape_fwk_drm_plugins_life.png" alt="安卓 DRM 插件生命周期"/> <p class="img-caption"><strong>图 4. </strong> DRM 插件生命周期</p> @@ -90,7 +91,7 @@ DrmInfo* acquireDrmInfo(int uniqueId, const DrmInfoRequest* drmInfoRequest); <pre class="devsite-click-to-copy prettyprint"> DrmInfoStatus* processDrmInfo(int uniqueId, const DrmInfo* drmInfo); </pre> -<p>processDrmInfo() 以异步方式运行，事务的结果可通过 OnEventListener 或 OnErrorListener 检索。</p> +<p>processDrmInfo() 会以异步方式运行，事务的结果可通过 OnEventListener 或 OnErrorListener 检索。</p> <h3 id="drm-rights">DRM 权限</h3> @@ -109,7 +110,7 @@ status_t saveRights(int uniqueId, const DrmRights& drmRights, const String8& <p>将 DRM 权限保存到指定的权限路径并与内容路径相关联。输入参数是要保存的 DrmRights、权限要保存到的权限文件路径，以及已保存内容所在的内容文件路径。</p> <h3 id="metadata">许可元数据</h3> -<p>许可元数据（如许可到期时间、可重复计数等）可嵌入受保护内容的权限内。Android DRM 框架提供了 API 来返回与输入内容相关联的限制条件。请参阅 <a href="http://developer.android.com/reference/android/drm/DrmManagerClient.html">DrmManagerClient</a> 了解更多信息。</p> +<p>许可元数据（如许可到期时间、可重复计数等）可嵌入受保护内容的权限内。安卓 DRM 框架提供了 API 来返回与输入内容相关联的限制条件。请参阅 <a href="http://developer.android.com/reference/android/drm/DrmManagerClient.html">DrmManagerClient</a> 了解更多信息。</p> <pre class="devsite-click-to-copy prettyprint"> DrmConstraints* getConstraints(int uniqueId, const String path, int @@ -117,7 +118,7 @@ action); </pre> <p>getConstraint 函数调用可返回受保护内容中嵌入的限制条件的键值对。要检索这些限制条件，则需要 uniqueId（受保护内容的会话和路径的唯一标识符）。此外，还需要执行被定义为 Action::DEFAULT、Action::PLAY 等的操作。</p> - <img src="images/ape_fwk_drm_retrieve_license.png" alt="Android DRM 许可元数据"/> + <img src="images/ape_fwk_drm_retrieve_license.png" alt="安卓 DRM 许可元数据"/> <p class="img-caption"><strong>图 5. </strong> 检索许可元数据</p> @@ -147,7 +148,7 @@ status_t openDecryptSession( <h3 id="source">源代码</h3> -<p>Android DRM 框架包括几个示例、一个 passthru 插件和一个转发锁定插件，它们的位置如下：</p> +<p>安卓 DRM 框架包括几个示例、一个 passthru 插件和一个转发锁定插件，它们的位置如下：</p> <pre class="devsite-click-to-copy"> <var>PLATFORM_ROOT</var>/frameworks/av/drm/libdrmframework/plugins/passthru <var>PLATFORM_ROOT</var>/frameworks/av/drm/libdrmframework/plugins/forward-lock |