AI 144597: am: CL 144596 am: CL 144595 Fix the AVD configuration code to support "sdcard.path" in config.ini to indicate an explicit SD Card image file (instead of using the one in the content directory)

  Note that this also fix a bug where the SD Card image was not properly locked in the previous implementation.
  Allow the http-proxy support code to actually manage to receive chunked encoding data, instead of complaining needlessly.
  Introduce a new CharBuffer object that is used indirectly by "-radio <hostdevice>" and "-gps <hostdevice>" options
  Add new documentation for QEMUD and CharDriverState objects
  Update the Audio documentation with ASCII graphics (because I'm an artist too)
  Original author: digit
  Merged from: //branches/cupcake/...
  Original author: android-build

Automated import of CL 144597

1 files changed, 241 insertions, 0 deletions

diff --git a/docs/ANDROID-QEMUD.TXT b/docs/ANDROID-QEMUD.TXT
new file mode 100644
index 0000000..6415a47
--- /dev/null
+++ b/docs/ANDROID-QEMUD.TXT
@@ -0,0 +1,241 @@
+                    THE ANDROID "QEMUD" MULTIPLEXING DAEMON
+
+I. Overview:
+------------
+
+The Android system image includes a small daemon program named "qemud"
+which is started at boot time. Its purpose is to provide a multiplexing
+communication channel between the emulated system and the emulator program
+itself.
+
+Its goal is to allow certain parts of the system to talk directly to the
+emulator without requiring special kernel support; this simplifies a lot of
+things since it does *not* require:
+
+- writing/configuring a specific kernel driver
+- writing the corresponding hardware emulation code in hw/goldfish_xxxx.c
+- dealing with device allocation and permission issues in the emulated system
+
+The emulator provides 'services' to various parts of the emulated system.
+Each service is identified by a name and serves a specific purpose. For
+example:
+
+   "gsm"       Used to communicate with the emulated GSM modem with
+               AT commands.
+
+   "gps"       Used to receive NMEA sentences broadcasted from the
+               emulated GPS device.
+
+   "sensors"   Used to list the number of emulated sensors, as well as
+               enable/disable reception of specific sensor events.
+
+   "control"   Used to control misc. simple emulated hardware devices
+               (e.g. vibrator, leds, LCD backlight, etc...)
+
+
+II. Implementation:
+-------------------
+
+Since the "cupcake" platform, this works as follows:
+
+- A 'qemud client' is any part of the emulated system that wants to talk
+  to the emulator. It does so by:
+
+  - connecting to the /dev/socket/qemud Unix domain socket
+  - sending the service name through the socket
+  - receives two bytes of data, which will be "OK" in case of
+    success, or "KO" in case of failure.
+
+  After an OK, the same connection can be used to talk directly to the
+  corresponding service.
+
+
+- The /dev/socket/qemud Unix socket is created by init and owned by the
+  'qemud' daemon started at boot by /system/etc/init.goldfish.rc
+
+  The daemon also opens an emulated serial port (e.g. /dev/ttyS1) and
+  will pass all messages between clients and emulator services. Thus,
+  everything looks like the following:
+
+
+     emulator <==serial==> qemud <---> /dev/socket/qemud <-+--> client1
+                                                           |
+                                                           +--> client2
+
+  A very simple multiplexing protocol is used on the serial connection:
+
+           offset    size    description
+
+               0       2     2-char hex string giving the destination or
+                             source channel
+
+               2       4     4-char hex string giving the payload size
+
+               6       n     the message payload
+
+  Where each client gets a 'channel' number allocated by the daemon
+  at connection time.
+
+  Note that packets larger than 65535 bytes cannot be sent directly
+  through the qemud channel. This is intentional; for large data
+  communication, the client and service should use a fragmentation
+  convention that deals with this.
+
+  Zero-sized packets are silently discard by qemud and the emulator and
+  should normally not appear on the serial port.
+
+  Channel 0 is reserved for control messages between the daemon and the
+  emulator. These are the following:
+
+    - When a client connects to /dev/socket/qemud and sends a service
+      name to the daemon, the later sends to the emulator:
+
+        connect:<service>:<id>
+
+      where <service> is the service name, and <id> is a 4-hexchar string
+      giving the allocated channel index for the client.
+
+
+    - The emulator can respond in case of success with:
+
+        ok:connect:<id>
+
+      or, in case of failure, with:
+
+        ok:connect:<id>:<reason>
+
+      where <reason> is a liberal string giving the reason for failure.
+      It is never sent to clients (which will only receive a "KO") and
+      is used strictly for debugging purposes.
+
+    - After a succesful connect, all messages between the client and
+      the corresponding emulator service will be passed through the
+      corresponding numbered channel.
+
+      But if the client disconnects from the socket, the daemon will
+      send through channel 0 this message to the emulator:
+
+        disconnect:<id>
+
+    - If an emulator service decides, for some reason, to disconnect
+      a client, the emulator will send to the daemon (on channel 0):
+
+        disconnect:<id>
+
+      The daemon deals with this gracefully (e.g. it will wait that the
+      client has read all buffered data in the daemon before closing the
+      socket, to avoid packet loss).
+
+    - Any other command sent from the daemon to the emulator will result
+      in the following answer:
+
+        ko:bad command
+
+- Which exact serial port to open is determined by the emulator at startup
+  and is passed to the system as a kernel parameter, e.g.:
+
+        android.qemud=ttyS1
+
+
+- The code to support services and their clients in the emulator is located
+  in android/hw-qemud.c. This code is heavily commented.
+
+  The daemon's source is in $ROOT/development/emulator/qemud/qemud.c
+
+  The header in $ROOT/hardware/libhardware/include/hardware/qemud.h
+  can be used by clients to ease connecting and talking to QEMUD-based
+  services.
+
+  This is used by $ROOT/developement/emulator/sensors/sensors_qemu.c which
+  implements emulator-specific sensor support in the system by talking to
+  the "sensors" service provided by the emulator (if available).
+
+  Code in $ROOT/hardware/libhardware_legacy also uses QEMUD-based services.
+
+
+- Certain services also implement a simple framing protocol when exchanging
+  messages with their clients. The framing happens *after* serial port
+  multiplexing and looks like:
+
+           offset    size    description
+
+               0       4     4-char hex string giving the payload size
+
+               4       n     the message payload
+
+  This is needed because the framing protocol used on the serial port is
+  not preserved when talking to clients through /dev/socket/qemud.
+
+  Certain services do not need it at all (GSM, GPS) so it is optional and
+  must be used depending on which service you talk to by clients.
+
+
+III. Legacy 'qemud':
+--------------------
+
+The system images provided by the 1.0 and 1.1 releases of the Android SDK
+implement an older variant of the qemud daemon that uses a slightly
+different protocol to communicate with the emulator.
+
+This is documented here since this explains some subtleties in the
+implementation code of android/hw-qemud.c
+
+The old scheme also used a serial port to allow the daemon and the emulator
+to communicate. Besides, the same multiplexing protocol was used to pass
+messages through multiple channels. However, several other differences
+exist, best illustrated by the following graphics:
+
+    emulator <==serial==> qemud <-+--> /dev/socket/qemud_gsm <--> GSM client
+                                  |
+                                  +--> /dev/socket/qemud_gps <--> GPS client
+                                  |
+                                  +--> /dev/socket/qemud_control <--> client(s)
+
+Now, for the details:
+
+ - instead of a single /dev/socket/qemud, init created several Unix domain
+   sockets, one per service:
+
+        /dev/socket/qemud_gsm
+        /dev/socket/qemud_gps
+        /dev/socket/qemud_control
+
+   note that there is no "sensors" socket in 1.0 and 1.1
+
+ - the daemon created a de-facto numbered channel for each one of these
+   services, even if no client did connect to it (only one client could
+   connect to a given service at a time).
+
+ - at startup, the emulator does query the channel numbers of all services
+   it implements, e.g. it would send *to* the daemon on channel 0:
+
+        connect:<service>
+
+   where <service> can be one of "gsm", "gps" or "control"
+
+   (Note that on the current implementation, the daemon is sending connection
+   messages to the emulator instead).
+
+ - the daemon would respond with either:
+
+        ok:connect:<service>:<hxid>
+
+   where <service> would be the service name, and <hxid> a 4-hexchar channel
+   number (NOTE: 4 chars, not 2). Or with:
+
+        ko:connect:bad name
+
+
+This old scheme was simpler to implement in both the daemon and the emulator
+but lacked a lot of flexibility:
+
+  - adding a new service required to modify /system/etc/init.goldfish.rc
+    as well as the daemon source file (which contained a hard-coded list
+    of sockets to listen to for client connections).
+
+  - only one client could be connected to a given service at a time,
+    except for the GPS special case which was a unidirectionnal broadcast
+    by convention.
+
+The current implementation moves any service-specific code to the emulator,
+only uses a single socket and allows concurrent clients for a all services.