Add two documentation files describing the format of config and skin files.

2 files changed, 324 insertions, 0 deletions

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.