Add two documentation files describing the format of config and skin files.
diff --git a/android/utils/ini.h b/android/utils/ini.h
index a176bfe..83d2027 100644
--- a/android/utils/ini.h
+++ b/android/utils/ini.h
@@ -15,37 +15,7 @@
#include <stdint.h>
/* the emulator supports a simple .ini file format for its configuration
- * files. Here's the BNF for it:
- *
- * file := <line>*
- * line := <comment> | <LF> | <assignment>
- * comment := (';'|'#') <noLF>* <LF>
- * assignment := <space>* <keyName> <space>* '=' <space>* <valueString> <space>* <LF>
- * keyName := <keyNameStartChar> <keyNameChar>*
- * keyNameStartChar := [A-Za-z_]
- * keyNameChar := [A-Za-z0-9_.-]
- * valueString := <noLF>*
- * space := ' ' | '\t'
- * LF := '\r\n' | '\n' | '\r'
- * noLF := [^<LF>]
- *
- * Or, in English:
- *
- * - no support for sections
- * - empty lines are ignored, as well as lines beginning with ';' or '#'
- * - lines must be of the form: "<keyName> = <value>"
- * - key names must start with a letter or an underscore
- * - other key name characters can be letters, digits, underscores, dots or dashes
- *
- * - leading and trailing space are allowed and ignored before/after the key name
- * and before/after the value
- *
- * - there is no restriction on the value, except that it can't contain
- * leading/trailing space/tab characters or newline/charfeed characters
- *
- * - empty values are possible, and will be stored as an empty string.
- * - any badly formatted line is discarded (and will print a warning)
- *
+ * files. See docs/ANDROID-CONFIG-FILES.TXT for details.
*/
/* an opaque structure used to model an .ini configuration file */
diff --git a/docs/ANDROID-CONFIG-FILES.TXT b/docs/ANDROID-CONFIG-FILES.TXT
new file mode 100644
index 0000000..633b57a
--- /dev/null
+++ b/docs/ANDROID-CONFIG-FILES.TXT
@@ -0,0 +1,103 @@
+Android Emulator Config File Formats:
+====================================
+
+Introduction:
+-------------
+
+The Android emulator supports several file formats for its configuration
+files, depending on specific usage. This file documents them.
+
+
+I. Android .ini configuration files:
+------------------------------------
+
+The code in android/utils/ini.[hc] is used to support a simple .ini file
+format for some configuration files. Here's the BNF for it:
+
+ file := <line>*
+ line := <comment> | <LF> | <assignment>
+ comment := (';'|'#') <noLF>* <LF>
+ assignment := <space>* <keyName> <space>* '=' <space>* <valueString> <space>* <LF>
+ keyName := <keyNameStartChar> <keyNameChar>*
+ keyNameStartChar := [A-Za-z_]
+ keyNameChar := [A-Za-z0-9_.-]
+ valueString := <noLF>*
+ space := ' ' | '\t'
+ LF := '\r\n' | '\n' | '\r'
+ noLF := [^<LF>]
+
+Or, in plain English:
+
+ - No support for sections
+ - Empty lines are ignored, as well as lines beginning with ';' or '#'
+ - Lines must be of the form: "<keyName> = <value>"
+ - Key names must start with a letter or an underscore
+ - Other key name characters can be letters, digits, underscores, dots or
+ dashes
+
+ - Leading and trailing space are allowed and ignored before/after the key
+ name and before/after the value
+
+ - There is no restriction on the value, except that it can't contain
+ leading/trailing space/tab characters or newline/charfeed characters
+
+ - Empty values are possible, and will be stored as an empty string.
+ - Any badly formatted line is discarded (and will print a warning)
+
+
+II. Android 'aconfig' configuration files:
+------------------------------------------
+
+Alternatively, another configuration file format is supported by the code
+in android/config.[hc]. Its purpose is to support each config file as a
+tree of key/value pairs. More specifically:
+
+ - Each key or value is a string
+ - Each key can be associated either to a value, or a sub-tree
+ - A (key,value) pair is written in the config file as:
+
+ <keyname> <value>
+
+ which means the key name, some spaces, then the value.
+
+ - Dots can be used to separate keys in a tree path, as in:
+
+ some.other.name value
+
+ corresponding to a top-level key named 'some' with a single
+ sub-key 'other' which itself has a sub-key 'name' associated to
+ value 'value'.
+
+ - As a consequence, key names *cannot* contain a dot.
+
+ - Alternatively, braces can be used to group sub-keys, as in:
+
+ some {
+ other {
+ name value
+ name2 other-value
+ }
+ }
+
+ which defines a top-level 'some' key with two sub-keys 'name' and
+ 'name2'
+
+ - Brace and dot notations are equivalent, so the above config file
+ can also be written as:
+
+ some.other.name value
+ some.other.name2 other-value
+
+ - If a key appears twice in the config file, it replaces any
+ assigned value, hence:
+
+ some-key foo
+ some-key bar
+
+ defines 'some-key' to 'bar'
+
+ - If a sharp (#) appears whenever a key name is expected by the parser,
+ then it is considered a comment and will be ignored along anything that
+ follows on the current line.
+
+
diff --git a/docs/ANDROID-SKIN-FILES.TXT b/docs/ANDROID-SKIN-FILES.TXT
new file mode 100644
index 0000000..004f83d
--- /dev/null
+++ b/docs/ANDROID-SKIN-FILES.TXT
@@ -0,0 +1,221 @@
+Android Emulator Skin File Specification:
+=========================================
+
+ Revision 2. Dated 2009-12-07
+
+
+Introduction:
+-------------
+
+The Android emulator program is capable of displaying a window containing
+an image of a fake handset and associated controls (e.g. D-Pad, trackball,
+keyboard).
+
+The content of this window is dictated by a "skin", i.e. a collection of
+images and configuration data that indicates how to populate the window.
+Each skin can have several "layouts" (e.g. "landscape" and "portrait")
+corresponding to different orientation / physical configurations of the
+emulated handset.
+
+This document specifies how to generate a new skin for the emulator.
+
+General File Format:
+--------------------
+
+Each "skin" has a unique name and corresponds to a directory filled with
+various files. All skins are located under a parent "skin-dir" directory.
+You can use the '-skin-dir <path>' and '-skin <name>' options when starting
+the emulator to specify them. This will instruct the program to look into
+
+ <path>/<name>/
+
+For skin-specific files. Without these options, the emulator will look for
+skins in the SDK in a way described later in this document.
+
+The most important file in a skin must be named 'layout', as in:
+
+ <path>/<name>/layout
+
+The format of this file must follow the "aconfig" specification, see
+docs/ANDROID-CONFIG-FILES.TXT for details about it.
+
+
+Layouts & Parts:
+----------------
+
+Each skin file must define a list of 'parts' and a list of 'layouts'.
+
+A 'skin part' correspond to a named item that can contain a set of
+visual/control elements that can be of the following types:
+
+ - 'background': A background image in PNG format.
+
+ - 'display': An emulated LCD screen area.
+
+ - 'buttons': A set of clickable control areas (e.g. for a D-Pad, or
+ a Keyboard)
+
+Each part can be independently positioned and/or rotated in a 'layout'.
+A 'skin layout' is simply a specific arrangement of parts. A typical device
+skin file contains two layouts: one for landscape mode, and another one for
+portrait mode. More layouts can be used if needed. For example, one could
+use portrait + landscape-with-keyboard-closed + landscape-with-keyboard-opened)
+
+
+Skin Layouts:
+-------------
+
+Each skin layout is a named sub-key of the top-level 'layouts' key in the
+config file, for example:
+
+ layouts {
+ portrait {
+ ....
+ }
+ landscape {
+ ....
+ }
+ }
+
+Defines two layouts named 'portrait' and 'landscape'.
+
+Each layout can have the following keys (and corresponding values):
+
+- 'width': The width of the emulator window in pixels, as an integer
+
+- 'height': The height of the emulator window in pixels, as an integer
+
+- 'color' : Background color to be used to fill the emulator window.
+ this is a 32-bit ARGB value, the 0x prefix can be used to
+ use hexadecimal notation.
+
+- 'event' : An optional specific Linux event code that is generated whenever
+ the emulator switches/initializes this layout. This is used to
+ emulate the 'keyboard-lid open/close' events when emulating
+ certain devices with a hardware keyboard.
+
+ The value must be of the format:
+
+ <type>:<code>:<value>
+
+ Where the event type, code and value are numerical values or,
+ in certain cases string aliases for Linux input-subsystem event
+ codes. You can use the following emulator console commands to
+ print valid types and codes:
+
+ event types -> prints all valid types
+ event codes <type> -> prints all valid codes for <type>
+
+ The typical event to be used is EV_SW:0:1 for portrait mode
+ and EV_SW:0:0 for landscape ones. They corresponds to "keyboard
+ closed" and "keyboard opened" respectively, and would match a
+ device like the T-Mobile G1 or the Verizon Droid.
+
+- 'part<n>': Individual part references for the layout. They are named
+ in incremental numerical order, starting from 'part1', as in
+ 'part1', 'part2', 'part3', etc...
+
+ Each such key must contain the following sub-keys:
+
+ - 'name': The name of the corresponding part to be displayed
+ as defined in the rest of the configuration file
+
+ - 'x': Horizontal offset where the part is displayed
+ - 'y': Vertical offset where the part is displayed
+
+ - 'rotation': An optional sub-key which value is a integer
+ in the 0..3 range specifying the rotation
+ (in 90-degrees increment) to apply to the part
+ before display.
+
+- 'dpad-rotation':
+ An option integer in the 0..3 range indicating which
+ counter-rotation (in 90-degrees increments) to apply to the
+ D-Pad keys for proper usage.
+
+ This is needed because the Android framework considers that
+ the DPad is in landscape mode when the device is in landscape
+ mode and will-auto-rotate the D-Pad value. This setting is used
+ to counter-effect this correction for certain skins which
+ do not rotate the DPad in landscape mode.
+
+Skin Parts:
+-----------
+
+Each skin part is a sub-key of the top-level 'parts' key in the configuration
+file. For example:
+
+ parts {
+ foo {
+ ...
+ }
+ bar {
+ ...
+ }
+ zoo {
+ ...
+ }
+ }
+
+Defines three parts named 'foo', 'bar' and 'zoo'.
+
+Each part can have one or more elements of the following type/key name that
+will determine its visual appearance:
+
+- 'background':
+ A background image in PNG format. This is a tree key that can
+ have the following sub-keys:
+
+ - 'image': Name of the PNG image in the skin directory
+ - 'x' : Optional horizontal offset in pixels (integer)
+ - 'y' : Optional vertical offset in pixels (integer)
+
+- 'display':
+ An optional rectangular area that will appear on top of the
+ background image to display an emulated LCD screen. Valid sub-keys
+ are:
+
+ - 'x' : Optional horizontal offset in pixels (integer)
+ - 'y' : Optional vertical offset in pixels (integer)
+ - 'width' : Width in pixels (integer)
+ - 'height' : Height in pixels (integer)
+ - 'rotation': Optional rotation value (0..3) in 90 degrees
+ increments.
+
+- 'buttons':
+ Used to define a list of rectangular clickable control areas with
+ an optional high-lighting image. Each sub-key must have a unique
+ name, and may contain the following sub-sub-keys:
+
+ - 'x' : Horizontal offset in pixels (integer)
+ - 'y' : Vertical offset in pixels (integer)
+ - 'image' : PNG image of the high-lighting for the button
+
+ Each highlight image will be drawn on top of the background are for
+ the button. A typical one has 50% opacity. The highlight will be drawn
+ twice to simulate 'clicked' state.
+
+ The image's dimensions are used to determine the size of the control
+ area.
+
+ The name of each button must correspond to the list of key symbols
+ defined in the _keyinfo_table array defined in android/skin/file.c.
+
+Other top-level keys:
+---------------------
+
+A few other top-level keys are supported for legacy reasons, but the
+corresponding definition is best defined in the hardware properties/config
+file instead:
+
+- 'keyboard.charmap':
+ Optional, must be the name of the charmap being used for this
+ skin. Currently unused so ignore this.
+
+- 'network.speed':
+ Default network speed for this skin. Values correspond to the
+ -netspeed <speed> emulator command-line option.
+
+- 'network.delay':
+ Default network latency for this skin. Values correspond to the
+ -netdelay <delay> emulator command-line option.
