diff options
Diffstat (limited to 'en/devices')
| -rw-r--r-- | en/devices/_toc-interfaces.yaml | 6 | ||||
| -rw-r--r-- | en/devices/_toc-tech.yaml | 2 | ||||
| -rw-r--r-- | en/devices/architecture/index.html | 10 | ||||
| -rw-r--r-- | en/devices/audio/debugging.html | 5 | ||||
| -rw-r--r-- | en/devices/bluetooth/ble_advertising.html | 258 | ||||
| -rw-r--r-- | en/devices/bluetooth/services.html | 463 | ||||
| -rw-r--r-- | en/devices/camera/camera3_requests_methods.html | 2 | ||||
| -rw-r--r-- | en/devices/input/migration-guide.html | 3 | ||||
| -rw-r--r-- | en/devices/tech/admin/testing-setup.html | 62 | ||||
| -rw-r--r-- | en/devices/tech/config/filesystem.html | 390 | ||||
| -rw-r--r-- | en/devices/tech/dalvik/images/jit-arch.png | bin | 31349 -> 19327 bytes | |||
| -rw-r--r-- | en/devices/tech/dalvik/images/jit-daemon.png | bin | 53542 -> 21919 bytes | |||
| -rw-r--r-- | en/devices/tech/dalvik/images/jit-profile-comp.png | bin | 41397 -> 18648 bytes | |||
| -rw-r--r-- | en/devices/tech/dalvik/images/jit-workflow.png | bin | 104054 -> 60140 bytes | |||
| -rw-r--r-- | en/devices/tech/dalvik/jit-compiler.html | 177 | ||||
| -rw-r--r-- | en/devices/tech/debug/index.html | 7 | ||||
| -rw-r--r-- | en/devices/tech/perf/low-ram.html | 2 |
17 files changed, 1180 insertions, 207 deletions
diff --git a/en/devices/_toc-interfaces.yaml b/en/devices/_toc-interfaces.yaml index 78759ac0..6c13a21c 100644 --- a/en/devices/_toc-interfaces.yaml +++ b/en/devices/_toc-interfaces.yaml @@ -205,6 +205,10 @@ toc: section: - title: Overview path: /devices/bluetooth + - title: Services + path: /devices/bluetooth/services + - title: BLE Advertising + path: /devices/bluetooth/ble_advertising - title: Verifying and Debugging path: /devices/bluetooth/verifying_debugging - title: HCI Requirements @@ -303,8 +307,6 @@ toc: path: /devices/input/keyboard-devices - title: Touch Devices path: /devices/input/touch-devices - - title: Diagnostics - path: /devices/input/diagnostics - title: Getevent path: /devices/input/getevent - title: Validate Keymaps diff --git a/en/devices/_toc-tech.yaml b/en/devices/_toc-tech.yaml index acbcf334..14c55a38 100644 --- a/en/devices/_toc-tech.yaml +++ b/en/devices/_toc-tech.yaml @@ -205,8 +205,6 @@ toc: path: /devices/tech/power/device - title: Power Values path: /devices/tech/power/values - - title: Battery Use - path: /devices/tech/power/batterystats - title: Settings Menu section: - title: Overview diff --git a/en/devices/architecture/index.html b/en/devices/architecture/index.html index a4a415e3..38f494a7 100644 --- a/en/devices/architecture/index.html +++ b/en/devices/architecture/index.html @@ -65,10 +65,12 @@ loaded by the Android system at the appropriate time. For details, see <h2 id="Linux-kernel">Linux kernel</h2> <p>Developing your device drivers is similar to developing a typical Linux device driver. Android uses a version of the Linux kernel with a few special -additions such as wake locks (a memory management system that is more aggressive -in preserving memory), the Binder IPC driver, and other features important for a -mobile embedded platform. These additions are primarily for system functionality -and do not affect driver development.</p> +additions such as Low Memory Killer (a memory management system that is more +aggressive in preserving memory), wake locks (a +<a href="https://developer.android.com/reference/android/os/PowerManager.html"> +<code>PowerManager</code></a> system service), the Binder IPC driver, and +other features important for a mobile embedded platform. These additions are +primarily for system functionality and do not affect driver development.</p> <p>You can use any version of the kernel as long as it supports the required features (such as the binder driver). However, we recommend using the latest diff --git a/en/devices/audio/debugging.html b/en/devices/audio/debugging.html index 67e23d03..c2b7cd73 100644 --- a/en/devices/audio/debugging.html +++ b/en/devices/audio/debugging.html @@ -121,12 +121,13 @@ but you can get similar results using "4." <ol> <li>Run your audio test.</li> <li><code class="devsite-terminal">adb shell dumpsys media.audio_flinger</code></li> -<li>Look for a line in dumpsys output such as this:<br /> +<li>Look for a line in <code>dumpsys</code> output such as this:<br /> <code>tee copied to /data/misc/media/20131010101147_2.wav</code> <br />This is a PCM .wav file. </li> <li>Then <code>adb pull</code> any <code>/data/misc/media/*.wav</code> files of interest; -note that track-specific dump filenames do not appear in the dumpsys output, + note that track-specific dump filenames do not appear in the + <code>dumpsys</code> output, but are still saved to <code>/data/misc/media</code> upon track closure. </li> <li>Review the dump files for privacy concerns before sharing with others.</li> diff --git a/en/devices/bluetooth/ble_advertising.html b/en/devices/bluetooth/ble_advertising.html new file mode 100644 index 00000000..6fc93f8c --- /dev/null +++ b/en/devices/bluetooth/ble_advertising.html @@ -0,0 +1,258 @@ +<html devsite> + <head> + <title>Bluetooth Low Energy Advertising</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> + Bluetooth Low Energy (BLE) conserves power by remaining in sleep mode + most of the time. It wakes up only to make advertisements and short + connections, so advertisements affect both power consumption and + data transfer bandwidth. + </p> + + <h2 id="bluetooth-5-advertising-extension">Bluetooth 5 advertising extension</h2> + + <p> + Android 8.0 supports Bluetooth 5, which provides broadcasting + improvements and flexible data advertisement for BLE. Bluetooth 5 supports BLE Physical Layers (PHYs) that retain the + reduced power consumption of Bluetooth 4.2 and let users choose + increased bandwidth or range. More information can be found in the + <a href="https://www.bluetooth.com/specifications/adopted-specifications"> + Bluetooth 5 Core Specifications</a>. + </p> + + <h3 id="implementation">Implementation</h3> + + <p> + New Bluetooth 5 features are automatically available for devices + running Android 8.0 with compatible Bluetooth controllers. Use these + <code><a href="https://developer.android.com/reference/android/bluetooth/BluetoothAdapter.html"> + BluetoothAdapter</a></code> + methods to check if a device supports Bluetooth 5 features: + </p> + + <ul> + <li><code>isLe2MPhySupported()</code></li> + <li><code>isLeCodedPhySupported()</code></li> + <li><code>isLeExtendedAdvertisingSupported()</code></li> + <li><code>isLePeriodicAdvertisingSupported()</code></li> + </ul> + + <p> + To disable the advertising features, work with the Bluetooth chip + vendor to disable chip-set support. + </p> + + <p> + The Bluetooth PHYs are exclusive of one another, and the behavior of + each PHY is predefined by the Bluetooth SIG. By default, Android 8.0 + uses Bluetooth LE 1M PHY, from Bluetooth 4.2. The + <code><a href="https://developer.android.com/reference/android/bluetooth/le/package-summary.html"> + android.bluetooth.le</a></code> + package exposes the Bluetooth 5 advertising features through these + APIs: + </p> + + <ul> + <li><code>AdvertisingSet</code></li> + <li><code>AdvertisingSetCallback</code></li> + <li><code>AdvertisingSetParameters</code></li> + <li><code>PeriodicAdvertisingParameters</code></li> + </ul> + + <p> + Create an <code><a href="https://developer.android.com/reference/android/bluetooth/le/AdvertisingSet.html"> + AdvertisingSet</a></code> + to modify Bluetooth advertisement settings by using the <code><a + href="https://developer.android.com/reference/android/bluetooth/le/BluetoothLeAdvertiser.html#startAdvertisingSet(android.bluetooth.le.AdvertisingSetParameters, + android.bluetooth.le.AdvertiseData, android.bluetooth.le.AdvertiseData, + android.bluetooth.le.PeriodicAdvertisingParameters, + android.bluetooth.le.AdvertiseData, + android.bluetooth.le.AdvertisingSetCallback)"> + startAdvertisingSet()</a></code> method in <code><a + href="https://developer.android.com/reference/android/bluetooth/le/BluetoothLeAdvertiser.html"> + android.bluetooth.le.BluetoothLeAdvertiser</a></code>. Even if + support for Bluetooth 5 or its advertising features is disabled, the + API features can also apply to LE 1M PHY. + </p> + + <h4 id="examples">Examples</h4> + + <p> + This example app uses Bluetooth LE 1M PHY for advertising: + </p> + +<pre class="prettyprint"> + // Start legacy advertising. Works for devices with 5.x controllers, + and devices that support multi-advertising. + + void example1() { + BluetoothLeAdvertiser advertiser = + BluetoothAdapter.getDefaultAdapter().getBluetoothLeAdvertiser(); + + AdvertisingSetParameters parameters = (new AdvertisingSetParameters.Builder()) + .setLegacyMode(true) // True by default, but set here as a reminder. + .setConnectable(true) + .setInterval(AdvertisingSetParameters.INTERVAL_HIGH) + .setTxPowerLevel(AdvertisingSetParameters.TX_POWER_MEDIUM) + .build(); + + AdvertiseData data = (new AdvertiseData.Builder()).setIncludeDeviceName(true).build(); + + AdvertisingSetCallback callback = new AdvertisingSetCallback() { + @Override + public void onAdvertisingSetStarted(AdvertisingSet advertisingSet, int txPower, int status) { + Log.i(LOG_TAG, "onAdvertisingSetStarted(): txPower:" + txPower + " , status: " + + status); + currentAdvertisingSet = advertisingSet; + } + + @Override + public void onAdvertisingDataSet(AdvertisingSet advertisingSet, int status) { + Log.i(LOG_TAG, "onAdvertisingDataSet() :status:" + status); + } + + @Override + public void onScanResponseDataSet(AdvertisingSet advertisingSet, int status) { + Log.i(LOG_TAG, "onScanResponseDataSet(): status:" + status); + } + + @Override + public void onAdvertisingSetStopped(AdvertisingSet advertisingSet) { + Log.i(LOG_TAG, "onAdvertisingSetStopped():"); + } + }; + + advertiser.startAdvertisingSet(parameters, data, null, null, null, callback); + + // After onAdvertisingSetStarted callback is called, you can modify the + // advertising data and scan response data: + currentAdvertisingSet.setAdvertisingData(new AdvertiseData.Builder(). + setIncludeDeviceName(true).setIncludeTxPowerLevel(true).build()); + // Wait for onAdvertisingDataSet callback... + currentAdvertisingSet.setScanResponseData(new + AdvertiseData.Builder().addServiceUuid(new ParcelUuid(UUID.randomUUID())).build()); + // Wait for onScanResponseDataSet callback... + + // When done with the advertising: + advertiser.stopAdvertisingSet(callback); +}</pre> + + <p> + This example app uses the BLE 2M PHY for advertising. The app first + checks that the device supports the features being used. If the + advertising features are supported, then the app configures BLE 2M + PHY as the primary PHY. While 2M PHY is active, advertisement does + not support Bluetooth 4.x controllers, so <code>setLegacyMode</code> + is set to <code>false</code>. This example modifies parameters while + advertising and also pauses the advertisement. + </p> + +<pre class="prettyprint">void example2() { + BluetoothAdapter adapter = BluetoothAdapter.getDefaultAdapter(); + BluetoothLeAdvertiser advertiser = + BluetoothAdapter.getDefaultAdapter().getBluetoothLeAdvertiser(); + + // Check if all features are supported + if (!adapter.isLe2MPhySupported()) { + Log.e(LOG_TAG, "2M PHY not supported!"); + return; + } + if (!adapter.isLeExtendedAdvertisingSupported()) { + Log.e(LOG_TAG, "LE Extended Advertising not supported!"); + return; + } + + int maxDataLength = adapter.getLeMaximumAdvertisingDataLength(); + + AdvertisingSetParameters.Builder parameters = (new AdvertisingSetParameters.Builder()) + .setLegacyMode(false) + .setInterval(AdvertisingSetParameters.INTERVAL_HIGH) + .setTxPowerLevel(AdvertisingSetParameters.TX_POWER_MEDIUM) + .setPrimaryPhy(BluetoothDevice.PHY_LE_2M) + .setSecondaryPhy(BluetoothDevice.PHY_LE_2M); + + AdvertiseData data = (new AdvertiseData.Builder()).addServiceData(new + ParcelUuid(UUID.randomUUID()), + "You should be able to fit large amounts of data up to maxDataLength. This goes + up to 1650 bytes. For legacy advertising this would not + work".getBytes()).build(); + + AdvertisingSetCallback callback = new AdvertisingSetCallback() { + @Override + public void onAdvertisingSetStarted(AdvertisingSet advertisingSet, int txPower, int status) { + Log.i(LOG_TAG, "onAdvertisingSetStarted(): txPower:" + txPower + " , status: " + + status); + currentAdvertisingSet = advertisingSet; + } + + @Override + public void onAdvertisingSetStopped(AdvertisingSet advertisingSet) { + Log.i(LOG_TAG, "onAdvertisingSetStopped():"); + } + }; + + advertiser.startAdvertisingSet(parameters.build(), data, null, null, null, callback); + + // After the set starts, you can modify the data and parameters of currentAdvertisingSet. + currentAdvertisingSet.setAdvertisingData((new + AdvertiseData.Builder()).addServiceData(new ParcelUuid(UUID.randomUUID()), + "Without disabling the advertiser first, you can set the data, if new data is + less than 251 bytes long.".getBytes()).build()); + + // Wait for onAdvertisingDataSet callback... + + // Can also stop and restart the advertising + currentAdvertisingSet.enableAdvertising(false, 0, 0); + // Wait for onAdvertisingEnabled callback... + currentAdvertisingSet.enableAdvertising(true, 0, 0); + // Wait for onAdvertisingEnabled callback... + + // Or modify the parameters - i.e. lower the tx power + currentAdvertisingSet.enableAdvertising(false, 0, 0); + // Wait for onAdvertisingEnabled callback... + currentAdvertisingSet.setAdvertisingParameters(parameters.setTxPowerLevel + (AdvertisingSetParameters.TX_POWER_LOW).build()); + // Wait for onAdvertisingParametersUpdated callback... + currentAdvertisingSet.enableAdvertising(true, 0, 0); + // Wait for onAdvertisingEnabled callback... + + // When done with the advertising: + advertiser.stopAdvertisingSet(callback); +}</pre> + + <h3 id="verification">Verification</h3> + + <p> Run applicable <a + href="https://www.bluetooth.com/develop-with-bluetooth/test-tools"> + Bluetooth product tests</a> to verify device compatibility with + Bluetooth 5. + </p> + + <p> + AOSP contains the Android Comms Test Suite (ACTS), which includes + tests for Bluetooth 5. The ACTS tests for Bluetooth 5 can be found + in <code><a + href="https://android.googlesource.com/platform/tools/test/connectivity/+/master/acts/tests/google/ble/bt5/"> + tools/test/connectivity/acts/tests/google/ble/bt5</a></code>. + </p> + </body> +</html> diff --git a/en/devices/bluetooth/services.html b/en/devices/bluetooth/services.html new file mode 100644 index 00000000..59a76ca2 --- /dev/null +++ b/en/devices/bluetooth/services.html @@ -0,0 +1,463 @@ +<html devsite> + <head> + <title>Bluetooth Services</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> + Over Bluetooth, devices can transmit data that can be used for + interactive services such as audio, messaging, and telephony. The + Bluetooth profiles used for different services can be found in + <code><a href="https://android.googlesource.com/platform/hardware/libhardware/+/master/include/hardware"> + hardware/libhardware/include/hardware/</a></code>. + </p> + + <h2 id="audio">Audio</h2> + + <aside class="note"><strong>Note</strong>: Currently only + Classic Bluetooth supports any type of audio streaming. + </aside> + + <p> + A Bluetooth connection lets users stream audio on Bluetooth-enabled + devices. For most audio use cases, the Android device is the source, + and the rendering device, such as a speaker or a headset, is the sink. + </p> + + <h3 id="absolute-volume-control">Absolute volume control</h3> + + <p> + In Android 6.0 and later, the Android Bluetooth stack lets a + source set an absolute volume, giving users accurate control over + audio volume. The source device sends un-attenuated audio and volume + information to the sink. The sink then amplifies the audio according + to the volume information, so users hear accurate playback volume. + </p> + + <p> + The source device can also register volume notifications. When + volume changes are made with controls on the sink, the sink sends a + notification to the source. This lets the source accurately display + volume information on a user interface. + </p> + + <p> + Absolute volume control is on by default. To disable absolute + volume control, users can go to <strong>Settings</strong> > + <strong>System</strong> > <strong>Developer options</strong> + and select the toggle for <strong>Disable absolute volume</strong>. + </p> + + <h3 id="advanced-audio-codecs">Advanced audio codecs</h3> + + <p> + In Android 8.0, devices that use the Advanced Audio Distribution + Profile (A2DP) can support additional audio codecs. The Bluetooth + stack supports audio codec negotiation for when devices connect to + a remote audio sink. This negotiation selects the best codec + supported by both the sender and the sink to provide high-quality + audio. After selection, all audio is routed through the selected + encoder and then sent to the sink. + </p> + + <h4 id="implementation">Implementation</h4> + + <p> + Devices running Android 8.0 that support A2DP automatically + gain the additional codec support. Device manufacturers may need + to obtain separate licenses and binary blobs for some + proprietary audio codecs. In addition to SBC, Android 8.0 + supports the following codecs: + </p> + + <ul> + <li>AAC</li> + <li>aptX</li> + <li>aptX HD</li> + <li>LDAC</li> + </ul> + + <p> + Device manufacturers can choose which codecs their devices + attempt to use first. Set the codec priorities by changing the + following values in <code><a href="https://android.googlesource.com/platform/packages/apps/Bluetooth/+/master/res/values/config.xml"> + res/values/config.xml</a></code>: + </p> + +<pre class="prettyprint"> + <!-- Configuring priorities of A2DP source codecs. Larger value means + higher priority. Value -1 means the codec is disabled. + Value 0 is reserved and should not be used here. Enabled codecs + should have priorities in the interval [1, 999999], and each + priority value should be unique. --> + <integer name="a2dp_source_codec_priority_sbc">1001</integer> + <integer name="a2dp_source_codec_priority_aac">2001</integer> + <integer name="a2dp_source_codec_priority_aptx">3001</integer> + <integer name="a2dp_source_codec_priority_aptx_hd">4001</integer> + <integer name="a2dp_source_codec_priority_ldac">5001</integer> + </pre> + + <h4 id="ldac-certification">LDAC certification</h4> + + <p> + The Android Open Source Project includes Sony's LDAC codec, so a + separate license or blob is not needed for it. To integrate the + LDAC codec into your device, register with Sony and follow the + <a href="https://www.sony.net/Products/LDAC/aosp/"> + LDAC certification process</a>. + </p> + + <p> + The LDAC certification website has documentation about LDAC, + such as specification and operation handbooks. The LDAC site also + provides validation and interoperability tests for mobile and + tablet devices. Send passing test results to Sony to complete LDAC + certification. + </p> + + <h4 id="ui-features">UI features</h4> + + <p> + Along with additional codec support, Android 8.0 provides a + user-facing setting to disable high-definition (HD) Bluetooth + audio codecs. + </p> + + <ol> + <li>Navigate to <strong>Settings</strong> > + <strong>Connected devices</strong> > + <strong>Bluetooth</strong>.</li> + <li>Tap on the gear icon next to the sink you want to disable codecs for.</li> + <li>Uncheck the <strong>HD Audio</strong> checkbox.</li> + </ol> + + <p> + Device manufacturers that customize Settings should implement a + way for users to disable HD codecs. + </p> + + <h2 id="messaging">Messaging</h2> + + <p> + Messaging over Bluetooth lets users read, browse, and compose SMS + messages from a remote device. This capability is often used when + connecting a phone to an in-vehicle infotainment system. + </p> + + <aside class="note"><strong>Note</strong>: Bluetooth messaging services + currently only support SMS. Email and instant messages are not + supported. + </aside> + + <h2 id="telephony">Telephony</h2> + + <p> + Bluetooth telephony services lets users stream calls and sync + contacts from a phone to another Bluetooth device. These features are + often used for hands-free calls when driving. + </p> + + <p> + In Android 8.0, Bluetooth supports in-band ringtone. When a phone + connected over Bluetooth receives an incoming call, the ringtone will + play on the sink. Enable in-band ringtone in <strong>Settings</strong> + > <strong>System</strong> > <strong>Developer options</strong> by + selecting the toggle for <strong>Enable in-band ringing</strong>. + </p> + + <h2>Bluetooth features</h2> + <p> To implement the Bluetooth services, the Bluetooth stack supports a + variety of profiles and features. + </p> + + <h3 id="bluetooth-profiles">Bluetooth profiles</h3> + + <p> + These profiles are available for Bluetooth: + </p> + + <table> + <tr> + <th colspan="2" >Feature</th> + <th colspan="5" >Android version</th> + </tr> + <tr> + <th>Name</th> + <th>Description</th> + <th>6.0</th> + <th>7.0</th> + <th>7.1</th> + <th>7.1.2</th> + <th>8.0</th> + </tr> + <tr> + <td><strong>SAP</strong></td> + <td>SIM Access Profile</td> + <td>1.1</td> + <td>1.1</td> + <td>1.1</td> + <td>1.1</td> + <td>1.1</td> + </tr> + <tr> + <td><strong>MAP</strong></td> + <td>Message Access Profile for SMS</td> + <td>1.2</td> + <td>1.2</td> + <td>1.2</td> + <td>1.2</td> + <td>1.2</td> + </tr> + <tr> + <td><strong>OPP</strong></td> + <td>Object Push Profile</td> + <td>1.1</td> + <td>1.1</td> + <td>1.1</td> + <td>1.1</td> + <td>1.2</td> + </tr> + <tr> + <td><strong>OBEX over L2CAP</strong></td> + <td>OBject EXchange over Logical Link Control and Adaptation + Protocol</td> + <td>Yes</td> + <td>Yes</td> + <td>Yes</td> + <td>Yes</td> + <td>Yes</td> + </tr> + <tr> + <td><strong>HFP Audio Gateway</strong></td> + <td>Hands-Free Profile</td> + <td>1.6</td> + <td>1.6</td> + <td>1.7</td> + <td>1.7</td> + <td>1.7</td> + </tr> + <tr> + <td><strong>HSP</strong></td> + <td>Headset Profile</td> + <td>1.2</td> + <td>1.2</td> + <td>1.2</td> + <td>1.2</td> + <td>1.2</td> + </tr> + <tr> + <td><strong>A2DP</strong></td> + <td>Advanced Audio Distribution Profile</td> + <td>1.2</td> + <td>1.2</td> + <td>1.2</td> + <td>1.2</td> + <td>1.2</td> + </tr> + <tr> + <td><strong>AVRCP</strong></td> + <td>Audio/Video Remote Control Profile</td> + <td>1.3</td> + <td>1.3</td> + <td>1.3</td> + <td>1.3</td> + <td>1.4</td> + </tr> + <tr> + <td><strong>HID</strong></td> + <td>Human Interface Device Profile</td> + <td>1.0</td> + <td>1.0</td> + <td>1.0</td> + <td>1.0</td> + <td>1.0</td> + </tr> + <tr> + <td><strong>PBAP</strong></td> + <td>Phone Book Access Profile</td> + <td>1.1.1</td> + <td>1.1.1</td> + <td>1.1.1</td> + <td>1.1.1</td> + <td>1.2</td> + </tr> + <tr> + <td><strong>HDP</strong></td> + <td>Health Device Profile</td> + <td>1.0</td> + <td>1.0</td> + <td>1.1</td> + <td>1.1</td> + <td>1.1</td> + </tr> + <tr> + <td><strong>SPP</strong></td> + <td>Serial Port Profile</td> + <td>1.2</td> + <td>1.2</td> + <td>1.2</td> + <td>1.2</td> + <td>1.2</td> + </tr> + <tr> + <td><strong>PAN / BNEP</strong></td> + <td>Personal Area Networking Profile / Bluetooth Network + Encapsulation Protocol</td> + <td>1.0</td> + <td>1.0</td> + <td>1.0</td> + <td>1.0</td> + <td>1.0</td> + </tr> + <tr> + <td><strong>DIP</strong></td> + <td>Device ID Profile</td> + <td>1.3</td> + <td>1.3</td> + <td>1.3</td> + <td>1.3</td> + <td>1.3</td> + </tr> + <tr> + <td><strong>HOGP 1.0</strong></td> + <td>HID over GATT</td> + <td>Yes</td> + <td>Yes</td> + <td>Yes</td> + <td>Yes</td> + <td>Yes</td> + </tr> + <tr> + <td><strong>HD Audio</strong><sup id="fnref1"><a href="#fn1" + rel="footnote">1</a></sup></td> + <td>See "Advanced audio codecs" above</td> + <td>No</td> + <td>No</td> + <td>No</td> + <td>No</td> + <td>Yes</td> + </tr> + </table> + + <p> + <sup id="fn1">1</sup> Implementing HD Audio depends on device + capabilities, both on the source and the sink. + </p> + + <h3 id="bluetooth-low-energy-features">Bluetooth Low Energy features</h3> + + <p> + These features are available for BLE: + </p> + + <table> + <tr> + <th>Feature</th> + <th colspan="5" >Android version</th> + </tr> + <tr> + <th>Name</th> + <th>6.0</th> + <th>7.0</th> + <th>7.1</th> + <th>7.1.2</th> + <th>8.0</th> + </tr> + <tr> + <td><strong>BR/EDR secure connections</strong></td> + <td>4.1</td> + <td>4.1</td> + <td>4.1</td> + <td>4.1</td> + <td>5.0</td> + </tr> + <tr> + <td><strong>LE Privacy</strong></td> + <td>4.2</td> + <td>4.2</td> + <td>4.2</td> + <td>4.2</td> + <td>5.0</td> + </tr> + <tr> + <td><strong>LE secure connections</strong></td> + <td>4.2</td> + <td>4.2</td> + <td>4.2</td> + <td>4.2</td> + <td>5.0</td> + </tr> + <tr> + <td><strong>Data Packet Extensions</strong></td> + <td>4.2</td> + <td>4.2</td> + <td>4.2</td> + <td>4.2</td> + <td>5.0</td> + </tr> + <tr> + <td><strong>32-bit UUIDs</strong></td> + <td>Yes</td> + <td>Yes</td> + <td>Yes</td> + <td>Yes</td> + <td>Yes</td> + </tr> + <tr> + <td><strong>Dual Mode LE Central/Peripheral</strong></td> + <td>Yes</td> + <td>Yes</td> + <td>Yes</td> + <td>Yes</td> + <td>Yes</td> + </tr> + <tr> + <td><strong>LE Peripheral Mode</strong></td> + <td>Yes</td> + <td>Yes</td> + <td>Yes</td> + <td>Yes</td> + <td>Yes</td> + </tr> + <tr> + <td><strong>Google HCI Requirements</strong></td> + <td>Yes</td> + <td>Yes</td> + <td>Yes</td> + <td>Yes</td> + <td>Yes</td> + </tr> + <tr> + <td><strong>LE Connection-Oriented Channels</strong></td> + <td>No</td> + <td>No</td> + <td>No</td> + <td>No</td> + <td>Yes<sup id="fnref2"><a href="#fn2" rel="footnote">2</a></sup> + </td> + </tr> + </table> + + <p> + <sup id="fn2">2</sup> Implementing LE Connection-Oriented Channels + depends on device capabilities, both on the source and the sink. + </p> + </body> +</html> diff --git a/en/devices/camera/camera3_requests_methods.html b/en/devices/camera/camera3_requests_methods.html index edd4dfe5..6fd429d4 100644 --- a/en/devices/camera/camera3_requests_methods.html +++ b/en/devices/camera/camera3_requests_methods.html @@ -85,7 +85,7 @@ returned by the HAL through the <code>process_capture_result()</code> call. This <h3 id="dump">dump</h3> <p>Print out debugging state for the camera device. This will be called by the framework when the camera service is asked for a debug dump, which happens when - using the dumpsys tool, or when capturing a bugreport. The passed-in file + using the <code>dumpsys</code> tool, or when capturing a bugreport. The passed-in file descriptor can be used to write debugging text using <code>dprintf()</code> or <code>write()</code>. The text should be in ASCII encoding only.</p> <h3 id="flush">flush</h3> diff --git a/en/devices/input/migration-guide.html b/en/devices/input/migration-guide.html index 6f50f004..9ca346b8 100644 --- a/en/devices/input/migration-guide.html +++ b/en/devices/input/migration-guide.html @@ -45,7 +45,8 @@ function input devices. These files should simple contain a line to set the keyboard type to <code>SPECIAL_FUNCTION</code>.</p> <p>A good way to ensure that all built-in input devices are appropriately configured is to run <a - href="https://developer.android.com/studio/command-line/dumpsys.html">Dumpsys</a> + href="https://developer.android.com/studio/command-line/dumpsys.html"> + <code>dumpsys</code></a> and look for devices that are inappropriately using <code>Generic.kcm</code>.</p> <h2 id="migrating-to-android-honeycomb-32">Migrating to Android Honeycomb 3.2</h2> <p>In Honeycomb 3.2, we added support for joysticks and extended the key layout file diff --git a/en/devices/tech/admin/testing-setup.html b/en/devices/tech/admin/testing-setup.html index dc89c1a4..131ade86 100644 --- a/en/devices/tech/admin/testing-setup.html +++ b/en/devices/tech/admin/testing-setup.html @@ -27,45 +27,39 @@ following essential elements:</p> <ul> - <li>Profile owner (as described in - <a href="https://developer.android.com/training/enterprise/app-compatibility.html">Ensuring - Compatibility with Managed Profiles</a>)</li> - <li>Device owner</li> - </ul> +<li>Profile owner (as described in +<a href="https://developer.android.com/training/enterprise/app-compatibility.html" class="external">Ensuring +Compatibility with Managed Profiles</a>)</li> +<li>Device owner</li> +</ul> <p>For a complete list of requirements, see <a href="/devices/tech/admin/implement.html">Implementing Device -Administration</a>.</p> - -<p>To test device administration features, device owners can use the TestDPC -application (described below); consider also working directly with other -enterprise mobility management (EMM) providers.</p> +Administration</a>. To test device administration features, device owners can +use the TestDPC application described below.</p> <h2 id=set_up_the_device_owner_for_testing>Set up device owner for testing</h2> <p>Use the following instructions to set up a device owner testing environment.</p> <ol> - <li>Set up the device: - <ol> - <li style="list-style-type: lower-alpha">Factory reset the target device.</li> - <li style="list-style-type: lower-alpha">Ensure you do not add any user accounts - (e.g. those used to log into online services) to the device. - This can be checked in <em>Settings->Accounts</em>.</li> - </ol></li> - <li>Set up the testing application using one of the following methods: +<li>Factory reset the target device.</li> +<li>Ensure the device does not contain any user accounts (e.g. those used to log +into online services). To verify, check <em>Settings > Accounts</em>.</li> +<li>Set up the testing application using one of the following methods: <ul> - <li><a href="https://play.google.com/store/apps/details?id=com.afwsamples.testdpc&hl=en">Download + <li><a href="https://play.google.com/store/apps/details?id=com.afwsamples.testdpc&hl=en" class="external">Download the TestDPC application</a> (available from Google Play).</li> - <li><a href="https://github.com/googlesamples/android-testdpc/">Build + <li><a href="https://github.com/googlesamples/android-testdpc/" class="external">Build the TestDPC application</a> (available from github.com).</li> </ul> - </li> - <li>Set the TestDPC app as the device owner using the following command:<br> +</li> +<li>Set the TestDPC app as the device owner using the following command: <pre class="devsite-terminal devsite-click-to-copy"> adb shell dpm set-device-owner "com.afwsamples.testdpc/.DeviceAdminReceiver" </pre> - </li> - <li>Go through device owner setup on the device (encrypt, select Wi-Fi, etc.)</li> +</li> +<li>Go through device owner setup on the device (encrypt, select Wi-Fi, etc.). +</li> </ol> <h2 id=verify_the_device_owner_was_correctly_setup>Verify device owner setup</h2> @@ -80,22 +74,22 @@ the Android for Work (AfW) Test Harness. For details, see Provisioning</a>.</p> <h2 id="troubleshooting">Bug reports and logs</h2> -<p>In Android 7.0, device owner Device Policy Client (DPCs) can get bug reports -and view logs for enterprise processes on a managed device.</p> - -<p>To trigger a bug report (i.e., the equivalent data collected by <code>adb -bugreport</code> containing dumpsys, dumpstate, and logcat data), use -<code>DevicePolicyController.requestBugReport</code>. After the bug report is -collected, the user is prompted to give consent to send the bug report data. -Results are received by +<p>As of Android 7.0, device owner Device Policy Client (DPCs) can get bug +reports and view logs for enterprise processes on a managed device.</p> + +<p>To trigger a bug report (i.e., the equivalent data collected by +<code>adb bugreport</code> containing <code>dumpsys</code>, dumpstate, and +logcat data), use <code>DevicePolicyController.requestBugReport</code>. After +the bug report is collected, the user is prompted to give consent to send the +bug report data. Results are received by <code>DeviceAdminReceiver.onBugreport[Failed|Shared|SharingDeclined]</code>. For details on bug report contents, see -<a href="/source/read-bug-reports.html">Reading Bug Reports</a>. +<a href="/source/read-bug-reports.html">Reading Bug Reports</a>.</p> <p>In addition, device owner DPCs can also collect logs related to actions a user has taken on a managed device. Enterprise process logging is required for all devices that report device_admin and enabled by a new log security buffer -readable only by the system server (i.e., <code>adb logcat -b security</code> +readable only by the system server (i.e., <code>$ adb logcat -b security</code> cannot read the buffer). ActivityManager service and Keyguard components log the following events to the security buffer:</p> diff --git a/en/devices/tech/config/filesystem.html b/en/devices/tech/config/filesystem.html index 98a72baa..c1bf33d5 100644 --- a/en/devices/tech/config/filesystem.html +++ b/en/devices/tech/config/filesystem.html @@ -21,31 +21,306 @@ limitations under the License. --> +<p>When adding file system objects and services to the build, such items +frequently need separate unique IDs, known as Android IDs (AIDs). Currently, +many resources such as files and services use core, Android-defined AIDs +unnecessarily; in many cases you can use OEM-defined AIDs instead.</p> -<p>Earlier versions of Android used a system configuration file that was -not extensible, preventing device manufacturers from adding named binaries to -specify Discretionary Access Controls (DAC) of ownership, access mode, or -executable capabilities. This limitation occurred as a result of support for -Linux kernels 3.14 and higher in which wake lock is enabled via the -<code>CAP_SUSPEND_BLOCK</code> capability; partner-supplied GPS daemons were -required to hold this wake lock (and thus have this capability set in the file -system).</p> - -<p>As of Android 6.0, <code>fs_config</code> and associated structure definitions -(<code>system/core/include/private/android_filesystem_config.h</code>) are now -located in <code>system/core/libcutils/fs_config.c</code> where they can be -updated or overridden by binary files installed in -<code>/system/etc/fs_config_dirs</code> and -<code>/system/etc/fs_config_files</code>. For clarity, Android uses separate -matching and parsing rules for directories and files (which can use additional -glob expressions) and handles directories and files in two different tables. -Structure definitions in <code>system/core/libcutils/fs_config.c</code> not only -allow runtime reading of directories and files, but the host may use the same -files during build time to construct filesystem images as +<p>In earlier versions of Android, extending the AIDs mechanism used a +device-specific <code>android_filesystem_config.h</code> file to specify the +filesystem capabilities and/or custom OEM AIDs. However, this system was +unintuitive as it did not support using nice names for OEM AIDs, requiring you +to specify the raw numeric for user and group fields without a way to associate +a friendly name with the numeric AID.</p> + +<p>Android 8.0 and higher includes a new AIDs mechanism for extending filesystem +capabilities. This new method has support for the following:</p> +<ul> +<li>Multiple source locations for configuration files (enables extensible build +configurations).</li> +<li>Build-time sanity checking of OEM AID values.</li> +<li>Generation of a custom OEM AID header that can be used in source files as +needed.</li> +<li>Association of a friendly name with the actual OEM AID value. Supports +non-numeric string arguments for user and group, i.e. "foo" instead of +"2901".</li> +</ul> + +<p>Additional improvements include the removal of the <code>android_ids[]</code> +array from <code>system/core/include/private/android_filesystem_config.h</code>. +This array now exists in Bionic as a fully private generated array, with +accessors via <code>getpwnam()</code> and <code>getgrnam()</code>. (This has the +side effect of producing stable binaries as core AIDs are modified.) For tooling +and a README file with more details, refer to +<code>build/make/tools/fs_config</code>.</p> + +<aside class="note"><strong>Note:</strong> While you can still use the +<a href="#older">filesystem override method from previous Android releases</a>, +you cannot use it simultaneously with the new AIDs mechanism. Using the new +mechanism whenever possible is recommended.</aside> + +<h2 id="adding-android-ids-aids">Adding Android IDs (AIDs)</h2> +<p>Android 8.0 removes the <code>android_ids[]</code> array from the Android +Open Source Project (AOSP). All AID-friendly names are instead generated from +the <code>system/core/include/private/android_filesystem_config.h</code> header +file when generating the Bionic <code>android_ids[]</code> array. Any +<code>define</code> matching <code>AID_*</code> is picked up by the tooling and +<strong>*</strong> becomes the lowercase name.</p> + +<p>For example, in <code>private/android_filesystem_config.h</code>:</p> + +<pre class="prettyprint">#define AID_SYSTEM 1000</pre> + +<p>Becomes:</p> +<ul> +<li>Friendly name: system</li> +<li>uid: 1000</li> +<li>gid: 1000</li> +</ul> + +<p>To add a new AOSP core AID, simply add the <code>#define</code> to the +<code>android_filesystem_config.h</code> header file. The AID will be generated +at build and made available to interfaces that use user and group arguments. The +tooling validates the new AID is not within the APP or OEM ranges; it also +respects changes to those ranges and should automatically reconfigure on changes +or new OEM-reserved ranges.</p> + +<h2 id="configuring-aids">Configuring AIDs</h2> +<p> +To enable the new AIDs mechanism, set <code>TARGET_FS_CONFIG_GEN</code> in the +<code>BoardConfig.mk</code> file. This variable holds a list of configuration +files, enabling you to append files as needed.</p> + +<aside class="caution"><strong>Caution:</strong> Don't use +<code>TARGET_FS_CONFIG_GEN</code> with the +older <code>TARGET_ANDROID_FILESYSTEM_CONFIG_H</code> method from older Android +releases! You will get an error.</aside> + +<p>By convention, configuration files use the name <code>config.fs</code>, but +in practice you can use any name. <code>config.fs</code> files are in the +<a href="https://docs.python.org/2/library/configparser.html" class="external">Python +ConfigParser ini format</a> and include a caps section (for configuring file +system capabilities) and an AIDs section (for configuring OEM-specific AIDs). +</p> + +<h3 id="configuring-the-caps-section">Configuring the caps section</h3> +<p>The caps section supports setting +<a href="http://man7.org/linux/man-pages/man7/capabilities.7.html" class="external">file +system capabilities</a> on filesystem objects within the build (the filesystem +itself must also support this functionality).</p> + +<p>Because running a stable service as root in Android causes a +<a href="/compatibility/cts/index.html">Compatibility Test Suite (CTS)</a> +failure, previous requirements for retaining a capability while running a +process or service involved setting up capabilities then using +<code>setuid</code>/<code>setgid</code> to a proper AID to run. With caps, you +can skip these requirements and have the kernel do it for you. When control is +handed to <code>main()</code>, your process already has the capabilities it +needs so your service can use a non-root user and group (this is the preferred +way for starting privileged services).</p> + +<p>The caps section uses the following syntax:</p> +<table> + <tr> + <th>Section</th> + <th>Value</th> + <th>Definition</th> + </tr> + <tr> + <td><code>[path]</code></td> + <td></td> + <td>The filesystem path to configure. A path ending in / is considered a dir, + else it's a file. + <br><br>It is an error to specify multiple sections with the same + <code>[path]</code> in different files. In Python versions <= 3.2, the same + file may contain sections that override the previous section; in Python 3.2, + it's set to strict mode.</td> + </tr> + <tr> + <td><code>mode</code></td> + <td>Octal file mode</td> + <td>A valid octal file mode of at least 3 digits. If 3 is specified, it is + prefixed with a 0, else mode is used as is.</td> + </tr> + <tr> + <td><code>user</code></td> + <td>AID_<user></td> + <td>Either the C <code>define</code> for a valid AID or the friendly name + (e.g. both <code>AID_RADIO</code> and <code>radio</code> are acceptable). To + define a custom AID, see <a href="#configuring-the-aid-section">Configuring + the AID section</a>.</td> + </tr> + <tr> + <td><code>group</code></td> + <td>AID_<group></td> + <td>Same as user.</td> + </tr> + <tr> + <td><code>caps</code></td> + <td>cap*</td> + <td>The name as declared in + <code>system/core/include/private/android_filesystem_capability.h</code> + without the leading <code>CAP_</code>. Mixed case allowed. Caps can also be + the raw: + <ul> + <li>binary (0b0101)</li> + <li>octal (0455)</li> + <li>int (42)</li> + <li>hex (0xFF)</li> + </ul> + Separate multiple caps using whitespaces.</td> + </tr> +</table> + +<p>For a usage example, see <a href="#using-file-system-capabilities">Using file +system capabilities</a>.</p> + +<h3 id="configuring-the-aid-section">Configuring the AID section</h3> +<p>The AID section contains OEM-specific AIDs and uses the following syntax:</p> + +<table> + <tr> + <th>Section</th> + <th>Value</th> + <th>Definition</th> + </tr> + <tr> + <td><code>[AID_<name>]</code></td> + <td></td> + <td>The <code><name></code> can contain characters in the set + uppercase, numbers, and underscores. The lowercase version is used as the + friendly name. The generated header file for code inclusion uses the exact + <code>AID_<name></code>. + <br><br>It is an error to specify multiple sections with the same + <code>AID_<name></code> (case insensitive with the same constraints as + <code>[path]</code>).</td> + </tr> + <tr> + <td><code>value</code></td> + <td><number></td> + <td>A valid C style number string (hex, octal, binary and decimal). + <br><br>It is an error to specify multiple sections with the same value option + <strong>or</strong> to specify a value that is outside of the inclusive OEM + ranges (defined in + <code>system/core/include/private/android_filesystem_config.h</code>): + <ul> + <li>AID_OEM_RESERVED_START(2900) - AID_OEM_RESERVED_END(2999)</li> + <li>AID_OEM_RESERVED_2_START(5000) - AID_OEM_RESERVED_2_END(5999)</li> + </ul> + </td> + </tr> +</table> + +<p>For usage examples, see <a href="#defining-an-oem-specific-aid">Defining an +OEM-specific AID</a> and <a href="#using-an-oem-specific-aid">Using an +OEM-specific AID</a>.</p> + +<h2 id="usage-examples">Usage examples</h2> +<p>The following examples detail how to define and use an OEM-specific AID and +how to enable filesystem capabilities.</p> + +<h3 id="defining-an-oem-specific-aid">Defining an OEM-specific AID</h3> +<p>To define an OEM-specific AID, create a <code>config.fs</code> file and set +the AID value. For example, in <code>device/x/y/config.fs</code>, set the +following:</p> + +<pre class="prettyprint"> +[AID_FOO] +value: 2900 +</pre> + +<p>After creating the file, set the <code>TARGET_FS_CONFIG_GEN</code> variable +and point to it in <code>BoardConfig.mk</code>. For example, in +<code>device/x/y/BoardConfig.mk</code>, set the following:</p> + +<pre class="prettyprint">TARGET_FS_CONFIG_GEN += device/x/y/config.fs</pre> + +<p>Your custom AID can now be consumed by the system at large on a new build. +</p> + +<h3 id="using-an-oem-specific-aid">Using an OEM-specific AID</h3> +<p>To access the <code>#define</code> value of your AID via C or C++ code, use +the autogenerated header file by adding to your module's <code>Android.mk</code> +and including the empty faux library. For example, in <code>Android.mk</code>, +add the following:</p> + +<pre class="prettyprint"> LOCAL_STATIC_LIBRARIES := liboemaids</pre> +<p>In your C code, <code>#include "generated_oem_aid.h"</code> and start using +the declared identifiers. For example, in <code>my_file.c</code>, add the +following: </p> + +<pre class="prettyprint"> +#include "generated_oem_aid.h" + +… + +If (ipc->uid == AID_FOO) { + // Do something +... +</pre> + +<p>In Android 8.0, you must continue to use <code>oem_####</code> with +<code>getpwnam</code> and similar functions, as well in places that handle +lookups via <code>getpwnam</code> (such as init scripts). For example, in +<code>some/init.rc</code>, use the following:</p> + +<pre class="prettyprint"> +service foo /vendor/bin/foo_service + user: oem_2900 + group: oem_2900 +</pre> + +<h3 id="using-file-system-capabilities">Using file system capabilities</h3> +<p>To enable filesystem capabilities, create a caps section in the +<code>config.fs</code> file. For example, in <code>device/x/y/config.fs</code>, +add the following section:</p> + +<pre class="prettyprint"> +[system/bin/foo_service] +mode: 0555 +user: AID_FOO +group: AID_SYSTEM +caps: SYS_ADMIN | SYS_NICE +</pre> + +<aside class="note"><strong>Note:</strong> The nice names <code>foo</code> and +<code>system</code> could be used here as well.</aside> + +<p>After creating the file, set the <code>TARGET_FS_CONFIG_GEN</code> to point +to it in <code>BoardConfig.mk</code>. For example, in +<code>device/x/y/BoardConfig.mk</code>, set the following:</p> + +<pre class="prettyprint">TARGET_FS_CONFIG_GEN += device/x/y/config.fs</pre> + +<p>When service <code>foo</code> is executed, it starts with capabilities +<code>CAP_SYS_ADMIN</code> and <code>CAP_SYS_NICE</code> without +<code>setuid</code> and <code>setgid</code> calls. In addition, the +<code>foo</code> service's SELinux policy no longer needs <code>setuid</code> +and <code>setgid</code>, so these capabilities can be removed from the SELinux +policy for <code>foo</code>.</p> + +<h2 id="older">Configuring overrides (Android 6.x-7.x)</h2> + +<p>Android 6.0 relocated <code>fs_config</code> and associated structure +definitions +(<code>system/core/include/private/android_filesystem_config.h</code>) to +<code>system/core/libcutils/fs_config.c</code> where they could be updated or +overridden by binary files installed in <code>/system/etc/fs_config_dirs</code> +and <code>/system/etc/fs_config_files</code>. Using separate matching and +parsing rules for directories and files (which could use additional glob +expressions) enabled Android to handle directories and files in two different +tables. Structure definitions in <code>system/core/libcutils/fs_config.c</code> +not only allowed runtime reading of directories and files, but the host could +use the same files during build time to construct filesystem images as <code>${OUT}/system/etc/fs_config_dirs</code> and <code>${OUT}/system/etc/fs_config_files</code>.</p> -<h2 id=gen-files>Generating override files</h2> +<p>While the override method of extending the filesystem has been superseded by +the modular config system introduced in Android 8.0, you can still use the old +method if desired. The following sections detail how to generate and include +override files and configure the filesystem.</p> + +<h3 id=older-generate>Generating override files</h3> <p>You can generate the aligned binary files <code>/system/etc/fs_config_dirs</code> and @@ -69,27 +344,23 @@ following structure initializations for directory and file symbols:</p> <p>When not using <code>android_device_dirs[]</code> and <code>android_device_files[]</code>, you can define <code>NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_DIRS</code> and <code>NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_FILES</code> (see the -<a href="#example">example</a> below).</p> - -<p>You can also specify the -override file using <code>TARGET_ANDROID_FILESYSTEM_CONFIG_H</code> in the board +<a href="#older-example">example</a> below). You can also specify the override file +using <code>TARGET_ANDROID_FILESYSTEM_CONFIG_H</code> in the board configuration, with an enforced basename of -<code>android_filesystem_config.h</code>. - -<h2 id=include-files>Including files</h2> - -<p><code>PRODUCT_PACKAGES</code> must include <code>fs_config_dirs</code> -and/or <code>fs_config_files</code> to install them to -<code>/system/etc/fs_config_dirs</code> and -<code>/system/etc/fs_config_files</code>, respectively.</p> +<code>android_filesystem_config.h</code>.</p> -<p>The build system searches for custom <code>android_filesystem_config.h</code> -in <code>$(TARGET_DEVICE_DIR)</code>, where <code>BoardConfig.mk</code> exists. +<h3 id=older-include>Including override files</h3> +<p>To include files, ensure that <code>PRODUCT_PACKAGES</code> includes +<code>fs_config_dirs</code> and/or <code>fs_config_files</code> so it can +install them to <code>/system/etc/fs_config_dirs</code> and +<code>/system/etc/fs_config_files</code>, respectively. The build system +searches for custom <code>android_filesystem_config.h</code> in +<code>$(TARGET_DEVICE_DIR)</code>, where <code>BoardConfig.mk</code> exists. If this file exists elsewhere, set board config variable <code>TARGET_ANDROID_FILESYSTEM_CONFIG_H</code> to point to that location.</p> -<h2 id=configuring>Configuring</h2> -<p>To configure the file system in Android 6.0 and higher:</p> +<h3 id=older-configure>Configuring the filesystem</h3> +<p>To configure the filesystem in Android 6.0 and higher:</p> <ol> <li>Create the <code>$(TARGET_DEVICE_DIR)/android_filesystem_config.h</code> @@ -99,28 +370,7 @@ file.</li> <code>$(TARGET_DEVICE_DIR)/device.mk</code>).</li> </ol> -<h2 id=migration-concerns>Migration concerns</h2> -<p>Migrating system configurations from Android 5.0 and earlier can be -disruptive. When planning such a migration, keep in mind that Android 6.0:</p> -<ul> -<li>Removes some includes, structures, and inline definitions.</li> -<li>Requires a reference to <code>libcutils</code> instead of running directly -from <code>system/core/include/private/android_filesystem_config.h</code>. -Device manufacturer private executables that depend on -<code>system/code/include/private_filesystem_config.h</code> for the file or -directory structures or <code>fs_config</code> must add <code>libcutils</code> -library dependencies.</li> -<li>Requires device manufacturer private branch copies of the -<code>system/core/include/private/android_filesystem_config.h</code> with extra -content on existing targets to move to -<code>device/<em>vendor</em>/<em>device</em>/android_filesystem_config.h</code>. -</li> -<li>As Android reserves the right to apply SELinux Mandatory Access Controls (MAC) -to configuration files on the target system, implementations that include -custom target executables using <code>fs_config()</code> must ensure access.</li> -</ul> - -<h2 id=example>Example</h2> +<h3 id=older-example>Override example</h3> <p>This example shows a patch for overriding the <code>system/bin/glgps</code> daemon to add wake lock support in the @@ -201,7 +451,27 @@ index 0c71d21..235c1a7 100644 ifeq ($(USE_SVELTE_KERNEL), true) </pre> - +<h3 id=older-migration>Migrating filesystems from earlier releases</h3> +<p>When migrating filesystems from Android 5.x and earlier, keep in mind that +Android 6.x:</p> +<ul> +<li>Removes some includes, structures, and inline definitions.</li> +<li>Requires a reference to <code>libcutils</code> instead of running directly +from <code>system/core/include/private/android_filesystem_config.h</code>. +Device manufacturer private executables that depend on +<code>system/code/include/private_filesystem_config.h</code> for the file or +directory structures or <code>fs_config</code> must add <code>libcutils</code> +library dependencies.</li> +<li>Requires device manufacturer private branch copies of the +<code>system/core/include/private/android_filesystem_config.h</code> with extra +content on existing targets to move to +<code>device/<em>vendor</em>/<em>device</em>/android_filesystem_config.h</code>. +</li> +<li>As Android reserves the right to apply SELinux Mandatory Access Controls +(MAC) to configuration files on the target system, implementations that include +custom target executables using <code>fs_config()</code> must ensure access. +</li> +</ul> </body> </html> diff --git a/en/devices/tech/dalvik/images/jit-arch.png b/en/devices/tech/dalvik/images/jit-arch.png Binary files differindex 6e2960eb..b34acb32 100644 --- a/en/devices/tech/dalvik/images/jit-arch.png +++ b/en/devices/tech/dalvik/images/jit-arch.png diff --git a/en/devices/tech/dalvik/images/jit-daemon.png b/en/devices/tech/dalvik/images/jit-daemon.png Binary files differindex ae46d594..6a801120 100644 --- a/en/devices/tech/dalvik/images/jit-daemon.png +++ b/en/devices/tech/dalvik/images/jit-daemon.png diff --git a/en/devices/tech/dalvik/images/jit-profile-comp.png b/en/devices/tech/dalvik/images/jit-profile-comp.png Binary files differindex 47fad635..f9dca0ab 100644 --- a/en/devices/tech/dalvik/images/jit-profile-comp.png +++ b/en/devices/tech/dalvik/images/jit-profile-comp.png diff --git a/en/devices/tech/dalvik/images/jit-workflow.png b/en/devices/tech/dalvik/images/jit-workflow.png Binary files differindex 282c5d9b..e9a5d732 100644 --- a/en/devices/tech/dalvik/images/jit-workflow.png +++ b/en/devices/tech/dalvik/images/jit-workflow.png diff --git a/en/devices/tech/dalvik/jit-compiler.html b/en/devices/tech/dalvik/jit-compiler.html index 74ac6de0..c105fd06 100644 --- a/en/devices/tech/dalvik/jit-compiler.html +++ b/en/devices/tech/dalvik/jit-compiler.html @@ -24,112 +24,97 @@ <p> -Android 7.0 adds a just-in-time (JIT) compiler with code profiling to Android -runtime (ART) that constantly improves the performance of Android apps as they -run. The JIT compiler complements ART's current ahead-of-time (AOT) compiler and -improves runtime performance, saves storage space, and speeds app updates and -system updates. +Android runtime (ART) includes a just-in-time (JIT) compiler with code profiling +that continually improves the performance of Android applications as they run. +The JIT compiler complements ART's current ahead-of-time (AOT) compiler and +improves runtime performance, saves storage space, and speeds application and +system updates. It also improves upon the AOT compiler by avoiding system +slowdown during automatic application updates or recompilation of applications +during over-the-air (OTA) updates. </p> <p> -The JIT compiler also improves upon the AOT compiler by avoiding system slowdown -during automatic application updates or recompilation of applications during -OTAs. This feature should require minimal device integration on the part of -manufacturers. +Although JIT and AOT use the same compiler with a similar set of optimizations, +the generated code might not be identical. JIT makes use of runtime type +information, can do better inlining, and makes on stack replacement (OSR) +compilation possible, all of which generates slightly different code. </p> -<p> -JIT and AOT use the same compiler with an almost identical set of optimizations. -The generated code might not be the same but it depends. JIT makes uses of -runtime type information and can do better inlining. Also, with JIT we sometimes -do OSR compilation (on stack replacement) which will again generate a bit -different code. -</p> +<h2 id="architectural-overview">JIT architecture</h2> -<h2 id="architectural-overview">Architectural Overview</h2> - -<img src="/devices/tech/dalvik/images/jit-arch.png" alt="JIT architecture" width="633" id="JIT-architecture" /> -<p class="img-caption"> - <strong>Figure 1.</strong> JIT architecture - how it works -</p> +<img src="./images/jit-arch.png" alt="JIT architecture"/> +<figcaption><strong>Figure 1.</strong> JIT architecture.</figcaption> -<h2 id="flow">Flow</h2> +<h2 id="flow">JIT compilation</h2> -<p> -JIT compilation works in this manner: -</p> +<p>JIT compilation involves the following activities:</p> +<img src="./images/jit-profile-comp.png" alt="Profile-guided comp"/> +<figcaption><strong>Figure 2.</strong> Profile-guided compilation.</figcaption> <ol> -<li>The user runs the app, which then triggers ART to load the .dex file. -<li>If the .oat file (the AOT binary for the .dex file) is available, ART uses -them directly. Note that .oat files are generated regularly. However, that does -not imply they contain compiled code (AOT binary). -<li>If no .oat file is available, ART runs through either JIT or an interpreter -to execute the .dex file. ART will always use the .oat files if available. -Otherwise, it will use the APK and extract it in memory to get to the .dex -incurring a big memory overhead (equal to the size of the dex files). +<li>The user runs the app, which then triggers ART to load the <code>.dex</code> +file. + <ul> + <li>If the <code>.oat</code> file (the AOT binary for the <code>.dex</code> + file) is available, ART uses it directly. Although <code>.oat</code> files are + generated regularly, they don't always contain compiled code (AOT binary).</li> + <li>If no <code>.oat</code> file is available, ART runs through JIT or an + interpreter to execute the <code>.dex</code> file.</li> + ART always uses the <code>.oat</code> files if available. Otherwise, it uses + the APK and extracts it in memory to get to the <code>.dex</code>; this incurs + a big memory overhead that is equal to the size of the dex files.</li> +</ul> +</li> <li>JIT is enabled for any application that is not compiled according to the -"speed" compilation filter (which says, compile as much as you can from the -app). -<li>The JIT profile data is dumped to a file in a system directory. Only the -application has access to the directory. -<li>The AOT compilation (dex2oat) daemon parses that file to drive its -compilation.</li> +<code>speed</code> compilation filter (which says "compile as much as you can +from the app").</li> +<li>The JIT profile data is dumped to a file in a system directory that only +the application can access.</li> +<li>The AOT compilation (<code>dex2oat</code>) daemon parses that file to drive +its compilation. +<br> +<br> +<img src="./images/jit-daemon.png" alt="JIT daemon"/> +<figcaption><strong>Figure 3.</strong> JIT daemon activities.</figcaption> +</li> </ol> -<img src="/devices/tech/dalvik/images/jit-profile-comp.png" alt="Profile-guided comp" width="452" id="JIT-profile-comp" /> -<p class="img-caption"> - <strong>Figure 2.</strong> Profile-guided compilation -</p> - -<img src="/devices/tech/dalvik/images/jit-daemon.png" alt="JIT daemon" width="718" id="JIT-daemon" /> -<p class="img-caption"> - <strong>Figure 3.</strong> How the daemon works -</p> - <p> -The Google Play service is an example used by other apps. These application tend -to behave more like shared libraries. +The Google Play service is an example used by other applications that behave +similar to shared libraries. </p> -<h2 id="jit-workflow">JIT Workflow</h2> -<p> -See the following high-level overview of how JIT works in the next diagram. -</p> +<h2 id="jit-workflow">JIT workflow</h2> -<img src="/devices/tech/dalvik/images/jit-workflow.png" alt="JIT architecture" width="707" id="JIT-workflow" /> -<p class="img-caption"> - <strong>Figure 4.</strong> JIT data flow -</p> - -<p> -This means: -</p> +<img src=./images/jit-workflow.png" alt="JIT architecture"/> +<figcaption><strong>Figure 4.</strong> JIT data flow.</figcaption> <ul> <li>Profiling information is stored in the code cache and subjected to garbage collection under memory pressure. -<li>As a result, there’s no guarantee the snapshot taken when the application is -in the background will contain the complete data (i.e. everything that was -JITed). -<li>There is no attempt to make sure we record everything as that will impact -runtime performance. -<li>Methods can be in three different states: <ul> - <li>interpreted (dex code) - <li>JIT compiled - <li>AOT compiled -<li>If both, JIT and AOT code exists (e.g. due to repeated de-optimizations), -the JITed code will be preferred. -<li>The memory requirement to run JIT without impacting foreground app -performance depends upon the app in question. Large apps will require more -memory than small apps. In general, big apps stabilize around 4 MB.</li></ul> + <ul> + <li>There is no guarantee a snapshot taken when the application was in the + background will contain complete data (i.e., everything that was JITed).</li> + <li>There is no attempt to ensure everything is recorded (as this can impact + runtime performance).</li> + </ul> </li> +<li>Methods can be in three different states: + <ul> + <li>interpreted (dex code)</li> + <li>JIT compiled</li> + <li>AOT compiled</li> + </ul> + If both JIT and AOT code exists (e.g. due to repeated de-optimizations), + the JITed code is preferred. +</li> +<li>The memory requirement to run JIT without impacting foreground app +performance depends upon the app in question. Large apps require more memory +than small apps. In general, large apps stabilize around 4 MB.</li> </ul> -<h2 id="tuning">Useful tips</h2> - -<h3 id="turn-on-jit-logging">Turn on JIT logging</h3> - +<h2 id="turn-on-jit-logging">Turning on JIT logging</h2> +<p>To turn on JIT logging, run the following commands:</p> <pre class="devsite-click-to-copy"> <code class="devsite-terminal">adb root</code> <code class="devsite-terminal">adb shell stop</code> @@ -137,8 +122,8 @@ memory than small apps. In general, big apps stabilize around 4 MB.</li></ul> <code class="devsite-terminal">adb shell start</code> </pre> -<h3 id="disable-jit-and-run-applications-in-interpreter">Disable JIT</h3> - +<h2 id="disable-jit-and-run-applications-in-interpreter">Disabling JIT</h2> +<p>To disable JIT, run the following commands:</p> <pre class="devsite-click-to-copy"> <code class="devsite-terminal">adb root</code> <code class="devsite-terminal">adb shell stop</code> @@ -146,13 +131,14 @@ memory than small apps. In general, big apps stabilize around 4 MB.</li></ul> <code class="devsite-terminal">adb shell start</code> </pre> -<h3 id="force-compilation-of-a-specific-package">Force compilation of a specific -package</h3> +<h2 id="force-compilation-of-a-specific-package">Forcing compilation</h2> -<p> -Check <code>$ adb shell cmd package compile</code> for usage. A few common use cases: -</p> +<p>To force compilation, run the following:</p> +<pre class="devsite-terminal devsite-click-to-copy"> +adb shell cmd package compile +</pre> +<p>Common use cases for force compiling a specific package:</p> <ul> <li>Profile-based: <pre class="devsite-terminal devsite-click-to-copy"> @@ -166,9 +152,7 @@ adb shell cmd package compile -m speed -f my-package </li> </ul> -<h3 id="force-compilation-of-all-packages">Force compilation of all -packages</h3> - +<p>Common use cases for force compiling all packages:</p> <ul> <li>Profile-based: <pre class="devsite-terminal devsite-click-to-copy"> @@ -182,16 +166,15 @@ adb shell cmd package compile -m speed -f -a </li> </ul> -<h3 id="clear-profile-data-and-remove-compiled-code">Clear profile data and -remove compiled code</h3> - +<h2 id="clear-profile-data-and-remove-compiled-code">Clearing profile data</h2> +<p>To clear profile data and remove compiled code, run the following:</p> <ul> -<li>One package: +<li>For one package: <pre class="devsite-terminal devsite-click-to-copy"> adb shell cmd package compile --reset my-package </pre> </li> -<li>All packages +<li>For all packages: <pre class="devsite-terminal devsite-click-to-copy"> adb shell cmd package compile --reset -a </pre> diff --git a/en/devices/tech/debug/index.html b/en/devices/tech/debug/index.html index 307c4585..702b7a14 100644 --- a/en/devices/tech/debug/index.html +++ b/en/devices/tech/debug/index.html @@ -36,9 +36,10 @@ it was necessary to truncate the name to fit. In Android O and later, this limit is much greater and should require no truncation.</p> <p>This page covers use of <code>debuggerd</code>, a daemon process for -collecting error information after applications crash. Other pages in this -section explore system services with -<a href="https://developer.android.com/studio/command-line/dumpsys.html">Dumpsys</a>, viewing +collecting error information after applications crash. Other pages explore system services with +<a + href="https://developer.android.com/studio/command-line/dumpsys.html"> + <code>dumpsys</code></a>, viewing <a href="/devices/tech/debug/native-memory.html">native memory</a>, <a href="https://developer.android.com/studio/command-line/dumpsys.html#network">network</a>, and <a href="https://developer.android.com/studio/command-line/dumpsys.html#procstats">RAM</a> usage, using diff --git a/en/devices/tech/perf/low-ram.html b/en/devices/tech/perf/low-ram.html index d1ca5b5e..4b9f67e7 100644 --- a/en/devices/tech/perf/low-ram.html +++ b/en/devices/tech/perf/low-ram.html @@ -71,7 +71,7 @@ when running on low memory devices and choose to disable large-RAM features. <h3 id="opt-track">Memory tracking</h3> <p> New memtrack HAL to track graphics memory allocations, additional information -in dumpsys meminfo, clarified summaries in meminfo (for example reported free +in <code>dumpsys</code> meminfo, clarified summaries in meminfo (for example reported free RAM includes RAM of cached processes, so that OEMs don't try to optimize the wrong thing). </p> |
