- adding vbe_display_api documentation

2 files changed, 141 insertions, 0 deletions

diff --git a/ChangeLog b/ChangeLog
index cae9896..b0dbec6 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,6 @@
 
 vgabios-0.3a (Not released yet!!)
+    . added vbe_display_api documentation
     . added 640x400x8, 640x480x8, 800x600x8, 1024x768 (>640x480 needs a special bochs patch atm)
     . added 320x200x8 vbe support (uses the standard 320x200x8 vga mode to
       display, this allows for testing & having something on screen as well,
diff --git a/vbe_display_api.txt b/vbe_display_api.txt
new file mode 100644
index 0000000..94adcce
--- /dev/null
+++ b/vbe_display_api.txt
@@ -0,0 +1,140 @@
+VBE Display API
+-------------------------------------------------------------------------------------------------------------
+  This document is part of the Bochs/VBEBios documentation,
+  it specifies the bochs host <-> vbebios client communication.
+  
+  That means, the display code implementation and the vbebios code depend
+  very heavily on each other. As such, this documents needs be synchronised 
+  between bochs CVS and the vgabios CVS.
+  
+  This document does not describe hwo the VBEBios implements the VBE2/3 spec.
+  This document does not describe how the Bochs display code will display gfx based upon this spec.
+  
+
+History
+-------
+  Version 0.5     2002 March 08   Jeroen Janssen
+                  - Added documentation about panic behaviour / current limits of the data values.
+                  - Changed BPP API (in order to include future (A)RGB formats)
+                  - Initial version (based upon extended display text of the vbe bochs display patch)
+
+
+Todo
+----
+  Version 0.5     - Update the VBEBios with the new API in this spec
+                  - Update the Bochs display patch with the new API in this spec + add this document.
+  
+  Version 0.5+    [random order]
+                  - Add lots of different (A)RGB formats
+                  - Add Linear Frame Buffer API
+
+  
+References
+----------
+  [VBE3]          VBE 3 Specification at 
+                  http://www.vesa.org/vbe3.pdf
+                  
+  [BOCHS]         Bochs Open Source IA-32 Emulator at 
+                  http://bochs.sourceforge.net
+                  
+  [VBEBIOS]       VBE Bios for Bochs at 
+                  http://savannah.gnu.org/projects/vgabios/
+                  
+  [Screenshots]   Screenshots of programs using the VBE Bios at 
+                  http://japj.org/projects/bochs_plex86/screenshots.html
+
+Abbreviations
+-------------
+  VBE             Vesa Bios Extension
+  DISPI           (Bochs) Display Interface
+  BPP             Bits Per Pixel
+  LFB             Linear Frame Buffer
+
+
+#defines
+--------
+  #define VBE_DISPI_BANK_ADDRESS          0xA0000
+  #define VBE_DISPI_BANK_SIZE_KB          64
+  
+  #define VBE_DISPI_MAX_XRES              1024
+  #define VBE_DISPI_MAX_YRES              768
+  
+  #define VBE_DISPI_IOPORT_INDEX          0xFF80
+  #define VBE_DISPI_IOPORT_DATA           0xFF81
+  
+  #define VBE_DISPI_INDEX_ID              0x0
+  #define VBE_DISPI_INDEX_XRES            0x1
+  #define VBE_DISPI_INDEX_YRES            0x2
+  #define VBE_DISPI_INDEX_BPP             0x3
+  #define VBE_DISPI_INDEX_ENABLE          0x4
+  #define VBE_DISPI_INDEX_BANK            0x5
+  
+  #define VBE_DISPI_ID0                   0xB0C0
+  
+  #define VBE_DISPI_BPP_8                 0x0
+// The following is not support yet, but just for reference available.  
+//  #define VBE_DISPI_BPP_RGB565            0x1
+//  #define VBE_DISPI_BPP_RGB555            0x2
+
+  #define VBE_DISPI_DISABLED              0x00
+  #define VBE_DISPI_ENABLED               0x01
+
+
+API
+---
+  The display api works by using a index (VBE_DISPI_IOPORT_INDEX) and 
+  data (VBE_DISPI_IOPORT_DATA) ioport. One writes the index of the parameter to the index port.
+  Next, the parameter value can be read or written.
+  
+  * VBE_DISPI_INDEX_ID  : WORD
+    This parameter can be used to detect the current display API (both bochs & vbebios).
+    The bios writes VBE_DISPI_ID0 to the dataport and reads it back again.
+    This way, the display code knows the vbebios 'ID' and the vbebios can check if the correct
+    display code is present.
+    As a result, a PANIC can be generated if an incompatible vbebios/display code combination is detected.
+    This panic can be generated from both the display code and the bios.
+    
+    Example values: VBE_DISPI_ID0
+        
+  * VBE_DISPI_INDEX_XRES : WORD
+    This parameter can be used to read/write the vbe display X resolution (in pixels).
+    It's illegal to set the XRES when the VBE is enabled (display code should generate PANIC).
+    
+    If the value written exceeds VBE_DISPI_MAX_XRES, the display code needs to generate a PANIC.
+    
+    Example values:   320,640,800,1024
+
+  * VBE_DISPI_INDEX_YRES : WORD
+    This parameter can be used to read/write the vbe display Y resolution (in pixels).
+    It's illegal to set the YRES when the VBE is enabled (display code should generate PANIC).
+    
+    If the value written exceeds VBE_DISPI_MAX_YRES, the display code needs to generate a PANIC.
+    
+    Example values:   200,400,480,600,768
+  
+  * VBE_DISPI_INDEX_BPP : WORD
+    This parameter can be used to read/write the vbe display BPP.
+    It's illegal to set the BPP when the VBE is enabled (display code should generate PANIC).
+    
+    If the value written is an incompatible BPP, the display code needs to generate a PANIC.
+    
+    Example values:   VBE_DISPI_BPP_8
+    
+  * VBE_DISPI_INDEX_ENABLE : WORD
+    This parameter can be used to read/write the vbe ENABLED state.
+    If the bios writes VBE_DISPI_ENABLED then the display code will setup a hostside display mode 
+    with the current XRES, YRES and BPP settings.
+    If the bios write VBE_DISPI_DISABLED then the display code will switch back to normal vga mode behaviour.
+    
+    Example values: VBE_DISPI_ENABLED, VBE_DISPI_DISABLED
+  
+  * VBE_DISPI_INDEX_BANK : WORD
+    This parameter can be used to read/write the current selected BANK (at 0xA0000).
+    This can be used for switching banks in banked mode.
+    
+Notes
+-----
+  * Currently only Banked modi are 'officially' supported (although 320x200x8 LFB is available in the bios atm).
+   
+  * Since the XRES/YRES/BPP may not be written when VBE is enabled, if you want to switch from one VBE mode
+    to another, you will need to disable VBE first.