Home | History | Annotate | Download | only in docs 
      1 Android Framebuffer emulation technical notes:
      2 ==============================================
      3 
      4 This document tries to explain how framebuffer emulation works in the
      5 Android emulator.
      6 
      7 1 - Hardware emulation (hw/android/goldfish/fb.c):
      8 --------------------------------------------------
      9 
     10   The emulated hardware provides a bunch of i/o registers to allow
     11   the following:
     12 
     13   - let the kernel query the framebuffer's dimensions (both in pixels
     14     and millimeters) (see goldfish_fb_read)
     15 
     16   - let the kernel control the physical base address for the framebuffer
     17     and the internal pixel rotation to apply before display (see
     18     goldfish_fb_write).
     19 
     20   Read docs/GOLDFISH-VIRTUAL-HARDWARE.TXT for low-level details.
     21 
     22   The pixel buffer is itself a set of physical pages allocated by the
     23   kernel driver in the emulated system. These pages are contiguous in
     24   the emulated system, but not in the emulator's process space which
     25   places them randomly in the heap.
     26 
     27   Also, a function called goldfish_fb_update_display() is in charge of
     28   checking the dirty bits of the framebuffer physical pages, in order to
     29   compute the bounding rectangle of pixel updates since the last call, and
     30   send them to the UI through qframebuffer_update(). More on this later.
     31 
     32 
     33 2 - Framebuffer abstract interface (framebuffer.h):
     34 ---------------------------------------------------
     35 
     36   The Android-specific header 'framebuffer.h' is used to provide a generic
     37   interface between framebuffer 'producers' and 'clients'. Essentially, each
     38   QFrameBuffer object:
     39 
     40     - holds a contiguous pixel buffer allocated by the emulator.
     41     - can have one producer in charge of drawing into the pixel buffer
     42     - can have zero or more clients, in charge of displaying the pixel
     43       buffer to the final UI window (or remote VNC connection, whatever).
     44 
     45   The emulator will periodically call 'qframebuffer_check_updates()' which
     46   does the following:
     47 
     48       foreach fb in framebuffers:
     49           if fb.producer:
     50             fb.producer.check_updates()
     51               => in producer
     52                foreach up in updates:
     53                  qframebuffer_update(fb, up.x, up.y, up.w, up.h)
     54                    =>
     55                      foreach cl in fb.clients:
     56                         cl.update(cl.opaque, up.x, up.y. up.w, up.h)
     57 
     58   hw/android/goldfish/fb.c implements a producer
     59   the QEmulator type in android/main.c implements a client.
     60 
     61 
     62 3 - DisplayState (console.h):
     63 -----------------------------
     64 
     65   The upstream QEMU sources use a DisplayState object to model the state
     66   of each "display". This is not conceptually exactly the same thing than
     67   a QFrameBuffer object as it can also be used to emulated text-based
     68   displays instead of pixel framebuffers, and incorporates input state
     69   as well.
     70 
     71   See sdl_display_init() in android/main.c which is called from vl-android.c
     72   on startup to initialize the display. This really registers a function,
     73   sdl_refresh() (in android/main.c), that will get called every 1/60th of
     74   a second to handle pending inputs.
     75 
     76   sdl_refresh() also calls qframebuffer_check_updates(), ensuring that
     77   any animation in the emulated framebuffer will be displayed at the same
     78   frequency.
     79 
     80   The refresh frequency is defined by the GUI_REFRESH_INTERVAL defined
     81   at the top of console.h
     82 
     83 
     84 4 - QEmulator object:
     85 ---------------------
     86 
     87   Currently defined and implemented in android/main.c (we may want to move
     88   it to a different location). The QEmulator object bridges provides a
     89   framebuffer client that uses the "generic" skin code under android/skin
     90   to display the main UI window.
     91