Add documentation for framebuffer emulation.

Change-Id: I9f1ac21df0e6644533c4f35fe51e08ae7a979fb3

1 files changed, 88 insertions, 0 deletions

diff --git a/docs/ANDROID-FRAMEBUFFER.TXT b/docs/ANDROID-FRAMEBUFFER.TXT
new file mode 100644
index 0000000..9e7ac28
--- /dev/null
+++ b/docs/ANDROID-FRAMEBUFFER.TXT
@@ -0,0 +1,88 @@
+Android Framebuffer emulation technical notes:
+==============================================
+
+This document tries to explain how framebuffer emulation works in the
+Android emulator.
+
+1 - Hardware emulation (hw/goldfish_fb.c):
+------------------------------------------
+
+  The emulated hardware provides a bunch of i/o registers to allow
+  the following:
+
+  - let the kernel query the framebuffer's dimensions (both in pixels
+    and millimeters) (see goldfish_fb_read)
+
+  - let the kernel control the physical base address for the framebuffer
+    and the internal pixel rotation to apply before display (see
+    goldfish_fb_write).
+
+  The pixel buffer is itself a set of physical pages allocated by the
+  kernel driver in the emulated system. These pages are contiguous in
+  the emulated system, but not in the emulator's process space which
+  places them randomly in the heap.
+
+  Also, a function called goldfish_fb_update_display() is in charge of
+  checking the dirty bits of the framebuffer physical pages, in order to
+  compute the bounding rectangle of pixel updates since the last call, and
+  send them to the UI through qframebuffer_update(). More on this later.
+
+
+2 - Framebuffer abstract interface (framebuffer.h):
+---------------------------------------------------
+
+  The Android-specific header 'framebuffer.h' is used to provide a generic
+  interface between framebuffer 'producers' and 'clients'. Essentially, each
+  QFrameBuffer object:
+
+    - holds a contiguous pixel buffer allocated by the emulator.
+    - can have one producer in charge of drawing into the pixel buffer
+    - can have zero or more clients, in charge of displaying the pixel
+      buffer to the final UI window (or remote VNC connection, whatever).
+
+  The emulator will periodically call 'qframebuffer_check_updates()' which
+  does the following:
+
+      foreach fb in framebuffers:
+          if fb.producer:
+            fb.producer.check_updates()
+              => in producer
+               foreach up in updates:
+                 qframebuffer_update(fb, up.x, up.y, up.w, up.h)
+                   =>
+                     foreach cl in fb.clients:
+                        cl.update(cl.opaque, up.x, up.y. up.w, up.h)
+
+  hw/goldfish_fb.c implements a producer
+  the QEmulator type in android/main.c implements a client.
+
+
+3 - DisplayState (console.h):
+-----------------------------
+
+  The upstream QEMU sources use a DisplayState object to model the state
+  of each "display". This is not conceptually exactly the same thing than
+  a QFrameBuffer object as it can also be used to emulated text-based
+  displays instead of pixel framebuffers, and incorporates input state
+  as well.
+
+  See sdl_display_init() in android/main.c which is called from vl-android.c
+  on startup to initialize the display. This really registers a function,
+  sdl_refresh() (in android/main.c), that will get called every 1/60th of
+  a second to handle pending inputs.
+
+  sdl_refresh() also calls qframebuffer_check_updates(), ensuring that
+  any animation in the emulated framebuffer will be displayed at the same
+  frequency.
+
+  The refresh frequency is defined by the GUI_REFRESH_INTERVAL defined
+  at the top of console.h
+
+
+4 - QEmulator object:
+---------------------
+
+  Currently defined and implemented in android/main.c (we may want to move
+  it to a different location). The QEmulator object bridges provides a
+  framebuffer client that uses the "generic" skin code under android/skin
+  to display the main UI window.