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 /en/devices | |
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
Diffstat (limited to 'en/devices')
-rw-r--r-- | en/devices/_toc-tech.yaml | 2 | ||||
-rw-r--r-- | en/devices/architecture/hidl/versioning.html | 2 | ||||
-rw-r--r-- | en/devices/bluetooth/hci_requirements.html | 564 | ||||
-rw-r--r-- | en/devices/tech/connect/emergency-affordance.html | 242 | ||||
-rw-r--r-- | en/devices/tech/dalvik/jit-compiler.html | 2 | ||||
-rw-r--r-- | en/devices/tech/debug/kasan-kcov.html | 410 | ||||
-rw-r--r-- | en/devices/tech/display/widgets-shortcuts.html | 2 |
7 files changed, 852 insertions, 372 deletions
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> |