From eb98133b0f66cca46ea2b8f54479fb745ddc478a Mon Sep 17 00:00:00 2001 From: David Warren Date: Wed, 13 May 2009 12:00:07 -0700 Subject: [PATCH] AI 148792: 3 new pages: customization, early_suspend, and wakelock. Automated import of CL 148792 --- pdk/docs/guide/customization.jd | 319 ++++++++++++++++++++++++++++++++ pdk/docs/guide/early_suspend.jd | 29 +++ pdk/docs/guide/wakelock.jd | 77 ++++++++ 3 files changed, 425 insertions(+) create mode 100755 pdk/docs/guide/customization.jd create mode 100755 pdk/docs/guide/early_suspend.jd create mode 100755 pdk/docs/guide/wakelock.jd diff --git a/pdk/docs/guide/customization.jd b/pdk/docs/guide/customization.jd new file mode 100755 index 000000000..a405113c4 --- /dev/null +++ b/pdk/docs/guide/customization.jd @@ -0,0 +1,319 @@ +page.title=Customization +pdk.version=1.0 +@jd:body + + +
+Boot Screen Customization
+Network Customization Platform
+ +Network Configuration
+Build-time APN configuration
+APN configuration at run time
+Customizing pre-loaded applications
+Customizing browser bookmarks
+Email Provider Customization
+Platform Themes
+ +Themes and Styles
+Animations
+ +

Boot Screen Customization

+ +

At startup, Android displays a splashscreen image while booting the device. Do the following if you wish to modify the default splash screen:

+

+

  1. Create a 320x480 image, splashscreen.jpg in this example.
    2. +
  2. Using ImageMagick, convert your .jpg file to .r format: +
     
+convert screen.jpg screen.r
+
    +
    3. +
  3. Use the rgb2565 application to convert the image to 565 format: +
     
+rgb2565 < screen.rgb > screen.565
+
    +
    4. +
  4. Use fastboot to flash the image to the device: +
     
+fastboot flash splash1 screen.565
+
    +
    5. +
+ + +

Network Customization Platform

+ + + +

Network Configuration

+ +

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 //android/frameworks/base/core/res/res/xml/apns.xml. 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).

+

Each network configuration is stored in an XML element following this syntax:

+
 
+<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"
+/>
+
+ + +

Build-time APN configuration

+ +

To set the APN configuration for a particular product target, add an apns-conf.xml 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.

+ +

To configure APNs at the product level, add a line to the product configuration file like the example below (vendor/<vendor_name>/products/myphone-us.mk):

+ +
 
+PRODUCT_COPY_FILES := vendor/acme/etc/apns-conf-us.xml:system/etc/apns-conf.xml
+
+ + + +

APN configuration at run time

+ +

At runtime, the Android reads APNs from the following file:

+
 
+system/etc/apns-conf.xml
+
+ +

Android supports the following run-time network configuration methods to choose the appropriate APN from the list of configured APNs:

+

+ + + + +

Customizing pre-loaded applications

+ +

To customize the list of Android packages for a particular product (applications, input methods, providers, services, etc.), set PRODUCT_PACKAGES property in the product configuration, as illustrated below:

+ +
 
+PRODUCT_PACKAGES := \
+ <company_name>Mail \
+    <company_name>IM \
+ <company_name>HomeScreen \
+ <company_name>Maps \
+ <company_name>SystemUpdater
+
+ +

Package names should correspond to the LOCAL_PACKAGE_NAME specified for each package's build target. For example, the Android.mk build target for <company_name>Mail, referenced above, could look like this: + +

 
+# 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
+
+ +

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.).

+ + + +

Customizing browser bookmarks

+ +

Browser bookmarks are stored as string resources in the Browser application: //android/packages/apps/Browser/res/values/strings.xml. 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:

+
 
+<!-- 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>
+
+

Like and Android application resource, the platform will load alternate resources based on the platform configuration values. See Resources and Internationalization in the Android SDK for details. To configure bookmarks for a specific mobile network operator, place your customized bookmarks in a separate strings.xml file and place it under a Mobile Network Code (MNO) specific resource folder. For example, Browser/res/values-mccXXX-mncYYY/strings.xml where XXX and YYY represent the three-digit MCC and two to three digit MNC values.

+

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.

+ + + + +

Email Provider Customization

+ +

