This tries to document the mess that is DisplayState in QEMU.
See "console.h" for the main definitions, and below for some
explanations:
DISPLAY STATE OBJECTS:
======================
A DisplayState holds state for stuff to be displayed on QEMU. More
precisely:
- A DisplayState owns a 'DisplaySurface' which is nothing more than a
pixel buffer with specific dimensions, pitch and format plus bytes
to carry its content.
- A DisplayState also holds a 'DisplayAllocator' which allows it to
allocate its surface through a proper API. For example, this is
used in the upstream sdl UI backend to allocate the surface pixels
through SDL_SetVideoMode(). The default allocator simply uses
'malloc' to do the allocation (with 32-bits/pixel).
- A DisplayState also holds a list of DisplayChangeListener object.
Each listener contains a small set of callbacks that will be called
whenever an "event" happens on the display state. Events examples
are:
dpy_update: a rectangular portion of the surface has been updated.
dpy_resize: the hardware decided to resize the framebuffer.
dpy_refresh: called periodically by the GUI timer.
dpy_copy: the hardware performed a rectangular copy operation.
dpy_fill: the hardware performed a rectangular fill operation.
dpy_setdata: the hardware decided to change the framebuffer address.
dpy_text_cursor: the hardware placed the text cursor at a given (x,y).
NOTE: dpy_setdata is essentially the same than dpy_resize except that
there is a guarantee that the size didn't change.
More on DisplayChangeListeners below.
- The file "console.h" provides many helper functions to call all listeners
registered for a given DisplayState. For example, dpy_update(ds,x,y,w,h)
will call the 'dpy_update' callback of all listeners for the display
state 'ds'.
CONSOLES:
=========
A "console" is something that can write pixels into a DisplayState.
There are two kinds of consoles, and they're fairly different in usage.
GRAPHICAL CONSOLE:
------------------
A "Graphical console" creates and owns a DisplayState. It is used when one
needs to write directly to the DisplaySurface pixel buffer. A typical
hardware framebuffer emulator (e.g. hw/vga-pic.c) will call the
function graphic_console_init() to create the DisplayState. Note that
this functions accepts several callbacks and is defined as:
typedef void (*vga_hw_update_ptr)(void *);
typedef void (*vga_hw_invalidate_ptr)(void *);
typedef void (*vga_hw_screen_dump_ptr)(void *, const char *);
typedef void (*vga_hw_text_update_ptr)(void *, console_ch_t *);
DisplayState *graphic_console_init(vga_hw_update_ptr update,
vga_hw_invalidate_ptr invalidate,
vga_hw_screen_dump_ptr screen_dump,
vga_hw_text_update_ptr text_update,
void *opaque);
The update/invalidate/screen_dump/text_update functions must be provided
by the hardware framebuffer emulation, and will be called under various
circumstances:
'update' is called periodically to check for any hw framebuffer
updates (and then copy them to the DisplayState, to finally send
them through dpy_update() to the listeners).
'invalidate' is called to indicate that the next call to 'update'
should send the content of _all_ the framebuffer, instead of only
the smallest possible update.
'screen_dump' is called to force a screen dump (i.e. print the
content of the framebuffer to a ppm file, which name is passed as
a parameter).
'text_update' is called to display one single character. XXX: Code is
not very clear, but probably related to text console.
TEXT CONSOLES:
--------------
A "Text console" attaches to an existing DisplayState, and is able to
take over its rendering in order to display a text *terminal*. It's not
sure whether this emulates VT101 or something else (see the code inside
the console_putchar() for all the gory details), but the main idea is
that you create a console with a call to:
CharDriverState* text_console_init(const char* p);
The function returns a CharDriverState* (see docs/CHAR-DEVICES.TXT) that
will be connected to a host device identified by the string in 'p'. This
allows you, for example, to connect the console to stdio.
The text console code is capable of producing a bitmap each time you update
its content (i.e. it includes code to manage fixed-size font rendering,
scrolling, escape sequences, color, blinking cursor, etc...).
- By default, the graphics console writes to its DisplayState, but you can
use console_select() to change that at runtime. This function can be used
to force switching between virtual terminals and the graphics display.
There can be several text consoles associated to a single DisplayState
object.
DISPLAY CHANGE LISTENERES:
==========================
There QEMU sources provide the implementation for various
DisplayChangeListeners, most notables are the following:
- In sdl.c: This one uses the SDL library to display the content of a
DisplaySurface through a SDL_Window. The implementation also supports
zooming the output to an arbitrary size (using SDL functions).
- In vnc.c: This listener implements a VNC Server that can be used to
display the DisplaySurface remotely through the RDP protocol.
- In curses.c: This listener is used to display text consoles through the
"curses" library on Unix systems. It cannot be used to display any
graphics though.
NOTE: The initialization sequence in vl.c only allows for a single listener
on the main display state, but the rest of the code deals with several
listeners per DisplayState just fine.
Each DisplayChangeListener can specify a refresh period (e.g. every 1/60th
of second). QEMU will then create a timer that will be programmed to called
the listener's 'dpy_refresh' callback periodically. The point of this
callback is to perform the following:
- poll for new user input events from the underlying UI (e.g. from the SDL
event loop, or from the network for VNC). These should be translated into
guest event codes with functions like 'kbd_put_keycode' or 'kbd_mouse_event'.
- call the global vga_hw_update() function. It will, if the graphics console
is being displayed, call the 'update' callback that was passed to
graphic_console_init(). If a text console is being displayed, the does
nothing.
- eventually call the global vga_hw_invalidate() to indicate that the whole
framebuffer content should be resent as an update. This can happen when a
UI window was minimized and is made visible again, for example.
INITIALIZATION AND RUNTIME EXECUTION:
=====================================
Initialization happens in the qemu main() function in the vl.c source file.
First, the hardware machine is initialized. The hardware fraembuffer emulation
shall call graphic_console_init() to create a new DisplayState. Note that the
object returned by this function has a default DisplaySurface of 640x480 pixels
allocated through malloc(). In other words, the hardware emulation does not
set the size of the display state by default!
After that, the listener's initialization function (e.g. sdl_display_init)
is called. It is passed the DisplayState object and can replace the
corresponding DisplaySurface with another one with proper dimensions, and
eventually created with a different DisplayAllocator. It also registers a
DisplayChangeListener to receive later state changes.
Note that the VNC listener doesn't change the dimension of the DisplayState
surface it is initialized with. However, it will react to dpy_resize events
accordingly.
NOTE: dpy_resize()s are currently only generated when switching between
consoles, or when the framebuffer's size is modified by the guest kernel.
The GUI timer, corresponding to the first listener than has one refresh
period, drives the whole update process (if no listener provides a refresh
period, a default 'no_graphic' timer is setup with a default refresh period
of 30 frame/s).
Things happen in this order:
- the GUI timer kicks in, and calls the 'dpy_refresh()' callback of
the listener (each listener has its own timer, btw).
- the listener callback polls for user events, and calls vga_hw_update()
to see if there are hardware framebuffer updates.
- vga_hw_update() checks that the graphics console is displayed (otherwise
it exits)
- it then calls the graphics console's 'update' callback
- the callback, implemented by the framebuffer hw emulation, checks for
dirty pages in order to detect what changed since it was invoked.
For every rectangle of the hw framebuffer that was modified, it copies
the pixels from VRAM into the DisplayState's surface buffer (eventually
performing format conversion at the same time).
After that, it calls dpy_update() to send the update to all registered
listeners for the DisplayState.
- The listener's 'dpy_update' callback is called and receives a pointer
to the DisplayState, and the rectangle corresponding to the update. Its
implementation can then update the content of the screen (or the internal
VNC framebuffer).
Eventually, hardware emulation can also trigger other dpy_xxxx events (e.g.
dpy_resize, dpy_copy, dpy_fill....)
Here's a simplified diagram of what happens in the typical case:
_____________
| |
| hardware |
| framebuffer |-------+
| | |
|_____________| |
^ |
| |
| 3/ ds.update() | 4/ dpy_update(ds,x,y,w,h)
| |
| |
_____________ |
| | |
| Display | <-----+
| State |
| | ----------+
|_____________| |
^ |
| |
| 2/ vga_hw_update() |
| |
| |
| |
| +---------------+
| | |
| | 5/listener.dpy_update(ds,x,y,w,h)
| | |
| | | 6/listener.dpy_update(...)
| | |
| v v
_____________ _____________
| | | |
| SDL | | VNC |
| Listener | | Listener |
| | | |
|_____________| |_____________|
^
|
| 1/ listener.dpy_refresh()
|
GUI timer