sys/src/cmd/aux/vga/adventure

   1
   2 From The Be Newsletter
   3 Volume 3, Issue 8 -- February 24, 1999
   4
   5 --------------------------------------------------------------------------------
   6 BE ENGINEERING INSIGHTS: Adventures in Graphics Drivers
   7 By Leo Schwab -- <ewhac@be.com>
   8 --------------------------------------------------------------------------------
   9
  10 This adventure is more true than I might otherwise be
  11 willing to admit. All persons and events depicted are
  12 entirely fictitious, except where they aren't. Unflattering
  13 characterizations of certain organizations are entirely
  14 deliberate and intentional.
  15
  16         You are in a cube. In front of you is a 16"
  17         (visible) Sony monitor. In front of that is a
  18         Mitsumi keyboard and an unbranded mouse. Just to
  19         the right is a 266 MHz PC clone. The system is
  20         running a development version of BeOS R4.
  21
  22         There is a graphics card here.
  23         There is a floppy disk here.
  24         There is a note from your boss here.
  25         There is a Hoberman sphere here.
  26
  27 > INVENTORY
  28
  29         You have a well-used satchel. Inside it are
  30
  31             A set of screwdrivers
  32             A small telescope
  33             A 16M laptop RAM module
  34             A book on decorative knots
  35             A PCMCIA Ethernet card
  36             Last year's tax return
  37             A 166 MHz Pentium laptop computer
  38             A bottle of echinacea capsules
  39             Hair sticks
  40
  41         Your wallet contains $3200.
  42
  43 > REPLACE KEYBOARD
  44
  45         You put aside the amazingly cruddy Mitsumi keyboard
  46         and substitute your favorite AT&T keyboard.
  47
  48 > PUT LAPTOP ON DESK
  49
  50         The laptop is now on the desk.
  51
  52 > READ NOTE
  53
  54         "Write a driver for this card. We'd like it in time
  55         for R4 release."
  56
  57 > EXAMINE GRAPHICS CARD
  58
  59         You are evidently the proud owner of a Yoyodyne
  60         Monstra VelocElite-LX 128-3D-AGP graphics card.
  61
  62 > INSERT CARD IN MACHINE
  63
  64         The machine emits a curious and worrying noise.
  65
  66 > TURN OFF MACHINE AND INSERT CARD
  67
  68         The graphics card is now installed in the machine.
  69
  70 > TURN ON MACHINE
  71
  72         BeOS R4(devel) boots. You are looking at a
  73         gray scale desktop.
  74
  75 > EXAMINE FLOPPY DISK
  76
  77         The handwritten label reads, "Programming docs."
  78
  79 > INSERT DISK AND PRINT DOCS
  80
  81         Nothing happens.
  82
  83 > INSERT DISK, MOUNT DISK, AND PRINT DOCS
  84
  85         The drive spins for a moment, and the command prompt
  86         returns.
  87
  88 > READ DOCS
  89
  90         I see no docs here.
  91
  92 > GO TO PRINTER AND GET DOCS
  93
  94         The printer is out of paper.
  95
  96 > PUT PAPER IN PRINTER
  97
  98         There is no paper here.
  99
 100 > STEAL PAPER FROM COPIER UPSTAIRS
 101
 102         After installing the liberated paper in the printer,
 103         you print your docs.
 104
 105 > EXAMINE DOCS
 106
 107         The cover page reads, "Yoyodyne Monstra
 108         VelocElite-LX 128-3D Programmer's Reference. Alpha
 109         Revision 05-31-98. Confidential and Proprietary.
 110         Restricted Secret; Level Violet. Do not expose in
 111         public. This document must be kept secured when not
 112         in use. Disclosure of this document to third
 113         parties is punishable by death."
 114
 115 > READ DOCS
 116
 117         After several hours, you finish reading the docs.
 118         The VelocElite-LX is a depressingly predictable
 119         variation on the VGA register set. There are some
 120         registers that have unhelpfully terse descriptions.
 121         The card also has the ability to execute rendering
 122         command lists out of RAM.
 123
 124         You now know enough to write a rough driver for the
 125         card.
 126
 127 > WRITE ROUGH DRIVER
 128
 129         After several days, you have driver ready to test.
 130
 131 > INSTALL DRIVER AND TEST
 132         You reboot the machine.  The screen is blank.
 133
 134 > RUN 'minicom' ON LAPTOP
 135
 136         The 'minicom' terminal emulator is now running in an
 137         XTerm on the laptop.
 138
 139 > PRESS ALT-SYSRQ ON MACHINE
 140
 141         Nothing happens.
 142
 143 > PLUG SERIAL CABLE INTO LAPTOP
 144
 145         The "kdebug>" prompt from the kernel debugger
 146         appears on the XTerm.
 147
 148 > EXAMINE REGISTERS
 149
 150         After thirty minutes, you determine that two of the
 151         sync registers are set incorrectly.
 152
 153 > FIX BUGS IN DRIVER AND TEST
 154
 155         You can't see anything.
 156
 157 > REBOOT IN SAFE MODE AND FIX BUGS
 158
 159         A new version of the driver is ready to test.
 160
 161 > TEST
 162
 163         You reboot the machine. You see a color BeOS
 164         desktop.
 165
 166 > TEST MODES
 167
 168         You switch to 800*600. It looks fine.
 169         You switch to 1024*768. It looks fine.
 170         You switch to 1152*864. There are pixel sparkles on
 171         the screen.
 172
 173 > PRESS ALT-SYSRQ ON MACHINE
 174
 175         Nothing happens.
 176
 177 > YES, IT DOES!
 178
 179         Oh, sorry, I forgot. You get a "kdebug>" prompt.
 180
 181 > EXAMINE SYNC REGISTERS
 182
 183         After forty minutes, you find nothing wrong with the
 184         registers.
 185
 186 > EXAMINE REGISTER 0x6000
 187
 188         Register 0x6000 (FIFO watermarks) contains 0x0201
 189         (powerup default).
 190
 191 > WRITE 0x0200 TO REGISTER 0x6000
 192
 193         This is one of the poorly documented registers. Are
 194         you sure you want to do this?
 195
 196 > YES
 197
 198         The screen goes blank.
 199
 200 > WRITE 0x0201 TO REGISTER 0x6000
 201
 202         You see a color BeOS desktop.
 203
 204 > WRITE 0x0202 TO REGISTER 0x6000
 205
 206         The screen goes blank.
 207
 208 [ ...Many more iterations deleted... ]
 209
 210 > WRITE 0x1810 TO REGISTER 0x6000
 211
 212         The pixel sparkles cease.
 213
 214 > MODIFY DRIVER TO WRITE 0x1810 to 0x6000 AND TEST
 215
 216         You reboot the machine. You see a color BeOS
 217         desktop, sans pixel sparkles.
 218
 219 > ADD HARDWARE BLITTER SUPPORT TO DRIVER AND TEST
 220
 221         You reboot the machine. You see a perfectly stable
 222         display of utter garbage with icons and text on top
 223         of it.
 224
 225 > FIX RECTANGLE CODE AND TEST
 226
 227         You reboot the machine. You see a color BeOS desktop.
 228
 229 > DRAG WINDOW
 230
 231         The screen turns blank.
 232
 233 > FIX BLITTING CODE AND TEST
 234
 235         You can't see anything. If you proceed, you will
 236         likely be eaten by a Grue.
 237
 238 > REBOOT IN SAFE MODE, FIX BLITTING CODE, AND TEST
 239
 240         You reboot the machine. A color BeOS desktop greets
 241         you.
 242
 243 > DRAG WINDOW
 244
 245         The window moves, but leaves "dirt" behind it.
 246
 247 > READ DOCS ON BLITTER
 248
 249         "The blit width register is set to the number of
 250         bytes copied per row." Your code reflects this
 251         statement.
 252
 253 > ADD FENCEPOST TO BLIT WIDTH AND TEST
 254
 255         You reboot the machine. Windows now drag normally,
 256         except for some weirdness at the left edge of the
 257         screen.
 258
 259 > EXAMINE WEIRDNESS
 260
 261         It looks as if the left four columns of pixels are
 262         being blitted 64 pixels too high.
 263
 264 > READ DOCS ON BLITTER
 265
 266         There is nothing in the docs to explain this behavior.
 267
 268 > GO www.yoyodyne.com
 269
 270         You are in a Web site.
 271
 272         There are many links here.
 273
 274 > GO DEVELOPER SUPPORT
 275
 276         There is no developer support here.
 277
 278 > READ DOCS ON SUPPORT
 279
 280         There is nothing in the docs on how to get support.
 281
 282 > TALK TO BOSS
 283
 284         Your boss gives you the e-mail address of the contact
 285         person at Yoyodyne.
 286
 287 > SEND MAIL DESCRIBING PROBLEM
 288
 289         The e-mail disappears down the Ethernet port, on its
 290         way to yoyodyne.com.
 291
 292 > WAIT
 293
 294         Time passes.
 295
 296         You have new mail.
 297
 298 > READ MAIL
 299
 300         You have 1 new message(s):
 301
 302         From: john.smallberries@yoyodyne.com
 303         "Oh, yeah. That's a known bug. The official
 304         workaround is to copy those four pixel columns in
 305         software."
 306
 307 > WRITE SPECIAL CASE FOR BLITTING CODE AND TEST
 308
 309         You reboot the machine. Windows now glide across
 310         the display like silk.
 311
 312 > TEST 15 BIT MODES
 313
 314         All 15 bit modes work perfectly.
 315
 316 > TEST 16 BIT MODES
 317
 318         All 16 bit modes work perfectly.
 319
 320 > TEST 32 BIT MODES
 321
 322         The screen turns blank, then returns to the previous
 323         mode.
 324
 325 > READ DOCS ON DISPLAY DEPTHS
 326
 327         "The following display depths are supported:
 328
 329                 0x00:   4 bits
 330                 0x02:   8 bits
 331                 0x04:   16 bits (RGB 555)
 332                 0x05:   16 bits (RGB 565)
 333                 0x06:   24 bits (RGB 888)
 334                 0x08:   32 bits (xRGB 8888)"
 335
 336 > PRESS ALT-SYSRQ AND EXAMINE REGISTER
 337
 338         The display depth register is set to 0x05.
 339
 340 > WRITE 0x08 TO REGISTER
 341
 342         The display turns blank.
 343
 344 > WRITE 0x06 TO REGISTER
 345
 346         You see a color BeOS desktop.
 347
 348 > WRITE MAIL DESCRIBING PROBLEM
 349
 350         Nothing happens.
 351
 352 > ENTER 'c' AT DEBUGGER PROMPT AND WRITE MAIL
 353
 354         The e-mail disappears down the Ethernet port, on its
 355         way to yoyodyne.com.
 356
 357 > WAIT
 358
 359         Time passes.
 360
 361         You have new mail.
 362
 363 > READ MAIL
 364
 365         You have 1 new message(s):
 366
 367         From: john.smallberries@yoyodyne.com
 368         "I just spoke to our hardware engineer, and he says
 369         that 32-bit modes don't really work all that well,
 370         and they should be avoided. 24-bit works fine,
 371         however."
 372
 373 > REMOVE 32 BIT SUPPORT FROM DRIVER AND TEST
 374
 375         You reboot the machine. You have now have a
 376         functional accelerated BeOS desktop.
 377
 378 > CHECK DRIVER INTO SOURCE TREE
 379
 380         You check in your new source files into the master
 381         source tree.
 382
 383         You have broken the build.
 384
 385         A dunce cap has appeared in your cube.
 386
 387 > FIX DEPENDENCY FILE AND CHECK IN
 388
 389         The build is restored to its former glory.
 390
 391         The dunce cap has vanished.
 392
 393         You have new mail.
 394
 395 > READ MAIL
 396
 397         You have 1 new message(s):
 398
 399         From: baron@be.com
 400         "We're having trouble with the Yoyodyne driver in
 401         the QA lab. Can you look at it?"
 402
 403 > GO QA LAB
 404
 405         You are in the QA Lab. Many machines on many
 406         shelves are here, running test programs. The Baron
 407         directs you to the misbehaving machine. Its screen
 408         is blank.
 409
 410 > TELNET INTO MACHINE
 411
 412         A 'bash' shell prompt greets you.
 413
 414 > REMOVE FILE '/boot/home/config/settings/app_server_settings'
 415   AND REBOOT
 416
 417         You reboot the machine. You see a perfectly
 418         functional 640*480 display.
 419
 420         The Baron looks like he has something to say.
 421
 422 > TALK TO BARON
 423
 424         He directs you to another machine. The monitor
 425         looks as if it can't quite sync to the card's
 426         signal.
 427
 428 > TELNET INTO MACHINE
 429
 430         A 'bash' shell prompt greets you.
 431
 432 > REMOVE FILE '/boot/home/config/settings/app_server_settings'
 433   AND REBOOT
 434
 435         Ha ha! That doesn't work this time! A sense of
 436         crushing defeat envelops you.
 437
 438 > DON'T EDITORIALIZE
 439
 440         Sorry.
 441
 442 > EXAMINE MONITOR
 443
 444         You are looking at a Flabloden 15ZF monitor.
 445
 446 > READ MONITOR DOCS
 447
 448         "Congratulations on your purchase of a Flabloden
 449         15ZF monitor. Our products are fully compliant with
 450         VESA standards, including the VESA signalling and
 451         GTF specifications, assuring your monitor will work
 452         with whatever the hell graphics card you have
 453         installed..."
 454
 455 > GO www.vesa.org
 456
 457         You are at the Video Electronics Standards
 458         Association's Web site.
 459
 460         There are many links here.
 461
 462         A Reporter from CNN visiting Jean-Louis wanders by.
 463         He glances in your cube.
 464
 465 > HIDE YOYODYNE DOCS!
 466
 467         It is too late. The Reporter has seen the docs on
 468         your desk. A lightning bolt stabs out of the sky
 469         and through the ceiling, striking the Reporter,
 470         leaving only a smoking pile of ash.
 471
 472 > CLEAN UP ASH
 473
 474         You dutifully clean up the Reporter's remains.
 475
 476 > SEARCH FOR GTF DOCS
 477
 478         You find a link here named "VESA General Timing
 479         Formula."
 480
 481 > GO VESA GENERAL TIMING FORMULA
 482
 483         A Troll bars your way. He is demanding tribute.
 484
 485 > EXAMINE TROLL
 486
 487         He is big, strong, mean, ugly, pitiless, and
 488         unusually well dressed.
 489
 490 > EVADE TROLL
 491
 492         Despite your best efforts, the Troll thwarts your
 493         attempts to evade him.
 494
 495 > TALK TO TROLL
 496
 497         "THOU CANST NOT PASS LEST THOU PAYEST UNTO ME MY
 498         RIGHTFUL TRIBUTE!" thunders the Troll.
 499
 500 > EXPLAIN SITUATION TO TROLL
 501
 502         The Troll ignores you.
 503
 504 > KILL TROLL
 505
 506         You can't do that.
 507
 508 > DAMMIT!
 509
 510         Now who's editorializing?
 511
 512 > PAY TRIBUTE
 513
 514         Reluctantly, you hand over the required tribute.
 515         The Troll gives you a token so that you may pass
 516         this way again.
 517
 518         Your wallet now contains $2500.
 519
 520 > GO VESA GENERAL TIMING FORMULA
 521
 522         There is a file here. The description says it
 523         contains the algorithm for calculating sync timings
 524         for any display mode.
 525
 526 > DOWNLOAD FILE
 527
 528         A copy of the file is now on your machine.
 529
 530 > READ FILE
 531
 532         There is no PDF reader here.
 533
 534 > TRANSFER FILE TO LAPTOP AND READ
 535
 536         After picking through some opaque language, you now
 537         understand the VESA GTF.
 538
 539 > ADD VESA GTF CODE TO DRIVER AND TEST
 540
 541         You reboot the machine. The Flabloden 15ZF monitor
 542         now works perfectly.
 543
 544         You have new mail.
 545
 546 > READ MAIL
 547
 548         You have 2 new message(s):
 549
 550         From: xf541ceuc8@aol.com
 551         "MAKE.MONEY.FAST! Hi, my name is Dave Rhodes..."
 552
 553 > DELETE MESSAGE, NEXT MESSAGE
 554
 555         From: rjs@be.com
 556         "We're going to need AGP support on the Yoyodyne
 557         card so we can start on OpenGL acceleration. Can
 558         you help with that?"
 559
 560 > READ DOCS ON AGP
 561
 562         Except for a few PCI configuration registers, there
 563         is no mention of AGP in the docs.
 564
 565 > GO developer.intel.com
 566
 567         You are at Intel's developers' Web site.
 568
 569         There are many links here.
 570
 571 > FIND AGP DOCS
 572
 573         You find a single file named, "Accelerated Graphics
 574         Port Interface Specification (v2.0)".
 575
 576 > DOWNLOAD FILE TO LAPTOP AND READ
 577
 578         AGP is an extension to PCI. Like a modern CPU's
 579         MMU, AGP uses a translation table (called a GART) to
 580         make disjoint blocks of system memory appear
 581         contiguous. Both the graphics card and the
 582         motherboard controller must be properly configured
 583         for AGP to work. The layout and function of the PCI
 584         AGP configuration registers are described only in
 585         general terms. Most of the rest of the document
 586         describes hardware implementation and signalling
 587         details.
 588
 589 > EXAMINE MOTHERBOARD IN MACHINE
 590
 591         Your machine uses an Intel 440LX motherboard
 592         controller.
 593
 594 > GO developer.intel.com
 595
 596         You are at Intel's developers' Web site.
 597
 598         There are many links here.
 599
 600 > FIND 440LX DOCS
 601
 602         You find a file named, "Intel 440LX AGPset: 82443LX
 603         PCI AGP Controller (PAC) Datasheet"
 604
 605 > DOWNLOAD FILE TO LAPTOP AND READ
 606
 607         You now understand how to program the host's and
 608         graphics card's AGP control registers.
 609
 610 > ADD CODE ENABLING AGP 1X MODE TO DRIVER AND TEST
 611
 612         You reboot the machine. Everything still works.
 613
 614 > ADD CODE ENABLING SIDEBAND ADDRESSING TO DRIVER AND TEST
 615
 616         You reboot the machine. Everything still works.
 617
 618 > ADD CODE ENABLING GART TO DRIVER AND TEST
 619
 620         You do not know how to create a GART.
 621
 622 > READ AGP DOCS ON GART
 623
 624         "The specific layout of the GART is
 625         chipset-specific, and not documented here. GART
 626         manipulation is done via a miniport driver or HAL
 627         supplied with the chipset BIOS reference
 628         implementation."
 629
 630 > READ 440LX DOCS ON GART
 631
 632         There is no description of the GART here.
 633
 634 > GO developer.intel.com
 635
 636         You are at Intel's developers' Web site.
 637
 638         There are many links here.
 639
 640 > FIND GART DOCS
 641
 642         There are no GART docs here.
 643
 644 > SEARCH FOR OTHER AGP RESOURCES
 645
 646         There is a link to the AGP Implementor's Forum, at
 647         www.agpforum.org.
 648
 649 > GO www.agpforum.org
 650
 651         You are at the AGP Implementor's Forum Web site.
 652
 653         There are many links here.
 654
 655 > FIND GART DOCS
 656
 657         A Troll bars your way. He is demanding tribute.
 658
 659 > EVADE TROLL
 660
 661         Despite your best efforts, the Troll thwarts your
 662         attempts to evade him.
 663
 664 > PAY TRIBUTE
 665
 666         Reluctantly, you hand over the required tribute.
 667         The Troll gives you a token so that you may pass
 668         this way again.
 669
 670         Your wallet is now empty.
 671
 672 > FIND GART DOCS
 673
 674         There are no GART docs here. The Troll laughs
 675         uproariously.
 676
 677 > FIND ALL PROGRAMMING DOCS
 678
 679         You find a file named, "System Software."
 680
 681 > DOWNLOAD FILE TO LAPTOP AND READ
 682
 683         'ghostscript' reports: "This PDF file is encrypted
 684         and cannot be processed."
 685
 686 > CRASH LAPTOP BACK TO WINDOWS
 687
 688         You close your XTerms, reboot the laptop, and in
 689         mere minutes, Windows is ready.
 690
 691 > OPEN "SYSTEM SOFTWARE" DOCS
 692
 693         The PDF reader opens. This looks suspiciously like a
 694         Powerpoint slide.
 695
 696 > SEARCH DOCS FOR "GART"
 697
 698         "GART manipulation is performed through the miniport
 699         driver and DirectX 5 extensions..."
 700
 701 > CURSE
 702
 703         You heartily curse in a manner that comes only with
 704         long practice. Co-workers pop up from their cubes
 705         like prairie dogs.
 706
 707 > SCORE
 708
 709         Out of a possible 127 points, you have a total score
 710         of 83 (65%).
 711
 712 > SAVE
 713
 714         Your adventure has been saved...
 715