libutils/README - android_system_core - Gitiles

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