The default email provider settings are stored as string resources in the Email application (//android/packages/apps/Email/res/xml/providers.xml) as illustrated below.

+

<providers>

+
 
+<!-- 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>
 
+ 
+    <!-- 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>
+
+

As with all Android application resources, the platform will load alternate resources based on the platform configuration values. See Resources and Internationalization in the Android SDK for details. To configure email providers for a specific mobile network operator, place the customized providers in a separate providers.xml file and place it under a Mobile Network Code (MNO) specific resource folder. For example, Email/res/xml-mccXXX-mncYYY/providers.xml where XXX and YYY represent the three-digit MCC and two to three digit MNC values.

+ + + +

Platform Themes

+ + + +

Themes and Styles

+ +

System level styles are defined in //android/framework/base/core/res/res/values/styles.xml.

+ + +

Animations

+ +

Android supports configurable animations for window and view transitions. System-level animations are defined in XML in global resource files located in //android/framework/base/core/res/res/anim/.

+ \ 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 000000000..a27a5caba --- /dev/null +++ b/pdk/docs/guide/early_suspend.jd @@ -0,0 +1,29 @@ +page.title=Early Suspend +pdk.version=1.0 +@jd:body +

The early-suspend API allows drivers to get notified when user-space writes to /sys/power/request_state 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).

+
    +
  1. EARLY_SUSPEND_LEVEL_BLANK_SCREEN:
    2. + +
  2. EARLY_SUSPEND_LEVEL_STOP_DRAWING: +
      +
    • on suspend: this level notifies user-space that it should stop accessing the framebuffer and it waits for it to complete.
      • +
    • on resume: it notifies user-space that it should resume screen access. Two methods are provided, console switch or a sysfs interface.
      • +
    +
    3. +
  3. EARLY_SUSPEND_LEVEL_DISABLE_FB: Turn off the framebuffer +
      +
    • on suspend: turn off the framebuffer
      • +
    • on resume: turn the framebuffer back on.
      • +
    +
    4. +
  4. EARLY_SUSPEND_LEVEL_STOP_INPUT: +
      +
    • on suspend: turn off input devices that are not capable of wakeup or where wakeup is disabled.
      • +
    • on resume: turn the same devices back on.
      • +
    +
    5. +
diff --git a/pdk/docs/guide/wakelock.jd b/pdk/docs/guide/wakelock.jd new file mode 100755 index 000000000..1d8b425c6 --- /dev/null +++ b/pdk/docs/guide/wakelock.jd @@ -0,0 +1,77 @@ +page.title=Wakelocks +pdk.version=1.0 +@jd:body + + + +
+ Introduction
+ Driver API
+ User Space API
+
+ +

Introduction

+

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.

+

There are two settings for a wakelock:

+ +

Unless the type is specified, this document refers to wakelocks of type WAKE_LOCK_SUSPEND.

+

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 suspend_late 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 suspend_late 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 set_irq_wake 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:

+
    +
  1. The Keypad driver receives an interrupt, locks the keypad-scan wakelock, + and starts scanning the keypad matrix.
    2. +
  2. The keypad-scan code detects a key change and reports it to the input-event + driver.
    3. +
  3. The input-event driver sees the key change, enqueues an event, and locks + the input-event-queue wakelock.
    4. +
  4. The keypad-scan code detects that no keys are held and unlocks the + keypad-scan wakelock.
    5. +
  5. The user-space input-event thread returns from select/poll, locks the + process-input-events wakelock, and calls read in the input-event device.
    6. +
  6. The input-event driver dequeues the key-event and, since the queue is now + empty, unlocks the input-event-queue wakelock.
    7. +
  7. 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.
    8. +
+

The simple sequence diagram below illustrates these steps:

+ 
+     					Key pressed      Key released
+      					     |		      |
+      keypad-scan       		     ++++++++++++++++++++++
+      input-event-queue 			  +++ 		  +++
+      process-input-events 		            +++ 	    +++
+
+ +

Driver API

+

A driver can use the wakelock API by adding a wakelock variable to its state and calling wake_lock_init, as illustrated in the snippet below:

+
+  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);
+  }
+
+

When the driver determines that it needs to run (usually in an interrupt handler), it calls wake_lock:

+
+  wake_lock(&state->wakelock);
+
+

When it no longer needs to run, it calls wake_unlock:

+
+  wake_unlock(&state->wakelock);
+
+

It can also call wake_lock_timeout to release the wakelock after a delay:

+
+  wake_lock_timeout(&state->wakelock, HZ);
+
+

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.

+

User-space API

+

Write lockname or lockname timeout to /sys/power/wake_lock lock and, if needed, create a wakelock. The timeout here is specified in nanoseconds. Write lockname to /sys/power/wake_unlock to unlock a user wakelock.

+

Do not use randomly generated wakelock names as there is no API to free a user-space wakelock.

\ No newline at end of file