aboutsummaryrefslogtreecommitdiff
path: root/en/devices
diff options
context:
space:
mode:
authorAndroid Partner Docs <noreply@android.com>2017-10-12 23:50:33 +0000
committerandroid-build-merger <android-build-merger@google.com>2017-10-12 23:50:33 +0000
commit4f88a0c2d6ad75a024d9e99c08cd85d53b9f14b5 (patch)
tree02fbb342c6f4bca6841ecbd345644bc030916535 /en/devices
parente666c7a2d6d7a0152dd038d6fbec21b7811a8c36 (diff)
parent0ba442dfe941cbb8bc0c024e584ca861474c8072 (diff)
downloadsource.android.com-4f88a0c2d6ad75a024d9e99c08cd85d53b9f14b5.tar.gz
Merge "Docs: Changes to source.android.com" am: 261f6b9388 am: 344332ce19
am: 0ba442dfe9 Change-Id: Ic0d6c065065908759507e3cf691bac03f6388b98
Diffstat (limited to 'en/devices')
-rw-r--r--en/devices/_toc-tech.yaml2
-rw-r--r--en/devices/architecture/hidl/versioning.html2
-rw-r--r--en/devices/bluetooth/hci_requirements.html564
-rw-r--r--en/devices/tech/connect/emergency-affordance.html242
-rw-r--r--en/devices/tech/dalvik/jit-compiler.html2
-rw-r--r--en/devices/tech/debug/kasan-kcov.html410
-rw-r--r--en/devices/tech/display/widgets-shortcuts.html2
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 --&gt; 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&lt;<i>SimSlotNumber</i>&gt;</code>' when a SIM is inserted
-and <code><i>&lt;SimSlotNumber&gt;</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 -&gt; System -&gt; 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 &lt;__sanitizer_cov_trace_pc&gt;
+ffffffc000082050: 94040650 bl ffffffc000183990 &lt;__sanitizer_cov_trace_pc&gt;
+ffffffc000082078: 94040646 bl ffffffc000183990 &lt;__sanitizer_cov_trace_pc&gt;
+ffffffc000082080: 94040644 bl ffffffc000183990 &lt;__sanitizer_cov_trace_pc&gt;
+ffffffc0000820ac: 94040639 bl ffffffc000183990 &lt;__sanitizer_cov_trace_pc&gt;
+</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>
generated by cgit v1.2.3 (git 2.25.1) at 2024-07-02 11:39:29 +0000