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 hwo 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:
  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
  34
  35 History
  36 -------
  37   Version 0.6     (UNRELEASED)  Jeroen Janssen
  38                   - Added LFB support
  39                   - Added Virt width, height and x,y offset
  40
  41   Version 0.5     2002 March 08   Jeroen Janssen
  42                   - Added documentation about panic behaviour / current limits of the data values.
  43                   - Changed BPP API (in order to include future (A)RGB formats)
  44                   - Initial version (based upon extended display text of the vbe bochs display patch)
  45
  46
  47 Todo
  48 ----
  49   Version 0.6     - add virtual width, height, x offset, y offset in bios & bochs
  50                     (for set/get logical scan line length andset/get display start)
  51
  52   Version 0.6+    [random order]
  53                   - Add lots of different (A)RGB formats
  54
  55 References
  56 ----------
  57   [VBE3]          VBE 3 Specification at
  58                   http://www.vesa.org/vbe3.pdf
  59
  60   [BOCHS]         Bochs Open Source IA-32 Emulator at
  61                   http://bochs.sourceforge.net
  62
  63   [VBEBIOS]       VBE Bios for Bochs at
  64                   http://savannah.gnu.org/projects/vgabios/
  65
  66   [Screenshots]   Screenshots of programs using the VBE Bios at
  67                   http://japj.org/projects/bochs_plex86/screenshots.html
  68
  69 Abbreviations
  70 -------------
  71   VBE             Vesa Bios Extension
  72   DISPI           (Bochs) Display Interface
  73   BPP             Bits Per Pixel
  74   LFB             Linear Frame Buffer
  75
  76
  77 #defines
  78 --------
  79   #define VBE_DISPI_TOTAL_VIDEO_MEMORY_MB 4
  80   #define VBE_DISPI_BANK_ADDRESS          0xA0000
  81   #define VBE_DISPI_BANK_SIZE_KB          64
  82
  83   #define VBE_DISPI_MAX_XRES              1024
  84   #define VBE_DISPI_MAX_YRES              768
  85
  86   #define VBE_DISPI_IOPORT_INDEX          0xFF80
  87   #define VBE_DISPI_IOPORT_DATA           0xFF81
  88
  89   #define VBE_DISPI_INDEX_ID              0x0
  90   #define VBE_DISPI_INDEX_XRES            0x1
  91   #define VBE_DISPI_INDEX_YRES            0x2
  92   #define VBE_DISPI_INDEX_BPP             0x3
  93   #define VBE_DISPI_INDEX_ENABLE          0x4
  94   #define VBE_DISPI_INDEX_BANK            0x5
  95   #define VBE_DISPI_INDEX_VIRT_WIDTH      0x6
  96   #define VBE_DISPI_INDEX_VIRT_HEIGHT     0x7
  97   #define VBE_DISPI_INDEX_X_OFFSET        0x8
  98   #define VBE_DISPI_INDEX_Y_OFFSET        0x9
  99
 100   #define VBE_DISPI_ID0                   0xB0C0
 101   #define VBE_DISPI_ID1                   0xB0C1
 102
 103   #define VBE_DISPI_BPP_8                 0x0
 104 // The following is not support yet, but just for reference available.
 105 //  #define VBE_DISPI_BPP_RGB565            0x1
 106 //  #define VBE_DISPI_BPP_RGB555            0x2
 107
 108   #define VBE_DISPI_DISABLED              0x00
 109   #define VBE_DISPI_ENABLED               0x01
 110
 111   #define VBE_DISPI_LFB_PHYSICAL_ADDRESS  0xE0000000
 112
 113 API
 114 ---
 115   The display api works by using a index (VBE_DISPI_IOPORT_INDEX) and
 116   data (VBE_DISPI_IOPORT_DATA) ioport. One writes the index of the parameter to the index port.
 117   Next, the parameter value can be read or written.
 118
 119 [0xb0c0]
 120   * VBE_DISPI_INDEX_ID  : WORD {R,W}
 121     This parameter can be used to detect the current display API (both bochs & vbebios).
 122     The bios writes VBE_DISPI_ID0 to the dataport and reads it back again.
 123     This way, the display code knows the vbebios 'ID' and the vbebios can check if the correct
 124     display code is present.
 125     As a result, a PANIC can be generated if an incompatible vbebios/display code combination is detected.
 126     This panic can be generated from the bochs display code (NOT the bios, see Notes).
 127
 128     Example values: VBE_DISPI_ID0
 129
 130   * VBE_DISPI_INDEX_XRES : WORD {R,W}
 131     This parameter can be used to read/write the vbe display X resolution (in pixels).
 132     It's illegal to set the XRES when the VBE is enabled (display code should generate PANIC).
 133
 134     If the value written exceeds VBE_DISPI_MAX_XRES, the display code needs to generate a PANIC.
 135
 136     Example values:   320,640,800,1024
 137
 138   * VBE_DISPI_INDEX_YRES : WORD {R,W}
 139     This parameter can be used to read/write the vbe display Y resolution (in pixels).
 140     It's illegal to set the YRES when the VBE is enabled (display code should generate PANIC).
 141
 142     If the value written exceeds VBE_DISPI_MAX_YRES, the display code needs to generate a PANIC.
 143
 144     Example values:   200,400,480,600,768
 145
 146   * VBE_DISPI_INDEX_BPP : WORD {R,W}
 147     This parameter can be used to read/write the vbe display BPP.
 148     It's illegal to set the BPP when the VBE is enabled (display code should generate PANIC).
 149
 150     If the value written is an incompatible BPP, the display code needs to generate a PANIC.
 151
 152     Example values:   VBE_DISPI_BPP_8
 153
 154   * VBE_DISPI_INDEX_ENABLE : WORD {R,W}
 155     This parameter can be used to read/write the vbe ENABLED state.
 156     If the bios writes VBE_DISPI_ENABLED then the display code will setup a hostside display mode
 157     with the current XRES, YRES and BPP settings.
 158     If the bios write VBE_DISPI_DISABLED then the display code will switch back to normal vga mode behaviour.
 159
 160     Example values: VBE_DISPI_ENABLED, VBE_DISPI_DISABLED
 161
 162   * VBE_DISPI_INDEX_BANK : WORD {R,W}
 163     This parameter can be used to read/write the current selected BANK (at 0xA0000).
 164     This can be used for switching banks in banked mode.
 165
 166 [0xb0c1]
 167   * VBE_DISPI_INDEX_VIRT_WIDTH : WORD {R,W}
 168     This parameter can be used to read/write the current virtual width.
 169     Upon enabling a mode, this will be set to the current xres
 170     Setting this field during enabled mode will result in the virtual width to be changed.
 171     Value will be adjusted if current setting is not possible.
 172
 173   * VBE_DISPI_INDEX_VIRT_HEIGHT : WORD {R}
 174     This parameter can be read in order to obtain the current virtual height.
 175     This setting will be adjusted after setting a virtual width in order to stay within limit of video memory.
 176
 177   * VBE_DISPI_INDEX_X_OFFSET : WORD {R,W}
 178     The current X offset (in pixels!) of the visible screen part.
 179     Writing a new offset will also result in a complete screen refresh.
 180
 181   * VBE_DISPI_INDEX_Y_OFFSET : WORD {R,W}
 182     The current Y offset (in pixels!) of the visible screen part.
 183     Writing a new offset will also result in a complete screen refresh.
 184
 185
 186 Displaying GFX
 187 --------------
 188   Currently Linear Frame Buffer support is not available yet.
 189   The only other way of displaying (VBE) graphics is using banked modi.
 190
 191   What happens is that the total screen is devided in banks of 'VBE_DISPI_BANK_SIZE_KB' KiloByte in size.
 192   If you want to set a pixel you can calculate its bank by doing:
 193
 194     offset = pixel_x + pixel_y * resolution_x;
 195     bank = offset / 64 Kb (rounded 1.9999 -> 1)
 196
 197     bank_pixel_pos = offset - bank * 64Kb
 198
 199   Now you can set the current bank and put the pixel at VBE_DISPI_BANK_ADDRESS + bank_pixel_pos
 200
 201
 202 Notes
 203 -----
 204   * Since the XRES/YRES/BPP may not be written when VBE is enabled, if you want to switch from one VBE mode
 205     to another, you will need to disable VBE first.
 206
 207   * Note when the bios doesn't find a valid DISPI_ID, it can disable the VBE functions. This allows people to
 208     use the same bios for both vbe enabled and disabled bochs executables.