harvey/sys/src/cmd/aux/vga/adventure

From The Be Newsletter 
Volume 3, Issue 8 -- February 24, 1999

--------------------------------------------------------------------------------
BE ENGINEERING INSIGHTS: Adventures in Graphics Drivers 
By Leo Schwab -- <ewhac@be.com> 
--------------------------------------------------------------------------------

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: 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...