Subversion Repositories planix.SVN

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