Bochs VBE Extensions

This page is a work in progress.

This page may thus be incomplete. Its content may be changed in the near future.

The Bochs VGA BIOS supports, to an extend, the VBE specification. Since Bochs only emulates a VGA card down to the hardware level (and a Cirrus graphics card if you enable it, but that is not tied in with the Bochs VBE extensions), it emulates very simple graphics hardware that the VBE BIOS can drive. The advantage of this is that if you are running your OS in Bochs (or Qemu, which uses the Bochs VGA BIOS), you can use this emulated hardware to directly set video modes, without using VBE (which would require real mode or v86).

Overview

The Bochs emulated graphics hardware (henceforth called BGA for Bochs Graphics Adaptor) is accessed via two 16-bit IO-ports. The first one is an index port, the second one a data port (comparable to how the VGA handles its sets of registers). Via these ports it is possible to enable or disable the VBE extensions, change the screen resolution and bit depth, and manage a larger virtual screen. There are five versions of the BGA, but if you use the latest version of Bochs you only need to concern yourself with the latest one.

The Bochs sources define in vga.h, located in the subdirectory iodev/, a number of defines that are useful for programming the BGA. The names of these defines all start with VBE_DISPI. They are used in the sections below, with their numerical value between parentheses.

Programming the BGA

Writing values

To write an index/data pair to the BGA, first write the index value to the 16-bit IO-port VBE_DISPI_IOPORT_INDEX (0x01CE), followed by writing the data value to the 16-bit IO-port VBE_DISPI_IOPORT_DATA (0x01CF). The BGA supports 10 different index values (0 through 9):

• VBE_DISPI_INDEX_ID (0)
• VBE_DISPI_INDEX_XRES (1)
• VBE_DISPI_INDEX_YRES (2)
• VBE_DISPI_INDEX_BPP (3)
• VBE_DISPI_INDEX_ENABLE (4)
• VBE_DISPI_INDEX_BANK (5)
• VBE_DISPI_INDEX_VIRT_WIDTH (6)
• VBE_DISPI_INDEX_VIRT_HEIGHT (7)
• VBE_DISPI_INDEX_X_OFFSET (8)
• VBE_DISPI_INDEX_Y_OFFSET (9)

In order to change any of the registers (with the logical exception of VBE_DISPI_INDEX_ENABLE), the VBE extensions must be disabled first. To do so, write the value VBE_DISPI_DISABLED (0x00) to VBE_DISPI_INDEX_ENABLE (4). The changes are not visible until the VBE extensions are enabled again. To do so, write the value VBE_DISPI_ENABLED (0x01) to the same register (see also note below on enabling the LFB).

[TODO: check whether we can read registers as well, and describe]

Setting display resolution and bit depth

Most likely, setting the display resolution and bit depth is all you need. To do so, disable the VBE extensions (see above), write the X resolution, Y resolution and BPP to their respective registers (VBE_DISPI_INDEX_XRES (1), VBE_DISPI_INDEX_YRES (2) and VBE_DISPI_INDEX_BPP (3)) and enable the VBE extensions. Since the BGA is not real hardware, X and Y resolutions can be set at will [TODO: check whether Bochs does a sanity check and describe]. The bit depth needs to be one of the following:

• VBE_DISPI_BPP_4 (0x04)
• VBE_DISPI_BPP_8 (0x08)
• VBE_DISPI_BPP_15 (0x0F)
• VBE_DISPI_BPP_16 (0x10)
• VBE_DISPI_BPP_24 (0x18)
• VBE_DISPI_BPP_32 (0x20)

For 24 BPP, the order of the colour components is blue first, then green, then red. [TODO: check for other BPP and describe]

[TODO: some example code]

Using banked mode

When using banked mode, the BGA uses a 64Kb bank size (VBE_DISPI_BANK_SIZE_KB) starting at address 0xA0000 (VBE_DISPI_BANK_ADDRESS). Banked mode is the default mode, so when enabling the VBE extensions without explicitly telling the BGA to use a linear frame buffer, the BGA enables banked mode. To set the bank to use, write the bank number to the bank register (VBE_DISPI_INDEX_BANK (5)). [TODO: check whether Bochs does a sanity check, or wrap-around, or whatever and describe]