1VBE 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 14API History 15----------- 160xb0c0 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 270xb0c1 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 330xb0c2 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 390xb0c3 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 430xb0c4 VBE video memory increased to 8 MB 44 45 46History 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 58Todo 59---- 60 Version 0.6+ [random order] 61 - Add lots of different (A)RGB formats 62 63References 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 77Abbreviations 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-------- 87vbetables-gen.c 88 #define VBE_DISPI_TOTAL_VIDEO_MEMORY_MB 8 89 90vbe.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 124API 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 215Displaying 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 227Displaying GFX (linear frame buffer mode) 228-------------- 229 NOT WRITTEN YET 230 231Notes 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. 238