Android is an open-source software stack created for mobile phones and
+other devices. The Android Open Source Project (AOSP) is tasked with the
+maintenance and further development of Android. Many device manufacturers have
+brought to market devices running Android, and they are readibly available
+around the world.
+Our primary purpose is to build an excellent software platform for everyday
+users. A number of companies have committed many engineers to achieve this
+goal, and the result is a full production quality consumer product whose
+source is open for customization and porting.
+The key to any community is, obviously, communication. Like most projects,
+Android communicates via mailing lists. Because Android is an extremely large
+project with many components, we have many discussion forums, each focusing on
+a different topic.
+Please check out the groups below, and join any that seem interesting to
+you. Note that if you're a user looking for help with your Android device,
+this page probably isn't for you; you should contact your carrier or retailer
+for help with your phone.
+Please note that if you're looking for information about building
+applications for Android, you can find a separate set of groups for those at
+our sister site, developer.android.com: http://developer.android.com/community/index.html
-Please consider the following before you post to our lists.
+To subscribe to a group without using the Google Groups site, use the link
+under "subscribe via email" in the lists above.
+We also have a presence on IRC via Freenode. We maintain two official IRC
+channels on irc.freenode.net:
+The channels above are official. There are a few other channels the
+community is using, but are not official. These aren't official or officially
+moderated/managed, so you use the channels below at your own risk. The Open
+Handset Alliance doesn't endorse these channels, there's no warranty express
+or implied, and so on. There may be more.
+
-
-
Android Open Source Project
-
-
Android is the first free, open source, and fully customizable mobile platform.
- Android offers a full stack: an operating system, middleware and key mobile applications.
- It also contains a rich set of APIs that allows third-party developers to develop great
- applications.
-
+
+
+ Get Involved
+
+  Learn how you, for one, can help welcome our new Android overlords.
+ More »
+
+
-
-
-  |
-
- Download
- The Android SDK has the tools, sample code, and docs you need to create great apps.
- Learn more »
- |
-
-
- |
-
-
-  |
-
- Publish
- Android Market is an open service that lets you distribute your apps to handsets.
- Learn more »
- |
-
-
- |
-
+
+ Build a Device
+
+ So,
+ you think you have what it takes to build an Android device? We'll see;
+ we'll see.
+ More »
+
+
-
+ Compatibility
+
+ There's more to this than
+ just booting the Linux kernel. Don't be evil, be compatible.
+ More »
+
+ |
-
-
-
-
-
+
diff --git a/pdk/docs/porting/audio.jd b/pdk/docs/porting/audio.jd
new file mode 100755
index 000000000..e82788f63
--- /dev/null
+++ b/pdk/docs/porting/audio.jd
@@ -0,0 +1,61 @@
+page.title=Audio
+pdk.version=1.0
+doc.type=porting
+@jd:body
+
+
+
+
+
AudioHardwareInterface serves as the glue between proprietary audio drivers and the Android AudioFlinger service, the core audio service that handles all audio-related requests from applications.
+
+
+Solid elements represent Android blocks and dashed elements represent partner-specific blocks.
+
+
+
+
Building an Audio Library
+
+
To implement an audio driver, create a shared library that implements the interface defined in AudioHardwareInterface.h. You must name your shared library libaudio.so so that it will get loaded from /system/lib at runtime. Place libaudio sources and Android.mk in vendor/acme/chipset_or_board/libaudio/.
+
The following stub Android.mk file ensures that libaudio compiles and links to the appropriate libraries:
+
+
+LOCAL_PATH := $(call my-dir)
+include $(CLEAR_VARS)
+
+LOCAL_MODULE := libaudio
+
+LOCAL_SHARED_LIBRARIES := \
+ libcutils \
+ libutils \
+ libmedia \
+ libhardware
+
+LOCAL_SRC_FILES += MyAudioHardware.cpp
+
+LOCAL_CFLAGS +=
+
+LOCAL_C_INCLUDES +=
+
+LOCAL_STATIC_LIBRARIES += libaudiointerface
+
+include $(BUILD_SHARED_LIBRARY)
+
+
+
+
Interface
+
+
+
+
Note: This document relies on some Doxygen-generated content that appears in an iFrame below. To return to the Doxygen default content for this page, click here.
+
+
+
diff --git a/pdk/docs/porting/bluetooth.jd b/pdk/docs/porting/bluetooth.jd
new file mode 100755
index 000000000..e9749827b
--- /dev/null
+++ b/pdk/docs/porting/bluetooth.jd
@@ -0,0 +1,193 @@
+page.title=Bluetooth
+pdk.version=1.0
+doc.type=porting
+@jd:body
+
+
+
+
Android's Bluetooth stack uses BlueZ version 3.36 for GAP, SDP, and RFCOMM profiles, and is a SIG-qualified Bluetooth 2.0 + EDR host stack.
+
+
Bluez is GPL licensed, so the Android framework interacts with userspace bluez code through D-BUS IPC to avoid proprietary code.
+
+
Headset and Handsfree (v1.5) profiles are implemented in the Android framework and are both tightly coupled with the Phone App. These profiles are also SIG qualified.
+
+
The diagram below offers a library-oriented view of the Bluetooth stack. Click Bluetooth Process Diagram for a process-oriented view.
+
+
+
+Solid elements represent Android blocks and dashed elements represent partner-specific blocks.
+
+
+
+
Porting
+
+
BlueZ is Bluetooth 2.0 compatible and should work with any 2.0 chipset. There are two integration points:
+
+- UART driver
+- Bluetooth Power On / Off
+
+
+
+
+
UART Driver
+
+
The BlueZ kernel sub-system attaches to your hardware-specific UART driver using the hciattach daemon.
+
For example, for MSM7201A, this is drivers/serial/msm_serial.c. You may also need to edit command line options to hciattach via init.rc.
+
+
+
Bluetooth Power On / Off
+
+
The method for powering on and off your bluetooth chip varies from Android V 1.0 to post 1.0.
+
+
+- 1.0: Android framework writes a 0 or 1 to
/sys/modules/board_[PLATFORM]/parameters/bluetooth_power_on.
+
+- Post 1.0: Android framework uses the linux
rfkill API. See arch/arm/mach-msm/board-trout-rfkill.c for an example.
+
+
+
+
Compiling
+
+
To compile Android with Bluetooth support enabled, add the following line to BoardConfig.mk.
+
+BOARD_HAVE_BLUETOOTH := true
+
+
+
Troubleshooting
+
Debugging
+
To debug your bluetooth implementation, start by reading the logs (adb logcat) and look for ERRROR and WARNING messages regarding Bluetooth.
+ Andoird uses Bluez, which comes with some useful debugging tools. The snippet below provides examples in a suggested order:
+
+hciconfig -a # print BT chipset address and features. Useful to check if you can communicate with your BT chipset.
+hcidump -XVt # print live HCI UART traffic.
+hcitool scan # scan for local devices. Useful to check if RX/TX works.
+l2ping ADDRESS # ping another BT device. Useful to check if RX/TX works.
+sdptool records ADDRESS # request the SDP records of another BT device.
+
+
+
Deamon Logs
+
Deamon logs for hcid (STDOUT) and hciattach (STDERR) are sent to /dev/null by default. Edit init.rc and init.PLATFORM.rc to run these daemons under logwrapper, which redirects output to logcat.
+
hciconfig -a and hcitool
+
If you compile your own system.img for Android, and hciconfig -a works but hcitool scan doesn't, try installing the firmware for the Bluetooth chipset. This firmware isn't yet available in the open source codebase, but you can adb pull and then adb pushit from a stock T-Mobile G1 (located in /etc/firmware/brf6300.bin).
+
+
Tools
+
+
BlueZ provides a rich set of command line tools for debugging and interacting with the Bluetooth sub-system, including:
+
+hciconfighcitoolhcidumpsdptooldbus-senddbus-monitor
+
+
+
+
Feature Support
+
This section provides a change history of Bluetooth features added in each Android release and provides some rough guidance as to future features.
+
Android 1.0 release
+
Platform features
+
+ - Based on Bluez 3.36 and Linux Kernel 2.6.25
+ - Bluetooth 2.0+EDR host stack
+ - Headset Profile 1.0 in Audio Gateway role
+ - Handsfree Profile 1.5 in Audio Gateway role
+
+ - Three-way calling
+ - Phonebook over AT commands
+
+
+
+
Qualifications
+
+ - QDID B014524: Host stack (SDP, L2CAP, GAP, RFCOMM, SPP)
+ - QDID B014624: EPL for HTC Dream (HSP, HFP)
+
+
Example products
+
+ - HTC Dream / T-Mobile G1
+
+
+
Android 1.1 release
+
No Bluetooth changes since 1.0
+
+
Android 1.5 release (cupcake)
+
Platform features
+
+ - Based on Bluez 3.36 with Linux Kernel 2.6.27
+ - Bluetooth 2.0+EDR host stack
+
+ - Support for auto-pairing with '0000' devices
+
+ - Headset Profile 1.1 in Audio Gateway role
+ - Handsfree Profile 1.5 in Audio Gateway role
+
+ - Three-way calling
+ - Phonebook over AT commands
+ - Volume synchronization
+ - eSCO
+ - Extensive bug fixes and compatibility improvements
+
+ - Stereo Bluetooth (A2DP 1.2) in Source role
+
+ - AVDTP 1.2 in Acceptor and Initiator roles
+ - GAVDTP 1.0 in Acceptor and Initiator roles
+ - 44.1 khz, stereo, software SBC codec
+
+ - Remote Control (AVRCP 1.0) in Target role
+
+ - AVCTP 1.3 in Target role
+ - play/pause/stop/prev/next
+
+
+
Qualifications
+
+ - QDID B015261: Host stack (SDP, L2CAP, GAP, RFCOMM, SPP, AVCTP, AVRCP, GAVDP, AVDTP, A2DP)
+ - QDID B015262: EPL for HTC Sapphire (HSP, HFP)
+
+
+
Future releases
+
This section offers a rough guide of which features the team is developing for the next release. This feature list may change without notice. It isn't possible to post scheduling advice to the mailing lists.
+
+ - Java Bluetooth API
+ - Bluez 4.x with Linux Kernel 2.6.29
+ - More profiles...
+ - Bluetooth 2.1+EDR
+
+
+
Development Notes
+
+ - HID Support
+ Cupcake features some early work—Bluez has an HID plugin, external/bluez/utils/input/Android.mk, which gets compiled.
+
+You can interact directly with this plugin using dbus-send and dbus-monitor. While not officially supported, you should be able to connect and use a HID keyboard and mouse using the Bluez HID plugin API. Next steps include plumbing the plugin API in the Android Java framework and offering better support for HID input methods (new keymaps and mouse support).
+
+
+ - Tethering - DUN and PAN Support
+ Cupcake features some early work—Bluez has has DUN and PAN daemons which get compiled and external/bluez/utils/dun/Android.mk
+ external/bluez/utils/pan/Android.mk
+BNEP support is compiled into the kernel with cupcake.
+
+While not officially supported, you should be able to run dund or pand daemons and, using pppd or iptables, test tethering support. Next steps include plubming the DBUS APIs to these daemons up into the Android Java framework and adding code to setup the network paths via pppd and / or iptables.
+
+
+ - Emulator Support
+ The Android emulator does not support Bluetooth at this time and there currently aren't any plans for its support.
+
+
+ - Bluetooth 2.1 and Simple Pairing Support
+ In order to support these features, Android needs to move to a Bluez 4.x version. This change is not scheduled at this time.
+
diff --git a/pdk/docs/porting/bluetooth/bluetooth_process.jd b/pdk/docs/porting/bluetooth/bluetooth_process.jd
new file mode 100755
index 000000000..ea46f231e
--- /dev/null
+++ b/pdk/docs/porting/bluetooth/bluetooth_process.jd
@@ -0,0 +1,7 @@
+page.title=Bluetooth Process Diagram
+pdk.version=1.0
+doc.type=guide
+@jd:body
+
+
The diagram below offers a process-oriented architectural overview of Android's Bluetooth stack. Click Bluetooth to return to the Bluetooth overview page.
+
diff --git a/pdk/docs/porting/bluetooth/images/androidBluetoothProcessDiagram.jpg b/pdk/docs/porting/bluetooth/images/androidBluetoothProcessDiagram.jpg
new file mode 100755
index 000000000..687218018
Binary files /dev/null and b/pdk/docs/porting/bluetooth/images/androidBluetoothProcessDiagram.jpg differ
diff --git a/pdk/docs/porting/bring_up.jd b/pdk/docs/porting/bring_up.jd
new file mode 100755
index 000000000..022c18534
--- /dev/null
+++ b/pdk/docs/porting/bring_up.jd
@@ -0,0 +1,359 @@
+page.title=Bring Up
+pdk.version=1.0
+doc.type=porting
+@jd:body
+
+
Once your code is built and you have verified that all necessary directories exist, power on and test your device with basic bring up, as described below. Bring up tests are typically designed to stress certain aspects of your system and allow you to characterize the device's behavior.
+
+
1. Confirm a Clean Installation of a Basic Linux Kernel
+
Before considering Android-specific modifications to the Linux kernel, verify that you can build, deploy, and boot a core Linux kernel on your target hardware.
+
+
2. Modify Your Kernel Configuration to Accommodate Android Drivers
+
Your kernel configuration file should include the following:
+
+#
+# Android
+#
+# CONFIG_ANDROID_GADGET is not set
+# CONFIG_ANDROID_RAM_CONSOLE is not set
+CONFIG_ANDROID_POWER=y
+CONFIG_ANDROID_POWER_STAT=y
+CONFIG_ANDROID_LOGGER=y
+# CONFIG_ANDROID_TIMED_GPIO is not set
+CONFIG_ANDROID_BINDER_IPC=y
+
+
3. Write Drivers
+
Android ships with default drivers for all basic functionality but you'll likely want to write your own drivers (or at least customize the default drivers) for your own device depending on your hardware configuration. See the following topics for examples of how to write your own drivers.
+
+
+
4. Burn Images to Flash
+
An image represents the state of a system or part of a system stored in non-volatile memory. The build process should produce the following system images:
+
+ - bootloader: The bootloader is a small program responsible for initiating loading of the operating system.
+ - boot:
+ - recovery:
+ - system: The system image stores a snapshot of the Android operating system.
+ - data: The data image stores user data. Anything not saved to the
device/data directory will be lost on reboot.
+
+
+ - kernel: The kernel represents the most basic element of an operating system. Android's Linux kernel is responsible for managing the system's resources and acts as an abstraction layer between hardware and a system's applications.
+ - ramdisk: RAMdisk defines a portion of Random Access Memory (RAM) that gets used as if it were a hard drive.
+
+
+
Configure the bootloader to load the kernel and RAMdisk into RAM and pass the RAMdisk address to the kernel on startup.
+
+
5. Boot the kernel and mount the RAMdisk.
+
+
6. Debug Android-specific init programs on RAMdisk
+
Android-specific init programs are found in device/system/init. Add LOG messages to help you debug potential problems with the LOG macro defined in device/system/init/init.c.
+
The init program directly mounts all filesystems and devices using either hard-coded file names or device names generated by probing the sysfs filesystem (thereby eliminating the need for a /etc/fstab file in Android). After device/system files are mounted, init reads /etc/init.rc and invokes the programs listed there (one of the first of which is the console shell).
+
+
7. Verify that applications have started
+
Once the shell becomes available, execute % ps to confirm that the following applications are running:
+
+ /system/bin/logd/sbin/adbd/system/bin/usbd/system/bin/debuggerd/system/bin/rild/system/bin/app_process/system/bin/runtime/system/bin/dbus-daemonsystem_server
+
Each of these applications is embedded Linux C/C++ and you can use any standard Linux debugging tool to troubleshoot applications that aren't running. Execute % make showcommands to determine precise build commands. gdbserver (the GNU debugger) is available in the bin directory of the system partition (please see http://sourceware.org/gdb/ for more information).
+
+
8. Pulling it all together
+
If bring up was successful, you should see the following Java applications (with icons) visible on the LCD panel:
+
+ - com.google.android.phone: The Android contact application.
+ - com.google.android.home
+ - android.process.google.content
+
+
If they are not visible or unresponsive to keypad control, run the framebuffer/keypad tests.
+
+
+
Android Init Language
+
+
+
The Android Init Language consists of four broad classes of statements:
+
+ - Actionn
+ - Commands
+ - Services
+ - Options
+
+
The language syntax includes the following conventions:
+
+ - All classes are line-oriented and consist of tokens separated by whitespace. c-style backslash escapes may be used to insert whitespace into a token. Double quotes may also be used to prevent whitespace from breaking text into multiple tokens. A backslash
+ appearing as the last character on a line is used for line-folding.
+ - Lines that start with a # (leading whitespace allowed) are comments.
+ - Actions and Services implicitly declare new sections. All commands
+ or options belong to the section most recently declared. Commands
+ or options before the first section are ignored.
+ - Actions and Services have unique names. If a second Action or Service is declared with the same name as an existing one, it is ignored as an error.
+
+
Actions
+
Actions are named sequences of commands. Actions have a trigger used to determine when the action should occur. When an event
+ occurs which matches an action's trigger, that action is added to
+ the tail of a to-be-executed queue (unless it is already on the
+ queue).
+
+ Each action in the queue is dequeued in sequence. Each command in
+ an action is executed in sequence. Init handles other activities
+ (such as, device creation/destruction, property setting, process restarting) "between" the execution of the commands in activities.
+
Actions take the form of:
+
+on <trigger>
+ <command>
+ <command>
+ <command>
+
+
Services
+
Services are programs that init launches and (optionally) restarts
+when they exit.
+
Services take the form of:
+
+ service <name> <pathname> [ <argument> ]*
+ <option>
+ <option>
+ ...
+
+
Options
+
Options are modifiers to services that affect how and when init
+runs a service. Options are described in the table below:
+
+
+ | Option | Description |
+
+ disabled |
+ This service will not automatically start with its class. It must be explicitly started by name. |
+
+
+ socket <type> <name> <perm> [ <user> [ <group> ] ] |
+ Create a unix domain socket named /dev/socket/<name> and pass its fd to the launched process. Valid <type> values include dgram and stream. user and group default to 0. |
+
+
+ user <username> |
+ Change to username before exec'ing this service. Currently defaults to root. |
+
+
+ group <groupname> [ <groupname> ]* |
+ Change to groupname before exec'ing this service. Additional groupnames beyond the first, which is required, are used to set additional groups of the process (with setgroups()). Currently defaults to root. |
+
+
+ capability [ <capability> ]+ |
+ Set linux capability before exec'ing this service |
+
+
+ oneshot |
+ Do not restart the service when it exits. |
+
+
+ class <name> |
+ Specify a class name for the service. All services in a named class must start and stop together. A service is considered of class "default" if one is not specified via the class option. |
+
+
+
Triggers
+
Triggers are strings used to match certain kinds of events that cause an action to occur.
+
+
+ | Trigger |
+ Description |
+
+
+ boot |
+ This is the first trigger that occurs when init starts (after /init.conf is loaded). |
+
+
+ <name>=<value> |
+ Triggers of this form occur when the property <name> is set to the specific value <value>. |
+
+
+ device-added-<path>
+ device-removed-<path> |
+ Triggers of these forms occur when a device node is added or removed. |
+
+
+ service-exited-<name> |
+ Triggers of this form occur when the specified service exits. |
+
+
+
+ Commands
+
+
+ | Command |
+ Description |
+
+
+ exec <path> [ <argument> ]* |
+ Fork and execute a program (<path>). This will block until the program completes execution. Try to avoid exec. Unlike the builtin commands, it runs the risk of getting init "stuck". |
+
+
+ export <name> <value> |
+ Set the environment variable <name> equal to <value> in the global environment (which will be inherited by all processes started after this command is executed). |
+
+
+ ifup <interface> |
+ Bring the network interface <interface> online. |
+
+
+ import <filename> |
+ Parse an init config file, extending the current configuration. |
+
+
+ hostname <name> |
+ Set the host name. |
+
+
+ class_start <serviceclass> |
+ Start all services of the specified class if they are not already running. |
+
+
+ class_stop <serviceclass> |
+ Stop all services of the specified class if they are currently running. |
+
+
+ domainname <name> |
+ Set the domain name. |
+
+
+ insmod <path> |
+ Install the module at <path>. |
+
+
+ mkdir <path> |
+ Make a directory at <path>. |
+
+
+ mount <type> <device> <dir> [ <mountoption> ]* |
+ Attempt to mount the named device at the directory <dir> <device>. This may be of the form mtd@name to specify a mtd block device by name. |
+
+
+ setkey |
+ - currenlty undefined - |
+
+
+ setprop <name> <value> |
+ Set system property <name> to <value>. |
+
+
+ setrlimit <resource> <cur> <max> |
+ Set the rlimit for a resource. |
+
+
+ start <service> |
+ Start a service running if it is not already running. |
+
+
+ stop <service> |
+ Stop a service from running if it is currently running. |
+
+
+ symlink <target> <path> |
+ Create a symbolic link at <path> with the value <target>. |
+
+
+ write <path> <string> [ <string> ]* |
+ Open the file at <path> and write one or more strings to it with write(2). |
+
+
+
Properties
+ Init updates some system properties to provide some insight into
+ what it's doing:
+
+
+ | Property |
+ Description |
+
+
+ init.action |
+ Equal to the name of the action currently being executed or "" if none. |
+
+
+ init.command |
+ Equal to the command being executed or "" if none. |
+
+
+ init.svc.<name> |
+ State of a named service ("stopped", "running", or "restarting"). |
+
+
+
Example init.conf
+
The following snippet is an incomplete example of the init.conf file, simply meant to give you an idea of what a proper configuration resembles.
+
+on boot
+ export PATH /sbin:/system/sbin:/system/bin
+ export LD_LIBRARY_PATH /system/lib
+
+ mkdir /dev
+ mkdir /proc
+ mkdir /sys
+
+
+ mount tmpfs tmpfs /dev
+ mkdir /dev/pts
+ mkdir /dev/socket
+ mount devpts devpts /dev/pts
+ mount proc proc /proc
+ mount sysfs sysfs /sys
+
+
+ write /proc/cpu/alignment 4
+
+
+ ifup lo
+
+
+ hostname localhost
+ domainname localhost
+
+
+ mount yaffs2 mtd@system /system
+ mount yaffs2 mtd@userdata /data
+
+
+ import /system/etc/init.conf
+
+
+ class_start default
+
+
+service adbd /sbin/adbd
+ user adb
+ group adb
+
+
+service usbd /system/bin/usbd -r
+ user usbd
+ group usbd
+ socket usbd 666
+
+
+service zygote /system/bin/app_process -Xzygote /system/bin --zygote
+ socket zygote 666
+
+
+service runtime /system/bin/runtime
+ user system
+ group system
+
+
+on device-added-/dev/compass
+ start akmd
+
+
+on device-removed-/dev/compass
+ stop akmd
+
+
+service akmd /sbin/akmd
+ disabled
+ user akmd
+ group akmd
+
diff --git a/pdk/docs/porting/build_cookbook.jd b/pdk/docs/porting/build_cookbook.jd
new file mode 100755
index 000000000..d6190862a
--- /dev/null
+++ b/pdk/docs/porting/build_cookbook.jd
@@ -0,0 +1,556 @@
+page.title=Build Cookbook
+pdk.version=1.0
+doc.type=porting
+@jd:body
+
+
+
+
+
The Android Build Cookbook offers code snippets to help you quickly implement some common build tasks. For additional instruction, please see the other build documents in this section.
+
Building a simple APK
+
+ LOCAL_PATH := $(call my-dir)
+ include $(CLEAR_VARS)
+
+ # Build all java files in the java subdirectory
+ LOCAL_SRC_FILES := $(call all-subdir-java-files)
+
+ # Name of the APK to build
+ LOCAL_PACKAGE_NAME := LocalPackage
+
+ # Tell it to build an APK
+ include $(BUILD_PACKAGE)
+
+
Building a APK that depends on a static .jar file
+
+ LOCAL_PATH := $(call my-dir)
+ include $(CLEAR_VARS)
+
+ # List of static libraries to include in the package
+ LOCAL_STATIC_JAVA_LIBRARIES := static-library
+
+ # Build all java files in the java subdirectory
+ LOCAL_SRC_FILES := $(call all-subdir-java-files)
+
+ # Name of the APK to build
+ LOCAL_PACKAGE_NAME := LocalPackage
+
+ # Tell it to build an APK
+ include $(BUILD_PACKAGE)
+
+
Building a APK that should be signed with the platform key
+
+ LOCAL_PATH := $(call my-dir)
+ include $(CLEAR_VARS)
+
+ # Build all java files in the java subdirectory
+ LOCAL_SRC_FILES := $(call all-subdir-java-files)
+
+ # Name of the APK to build
+ LOCAL_PACKAGE_NAME := LocalPackage
+
+ LOCAL_CERTIFICATE := platform
+
+ # Tell it to build an APK
+ include $(BUILD_PACKAGE)
+
+
Building a APK that should be signed with a specific vendor key
+
+ LOCAL_PATH := $(call my-dir)
+ include $(CLEAR_VARS)
+
+ # Build all java files in the java subdirectory
+ LOCAL_SRC_FILES := $(call all-subdir-java-files)
+
+ # Name of the APK to build
+ LOCAL_PACKAGE_NAME := LocalPackage
+
+ LOCAL_CERTIFICATE := vendor/example/certs/app
+
+ # Tell it to build an APK
+ include $(BUILD_PACKAGE)
+
+
Adding a prebuilt APK
+
+ LOCAL_PATH := $(call my-dir)
+ include $(CLEAR_VARS)
+
+ # Module name should match apk name to be installed.
+ LOCAL_MODULE := LocalModuleName
+ LOCAL_SRC_FILES := $(LOCAL_MODULE).apk
+ LOCAL_MODULE_CLASS := APPS
+ LOCAL_MODULE_SUFFIX := $(COMMON_ANDROID_PACKAGE_SUFFIX)
+
+ include $(BUILD_PREBUILT)
+
+
Adding a Static Java Library
+
+ LOCAL_PATH := $(call my-dir)
+ include $(CLEAR_VARS)
+
+ # Build all java files in the java subdirectory
+ LOCAL_SRC_FILES := $(call all-subdir-java-files)
+
+ # Any libraries that this library depends on
+ LOCAL_JAVA_LIBRARIES := android.test.runner
+
+ # The name of the jar file to create
+ LOCAL_MODULE := sample
+
+ # Build a static jar file.
+ include $(BUILD_STATIC_JAVA_LIBRARY)
+
+
Android.mk Variables
+
+
These are the variables that you'll commonly see in Android.mk files, listed
+alphabetically. First, a note on the variable naming:
+
+
+ - LOCAL_ - These variables are set per-module. They are cleared
+ by the
include $(CLEAR_VARS) line, so you can rely on them
+ being empty after including that file. Most of the variables you'll use
+ in most modules are LOCAL_ variables.
+ - PRIVATE_ - These variables are make-target-specific variables. That
+ means they're only usable within the commands for that module. It also
+ means that they're unlikely to change behind your back from modules that
+ are included after yours. This
+ link to the make documentation
+ describes more about target-specific variables.
+
+ - HOST_ and TARGET_ - These contain the directories
+ and definitions that are specific to either the host or the target builds.
+ Do not set variables that start with HOST_ or TARGET_ in your makefiles.
+
+ - BUILD_ and CLEAR_VARS - These contain the names of
+ well-defined template makefiles to include. Some examples are CLEAR_VARS
+ and BUILD_HOST_PACKAGE.
+ - Any other name is fair-game for you to use in your Android.mk. However,
+ remember that this is a non-recursive build system, so it is possible that
+ your variable will be changed by another Android.mk included later, and be
+ different when the commands for your rule / module are executed.
+
+
+
+
+ | Parameter |
+ Description |
+
+
+| LOCAL_AAPT_FLAGS |
+ |
+
+
+| LOCAL_ACP_UNAVAILABLE |
+ |
+
+
+| LOCAL_ADDITIONAL_JAVA_DIR |
+ |
+
+
+| LOCAL_AIDL_INCLUDES |
+ |
+
+
+| LOCAL_ALLOW_UNDEFINED_SYMBOLS |
+ |
+
+
+| LOCAL_ARM_MODE |
+ |
+
+
+| LOCAL_ASFLAGS |
+ |
+
+
+| LOCAL_ASSET_DIR |
+ |
+
+
+| LOCAL_ASSET_FILES |
+In Android.mk files that include $(BUILD_PACKAGE) set this
+to the set of files you want built into your app. Usually:
+LOCAL_ASSET_FILES += $(call find-subdir-assets)
|
+
+
+| LOCAL_BUILT_MODULE_STEM |
+ |
+
+
+| LOCAL_C_INCLUDES |
+Additional directories to instruct the C/C++ compilers to look for header
+files in. These paths are rooted at the top of the tree. Use
+LOCAL_PATH if you have subdirectories of your own that you
+want in the include paths. For example:
+
+LOCAL_C_INCLUDES += extlibs/zlib-1.2.3
+LOCAL_C_INCLUDES += $(LOCAL_PATH)/src
+
+You should not add subdirectories of include to
+LOCAL_C_INCLUDES, instead you should reference those files
+in the #include statement with their subdirectories. For
+example:
+#include <utils/KeyedVector.h>
+not #include <KeyedVector.h>
|
+
+
+| LOCAL_CC |
+If you want to use a different C compiler for this module, set LOCAL_CC
+to the path to the compiler. If LOCAL_CC is blank, the appropriate default
+compiler is used. |
+
+
+| LOCAL_CERTIFICATE |
+ |
+
+
+| LOCAL_CFLAGS |
+If you have additional flags to pass into the C or C++ compiler, add
+them here. For example:
+ LOCAL_CFLAGS += -DLIBUTILS_NATIVE=1
|
+
+
+| LOCAL_CLASSPATH |
+ |
+
+
+| LOCAL_COMPRESS_MODULE_SYMBOLS |
+ |
+
+
+| LOCAL_COPY_HEADERS |
+The set of files to copy to the install include tree. You must also
+supply LOCAL_COPY_HEADERS_TO.
+This is going away because copying headers messes up the error messages, and
+may lead to people editing those headers instead of the correct ones. It also
+makes it easier to do bad layering in the system, which we want to avoid. We
+also aren't doing a C/C++ SDK, so there is no ultimate requirement to copy any
+headers. |
+
+
+| LOCAL_COPY_HEADERS_TO |
+The directory within "include" to copy the headers listed in
+LOCAL_COPY_HEADERS to.
+This is going away because copying headers messes up the error messages, and
+may lead to people editing those headers instead of the correct ones. It also
+makes it easier to do bad layering in the system, which we want to avoid. We
+also aren't doing a C/C++ SDK, so there is no ultimate requirement to copy any
+headers. |
+
+
+| LOCAL_CPP_EXTENSION |
+If your C++ files end in something other than ".cpp",
+you can specify the custom extension here. For example:
+LOCAL_CPP_EXTENSION := .cc
+Note that all C++ files for a given module must have the same
+extension; it is not currently possible to mix different extensions. |
+
+
+| LOCAL_CPPFLAGS |
+If you have additional flags to pass into only the C++ compiler, add
+them here. For example:
+ LOCAL_CPPFLAGS += -ffriend-injection
+LOCAL_CPPFLAGS is guaranteed to be after LOCAL_CFLAGS
+on the compile line, so you can use it to override flags listed in
+LOCAL_CFLAGS |
+
+
+| LOCAL_CXX |
+If you want to use a different C++ compiler for this module, set LOCAL_CXX
+to the path to the compiler. If LOCAL_CXX is blank, the appropriate default
+compiler is used. |
+
+
+| LOCAL_DX_FLAGS |
+ |
+
+
+| LOCAL_EXPORT_PACKAGE_RESOURCES |
+ |
+
+
+| LOCAL_FORCE_STATIC_EXECUTABLE |
+If your executable should be linked statically, set
+LOCAL_FORCE_STATIC_EXECUTABLE:=true. There is a very short
+list of libraries that we have in static form (currently only libc). This is
+really only used for executables in /sbin on the root filesystem. |
+
+
+| LOCAL_GENERATED_SOURCES |
+Files that you add to LOCAL_GENERATED_SOURCES will be
+automatically generated and then linked in when your module is built.
+See the Custom Tools template makefile for an
+example. |
+
+
+| LOCAL_INSTRUMENTATION_FOR |
+ |
+
+
+| LOCAL_INSTRUMENTATION_FOR_PACKAGE_NAME |
+ |
+
+
+| LOCAL_INTERMEDIATE_SOURCES |
+ |
+
+
+| LOCAL_INTERMEDIATE_TARGETS |
+ |
+
+
+| LOCAL_IS_HOST_MODULE |
+ |
+
+
+| LOCAL_JAR_MANIFEST |
+ |
+
+
+| LOCAL_JARJAR_RULES |
+ |
+
+
+| LOCAL_JAVA_LIBRARIES |
+When linking Java apps and libraries, LOCAL_JAVA_LIBRARIES
+specifies which sets of java classes to include. Currently there are
+two of these: core and framework.
+In most cases, it will look like this:
+LOCAL_JAVA_LIBRARIES := core framework
+Note that setting LOCAL_JAVA_LIBRARIES is not necessary
+(and is not allowed) when building an APK with
+"include $(BUILD_PACKAGE)". The appropriate libraries
+will be included automatically. |
+
+
+| LOCAL_JAVA_RESOURCE_DIRS |
+ |
+
+
+| LOCAL_JAVA_RESOURCE_FILES |
+ |
+
+
+| LOCAL_JNI_SHARED_LIBRARIES |
+ |
+
+
+| LOCAL_LDFLAGS |
+You can pass additional flags to the linker by setting
+LOCAL_LDFLAGS. Keep in mind that the order of parameters is
+very important to ld, so test whatever you do on all platforms. |
+
+
+| LOCAL_LDLIBS |
+LOCAL_LDLIBS allows you to specify additional libraries
+that are not part of the build for your executable or library. Specify
+the libraries you want in -lxxx format; they're passed directly to the
+link line. However, keep in mind that there will be no dependency generated
+for these libraries. It's most useful in simulator builds where you want
+to use a library preinstalled on the host. The linker (ld) is a particularly
+fussy beast, so it's sometimes necessary to pass other flags here if you're
+doing something sneaky. Some examples:
+LOCAL_LDLIBS += -lcurses -lpthread
+LOCAL_LDLIBS += -Wl,-z,origin
+
|
+
+
+| LOCAL_MODULE |
+LOCAL_MODULE is the name of what's supposed to be generated
+from your Android.mk. For exmample, for libkjs, the LOCAL_MODULE
+is "libkjs" (the build system adds the appropriate suffix -- .so .dylib .dll).
+For app modules, use LOCAL_PACKAGE_NAME instead of
+LOCAL_MODULE. |
+
+
+| LOCAL_MODULE_PATH |
+Instructs the build system to put the module somewhere other than what's
+normal for its type. If you override this, make sure you also set
+LOCAL_UNSTRIPPED_PATH if it's an executable or a shared library
+so the unstripped binary has somewhere to go. An error will occur if you forget
+to.
+See Putting modules elsewhere for more. |
+
+
+| LOCAL_MODULE_STEM |
+ |
+
+
+| LOCAL_MODULE_TAGS |
+Set LOCAL_MODULE_TAGS to any number of whitespace-separated
+tags. This variable controls what build flavors the package gets included in. For example:
+
+ user: include this in user/userdebug buildseng: include this in eng buildstests: the target is a testing target and makes it available for testsoptional: don't include this |
+
+
+| LOCAL_NO_DEFAULT_COMPILER_FLAGS |
+ |
+
+
+| LOCAL_NO_EMMA_COMPILE |
+ |
+
+
+| LOCAL_NO_EMMA_INSTRUMENT |
+ |
+
+
+| LOCAL_NO_STANDARD_LIBRARIES |
+ |
+
+
+| LOCAL_OVERRIDES_PACKAGES |
+ |
+
+
+| LOCAL_PACKAGE_NAME |
+LOCAL_PACKAGE_NAME is the name of an app. For example,
+Dialer, Contacts, etc. |
+
+
+| LOCAL_POST_PROCESS_COMMAND |
+For host executables, you can specify a command to run on the module
+after it's been linked. You might have to go through some contortions
+to get variables right because of early or late variable evaluation:
+module := $(HOST_OUT_EXECUTABLES)/$(LOCAL_MODULE)
+LOCAL_POST_PROCESS_COMMAND := /Developer/Tools/Rez -d __DARWIN__ -t APPL\
+ -d __WXMAC__ -o $(module) Carbon.r
+
+ |
+
+
+| LOCAL_PREBUILT_EXECUTABLES |
+When including $(BUILD_PREBUILT) or $(BUILD_HOST_PREBUILT), set these to
+executables that you want copied. They're located automatically into the
+right bin directory. |
+
+
+| LOCAL_PREBUILT_JAVA_LIBRARIES |
+ |
+
+
+| LOCAL_PREBUILT_LIBS |
+When including $(BUILD_PREBUILT) or $(BUILD_HOST_PREBUILT), set these to
+libraries that you want copied. They're located automatically into the
+right lib directory. |
+
+
+| LOCAL_PREBUILT_OBJ_FILES |
+ |
+
+
+| LOCAL_PREBUILT_STATIC_JAVA_LIBRARIES |
+ |
+
+
+| LOCAL_PRELINK_MODULE |
+ |
+
+
+| LOCAL_REQUIRED_MODULES |
+Set LOCAL_REQUIRED_MODULES to any number of whitespace-separated
+module names, like "libblah" or "Email". If this module is installed, all
+of the modules that it requires will be installed as well. This can be
+used to, e.g., ensure that necessary shared libraries or providers are
+installed when a given app is installed. |
+
+
+| LOCAL_RESOURCE_DIR |
+ |
+
+
+| LOCAL_SDK_VERSION |
+ |
+
+
+| LOCAL_SHARED_LIBRARIES |
+These are the libraries you directly link against. You don't need to
+pass transitively included libraries. Specify the name without the suffix:
+ LOCAL_SHARED_LIBRARIES := \
+ libutils \
+ libui \
+ libaudio \
+ libexpat \
+ libsgl
+
|
+
+
+| LOCAL_SRC_FILES |
+The build system looks at LOCAL_SRC_FILES to know what source
+files to compile -- .cpp .c .y .l .java. For lex and yacc files, it knows
+how to correctly do the intermediate .h and .c/.cpp files automatically. If
+the files are in a subdirectory of the one containing the Android.mk, prefix
+them with the directory name:
+LOCAL_SRC_FILES := \
+ file1.cpp \
+ dir/file2.cpp
+
|
+
+
+| LOCAL_STATIC_JAVA_LIBRARIES |
+ |
+
+
+| LOCAL_STATIC_LIBRARIES |
+These are the static libraries that you want to include in your module.
+Mostly, we use shared libraries, but there are a couple of places, like
+executables in sbin and host executables where we use static libraries instead.
+ LOCAL_STATIC_LIBRARIES := \
+ libutils \
+ libtinyxml
+
|
+
+
+| LOCAL_UNINSTALLABLE_MODULE |
+ |
+
+
+| LOCAL_UNSTRIPPED_PATH |
+Instructs the build system to put the unstripped version of the module
+somewhere other than what's normal for its type. Usually, you override this
+because you overrode LOCAL_MODULE_PATH for an executable or a
+shared library. If you overrode LOCAL_MODULE_PATH, but not
+LOCAL_UNSTRIPPED_PATH, an error will occur.
+See Putting modules elsewhere for more. |
+
+
+| LOCAL_WHOLE_STATIC_LIBRARIES |
+These are the static libraries that you want to include in your module without allowing
+the linker to remove dead code from them. This is mostly useful if you want to add a static library
+to a shared library and have the static library's content exposed from the shared library.
+ LOCAL_WHOLE_STATIC_LIBRARIES := \
+ libsqlite3_android
+
|
+
+
+| LOCAL_YACCFLAGS |
+Any flags to pass to invocations of yacc for your module. A known limitation
+here is that the flags will be the same for all invocations of YACC for your
+module. This can be fixed. If you ever need it to be, just ask.
+ LOCAL_YACCFLAGS := -p kjsyy
|
+
+
+| OVERRIDE_BUILT_MODULE_PATH |
+ |
+
+
+
diff --git a/pdk/docs/porting/build_new_device.jd b/pdk/docs/porting/build_new_device.jd
new file mode 100755
index 000000000..55b03553f
--- /dev/null
+++ b/pdk/docs/porting/build_new_device.jd
@@ -0,0 +1,242 @@
+page.title=Configuring a New Product
+pdk.version=1.0
+doc.type=porting
+@jd:body
+
+
+
+
+
+
+
Detailed Instructions
+
+
The steps below describe how to configure makefiles for new mobile devices and products running Android.
+
+ - Create a company directory in
//vendor/.
+
+ mkdir vendor/<company_name>
+ - Create a
products directory beneath the company directory you created in step 1.
+
+ mkdir vendor/<company_name>/products/
+ - Create a product-specific makefile, called
vendor/<company_name>/products/<first_product_name>.mk, that includes at least the following code:
+
+ $(call inherit-product, $(SRC_TARGET_DIR)/product/generic.mk)
+ #
+ # Overrides
+ PRODUCT_NAME := <first_product_name>
+ PRODUCT_DEVICE := <board_name>
+ -
+ Additional product-specific variables can be added to this Product Definition
+file.
+
+ - In the
products directory, create an AndroidProducts.mk file that point to (and is responsible for finding) the individual product make files.
+
+ #
+ # This file should set PRODUCT_MAKEFILES to a list of product makefiles
+ # to expose to the build system. LOCAL_DIR will already be set to
+ # the directory containing this file.
+ #
+ # This file may not rely on the value of any variable other than
+ # LOCAL_DIR; do not use any conditionals, and do not look up the
+ # value of any variable that isn't set in this file or in a file that
+ # it includes.
+ #
+
+ PRODUCT_MAKEFILES := \
+ $(LOCAL_DIR)/first_product_name.mk \
+ - Create a board-specific directory beneath your company directory that matches the
PRODUCT_DEVICE variable <board_name> referenced in the product-specific make file above. This will include a make file that gets accessed by any product using this board.
+
+ mkdir vendor/<company_name>/<board_name>
+ - Create a
BoardConfig.mk file in the directory created in the previous step (vendor/<company_name>/<board_name>).
+
+ # These definitions override the defaults in config/config.make for <board_name>
+ #
+ # TARGET_NO_BOOTLOADER := false
+ # TARGET_HARDWARE_3D := false
+ #
+ TARGET_USE_GENERIC_AUDIO := true
+ - If you wish to modify system properties, create a
system.prop file in your <board_name> directory(vendor/<company_name>/<board_name>).
+
+ # system.prop for
+ # This overrides settings in the products/generic/system.prop file
+ #
+ # rild.libpath=/system/lib/libreference-ril.so
+ # rild.libargs=-d /dev/ttyS0
+ - Add a pointer to
<second_product_name>.mk within products/AndroidProducts.mk.
+
+ PRODUCT_MAKEFILES := \
+ $(LOCAL_DIR)/first_product_name.mk \
+ $(LOCAL_DIR)/second_product_name.mk
+ - An
Android.mk file must be included in vendor/<company_name>/<board_name> with at least the following code:
+
+ # make file for new hardware from
+ #
+ LOCAL_PATH := $(call my-dir)
+ #
+ # this is here to use the pre-built kernel
+ ifeq ($(TARGET_PREBUILT_KERNEL),)
+ TARGET_PREBUILT_KERNEL := $(LOCAL_PATH)/kernel
+ endif
+ #
+ file := $(INSTALLED_KERNEL_TARGET)
+ ALL_PREBUILT += $(file)
+ $(file): $(TARGET_PREBUILT_KERNEL) | $(ACP)
+ $(transform-prebuilt-to-target)
+ #
+ # no boot loader, so we don't need any of that stuff..
+ #
+ LOCAL_PATH := vendor/<company_name>/<board_name>
+ #
+ include $(CLEAR_VARS)
+ #
+ # include more board specific stuff here? Such as Audio parameters.
+ #
+
+
+- To create a second product for the same board, create a second product-specific make file called
vendor/company_name/products/<second_product_name>.mk that includes:
+
+ $(call inherit-product, $(SRC_TARGET_DIR)/product/generic.mk)
+ #
+ # Overrides
+ PRODUCT_NAME := <second_product_name>
+ PRODUCT_DEVICE := <board_name>
+
+
By now, you should have two new products, called <first_product_name> and <second_product_name> associated with <company_name>. To verify that a product is properly configured (<first_product_name>, for example), execute the following:
+
+ . build/envsetup.sh
+ make PRODUCT-<first_product_name>-user
+
+
You should find new build binaries located in /out/target/product/<board_name>.
+
+
+
New Product File Tree
+
+
The file tree below illustrates what your own system should look like after completing the steps above.
+
+
+ <company_name>
+ <board_name>
+ Android.mkproduct_config.mksystem.prop
+ products
+ AndroidProducts.mk<first_product_name>.mk<second_product_name>.mk
+
+
+
+
+
Product Definition Files
+
+
Product-specific variables are defined in product definition files. A product definition file can inherit from other product definition files, thus reducing the need to copy and simplifying maintenance.
+
Variables maintained in a product definition files include:
+
+
+
+ | Parameter |
+ Description |
+ Example |
+
+
+ | PRODUCT_NAME |
+ End-user-visible name for the overall product. Appears in the "About the phone" info. |
+ |
+
+
+ | PRODUCT_MODEL |
+ End-user-visible name for the end product |
+ |
+
+
+ | PRODUCT_LOCALES |
+ A space-separated list of two-letter language code, two-letter country code pairs that describe several settings for the user, such as the UI language and time, date and currency formatting. The first locale listed in PRODUCT_LOCALES is is used if the locale has never been set before. |
+ en_GB de_DE es_ES fr_CA |
+
+
+ | PRODUCT_PACKAGES |
+ Lists the APKs to install. |
+ Calendar Contacts |
+
+
+ | PRODUCT_DEVICE |
+ Name of the industrial design |
+ dream |
+
+
+ | PRODUCT_MANUFACTURER |
+ Name of the manufacturer |
+ acme |
+
+
+ | PRODUCT_BRAND |
+ The brand (e.g., carrier) the software is customized for, if any |
+ |
+
+
+ | PRODUCT_PROPERTY_OVERRIDES |
+ List of property assignments in the format "key=value" |
+ |
+
+
+ | PRODUCT_COPY_FILES |
+ List of words like source_path:destination_path. The file at the source path should be copied to the destination path when building this product. The rules for the copy steps are defined in config/Makefile |
+ |
+
+
+ | PRODUCT_OTA_PUBLIC_KEYS |
+ List of OTA public keys for the product |
+ |
+
+
+ | PRODUCT_POLICY |
+ Indicate which policy this product should use |
+ |
+
+
+ | PRODUCT_PACKAGE_OVERLAYS |
+ Indicate whether to use default resources or add any product specific overlays |
+ vendor/acme/overlay |
+
+
+ | PRODUCT_CONTRIBUTORS_FILE |
+ HTML file containing the contributors to the project. |
+ |
+
+
+ | PRODUCT_TAGS |
+ list of space-separated words for a given product |
+ |
+
+
+
+
+
The snippet below illustrates a typical product definition file.
+
+$(call inherit-product, build/target/product/generic.mk)
+
+#Overrides
+PRODUCT_NAME := MyDevice
+PRODUCT_MANUFACTURER := acme
+PRODUCT_BRAND := acme_us
+PRODUCT_LOCALES := en_GB es_ES fr_FR
+PRODUCT_PACKAGE_OVERLAYS := vendor/acme/overlay
+
+
+
+
diff --git a/pdk/docs/porting/build_system.jd b/pdk/docs/porting/build_system.jd
new file mode 100755
index 000000000..e5811bd4f
--- /dev/null
+++ b/pdk/docs/porting/build_system.jd
@@ -0,0 +1,270 @@
+page.title=Android Build System
+pdk.version=1.0
+doc.type=porting
+@jd:body
+
+
+
+
+
Android uses a custom build system to generate tools, binaries, and documentation. This document provides an overview of Android's build system and instructions for doing a simple build.
+
Android's build system is make based and requires a recent version of GNU Make (note that Android uses advanced features of GNU Make that may not yet appear on the GNU Make web site). Before continuing, check your version of make by running % make -v. If you don't have version 3.80 or greater, you need to upgrade your version of make.
+
+
+
+
+
Understanding the makefile
+
+
A makefile defines how to build a particular application. Makefiles typically include all of the following elements:
+
+ - Name: Give your build a name (
LOCAL_MODULE := <build_name>).
+ - Local Variables: Clear local variables with CLEAR_VARS (
include $(CLEAR_VARS)).
+ - Files: Determine which files your application depends upon (
LOCAL_SRC_FILES := main.c).
+ - Tags: Define tags, as necessary (
LOCAL_MODULE_TAGS := eng development).
+ - Libraries: Define whether your application links with other libraries (
LOCAL_SHARED_LIBRARIES := cutils).
+ - Template file: Include a template file to define underlining make tools for a particular target (
include $(BUILD_EXECUTABLE)).
+
+
+
The following snippet illustrates a typical makefile.
+
+LOCAL_PATH := $(my-dir)
+include $(CLEAR_VARS)
+LOCAL_MODULE := <buil_name>
+LOCAL_SRC_FILES := main.c
+LOCAL_MODULE_TAGS := eng development
+LOCAL_SHARED_LIBRARIES := cutils
+include $(BUILD_EXECUTABLE)
+(HOST_)EXECUTABLE, (HOST_)JAVA_LIBRARY, (HOST_)PREBUILT, (HOST_)SHARED_LIBRARY,
+ (HOST_)STATIC_LIBRARY, PACKAGE, JAVADOC, RAW_EXECUTABLE, RAW_STATIC_LIBRARY,
+ COPY_HEADERS, KEY_CHAR_MAP
+
+
The snippet above includes artificial line breaks to maintain a print-friendly document.
+
+
+
Layers
+
+
The build hierarchy includes the abstraction layers described in the table below.
+
+
Each layer relates to the one above it in a one-to-many relationship. For example, an arch can have more than one board and each board can have more than one device. You may define an element in a given layer as a specialization of an element in the same layer, thus eliminating copying and simplifying maintenance.
+
+
+
+ | Layer |
+ Example |
+ Description |
+
+
+ | Product |
+ myProduct, myProduct_eu, myProduct_eu_fr, j2, sdk |
+ The product layer defines a complete specification of a shipping product, defining which modules to build and how to configure them. You might offer a device in several different versions based on locale, for example, or on features such as a camera. |
+
+
+ | Device |
+ myDevice, myDevice_eu, myDevice_eu_lite |
+ The device layer represents the physical layer of plastic on the device. For example, North American devices probably include QWERTY keyboards whereas devices sold in France probably include AZERTY keyboards. Peripherals typically connect to the device layer. |
+
+
+ | Board |
+ sardine, trout, goldfish |
+ The board layer represents the bare schematics of a product. You may still connect peripherals to the board layer. |
+
+
+ | Arch |
+ arm (arm5te) (arm6), x86, 68k |
+ The arch layer describes the processor running on your board. |
+
+
+
+
Building the Android Platform
+
+
This section describes how to build the default version of Android. Once you are comfortable with a generic build, then you can begin to modify Android for your own target device.
+
+
+
Device Code
+
+
To do a generic build of android, source build/envsetup.sh, which contains necessary variable and function definitions, as described below.
+
+% cd $TOP
+
+% . build/envsetup.sh
+
+# pick a configuration using choosecombo
+% choosecombo
+
+% make -j4 PRODUCT-generic-user
+
+
You can also replace user with eng for a debug engineering build:
+
+
+% make -j4 PRODUCT-generic-eng
+
+
+
These Build Variants differ in terms of debug options and packages installed.
+
+
+
Cleaning Up
+
+
Execute % m clean to clean up the binaries you just created. You can also execute % m clobber to get rid of the binaries of all combos. % m clobber is equivalent to removing the //out/ directory where all generated files are stored.
+
+
+
Speeding Up Rebuilds
+
+
The binaries of each combo are stored as distinct sub-directories of //out/, making it possible to quickly switch between combos without having to recompile all sources each time.
+
However, performing a clean rebuild is necessary if the build system doesn't catch changes to environment variables or makefiles. If this happens often, you should define the USE_CCACHE environment variable as shown below:
+
+% export USE_CCACHE=1
+
+
Doing so will force the build system to use the ccache compiler cache tool, which reduces recompiling all sources.
+
+
ccache binaries are provided in //prebuilt/... and don't need to get installed on your system.
+
+
+
Troubleshooting
+
+
The following error is likely caused by running an outdated version of Java.
+
+device Dex: core UNEXPECTED TOP-LEVEL ERROR:
+java.lang.NoSuchMethodError: method java.util.Arrays.hashCode with
+signature ([Ljava.lang.Object;)I was not found.
+ at com.google.util.FixedSizeList.hashCode(FixedSizeList.java:66)
+ at com.google.rop.code.Rop.hashCode(Rop.java:245)
+ at java.util.HashMap.hash(libgcj.so.7)
+[...]
+
+
dx is a Java program that uses facilities first made available in Java version 1.5. Check your version of Java by executing % java -version in the shell you use to build. You should see something like:
+
+java version "1.5.0_07"
+Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_07-164)
+Java HotSpot(TM) Client VM (build 1.5.0_07-87, mixed mode, sharing)
+
+
If you do have Java 1.5 or later and your receive this error, verify that you have properly updated your PATH variable.
+
+
+
Building the Android Kernel
+
+
This section describes how to build Android's default kernel. Once you are comfortable with a generic build, then you can begin to modify Android drivers for your own target device.
+
+
+
To build the kernel base, switch to the device directory (/home/joe/android/device) in order to establish variables and run:
+
+% . build/envsetup.sh
+% partner_setup generic
+
+
Then switch to the kernel directory /home/joe/android/kernel.
+
+
+
Checking Out a Branch
+
+
The default branch is always android. To check out a different branch, execute the following:
+
+
+% git checkout --track -b android-mydevice origin/android-mydevice
+ //Branch android-mydevice set up to track remote branch
+% refs/remotes/origin/android-mydevice.
+ //Switched to a new branch "android-mydevice"
+
+
+
To simplify code management, give your local branch the same name as the remote branch it is tracking (as illustrated in the snippet above). Switch between branches by executing % git checkout <branchname>.
+
+
+
Verifying Location
+
+
Find out which branches exist (both locally and remotely) and which one is active (marked with an asterisk) by executing the following:
+
+% git branch -a
+ android
+* android-mydevice
+ origin/HEAD
+ origin/android
+ origin/android-mydevice
+ origin/android-mychipset
+
+
To only see local branches, omit the -a flag.
+
+
+
Building the Kernel
+
+
To build the kernel, execute:
+
+% make -j4
+
+
+
Build Variants
+
+
+When building for a particular product, it's often useful to have minor
+variations on what is ultimately the final release build. These are the
+currently-defined build variants:
+
+
+
+
+
+ eng
+ |
+
+ This is the default flavor. A plain make is the
+ same as make eng.
+
+ - Installs modules tagged with:
eng, debug,
+ user, and/or development.
+ - Installs non-APK modules that have no tags specified.
+
- Installs APKs according to the product definition files, in
+ addition to tagged APKs.
+
ro.secure=0
+ ro.debuggable=1
+ ro.kernel.android.checkjni=1
+ adb is enabled by default.
+ |
+
+
+
+ user
+ |
+
+ make user
+
+ This is the flavor intended to be the final release bits.
+
+ - Installs modules tagged with
user.
+ - Installs non-APK modules that have no tags specified.
+ - Installs APKs according to the product definition files; tags
+ are ignored for APK modules.
+ ro.secure=1 ro.debuggable=0 adb is disabled by default. |
+
+
+
+ userdebug
+ |
+
+ make userdebug
+
+ The same as user, except:
+
+ - Also installs modules tagged with
debug.
+ ro.debuggable=1
+ adb is enabled by default.
+ |
+
+
+
+
+If you build one flavor and then want to build another, you should run
+make installclean between the two makes to guarantee that
+you don't pick up files installed by the previous flavor. make
+clean will also suffice, but it takes a lot longer.
+
diff --git a/pdk/docs/porting/camera.jd b/pdk/docs/porting/camera.jd
new file mode 100755
index 000000000..0571fb5ac
--- /dev/null
+++ b/pdk/docs/porting/camera.jd
@@ -0,0 +1,76 @@
+page.title=Camera
+pdk.version=1.0
+doc.type=porting
+@jd:body
+
+
+
+
Android's camera subsystem connects the camera application to the application framework and user space libraries, which in turn communicate with the camera hardware layer that operates the physical camera.
+
The diagram below illustrates the structure of the camera subsystem.
+
+
+
+
Building a Camera Library
+
+
To implement a camera driver, create a shared library that implements the interface defined in CameraHardwareInterface.h. You must name your shared library libcamera.so so that it will get loaded from /system/lib at runtime. Place libcamera sources and Android.mk in vendor/acme/chipset_or_board/libcamera/.
+
The following stub Android.mk file ensures that libcamera compiles and links to the appropriate libraries:
+
+LOCAL_PATH := $(call my-dir)
+include $(CLEAR_VARS)
+
+LOCAL_MODULE := libcamera
+
+LOCAL_SHARED_LIBRARIES := \
+ libutils \
+ librpc \
+ liblog
+
+LOCAL_SRC_FILES += MyCameraHardware.cpp
+
+LOCAL_CFLAGS +=
+
+LOCAL_C_INCLUDES +=
+
+LOCAL_STATIC_LIBRARIES += \
+ libcamera-common \
+ libclock-rpc \
+ libcommondefs-rpc
+
+include $(BUILD_SHARED_LIBRARY)
+
+
+
+
Sequence Diagrams
+
+
+
+
Preview
+
+
The following diagram illustrates the sequence of function calls and actions necessary for your camera to preview.
+
+
+
+
Taking a Picture
+
+
The following diagram illustrates the sequence of function calls and actions necessary for your camera to take a picture.
+
+
+
+
Interface
+
+
+
+
Note: This document relies on some Doxygen-generated content that appears in an iFrame below. To return to the Doxygen default content for this page, click here.
+
+
+
diff --git a/pdk/docs/porting/customization.jd b/pdk/docs/porting/customization.jd
new file mode 100755
index 000000000..7c11a8eb8
--- /dev/null
+++ b/pdk/docs/porting/customization.jd
@@ -0,0 +1,321 @@
+page.title=Customization
+pdk.version=1.0
+doc.type=porting
+@jd:body
+
+
+
+
+
+
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:
+
+
- Create a 320x480 image,
splashscreen.jpg in this example.
+- Using ImageMagick, convert your .jpg file to .r format:
+
+convert screen.jpg screen.r
+
+
+- Use the rgb2565 application to convert the image to 565 format:
+
+rgb2565 < screen.rgb > screen.565
+
+
+- Use fastboot to flash the image to the device:
+
+fastboot flash splash1 screen.565
+
+
+
+
+
+
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:
+
+- Automatic Configuration: 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.
+- Manual Configuration: 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.
+- WAP / SMS Push Configuration: 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.
+
+
+
+
+
+
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/.
+
diff --git a/pdk/docs/porting/dalvik.jd b/pdk/docs/porting/dalvik.jd
new file mode 100755
index 000000000..50b749903
--- /dev/null
+++ b/pdk/docs/porting/dalvik.jd
@@ -0,0 +1,355 @@
+page.title=Dalvik
+pdk.version=1.0
+doc.type=porting
+@jd:body
+
+
+
+
+The Dalvik virtual machine is intended to run on a variety of platforms.
+The baseline system is expected to be a variant of UNIX (Linux, BSD, Mac
+OS X) running the GNU C compiler. Little-endian CPUs have been exercised
+the most heavily, but big-endian systems are explicitly supported.
+
+There are two general categories of work: porting to a Linux system
+with a previously unseen CPU architecture, and porting to a different
+operating system. This document covers the former.
+
+
+
+
Core Libraries
+
+
+The native code in the core libraries (chiefly dalvik/libcore,
+but also dalvik/vm/native) is written in C/C++ and is expected
+to work without modification in a Linux environment. Much of the code
+comes directly from the Apache Harmony project.
+
+The core libraries pull in code from many other projects, including
+OpenSSL, zlib, and ICU. These will also need to be ported before the VM
+can be used.
+
+
+
+
JNI Call Bridge
+
+
+Most of the Dalvik VM runtime is written in portable C. The one
+non-portable component of the runtime is the JNI call bridge. Simply put,
+this converts an array of integers into function arguments of various
+types, and calls a function. This must be done according to the C calling
+conventions for the platform. The task could be as simple as pushing all
+of the arguments onto the stack, or involve complex rules for register
+assignment and stack alignment.
+
+To ease porting to new platforms, the
+open-source FFI library (Foreign Function Interface) is used when a
+custom bridge is unavailable. FFI is not as fast as a native implementation,
+and the optional performance improvements it does offer are not used, so
+writing a replacement is a good first step.
+
+The code lives in dalvik/vm/arch/*, with the FFI-based version
+in the "generic" directory. There are two source files for each architecture.
+One defines the call bridge itself:
+
+void dvmPlatformInvoke(void* pEnv, ClassObject* clazz, int argInfo,
+int argc, const u4* argv, const char* signature, void* func,
+JValue* pReturn)
+
+This will invoke a C/C++ function declared:
+
+ return_type func(JNIEnv* pEnv, Object* this [, args])
+
or (for a "static" method):
+ return_type func(JNIEnv* pEnv, ClassObject* clazz [, args])
+
+The role of dvmPlatformInvoke is to convert the values in
+argv into C-style calling conventions, call the method, and
+then place the return type into pReturn (a union that holds
+all of the basic JNI types). The code may use the method signature
+(a DEX "shorty" signature, with one character for the return type and one
+per argument) to determine how to handle the values.
+
+The other source file involved here defines a 32-bit "hint". The hint
+is computed when the method's class is loaded, and passed in as the
+"argInfo" argument. The hint can be used to avoid scanning the ASCII
+method signature for things like the return value, total argument size,
+or inter-argument 64-bit alignment restrictions.
+
+
+
Interpreter
+
+
+The Dalvik runtime includes two interpreters, labeled "portable" and "fast".
+The portable interpreter is largely contained within a single C function,
+and should compile on any system that supports gcc. (If you don't have gcc,
+you may need to disable the "threaded" execution model, which relies on
+gcc's "goto table" implementation; look for the THREADED_INTERP define.)
+
+The fast interpreter uses hand-coded assembly fragments. If none are
+available for the current architecture, the build system will create an
+interpreter out of C "stubs". The resulting "all stubs" interpreter is
+quite a bit slower than the portable interpreter, making "fast" something
+of a misnomer.
+
+The fast interpreter is enabled by default. On platforms without native
+support, you may want to switch to the portable interpreter. This can
+be controlled with the dalvik.vm.execution-mode system
+property. For example, if you:
+
+adb shell "echo dalvik.vm.execution-mode = int:portable >> /data/local.prop"
+
+and reboot, the Android app framework will start the VM with the portable
+interpreter enabled.
+
+
+
+
Mterp Interpreter Structure
+
+
+There may be significant performance advantages to rewriting the
+interpreter core in assembly language, using architecture-specific
+optimizations. In Dalvik this can be done one instruction at a time.
+
+The simplest way to implement an interpreter is to have a large "switch"
+statement. After each instruction is handled, the interpreter returns to
+the top of the loop, fetches the next instruction, and jumps to the
+appropriate label.
+
+An improvement on this is called "threaded" execution. The instruction
+fetch and dispatch are included at the end of every instruction handler.
+This makes the interpreter a little larger overall, but you get to avoid
+the (potentially expensive) branch back to the top of the switch statement.
+
+Dalvik mterp goes one step further, using a computed goto instead of a goto
+table. Instead of looking up the address in a table, which requires an
+extra memory fetch on every instruction, mterp multiplies the opcode number
+by a fixed value. By default, each handler is allowed 64 bytes of space.
+
+Not all handlers fit in 64 bytes. Those that don't can have subroutines
+or simply continue on to additional code outside the basic space. Some of
+this is handled automatically by Dalvik, but there's no portable way to detect
+overflow of a 64-byte handler until the VM starts executing.
+
+The choice of 64 bytes is somewhat arbitrary, but has worked out well for
+ARM and x86.
+
+In the course of development it's useful to have C and assembly
+implementations of each handler, and be able to flip back and forth
+between them when hunting problems down. In mterp this is relatively
+straightforward. You can always see the files being fed to the compiler
+and assembler for your platform by looking in the
+dalvik/vm/mterp/out directory.
+
+The interpreter sources live in dalvik/vm/mterp. If you
+haven't yet, you should read dalvik/vm/mterp/README.txt now.
+
+
+
+
Getting Started With Mterp
+
+
+Getting started:
+
+- Decide on the name of your architecture. For the sake of discussion,
+let's call it
myarch.
+ - Make a copy of
dalvik/vm/mterp/config-allstubs to
+dalvik/vm/mterp/config-myarch.
+ - Create a
dalvik/vm/mterp/myarch directory to hold your
+source files.
+ - Add
myarch to the list in
+dalvik/vm/mterp/rebuild.sh.
+ - Make sure
dalvik/vm/Android.mk will find the files for
+your architecture. If $(TARGET_ARCH) is configured this
+will happen automatically.
+
+
+You now have the basic framework in place. Whenever you make a change, you
+need to perform two steps: regenerate the mterp output, and build the
+core VM library. (It's two steps because we didn't want the build system
+to require Python 2.5. Which, incidentally, you need to have.)
+
+- In the
dalvik/vm/mterp directory, regenerate the contents
+of the files in dalvik/vm/mterp/out by executing
+./rebuild.sh. Note there are two files, one in C and one
+in assembly.
+ - In the
dalvik directory, regenerate the
+libdvm.so library with mm. You can also use
+make libdvm from the top of the tree.
+
+
+This will leave you with an updated libdvm.so, which can be pushed out to
+a device with adb sync or adb push. If you're
+using the emulator, you need to add make snod (System image,
+NO Dependency check) to rebuild the system image file. You should not
+need to do a top-level "make" and rebuild the dependent binaries.
+
+At this point you have an "all stubs" interpreter. You can see how it
+works by examining dalvik/vm/mterp/cstubs/entry.c. The
+code runs in a loop, pulling out the next opcode, and invoking the
+handler through a function pointer. Each handler takes a "glue" argument
+that contains all of the useful state.
+
+Your goal is to replace the entry method, exit method, and each individual
+instruction with custom implementations. The first thing you need to do
+is create an entry function that calls the handler for the first instruction.
+After that, the instructions chain together, so you don't need a loop.
+(Look at the ARM or x86 implementation to see how they work.)
+
+Once you have that, you need something to jump to. You can't branch
+directly to the C stub because it's expecting to be called with a "glue"
+argument and then return. We need a C stub "wrapper" that does the
+setup and jumps directly to the next handler. We write this in assembly
+and then add it to the config file definition.
+
+To see how this works, create a file called
+dalvik/vm/mterp/myarch/stub.S that contains one line:
+
+/* stub for ${opcode} */
+
+Then, in
dalvik/vm/mterp/config-myarch, add this below the
+
handler-size directive:
+
+# source for the instruction table stub
+asm-stub myarch/stub.S
+
+
+Regenerate the sources with ./rebuild.sh, and take a look
+inside dalvik/vm/mterp/out/InterpAsm-myarch.S. You should
+see 256 copies of the stub function in a single large block after the
+dvmAsmInstructionStart label. The stub.S
+code will be used anywhere you don't provide an assembly implementation.
+
+Note that each block begins with a .balign 64 directive.
+This is what pads each handler out to 64 bytes. Note also that the
+${opcode} text changed into an opcode name, which should
+be used to call the C implementation (dvmMterp_${opcode}).
+
+The actual contents of stub.S are up to you to define.
+See entry.S and stub.S in the armv5te
+or x86 directories for working examples.
+
+If you're working on a variation of an existing architecture, you may be
+able to use most of the existing code and just provide replacements for
+a few instructions. Look at the armv4t implementation as
+an example.
+
+
+
+
Replacing Stubs
+
+
+There are roughly 230 Dalvik opcodes, including some that are inserted by
+dexopt and aren't described in the
+Dalvik bytecode documentation. Each
+one must perform the appropriate actions, fetch the next opcode, and
+branch to the next handler. The actions performed by the assembly version
+must exactly match those performed by the C version (in
+dalvik/vm/mterp/c/OP_*).
+
+It is possible to customize the set of "optimized" instructions for your
+platform. This is possible because optimized DEX files are not expected
+to work on multiple devices. Adding, removing, or redefining instructions
+is beyond the scope of this document, and for simplicity it's best to stick
+with the basic set defined by the portable interpreter.
+
+Once you have written a handler that looks like it should work, add
+it to the config file. For example, suppose we have a working version
+of OP_NOP. For demonstration purposes, fake it for now by
+putting this into dalvik/vm/mterp/myarch/OP_NOP.S:
+
+/* This is my NOP handler */
+
+
+Then, in the op-start section of config-myarch, add:
+
+ op OP_NOP myarch
+
+
+This tells the generation script to use the assembly version from the
+myarch directory instead of the C version from the c
+directory.
+
+Execute ./rebuild.sh. Look at InterpAsm-myarch.S
+and InterpC-myarch.c in the out directory. You
+will see that the OP_NOP stub wrapper has been replaced with our
+new code in the assembly file, and the C stub implementation is no longer
+included.
+
+As you implement instructions, the C version and corresponding stub wrapper
+will disappear from the output files. Eventually you will have a 100%
+assembly interpreter.
+
+
+
+
Interpreter Switching
+
+
+The Dalvik VM actually includes a third interpreter implementation: the debug
+interpreter. This is a variation of the portable interpreter that includes
+support for debugging and profiling.
+
+When a debugger attaches, or a profiling feature is enabled, the VM
+will switch interpreters at a convenient point. This is done at the
+same time as the GC safe point check: on a backward branch, a method
+return, or an exception throw. Similarly, when the debugger detaches
+or profiling is discontinued, execution transfers back to the "fast" or
+"portable" interpreter.
+
+Your entry function needs to test the "entryPoint" value in the "glue"
+pointer to determine where execution should begin. Your exit function
+will need to return a boolean that indicates whether the interpreter is
+exiting (because we reached the "bottom" of a thread stack) or wants to
+switch to the other implementation.
+
+See the entry.S file in x86 or armv5te
+for examples.
+
+
+
+
Testing
+
+
+A number of VM tests can be found in dalvik/tests. The most
+useful during interpreter development is 003-omnibus-opcodes,
+which tests many different instructions.
+
+The basic invocation is:
+
+$ cd dalvik/tests
+$ ./run-test 003
+
+
+This will run test 003 on an attached device or emulator. You can run
+the test against your desktop VM by specifying --reference
+if you suspect the test may be faulty. You can also use
+--portable and --fast to explictly specify
+one Dalvik interpreter or the other.
+
+Some instructions are replaced by dexopt, notably when
+"quickening" field accesses and method invocations. To ensure
+that you are testing the basic form of the instruction, add the
+--no-optimize option.
+
+There is no in-built instruction tracing mechanism. If you want
+to know for sure that your implementation of an opcode handler
+is being used, the easiest approach is to insert a "printf"
+call. For an example, look at common_squeak in
+dalvik/vm/mterp/armv5te/footer.S.
+
+At some point you need to ensure that debuggers and profiling work with
+your interpreter. The easiest way to do this is to simply connect a
+debugger or toggle profiling. (A future test suite may include some
+tests for this.)
+
+
+
diff --git a/pdk/docs/porting/debugging_gdb.jd b/pdk/docs/porting/debugging_gdb.jd
new file mode 100755
index 000000000..17ff471bc
--- /dev/null
+++ b/pdk/docs/porting/debugging_gdb.jd
@@ -0,0 +1,146 @@
+page.title=Debugging with GDB
+pdk.version=1.0
+doc.type=porting
+@jd:body
+
+
+
+
The current version of envsetup.sh has a gdbclient command that handles much of the setup. For example, to attach the
+ already-running globaltime application, execute the following, making sure that: 1) you do this from the same window used to build the software on the device you are debugging and 2) verify that the symbols in the object files in the build tree match up with what is installed on the device or emulator.
+
+gdbclient app_process :5039 globaltime
+
+
Debugging
+
+
Short Instructions
+
Android runs gdbserver on the device and an ARM aware gdb, named arm-eabi-gdb, on the desktop machine.
+
+ - First you need to
+ run
gdbserver on the device:
+
+ gdbserver :5039 /system/bin/executable
+
+
+ The :5039 tells gdbserver to listen on port 5039 on the localhost, which adb bridges from the host to the device. executable represents the command to debug, a common one being runtime -s which starts the entire system all running in a single process.
+
+
+ - Launch
gdb on the desktop.
+ This can be
+ done easily with the following command in the shell from which you built:
+
+gdbclient executable
+
+
+
+
At this point gdb will connect with your device
+ and you should be
+ able to enter c to have the device start executing inside of the
+ desktop gdb session.
+
+
Detailed Instructions
+
If the short instructions don't work, these detailed instructions should:
+
+ - On the device, launch a new command:
+
gdbserver :5039 /system/bin/executable
+ or attach to an existing process:
+ gdbserver :5039 --attach pid
+
+ - On your workstation, forward port 5039 to the device with adb:
+
adb forward tcp:5039 tcp:5039
+
+ - Start a special version of
gdb that lives in the "prebuilt" area of the source tree:
+ prebuilt/Linux/toolchain-eabi-4.2.1/bin/arm-eabi-gdb (for Linux)
+ prebuilt/darwin-x86/toolchain-eabi-4.2.1/bin/arm-eabi-gdb (for Darwin)
+ - If you can't find either special version of
gdb, run find prebuilt -name arm-eabi-gdb in your source tree to find and run the latest version:
+
+prebuilt/Linux/toolchain-eabi-4.2.1/bin/arm-eabi-gdb out/target/product/product-name/symbols/system/bin/executable
+
+
+ Where product-name is the name of the device product that you're building (for example, sooner),
+ and executable is the program to debug (usually app_process for an application).
+
+ Make sure to use the copy of the executable in the symbols directory, not the
+ primary android directory, because the one in the primary directory has
+ been stripped of its debugging information.
+ - In
gdb, Tell gdb where to find the shared libraries that will get loaded:
+
+set solib-absolute-prefix /absolute-source-path/out/target/product/product-name/symbols
+set solib-search-path /absolute-source-path/out/target/product/product-name/symbols/system/lib
+
+
+ absolute-source-path is the path to your source tree; for example, /work/device or /Users/hoser/android/device.
+ product-name is the same as above; for example, sooner.
+
+ Make sure you specify the correct directories—gdb may not tell you if you make a mistake.
+ - Connect to the device by issuing the
gdb command:
+
+target remote :5039
+
+
+
+ The :5039 tells gdb to connect to the localhost port 5039, which is bridged to the device by adb.
+
+ You may need to inspire gdb to load some symbols by typing:
+ shared
+
+
+
You should be connected and able to debug as you normally would. You can ignore the error about not
+ finding the location for the thread creation breakpoint. It will be found when
+ the linker loads libc into your process before hitting main(). Also note that
+ the gdb remote protocol doesn't have a way for the device to
+ tell the host about
+ newly created threads so you will not always see notifications about newly
+ created threads. Info about other threads will be queried from the
+ device when a
+ breakpoint is hit or you ask for it by running info thread.
+
Just-In-Time Debug Feature
+If you see the red LED flashing it means a process is in that new
+state (crashed and waiting for GDB connection). If this happens to the
+system process, most likely your device will be frozen at this point.
Do not press the home key. Bring the device to someone who can
+debug native crashes and ask for advice.
+If you're in the field and just want your device to continue as it
+would have without this feature (like cylonning), press home (a
+tombstone will be recorded as usual).
+
+To enable a process to be debugged this way, you need to set a property:
+
+adb shell setprop debug.db.uid 10000
+
+and all processes with a
uid <= 10000 will be trapped in this
+manner. When one of them crashes, the tombstone is processed as usual, an explicit message is printed into the log, and the red LED starts
+flashing waiting for the Home key to be depressed (in which case it
+continues execution as usual).
+
+I/DEBUG ( 27): ********************************************************
+I/DEBUG ( 27): * process 82 crashed. debuggerd waiting for gdbserver
+I/DEBUG ( 27): *
+I/DEBUG ( 27): * adb shell gdbserver :port --attach 82 &
+I/DEBUG ( 27): *
+I/DEBUG ( 27): * and press the HOME key.
+I/DEBUG ( 27): ********************************************************
+
+
When you see the entry above, make sure adb is forwarding port 5039 (you only need to do this once,
+ unless the ADB server dies) and execute:
+
% adb forward tcp:5039 tcp:5039
+Execute the line shown in the debug output, substituting 5039 for the proper
port:
+
+% adb shell gdbserver :5039 --attach 82 &
+
+
If the crashing process is based off zygote (that is, system_server and all
+ applications), the default values for the gdbclient command, app_process binary and port 5039, are correct, so you can execute:
+
+% cd <top of device source tree>
+% gdbclient
+
+
Otherwise you need to determine the path of the crashing binary and follow the
+ steps as mentioned above (for example, gdbclient hoser :5039 if
+ the hoser command has failed).
diff --git a/pdk/docs/porting/debugging_native.jd b/pdk/docs/porting/debugging_native.jd
new file mode 100755
index 000000000..7bb655fcb
--- /dev/null
+++ b/pdk/docs/porting/debugging_native.jd
@@ -0,0 +1,305 @@
+page.title=Debugging Native Code
+pdk.version=1.0
+doc.type=porting
+@jd:body
+
+
+
+
+
Capturing logs
+
+
To capture log output:
+
+- Produce a process list with
ps (ps -t if you want verbose thread feedback).
+- Dump kernel messages with
dmesg.
+- Get verbose log messages with
logcat '*:v' & (running in bg with & is important).
+
+
+
+
Debug Scenarios
+
+ # command to device shell (via adb)
+ % command to host pc shell
+
+
+
+
+
Crash but no exit...stuck
+
+
In this scenario, the GTalk app crashed but did not actually exit or seems stuck. Check the debug logs to see if there is anything unusual:
+
+
+# logcat &
+
+...
+E/WindowManager( 182): Window client android.util.BinderProxy@4089f948 has died!! Removing window.
+W/WindowManager( 182): **** WINDOW CLIENT android.view.WindowProxy@40882248 DIED!
+W/ActivityManager( 182): **** APPLICATION com.google.android.gtalk DIED!
+I/ServiceManager( 257): Executing: /android/bin/app_process (link=/tmp/android-servicemanager/com.google.android.gtalk, wrapper=/tmp/android-servi
+cemanager/com.google.android.gtalk)
+I/appproc ( 257): App process is starting with pid=257, class=android/activity/ActivityThread.
+I/ ( 257): java.io.FileDescriptor: class initialization
+I/SurfaceFlinger.HW( 182): About to give-up screen
+I/SurfaceFlinger.HW( 182): screen given-up
+I/SurfaceFlinger.HW( 182): Screen about to return
+I/SurfaceFlinger.HW( 182): screen returned
+I/SurfaceFlinger.HW( 182): About to give-up screen
+I/SurfaceFlinger.HW( 182): screen given-up
+I/SurfaceFlinger.HW( 182): Screen about to return
+...
+
+
+
+The logs indicate that the system launched a replacement GTalk process but that it got stuck somehow:
+
+
+
+# ps
+PID PPID VSIZE RSS WCHAN PC NAME
+257 181 45780 5292 ffffffff 53030cb4 S com.google.andr
+
+
+
+GTalk's PC is at 53030cb4. Look at the memory map to find out what lib is 0x53......
+
+
+
+# cat /proc/257/maps
+...
+51000000-5107c000 rwxp 00000000 1f:03 619 /android/lib/libutils.so
+52000000-52013000 rwxp 00000000 1f:03 639 /android/lib/libz.so
+53000000-53039000 rwxp 00000000 1f:03 668 /android/lib/libc.so
+53039000-53042000 rw-p 53039000 00:00 0
+54000000-54002000 rwxp 00000000 1f:03 658 /android/lib/libstdc++.so
+...
+
+
+
+Disassemble libc to figure out what is going on:
+
+
+
+% prebuilt/Linux/toolchain-eabi-4.2.1/bin/arm-elf-objdump -d out/target/product/sooner/symbols/android/lib/libc.so
+
+00030ca4 <__futex_wait>:
+ 30ca4: e1a03002 mov r3, r2
+ 30ca8: e1a02001 mov r2, r1
+ 30cac: e3a01000 mov r1, #0 ; 0x0
+ 30cb0: ef9000f0 swi 0x009000f0
+ 30cb4: e12fff1e bx lr
+
+
+
Blocked in a syscall
+
+
+In this scenario, the system is blocked in a syscall. To debug using gdb, first tell adb to forward the gdb port:
+
+
+
+
+% adb forward tcp:5039 tcp:5039
+
+
+
+Start the gdb server and attach to process 257 (as demonstrated in the previous example):
+
+
+
+# gdbserver :5039 --attach 257 &
+Attached; pid = 257
+Listening on port 5039
+
+% prebuilt/Linux/toolchain-eabi-4.2.1/bin/arm-elf-gdb out/target/product/sooner/system/bin/app_process
+(gdb) set solib-absolute-prefix /work/android/device/out/target/product/sooner/symbols
+(gdb) set solib-search-path /work/android/device/out/target/product/sooner/symbols/android/lib
+(gdb) target remote :5039
+Remote debugging using :5039
+0x53030cb4 in ?? ()
+Current language: auto; currently asm
+
+
+
+Don't let other threads get scheduled while we're debugging.
+You should "set scheduler-locking off" before issuing a "continue", or else your thread may get stuck on a futex or other
+spinlock because no other thread can release it.
+
+
+
+(gdb) set scheduler-locking on
+
+
+
+Ignore SIGUSR1 if you're using JamVM. Shouldn't hurt if you're not.
+
+
+
+(gdb) handle SIGUSR1 noprint
+
+(gdb) where
+#0 __futex_wait () at system/klibc/android/atomics_arm.S:88
+#1 0x53010eb8 in pthread_cond_timedwait (cond=0x12081c, mutex=0x120818, abstime=0xffffffff)
+ at system/klibc/android/pthread.c:490
+#2 0x6b01c848 in monitorWait (mon=0x120818, self=0x6b039ba4, ms=0, ns=0) at extlibs/jamvm-1.4.1/src/lock.c:194
+#3 0x6b01d1d8 in objectWait (obj=0x408091c0, ms=0, ns=0) at extlibs/jamvm-1.4.1/src/lock.c:420
+#4 0x6b01d4c8 in jamWait (clazz=0xfffffffc, mb=0x0, ostack=0x2e188) at extlibs/jamvm-1.4.1/src/natives.c:91
+#5 0x6b013b2c in resolveNativeWrapper (clazz=0x408001d0, mb=0x41798, ostack=0x2e188) at extlibs/jamvm-1.4.1/src/dll.c:236
+#6 0x6b015c04 in executeJava () at extlibs/jamvm-1.4.1/src/interp.c:2614
+#7 0x6b01471c in executeMethodVaList (ob=0x0, clazz=0x40808f20, mb=0x12563c, jargs=0xbe9229f4)
+ at extlibs/jamvm-1.4.1/src/execute.c:91
+#8 0x6b01bcd0 in Jam_CallStaticVoidMethod (env=0xfffffffc, klass=0x0, methodID=0x12563c)
+ at extlibs/jamvm-1.4.1/src/jni.c:1063
+#9 0x58025b2c in android::AndroidRuntime::callStatic (this=0xfffffffc,
+ className=0xbe922f0a "android/activity/ActivityThread", methodName=0x57000b7c "main")
+ at libs/android_runtime/AndroidRuntime.cpp:215
+#10 0x57000504 in android::app_init (className=0xbe922f0a "android/activity/ActivityThread")
+ at servers/app/library/app_init.cpp:20
+#11 0x000089b0 in android::sp<android::ProcessState>::~sp ()
+#12 0x000089b0 in android::sp<android::ProcessState>::~sp ()
+Previous frame identical to this frame (corrupt stack?)
+
+(gdb) info threads
+ 7 thread 263 __ioctl () at system/klibc/syscalls/__ioctl.S:12
+ 6 thread 262 accept () at system/klibc/syscalls/accept.S:12
+ 5 thread 261 __futex_wait () at system/klibc/android/atomics_arm.S:88
+ 4 thread 260 __futex_wait () at system/klibc/android/atomics_arm.S:88
+ 3 thread 259 __futex_wait () at system/klibc/android/atomics_arm.S:88
+ 2 thread 258 __sigsuspend () at system/klibc/syscalls/__sigsuspend.S:12
+ 1 thread 257 __futex_wait () at system/klibc/android/atomics_arm.S:88
+
+
+(gdb) thread 7
+[Switching to thread 7 (thread 263)]#0 __ioctl () at system/klibc/syscalls/__ioctl.S:12
+12 movs r0, r0
+(gdb) bt
+#0 __ioctl () at system/klibc/syscalls/__ioctl.S:12
+#1 0x53010704 in ioctl (fd=-512, request=-1072143871) at system/klibc/android/ioctl.c:22
+#2 0x51040ac0 in android::IPCThreadState::talkWithDriver (this=0x1207b8, doReceive=true) at RefBase.h:83
+#3 0x510418a0 in android::IPCThreadState::joinThreadPool (this=0x1207b8, isMain=false)
+ at libs/utils/IPCThreadState.cpp:343
+#4 0x51046004 in android::PoolThread::threadLoop (this=0xfffffe00) at libs/utils/ProcessState.cpp:52
+#5 0x51036428 in android::Thread::_threadLoop (user=0xfffffe00) at libs/utils/Threads.cpp:1100
+#6 0x58025c68 in android::AndroidRuntime::javaThreadShell (args=0x105ffe28) at libs/android_runtime/AndroidRuntime.cpp:540
+
+(gdb) thread 6
+[Switching to thread 6 (thread 262)]#0 accept () at system/klibc/syscalls/accept.S:12
+12 movs r0, r0
+(gdb) bt
+#0 accept () at system/klibc/syscalls/accept.S:12
+#1 0x6b0334e4 in jdwpAcceptConnection (state=0xfffffe00) at extlibs/jamvm-1.4.1/jdwp/JdwpNet.c:213
+#2 0x6b032660 in jdwpThreadEntry (self=0x4d020) at extlibs/jamvm-1.4.1/jdwp/JdwpMain.c:37
+#3 0x6b022c2c in shell (args=0x4d960) at extlibs/jamvm-1.4.1/src/thread.c:629
+
+(gdb) thread 5
+[Switching to thread 5 (thread 261)]#0 __futex_wait () at system/klibc/android/atomics_arm.S:88
+88 bx lr
+(gdb) bt
+#0 __futex_wait () at system/klibc/android/atomics_arm.S:88
+#1 0x53010f48 in pthread_cond_timeout (cond=0x6b039b64, mutex=0x6b039b60, msecs=0) at system/klibc/android/pthread.c:513
+#2 0x6b01c8d0 in monitorWait (mon=0x6b039b60, self=0x4d400, ms=1000, ns=272629312) at extlibs/jamvm-1.4.1/src/lock.c:183
+#3 0x6b022084 in threadSleep (thread=0x4d400, ms=1000, ns=272629312) at extlibs/jamvm-1.4.1/src/thread.c:215
+#4 0x6b00d4fc in asyncGCThreadLoop (self=0x4d400) at extlibs/jamvm-1.4.1/src/alloc.c:1179
+#5 0x6b022c2c in shell (args=0x4d480) at extlibs/jamvm-1.4.1/src/thread.c:629
+
+(gdb) thread 4
+[Switching to thread 4 (thread 260)]#0 __futex_wait () at system/klibc/android/atomics_arm.S:88
+88 bx lr
+(gdb) bt
+#0 __futex_wait () at system/klibc/android/atomics_arm.S:88
+#1 0x53010eb8 in pthread_cond_timedwait (cond=0x6b039934, mutex=0x6b039930, abstime=0x0)
+ at system/klibc/android/pthread.c:490
+#2 0x6b00b3ec in referenceHandlerThreadLoop (self=0x4d360) at extlibs/jamvm-1.4.1/src/alloc.c:1247
+#3 0x6b022c2c in shell (args=0x4d960) at extlibs/jamvm-1.4.1/src/thread.c:629
+
+(gdb) thread 3
+[Switching to thread 3 (thread 259)]#0 __futex_wait () at system/klibc/android/atomics_arm.S:88
+88 bx lr
+(gdb) bt
+#0 __futex_wait () at system/klibc/android/atomics_arm.S:88
+#1 0x53010eb8 in pthread_cond_timedwait (cond=0x6b03992c, mutex=0x6b039928, abstime=0x0)
+ at system/klibc/android/pthread.c:490
+#2 0x6b00b1dc in finalizerThreadLoop (self=0x4d8e0) at extlibs/jamvm-1.4.1/src/alloc.c:1238
+#3 0x6b022c2c in shell (args=0x4d960) at extlibs/jamvm-1.4.1/src/thread.c:629
+
+(gdb) thread 2
+[Switching to thread 2 (thread 258)]#0 __sigsuspend () at system/klibc/syscalls/__sigsuspend.S:12
+12 movs r0, r0
+(gdb) bt
+#0 __sigsuspend () at system/klibc/syscalls/__sigsuspend.S:12
+#1 0x6b023814 in dumpThreadsLoop (self=0x51b98) at extlibs/jamvm-1.4.1/src/thread.c:1107
+#2 0x6b022c2c in shell (args=0x51b58) at extlibs/jamvm-1.4.1/src/thread.c:629
+
+
+
Crash in C / C++ code
+
If it crashes, connect with aproto and run logcat on the device. You should see output like this:
+
+
+I/ActivityManager( 188): Starting activity: Intent { component=com.android.calendar.MonthScreen }
+I/ActivityManager( 188): Starting application com.android.calendar to host activity com.android.calendar.MonthScree
+n
+I/ServiceManager( 417): Executing: /android/bin/app_process (link=/android/bin/app_process, wrapper=/android/bin/app_process)
+I/DEBUG: -- observer of pid 417 starting --
+I/appproc ( 417): App process is starting with pid=417, class=android/activity/ActivityThread.
+I/DEBUG: -- observer of pid 417 exiting --
+I/DEBUG: -- observer of pid 420 starting --
+I/DEBUG: *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
+I/DEBUG: pid: 373, tid: 401 >>> android.content.providers.pim <<<
+I/DEBUG: signal 11 (SIGSEGV), fault addr 00000000
+I/DEBUG: r0 ffffffff r1 00000000 r2 00000454 r3 002136d4
+I/DEBUG: r4 002136c0 r5 40804810 r6 0022dc70 r7 00000010
+I/DEBUG: r8 0020a258 r9 00000014 10 6b039074 fp 109ffcf8
+I/DEBUG: ip 6b039e90 sp 109ffc0c lr 580239f0 pc 6b0156a0
+I/DEBUG: #01 pc 6b0156a0 /android/lib/libjamvm.so
+I/DEBUG: #01 lr 580239f0 /android/lib/libandroid_runtime.so
+I/DEBUG: #02 pc 6b01481c /android/lib/libjamvm.so
+I/DEBUG: #03 pc 6b0148a4 /android/lib/libjamvm.so
+I/DEBUG: #04 pc 6b00ebc0 /android/lib/libjamvm.so
+I/DEBUG: #05 pc 6b02166c /android/lib/libjamvm.so
+I/DEBUG: #06 pc 6b01657c /android/lib/libjamvm.so
+I/DEBUG: #07 pc 6b01481c /android/lib/libjamvm.so
+I/DEBUG: #08 pc 6b0148a4 /android/lib/libjamvm.so
+I/DEBUG: #09 pc 6b0235c0 /android/lib/libjamvm.so
+I/DEBUG: #10 pc 5300fac4 /android/lib/libc.so
+I/DEBUG: #11 pc 5300fc5c /android/lib/libc.so
+I/DEBUG: -- observer of pid 373 exiting --
+I/DEBUG: -- observer of pid 423 starting --
+
+
+
If debugging output indicates an error in C or C++ code, the addresses aren't particularly useful, but the debugging symbols aren't present on the device. Use the "stack" tool to convert these addresses to files and line numbers, for example:
+
+
+pid: 373, tid: 401 >>> android.content.providers.pim <<<
+
+ signal 11 (SIGSEGV), fault addr 00000000
+ r0 ffffffff r1 00000000 r2 00000454 r3 002136d4
+ r4 002136c0 r5 40804810 r6 0022dc70 r7 00000010
+ r8 0020a258 r9 00000014 10 6b039074 fp 109ffcf8
+ r8 0020a258 r9 00000014 10 6b039074 fp 109ffcf8
+
+ ADDR FUNCTION FILE:LINE
+ 6b0156a0 executeJava extlibs/jamvm-1.4.1/src/interp.c:2674
+ 580239f0 android_util_Parcel_freeBuffer libs/android_runtime/android_util_Binder.cpp:765
+ 6b01481c executeMethodVaList extlibs/jamvm- 1.4.1/src/execute.c:91
+ 6b0148a4 executeMethodArgs extlibs/jamvm-1.4.1/src/execute.c:67
+ 6b00ebc0 initClass extlibs/jamvm-1.4.1/src/class.c:1124
+ 6b02166c resolveMethod extlibs/jamvm- 1.4.1/src/resolve.c:197
+ 6b01657c executeJava extlibs/jamvm-1.4.1/src/interp.c:2237
+ 6b01481c executeMethodVaList extlibs/jamvm-1.4.1/src/execute.c:91
+ 6b0148a4 executeMethodArgs extlibs/jamvm- 1.4.1/src/execute.c:67
+ 6b0235c0 threadStart extlibs/jamvm-1.4.1/src/thread.c:355
+ 5300fac4 __thread_entry system/klibc/android/pthread.c:59
+ 5300fc5c pthread_create system/klibc/android/pthread.c:182
+
+
+
Or you can run logcat without any parameters and it will read from stdin. You can then paste output into the terminal or pipe it. Run logcat from the top of the tree in the environment in which you do builds so that the application can determine relative paths to the toolchain to use to decode the object files.
+
+
+
-