ref: dab539cd14726de15932b0310532212f8da29bf7
dir: /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...