AI 148792: 3 new pages: customization, early_suspend, and wakelock.
Automated import of CL 148792
diff --git a/pdk/docs/guide/customization.jd b/pdk/docs/guide/customization.jd
new file mode 100755
index 0000000..a405113
--- /dev/null
+++ b/pdk/docs/guide/customization.jd
@@ -0,0 +1,319 @@
+page.title=Customization
+pdk.version=1.0
+@jd:body
+
+<a name="toc"/>
+<div style="padding:10px">
+<a href="#androidBootScreenCustomization">Boot Screen Customization</a><br/>
+<a href="#androidNetCustPlat">Network Customization Platform</a><br/><div style="padding-left:40px">
+
+<a href="#androidNetCustPlatNetworkConfig">Network Configuration</a><br/>
+<a href="#androidNetCustPlatAPNConfig">Build-time APN configuration</a><br/>
+<a href="#androidNetCustPlatAPNRunTime">APN configuration at run time</a><br/></div>
+<a href="#androidCustomizingPre-LoadedApps">Customizing pre-loaded applications</a><br/>
+<a href="#androidBrowserBookmarks">Customizing browser bookmarks</a><br/>
+<a href="#androidEmailProviderCustomization">Email Provider Customization</a><br/>
+<a href="#androidThemes">Platform Themes</a><br/><div style="padding-left:40px">
+
+<a href="#androidThemesStyles">Themes and Styles</a><br/>
+<a href="#androidThemesAnimations">Animations</a><br/></div></div></font></div>
+
+<a name="androidBootScreenCustomization"></a><h3>Boot Screen Customization</h3>
+
+<p>At startup, Android displays a splashscreen image while booting the device. Do the following if you wish to modify the default splash screen:</p>
+<p>
+<ol><li>Create a 320x480 image, <code>splashscreen.jpg</code> in this example.</li>
+<li>Using ImageMagick, convert your .jpg file to .r format:
+<pre class="prettify">
+convert screen.jpg screen.r
+</pre>
+</li>
+<li>Use the rgb2565 application to convert the image to 565 format:
+<pre class="prettify">
+rgb2565 < screen.rgb > screen.565
+</pre>
+</li>
+<li>Use fastboot to flash the image to the device:
+<pre class="prettify">
+fastboot flash splash1 screen.565
+</pre>
+</li>
+</ol>
+
+
+<a name="androidNetCustPlat"></a><h3>Network Customization Platform</h3>
+
+
+
+<a name="androidNetCustPlatNetworkConfig"></a><h4>Network Configuration</h4>
+
+<p>Android stores network configurations as a resource that gets compiled into binary at form at build time. The XML representation of this resource is located at <code>//android/frameworks/base/core/res/res/xml/apns.xml</code>. This file does not include any configured APNs. You should not modify this file, but instead configure APNs by product at build time (see Build-time APN Configuration below).</p>
+<p>Each network configuration is stored in an XML element following this syntax:</p>
+<pre class="prettify">
+<apn carrier="T-Mobile US"
+ mcc="310"
+ mnc="260"
+ apn=" wap.voicestream.com"
+ user="none"
+ server="*"
+ password="none"
+ proxy=" 216.155.165.50"
+ port="8080"
+ mmsc="http://216.155.174.84/servlets/mms"
+/>
+</pre>
+
+
+<a name="androidNetCustPlatAPNConfig"></a><h4>Build-time APN configuration</h4>
+
+<p>To set the APN configuration for a particular product target, add an <code>apns-conf.xml</code> file to the product configuration (do not modify the default platform APNs). This allows multiple products, all with different APNs, to be built off the same code base. </p>
+
+<p>To configure APNs at the product level, add a line to the product configuration file like the example below (<code>vendor/<vendor_name>/products/myphone-us.mk</code>): </p>
+
+<pre class="prettify">
+PRODUCT_COPY_FILES := vendor/acme/etc/apns-conf-us.xml:system/etc/apns-conf.xml
+</pre>
+
+
+
+<a name="androidNetCustPlatAPNRunTime"></a><h4>APN configuration at run time</h4>
+
+<p>At runtime, the Android reads APNs from the following file:</p>
+<pre class="prettify">
+system/etc/apns-conf.xml
+</pre>
+
+<p>Android supports the following run-time network configuration methods to choose the appropriate APN from the list of configured APNs:</p>
+<p><ul>
+<li><b>Automatic Configuration</b>: At boot time, Android determines the correct network configuration based on the MCC and MNC from the SIM card and automatically configure all network settings.</li>
+<li><b>Manual Configuration</b>: The platform will also support runtime (user) manual selection of network settings by name, for example, "Company Name US," and will support manual network configuration entry.</li>
+<li><b>WAP / SMS Push Configuration</b>: The network configurations are standard Android resources. You can upgrade a resource at runtime by installing a new system resource APK package. It will be possible to develop a network configuration service which listens to a specific binary SMS port for binary SMS messages containing the network configurations. NOTE: The implementation will likely be network operator dependent due to inconsistent SMS ports, binary SMS formats, etc.</li>
+</ul>
+
+
+
+
+<a name="androidCustomizingPre-LoadedApps"></a><h3>Customizing pre-loaded applications</h3>
+
+<p>To customize the list of Android packages for a particular product (applications, input methods, providers, services, etc.), set <code>PRODUCT_PACKAGES</code> property in the product configuration, as illustrated below:</p>
+
+<pre class="prettify">
+PRODUCT_PACKAGES := \
+ <company_name>Mail \
+ <company_name>IM \
+ <company_name>HomeScreen \
+ <company_name>Maps \
+ <company_name>SystemUpdater
+</pre>
+
+<p>Package names should correspond to the <code>LOCAL_PACKAGE_NAME</code> specified for each package's build target. For example, the <code>Android.mk</code> build target for <company_name>Mail, referenced above, could look like this:
+
+<pre class="prettify">
+# Build the <company_name>Mail application
+LOCAL_PATH:= $(call my-dir)
+include $(CLEAR_VARS)
+
+LOCAL_MODULE_TAGS := user development
+
+LOCAL_SRC_FILES := $(call all-java-files-under,src,tests)
+
+LOCAL_STATIC_JAVA_LIBRARIES := <company_name>login-client
+
+# Specify the package name
+LOCAL_PACKAGE_NAME := <company_name>Mail
+
+# Specify the certificate used to sign the application
+LOCAL_CERTIFICATE := vendor/<company_name>/certs/app
+
+include $(BUILD_PACKAGE)
+
+# Build the login client static library
+include $(LOCAL_PATH)/client/Android.mk
+</pre>
+
+<p>Note that the home screen is just an Android application that can be replaced entirely or customized by changing source code and application resources (Java source, layouts, etc.).</p>
+
+
+
+<a name="androidBrowserBookmarks"></a><h3>Customizing browser bookmarks</h3>
+
+<p>Browser bookmarks are stored as string resources in the Browser application: <code>//android/packages/apps/Browser/res/values/strings.xml</code>. Bookmarks are defined as simple value string arrays called "bookmarks". Each bookmark entry is stored as a pair of array values; the first represents the bookmark name and the second the bookmark URL. For example:</p>
+<pre class="prettify">
+<!-- Bookmarks -->
+<string-array name="bookmarks">
+ <item>Google</item>
+ <item>http://www.google.com/</item>
+ <item>Yahoo!</item>
+ <item>http://www.yahoo.com/</item>
+ <item>MSN</item>
+ <item>http://www.msn.com/</item>
+ <item>MySpace</item>
+ <item>http://www.myspace.com/</item>
+ <item>Facebook</item>
+ <item>http://www.facebook.com/</item>
+ <item>Wikipedia</item>
+ <item>http://www.wikipedia.org/</item>
+ <item>eBay</item>
+ <item>http://www.ebay.com/</item>
+ <item>CNN</item>
+ <item>http://www.cnn.com/</item>
+ <item>New York Times</item>
+ <item>http://www.nytimes.com/</item>
+ <item>ESPN</item>
+ <item>http://espn.go.com/</item>
+ <item>Amazon</item>
+ <item>http://www.amazon.com/</item>
+ <item>Weather Channel</item>
+ <item>http://www.weather.com/</item>
+ <item>BBC</item>
+ <item>http://www.bbc.co.uk/</item>
+</string-array>
+</pre>
+<p>Like and Android application resource, the platform will load alternate resources based on the platform configuration values. See <a href="http://developer.android.com/guide/topics/resources/resources-i18n.html">Resources and Internationalization</a> in the Android SDK for details. To configure bookmarks for a specific mobile network operator, place your customized bookmarks in a separate <code>strings.xml</code> file and place it under a Mobile Network Code (MNO) specific resource folder. For example, <code>Browser/res/values-mccXXX-mncYYY/strings.xml</code> where XXX and YYY represent the three-digit MCC and two to three digit MNC values.</p>
+<p>Android loads any configuration-specific resources as override values for the default values, so it is only necessary to include the bookmarks string-array values in this file.</p>
+
+
+
+<a name="androidEmailProviderCustomization"></a>
+<h3>Email Provider Customization</h3>
+
+<p>The default email provider settings are stored as string resources in the Email application (<code>//android/packages/apps/Email/res/xml/providers.xml</code>) as illustrated below.</p>
+<p><providers></p>
+<pre class="prettify">
+<!-- Gmail variants -->
+ <provider id="gmail" label="Gmail" domain="gmail.com">
+ <incoming uri="imap+ssl+://imap.gmail.com" username="$email"/>
+ <outgoing uri="smtp+ssl+://smtp.gmail.com" username="$email"/>
+ </provider>
+ <provider id="googlemail" label="Google Mail" domain="googlemail.com">
+ <incoming uri="imap+ssl+://imap.googlemail.com" username="$email"/>
+ <outgoing uri="smtp+ssl+://smtp.googlemail.com" username="$email"/>
+ </provider>
+ <provider id="google" label="Google" domain="google.com">
+ <incoming uri="imap+ssl+://imap.gmail.com" username="$email"/>
+ <outgoing uri="smtp+ssl+://smtp.gmail.com" username="$email"/>
+ </provider>
+ <provider id="android" label="Android" domain="android.com">
+ <incoming uri="imap+ssl+://imap.gmail.com" username="$email"/>
+ <outgoing uri="smtp+ssl+://smtp.gmail.com" username="$email"/>
+ </provider></p>
+
+ <!-- Common US providers -->
+
+ <provider id="aim" label="AIM" domain="aim.com">
+ <incoming uri="imap://imap.aim.com" label="IMAP" username="$email"/>
+ <outgoing uri="smtp://smtp.aim.com:587" username="$email"/>
+ </provider>
+ <provider id="aol" label="AOL" domain="aol.com">
+ <incoming uri="imap://imap.aol.com" label="IMAP" username="$email"/>
+ <outgoing uri="smtp://smtp.aol.com:587" username="$email"/>
+ </provider>
+ <provider id="comcast" label="Comcast" domain="comcast.net">
+ <incoming uri="pop3+ssl+://mail.comcast.net" username="$user"/>
+ <outgoing uri="smtp+ssl+://smtp.comcast.net" username="$user"/>
+ </provider>
+ <provider id="compuserve" label="CompuServe" domain="cs.com">
+ <incoming uri="imap://imap.cs.com" username="$user"/>
+ <outgoing uri="smtp://smtp.cs.com" username="$user"/>
+ </provider>
+ <provider id="dotmac" label=".Mac" domain="mac.com">
+ <incoming uri="imap+tls://mail.mac.com" username="$email"/>
+ <outgoing uri="smtp+tls://smtp.mac.com" username="$email"/>
+ </provider>
+ <provider id="earthlink" label="Earthlink" domain="earthlink.net">
+ <incoming uri="pop3://pop.earthlink.net" username="$email"/>
+ <outgoing uri="smtp://smtpauth.earthlink.net:587" username="$email"/>
+ </provider>
+ <provider id="juno" label="Juno" domain="juno.com">
+ <incoming uri="pop3://pop.juno.com" username="$user"/>
+ <outgoing uri="smtp://smtp.juno.com" username="$user"/>
+ </provider>
+ <provider id="live" label="Windows Live Hotmail Plus" domain="live.com" note="@string/provider_note_live">
+ <incoming uri="pop3+ssl+://pop3.live.com" username="$email"/>
+ <outgoing uri="smtp+tls+://smtp.live.com" username="$email"/>
+ </provider>
+ <provider id="hotmail" label="Windows Live Hotmail Plus" domain="hotmail.com" note="@string/provider_note_live">
+ <incoming uri="pop3+ssl+://pop3.live.com" username="$email"/>
+ <outgoing uri="smtp+tls+://smtp.live.com" username="$email"/>
+ </provider>
+ <provider id="msn" label="Windows Live Hotmail Plus" domain="msn.com" note="@string/provider_note_live">
+ <incoming uri="pop3+ssl+://pop3.live.com" username="$email"/>
+ <outgoing uri="smtp+tls+://smtp.live.com" username="$email"/>
+ </provider>
+ <provider id="mobileme" label="MobileMe" domain="me.com">
+ <incoming uri="imap+tls://mail.me.com" username="$email"/>
+ <outgoing uri="smtp+tls://smtp.me.com" username="$email"/>
+ </provider>
+ <provider id="netzero" label="NetZero" domain="netzero.com">
+ <incoming uri="pop3://pop.netzero.com" username="$user"/>
+ <outgoing uri="smtp://smtp.netzero.com" username="$user"/>
+ </provider>
+ <provider id="sbcglobal" label="SBC Global" domain="sbcglobal.net">
+ <incoming uri="pop3://pop.sbcglobal.yahoo.com" username="$email"/>
+ <outgoing uri="smtp://smtp.sbcglobal.yahoo.com" username="$email"/>
+ </provider>
+ <provider id="verizon" label="Verizon" domain="verizon.net">
+ <incoming uri="pop3://incoming.verizon.net" username="$user"/>
+ <outgoing uri="smtp://outgoing.verizon.net" username="$user"/>
+ </provider>
+ <provider id="yahoo" label="Yahoo Plus" domain="yahoo.com" note="@string/provider_note_yahoo">
+ <incoming uri="pop3+ssl+://plus.pop.mail.yahoo.com" username="$user"/>
+ <outgoing uri="smtp+ssl+://plus.smtp.mail.yahoo.com" username="$user"/>
+ </provider>
+
+ <!-- Common UK providers -->
+
+ <provider id="aol-uk" label="AOL" domain="aol.co.uk">
+ <incoming uri="imap+ssl+://imap.uk.aol.com" label="IMAP" username="$user"/>
+ <outgoing uri="smtp+ssl+://smtp.uk.aol.com" username="$user"/>
+ </provider>
+ <provider id="bt" label="BT Internet" domain="btinternet.com">
+ <incoming uri="pop3://mail.btinternet.com" username="$email"/>
+ <outgoing uri="smtp://mail.btinternet.com" username=""/>
+ </provider>
+ <provider id="tiscali" label="Tiscali" domain="tiscali.co.uk">
+ <incoming uri="pop3://pop.tiscali.co.uk" username="$email"/>
+ <outgoing uri="smtp://smtp.tiscali.co.uk" username="$email:wq"/>
+ </provider>
+ <provider id="yahoo-uk" label="Yahoo" domain="yahoo.co.uk" note="@string/provider_note_yahoo_uk">
+ <incoming uri="pop3+ssl+://pop.mail.yahoo.co.uk" username="$user"/>
+ <outgoing uri="smtp+ssl+://smtp.mail.yahoo.co.uk" username="$user"/>
+ </provider>
+
+ <!-- Common Germany providers -->
+
+ <provider id="freenet" label="Freenet" domain="freenet.de">
+ <incoming uri="pop3://mx.freenet.de" username="$user"/>
+ <outgoing uri="smtp+ssl://mx.freenet.de" username="$email"/>
+ </provider>
+ <provider id="gmx" label="GMX" domain="gmx.de">
+ <incoming uri="pop3+tls://pop.gmx.net" username="$email"/>
+ <outgoing uri="smtp+tls://mail.gmx.net" username="$email"/>
+ </provider>
+ <provider id="T-Online" label="T-Online" domain="t-online.de" note="@string/provider_note_t_online">
+ <incoming uri="pop3://popmail.t-online.de" username="$email"/>
+ <outgoing uri="smtp://smtpmail.t-online.de" username="$email"/>
+ </provider>
+ <provider id="web.de" label="Web.de" domain="web.de">
+ <incoming uri="pop3+tls://pop3.web.de" username="$user"/>
+ <outgoing uri="smtp+tls://smtp.web.de" username="$user"/>
+ </provider>
+</providers>
+</pre>
+<p>As with all Android application resources, the platform will load alternate resources based on the platform configuration values. See <a href="http://developer.android.com/guide/topics/resources/resources-i18n.html">Resources and Internationalization</a> in the Android SDK for details. To configure email providers for a specific mobile network operator, place the customized providers in a separate <code>providers.xml</code> file and place it under a Mobile Network Code (MNO) specific resource folder. For example, <code>Email/res/xml-mccXXX-mncYYY/providers.xml</code> where XXX and YYY represent the three-digit MCC and two to three digit MNC values.</p>
+
+
+
+<a name="androidThemes"></a><h3>Platform Themes</h3>
+
+
+
+<a name="androidThemesStyles"></a><h4>Themes and Styles</h4>
+
+<p>System level styles are defined in <code>//android/framework/base/core/res/res/values/styles.xml</code>.</p>
+
+
+<a name="androidThemesAnimations"></a><h4>Animations</h4>
+
+<p>Android supports configurable animations for window and view transitions. System-level animations are defined in XML in global resource files located in <code>//android/framework/base/core/res/res/anim/</code>.</p>
+
\ No newline at end of file
diff --git a/pdk/docs/guide/early_suspend.jd b/pdk/docs/guide/early_suspend.jd
new file mode 100755
index 0000000..a27a5ca
--- /dev/null
+++ b/pdk/docs/guide/early_suspend.jd
@@ -0,0 +1,29 @@
+page.title=Early Suspend
+pdk.version=1.0
+@jd:body
+<p>The early-suspend API allows drivers to get notified when user-space writes to <code>/sys/power/request_state</code> to indicate that the user visible sleep state should change. Suspend handlers are called in order of low to high (4 - 1 below) and resume handlers are called in order of high to low (1 - 4 below).</p>
+<ol>
+ <li><code>EARLY_SUSPEND_LEVEL_BLANK_SCREEN</code>: </li>
+ <ul>
+ <li>on suspend: the screen should be turned off but the framebuffer must still be accessible. </li>
+ <li>on resume: the screen can be turned back on.</li>
+ </ul>
+ <li><code>EARLY_SUSPEND_LEVEL_STOP_DRAWING</code>:
+ <ul>
+ <li>on suspend: this level notifies user-space that it should stop accessing the framebuffer and it waits for it to complete.</li>
+ <li>on resume: it notifies user-space that it should resume screen access. Two methods are provided, console switch or a sysfs interface.</li>
+ </ul>
+ </li>
+ <li><code>EARLY_SUSPEND_LEVEL_DISABLE_FB</code>: Turn off the framebuffer
+ <ul>
+ <li>on suspend: turn off the framebuffer</li>
+ <li>on resume: turn the framebuffer back on. </li>
+ </ul>
+ </li>
+ <li><code>EARLY_SUSPEND_LEVEL_STOP_INPUT</code>:
+ <ul>
+ <li>on suspend: turn off input devices that are not capable of wakeup or where wakeup is disabled. </li>
+ <li>on resume: turn the same devices back on.</li>
+ </ul>
+ </li>
+</ol>
diff --git a/pdk/docs/guide/wakelock.jd b/pdk/docs/guide/wakelock.jd
new file mode 100755
index 0000000..1d8b425
--- /dev/null
+++ b/pdk/docs/guide/wakelock.jd
@@ -0,0 +1,77 @@
+page.title=Wakelocks
+pdk.version=1.0
+@jd:body
+
+
+<a name="toc"/>
+<div style="padding:10px">
+ <a href="#intro">Introduction</a><BR>
+ <a href="#driverAPI">Driver API</a><br/>
+ <a href="#userspaceAPI">User Space API</a><br/>
+</div>
+
+ <a name="userspaceAPI"></a><h2>Introduction</h2>
+<p>A locked wakelock, depending on its type, prevents the system from entering suspend or other low-power states. This document describes how to employ wakelocks. </p>
+<p>There are two settings for a wakelock:</p>
+<ul>
+ <li><code>WAKE_LOCK_SUSPEND</code>: prevents a full system suspend. </li>
+ <li><code></code><code>WAKE_LOCK_IDLE</code>: low-power states, which often cause large interrupt latencies or that disable a set of interrupts, will not be entered from idle until the wakelocks are released. </li>
+</ul>
+<p>Unless the type is specified, this document refers to wakelocks of type <code>WAKE_LOCK_SUSPEND</code>. </p>
+<p>If the suspend operation has already started when locking a wakelock, the system will abort the suspend operation as long it has not already reached the <code>suspend_late</code> stage. This means that locking a wakelock from an interrupt handler or a freezeable thread always works, but if you lock a wakelock from a <code>suspend_late</code> handler, you must also return an error from that handler to abort suspend. You can use wakelocks to allow the user-space to decide which keys should wake the full system and turn on the screen. Use <code>set_irq_wake</code> or a platform-specific API to ensure that the keypad interrupt wakes up the CPU. Once the keypad driver has resumed, the sequence of events can look like this:</p>
+<ol>
+ <li> The Keypad driver receives an interrupt, locks the keypad-scan wakelock,
+ and starts scanning the keypad matrix. </li>
+ <li>The keypad-scan code detects a key change and reports it to the input-event
+ driver. </li>
+ <li>The input-event driver sees the key change, enqueues an event, and locks
+ the input-event-queue wakelock. </li>
+ <li>The keypad-scan code detects that no keys are held and unlocks the
+ keypad-scan wakelock. </li>
+ <li>The user-space input-event thread returns from select/poll, locks the
+ process-input-events wakelock, and calls read in the input-event device. </li>
+ <li>The input-event driver dequeues the key-event and, since the queue is now
+ empty, unlocks the input-event-queue wakelock. </li>
+ <li>The user-space input-event thread returns from read. It determines that the
+ key should not wake up the full system, releases the process-input-events
+ wakelock, and calls select or poll. </li>
+</ol>
+<p>The simple sequence diagram below illustrates these steps:</p>
+ <pre>
+ Key pressed Key released
+ | |
+ keypad-scan ++++++++++++++++++++++
+ input-event-queue +++ +++
+ process-input-events +++ +++
+ </pre>
+
+<a name="driverAPI"></a><h2>Driver API</h2>
+<p>A driver can use the wakelock API by adding a wakelock variable to its state and calling <code>wake_lock_init</code>, as illustrated in the snippet below:</p>
+<pre class="prettify">
+ struct state {
+ struct wakelock wakelock;
+ }
+ init() {
+ wake_lock_init(&state->wakelock, WAKE_LOCK_SUSPEND, "wakelockname");
+ }
+ Before freeing the memory, wake_lock_destroy must be called:
+ uninit() {
+ wake_lock_destroy(&state->wakelock);
+ }
+ </pre>
+<p> When the driver determines that it needs to run (usually in an interrupt handler), it calls <code>wake_lock</code>:</p>
+<pre class="prettify">
+ wake_lock(&state->wakelock);
+ </pre>
+<p>When it no longer needs to run, it calls <code>wake_unlock</code>:</p>
+<pre class="prettify">
+ wake_unlock(&state->wakelock);
+ </pre>
+<p> It can also call <code>wake_lock_timeout</code> to release the wakelock after a delay:</p>
+<pre class="prettify">
+ wake_lock_timeout(&state->wakelock, HZ);
+</pre>
+<p> This works whether or not the wakelock is already held. It is useful if the driver woke up other parts of the system that do not use wakelocks but still need to run. Avoid this when possible, since it will waste power if the timeout is long or may fail to finish needed work if the timeout is short.</p>
+<a name="userspaceAPI"></a><h2>User-space API</h2>
+<p>Write <code>lockname</code> or <code>lockname timeout</code> to <code>/sys/power/wake_lock</code> lock and, if needed, create a wakelock. The timeout here is specified in nanoseconds. Write <code>lockname</code> to <code>/sys/power/wake_unlock</code> to unlock a user wakelock.</p>
+<p> Do not use randomly generated wakelock names as there is no API to free a user-space wakelock.</p>
\ No newline at end of file