From The Be Newsletter
Volume 3, Issue 8 -- February 24, 1999
--------------------------------------------------------------------------------
BE ENGINEERING INSIGHTS: Adventures in Graphics Drivers
By Leo Schwab -- <
[email protected]>
--------------------------------------------------------------------------------
This adventure is more true than I might otherwise be
willing to admit. All persons and events depicted are
entirely fictitious, except where they aren't. Unflattering
characterizations of certain organizations are entirely
deliberate and intentional.
You are in a cube. In front of you is a 16"
(visible) Sony monitor. In front of that is a
Mitsumi keyboard and an unbranded mouse. Just to
the right is a 266 MHz PC clone. The system is
running a development version of BeOS R4.
There is a graphics card here.
There is a floppy disk here.
There is a note from your boss here.
There is a Hoberman sphere here.
> INVENTORY
You have a well-used satchel. Inside it are
A set of screwdrivers
A small telescope
A 16M laptop RAM module
A book on decorative knots
A PCMCIA Ethernet card
Last year's tax return
A 166 MHz Pentium laptop computer
A bottle of echinacea capsules
Hair sticks
Your wallet contains $3200.
> REPLACE KEYBOARD
You put aside the amazingly cruddy Mitsumi keyboard
and substitute your favorite AT&T keyboard.
> PUT LAPTOP ON DESK
The laptop is now on the desk.
> READ NOTE
"Write a driver for this card. We'd like it in time
for R4 release."
> EXAMINE GRAPHICS CARD
You are evidently the proud owner of a Yoyodyne
Monstra VelocElite-LX 128-3D-AGP graphics card.
> INSERT CARD IN MACHINE
The machine emits a curious and worrying noise.
> TURN OFF MACHINE AND INSERT CARD
The graphics card is now installed in the machine.
> TURN ON MACHINE
BeOS R4(devel) boots. You are looking at a
gray scale desktop.
> EXAMINE FLOPPY DISK
The handwritten label reads, "Programming docs."
> INSERT DISK AND PRINT DOCS
Nothing happens.
> INSERT DISK, MOUNT DISK, AND PRINT DOCS
The drive spins for a moment, and the command prompt
returns.
> READ DOCS
I see no docs here.
> GO TO PRINTER AND GET DOCS
The printer is out of paper.
> PUT PAPER IN PRINTER
There is no paper here.
> STEAL PAPER FROM COPIER UPSTAIRS
After installing the liberated paper in the printer,
you print your docs.
> EXAMINE DOCS
The cover page reads, "Yoyodyne Monstra
VelocElite-LX 128-3D Programmer's Reference. Alpha
Revision 05-31-98. Confidential and Proprietary.
Restricted Secret; Level Violet. Do not expose in
public. This document must be kept secured when not
in use. Disclosure of this document to third
parties is punishable by death."
> READ DOCS
After several hours, you finish reading the docs.
The VelocElite-LX is a depressingly predictable
variation on the VGA register set. There are some
registers that have unhelpfully terse descriptions.
The card also has the ability to execute rendering
command lists out of RAM.
You now know enough to write a rough driver for the
card.
> WRITE ROUGH DRIVER
After several days, you have driver ready to test.
> INSTALL DRIVER AND TEST
You reboot the machine. The screen is blank.
> RUN 'minicom' ON LAPTOP
The 'minicom' terminal emulator is now running in an
XTerm on the laptop.
> PRESS ALT-SYSRQ ON MACHINE
Nothing happens.
> PLUG SERIAL CABLE INTO LAPTOP
The "kdebug>" prompt from the kernel debugger
appears on the XTerm.
> EXAMINE REGISTERS
After thirty minutes, you determine that two of the
sync registers are set incorrectly.
> FIX BUGS IN DRIVER AND TEST
You can't see anything.
> REBOOT IN SAFE MODE AND FIX BUGS
A new version of the driver is ready to test.
> TEST
You reboot the machine. You see a color BeOS
desktop.
> TEST MODES
You switch to 800*600. It looks fine.
You switch to 1024*768. It looks fine.
You switch to 1152*864. There are pixel sparkles on
the screen.
> PRESS ALT-SYSRQ ON MACHINE
Nothing happens.
> YES, IT DOES!
Oh, sorry, I forgot. You get a "kdebug>" prompt.
> EXAMINE SYNC REGISTERS
After forty minutes, you find nothing wrong with the
registers.
> EXAMINE REGISTER 0x6000
Register 0x6000 (FIFO watermarks) contains 0x0201
(powerup default).
> WRITE 0x0200 TO REGISTER 0x6000
This is one of the poorly documented registers. Are
you sure you want to do this?
> YES
The screen goes blank.
> WRITE 0x0201 TO REGISTER 0x6000
You see a color BeOS desktop.
> WRITE 0x0202 TO REGISTER 0x6000
The screen goes blank.
[ ...Many more iterations deleted... ]
> WRITE 0x1810 TO REGISTER 0x6000
The pixel sparkles cease.
> MODIFY DRIVER TO WRITE 0x1810 to 0x6000 AND TEST
You reboot the machine. You see a color BeOS
desktop, sans pixel sparkles.
> ADD HARDWARE BLITTER SUPPORT TO DRIVER AND TEST
You reboot the machine. You see a perfectly stable
display of utter garbage with icons and text on top
of it.
> FIX RECTANGLE CODE AND TEST
You reboot the machine. You see a color BeOS desktop.
> DRAG WINDOW
The screen turns blank.
> FIX BLITTING CODE AND TEST
You can't see anything. If you proceed, you will
likely be eaten by a Grue.
> REBOOT IN SAFE MODE, FIX BLITTING CODE, AND TEST
You reboot the machine. A color BeOS desktop greets
you.
> DRAG WINDOW
The window moves, but leaves "dirt" behind it.
> READ DOCS ON BLITTER
"The blit width register is set to the number of
bytes copied per row." Your code reflects this
statement.
> ADD FENCEPOST TO BLIT WIDTH AND TEST
You reboot the machine. Windows now drag normally,
except for some weirdness at the left edge of the
screen.
> EXAMINE WEIRDNESS
It looks as if the left four columns of pixels are
being blitted 64 pixels too high.
> READ DOCS ON BLITTER
There is nothing in the docs to explain this behavior.
> GO www.yoyodyne.com
You are in a Web site.
There are many links here.
> GO DEVELOPER SUPPORT
There is no developer support here.
> READ DOCS ON SUPPORT
There is nothing in the docs on how to get support.
> TALK TO BOSS
Your boss gives you the e-mail address of the contact
person at Yoyodyne.
> SEND MAIL DESCRIBING PROBLEM
The e-mail disappears down the Ethernet port, on its
way to yoyodyne.com.
> WAIT
Time passes.
You have new mail.
> READ MAIL
You have 1 new message(s):
From:
[email protected]
"Oh, yeah. That's a known bug. The official
workaround is to copy those four pixel columns in
software."
> WRITE SPECIAL CASE FOR BLITTING CODE AND TEST
You reboot the machine. Windows now glide across
the display like silk.
> TEST 15 BIT MODES
All 15 bit modes work perfectly.
> TEST 16 BIT MODES
All 16 bit modes work perfectly.
> TEST 32 BIT MODES
The screen turns blank, then returns to the previous
mode.
> READ DOCS ON DISPLAY DEPTHS
"The following display depths are supported:
0x00: 4 bits
0x02: 8 bits
0x04: 16 bits (RGB 555)
0x05: 16 bits (RGB 565)
0x06: 24 bits (RGB 888)
0x08: 32 bits (xRGB 8888)"
> PRESS ALT-SYSRQ AND EXAMINE REGISTER
The display depth register is set to 0x05.
> WRITE 0x08 TO REGISTER
The display turns blank.
> WRITE 0x06 TO REGISTER
You see a color BeOS desktop.
> WRITE MAIL DESCRIBING PROBLEM
Nothing happens.
> ENTER 'c' AT DEBUGGER PROMPT AND WRITE MAIL
The e-mail disappears down the Ethernet port, on its
way to yoyodyne.com.
> WAIT
Time passes.
You have new mail.
> READ MAIL
You have 1 new message(s):
From:
[email protected]
"I just spoke to our hardware engineer, and he says
that 32-bit modes don't really work all that well,
and they should be avoided. 24-bit works fine,
however."
> REMOVE 32 BIT SUPPORT FROM DRIVER AND TEST
You reboot the machine. You have now have a
functional accelerated BeOS desktop.
> CHECK DRIVER INTO SOURCE TREE
You check in your new source files into the master
source tree.
You have broken the build.
A dunce cap has appeared in your cube.
> FIX DEPENDENCY FILE AND CHECK IN
The build is restored to its former glory.
The dunce cap has vanished.
You have new mail.
> READ MAIL
You have 1 new message(s):
From:
[email protected]
"We're having trouble with the Yoyodyne driver in
the QA lab. Can you look at it?"
> GO QA LAB
You are in the QA Lab. Many machines on many
shelves are here, running test programs. The Baron
directs you to the misbehaving machine. Its screen
is blank.
> TELNET INTO MACHINE
A 'bash' shell prompt greets you.
> REMOVE FILE '/boot/home/config/settings/app_server_settings'
AND REBOOT
You reboot the machine. You see a perfectly
functional 640*480 display.
The Baron looks like he has something to say.
> TALK TO BARON
He directs you to another machine. The monitor
looks as if it can't quite sync to the card's
signal.
> TELNET INTO MACHINE
A 'bash' shell prompt greets you.
> REMOVE FILE '/boot/home/config/settings/app_server_settings'
AND REBOOT
Ha ha! That doesn't work this time! A sense of
crushing defeat envelops you.
> DON'T EDITORIALIZE
Sorry.
> EXAMINE MONITOR
You are looking at a Flabloden 15ZF monitor.
> READ MONITOR DOCS
"Congratulations on your purchase of a Flabloden
15ZF monitor. Our products are fully compliant with
VESA standards, including the VESA signalling and
GTF specifications, assuring your monitor will work
with whatever the hell graphics card you have
installed..."
> GO www.vesa.org
You are at the Video Electronics Standards
Association's Web site.
There are many links here.
A Reporter from CNN visiting Jean-Louis wanders by.
He glances in your cube.
> HIDE YOYODYNE DOCS!
It is too late. The Reporter has seen the docs on
your desk. A lightning bolt stabs out of the sky
and through the ceiling, striking the Reporter,
leaving only a smoking pile of ash.
> CLEAN UP ASH
You dutifully clean up the Reporter's remains.
> SEARCH FOR GTF DOCS
You find a link here named "VESA General Timing
Formula."
> GO VESA GENERAL TIMING FORMULA
A Troll bars your way. He is demanding tribute.
> EXAMINE TROLL
He is big, strong, mean, ugly, pitiless, and
unusually well dressed.
> EVADE TROLL
Despite your best efforts, the Troll thwarts your
attempts to evade him.
> TALK TO TROLL
"THOU CANST NOT PASS LEST THOU PAYEST UNTO ME MY
RIGHTFUL TRIBUTE!" thunders the Troll.
> EXPLAIN SITUATION TO TROLL
The Troll ignores you.
> KILL TROLL
You can't do that.
> DAMMIT!
Now who's editorializing?
> PAY TRIBUTE
Reluctantly, you hand over the required tribute.
The Troll gives you a token so that you may pass
this way again.
Your wallet now contains $2500.
> GO VESA GENERAL TIMING FORMULA
There is a file here. The description says it
contains the algorithm for calculating sync timings
for any display mode.
> DOWNLOAD FILE
A copy of the file is now on your machine.
> READ FILE
There is no PDF reader here.
> TRANSFER FILE TO LAPTOP AND READ
After picking through some opaque language, you now
understand the VESA GTF.
> ADD VESA GTF CODE TO DRIVER AND TEST
You reboot the machine. The Flabloden 15ZF monitor
now works perfectly.
You have new mail.
> READ MAIL
You have 2 new message(s):
From:
[email protected]
"MAKE.MONEY.FAST! Hi, my name is Dave Rhodes..."
> DELETE MESSAGE, NEXT MESSAGE
From:
[email protected]
"We're going to need AGP support on the Yoyodyne
card so we can start on OpenGL acceleration. Can
you help with that?"
> READ DOCS ON AGP
Except for a few PCI configuration registers, there
is no mention of AGP in the docs.
> GO developer.intel.com
You are at Intel's developers' Web site.
There are many links here.
> FIND AGP DOCS
You find a single file named, "Accelerated Graphics
Port Interface Specification (v2.0)".
> DOWNLOAD FILE TO LAPTOP AND READ
AGP is an extension to PCI. Like a modern CPU's
MMU, AGP uses a translation table (called a GART) to
make disjoint blocks of system memory appear
contiguous. Both the graphics card and the
motherboard controller must be properly configured
for AGP to work. The layout and function of the PCI
AGP configuration registers are described only in
general terms. Most of the rest of the document
describes hardware implementation and signalling
details.
> EXAMINE MOTHERBOARD IN MACHINE
Your machine uses an Intel 440LX motherboard
controller.
> GO developer.intel.com
You are at Intel's developers' Web site.
There are many links here.
> FIND 440LX DOCS
You find a file named, "Intel 440LX AGPset: 82443LX
PCI AGP Controller (PAC) Datasheet"
> DOWNLOAD FILE TO LAPTOP AND READ
You now understand how to program the host's and
graphics card's AGP control registers.
> ADD CODE ENABLING AGP 1X MODE TO DRIVER AND TEST
You reboot the machine. Everything still works.
> ADD CODE ENABLING SIDEBAND ADDRESSING TO DRIVER AND TEST
You reboot the machine. Everything still works.
> ADD CODE ENABLING GART TO DRIVER AND TEST
You do not know how to create a GART.
> READ AGP DOCS ON GART
"The specific layout of the GART is
chipset-specific, and not documented here. GART
manipulation is done via a miniport driver or HAL
supplied with the chipset BIOS reference
implementation."
> READ 440LX DOCS ON GART
There is no description of the GART here.
> GO developer.intel.com
You are at Intel's developers' Web site.
There are many links here.
> FIND GART DOCS
There are no GART docs here.
> SEARCH FOR OTHER AGP RESOURCES
There is a link to the AGP Implementor's Forum, at
www.agpforum.org.
> GO www.agpforum.org
You are at the AGP Implementor's Forum Web site.
There are many links here.
> FIND GART DOCS
A Troll bars your way. He is demanding tribute.
> EVADE TROLL
Despite your best efforts, the Troll thwarts your
attempts to evade him.
> PAY TRIBUTE
Reluctantly, you hand over the required tribute.
The Troll gives you a token so that you may pass
this way again.
Your wallet is now empty.
> FIND GART DOCS
There are no GART docs here. The Troll laughs
uproariously.
> FIND ALL PROGRAMMING DOCS
You find a file named, "System Software."
> DOWNLOAD FILE TO LAPTOP AND READ
'ghostscript' reports: "This PDF file is encrypted
and cannot be processed."
> CRASH LAPTOP BACK TO WINDOWS
You close your XTerms, reboot the laptop, and in
mere minutes, Windows is ready.
> OPEN "SYSTEM SOFTWARE" DOCS
The PDF reader opens. This looks suspiciously like a
Powerpoint slide.
> SEARCH DOCS FOR "GART"
"GART manipulation is performed through the miniport
driver and DirectX 5 extensions..."
> CURSE
You heartily curse in a manner that comes only with
long practice. Co-workers pop up from their cubes
like prairie dogs.
> SCORE
Out of a possible 127 points, you have a total score
of 83 (65%).
> SAVE
Your adventure has been saved...
