412 lines
19 KiB
HTML
412 lines
19 KiB
HTML
<html>
|
|
<head>
|
|
<title>FreeBE/AF - the free VBE/AF driver project</title>
|
|
<body>
|
|
<pre>
|
|
<p>
|
|
______ ____ ______ _____ ______
|
|
| ____| | _ \| ____| / / _ \| ____|
|
|
| |__ _ __ ___ ___| |_) | |__ / / |_| | |__
|
|
| __| '__/ _ \/ _ \ _ <| __| / /| _ | __|
|
|
| | | | | __/ __/ |_) | |____ / / | | | | |
|
|
|_| |_| \___|\___|____/|______/_/ |_| |_|_|
|
|
<p>
|
|
<br>
|
|
The free VBE/AF driver project, version 1.2
|
|
<p>
|
|
<a href="http://www.talula.demon.co.uk/freebe/">http://www.talula.demon.co.uk/freebe/</a>
|
|
<p>
|
|
<br>
|
|
"The nice thing about standards is that
|
|
there are so many of them to choose from."
|
|
</pre>
|
|
<p>
|
|
<br>
|
|
<br>
|
|
<h1><a name="Introduction">Introduction</a></h1>
|
|
<p>
|
|
VBE/AF is a low level driver interface for accessing graphics hardware.
|
|
It provides all the same features as VESA 3.0 (access to linear
|
|
framebuffer video memory, high speed protected mode bank switching, page
|
|
flipping, hardware scrolling, etc), and adds the ability to use 2D
|
|
hardware acceleration in an efficient and portable manner. An /AF driver
|
|
is provided as a disk file (vbeaf.drv), and contains clean 32 bit machine
|
|
code which can be called directly by a C program. If implemented
|
|
correctly, these drivers have the potential to be binary portable across
|
|
multiple operating systems, so the same driver file can be used from DOS,
|
|
Windows, Linux, etc.
|
|
<p>
|
|
FreeBE/AF is an attempt to implement free VBE/AF drivers on as many cards
|
|
as possible. This idea came about on the Allegro mailing list, due to the
|
|
need for a dynamically loadable driver structure that could support
|
|
hardware acceleration. VBE/AF seemed to fit the bill, and Allegro already
|
|
had support for the SciTech drivers, so it seemed like a good idea to
|
|
adopt this format for ourselves. The primary goal is to make these
|
|
drivers work with Allegro, so the emphasis will be on implementing the
|
|
functions that Allegro actually uses, but we encourage other developers
|
|
to join us in taking advantage of this excellent driver architecture.
|
|
<p>
|
|
This project currently provides fully accelerated drivers for a handful
|
|
of chipsets, plus a number of dumb framebuffer implementations based on
|
|
the video drivers from older versions of the Allegro library. It has also
|
|
defined a few extensions to the stock VBE/AF API, which allow Allegro
|
|
programs to use these drivers in a true protected mode environment
|
|
without having to resort to the nearptr hack, and provide a number of
|
|
hook functions that will be needed to remain compatible with future
|
|
generations of the SciTech drivers.
|
|
<p>
|
|
The current status of the VBE/AF standard is somewhat confused. It was
|
|
designed by SciTech Software (<a href="http://www.scitechsoft.com/">http://www.scitechsoft.com/</a>), who provide
|
|
commercial VBE/AF drivers for a wide range of cards as part of their
|
|
Display Doctor package. It was originally going to be released as a VESA
|
|
standard, but the VESA people seriously messed this up by charging
|
|
exorbitant sums of $$$ for copies of the spec. As a result, very few
|
|
people bothered to support these drivers, and the FreeBE/AF project was
|
|
only made possible by the information available in the SciTech MGL
|
|
library source code, and the helpfulness of Kendall Bennett (the designer
|
|
of the spec) himself. Unfortunately SciTech have now abandoned VBE/AF
|
|
themselves, replacing it with an equivalent but non-public API called
|
|
Nucleus, which is only available under NDA. SciTech will continue to
|
|
provide VBE/AF drivers for the cards which they already support, but
|
|
will not adding any new ones in the future, so this project is now the
|
|
only active source of VBE/AF driver implementations.
|
|
<p>
|
|
At present, the Allegro (<a href="http://www.talula.demon.co.uk/allegro/">http://www.talula.demon.co.uk/allegro/</a>) and MGL
|
|
(<a href="http://www.scitechsoft.com">http://www.scitechsoft.com</a>) libraries are the only major packages which
|
|
can take advantage of accelerated VBE/AF drivers. As such, this project
|
|
is starting to look more like a implementation of video drivers
|
|
specifically for the Allegro library, rather than a potential
|
|
industry-wide standard :-) But it doesn't have to be this way! VBE/AF is
|
|
technically an excellent design: efficient, easy to write and use, and
|
|
highly portable. If you are writing graphics code, and getting frustrated
|
|
by the many limitiations imposed by VESA, why not think about using
|
|
VBE/AF instead? Even better, if you have a card that our project doesn't
|
|
yet support, why not add a new driver for it? This can be a lot of fun,
|
|
and we would be delighted to offer any help or advice that you might need.
|
|
<p>
|
|
<br>
|
|
<br>
|
|
<h1><a name="Usage">Usage</a></h1>
|
|
<p>
|
|
Each driver is located in a different subdirectory. Run "make" to compile
|
|
them, choose the one you want, copy the vbeaf.drv file from this
|
|
directory to c:\, and you are ready to go!
|
|
<p>
|
|
The stub directory contains a generic non-accelerated VBE/AF driver. This
|
|
is not useful in any way, because it simply sits on top of your existing
|
|
VESA driver and emulates a few "hardware" drawing operations with very
|
|
slow software implementations. The stub is intended as a starting point
|
|
for people who want to make drivers for a specific card, and should not
|
|
be used directly.
|
|
<p>
|
|
To recompile FreeBE/AF, you need a working copy of djgpp. Run "make" to
|
|
build all the available drivers, or "make dir/vbeaf.drv" to compile a
|
|
specific driver (replacing {dir} with the directory name, eg. "make
|
|
stub/vbeaf.drv"). To build the install.exe program for a binary
|
|
distribution, run "make all" (this requires you to have the Allegro
|
|
library installed, and the allegro/tools/ directory in your path). This
|
|
documentation is converted from the custom ._tx format into ASCII and
|
|
HTML by the Allegro makedoc program: run "make docs" to do this, after
|
|
putting the makedoc utility somewhere in your path.
|
|
<p>
|
|
FreeBE/AF only supports the VBE/AF 2.0 API. It is not backward compatible
|
|
with the assembler VBE/AF 1.0 interface, and programs that try to use
|
|
those obsolete functions will not work correctly.
|
|
<p>
|
|
<br>
|
|
<br>
|
|
<h1><a name="Supported Hardware">Supported Hardware</a></h1>
|
|
<p>
|
|
Not all VBE/AF drivers provide the complete set of possible features.
|
|
Some may be written in a 100% clean and portable manner, allowing them to
|
|
be used on any platform, but others make use of the video BIOS in order
|
|
to set the initial video mode: this makes them a lot easier to write, but
|
|
means that it can only be used under DOS. Some of the drivers, in
|
|
particular the ones based on the old Allegro library chipset support,
|
|
don't support any hardware accelerated drawing at all: these are still
|
|
usefull because they provide high speed protected mode bank switching and
|
|
can work around the bugs in some manufacturer's VESA implementations, but
|
|
are obviously not nearly as cool as a fully accelerated driver.
|
|
<p>
|
|
This table lists the currently available FreeBE/AF drivers, and what
|
|
features they each provide:<br><br><br>
|
|
<p> <table border=3 cellborder=1 cellspacing=2 cellpadding=8>
|
|
<tr><td>ATI 18800/28800</td>
|
|
<td>Uses BIOS</td>
|
|
<td>Banked modes only</td>
|
|
<td>Supports farptr extension</td>
|
|
<td>Dumb framebuffer</td>
|
|
<p> </tr>
|
|
<tr><td>ATI mach64</td>
|
|
<td>Uses BIOS</td>
|
|
<td>Banked and linear modes</td>
|
|
<td>No FreeBE/AF extensions</td>
|
|
<td>Hardware accelerated</td>
|
|
<p> </tr>
|
|
<tr><td>Avance Logic ALG-2101, ALG-2201, ALG-2228, ALG-2301, ALG-2302</td>
|
|
<td>Uses BIOS</td>
|
|
<td>Banked modes only</td>
|
|
<td>No FreeBE/AF extensions</td>
|
|
<td>Dumb framebuffer</td>
|
|
<p> </tr>
|
|
<tr><td>Cirrus 54xx (not 546x). Should be ok with 5426, 5428, 7541, 7543</td>
|
|
<td>Uses BIOS</td>
|
|
<td>Banked and linear modes</td>
|
|
<td>No FreeBE/AF extensions</td>
|
|
<td>Hardware accelerated</td>
|
|
<p> </tr>
|
|
<tr><td>Matrox Millenium, Mystique, Millenium II</td>
|
|
<td>Uses BIOS</td>
|
|
<td>Banked and linear modes</td>
|
|
<td>Supports farptr and config extensions</td>
|
|
<td>Hardware accelerated</td>
|
|
<p> </tr>
|
|
<tr><td>NVidia Riva 128, TNT. Conflicts with Windows!</td>
|
|
<td>100% portable</td>
|
|
<td>Banked and linear modes</td>
|
|
<td>Supports config extension</td>
|
|
<td>Hardware accelerated</td>
|
|
<p> </tr>
|
|
<tr><td>Paradise</td>
|
|
<td>Uses BIOS</td>
|
|
<td>Banked modes only</td>
|
|
<td>Supports farptr extension</td>
|
|
<td>Dumb framebuffer</td>
|
|
<p> </tr>
|
|
<tr><td>S3</td>
|
|
<td>Uses BIOS</td>
|
|
<td>Banked modes only</td>
|
|
<td>Supports farptr extension</td>
|
|
<td>Hardware accelerated</td>
|
|
<p> </tr>
|
|
<tr><td>Trident TGUI 9440. Doesn't work under Windows!</td>
|
|
<td>100% portable</td>
|
|
<td>Banked and linear modes</td>
|
|
<td>No FreeBE/AF extensions</td>
|
|
<td>Hardware accelerated</td>
|
|
<p> </tr>
|
|
<tr><td>Trident</td>
|
|
<td>Uses BIOS</td>
|
|
<td>Banked modes only</td>
|
|
<td>Supports farptr extension</td>
|
|
<td>Dumb framebuffer</td>
|
|
<p> </tr>
|
|
<tr><td>Tseng ET3000/ET4000/ET6000</td>
|
|
<td>Uses BIOS</td>
|
|
<td>Banked modes only</td>
|
|
<td>Supports farptr extension</td>
|
|
<td>Dumb framebuffer</td>
|
|
<p> </tr>
|
|
<tr><td>Video-7</td>
|
|
<td>Uses BIOS</td>
|
|
<td>Banked modes only</td>
|
|
<td>Supports farptr extension</td>
|
|
<td>Dumb framebuffer</td>
|
|
<p> </tr>
|
|
<tr><td>stub driver (for testing and development purposes only)</td>
|
|
<td>Uses BIOS</td>
|
|
<td>Banked and linear modes</td>
|
|
<td>Supports farptr and config extensions</td>
|
|
<td>Slow software emulation of hardware drawing functions</td></tr></table>
|
|
<p>
|
|
<br>
|
|
<br>
|
|
<h1><a name="Contributing">Contributing</a></h1>
|
|
<p>
|
|
If you want to add a new driver, follow these steps:
|
|
<p><pre>
|
|
md cardname
|
|
copy stub\*.* cardname
|
|
edit makefile
|
|
{ add a new entry to the DRIVERS variable at the top of the file }
|
|
cd cardname
|
|
edit drvhdr.c
|
|
{ replace "stub driver implementation" with your driver name }
|
|
edit driver.c
|
|
{ fill in the blanks, replacing the VESA calls with chipset-specific }
|
|
{ code, and fleshing out the accelerated drawing functions }
|
|
edit notes.txt
|
|
{ describe anything interesting about your driver, most importantly }
|
|
{ listing what drawing functions it supports in hardware }
|
|
cd..
|
|
done!
|
|
<p></pre>
|
|
The makefile requires each driver to provide a drvhdr.c file, which will
|
|
be linked into the drvgen.exe utility and used to generate the VBE/AF
|
|
header. You must also provide a notes.txt, which will be displayed by the
|
|
installation program, but everything else is entirely up to you. Any C
|
|
source files placed into your driver directory will automatically be
|
|
compiled and linked into the driver binary, so you can organise your code
|
|
in whatever style you prefer.
|
|
<p>
|
|
Because the VBE/AF drivers are output as relocatable binary modules, they
|
|
cannot use any C library functions. There are a few utility functions in
|
|
helper.c, but these will not work on any platforms other than DOS+DPMI,
|
|
so it would be better to avoid using them if you can manage without.
|
|
<p>
|
|
A great deal of hardware information can be found in the VGADOC package
|
|
(<a href="ftp://x2ftp.oulu.fi/pub/msdos/programming/docs/vgadoc4b.zip">ftp://x2ftp.oulu.fi/pub/msdos/programming/docs/vgadoc4b.zip</a>) and the
|
|
XFree86 sources (<a href="http://www.xfree86.org/">http://www.xfree86.org/</a>). If this isn't enough, try
|
|
asking the manufacturer for more details.
|
|
<p>
|
|
<br>
|
|
<br>
|
|
<h1><a name="Files">Files</a></h1>
|
|
<p><pre>
|
|
freebe.txt - ASCII format documentation
|
|
freebe.html - HTML format documentation
|
|
freebe._tx - custom format documentation source file
|
|
makefile - script for building the drivers
|
|
vbeaf.h - VBE/AF structures and constants
|
|
start.s - driver relocation code
|
|
helper.c - debugging trace printf() and VESA helper routines
|
|
drvgen.c - modified version of DXEGEN, for building vbeaf.drv
|
|
drv.ld - linker script
|
|
install.c - installation program for binary distributions
|
|
<p>
|
|
stub/vbeaf.drv - example driver, using VESA to access the hardware
|
|
stub/driver.c - main implementation file for the example driver
|
|
stub/drvhdr.c - VBE/AF header structure for the example driver
|
|
stub/notes.txt - more information about the example driver
|
|
<p>
|
|
ati/ - ATI 18800/28800 driver, based on old Allegro code
|
|
avance/ - Avance Logic driver, by George Foot
|
|
cirrus54/ - Cirrus 54x driver, by Michal Mertl
|
|
mach64/ - ATI mach64 driver, by Ove Kaaven
|
|
matrox/ - Matrox driver, by Shawn Hargreaves
|
|
nvidia/ - NVidia driver, by Shawn Hargreaves
|
|
paradise/ - Paradise driver, based on old Allegro code
|
|
s3/ - S3 driver, by Michal Stencl
|
|
tgui/ - Trident TGUI 9440 driver, by Salvador Eduardo Tropea
|
|
trident/ - Trident driver, based on old Allegro code
|
|
tseng/ - Tseng driver, based on old Allegro code
|
|
video7/ - Video-7 driver, based on old Allegro code
|
|
<p></pre>
|
|
<br>
|
|
<br>
|
|
<h1><a name="Copyright">Copyright</a></h1>
|
|
<p>
|
|
As the name implies, FreeBE/AF is free. Both the driver binaries and
|
|
sources may be distributed and modified without restriction. If you find
|
|
any of this stuff useful, the best way to repay us is by writing a new
|
|
driver for a card that isn't currently supported.
|
|
<p>
|
|
Disclaimer: no warranty is provided with this software. We are not to be
|
|
held liable if it fries your monitor, eats your graphics card, or roasts
|
|
your motherboard.
|
|
<p>
|
|
<br>
|
|
<br>
|
|
<h1><a name="Credits">Credits</a></h1>
|
|
<p>
|
|
The DRVGEN utility is based on the djgpp DXEGEN system, by Charles
|
|
Sandmann (<a href="mailto:sandmann@clio.rice.edu">sandmann@clio.rice.edu</a>) and DJ Delorie (<a href="mailto:dj@delorie.com">dj@delorie.com</a>).
|
|
<p>
|
|
Linking/relocation system and ATI mach64 driver by Ove Kaaven
|
|
(<a href="mailto:ovek@arcticnet.no">ovek@arcticnet.no</a>).
|
|
<p>
|
|
VBE/AF framework, stub driver, Matrox driver, NVidia driver, most of the
|
|
old Allegro chipset drivers, conversion from Allegro to VBE/AF format,
|
|
and installation program by Shawn Hargreaves (<a href="mailto:shawn@talula.demon.co.uk">shawn@talula.demon.co.uk</a>).
|
|
<p>
|
|
Cirrus 54x driver by Michal Mertl (<a href="mailto:mime@eunet.cz">mime@eunet.cz</a>).
|
|
<p>
|
|
Trident TGUI 9440 driver by Salvador Eduardo Tropea (<a href="mailto:set-soft@usa.net">set-soft@usa.net</a>).
|
|
<p>
|
|
Avance Logic driver by George Foot (<a href="mailto:george.foot@merton.oxford.ac.uk">george.foot@merton.oxford.ac.uk</a>).
|
|
<p>
|
|
Fixes to the Cirrus 5446 MMIO routines by Keir Fraser (<a href="mailto:kaf24@cam.ac.uk">kaf24@cam.ac.uk</a>).
|
|
<p>
|
|
Tseng ET6000 support by Ben Chauveau (<a href="mailto:bendomc@worldnet.fr">bendomc@worldnet.fr</a>).
|
|
<p>
|
|
Paradise driver by Francois Charton (<a href="mailto:deef@pobox.oleane.com">deef@pobox.oleane.com</a>).
|
|
<p>
|
|
Tseng ET4000 15/24 bit support by Marco Campinoti (<a href="mailto:marco@etruscan.li.it">marco@etruscan.li.it</a>).
|
|
<p>
|
|
Trident driver improved by Mark Habersack (<a href="mailto:grendel@ananke.amu.edu.pl">grendel@ananke.amu.edu.pl</a>).
|
|
<p>
|
|
Video-7 fixes by Markus Oberhumer (<a href="mailto:markus.oberhumer@jk.uni-linz.ac.at">markus.oberhumer@jk.uni-linz.ac.at</a>).
|
|
<p>
|
|
S3 driver improved by Michael Bukin (<a href="mailto:M.A.Bukin@inp.nsk.su">M.A.Bukin@inp.nsk.su</a>).
|
|
<p>
|
|
Video-7 driver by Peter Monks (<a href="mailto:Peter_Monks@australia.notes.pw.com">Peter_Monks@australia.notes.pw.com</a>).
|
|
<p>
|
|
S3 hardware acceleration by Michal Stencl (<a href="mailto:stenclpmd@ba.telecom.sk">stenclpmd@ba.telecom.sk</a>).
|
|
<p>
|
|
Website logo by Colin Walsh (<a href="mailto:cwalsh@nf.sympatico.ca">cwalsh@nf.sympatico.ca</a>).
|
|
<p>
|
|
More graphics hardware support by [insert your name here] :-)
|
|
<p>
|
|
VBE/AF itself is the brainchild of SciTech software, and in particular
|
|
Kendall Bennett (<a href="mailto:KendallB@scitechsoft.com">KendallB@scitechsoft.com</a>).
|
|
<p>
|
|
The Video Electronics Standards Association does _not_ deserve any
|
|
mention here. The absurd prices they charge for copies of the /AF
|
|
specification have prevented it from being widely supported, and I think
|
|
this is a great pity. Long live freedom!
|
|
<p>
|
|
<br>
|
|
<br>
|
|
<h1><a name="History">History</a></h1>
|
|
<p>
|
|
30 March, 1998 - v0.1.
|
|
First public release, containing an example driver implementation that
|
|
runs on top of VESA.
|
|
<p>
|
|
31 March, 1998 - v0.11.
|
|
Added support for multi-buffered modes.
|
|
<p>
|
|
5 April, 1998 - v0.2.
|
|
Added an accelerated Matrox driver.
|
|
<p>
|
|
8 April, 1998 - v0.3.
|
|
Added accelerated drivers for ATI mach64 and Cirrus 54x cards, plus
|
|
minor updates to the Matrox driver.
|
|
<p>
|
|
12 April, 1998 - v0.4.
|
|
Proper installation program, more drawing functions implemented by the
|
|
stub and Matrox drivers, improved ATI driver, compiled with PGCC for a
|
|
5% speed boost.
|
|
<p>
|
|
26 April, 1998 - v0.5.
|
|
More accelerated features in the Cirrus and ATI drivers. Fixed bugs in
|
|
the Matrox driver. Added an option to disable hardware emulation in
|
|
the stub driver, which produces a non-accelerated, dumb framebuffer
|
|
implementation. The init code will now politely fail any programs that
|
|
try to use VBE/AF 1.0 functions, rather than just crashing.
|
|
<p>
|
|
10 June, 1998 - v0.6.
|
|
Fixed scrolling problem on Millenium cards.
|
|
<p>
|
|
1 November, 1998 - v0.7.
|
|
Added drivers for Trident TGUI 9440 and Avance Logic cards, and
|
|
improved the build process.
|
|
<p>
|
|
14 December, 1998 - v0.8.
|
|
Bugfixes to the Matrox Millenium II and Cirrus drivers. Converted all
|
|
the old Allegro library chipset drivers into non-accelerated VBE/AF
|
|
format, adding support for ATI 18800/28800, Paradise, S3, Trident,
|
|
Tseng ET3000/ET4000/ET6000, and Video-7 boards. Designed and
|
|
implemented an API extension mechanism, providing the ability to use
|
|
these drivers in a true protected mode environment, a more rational
|
|
relocation scheme, and various hooks that will later be needed for
|
|
supporting the SciTech Nucleus drivers.
|
|
<p>
|
|
20 December, 1998 - v0.9.
|
|
Bugfixes. Added a config mechanism, allowing the install program to
|
|
optionally disable some features of a driver.
|
|
<p>
|
|
3 January, 1999 - v1.0
|
|
Bugfixes.
|
|
<p>
|
|
27 March, 1999 - v1.1
|
|
Added acceleration support to the S3 driver, plus some bugfixes.
|
|
<p>
|
|
27 June, 1999 - v1.2
|
|
Added driver for NVidia cards. Improved the PCI bus scanning code to
|
|
know about bridges to secondary devices (so it can locate AGP cards).
|
|
Minor bugfix to the Mach64 driver (it was using the wrong clip rect
|
|
for scrolling displays). Minor bugfix to the Matrox driver (it was
|
|
setting the wrong background color for the hardware cursor).
|
|
<p>
|