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.
-
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 partner/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) -- - -
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/bluetooth.jd b/pdk/docs/bluetooth.jd deleted file mode 100755 index d6865645b..000000000 --- a/pdk/docs/bluetooth.jd +++ /dev/null @@ -1,69 +0,0 @@ -page.title=Bluetooth -pdk.version=1.0 -@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 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.
- -
BlueZ is Bluetooth 2.0 compatible and should work with any 2.0 chipset. There are two integration points:
-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.
The method for powering on and off your bluetooth chip varies from Android V 1.0 to post 1.0.
- -/sys/modules/board_[PLATFORM]/parameters/bluetooth_power_on.rfkill API. See arch/arm/mach-msm/board-trout-rfkill.c for an example.BlueZ provides a rich set of command line tools for debugging and interacting with the Bluetooth sub-system, including:
-hciconfighcitoolhcidumpsdptooldbus-senddbus-monitorOnce 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.
--
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.
--
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 --
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.
--
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:
-device/data directory will be lost on reboot.-
Configure the bootloader to load the kernel and RAMdisk into RAM and pass the RAMdisk address to the kernel on startup.
--
-
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).
-
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_serverEach 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).
-
If bring up was successful, you should see the following Java applications (with icons) visible on the LCD panel:
-If they are not visible or unresponsive to keypad control, run the framebuffer/keypad tests.
The Android Init Language consists of four broad classes of statements:
-The language syntax includes the following conventions:
-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> |
- 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| 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 -\ No newline at end of file diff --git a/pdk/docs/build_new_device.jd b/pdk/docs/build_new_device.jd deleted file mode 100755 index 0050889a2..000000000 --- a/pdk/docs/build_new_device.jd +++ /dev/null @@ -1,131 +0,0 @@ -page.title=Building Android for a new Mobile Device -pdk.version=1.0 -@jd:body - - - - - - -
The directions below describe how to configure make files for new mobile devices and products.
-//vendor/.- mkdir vendor/<company_name>
products directory beneath the company directory you created in step 1.- mkdir vendor/<company_name>/products/
vendor/<company_name>/products/<first_product_name>.mk, that includes the
-following code:- $(call inherit-product, $(SRC_TARGET_DIR)/product/generic.mk) - # - # Overrides - PRODUCT_NAME := <first_product_name> - PRODUCT_DEVICE := <board_name>
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 \
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>
product_config.mk file in the directory created in the previous step (vendor/<company_name>/<board_name>). If this directory does not include a product_config.mk file, the build will fail.- # 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
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
<second_product_name>.mk within products/AndroidProducts.mk.- PRODUCT_MAKEFILES := \ - $(LOCAL_DIR)/first_product_name.mk \ - $(LOCAL_DIR)/second_product_name.mk
vendor/<company_name>/<board_name> must include an Android.mk
-file with at least the following code:- # make file for new hardwarefrom - # - 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. - #
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>.
-
-
-
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.propproductsAndroidProducts.mk<first_product_name>.mk<second_product_name>.mkAndroid 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.
A makefile defines how to build a particular application. Makefiles typically include all of the following elements:
-LOCAL_MODULE := <build_name>).include $(CLEAR_VARS)).LOCAL_SRC_FILES := main.c).LOCAL_MODULE_TAGS := eng development).LOCAL_SHARED_LIBRARIES := cutils).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.
- - -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. | -
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:
-PRODUCT_DEVICELOCALESBRANDING_PARTNERPROPERTY_OVERRIDESThe snippet below illustrates a typical product definition file.
--//device/target/product/core.mk -PRODUCT_PACKAGES := Home SettingsProvider ... -//device/target/product/generic.mk -PRODUCT_PACKAGES := Calendar Camera SyncProvider ... -$(call inherit-product, target/product/core.mk) -PRODUCT_NAME := generic -//device/partner/google/products/core.mk -PRODUCT_PACKAGES := Maps GoogleAppsProvider ... -$(call inherit-product, target/product/core.mk) -//device/partner/google/products/generic.mk -PRODUCT_PACKAGES := Gmail GmailProvider ... -$(call inherit-product, partner/google/products/core.mk) -$(call inherit-product, target/product/generic.mk) -PRODUCT_NAME := google_generic - -- - -
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.
- - -Of the two options below, the first tends to yield more consistent results.
- - -Create a local version of buildspec.mk. The easiest way to do so is to change to your device directory and execute the following:
-% cp buildspec.mk.default buildspec.mk ; chmod u=rw buildspec.mk-
The default buildspec.mk. file is written so that all options appear commented. In order to establish a personal configuration environment, edit buildspec.mk as desired.
Once you have established your configuration environment, you can build the device code base by executing make in order to build the Android binaries. This may take a long time the first time you issue this command. On a dual-core machine, consider using '-j2' (or even '-j4') to speed up the build.
-% make -j2- - -
To do a generic build of android, source //device/envsetup.sh, which contains necessary variable and function definitions, as described below.
-% cd $TOP - -% . envsetup.sh - -% partner_setup generic - //select generic as the product - -% make -j4 PRODUCT-generic-user --
You can also replace user with eng for a debug engineering build:
- --% make -j4 PRODUCT-generic-eng -- - -
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 //device/out/ directory where all generated files are stored.
The binaries of each combo are stored as distinct sub-directories of //device/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 //device/prebuilt/... and don't need to get installed on your system.
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.
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:
-
-% . envsetup.sh -% partner_setup generic --
Then switch to the kernel directory /home/joe/android/kernel.
-
-
-
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>.
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.
To build the kernel, execute:
--% make -j4 -\ No newline at end of file diff --git a/pdk/docs/camera.jd b/pdk/docs/camera.jd deleted file mode 100755 index e4532d56c..000000000 --- a/pdk/docs/camera.jd +++ /dev/null @@ -1,75 +0,0 @@ -page.title=Camera -pdk.version=1.0 -@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.
-
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 partner/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) -- - -
The following diagram illustrates the sequence of function calls and actions necessary for your camera to preview.
-
-
-
-The following diagram illustrates the sequence of function calls and actions necessary for your camera to take a picture.
-
-
-
-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/cameraPreview.jpg b/pdk/docs/cameraPreview.jpg deleted file mode 100755 index 3dea01174..000000000 Binary files a/pdk/docs/cameraPreview.jpg and /dev/null differ diff --git a/pdk/docs/cameraTakePicture.jpg b/pdk/docs/cameraTakePicture.jpg deleted file mode 100755 index 4ac6d953e..000000000 Binary files a/pdk/docs/cameraTakePicture.jpg and /dev/null differ diff --git a/pdk/docs/display_drivers.jd b/pdk/docs/display_drivers.jd deleted file mode 100755 index c2e5f3aa5..000000000 --- a/pdk/docs/display_drivers.jd +++ /dev/null @@ -1,341 +0,0 @@ -page.title=Display Drivers -pdk.version=1.0 -@jd:body - - - - - - -This section describes how the display driver functions and offers a functional template designed to help you build your own device-specific driver.
-Android relies on the standard frame buffer device (/dev/fb0 or /dev/graphics/fb0) and driver as described in the linux/fb.h kernel header file. For more information regarding the standard Linux frame buffer, please see The Frame Buffer Device at http://kernel.org.
-
-
-
In Android, every window gets implemented with an underlying Surface object, an object that gets placed on the framebuffer by SurfaceFlinger, the system-wide screen composer. Each Surface is double-buffered. The back buffer is where drawing takes place and the front buffer is used for composition.
- When unlockCanvas() is called, the back buffer is posted, which
- means that it gets displayed and becomes available again. Android flips the front and back buffers, ensuring a minimal amount of buffer copying and that there is always a buffer for SurfaceFlinger to use for composition (which ensures that the screen never flickers or shows artifacts).
Android makes two requirements of the driver: a linear address space of mappable memory that it can write to directly and support for the rgb_565 pixel format. A typical frame display includes:
-/dev/fb0FBIOGET_FSCREENINFO and FBIOGET_VSCREENINFO Input / Output Control (ioctl) calls to retrieve information about the screenFBIOPUT_VSCREENINFO ioctl to attempt to create a virtual display twice the size of the physical screen and to set the pixel format to rgb_565. If this succeeds, double buffering is accomplished with video memory. When a page flip is required, Android makes another FBIOPUT_VSCREENINFO ioctl call with a new y-offset pointing to the other buffer in video memory. This ioctl, in turn, invokes the driver's .fb_pan_display function in order to do the actual flip. If there isn't sufficient video memory, regular memory is used and is just copied into the video memory when it is time do the flip. After allocating the video memory and setting the pixel format, Android uses mmap() to map the memory into the process's address space. All writes to the frame buffer are done through this mmaped memory.
To maintain adequate performance, framebuffer memory should be cacheable. If you use write-back, flush the cache before the frame buffer is written from DMA to the LCD. If that isn't possible, you may use write-through. As a last resort, you can also use uncached memory with the write-bugger enabled, but performance will suffer.
- - -The following sample driver offers a functional example to help you build your own display driver. Modify PGUIDE_FB... macros as desired to match the requirements of your own device hardware.
-/*
- * pguidefb.c
- *
- * Copyright 2007, Google Inc.
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2 as
- * published by the Free Software Foundation.
- */
-
-
-/*
- * ANDROID PORTING GUIDE: FRAME BUFFER DRIVER TEMPLATE
- *
- * This template is designed to provide the minimum frame buffer
- * functionality necessary for Android to display properly on a new
- * device. The PGUIDE_FB macros are meant as pointers indicating
- * where to implement the hardware specific code necessary for the new
- * device. The existence of the macros is not meant to trivialize the
- * work required, just as an indication of where the work needs to be
- * done.
- */
-
-#include <linux/module.h>
-#include <linux/kernel.h>
-#include <linux/errno.h>
-#include <linux/string.h>
-#include <linux/slab.h>
-#include <linux/delay.h>
-#include <linux/mm.h>
-#include <linux/fb.h>
-#include <linux/init.h>
-#include <linux/platform_device.h>
-
-
-/* Android currently only uses rgb565 in the hardware framebuffer */
-#define ANDROID_BYTES_PER_PIXEL 2
-
-/* Android will use double buffer in video if there is enough */
-#define ANDROID_NUMBER_OF_BUFFERS 2
-
-/* Modify these macros to suit the hardware */
-
-#define PGUIDE_FB_ROTATE
- /* Do what is necessary to cause the rotation */
-
-#define PGUIDE_FB_PAN
- /* Do what is necessary to cause the panning */
-
-#define PGUIDE_FB_PROBE_FIRST
- /* Do any early hardware initialization */
-
-#define PGUIDE_FB_PROBE_SECOND
- /* Do any later hardware initialization */
-
-#define PGUIDE_FB_WIDTH 320
- /* Return the width of the screen */
-
-#define PGUIDE_FB_HEIGHT 240
- /* Return the heighth of the screen */
-
-#define PGUIDE_FB_SCREEN_BASE 0
- /* Return the virtual address of the start of fb memory */
-
-#define PGUIDE_FB_SMEM_START PGUIDE_FB_SCREEN_BASE
- /* Return the physical address of the start of fb memory */
-
-#define PGUIDE_FB_REMOVE
- /* Do any hardware shutdown */
-
-
-
-
-
-struct pguide_fb {
- int rotation;
- struct fb_info fb;
- u32 cmap[16];
-};
-
-static inline u32 convert_bitfield(int val, struct fb_bitfield *bf)
-{
- unsigned int mask = (1 << bf->length) - 1;
-
- return (val >> (16 - bf->length) & mask) << bf->offset;
-}
-
-
-/* set the software color map. Probably doesn't need modifying. */
-static int
-pguide_fb_setcolreg(unsigned int regno, unsigned int red, unsigned int green,
- unsigned int blue, unsigned int transp, struct fb_info *info)
-{
- struct pguide_fb *fb = container_of(info, struct pguide_fb, fb);
-
- if (regno < 16) {
- fb->cmap[regno] = convert_bitfield(transp, &fb->fb.var.transp) |
- convert_bitfield(blue, &fb->fb.var.blue) |
- convert_bitfield(green, &fb->fb.var.green) |
- convert_bitfield(red, &fb->fb.var.red);
- return 0;
- }
- else {
- return 1;
- }
-}
-
-/* check var to see if supported by this device. Probably doesn't
- * need modifying.
- */
-static int pguide_fb_check_var(struct fb_var_screeninfo *var, struct fb_info *info)
-{
- if((var->rotate & 1) != (info->var.rotate & 1)) {
- if((var->xres != info->var.yres) ||
- (var->yres != info->var.xres) ||
- (var->xres_virtual != info->var.yres) ||
- (var->yres_virtual >
- info->var.xres * ANDROID_NUMBER_OF_BUFFERS) ||
- (var->yres_virtual < info->var.xres )) {
- return -EINVAL;
- }
- }
- else {
- if((var->xres != info->var.xres) ||
- (var->yres != info->var.yres) ||
- (var->xres_virtual != info->var.xres) ||
- (var->yres_virtual >
- info->var.yres * ANDROID_NUMBER_OF_BUFFERS) ||
- (var->yres_virtual < info->var.yres )) {
- return -EINVAL;
- }
- }
- if((var->xoffset != info->var.xoffset) ||
- (var->bits_per_pixel != info->var.bits_per_pixel) ||
- (var->grayscale != info->var.grayscale)) {
- return -EINVAL;
- }
- return 0;
-}
-
-
-/* Handles screen rotation if device supports it. */
-static int pguide_fb_set_par(struct fb_info *info)
-{
- struct pguide_fb *fb = container_of(info, struct pguide_fb, fb);
- if(fb->rotation != fb->fb.var.rotate) {
- info->fix.line_length =
- info->var.xres * ANDROID_BYTES_PER_PIXEL;
- fb->rotation = fb->fb.var.rotate;
- PGUIDE_FB_ROTATE;
- }
- return 0;
-}
-
-
-/* Pan the display if device supports it. */
-static int pguide_fb_pan_display(struct fb_var_screeninfo *var, struct fb_info *info)
-{
- struct pguide_fb *fb __attribute__ ((unused))
- = container_of(info, struct pguide_fb, fb);
-
- /* Set the frame buffer base to something like:
- fb->fb.fix.smem_start + fb->fb.var.xres *
- ANDROID_BYTES_PER_PIXEL * var->yoffset
- */
- PGUIDE_FB_PAN;
-
- return 0;
-}
-
-
-static struct fb_ops pguide_fb_ops = {
- .owner = THIS_MODULE,
- .fb_check_var = pguide_fb_check_var,
- .fb_set_par = pguide_fb_set_par,
- .fb_setcolreg = pguide_fb_setcolreg,
- .fb_pan_display = pguide_fb_pan_display,
-
- /* These are generic software based fb functions */
- .fb_fillrect = cfb_fillrect,
- .fb_copyarea = cfb_copyarea,
- .fb_imageblit = cfb_imageblit,
-};
-
-
-static int pguide_fb_probe(struct platform_device *pdev)
-{
- int ret;
- struct pguide_fb *fb;
- size_t framesize;
- uint32_t width, height;
-
- fb = kzalloc(sizeof(*fb), GFP_KERNEL);
- if(fb == NULL) {
- ret = -ENOMEM;
- goto err_fb_alloc_failed;
- }
- platform_set_drvdata(pdev, fb);
-
- PGUIDE_FB_PROBE_FIRST;
- width = PGUIDE_FB_WIDTH;
- height = PGUIDE_FB_HEIGHT;
-
-
- fb->fb.fbops = &pguide_fb_ops;
-
- /* These modes are the ones currently required by Android */
-
- fb->fb.flags = FBINFO_FLAG_DEFAULT;
- fb->fb.pseudo_palette = fb->cmap;
- fb->fb.fix.type = FB_TYPE_PACKED_PIXELS;
- fb->fb.fix.visual = FB_VISUAL_TRUECOLOR;
- fb->fb.fix.line_length = width * ANDROID_BYTES_PER_PIXEL;
- fb->fb.fix.accel = FB_ACCEL_NONE;
- fb->fb.fix.ypanstep = 1;
-
- fb->fb.var.xres = width;
- fb->fb.var.yres = height;
- fb->fb.var.xres_virtual = width;
- fb->fb.var.yres_virtual = height * ANDROID_NUMBER_OF_BUFFERS;
- fb->fb.var.bits_per_pixel = 16;
- fb->fb.var.activate = FB_ACTIVATE_NOW;
- fb->fb.var.height = height;
- fb->fb.var.width = width;
-
- fb->fb.var.red.offset = 11;
- fb->fb.var.red.length = 5;
- fb->fb.var.green.offset = 5;
- fb->fb.var.green.length = 6;
- fb->fb.var.blue.offset = 0;
- fb->fb.var.blue.length = 5;
-
- framesize = width * height *
- ANDROID_BYTES_PER_PIXEL * ANDROID_NUMBER_OF_BUFFERS;
- fb->fb.screen_base = PGUIDE_FB_SCREEN_BASE;
- fb->fb.fix.smem_start = PGUIDE_FB_SMEM_START;
- fb->fb.fix.smem_len = framesize;
-
- ret = fb_set_var(&fb->fb, &fb->fb.var);
- if(ret)
- goto err_fb_set_var_failed;
-
- PGUIDE_FB_PROBE_SECOND;
-
- ret = register_framebuffer(&fb->fb);
- if(ret)
- goto err_register_framebuffer_failed;
-
- return 0;
-
-
-err_register_framebuffer_failed:
-err_fb_set_var_failed:
- kfree(fb);
-err_fb_alloc_failed:
- return ret;
-}
-
-static int pguide_fb_remove(struct platform_device *pdev)
-{
- struct pguide_fb *fb = platform_get_drvdata(pdev);
-
- PGUIDE_FB_REMOVE;
-
- kfree(fb);
- return 0;
-}
-
-
-static struct platform_driver pguide_fb_driver = {
- .probe = pguide_fb_probe,
- .remove = pguide_fb_remove,
- .driver = {
- .name = "pguide_fb"
- }
-};
-
-static int __init pguide_fb_init(void)
-{
- return platform_driver_register(&pguide_fb_driver);
-}
-
-static void __exit pguide_fb_exit(void)
-{
- platform_driver_unregister(&pguide_fb_driver);
-}
-
-module_init(pguide_fb_init);
-module_exit(pguide_fb_exit);
-
-MODULE_LICENSE("GPL");
-
-
-
-Both of the following problems have a similar cause:
-Both problems are caused by an incorrect implementation of the frame buffer's page flipping. Key events are captured, but the graphical interface appears to drop every other frame.
-Android relies on a double buffer to smoothly render page flips (please see Functionality for details).
\ No newline at end of file diff --git a/pdk/docs/getting_source_code.jd b/pdk/docs/getting_source_code.jd deleted file mode 100755 index 19a7069ab..000000000 --- a/pdk/docs/getting_source_code.jd +++ /dev/null @@ -1,126 +0,0 @@ -page.title=Getting Source Code -@jd:body - - -Android relies on Git, a version control system, to install the Android platform. You will need to install Git 1.5.2 or greater in order to access the source tree. Please visit http://git.or.cz/ for more information regarding Git.
-Git permits you to control access to working directories, and we recommend that you use it to limit Android repository access to only a few people within your organization (please refer to your Google NDA for potential contractual restraints on sharing Android source access).
-You may clone Google's repository to a local copy for sharing internally (see Git documentation for details).
- - -To install the Git package, execute:
--% sudo apt-get install git-core -- - -
Once Git is cleanly installed, you need to establish a connection with Google's Git server, a connection that requires an RSA key in order to authenticate requests.
- - -Each developer must have a unique RSA key in order to access Android source code. To generate an RSA key:
--
% ssh-keygen -t rsa -C email@domain.com
id_rsa in this example).id_rsa: This file contains the private half of your RSA key. You shouldn't share this file with anyone. id_rsa.pub: This is the public half or your RSA key and you should send it to your Google technical account manager.Send your Google Account Manager your public key file in order to establish Git server access.
- - -Once you have generated an RSA key and shared the public file with Google, you can test your connection with the Git server with the following command:
--% ssh android-git.ext.google.com -- -
You should receive one of the following results:
- -| Result | -Cause | -Action | -
|---|---|---|
-fatal: What do you think I am? A shell?
- |
- Success | -None. You successfully connected to the Git server. (You should not have shell access and it's expected to receive this error.) | -
| ssh hangs and eventually times out. | -Your setup is failing to locate and establish a basic connection. | -Google needs to debug network settings. | -
| Error: Permission denied <public key> | -Either you are not using the matching username or the RSA private key does not match the public key. | -Try executing: -
-% ssh $USER@android-
- git.ext.google.com
- |
-
Android source code is maintained in two repositories: device and kernel. The device repository includes the Android framework (things like the Activity Manager, Window Manager, Telephony Manager, View System, etc.). The kernel repository includes the core code necessary to run the operating system (things like the Display Driver, Camera Driver, Keypad Driver, Power Management, etc.). (Please see What is Android? for details.)
Save device and kernel code at the same directory level, for example:
--
/home/joe/android/device/home/joe/android/kernelDevice Code
-To download device code, you need your username and a unique <path> string supplied by Google to execute the following:
-% git-clone $USER@android-git.ext.google.com:<path>/device.git -- -
Kernel Code
-To download kernel code, you need your username and a unique <path> string supplied by Google to execute the following:
-% git-clone $USER@android-git.ext.google.com:<path>/kernel.git -- - - -
You likely already have Linux running on your platform and only need to integrate Android-specific changes. The following directions describe how to extract an Android patch.
-diff on the two kernel packages to get Android-specific changes.Android defines a user space C abstraction interface for GPS hardware. The interface header is defined in include/hardware/gps.h. In order to integate GPS with Android, you need to build a shared library that implements this interface.
To implement a GPS driver, create a shared library that implements the interface defined in gps.h. You must name your shared library libgps.so so that it will get loaded from /system/lib at runtime. Place GPS sources and Android.mk in partner/acme/chipset_or_board/gps/ (where "acme" is your product name and "chipset_or_board" is your hardware target).
The following stub Android.mk file ensures that libgps compiles and links to the appropriate libraries:
-LOCAL_PATH := $(call my-dir) -include $(CLEAR_VARS) - -LOCAL_MODULE := libgps - -LOCAL_STATIC_LIBRARIES:= \ -# include any static library dependencies - -LOCAL_SHARED_LIBRARIES := \ -# include any shared library dependencies - -LOCAL_SRC_FILES += \ -# include your source files. eg. MyGpsLibrary.cpp - -LOCAL_CFLAGS += \ -# include any needed compile flags - -LOCAL_C_INCLUDES:= \ -# include any needed local header files - -include $(BUILD_SHARED_LIBRARY) -- - -
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/group__memory.jd b/pdk/docs/group__memory.jd deleted file mode 100755 index 87f19d5f9..000000000 --- a/pdk/docs/group__memory.jd +++ /dev/null @@ -1,22 +0,0 @@ -page.title=Providing Heap Memory -@jd:body - - - - -[Neworking Support] -Modules | |
| Porividng Heap Memory | |
The Open Handset Distribution (OHD) is a software distribution for mobile devices, often referred to as Android, developed by members of the Open Handset Alliance. Android includes an operating system, middleware, and key applications typically required for a mobile device.
- -This porting guide describes the steps necessary to port Android to a new mobile device. Android is designed as a highly-portable, hardware-independent platform based on Linux, and porting the platform to new devices requires little more than porting the Linux kernel and developing the Linux drivers necessary for your device.
- -The current version of this guide describes bringing Android up to "PDA-level" functionality; functionality sufficient to support non-multimedia apps that run on unconnected mobile devices through the standard user interface devices such as keypad and display. Future versions of this guide will cover complete telephony, multi-media and peripheral integration to create a complete mobile device.
- - -This porting guide is intended for engineers proficient with running (and writing drivers for) Linux on embedded devices. -
The guide also assumes you have a target hardware that matches Device Requirements and that you -can boot and run a recent (2.6.x) version of the Linux kernel -with at least keypad and display drivers properly installed.
- - -To get started with Android, start with the publicly-available documentation at http://code.google.com/android/documentation.html, paying particular attention to What is Android? and Getting Started with Android.
- - -Start with the following sections in order to port Android to your target hardware.
-This document describes how to use the Instrumentation Framework to write test cases. You should have a working knowledge of the following:
-adb, am and various logging functionality Each Android application runs in its own process. Instrumentation kills the application process and restarts the process with Instrumentation. Instrumentation gives a handle to the application context used to poke around the application to validate test assertions, allowing you to write test cases to test applications at a much lower level than UI screen shot tests. Note that Instrumentation cannot catch UI bugs.
- - -am is used to start and instrument activities using the adb shell command, as shown in the snippet below:
-> adb shell am -usage: am [start|instrument] - am start [-a <ACTION>] [-d <DATA_URI>] [-t <MIME_TYPE>] - [-c <CATEGORY> [-c <CATEGORY>] ...] - [-e <EXTRA_KEY> <EXTRA_VALUE> [-e <EXTRA_KEY> <EXTRA_VALUE> ...] - [-n <COMPONENT>] [-D] [<URI>] - am instrument [-e <ARG_NAME> <ARG_VALUE>] [-p <PROF_FILE>] - [-w] <COMPONENT> -For example, to start the Contacts application you can use -> adb shell am start -n com.google.android.contacts/.ContactsActivity -- - -
Each instrumentation test case is similar to an Android application with the distinction that it starts another application. For example, have a look in the tests/Contacts directory.
tests/Contacts/src/com/google/android/contactstests. tests/Contacts/src/com/google/android/contactstests/functional/ContactsInstrumentationTestRunner.java.Suppose you have a makefile with Contactstests as the target.
make Contactstests: Compiles the test cases. adb install Contactstests.apk: Installs the apk on the device. am command to run them. For options and other details, please see Instrumentation Testing.
- - -The test case described in this section adds and tests a new Contact. Note that you can send intents, register intent receivers, etc.
-Instrumentation.java has helper functions that send key events and string, for example:
getInstrumentation(): Returns the handle to the instrumentation sendCharacterSync: Sends a character. sendStringSync: Sends a string to an input box. sendKeyDownUpSync: Sends a specific keyevent. sendTrackballEventSync: Send a trackball event. You can find the test case below at device/tests/Contacts.
-private void addNewContact(String name, int star, int phoneType, String number, String label,
- String email, int emailType){
- ContentValues values = new ContentValues();
- Uri phoneUri = null;
- Uri emailUri = null;
-
- values.put(Contacts.People.NAME, name);
- values.put(Contacts.People.STARRED, star);
-
- //Add Phone Numbers
- Uri uri = mActivity.getContentResolver().insert(Contacts.People.CONTENT_URI, values);
- phoneUri = Uri.withAppendedPath(uri, Contacts.People.Phones.CONTENT_DIRECTORY);
-
- values.clear();
- values.put(Contacts.Phones.TYPE, phoneType);
- values.put(Contacts.Phones.NUMBER, number);
- values.put(Contacts.Phones.LABEL, label);
- mActivity.getContentResolver().insert(phoneUri, values);
-
- //Add Email
- emailUri = Uri.withAppendedPath(uri, ContactMethods.CONTENT_DIRECTORY);
-
- values.clear();
- values.put(ContactMethods.KIND, Contacts.KIND_EMAIL);
- values.put(ContactMethods.DATA, email);
- values.put(ContactMethods.LABEL, "");
- values.put(ContactMethods.TYPE, emailType);
- mActivity.getContentResolver().insert(emailUri, values);
-}
-
-
- public void testAddSaveSingleContact(){
- int previousCount = mActivity.getListView().getCount();
- String message;
-
- addNewContact(INPUT_NAME_1 + "1", "5435754532", "1" + INPUT_EMAIL_1, CONFIRM_OPTION);
-
- message = "Added 1 to initial length=" + previousCount + ", but resulted with a count=" +
- mActivity.getListView().getCount();
- assertEquals(message, ++previousCount, mActivity.getListView().getCount());
-
- // Check Content; Name; Num; Starred
- assertEquals(INPUT_NAME_1 + "1", getTextFromView(0, android.R.id.text1));
- assertEquals("5435754532", getTextFromView(0, android.R.id.text2));
-
- //Check email is saved
- //cursor = returnEmailCursorAtId("1");
- Uri uri = Uri.parse("content://contacts/people/1");
- uri = Uri.withAppendedPath(uri, ContactMethods.CONTENT_DIRECTORY);
- Cursor cursor = mActivity.getContentResolver().query(uri, CONTACTS_COLUMNS, null, null, null);
- assertTrue("returnEmailCursorAtId: Moving cursor to first row has failed", cursor.first());
-
- int dataIndex = cursor.getColumnIndexOrThrow("data");
- assertEquals("1" + INPUT_EMAIL_1, cursor.getString(dataIndex));
- cursor.deactivate();
-}
-
-
-
-If you run your test cases and nothing appears to happen, have a look at adb logcat. The following is a common problem:
-I/dalvikvm( 688): threadid=11: attached from native, name=Binder Thread #1
-I/dalvikvm( 688): threadid=13: attached from native, name=Binder Thread #2
-W/ActivityManager( 469): Unable to find instrumentation info for: ComponentInfo{com.google.android.browser_instrumentation/com.google.android.browser_instrumentation.BrowserWebkitLayoutInstrumentation}
-D/AndroidRuntime( 688): Shutting down VM
-E/AndroidRuntime( 688): ERROR: thread attach failed
-
-It's possible that the instrumentation apk isn't installed on your device or that the package name is incorrect in the Manifest file.
- diff --git a/pdk/docs/instrumentation_testing.jd b/pdk/docs/instrumentation_testing.jd deleted file mode 100755 index 46467779f..000000000 --- a/pdk/docs/instrumentation_testing.jd +++ /dev/null @@ -1,511 +0,0 @@ -page.title=Instrumentation Testing -pdk.version=1.0 -@jd:body - - -This document describes how to use the Instrumentation Framework to write test cases. Instrumentation testing allows you to verify a particular feature or behavior with an automated JUnit TestCase. You can launch activities and providers within an application, send key events, and make assertions about various UI elements.
-You should have a working knowledge of the following:
-adb, am and various logging functionality Each Android application runs in its own process. Instrumentation kills the application process and restarts the process with Instrumentation. Instrumentation gives a handle to the application context used to poke around the application to validate test assertions, allowing you to write test cases to test applications at a much lower level than UI screen shot tests. Note that Instrumentation cannot catch UI bugs.
- - - The following classes help glue together Instrumentation with JUnit testing.
| Class | -Description |
|---|---|
InstrumentationTestCase |
-
- This extends the standard JUnit |
-
InstrumentationTestRunner |
- The instrumentation test runner is an instrumentation that runs instrumentation test cases and injects itself into each test case. Instrumentation test cases need to be grouped together with an instrumentation test runner with the appropriate target package. | -
InstrumentationTestSuite |
- The instrumentation test suite is a simple extension of the standard JUnit TestSuite that keeps a member Instrumentation variable on hand to inject into each TestCase before running them. It is used by InstrumentationTestRunner. |
-
Three additional base classes extend InstrumentationTestCase to allow you to test Activity and Provider classes:
| Class | -Description | -
|---|---|
ActivityTestCase |
- This class can be used to write tests for a specific activity. An activity is launched in its |
-
ServiceTestCase |
- This test case provides a framework in which you can test Service classes in a controlled environment. It provides basic support for the lifecycle of a Service, and hooks by which you can inject various dependencies and control the environment in which your Service is tested. | -
SingleLaunchActivityTestCase |
- This class is similar to ActivityTestCase except that the activity is launched once per class instead of every time the test case calls setup. |
-
ProviderTestCase |
- This class is similar to ActivityTestCase except that it will setup, tear down, and provide access to the Provider of your choice. |
-
The am command is a command-line interface to the ActivityManager (see http://code.google.com/android/reference/android/app/ActivityManager.html for details). am is used to start and instrument activities using the adb shell command, as shown in the snippet below:
-> adb shell am -usage: am [start|instrument] - am start [-a <ACTION>] [-d <DATA_URI>] [-t <MIME_TYPE>] - [-c <CATEGORY> [-c <CATEGORY>] ...] - [-e <EXTRA_KEY> <EXTRA_VALUE> [-e <EXTRA_KEY> <EXTRA_VALUE> ...] - [-n <COMPONENT>] [-D] [<URI>] - am instrument [-e <ARG_NAME> <ARG_VALUE>] [-p <PROF_FILE>] - [-w] <COMPONENT> -For example, to start the Contacts application you can use -> adb shell am start -n com.google.android.contacts/.ContactsActivity -- - -
This section provides an overview for various unit and functional test cases that can be executed through the instrumentation framework.
- - -Framework test cases test the Android application framework or specific Android application functionality that requires an Android runtime context. These tests can be found in //device/tests and //device/apps/AndroidTests.
Core library test cases test the Android library functionality that does not require an Android runtime context. These tests are split into Android library (android.* package space) tests at //device/java/tests and Java library (java.*, javax.*, etc. packages) tests at //device/dalvik/libcore/.../tests.
Each instrumentation test case is similar to an Android application with the distinction that it starts another application. For example, have a look in the tests/Contacts directory.
tests/Contacts/src/com/google/android/contactstests. tests/Contacts/src/com/google/android/contactstests/functional/ContactsInstrumentationTestRunner.java.Suppose you have a makefile with Contactstests as the target.
make Contactstests: Compiles the test cases. adb install Contactstests.apk: Installs the apk on the device. am command to run them. To run your tests, use the am instrument command with your InstrumentationTestRunner as its argument. Results are printed as a result of the instrumentation. For example, the following snippet displays the output after running the framework tests with one test failing (note the unusual syntax caused by how instrumentations are run via am):
-$ adb shell am instrument -w com.google.android.frameworktest/.tests.FrameworkInstrumentationTestRunner -INSTRUMENTATION_RESULT: test results:=.......F....... -Time: 6.837 -There was 1 failure: -1) testSetUpConditions(com.google.android.frameworktest.tests.focus.RequestFocusTest)junit.framework.AssertionFailedError: requestFocus() should work from onCreate. - at com.google.android.frameworktest.tests.focus.RequestFocusTest.testSetUpConditions(RequestFocusTest.java:66) - at java.lang.reflect.Method.invokeNative(Native Method) - at android.test.InstrumentationTestSuite.runTest(InstrumentationTestSuite.java:73) - at android.test.InstrumentationTestSuite.runTest(InstrumentationTestSuite.java:73) - at android.test.InstrumentationTestRunner.onStart(InstrumentationTestRunner.java:151) - at android.app.Instrumentation$InstrumentationThread.run(Instrumentation.java:1088) - -FAILURES!!! -Tests run: 14, Failures: 1, Errors: 0 - -<RETURN> to continue - -INSTRUMENTATION_CODE: -1 -$ -- - -
If no class or package is passed in to run, InstrumentationTestRunner will automatically find and run all tests under the package of the test application (as defined by the android:targetPackage attribute of the instrumentation defined in its manifest file).
-
-$ adb shell am instrument -w \ - com.android.samples.tests/android.test.InstrumentationTestRunner - -INSTRUMENTATION_RESULT: Test results for InstrumentationTestRunner=.......... -Time: 2.317 - -OK (10 tests) - - -INSTRUMENTATION_CODE: -1 -- - -
If you have many tests under one package, use the -e package <packagename> option to run all tests under that package without having to manually create a test suite.
-$ adb shell am instrument -w \ - -e package com.android.samples.view \ - com.android.samples.tests/android.test.InstrumentationTestRunner -INSTRUMENTATION_RESULT: Test results for InstrumentationTestRunner=........ -Time: 1.587 - -OK (8 tests) -- - -
If you prefer to explicitly state which tests comprise all of your tests, you can define a test suite and run that directly. By convention, all test packages in your system should have at least one suite called AllTests (see AllTests.java). To run all of the tests using the AllTests suite for the api demos test app:
-$ adb shell am instrument -w \ - -e class com.android.samples.AllTests \ - com.android.samples.tests/android.test.InstrumentationTestRunner - -INSTRUMENTATION_RESULT: Test results for AllTests=.......... -Time: 2.286 - -OK (10 tests) - - -INSTRUMENTATION_CODE: -1 -- - -
-$ adb shell am instrument -w \ - -e class com.android.samples.view.Focus2ActivityTest \ - com.android.samples.tests/android.test.InstrumentationTestRunner - -INSTRUMENTATION_RESULT: Test results for Focus2ActivityTest=.... -Time: 1.359 - -OK (4 tests) - - -INSTRUMENTATION_CODE: -1 -- - -
-$ adb shell am instrument -w \ - -e class com.android.samples.view.Focus2ActivityTest#testGoingLeftFromRightButtonGoesToCenter \ - com.android.samples.tests/android.test.InstrumentationTestRunner - -INSTRUMENTATION_RESULT: Test results for Focus2ActivityTest=. -Time: 0.51 - -OK (1 test) - - -INSTRUMENTATION_CODE: -1 -- - -
In order to debug your test code, instruct the controller to stop and wait for the debugger by adding -e debug true to your
-command line. This causes the test runner to stop and wait for the debugger just before calling your setUp() method. For example,
-$ adb shell am instrument -w \ - -e debug true \ - com.android.samples.tests/android.test.InstrumentationTestRunner -- - -
When writing tests, refer to the ApiDemos tests as models (located at //device/samples/ApiDemos). This section provides an overview of the test structure with ApiDemos.
Test packages should use the following structure and include Android.mk, AndroidManifest.xml, AllTests.java, and a src directory that mirrors the src directory of the tested application.
Files are located within a tests directory found in the root directory:
-$ find samples/ApiDemos/tests -samples/ApiDemos/tests -samples/ApiDemos/tests/Android.mk -samples/ApiDemos/tests/AndroidManifest.xml -samples/ApiDemos/tests/src -samples/ApiDemos/tests/src/com -samples/ApiDemos/tests/src/com/google -samples/ApiDemos/tests/src/com/google/android -samples/ApiDemos/tests/src/com/google/android/samples -samples/ApiDemos/tests/src/com/google/android/samples/AllTests.java -samples/ApiDemos/tests/src/com/google/android/samples/ApiDemosTest.java -samples/ApiDemos/tests/src/com/google/android/samples/os -samples/ApiDemos/tests/src/com/google/android/samples/os/MorseCodeConverterTest.java -samples/ApiDemos/tests/src/com/google/android/samples/view -samples/ApiDemos/tests/src/com/google/android/samples/view/Focus2ActivityTest.java -samples/ApiDemos/tests/src/com/google/android/samples/view/Focus2AndroidTest.java -- - -
The contents of the makefile are similar to a normal application with the addition of a LOCAL_INSTRUMENTATION_FOR declaration.
-# Add appropriate copyright banner here -LOCAL_PATH:= $(call my-dir) -include $(CLEAR_VARS) - -# We only want this apk build for tests. -LOCAL_MODULE_TAGS := tests - -# Include all test java files. -LOCAL_SRC_FILES := $(call all-java-files-under, src) - -# Notice that we don't have to include the src files of ApiDemos because, by -# running the tests using an instrumentation targeting ApiDemos, we -# automatically get all of its classes loaded into our environment. - -LOCAL_PACKAGE_NAME := ApiDemosTests - -LOCAL_INSTRUMENTATION_FOR := ApiDemos - -include $(BUILD_PACKAGE) -- - -
Use the following example to create an AndroidManifest.xml file that declares the instrumentation. Specify that the framework supplied Instrumentation TestRunner targest the package of your application, allowing the tests that are run with the instrumentation to get access to all of the classes of your application without having to build the source into the test app. The name of the test application is typically the same as your target application with .tests appended.
-# Add appropriate copyright banner here -<manifest xmlns:android="http://schemas.android.com/apk/res/android" - package="com.android.samples.tests"> - - <uses-permission android:name="android.permission.RUN_INSTRUMENTATION" /> - - <!-- - This declares that this app uses the instrumentation test runner targeting - the package of com.android.samples. To run the tests use the command: - "adb shell am instrument -w com.android.samples.tests/android.test.InstrumentationTestRunner" - --> - <instrumentation android:name="android.test.InstrumentationTestRunner" - android:targetPackage="com.android.samples" - android:label="Tests for Api Demos."/> - -</manifest> --
-
The following snippet will prefix the /android.test.InstrumentationTestRunner when running tests from the command line:
-$ adb shell am instrument -w \ - com.android.samples.tests/android.test.InstrumentationTestRunner -- - -
Create a class that derives from this class. You must override two abstract methods; one that returns the class loader of the target package, and another that defines all of the tests within the package. For example, the snippet below displays the test runner for the framework tests.
-
-public class FrameworkInstrumentationTestRunner extends InstrumentationTestRunner {
-
- @Override
- public TestSuite getAllTests() {
- InstrumentationTestSuite suite = new InstrumentationTestSuite(this);
-
- suite.addTestSuite(FocusAfterRemovalTest.class);
- suite.addTestSuite(RequestFocusTest.class);
- suite.addTestSuite(RequestRectangleVisibleTest.class);
- return suite;
- }
-
- @Override
- public ClassLoader getLoader() {
- return FrameworkInstrumentationTestRunner.class.getClassLoader();
- }
-}
-
- Next, in an appropriate AndroidManifest.xml, define the instrumentation for the derived class with the appropriate android:targetPackage set. For example, the snippet below defines the instrumentation runner for the framework tests.
-<uses-permission android:name="android.permission.RUN_INSTRUMENTATION" /> - -<instrumentation android:name="android.tests.FrameworkInstrumentationTestRunner" - android:targetPackage="com.google.android.frameworktest" - android:label="framework instrumentation test runner" /> -- - -
To create a new test case, write a class that extends InstrumentationTestCase in the same application as your test runner. The following snippet illustrates an example ActivityTestCase that tests an activity named MyActivity.
-public class ButtonPressTest extends ActivityTestCase<MyActivity> {
-
- Button mLeftButton;
-
- public ButtonPressTest() {
- super("com.example", MyActivity.class);
- }
-
- @Override
- public void setUp() throws Exception {
- super.setUp();
- mLeftButton = (Button) getActivity().findViewById(R.id.leftButton);
- }
-
- public void testFocusMovesToRight() throws Exception {
- assertTrue(mLeftButton.hasFocus());
- getInstrumentation().sendCharacterSync(KeyEvent.KEYCODE_DPAD_RIGHT);
-
- Button rightButton = (Button) getActivity().findViewById(R.id.rightButton);
- assertTrue(rightButton.hasFocus());
- }
-
- // could have several more tests...
-}
-
-
-
-The test case described in this section adds and tests a new Contact. Note that you can send intents, register intent receivers, etc.
-Instrumentation.java has helper functions that send key events and strings, for example:
getInstrumentation(): Returns the handle to the instrumentation sendCharacterSync: Sends a character. sendStringSync: Sends a string to an input box. sendKeyDownUpSync: Sends a specific keyevent. sendTrackballEventSync: Sends a trackball event. You can find the test case below at device/tests/Contacts.
-private void addNewContact(String name, int star, int phoneType, String number, String label,
- String email, int emailType){
- ContentValues values = new ContentValues();
- Uri phoneUri = null;
- Uri emailUri = null;
-
- values.put(Contacts.People.NAME, name);
- values.put(Contacts.People.STARRED, star);
-
- //Add Phone Numbers
- Uri uri = mActivity.getContentResolver().insert(Contacts.People.CONTENT_URI, values);
- phoneUri = Uri.withAppendedPath(uri, Contacts.People.Phones.CONTENT_DIRECTORY);
-
- values.clear();
- values.put(Contacts.Phones.TYPE, phoneType);
- values.put(Contacts.Phones.NUMBER, number);
- values.put(Contacts.Phones.LABEL, label);
- mActivity.getContentResolver().insert(phoneUri, values);
-
- //Add Email
- emailUri = Uri.withAppendedPath(uri, ContactMethods.CONTENT_DIRECTORY);
-
- values.clear();
- values.put(ContactMethods.KIND, Contacts.KIND_EMAIL);
- values.put(ContactMethods.DATA, email);
- values.put(ContactMethods.LABEL, "");
- values.put(ContactMethods.TYPE, emailType);
- mActivity.getContentResolver().insert(emailUri, values);
-}
-
-
- public void testAddSaveSingleContact(){
- int previousCount = mActivity.getListView().getCount();
- String message;
-
- addNewContact(INPUT_NAME_1 + "1", "5435754532", "1" + INPUT_EMAIL_1, CONFIRM_OPTION);
-
- message = "Added 1 to initial length=" + previousCount + ", but resulted with a count=" +
- mActivity.getListView().getCount();
- assertEquals(message, ++previousCount, mActivity.getListView().getCount());
-
- // Check Content; Name; Num; Starred
- assertEquals(INPUT_NAME_1 + "1", getTextFromView(0, android.R.id.text1));
- assertEquals("5435754532", getTextFromView(0, android.R.id.text2));
-
- //Check email is saved
- //cursor = returnEmailCursorAtId("1");
- Uri uri = Uri.parse("content://contacts/people/1");
- uri = Uri.withAppendedPath(uri, ContactMethods.CONTENT_DIRECTORY);
- Cursor cursor = mActivity.getContentResolver().query(uri, CONTACTS_COLUMNS, null, null, null);
- assertTrue("returnEmailCursorAtId: Moving cursor to first row has failed", cursor.first());
-
- int dataIndex = cursor.getColumnIndexOrThrow("data");
- assertEquals("1" + INPUT_EMAIL_1, cursor.getString(dataIndex));
- cursor.deactivate();
-}
-
-
-
-Once you are bootstrapped with your test application, you can start writing tests. There are three of types of tests you may wish to write:
-The API Demos test suite includes examples of all three styles and can be used as a guideline for writing each type of test.
-There are two utility classes available for the most common uses of InstrumentationTestCase: ActivityTestCase and ProviderTestCase. See their javadoc for more information. -
- - -If you run your test cases and nothing appears to happen, have a look at adb logcat. The following is a common problem:
-I/dalvikvm( 688): threadid=11: attached from native, name=Binder Thread #1
-I/dalvikvm( 688): threadid=13: attached from native, name=Binder Thread #2
-W/ActivityManager( 469): Unable to find instrumentation info for: ComponentInfo{com.google.android.browser_instrumentation/com.google.android.browser_instrumentation.BrowserWebkitLayoutInstrumentation}
-D/AndroidRuntime( 688): Shutting down VM
-E/AndroidRuntime( 688): ERROR: thread attach failed
-
-It's possible that the instrumentation apk isn't installed on your device or that the package name is incorrect in the Manifest file.
\ No newline at end of file diff --git a/pdk/docs/intro_source_code.jd b/pdk/docs/intro_source_code.jd deleted file mode 100755 index 100f3ee5b..000000000 --- a/pdk/docs/intro_source_code.jd +++ /dev/null @@ -1,169 +0,0 @@ -page.title=Source Code Overview -@jd:body - - - - -Android source code is maintained in two code bases: the Android Linux kernel (kernel directory) and Android platform and applications (device directory). This document provides a high-level introduction to the source code organization and an overview of the major components of each primary directory.
The Android Linux kernel includes enhancements to the Linux 2.6 kernel that provide additional drivers to support the Android platform, including:
-Look for Android-specific enhancements in the following directories:
-/drivers/android/drivers/misc/include/linuxThe following list outlines the directory structure found within the device branch of Android source code:
You can develop Android applications with the same standard tools you use to develop any Java application. The Android core libraries provide the functionality needed to build rich mobile applications and the Android development tools are designed to simplify running, debugging, and testing your applications.
- -Add project-specific source code to the Android source tree under the partner directory in a directory specific to the application or service you are building. For example, all Google-specific applications would be placed under device/partner/google/. A Google search application would be placed under device/partner/google/apps/Search.
-
See Building Android for a new Mobile Device for detailed instructions.
- - diff --git a/pdk/docs/keymaps_keyboard_input.jd b/pdk/docs/keymaps_keyboard_input.jd deleted file mode 100755 index a71b5e9ed..000000000 --- a/pdk/docs/keymaps_keyboard_input.jd +++ /dev/null @@ -1,509 +0,0 @@ -page.title=Keymaps and Keyboard Input -pdk.version=1.0 -@jd:body - - - -This document describes how keyboard input gets translated into Android actions and how you can customize key layout and key character maps to match the needs of your own device.
-Android uses the standard Linux input event device (/dev/event0) and driver as described in the linux/input.h kernel header file. For more information regarding standard Linux input drivers, please see Linux Input drivers at http://kernel.org.
Android's input event device is structured around an interrupt or polling routine that captures the device-specific scancode and converts it to a standard form acceptable to Linux (as defined in input.h) before passing it to the kernel with input_event().
The keymap driver's other primary function is to establish a probe function that sets up the interrupt or polling function, handles hardware initialization, and attaches the driver to the input subsystem with input_register_device().
The table below describes the steps required to translate from keyboard input to application action:
-| Step | -Action | -Explanation | -
|---|---|---|
| 1. | -Window manager reads key event from Linux keyboard driver. | -Events are typically positional. For example, the top-left position on a keypad returns 16 regardless of whether that key is printed with a Q (as on a QWERTY keypad) or an A (as on an AZERTY keypads). This first conversion by the Linux Keyboard Driver yields a scancode (for example, 16). | -
| 2. | -Window manager maps scancode to keycode. | -When the window manager reads a key event out of the driver, it maps the scancode to a keycode using a key layout map file. Typically, the keycode is the primary symbol screen-printed on a key. For example, KEYCODE_DPAD_CENTER is the center button on the five-way navigation control. Even though ALT + G generates a "?" character, KEYCODE_G is the keycode. |
-
| 3. | -Window manager sends both the scancode and the keycode to the application. | -Both the scancode and keycode are handled by the view with focus. - How the application interprets both depend on the application. | -
Key layout maps are installed in /system/usr/keylayout and /data/usr/keylayout.
For each keyboard device xxx, set the android.keylayout.xxx system property (see Building New Device for help setting system properties). If you don't specify a keylayout file, Android will default to /system/usr/keylayout/qwerty.kl.
Key layout maps are stored on the device as UTF-8 text files and have the following characteristics:
-key SCANCODE KEYCODE [FLAGS...], where SCANCODE is a number, KEYCODE is defined in your specific keylayout file (android.keylayout.xxx), and potential FLAGS are defined as follows:
-The following code comes from android/src/device/product/generic/tuttle2.kl and is an example of a complete key layout file:
-# Copyright 2007 Google Inc. - -key 2 1 -key 3 2 -key 4 3 -key 5 4 -key 6 5 -key 7 6 -key 8 7 -key 9 8 -key 10 9 -key 11 0 -key 158 BACK WAKE_DROPPED -key 230 SOFT_RIGHT WAKE -key 60 SOFT_RIGHT WAKE -key 107 ENDCALL WAKE_DROPPED -key 62 ENDCALL WAKE_DROPPED -key 229 MENU WAKE_DROPPED -key 59 MENU WAKE_DROPPED -key 228 POUND -key 227 STAR -key 231 CALL WAKE_DROPPED -key 61 CALL WAKE_DROPPED -key 232 DPAD_CENTER WAKE_DROPPED -key 108 DPAD_DOWN WAKE_DROPPED -key 103 DPAD_UP WAKE_DROPPED -key 102 HOME WAKE -key 105 DPAD_LEFT WAKE_DROPPED -key 106 DPAD_RIGHT WAKE_DROPPED -key 115 VOLUME_UP -key 114 VOLUME_DOWN -key 116 POWER WAKE -key 212 SLASH - -key 16 Q -key 17 W -key 18 E -key 19 R -key 20 T -key 21 Y -key 22 U -key 23 I -key 24 O -key 25 P - -key 30 A -key 31 S -key 32 D -key 33 F -key 34 G -key 35 H -key 36 J -key 37 K -key 38 L -key 14 DEL - -key 44 Z -key 45 X -key 46 C -key 47 V -key 48 B -key 49 N -key 50 M -key 51 COMMA -key 52 PERIOD -key 28 NEWLINE - -key 56 ALT_LEFT -key 42 SHIFT_LEFT -key 215 AT -key 57 SPACE -key 53 SLASH -key 127 SYM -key 100 ALT_LEFT - -key 399 GRAVE -- - -
Key character maps are installed in /system/usr/keychars and /data/usr/keychars.
For each keyboard device xxx, set the android.keychar.xxx system property to the full path of the desired keychar file. If you don't specify a keychar file, Android will default to /system/usr/keychar/qwerty.kl.
-
-
-
Key character maps are stored on the device as binary resources in order to reduce loading time. Key character maps have the following characteristics:
-columns MODIFIERS [...], where MODIFIERS are defined as follows:
-| Character in MODIFIERS | -Corresponding bit in the modifiers | -
|---|---|
| O | -no modifiers | -
| S | -MODIFIER_SHIFT | -
| C | -MODIFIER_CONTROL | -
| L | -MODIFIER_CAPS_LOCK | -
| A | -MODIFIER_ALT | -
key SCANCODE CHARACTER [...] where SCANCODE is a number and CHARACTER values are either UTF-8 characters in quotation marks (for example, "a") or a numeric value that strtol can parse.The following code comes from android/src/device/product/generic/tuttle2.kcm and represents a complete key character file:
The type line indicates what kind of keyboard your device implements. Possible types include:
-
-# Copyright 2007 Google Inc.
-
-[type=QWERTY]
-
-# keycode base caps fn caps_fn number display_label
-
-A 'a' 'A' '%' 0x00 '%' 'A'
-B 'b' 'B' '=' 0x00 '=' 'B'
-C 'c' 'C' '8' 0x00E7 '8' 'C'
-D 'd' 'D' '5' 0x00 '5' 'D'
-E 'e' 'E' '2' 0x0301 '2' 'E'
-F 'f' 'F' '6' 0x00A5 '6' 'F'
-G 'g' 'G' '-' '_' '-' 'G'
-H 'h' 'H' '[' '{' '[' 'H'
-I 'i' 'I' '$' 0x0302 '$' 'I'
-J 'j' 'J' ']' '}' ']' 'J'
-K 'k' 'K' '"' '~' '"' 'K'
-L 'l' 'L' ''' '`' ''' 'L'
-M 'm' 'M' '>' 0x00 '>' 'M'
-N 'n' 'N' '<' 0x0303 '<' 'N'
-O 'o' 'O' '(' 0x00 '(' 'O'
-P 'p' 'P' ')' 0x00 ')' 'P'
-Q 'q' 'Q' '*' 0x0300 '*' 'Q'
-R 'r' 'R' '3' 0x20AC '3' 'R'
-S 's' 'S' '4' 0x00DF '4' 'S'
-T 't' 'T' '+' 0x00A3 '+' 'T'
-U 'u' 'U' '&' 0x0308 '&' 'U'
-V 'v' 'V' '9' '^' '9' 'V'
-W 'w' 'W' '1' 0x00 '1' 'W'
-X 'x' 'X' '7' 0xEF00 '7' 'X'
-Y 'y' 'Y' '!' 0x00A1 '!' 'Y'
-Z 'z' 'Z' '#' 0x00 '#' 'Z'
-
-COMMA ',' ';' ';' '|' ',' ','
-PERIOD '.' ':' ':' 0x2026 '.' '.'
-AT '@' '0' '0' 0x2022 '0' '@'
-SLASH '/' '?' '?' '\' '/' '/'
-
-SPACE 0x20 0x20 0x9 0x9 0x20 0x20
-NEWLINE 0xa 0xa 0xa 0xa 0xa 0xa
-
-# on pc keyboards
-TAB 0x9 0x9 0x9 0x9 0x9 0x9
-0 '0' ')' ')' ')' '0' '0'
-1 '1' '!' '!' '!' '1' '1'
-2 '2' '@' '@' '@' '2' '2'
-3 '3' '#' '#' '#' '3' '3'
-4 '4' '$' '$' '$' '4' '4'
-5 '5' '%' '%' '%' '5' '5'
-6 '6' '^' '^' '^' '6' '6'
-7 '7' '&' '&' '&' '7' '7'
-8 '8' '*' '*' '*' '8' '8'
-9 '9' '(' '(' '(' '9' '9'
-
-GRAVE '`' '~' '`' '~' '`' '`'
-MINUS '-' '_' '-' '_' '-' '-'
-EQUALS '=' '+' '=' '+' '=' '='
-LEFT_BRACKET '[' '{' '[' '{' '[' '['
-RIGHT_BRACKET ']' '}' ']' '}' ']' ']'
-BACKSLASH '\' '|' '\' '|' '\' '\'
-SEMICOLON ';' ':' ';' ':' ';' ';'
-APOSTROPHE ''' '"' ''' '"' ''' '''
-STAR '*' '*' '*' '*' '*' '*'
-POUND '#' '#' '#' '#' '#' '#'
-PLUS '+' '+' '+' '+' '+' '+'
-
-
-
-The file snippet above gets converted to the following by the makekcharmap tool as part of the build process. You can mmap this file in and share the approximately 4k of memory that it uses between processes to minimize load time.
| Offset | - -Size (bytes) | -Description | -
|---|---|---|
| 0x00-0x0b | -- | The ascii value "keycharmap1" including the null character | - -
| 0x0c-0x0f | -- | padding | -
| 0x10-0x13 | - -- | The number of entries in the modifiers table (COLS) | -
| 0x14-0x17 | -- | The number of entries in the characters table (ROWS) | - -
| 0x18-0x1f | -- | padding | -
| - - | 4*COLS | -Modifiers table. The modifier mask values that each of the - columns in the characters table correspond to. | -
| - | - | padding to the next 16 byte boundary | - -
| - | 4*COLS*ROWS | -Characters table. The modifier mask values that each of the - columns correspond to. | -
The following file, pguide_events.c, illustrates how to implement an Android keymap driver.
-/* - * pguide_events.c - * - * ANDROID PORTING GUIDE: INPUT EVENTS DRIVER TEMPLATE - * - * This template is designed to an example of the functionality - * necessary for Android to recieve input events. The PGUIDE_EVENT - * macros are meant as pointers indicating where to implement the - * hardware specific code necessary for the new device. The existence - * of the macros is not meant to trivialize the work required, just as - * an indication of where the work needs to be done. - * - * Copyright 2007, Google Inc. - * Based on goldfish-events.c - * - */ - -#include- - --#include -#include -#include -#include -#include -#include - - -#include -#include - - - -#define PGUIDE_EVENTS_INTERRUPT do{} while(0) -#define PGUIDE_EVENTS_PROBE do{} while(0) - -struct event_dev { - struct input_dev *input; - int irq; -}; - -static irqreturn_t pguide_events_interrupt(int irq, void *dev_id) -{ - struct event_dev *edev = dev_id; - unsigned type=0, code=0, value=0; - - /* Set up type, code, and value per input.h - */ - PGUIDE_EVENTS_INTERRUPT; - - input_event(edev->input, type, code, value); - return IRQ_HANDLED; -} - -static int pguide_events_probe(struct platform_device *pdev) -{ - struct input_dev *input_dev; - struct event_dev *edev; - - printk("*** pguide events probe ***\n"); - - edev = kzalloc(sizeof(struct event_dev), GFP_KERNEL); - input_dev = input_allocate_device(); - - /* Setup edev->irq and do any hardware init */ - PGUIDE_EVENTS_PROBE; - - if(request_irq(edev->irq, pguide_events_interrupt, 0, - "pguide_events", edev) < 0) { - goto fail; - } - - /* indicate that we generate key events */ - set_bit(EV_KEY, input_dev->evbit); - set_bit(EV_REL, input_dev->evbit); - set_bit(EV_ABS, input_dev->evbit); - - /* indicate that we generate *any* key event */ - - bitmap_fill(input_dev->keybit, KEY_MAX); - bitmap_fill(input_dev->relbit, REL_MAX); - bitmap_fill(input_dev->absbit, ABS_MAX); - - platform_set_drvdata(pdev, edev); - - input_dev->name = "pguide_events"; - input_dev->private = edev; - input_dev->cdev.dev = &pdev->dev; - - input_register_device(input_dev); - return 0; - -fail: - kfree(edev); - input_free_device(input_dev); - - return -EINVAL; -} - -static struct platform_driver pguide_events_driver = { - .probe = pguide_events_probe, - .driver = { - .name = "pguide_events", - }, -}; - -static int __devinit pguide_events_init(void) -{ - return platform_driver_register(&pguide_events_driver); -} - - -static void __exit pguide_events_exit(void) -{ -} - -module_init(pguide_events_init); -module_exit(pguide_events_exit); - -MODULE_DESCRIPTION("Pguide Event Device"); -MODULE_LICENSE("GPL"); -
Assume the following for the setup of a new keypad device:
--android.keylayout.partnerxx_keypad = /system/usr/keylayout/partnerxx_keypad.kl -android.keychar.partnerxx_keypad = /system/usr/keychars/partnerxx.kcm --
The following example log file indicates that you have correctly registered the new keypad:
--I/EventHub( 1548): New device: path=/dev/input/event0 name=partnerxx_keypad id=0x10000 (of 0x1) index=1 fd=30 -I/EventHub( 1548): new keyboard input device added, name = partnerxx_keypad -D/WindowManager( 1548): Starting input thread. -D/WindowManager( 1548): Startup complete! -I/EventHub( 1548): New keyboard: name=partnerxx_keypad - keymap=partnerxx_keypad.kl - keymapPath=/system/usr/keychars/partnerxx_keypad.kcm.bin -I/ServiceManager( 1535): ServiceManager: addService(window, 0x13610) -I/EventHub( 1548): Reporting device opened: id=0x10000, name=/dev/input/event0 -I/KeyInputQueue( 1548): Device added: id=0x10000, name=partnerxx_keypad, classes=1 -I/KeyInputQueue( 1548): Keymap: partnerxx_keypad.kl --
The snippet above contains artificial line breaks to maintain a print-friendly document.
\ No newline at end of file diff --git a/pdk/docs/modules.html b/pdk/docs/modules.html deleted file mode 100755 index ea2a07a3b..000000000 --- a/pdk/docs/modules.html +++ /dev/null @@ -1,37 +0,0 @@ - - - - -Android supports its own Power Management (on top of the standard Linux Power Management) designed with the premise that the CPU shouldn't consume power if no applications or services require power. For more information regarding standard Linux power management, please see Linux Power Management Support at http://kernel.org.
-Android requires that applications and services request CPU resources with "wake locks" through the Android application framework and native Linux libraries. If there are no active wake locks, Android will shut down the CPU.
-The image below illustrates the Android power management architecture.
-
Wake locks are used by applications and services to request CPU resources.
- - -| Wake Lock | -Description | -
|---|---|
| ACQUIRE_CAUSES_WAKEUP |
- Normally wake locks don't actually wake the device, they just cause it to remain on once it's already on. Think of the video player app as the normal behavior. Notifications that pop up and want the device to be on are the exception; use this flag to be like them. | -
| FULL_WAKE_LOCK | -Wake lock that ensures that the screen and keyboard are on at full brightness. | -
| ON_AFTER_RELEASE | -When this wake lock is released, poke the user activity timer so the screen stays on for a little longer. | -
| PARTIAL_WAKE_LOCK | -Wake lock that ensures that the CPU is running. The screen might not be on. | -
| SCREEN_BRIGHT_WAKE_LOCK | -Wake lock that ensures that the screen is on at full brightness; the keyboard backlight will be allowed to go off. | -
| SCREEN_DIM_WAKE_LOCK | -Wake lock that ensures that the screen is on, but the keyboard backlight will be allowed to go off, and the screen backlight will be allowed to go dim. | -
All power management calls follow the same basic format:
-PowerManager service.The snippet below illustrates this process.
--PowerManager pm = (PowerManager)mContext.getSystemService( - Context.POWER_SERVICE); -PowerManager.WakeLock wl = pm.newWakeLock( - PowerManager.SCREEN_DIM_WAKE_LOCK - | PowerManager.ON_AFTER_RELEASE, - TAG); -wl.acquire(); - // ... -wl.release(); -- - -
The Android Framework exposes power management to services and applications through the PowerManager class.
User space native libraries (any hardware function in //device/lib/hardware/ meant to serve as supporting libraries for Android runtime) should never call into Android Power Management directly (see the image above). Bypassing the power management policy in the Android runtime will destabilize the system.
All calls into Power Management should go through the Android runtime PowerManager APIs.
-Please visit -http://code.google.com/android/reference/android/os/PowerManager.html for a description of the API and examples.
- - -You can register Kernel-level drivers with the Android Power Manager driver so that they're notified immediately before power down or after power up. For example, you might set a display driver to completely power down when a request comes in to power down from the user space (see the Android MSM MDDI display driver for a sample implementation).
-To register drivers with the Android PM driver, implement call-back handlers and register them with the Android PM, as illustrated in the snippet below:
--android_register_early_suspend(android_early_suspend_t *handler) -android_register_early_resume(android_early_resume_t *handler) --
It is critical in a drive to return immediately and not wait for anything to happen in the call back.
\ No newline at end of file diff --git a/pdk/docs/source_setup_guide.jd b/pdk/docs/source_setup_guide.jd deleted file mode 100755 index 5c0bed5e1..000000000 --- a/pdk/docs/source_setup_guide.jd +++ /dev/null @@ -1,116 +0,0 @@ -page.title=Host System Setup -@jd:body - - - - -This section provides instructions on how to configure your host system to build Android for mobile devices. While Android is designed as host-environment agnostic, it has been tested and is known to work on the following Linux operating system; Ubuntu 6.06 (Dapper), 7.10 (Gutsy), and 8.04. Cygwin is not recommended.
- - -Android requires the following system packages:
-On a clean Dapper system, type the following:
--% sudo apt-get install flex bison gperf libesd0-dev libwxgtk2.6-dev zlib1g-dev - build-essential --
This snippet includes an artificial line break to maintain a print-friendly document.
- - --## N.B. software from this repository is ENTIRELY UNSUPPORTED by the Ubuntu -## team, and may not be under a free license. Please satisfy yourself as to -## your rights to use the software. Also, please note that software in -## universe WILL NOT receive any review or updates from the Ubuntu security -## team. -# Line commented out by installer because it failed to verify: -deb http://us.archive.ubuntu.com/ubuntu/ gutsy universe -# Line commented out by installer because it failed to verify: -deb-src http://us.archive.ubuntu.com/ubuntu/ gutsy universe -# Line commented out by installer because it failed to verify: -deb http://us.archive.ubuntu.com/ubuntu/ gutsy-updates universe -# Line commented out by installer because it failed to verify: -deb-src http://us.archive.ubuntu.com/ubuntu/ gutsy-updates universe -
-% sudo apt-get install flex bison gperf libesd0-dev libwxgtk2.6-dev zlib1g-dev - build-essential --This snippet includes an artificial line break to maintain a print-friendly document. -
Install the X11 development environment with the following commands:
--% sudo apt-get install x-dev -% sudo apt-get install libx11-dev -% sudo apt-get install libncurses5-dev --
On a clean system, type the following:
--% sudo apt-get install flex bison gperf libesd0-dev libwxgtk2.6-dev -zlib1g-dev build-essential -% sudo apt-get install x-dev -% sudo apt-get install libx11-dev -% sudo apt-get install libncurses5-dev -% sudo apt-get install sun-java5-jdk -- - -
Android source code includes a hard dependency on the Java Developer Kit (JDK) 5.0 Update 12 or greater. The specific file name of the Update 12 package is jdk-1_5_0_12-linux-i586.bin. To download this version of the Java JDK:
Once you have cleanly installed the JDK, modify your PATH environment variable to include <jdk-install-dir>/jdk1.5.0_12/bin at its beginning so that Dapper will use the correct installation.
Ubuntu 7.10
-An alternative method to quickly install Java is to enable multiverse repo in /etc/apt/sources.list and then execute:
-% sudo apt-get install sun-java5-jdk -- - - diff --git a/pdk/docs/system_requirements.jd b/pdk/docs/system_requirements.jd deleted file mode 100755 index 2d3fcd68c..000000000 --- a/pdk/docs/system_requirements.jd +++ /dev/null @@ -1,59 +0,0 @@ -page.title=Device Requirements -pdk.version=1.0 -@jd:body - -
While Android is designed to support a wide variety of hardware platforms and configurations, this section provides recommended minimum device requirements.
-| Feature | -Minimum Requirement | -Notes | -
|---|---|---|
| Chipset | -ARM-based | -For the first release, Android is primarily targeted towards mobile handsets and portions of the platform, such as Dalvik VM graphics processing, currently assume an ARM architecture. | -
| Memory | -128 MB RAM; 256 MB Flash External | -Android can boot and run in configurations with less memory, but it isn't recommended. | -
| Storage | -Mini or Micro SD | -Not necessary for basic bring up, but recommended. | -
| Primary Display | -HVGA required | -The current Android interface targets a touch-based HVGA resolution display with a touch-interface no smaller than 2.8 inches in size. However, smaller displays will suffice for initial porting. | -
| Navigation Keys | -5-way navigation with 5 application keys, power, camera and volume controls | -- |
| Camera | -2MP CMOS | -Not required for basic bring up. | -
| USB | -Standard mini-B USB interface | -Android uses the USB interface for flashing the device system images and debugging a running device. | -
| Bluetooth | -1.2 or 2.0 | -Not required for initial bring up. | -
If available, your Android device can also benefit from the following optional device characteristics:
-Android's Radio Interface Layer (RIL) provides an abstraction layer between Android telephony services (android.telephony) and radio hardware. The RIL is radio agnostic, and includes support for Global System for Mobile communication (GSM)-based radios.
- - -The diagram below illustrates the RIL in the context of Android's Telephony system architecture.
-
The RIL consists of two primary components:
-ril.h that processes all communication with radio hardware and dispatches calls to the RIL Daemon (rild) through unsolicited commands.Android initializes the telephony stack and the Vendor RIL at startup as described in the sequence below:
-rild.lib path and rild.libargs system properties to determine the Vendor RIL library to use and any initialization arguments to provide to the Vendor RILRIL_Init to initialize the RIL and obtain a reference to RIL functionsRIL_register on the Android telephony stack, providing a reference to the Vendor RIL functionsSee the RIL Daemon source code at //device/commands/rild/rild.c for details.
There are two forms of communication that the RIL handles:
-DIAL and HANGUP.CALL_STATE_CHANGED and NEW_SMS.The following snippet illustrates the interface for solicited commands:
--void OnRequest (int request_id, void *data, size_t datalen, RIL_Token t); -void OnRequestComplete (RIL_Token t, RIL_Error e, void *response, size_t responselen); --
There are over sixty solicited commands grouped by the following families:
--
The following diagram illustrates a solicited call in Android.
-
The following snippet illustrates the interface for unsolicited commands:
--void OnUnsolicitedResponse (int unsolResponse, void *data, size_t datalen); --
There are over ten unsolicited commands grouped by the following families:
--
The following diagram illustrates an unsolicited call in Android.
-
To implement a radio-specific RIL, create a shared library that implements a set of functions required by Android to process radio requests. The required functions are defined in the RIL header (/include/telephony/ril.h).
The Android radio interface is radio-agnostic and the Vendor RIL can use any protocol to communicate with the radio. Android provides a reference Vendor RIL, using the Hayes AT command set, that you can use as a quick start for telephony testing and a guide for commercial vendor RILs. The source code for the reference RIL is found at /commands/reference-ril/.
Compile your Vendor RIL as a shared library using the convention libril-<companyname>-<RIL version>.so, for example, libril-acme-124.so, where:
Your Vendor RIL must define a RIL_Init function that provides a handle to the functions which will process all radio requests. RIL_Init will be called by the Android RIL Daemon at boot time to initialize the RIL.
- --RIL_RadioFunctions *RIL_Init (RIL_Env* env, int argc, char **argv); -- -
RIL_Init should return a RIL_RadioFunctions structure containing the handles to the radio functions:
-
-type structure {
- int RIL_version;
- RIL_RequestFunc onRequest;
- RIL_RadioStateRequest onStateRequest;
- RIL_Supports supports;
- RIL_Cancel onCancel;
- RIL_GetVersion getVersion;
-}
-RIL_RadioFunctions;
-
-
-
-ril.h defines RIL states and variables, such as RIL_UNSOL_STK_CALL_SETUP, RIL_SIM_READY, RIL_SIM_NOT_READY, as well as the functions described in the tables below. Skim the header file (/device/include/telephony/ril.h) for details.
The vendor RIL must provide the functions described in the table below to handle solicited commands. The RIL solicited command request types are defined in ril.h with the RIL_REQUEST_ prefix. Check the header file for details.
| Name | Description |
|---|---|
void (*RIL_RequestFunc) (int request, void *data, size_t datalen, RIL_Token t); |
-
- This is the RIL entry point for solicited commands and must be able to handle the various RIL solicited request types defined in
Must be completed with a call to |
-
RIL_RadioState (*RIL_RadioStateRequest)(); |
- This function should return the current radio state synchronously. | -
int (*RIL_Supports)(int requestCode); |
- This function returns "1" if the specified RIL_REQUEST code is supported and 0 if it is not. |
-
void (*RIL_Cancel)(RIL_Token t); |
- This function is used to indicate that a pending request should be canceled. This function is called from a separate thread--not the thread that calls On cancel, the callee should do its best to abandon the request and call Subsequent calls to
|
-
const char * (*RIL_GetVersion) (void); |
- Return a version string for your Vendor RIL | -
The vendor RIL uses the following callback methods to communicate back to the Android RIL daemon.
--
| Name | -Description | -
|---|---|
void RIL_onRequestComplete(RIL_Token t, RIL_Errno e, void *response, size_t responselen); |
-
|
-
void RIL_requestTimedCallback (RIL_TimedCallback callback, void *param, const struct timeval *relativeTime); |
- Call user-specified callback function on the same thread that RIL_RequestFunc is called. If relativeTime is specified, then it specifies a relative time value at which the callback is invoked. If relativeTime is NULL or points to a 0-filled structure, the callback will be invoked as soon as possible. |
-
The functions listed in the table below are call-back functions used by the Vendor RIL to invoke unsolicited commands on the Android platform. See ril.h for details.
-
| Name | -Description | -
|---|---|
void RIL_onUnsolicitedResponse(int unsolResponse, const void *data, size_t datalen); |
-
|
-
Android uses wpa_supplicant as the platform interface to the Wi-Fi device. Your Wi-Fi driver must be compatible with the standard wpa_supplicant in addition to extensions added to the supplicant (specifically, the "DRIVER" commands described in wifi.h/wifi_command()).
To create a Wi-Fi driver for Android:
-include/hardware/wifi.h, which also defines the Wi-Fi supplicant.libs/hardware/wifi/wpa_cli utilities.You can find the default implementation in libs/hardware/wifi/wifi.c. If you need to make changes, create a new source file similar to wifi.c, for example, wifi_mywifi.c.
Update the default Android.mk file (libs/hardware/wifi/Android.mk) as shown below.
-LOCAL_SHARED_LIBRARIES += libnetutils - -ifeq ($(TARGET_PRODUCT),acme) -LOCAL_SRC_FILES += wifi/wifi_mywifi.c -else -LOCAL_SRC_FILES += wifi/wifi.c -endif -- - -
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.
- - -