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