[logo]ewhac

Adventures in Graphics Drivers

1999.02.24

Last updated: 2020.01.08

A short "technical article" I wrote for the weekly Be Developers' Newsletter.

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

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 800600. It looks fine.
You switch to 1024768. 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: john.smallberries@yoyodyne.com
"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: john.smallberries@yoyodyne.com
"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: baron@be.com
"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: xf541ceuc8@aol.com
"MAKE.MONEY.FAST! Hi, my name is Dave Rhodes..."

> DELETE MESSAGE, NEXT MESSAGE

From: rjs@be.com
"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...