vgabios/vbe_display_api.txt

   1 VBE Display API
   2 -------------------------------------------------------------------------------------------------------------
   3   This document is part of the Bochs/VBEBios documentation,
   4   it specifies the bochs host <-> vbebios client communication.
   5
   6   That means, the display code implementation and the vbebios code depend
   7   very heavily on each other. As such, this documents needs be synchronised
   8   between bochs CVS and the vgabios CVS.
   9
  10   This document does not describe how the VBEBios implements the VBE2/3 spec.
  11   This document does not describe how the Bochs display code will display gfx based upon this spec.
  12
  13
  14 API History
  15 -----------
  16 0xb0c0            supports the following VBE_DISPI_ interfaces (present in Bochs 1.4):
  17                   VBE_DISPI_INDEX_ID
  18                   VBE_DISPI_INDEX_XRES
  19                   VBE_DISPI_INDEX_YRES
  20                   VBE_DISPI_INDEX_BPP
  21                   VBE_DISPI_INDEX_ENABLE
  22                   VBE_DISPI_INDEX_BANK
  23
  24                   Bpp format supported is:
  25                   VBE_DISPI_BPP_8
  26
  27 0xb0c1            supports 0xb0c0 VBE_DISPI_ interfaces, additional interfaces (present in Bochs 2.0):
  28                   VBE_DISPI_INDEX_VIRT_WIDTH
  29                   VBE_DISPI_INDEX_VIRT_HEIGHT
  30                   VBE_DISPI_INDEX_X_OFFSET
  31                   VBE_DISPI_INDEX_Y_OFFSET
  32
  33 0xb0c2            supports 0xb0c1 VBE_DISPI_ interfaces, interfaces updated for
  34                   additional features (present in Bochs 2.1):
  35                   VBE_DISPI_INDEX_BPP supports >8bpp color depth (value = bits)
  36                   VBE_DISPI_INDEX_ENABLE supports new flags VBE_DISPI_NOCLEARMEM and VBE_DISPI_LFB_ENABLED
  37                   VBE i/o registers changed from 0xFF80/81 to 0x01CE/CF
  38
  39 0xb0c3            supports 0xb0c2 VBE_DISPI_ interfaces, interfaces updated for
  40                   additional features:
  41                   VBE_DISPI_INDEX_ENABLE supports new flags VBE_DISPI_GETCAPS and VBE_DISPI_8BIT_DAC
  42
  43 0xb0c4            VBE video memory increased to 8 MB
  44
  45
  46 History
  47 -------
  48   Version 0.6     2002 Nov 23  Jeroen Janssen
  49                   - Added LFB support
  50                   - Added Virt width, height and x,y offset
  51
  52   Version 0.5     2002 March 08   Jeroen Janssen
  53                   - Added documentation about panic behaviour / current limits of the data values.
  54                   - Changed BPP API (in order to include future (A)RGB formats)
  55                   - Initial version (based upon extended display text of the vbe bochs display patch)
  56
  57
  58 Todo
  59 ----
  60   Version 0.6+    [random order]
  61                   - Add lots of different (A)RGB formats
  62
  63 References
  64 ----------
  65   [VBE3]          VBE 3 Specification at
  66                   http://www.vesa.org/vbe3.pdf
  67
  68   [BOCHS]         Bochs Open Source IA-32 Emulator at
  69                   http://bochs.sourceforge.net
  70
  71   [VBEBIOS]       VBE Bios for Bochs at
  72                   http://savannah.gnu.org/projects/vgabios/
  73
  74   [Screenshots]   Screenshots of programs using the VBE Bios at
  75                   http://japj.org/projects/bochs_plex86/screenshots.html
  76
  77 Abbreviations
  78 -------------
  79   VBE             Vesa Bios Extension
  80   DISPI           (Bochs) Display Interface
  81   BPP             Bits Per Pixel
  82   LFB             Linear Frame Buffer
  83
  84
  85 #defines
  86 --------
  87 vbetables-gen.c
  88   #define VBE_DISPI_TOTAL_VIDEO_MEMORY_MB 8
  89
  90 vbe.h
  91   #define VBE_DISPI_BANK_ADDRESS          0xA0000
  92   #define VBE_DISPI_BANK_SIZE_KB          64
  93
  94   #define VBE_DISPI_MAX_XRES              1024
  95   #define VBE_DISPI_MAX_YRES              768
  96
  97   #define VBE_DISPI_IOPORT_INDEX          0x01CE
  98   #define VBE_DISPI_IOPORT_DATA           0x01CF
  99
 100   #define VBE_DISPI_INDEX_ID              0x0
 101   #define VBE_DISPI_INDEX_XRES            0x1
 102   #define VBE_DISPI_INDEX_YRES            0x2
 103   #define VBE_DISPI_INDEX_BPP             0x3
 104   #define VBE_DISPI_INDEX_ENABLE          0x4
 105   #define VBE_DISPI_INDEX_BANK            0x5
 106   #define VBE_DISPI_INDEX_VIRT_WIDTH      0x6
 107   #define VBE_DISPI_INDEX_VIRT_HEIGHT     0x7
 108   #define VBE_DISPI_INDEX_X_OFFSET        0x8
 109   #define VBE_DISPI_INDEX_Y_OFFSET        0x9
 110
 111   #define VBE_DISPI_ID0                   0xB0C0
 112   #define VBE_DISPI_ID1                   0xB0C1
 113   #define VBE_DISPI_ID2                   0xB0C2
 114   #define VBE_DISPI_ID3                   0xB0C3
 115   #define VBE_DISPI_ID4                   0xB0C4
 116
 117   #define VBE_DISPI_DISABLED              0x00
 118   #define VBE_DISPI_ENABLED               0x01
 119   #define VBE_DISPI_VBE_ENABLED           0x40
 120   #define VBE_DISPI_NOCLEARMEM            0x80
 121
 122   #define VBE_DISPI_LFB_PHYSICAL_ADDRESS  0xE0000000
 123
 124 API
 125 ---
 126   The display api works by using a index (VBE_DISPI_IOPORT_INDEX) and
 127   data (VBE_DISPI_IOPORT_DATA) ioport. One writes the index of the parameter to the index port.
 128   Next, the parameter value can be read or written.
 129
 130 [0xb0c0]
 131   * VBE_DISPI_INDEX_ID  : WORD {R,W}
 132     This parameter can be used to detect the current display API (both bochs & vbebios).
 133     The bios writes VBE_DISPI_ID0 to the dataport and reads it back again.
 134     This way, the display code knows the vbebios 'ID' and the vbebios can check if the correct
 135     display code is present.
 136     As a result, a PANIC can be generated if an incompatible vbebios/display code combination is detected.
 137     This panic can be generated from the bochs display code (NOT the bios, see Notes).
 138
 139     Example values: VBE_DISPI_ID0
 140
 141   * VBE_DISPI_INDEX_XRES : WORD {R,W}
 142     This parameter can be used to read/write the vbe display X resolution (in pixels).
 143     It's illegal to set the XRES when the VBE is enabled (display code should generate PANIC).
 144
 145     If the value written exceeds VBE_DISPI_MAX_XRES, the display code needs to generate a PANIC.
 146
 147     Example values:   320,640,800,1024
 148
 149   * VBE_DISPI_INDEX_YRES : WORD {R,W}
 150     This parameter can be used to read/write the vbe display Y resolution (in pixels).
 151     It's illegal to set the YRES when the VBE is enabled (display code should generate PANIC).
 152
 153     If the value written exceeds VBE_DISPI_MAX_YRES, the display code needs to generate a PANIC.
 154
 155     Example values:   200,400,480,600,768
 156
 157   * VBE_DISPI_INDEX_BPP : WORD {R,W}
 158     This parameter can be used to read/write the vbe display BPP.
 159     It's illegal to set the BPP when the VBE is enabled (display code should generate PANIC).
 160
 161     If the value written is an incompatible BPP, the display code needs to generate a PANIC.
 162
 163     Example values:   VBE_DISPI_BPP_8
 164
 165   * VBE_DISPI_INDEX_ENABLE : WORD {R,W}
 166     This parameter can be used to read/write the vbe ENABLED state.
 167     If the bios writes VBE_DISPI_ENABLED then the display code will setup a hostside display mode
 168     with the current XRES, YRES and BPP settings.
 169     If the bios write VBE_DISPI_DISABLED then the display code will switch back to normal vga mode behaviour.
 170
 171     Example values: VBE_DISPI_ENABLED, VBE_DISPI_DISABLED
 172
 173   * VBE_DISPI_INDEX_BANK : WORD {R,W}
 174     This parameter can be used to read/write the current selected BANK (at 0xA0000).
 175     This can be used for switching banks in banked mode.
 176
 177 [0xb0c1]
 178   * VBE_DISPI_INDEX_VIRT_WIDTH : WORD {R,W}
 179     This parameter can be used to read/write the current virtual width.
 180     Upon enabling a mode, this will be set to the current xres
 181     Setting this field during enabled mode will result in the virtual width to be changed.
 182     Value will be adjusted if current setting is not possible.
 183
 184   * VBE_DISPI_INDEX_VIRT_HEIGHT : WORD {R}
 185     This parameter can be read in order to obtain the current virtual height.
 186     This setting will be adjusted after setting a virtual width in order to stay within limit of video memory.
 187
 188   * VBE_DISPI_INDEX_X_OFFSET : WORD {R,W}
 189     The current X offset (in pixels!) of the visible screen part.
 190     Writing a new offset will also result in a complete screen refresh.
 191
 192   * VBE_DISPI_INDEX_Y_OFFSET : WORD {R,W}
 193     The current Y offset (in pixels!) of the visible screen part.
 194     Writing a new offset will also result in a complete screen refresh.
 195
 196
 197 [0xb0c2]
 198   * VBE_DISPI_INDEX_BPP : WORD {R,W}
 199     The value written is now the number of bits per pixel. A value of 0 is treated
 200     the same as 8 for backward compatibilty. These values are supported: 8, 15,
 201     16, 24 and 32. The value of 4 is not yet handled in the VBE code.
 202   * VBE_DISPI_INDEX_ENABLE : WORD {R,W}
 203     The new flag VBE_DISPI_NOCLEARMEM allows to preserve the VBE video memory.
 204     The new flag VBE_DISPI_LFB_ENABLED indicates the usage of the LFB.
 205
 206 [0xb0c3]
 207   * VBE_DISPI_INDEX_ENABLE : WORD {R,W}
 208     If the new flag VBE_DISPI_GETCAPS is enabled, the xres, yres and bpp registers
 209     return the gui capabilities.
 210     The new flag VBE_DISPI_8BIT_DAC switches the DAC to 8 bit mode.
 211
 212 [0xb0c4]
 213   * VBE_DISPI_TOTAL_VIDEO_MEMORY_MB set to 8 (moved to auto-generated vbetables.h)
 214
 215 Displaying GFX (banked mode)
 216 --------------
 217   What happens is that the total screen is devided in banks of 'VBE_DISPI_BANK_SIZE_KB' KiloByte in size.
 218   If you want to set a pixel you can calculate its bank by doing:
 219
 220     offset = pixel_x + pixel_y * resolution_x;
 221     bank = offset / 64 Kb (rounded 1.9999 -> 1)
 222
 223     bank_pixel_pos = offset - bank * 64Kb
 224
 225   Now you can set the current bank and put the pixel at VBE_DISPI_BANK_ADDRESS + bank_pixel_pos
 226
 227 Displaying GFX (linear frame buffer mode)
 228 --------------
 229   NOT WRITTEN YET
 230
 231 Notes
 232 -----
 233   * Since the XRES/YRES/BPP may not be written when VBE is enabled, if you want to switch from one VBE mode
 234     to another, you will need to disable VBE first.
 235
 236   * Note when the bios doesn't find a valid DISPI_ID, it can disable the VBE functions. This allows people to
 237     use the same bios for both vbe enabled and disabled bochs executables.