diff options
Diffstat (limited to 'libs/utils/README')
| -rw-r--r-- | libs/utils/README | 289 |
1 files changed, 0 insertions, 289 deletions
diff --git a/libs/utils/README b/libs/utils/README deleted file mode 100644 index 01741e0..0000000 --- a/libs/utils/README +++ /dev/null @@ -1,289 +0,0 @@ -Android Utility Function Library -================================ - - -If you need a feature that is native to Linux but not present on other -platforms, construct a platform-dependent implementation that shares -the Linux interface. That way the actual device runs as "light" as -possible. - -If that isn't feasible, create a system-independent interface and hide -the details. - -The ultimate goal is *not* to create a super-duper platform abstraction -layer. The goal is to provide an optimized solution for Linux with -reasonable implementations for other platforms. - - - -Resource overlay -================ - - -Introduction ------------- - -Overlay packages are special .apk files which provide no code but -additional resource values (and possibly new configurations) for -resources in other packages. When an application requests resources, -the system will return values from either the application's original -package or any associated overlay package. Any redirection is completely -transparent to the calling application. - -Resource values have the following precedence table, listed in -descending precedence. - - * overlay package, matching config (eg res/values-en-land) - - * original package, matching config - - * overlay package, no config (eg res/values) - - * original package, no config - -During compilation, overlay packages are differentiated from regular -packages by passing the -o flag to aapt. - - -Background ----------- - -This section provides generic background material on resources in -Android. - - -How resources are bundled in .apk files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Android .apk files are .zip files, usually housing .dex code, -certificates and resources, though packages containing resources but -no code are possible. Resources can be divided into the following -categories; a `configuration' indicates a set of phone language, display -density, network operator, etc. - - * assets: uncompressed, raw files packaged as part of an .apk and - explicitly referenced by filename. These files are - independent of configuration. - - * res/drawable: bitmap or xml graphics. Each file may have different - values depending on configuration. - - * res/values: integers, strings, etc. Each resource may have different - values depending on configuration. - -Resource meta information and information proper is stored in a binary -format in a named file resources.arsc, bundled as part of the .apk. - -Resource IDs and lookup -~~~~~~~~~~~~~~~~~~~~~~~ -During compilation, the aapt tool gathers application resources and -generates a resources.arsc file. Each resource name is assigned an -integer ID 0xppttiii (translated to a symbolic name via R.java), where - - * pp: corresponds to the package namespace (details below). - - * tt: corresponds to the resource type (string, int, etc). Every - resource of the same type within the same package has the same - tt value, but depending on available types, the actual numerical - value may be different between packages. - - * iiii: sequential number, assigned in the order resources are found. - -Resource values are specified paired with a set of configuration -constraints (the default being the empty set), eg res/values-sv-port -which imposes restrictions on language (Swedish) and display orientation -(portrait). During lookup, every constraint set is matched against the -current configuration, and the value corresponding to the best matching -constraint set is returned (ResourceTypes.{h,cpp}). - -Parsing of resources.arsc is handled by ResourceTypes.cpp; this utility -is governed by AssetManager.cpp, which tracks loaded resources per -process. - -Assets are looked up by path and filename in AssetManager.cpp. The path -to resources in res/drawable are located by ResourceTypes.cpp and then -handled like assets by AssetManager.cpp. Other resources are handled -solely by ResourceTypes.cpp. - -Package ID as namespace -~~~~~~~~~~~~~~~~~~~~~~~ -The pp part of a resource ID defines a namespace. Android currently -defines two namespaces: - - * 0x01: system resources (pre-installed in framework-res.apk) - - * 0x7f: application resources (bundled in the application .apk) - -ResourceTypes.cpp supports package IDs between 0x01 and 0x7f -(inclusive); values outside this range are invalid. - -Each running (Dalvik) process is assigned a unique instance of -AssetManager, which in turn keeps a forest structure of loaded -resource.arsc files. Normally, this forest is structured as follows, -where mPackageMap is the internal vector employed in ResourceTypes.cpp. - -mPackageMap[0x00] -> system package -mPackageMap[0x01] -> NULL -mPackageMap[0x02] -> NULL -... -mPackageMap[0x7f - 2] -> NULL -mPackageMap[0x7f - 1] -> application package - - - -The resource overlay extension ------------------------------- - -The resource overlay mechanism aims to (partly) shadow and extend -existing resources with new values for defined and new configurations. -Technically, this is achieved by adding resource-only packages (called -overlay packages) to existing resource namespaces, like so: - -mPackageMap[0x00] -> system package -> system overlay package -mPackageMap[0x01] -> NULL -mPackageMap[0x02] -> NULL -... -mPackageMap[0x7f - 2] -> NULL -mPackageMap[0x7f - 1] -> application package -> overlay 1 -> overlay 2 - -The use of overlay resources is completely transparent to -applications; no additional resource identifiers are introduced, only -configuration/value pairs. Any number of overlay packages may be loaded -at a time; overlay packages are agnostic to what they target -- both -system and application resources are fair game. - -The package targeted by an overlay package is called the target or -original package. - -Resource overlay operates on symbolic resources names. Hence, to -override the string/str1 resources in a package, the overlay package -would include a resource also named string/str1. The end user does not -have to worry about the numeric resources IDs assigned by aapt, as this -is resolved automatically by the system. - -As of this writing, the use of resource overlay has not been fully -explored. Until it has, only OEMs are trusted to use resource overlay. -For this reason, overlay packages must reside in /system/overlay. - - -Resource ID mapping -~~~~~~~~~~~~~~~~~~~ -Resource identifiers must be coherent within the same namespace (ie -PackageGroup in ResourceTypes.cpp). Calling applications will refer to -resources using the IDs defined in the original package, but there is no -guarantee aapt has assigned the same ID to the corresponding resource in -an overlay package. To translate between the two, a resource ID mapping -{original ID -> overlay ID} is created during package installation -(PackageManagerService.java) and used during resource lookup. The -mapping is stored in /data/resource-cache, with a @idmap file name -suffix. - -The idmap file format is documented in a separate section, below. - - -Package management -~~~~~~~~~~~~~~~~~~ -Packages are managed by the PackageManagerService. Addition and removal -of packages are monitored via the inotify framework, exposed via -android.os.FileObserver. - -During initialization of a Dalvik process, ActivityThread.java requests -the process' AssetManager (by proxy, via AssetManager.java and JNI) -to load a list of packages. This list includes overlay packages, if -present. - -When a target package or a corresponding overlay package is installed, -the target package's process is stopped and a new idmap is generated. -This is similar to how applications are stopped when their packages are -upgraded. - - -Creating overlay packages -------------------------- - -Overlay packages should contain no code, define (some) resources with -the same type and name as in the original package, and be compiled with -the -o flag passed to aapt. - -The aapt -o flag instructs aapt to create an overlay package. -Technically, this means the package will be assigned package id 0x00. - -There are no restrictions on overlay packages names, though the naming -convention <original.package.name>.overlay.<name> is recommended. - - -Example overlay package -~~~~~~~~~~~~~~~~~~~~~~~ - -To overlay the resource bool/b in package com.foo.bar, to be applied -when the display is in landscape mode, create a new package with -no source code and a single .xml file under res/values-land, with -an entry for bool/b. Compile with aapt -o and place the results in -/system/overlay by adding the following to Android.mk: - -LOCAL_AAPT_FLAGS := -o com.foo.bar -LOCAL_MODULE_PATH := $(TARGET_OUT)/overlay - - -The ID map (idmap) file format ------------------------------- - -The idmap format is designed for lookup performance. However, leading -and trailing undefined overlay values are discarded to reduce the memory -footprint. - - -idmap grammar -~~~~~~~~~~~~~ -All atoms (names in square brackets) are uint32_t integers. The -idmap-magic constant spells "idmp" in ASCII. Offsets are given relative -to the data_header, not to the beginning of the file. - -map := header data -header := idmap-magic <crc32-original-pkg> <crc32-overlay-pkg> -idmap-magic := <0x706d6469> -data := data_header type_block+ -data_header := <m> header_block{m} -header_block := <0> | <type_block_offset> -type_block := <n> <id_offset> entry{n} -entry := <resource_id_in_target_package> - - -idmap example -~~~~~~~~~~~~~ -Given a pair of target and overlay packages with CRC sums 0x216a8fe2 -and 0x6b9beaec, each defining the following resources - -Name Target package Overlay package -string/str0 0x7f010000 - -string/str1 0x7f010001 0x7f010000 -string/str2 0x7f010002 - -string/str3 0x7f010003 0x7f010001 -string/str4 0x7f010004 - -bool/bool0 0x7f020000 - -integer/int0 0x7f030000 0x7f020000 -integer/int1 0x7f030001 - - -the corresponding resource map is - -0x706d6469 0x216a8fe2 0x6b9beaec 0x00000003 \ -0x00000004 0x00000000 0x00000009 0x00000003 \ -0x00000001 0x7f010000 0x00000000 0x7f010001 \ -0x00000001 0x00000000 0x7f020000 - -or, formatted differently - -0x706d6469 # magic: all idmap files begin with this constant -0x216a8fe2 # CRC32 of the resources.arsc file in the original package -0x6b9beaec # CRC32 of the resources.arsc file in the overlay package -0x00000003 # header; three types (string, bool, integer) in the target package -0x00000004 # header_block for type 0 (string) is located at offset 4 -0x00000000 # no bool type exists in overlay package -> no header_block -0x00000009 # header_block for type 2 (integer) is located at offset 9 -0x00000003 # header_block for string; overlay IDs span 3 elements -0x00000001 # the first string in target package is entry 1 == offset -0x7f010000 # target 0x7f01001 -> overlay 0x7f010000 -0x00000000 # str2 not defined in overlay package -0x7f010001 # target 0x7f010003 -> overlay 0x7f010001 -0x00000001 # header_block for integer; overlay IDs span 1 element -0x00000000 # offset == 0 -0x7f020000 # target 0x7f030000 -> overlay 0x7f020000 |