Docs: Add carrier config and UICC pages

Bug: 23208301
Change-Id: Ib415ebde7901978287c3db1b54648166fc15e751
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index 8a730cb..5744717 100644
--- a/src/devices/devices_toc.cs
+++ b/src/devices/devices_toc.cs
@@ -192,6 +192,7 @@
             </a>
         </div>
         <ul>
+          <li><a href="<?cs var:toroot ?>devices/tech/config/carrier.html">Carrier Customization</a></li>
           <li><a href="<?cs var:toroot ?>devices/tech/config/filesystem.html">File System</a></li>
           <li><a href="<?cs var:toroot ?>devices/tech/config/kernel.html">Kernel</a></li>
           <li><a href="<?cs var:toroot ?>devices/tech/config/low-ram.html">Low RAM</a></li>
diff --git a/src/devices/tech/config/carrier.jd b/src/devices/tech/config/carrier.jd
new file mode 100644
index 0000000..51261ff
--- /dev/null
+++ b/src/devices/tech/config/carrier.jd
@@ -0,0 +1,236 @@
+page.title=Carrier Configuration
+@jd:body
+
+<!--
+    Copyright 2015 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.
+-->
+
+<div id="qv-wrapper">
+  <div id="qv">
+    <h2>In this document</h2>
+    <ol id="auto-toc">
+    </ol>
+  </div>
+</div>
+
+<p>The Android 6.0 Marshmallow release introduces a capability for privileged
+applications to provide carrier-specific configuration to the platform. This
+functionality, based on the <a href="uicc.html">UICC carrier privilege
+functionality</a> introduced in Android 5.1 (Lollipop MR1), will allow carrier
+configuration to be moved away from the static configuration overlays and give
+carriers and OEMs the ability to dynamically provide carrier configuration to
+the platform through a defined interface.</p>
+
+<p>A properly signed carrier app can either be preloaded in the system image,
+installed automatically, or manually installed through an app store. The app
+will be queried by the platform to provide configuration for settings
+including:</p>
+
+<ul>
+  <li>Roaming/Non-roaming networks
+  <li>Visual Voicemail
+  <li>SMS/MMS network settings
+  <li>VoLTE/IMS configurations
+</ul>
+
+<p class="note"><strong>Note</strong>: This app must be signed with the
+certificate that has a matching signature to one on the SIM. See the <a
+href="#how_privilege_is_granted_to_a_carrier_app">How is privilege granted to a
+Carrier App</a> section for details.</p>
+
+<p>The determination of what values to return is entirely up to the Carrier App
+and can be dynamic based on detailed information passed to the app via the
+platform. </p>
+
+<p>The key benefits of this approach are:</p>
+
+<ul>
+  <li><strong>Dynamic configuration</strong> - Support for concepts like
+non-MCCMNC derived configuration, for example
+mobile virtual network operators (MVNOs) or customer opt in to extra services
+  <li><strong>Support for devices sold through any channel</strong> - e.g. an
+open market phone can be automatically configured with the right
+settings by downloading an app from an app store.
+  <li><strong>Security</strong> - Privilege to provide this configuration is
+given only to applications signed by the carrier
+  <li><strong>Defined API</strong> - Previously this configuration was stored
+mostly in internal XML overlays within the framework and not through a public
+API. The carrier config API in Android 6.0 is public and well defined.
+</ul>
+
+<h2 id=how_it_works>How it works</h2>
+
+<h3 id=loading_the_config>Loading the config</h3>
+
+<p>The carrier configuration supplied by this feature is a set of key-value pairs
+that change various telephony-related behaviors in the platform.</p>
+
+<p>The set of values for a particular device is determined by querying the
+following components in order:</p>
+
+<ol>
+  <li>The Carrier App (although this is technically optional, it is the recommended
+location for additional configuration beyond what exists in the Android Open
+Source Project - AOSP)
+  <li>The Platform Config App bundled with the system image
+  <li>Default values, hardcoded into the framework (equivalent to the behavior prior
+to M)
+</ol>
+
+<p class="caution"><strong>Important</strong>: If a value for a particular key
+is returned at any stage, the first value found takes precedence over the
+further stages.</p>
+
+<h4 id=the_platform_config_app>The Platform Config App</h4>
+
+<p>A generic Platform Config App is bundled with the system image that can supply
+values for any variables the regular Carrier App does not. The platform config
+app can be found (in M) in: <code>packages/apps/CarrierConfig</code></p>
+
+<p>This app’s purpose is to provide some per-network configuration when a Carrier
+App is not installed, and carriers/OEMs should make only minimal changes to it
+in their own images. Instead carriers should provide the separate Carrier App
+for carrier customization, allowing updates to be distributed via avenues such
+as app stores.</p>
+
+<h4 id=how_privilege_is_granted_to_a_carrier_app>How privilege is granted to a Carrier App</h4>
+
+<p>The Carrier App in question must be signed with the same certificate found on
+the SIM card, as documented in <a href="uicc.html">UICC Carrier Privileges</a>.</p>
+
+<h4 id=what_information_is_passed_to_the_carrier_app>What information is passed to the Carrier App</h4>
+
+<p>The Carrier App is supplied with the following values, enabling it to make a
+dynamic decision as to what values to return:</p>
+
+<ul>
+  <li>MCC
+  <li>MNC
+  <li>SPN
+  <li>IMSI
+  <li>GID1
+  <li>GID2
+</ul>
+
+<h4 id=when_loading_the_carrier_config_occurs>When loading the carrier config occurs</h4>
+
+<p>The building of the list of key value pairs occurs:</p>
+
+<ul>
+  <li>When the SIM is loaded (boot, or SIM hot swap)
+  <li>When the Carrier app manually triggers a reload
+  <li>When the Carrier app gets updated
+</ul>
+
+<p>See the <a
+href="http://developer.android.com/reference/android/service/carrier/CarrierService.html#onLoadConfig(android.service.carrier.CarrierIdentifier)">android.service.carrier.CarrierService#onLoadConfig()</a>
+reference for more details.</p>
+
+<p class="note"><strong>Note</strong>: The platform caches carrier
+configuration bundles and loads from the cache for SIM state changes. This is
+to speed up boot and SIM hot swap. It is assumed that without a package update
+or an explicit <code>notifyConfigChangedForSubId</code>, the config bundle has
+not been modified.</p>
+
+<h3 id=using_the_config>Using the config</h3>
+
+<p>Once the configuration has been built, the values contained within it are used
+to set various values of system configuration, including:</p>
+
+<ul>
+  <li>Internal framework telephony settings
+  <li>SDK-returned configuration values, e.g. in SmsManager
+  <li>App settings like VVM connection values in the Dialer
+</ul>
+
+<h3 id=configuration_keys>Configuration keys</h3>
+
+<p>The list of keys is defined as part of the public SDK in <code><a
+href="http://developer.android.com/reference/android/telephony/CarrierConfigManager.html">android.telephony.CarrierConfigManager</a></code>
+and cannot change within the same API level. See the table below for a summary of keys.</p>
+
+<h2 id=how_to_build_your_application>How to build your application</h2>
+
+<h3 id=create_your_application>Create your application</h3>
+
+<p>Your application must target the Android 6.0 API level (23).</p>
+
+<h3 id=declare_a_class_that_overrides_android_service_carrier_carrierservice>Declare a class that overrides android.service.carrier.CarrierService</h3>
+
+<ol>
+  <li>Override <code>onLoadConfig</code> to return the values you wish to
+supply based on the <code>service.carrier.CarrierIdentifier</code> object
+passed.
+  <li>Add logic to call <code>notifyConfigChangedForSubId</code> in scenarios
+where carrier configuration may change over time (e.g. when the
+user adds extra services to their account)
+</ol>
+
+<p>An example is below:</p>
+
+<pre>
+public class SampleCarrierConfigService extends CarrierService {
+
+    private static final String TAG = "SampleCarrierConfigService";
+
+    public SampleCarrierConfigService() {
+        Log.d(TAG, "Service created");
+    }
+
+    &#64;Override
+    public PersistableBundle onLoadConfig(CarrierIdentifier id) {
+        Log.d(TAG, "Config being fetched");
+        PersistableBundle config = new PersistableBundle();
+        config.putBoolean(
+            CarrierConfigManager.KEY_CARRIER_VOLTE_AVAILABLE_BOOL, true);
+        config.putBoolean(
+            CarrierConfigManager.KEY_CARRIER_VOLTE_TTY_SUPPORTED_BOOL, false);
+        config.putInt(CarrierConfigManager.KEY_VOLTE_REPLACEMENT_RAT_INT, 6);
+        // Check CarrierIdentifier and add more config if needed…
+        return config;
+    }
+}
+</pre>
+
+
+<p>Please see the <a
+href="https://developer.android.com/reference/android/service/carrier/CarrierService.html">android.service.carrier.CarrierService</a> reference on developer.android.com for more details.</p>
+
+<h3 id=name_the_class_in_your_manifest>Name the class in your manifest</h3>
+
+<p>An example is below:</p>
+
+<pre>
+&lt;service android:name=".SampleCarrierConfigService"
+android:label="&#64;string/service_name"
+android:permission="android.permission.BIND_CARRIER_SERVICES"&gt;
+      &lt;intent-filter&gt;
+      &lt;action android:name="android.service.carrier.ConfigService"/&gt;&lt;/intent-filter&gt;
+&lt;/service&gt;
+</pre>
+
+<h3 id=sign_app_with_same_certificate_on_sim>Sign app with same certificate on SIM</h3>
+
+<p>See <a href="uicc.html">UICC Carrier Privileges</a> for the requirements.</p>
+
+<h2 id=testing_your_application>Testing your application</h2>
+
+<p>Once you have built your configuration application, you can test your code
+with:</p>
+
+<ul>
+  <li>A SIM containing a valid certificate signature
+  <li>A device running Android 6.0 and later, for example a Nexus device
+</ul>