1 2 How to add an (S)VGA driver to XFree86 3 -------------------------------------- 4 (c) 1993 David E. Wexelblat <dwex@goblin.org> 5 Issue 1.2 - May 22, 1993 6 7Contents 8-------- 9 1) Introduction 10 2) Getting Started 11 3) Directory Tree Structure 12 4) Setting Up The Build Information 13 5) The Bank-Switching Functions 14 6) The Driver Itself 15 6a) Multiple Chipsets And Options 16 6b) Data Structures 17 6c) The Ident() function 18 6d) The ClockSelect() function 19 6e) The Probe() function 20 6f) The EnterLeave() function 21 6g) The Restore() function 22 6h) The Save() function 23 6i) The Init() function 24 6j) The Adjust() function 25 6k) The SaveScreen() function 26 6l) The GetMode() function 27 6m) The FbInit() function 28 7) Building The New Server 29 8) Debugging 30 9) Advice 31 10) Advanced Topics 32 11) References 33 12) Vendor Contact Information 34 351 - Introduction 36---------------- 37 Adding support for a new SVGA chipset to XFree86 is a challenging project 38for someone who wants to learn more about hardware-level programming. It 39can be fraught with hazards (in particular, crashing the machine is all too 40common). But in the end, when the server comes up and functions, it is 41immensely satisfying. 42 43Adding support for an SVGA chipset does not change any of the basic 44functioning of the server. It is still a dumb 8-bit PseudoColor server or 451-bit StaticGray server. Adding support for new hardware (e.g. accelerated 46chips) is a major undertaking, and is not anywhere near formalized enough yet 47that it can be documented. 48 49Nonetheless, the driver-level programming here is a good introduction. And 50can well be the first step for adding support for an accelerated chipset, as 51many are SVGA-supersets. Writing an SVGA-level driver for the chipset can 52provide a stable development platform for making use of new features (in fact, 53this has been done for the S3, Cirrus, and WD accelerated chipsets, for 54internal use as the accelerated servers are developed for XFree86 2.0). 55 56Now let's get down to it. In addition to this documentation, a stub driver has 57been provided. This should provide you a complete framework for your new 58driver. Don't let the size of this document persuade you that this is an 59overly difficult task. A lot of work has been put into making this document 60as close to complete as possible; hence it should, in theory, be possible to 61use this as a cookbook, and come out with a working driver when you reach the 62end. I do advise that you read it all the way through before starting. 63 642 - Getting Started 65------------------- 66 The first step in developing a new driver is to get the documentation for 67your chipset. I've included a list of vendor contact information that I have 68collected so far (it's far from complete, so if you have any that isn't on 69the list, please send it to me). You need to obtain the databook for the 70chipset. Make sure that the person you speak to is aware that you intend to 71do register-level programming (so they don't send you the EE-style datasheet). 72Ask for any example code, or developer's kits, etc. I've learned that at the 73SVGA level, in general, a databook that lists and describes the registers is 74the most you can hope to find. 75 76If you are not familiar with VGA register-level programming, you should get 77(and read!) a copy of Richard Ferraro's bible (see references below). The 78best way to understand what is happening in the server is to study the 79workings of the monochrome server's "generic" server, and compare it with 80the documentation in Ferraro's book (be aware that there are a few errors 81in the book). You can find the generic-VGA-register handling functions in 82the file "vgaHW.c". 83 84Once you understand what's happening in the generic server, you should study 85one or more of the existing SVGA drivers. Obtain the databook for a supported 86SVGA chipset, and study the documentation along with the code. When you have 87a good understanding of what that driver does over and above the generic VGA, 88you will know what information you need to obtain from the databook for the 89new chipset. Once you have this information, you are ready to begin work on 90your new driver. 91 923 - Directory Tree Structure 93---------------------------- 94 Here is an outline of the directory tree structure for the source tree. 95Only directories/files that are relevant to writing a driver are presented. 96The structure for the Link Kit is presented below. 97 98mit/config/ 99 site.def Local configuration customization 100 x386.cf XFree86 configuration/build parameters 101 102mit/server/ddx/x386/ The server source 103 common/ Files common to all of the server (Xconfig 104 parser, I/O device handlers, etc) 105 x386.h Contains the 'ScrnInfoRec' data structure 106 xf86_Option.h Contains option flags 107 compiler.h Contains in-line assembler macros and 108 utility functions 109 os-support/ OS-support layer 110 assyntax.h Contains macro-ized assembler mnemonics 111 xf86_OSlib.h OS-support includes, defines, and prototypes 112 LinkKit/ 113 site.def.LK Template for Link Kit site.def 114 vga256/ 256-color VGA server directories 115 vga/ The generic VGA handling code 116 vga.h Contains the 'vgaVideoChipRec' and 'vgaHWRec' 117 data structures 118 vgaHW.c Contains the generic-VGA-register handling 119 functions vgaHWInit(), vgaHWSave() and 120 vgaHWRestore(). 121 drivers/ Contains the SVGA driver subdirectories. 122 Each contains an Imakefile, a .c file for 123 the driver, and a .s file for the bank- 124 switching functions. 125 vga2/ The monochrome server directories. Most of 126 the files are linked from vga256, and the 127 differences handled by conditional compilation. 128 drivers/ The SVGA driver subdirectories. The 'generic' 129 VGA driver is also located here. 130 VGADriverDoc/ This documentation and the stub driver. 131 132The Link Kit is usually installed in /usr/X386/lib/Server. The Link Kit 133contains everything that is needed to relink the server. It is possible 134to write a new driver and build a new server without having even the server 135source installed. 136 137Server/ 138 site.def Local configuration customization 139 include/ All of the include files listed under the 140 'common' directory above 141 drivers/ All of the SVGA drivers 142 vga.h 143 vga2/ 144 vga256/ 145 VGADriverDoc/ The directory with this documentation and 146 the stub driver. 'vgaHW.c' is also copied 147 here, for reference (it is not built as 148 part of the Link Kit). 149 1504 - Setting Up The Build Information 151------------------------------------ 152 This section describes the peripheral configuration and build steps that 153must be performed to set up for your new driver. The steps are the same 154whether you are building from the source tree of from the Link Kit; only 155the locations of the files is different. Here are the configuration steps 156that must be followed: 157 158 1) Choose the name for your driver subdirectory and data structures. 159 Since the current driver scheme allows (in fact, encourages) 160 putting drivers for multiple related chipsets in a single driver, 161 it is usually best to use the vendor name, rather than a chipset 162 version. The fact that older XFree86 drivers do not follow this 163 convention should not deter you from using it now - most of that 164 code was developed before the driver interface had been made 165 flexible and extensible. 166 167 For this documentation, we'll use chips from the SuperDuper Chips 168 vendor. Hence, we'll use 'sdc' for the name of the driver. 169 170 2) Decide whether your driver will support the color server, the 171 monochrome server, or both. For this documentation, we will 172 assume that both the color and monochrome servers will be 173 supported. If you intend to support only the color server, the 174 steps for the monochrome server can be ignored. If you intend 175 to support only the monochrome server, the steps for the color 176 server listed should be performed for the monochrome server, 177 and the monochrome steps ignored. Most of the existing drivers 178 support only the color or both servers; the "generic" driver is 179 the only driver (currently) that supports just the monochrome 180 server. 181 182 3) Create your driver directories: 183 184 - If you are working in the source tree, create the 185 following directories: 186 187 mit/server/ddx/x386/vga256/drivers/sdc 188 mit/server/ddx/x386/vga2/drivers/sdc 189 190 - If you are working in the Link Kit, create the 191 following directories: 192 193 /usr/X386/lib/Server/drivers/vga256/sdc 194 /usr/X386/lib/Server/drivers/vga2/sdc 195 196 4) Set up the Imakefile parameters to cause your driver to be 197 built: 198 199 - If you are working in the source tree: 200 a) Edit the file mit/config/x386.cf, and add 201 'sdc' to the list for the definitions for 202 'X386Vga256Drivers' and for 'X386Vga2Drivers'. 203 You should put 'sdc' at the end of the list, to 204 ensure that none of the other driver's probe 205 functions incorrectly detect the 'sdc' chipset 206 (note that 'generic' must be last for 207 'X386Vga2Drivers' - put 'sdc' just before it). 208 b) Edit the file mit/config/site.def, and add the 209 same entries in this file (this is just a comment 210 that shows the default values). 211 c) Edit mit/server/ddx/x386/LinkKit/site.def.LK, 212 and add the same entries in this file. This is 213 the prototype 'site.def' file that will be 214 installed in the Link Kit. 215 216 - If you are working in the Link Kit, edit the file 217 /usr/X386/lib/Server/site.def, and add 'sdc' to the 218 'X386Vga256Drivers' and 'X386Vga2Drivers' definitions 219 as described in (a) above. 220 221 5) Now copy the prototype files into your new directories: 222 223 - If you are working in the source tree, copy the 'stub' 224 files as follows: 225 226 Imakefile.stub => 227 mit/server/ddx/x386/vga256/drivers/sdc/Imakefile 228 stub_driver.c => 229 mit/server/ddx/x386/vga256/drivers/sdc/sdc_driver.c 230 stub_bank.s => 231 mit/server/ddx/x386/vga256/drivers/sdc/sdc_bank.s 232 Imakefile.stub => 233 mit/server/ddx/x386/vga2/drivers/sdc/Imakefile 234 (then edit this Imakefile and make the changes 235 described in the comments). 236 237 - If you are working in the Link Kit, copy the 'stub' files 238 as follows: 239 240 Imakefile.stub => 241 /usr/X386/lib/Server/drivers/vga256/sdc/Imakefile 242 stub_driver.c => 243 /usr/X386/lib/Server/drivers/vga256/sdc/sdc_driver.c 244 stub_bank.s => 245 /usr/X386/lib/Server/drivers/vga256/sdc/sdc_bank.s 246 Imakefile.stub => 247 /usr/X386/lib/Server/drivers/vga2/sdc/Imakefile 248 (then edit this Imakefile and make the changes 249 described in the comments). 250 251 6) Edit each of the files you've just copied, and replace 'stub' 252 with 'sdc' and 'STUB' with 'SDC' wherever they appear. 253 254That's all the prep work needed. Now it's time to work on the actual driver. 255 2565 - The Bank-Switching Functions 257-------------------------------- 258 The normal VGA memory map is 64k starting at address 0xA0000. To access 259more than 64k of memory, SuperVGA chipsets implement "bank switching" - 260the high-order address bits are used to select the bank of memory in which 261operations will take place. The size and number of these banks varies, 262and will be spelled out in the chipset documentation. A chipset will 263have zero, one or two bank registers. Likely the ONLY case of zero bank 264registers is a generic VGA, and hence is not a concern. 265 266Note that some of the newer chipsets (e.g. Trident 8900CL, Cirrus) allow 267for a linear mapping of the video memory. While using such a scheme would 268improve the performance of the server, it is not currently supported. Hence 269there is no way to use such features for a new chipset. 270 271Most SVGA chipsets have two bank registers. This is the most desirable 272structure (if any banking structure can be called "desirable"), because 273data can be moved from one area of the screen to another with a simple 274'mov' instruction. There are two forms of dual-banking - one where the 275two bank operations define a read-only bank and a write-only bank, and 276one with two read/write windows. With the first form, the entire SVGA 277memory window is used for both read a write operations, and the two 278bank registers determine which bank is actually used (e.g. ET3000, ET4000). 279With the second form, the SVGA memory window is split into two read/write 280banks, with each bank pointer being used to control one window. In 281this case, one window is used for read operations and the other for write 282operations (e.g. PVGA1/Western Digital, Cirrus). 283 284A chipset that has a single bank register uses that one bank for both 285read and write access. This is problematic, because copying information 286from one part of the screen to another requires that the data be read in, 287stored, and then written out. Fortunately, the server is able to handle 288both one-bank and two-bank chipsets; the determination of behavior is 289defined by an entry in the driver data structure described below. 290 291A driver requires that three assembly-language functions be written, in 292the file 'sdc_bank.s'. These functions set the read bank - SDCSetRead(), 293the write bank - SDCSetWrite(), and set both banks - SDCSetReadWrite(). 294For a chipset with only one bank, all three will be declared as entry points 295to the same function (see the "tvga8900" driver for an example). 296 297The functions are fairly simple - the bank number is passed to the function 298in register %al. The function will shift, bitmask, etc - whatever is 299required to put the bank number into the correct form - and then write 300it to the correct I/O port. For chipsets where the two banks are read-only 301and write-only, the SetReadWrite() function will have to do this twice - once 302for each bank. For chipsets with two independent read/write windows, the 303SetReadWrite() function should use the same bank as the SetWrite() function. 304 305A special note - these functions MUST be written in the macroized assembler 306format defined in the header file "assyntax.h". This will ensure that 307the correct assembler code will be generated, regardless of OS. This 308macroized format currently supports USL, GNU, and Intel assembler formats. 309 310That's all there is to the banking functions. Usually the chipset reference 311will give examples of this code; if not, it is not difficult to figure out, 312especially using the other drivers as examples. 313 3146 - The Driver Itself 315--------------------- 316 Now it's time to get down to the real work - writing the major driver 317functions in the files sdc_driver.c. First, an overview of what the 318responsibilities of the driver are: 319 320 1) Provide a chipset-descriptor data structure to the server. This 321 data structure contains pointers to the driver functions and 322 some data-structure initialization as well. 323 2) Provide a driver-local data structure to hold the contents of 324 the chipset registers. This data structure will contain a 325 generic part and a driver-specific part. It is used to save the 326 initial chipset state, and is initialized by the driver to put 327 the chipset into different modes. 328 3) Provide an identification function that the server will call to 329 list the chipsets that the driver is capable of supporting. 330 4) Provide a probe function that will identify this chipset as 331 different from all others, and return a positive response if 332 the chipset this driver supports is installed, and a negative 333 response otherwise. 334 5) Provide a function to select dot-clocks available on the board. 335 6) Provide functions to save, restore, and initialize the driver- 336 local data structure. 337 7) Provide a function to set the starting address for display in 338 the video memory. This implements the virtual-screen for the 339 server. 340 8) Perhaps provide a function for use during VT-switching. 341 342Before stepping through the driver file in detail, here are some important 343issues: 344 345 1) If your driver supports both the color and monochrome servers, 346 you should take care of both cases in the same file. Most things 347 are the same - you can differentiate between the two with the 348 MONOVGA #define. 349 2) The color server uses the SVGA's 8-bit packed-pixel mode. The 350 monochrome server uses the VGA's 16-color mode (4 bit-planes). 351 Only one plane is enabled, yielding the monochrome. 352 3) It is possible for you to define your monochrome driver so that 353 no bank-switching is done. This is not particularly desirable, 354 as it yields only 64k of viewing area. 355 356Keeping these things in mind, you need to find the registers from your 357SVGA chipset that control the desired features. In particular, registers 358that control: 359 360 1) Clock select bits. The two low-order bits are part of the 361 standard Miscellaneous Output Register; most SVGA chipsets 362 will include 1 or 2 more bits, allowing the use of 8 or 16 363 discrete clocks. 364 2) Bank selection. The SVGA chipset will have one or two registers 365 that control read/write bank selection. 366 3) CRTC extensions. The standard VGA registers don't have enough 367 bits to address large displays. So the SVGA chipsets have 368 extension bits. 369 4) Interlaced mode. Standard VGA does not support interlaced 370 displays. So the SVGA chipset will have a bit somewhere to 371 control interlaced mode. Some chipsets require additional 372 registers to be set up to control interlaced mode 373 5) Starting address. The standard VGA only has 16 bits in which 374 to specify the starting address for the display. This restricts 375 the screen size usable by the virtual screen feature. The SVGA 376 chipset will usually provide one or more extension bits. 377 6) Lock registers. Many SVGA chipset prevent modification of 378 extended registers unless the registers are first "unlocked". 379 You will need to disable protection of any registers you will 380 need for other purposes. 381 7) Any other facilities. Some chipset may, for example, require 382 that certain bits be set before you can access extended VGA 383 memory (beyond the IBM-standard 256k). Or other facilities; 384 read through all of the extended register descriptions and see 385 if anything important leaps out at you. 386 387If you are fortunate, the chipset vendor will include in the databook some 388tables of register settings for various BIOS modes. You can learn a lot 389about what manipulations you must do by looking at the various BIOS modes. 390 3916a - Multiple Chipsets And Options 392---------------------------------- 393 It is possible, and in fact desirable, to have a single driver support 394multiple chipsets from the same vendor. If there are multiple supported 395chipsets, then you would have a series of #define's for them, and a 396variable 'SDCchipset', which would be used throughout the driver when 397distinctions must be made. See the Trident and PVGA1/WD drivers for 398examples (the Tseng ET3000 and ET4000 are counter-examples - these were 399implemented before the driver interface allowed for multiple chipsets, so 400this example should NOT be followed). Note that you should only distinguish 401versions when your driver needs to do things differently for them. For 402example, suppose the SDC driver supports the SDC-1a, SDC-1b, and SDC-2 403chipsets. The -1a and -1b are essentially the same, but different from the 404-2 chipset. Your driver should support the -1 and -2 chipsets, and not 405distinguish between the -1a and -1a. This will simplify things for the 406end user. 407 408In cases where you want to give the user control of driver behavior, or 409there are things that cannot be determined without user intervention, you 410should use "option" flags. Say that board vendors that use the SDC 411chipsets have the option of providing 8 or 16 clocks. There's no way you 412can determine this from the chipset probe, so you provide an option flag to 413let the user select the behavior from the Xconfig file. The option flags are 414defined in the file "xf86_option.h". You should look to see if there is 415already a flag that can be reused. If so, use it in your driver. If not, 416add a new #define, and define the string->symbol mapping in the table in 417that file. To see how option flags are used, look at the ET4000, 418PVGA1/WD, and Trident drivers. 419 4206b - Data Structures 421-------------------- 422 Once you have an understanding of what is needed from the above description, 423it is time to fill in the driver data structures. First we will deal with 424the 'vgaSDCRec' structure. This data structure is the driver-local structure 425that holds the SVGA state information. The first entry in this data structure 426is ALWAYS 'vgaHWRec std'. This piece holds the generic VGA portion of the 427information. After that, you will have one 'unsigned char' field for each 428register that will be manipulated by your driver. That's all there is to 429this data structure. 430 431Next you must initialize the 'SDC' structure (type 'vgaVideoChipRec'). This 432is the global structure that identifies your driver to the server. Its name 433MUST be 'SDC', in all caps - i.e. it must match the directory name for your 434driver. This is required so that the Link Kit reconfiguration can identify 435all of the requisite directories and global data structures. 436 437The first section of this structure simply holds pointers to the driver 438functions. 439 440Next, you must initialize the information about how your chipset does 441bank switching. The following fields must be filled in: 442 443 1) ChipMapSize - the amount of memory that must be mapped into 444 the server's address space. This is almost always 64k (from 445 0xA0000 to 0xAFFFF). Some chipsets use a 128k map (from 446 0xA0000 to 0xBFFFF). If your chipset gives an option, use the 447 64k window, as a 128k window rules out using a Hercules or 448 Monochrome Display Adapter card with the SVGA. 449 2) ChipSegmentSize - the size of each bank within the ChipMapSize 450 window. This is usually also 64k, however, some chipsets split 451 the mapped window into a read portion and a write portion (for 452 example the PVGA1/Western Digital chipsets). 453 3) ChipSegmentShift - the number of bits by which an address will 454 be shifted right to mask of the bank number. This is log-base-2 455 of ChipSegmentSize. 456 4) ChipSegmentMask - a bitmask used to mask off the address within 457 a given bank. This is (ChipSegmentSize-1). 458 5) ChipReadBottom,ChipReadTop - the addresses within the mapped 459 window in which read operations can be done. Usually 0, and 460 64k, respectively, except for those chipset that have separate 461 read and write windows. 462 6) ChipWriteBottom,ChipWriteTop - same as above, for write operations. 463 7) ChipUse2Banks - a boolean value for whether this chipset has one 464 or two bank registers. This is used to set up the screen-to-screen 465 operations properly. 466 467There are three more fields that must be filled in: 468 469 1) ChipInterlaceType - this is either VGA_NO_DIVIDE_VERT or 470 VGA_DIVIDE_VERT. Some chipsets require that the vertical timing 471 numbers be divided in half for interlaced modes. Setting this 472 flag will take care of that. 473 2) ChipOptionFlags - this should always be '{0,}' in the data 474 structure initialization. This is a bitfield that contains 475 the Option flags that are valid for this driver. The appropriate 476 bits are initialized at the end of the Probe function. 477 3) ChipRounding - this gets set to the multiple by which the 478 virtual width of the display must be rounded for the 256-color 479 server. This value is usually 8, but may be 4 or 16 for some 480 chipsets. 481 4826c - The Ident() function 483------------------------- 484 The Ident() function is a very simple function. The server will call 485this function repeatedly, until a NULL is returned, when printing out the 486list of configured drivers. The Ident() function should return a chipset 487name for a supported chipset. The function is passed a number which 488increments from 0 on each iteration. 489 4906d - The ClockSelect() function 491------------------------------- 492 The ClockSelect() function is used during clock probing (i.e. when no 493'Clocks' line is specified in the Xconfig file) to select the dot-clock 494indicated by the number passed in the parameter. The function should 495set the chipset's clock-select bits according to the passed-in number. 496Two dummy values will be passed in as well (CLK_REG_SAVE, CLK_SAVE_RESTORE). 497When CLK_REG_SAVE is passed, the function should save away copies of 498any registers that will be modified during clock selection. When 499CLK_REG_RESTORE is passed, the function should restore these registers. 500This ensure that the clock-probing cannot corrupt registers. 501 502This function should return FALSE if the passed-in index value is invalid 503or if the clock can't be set for some reason. 504 5056e - The Probe() function 506------------------------- 507 The Probe() function is perhaps the most important, and perhaps the 508least intuitive function in the driver. The Probe function is required 509to identify the chipset independent of all other chipsets. If the user 510has specified a 'Chipset' line in the Xconfig file, this is a simple 511string comparison check. Otherwise, you must use some other technique 512to figure out what chipset is installed. If you are lucky, the chipset 513will have an identification mechanism (ident/version registers, etc), and 514this will be documented in the databook. Otherwise, you will have to 515determine some scheme, using the reference materials listed below. 516 517The identification is often done by looking for particular patterns in 518register, or for the existence of certain extended registers. Or with 519some boards/chipsets, the requisite information can be obtained by reading 520the BIOS for certain signature strings. The best advise is to study the 521existing probe functions, and use the reference documentation. You 522must be certain that your probe is non-destructive - if you modify a 523register, it must be saved before, and restored after. 524 525Once the chipset is successfully identified, the Probe() function must 526do some other initializations: 527 528 1) If the user has not specified the 'VideoRam' parameter in the 529 Xconfig file, the amount of installed memory must be determined. 530 2) If the user has not specified the 'Clocks' parameter in the 531 Xconfig file, the values for the available dot-clocks must 532 be determined. This is done by calling the vgaGetClocks() 533 function, and passing it the number of clocks available and 534 a pointer to the ClockSelect() function. 535 3) It is recommended that the 'maxClock' field of the server's 536 'vga256InfoRec' structure be filled in with the maximum 537 dot-clock rate allowed for this chipset (specified in KHz). 538 If this is not filled in a probe time, a default (currently 539 90MHz) will be used. 540 4) The 'chipset' field of the server's 'vga256InfoRec' structure 541 must be initialized to the name of the installed chipset. 542 5) If the driver will be used with the monochrome server, the 543 'bankedMono' field of the server's 'vga256InfoRec' structure 544 must be set to indicate whether the monochrome driver supports 545 banking. 546 6) If any option flags are used by this driver, the 'ChipOptionFlags' 547 structure in the 'vgaVideoChipRec' must be initialized with the 548 allowed option flags using the OFLG_SET() macro. 549 5506f - The EnterLeave() function 551------------------------------ 552 The EnterLeave() function is called whenever the virtual console on which 553the server runs is entered or left (for OSs without virtual consoles, the 554function is called when the server starts and again when it exits). The 555purpose of this function is to enable and disable I/O permissions (for 556OSs where such is required), and to unlock and relock access to "protected" 557registers that the driver must manipulate. It is a fairly trivial function, 558and can be implemented by following the comments in the stub driver. 559 5606g - The Restore() function 561--------------------------- 562 The Restore() function is used for restoring a saved video state. Note 563that 'restore' is a bit of a misnomer - this function is used to both 564restore a saved state and to install a new one created by the server. The 565Restore() function must complete the following actions: 566 567 1) Ensure that Bank 0 is selected, and that any other state 568 information required prior to writing out a new state has been 569 set up. 570 2) Call vgaHWRestore() to restore the generic VGA portion of the 571 state information. This function is in the vgaHW.c file. 572 3) Restore the chipset-specific portion of the state information. 573 This may be done by simply writing out the register, or by 574 doing a read/modify/write cycle if only certain bits are to 575 be modified. Be sure to note the comment in the sample driver 576 about how to handle clock-select bits. 577 5786h - The Save() function 579------------------------ 580 The Save() function is used to extract the initial video state information 581when the server starts. The Save() function must complete the following 582actions: 583 584 1) Ensure that Bank 0 is selected. 585 2) Call vgaHWSave() to extract the generic VGA portion of the state 586 information. This function is in the vgaHW.c file. 587 3) Extract the chipset-specific portion of the state information. 588 5896i - The Init() function 590------------------------ 591 The Init() function is the second most important function in the driver 592(after the Probe() function). It is used to initialize a data structure 593for each of the defined display modes in the server. This function is 594required to initialize the entire 'vgaSDCRec' data structure with the 595information needed to put the SVGA chipset into the required state. The 596generic VGA portion of the structure is initialized with a call to 597vgaHWInit() (also located in vgaHW.c). 598 599Once the generic portion is initialized, the Init() function can override 600any of the generic register initialization, if necessary. All of the other 601fields are filled in with the correct initialization. The information 602about the particular mode being initialized is passed in the 'mode' 603parameter, a pointer to a 'DisplayModeRec' structure. This can be 604dereferenced to determine the needed parameters. 605 606If you only know how to initialize certain bits of the register, do that 607here, and make sure that the Restore() function does a read/modify/write 608to only manipulate those bits. Again, refer to the existing drivers 609for examples of what happens in this function. 610 6116j - The Adjust() function 612-------------------------- 613 The Adjust() function is another fairly basic function. It is called 614whenever the server needs to adjust the start of the displayed part of 615the video memory, due to scrolling of the virtual screen or when changing 616the displayed resolution. All it does is set the starting address on the 617chipset to match the specified coordinate. Follow the comments in the 618stub driver for details on how to implement it. 619 6206k - The SaveScreen() function 621------------------------------ 622 The SaveScreen() function is not needed by most chipsets. This function 623would only be required if the extended registers that your driver needs 624will be modified when a synchronous reset is performed on the SVGA chipset 625(your databook should tell you this). If you do NOT need this function, 626simply don't define it, and put 'NoopDDA' in its place in the vgaVideoChipRec 627structure initialization (NoopDDA is a generic-use empty function). 628 629If you DO need this function, it is fairly simple to do. It will be 630called twice - once before the reset, and again after. It will be passed 631a parameter of SS_START in the former case, and SS_FINISH in the latter. 632All that needs to be done is to save any registers that will be affected 633by the reset into static variables on the SS_START call, and then restore 634them on the SS_FINISH call. 635 6366l - The GetMode() function 637--------------------------- 638 The GetMode() function is not used as of XFree86 1.3; its place in the 639vgaVideoChipRec should be initialized to 'NoopDDA'. 640 641At some point in the future, this function will be used to enable the server 642and/or a standalone program using the server's driver libraries to do 643interactive video mode adjustments. This function will read the SVGA 644registers and fill in a DisplayModeRec structure with the current video 645mode. 646 6476m - The FbInit() function 648--------------------------- 649 The FbInit() function is required for drivers with accelerated graphics 650support. It is used to replace default cfb.banked functions with 651accelerated chip-specific versions. cfbLowlevFuncs is a struct containing 652a list of functions which can be replaced. This struct defined in 653cfbfuncs.h. Examples of FbInit() functions can be found in the et4000, 654pvga1 and cirrus drivers. 655 656If you do NOT need this function, simply don't define it, and put 'NoopDDA' 657in its place in the vgaVideoChipRec structure initialization. 658 6597 - Building The New Server 660--------------------------- 661 As in the setup work, the steps for building the server depend whether 662you are working in the source tree or in the Link Kit. Here are the 663steps for the initial build after installing your new driver files: 664 665 - If you are working in the source tree, follow these steps: 666 667 a) Go to mit/config, and enter 'make Makefiles'. 668 b) Go to mit/server, and enter 'make Makefile', then 669 'make Makefiles depend all' 670 671 - If you are working in the Link Kit, follow these steps: 672 673 a) Go to /usr/X386/lib/Server, and enter './mkmf' 674 b) In the same directory, enter 'make' 675 676To rebuild the server after the initial build (e.g. after making changes 677to your driver): 678 679 - If you are working in the source tree, follow these steps: 680 681 a) Go to the appropriate driver directory, and enter 682 'make'. 683 b) Go to mit/server, and enter 'make loadXF86_SVGA' 684 (to link the color server) or 'make loadXF86_Mono' 685 (to link the mono server). 686 687 - If you are working in the Link Kit, follow these steps: 688 689 a) Go to the appropriate driver directory, and enter 690 'make'. 691 b) Go to /usr/X386/lib/server, and enter 692 'make loadXF86_SVGA' (to link the color server) or 693 'make loadXF86_Mono' (to link the mono server). 694 6958 - Debugging 696------------- 697 Debugging a new driver can be a painful experience, unfortunately. It 698is likely that incorrect programming of the SVGA chipset can lock up your 699machine. More likely, however, is that the display will be lost, potentially 700requiring a reboot to correct. It is HIGHLY recommended that the server 701be run from an attached terminal or a network login. This is the only 702rational way in which a debugger can be used on the server. Attempting 703to use multiple VTs for debugging is basically a waste of time. 704 705Because of the potential for locking up the machine, it is a VERY good idea 706to remember to do a 'sync' or two before starting the server. In addition, 707any unnecessary filesystems should be unmounted while the debugging session 708is going on (to avoid having to run unnecessary fsck's). 709 710By default the server is built without debugging symbols. The server can 711grow VERY large with debugging enabled. It is very simple to rebuild 712your driver for debugging, though. Do the following: 713 714 1) Go to the driver directory. 715 2) Edit the Makefile. Look for the SECOND definition of 716 'CDEBUGFLAGS'. Change this definition to 717 718 CDEBUGFLAGS = -g -DNO_INLINE 719 720 (this will enable debugging symbols and disable inlining of 721 functions, which can make single-stepping a nightmare). 722 3) Remove the 'sdc_driver.o' file. 723 4) Now follow the steps above for rebuilding the server. 724 725 (Alternatively, instead of editing the Makefile, you can simply 726 do 'make CDEBUGFLAGS="-g -DNO_INLINE"' after removing the old 727 .o file, then rebuild the server as described above). 728 729This will give you a server with which you can set breakpoints in the driver 730functions and single-step them. If you are working in the source tree, 731and just learning about SVGA programming, it may be useful to rebuild 732vgaHW.c with debugging as well. 733 7349 - Advice 735---------- 736 I cannot stress this enough - study all available references, and the 737existing code, until you understand what is happening. Do this BEFORE you 738begin writing a driver. This will save you a massive amount of headache. 739Try to find a driver for a chipset that is similar to yours, if possible. 740Use this as an example, and perhaps derive your driver from it. 741 742Do not let the gloom-and-doom in the debugging section discourage you. 743While you will probably have problems initially (I still do), careful, 744deliberate debugging steps can bear fruit very quickly. It is likely 745that, given a good understanding of the chipset, a driver can be written 746and debugged in a day or two. For someone just learning about this kind 747of programming, a week is more reasonable. 748 74910 - Advanced Topics 750-------------------- 751 Newer chipsets are getting into two advanced areas: programmable clock 752generators, and accelerated capabilities (BitBlt, line drawing, HW cursor). 753These are new areas, and the formal interfaces to them are not yet defined. 754It is advised that you contact the XFree86 team and get involved with the 755development/beta-testing team if you need to be working in these areas. 756 75711 - References 758-------------- 7591) Programmer's Guide to the EGA and VGA Cards, 2nd ed. 760 Richard Ferraro 761 Addison-Wesley, 1990 762 ISBN 0-201-57025-4 763 (This is the bible of SVGA programming - it has a few errors, so watch out). 764 7652) vgadoc2.zip 766 Finn Thoegersen 767 (This is a collection of SVGA and other chipset documentation. It is 768 available on most MS-DOS/Windows related FTP archives, including wuarchive. 769 It is DOS/BIOS oriented, but is still extremely useful, especially for 770 developing probe functions). 771 77212 - Vendor Contact Information 773------------------------------- 774ATI Technologies (VGA-Wonder, Mach8, Mach32) 7753761 Victoria Park Ave 776Scarborough, Ontario 777Canada M1W 3S2 778(416) 756-0718 (sales) 779(416) 756-0711 (tech support) 780(416) 756-4951 (BBS) 781(416) 756-0720 (fax) 782 783Chips & Technologies 784??? 785 786Cirrus Logic (SVGA, Accelerators - CL-GD5426) 787(510) 623-8300 788 789Genoa Systems (GVGA) 79075 E. Trimble Road 791San Jose, CA 95131 792(408) 432-9090 (sales) 793(408) 432-8324 (tech support) 794 795Headland Technologies, Inc (Video-7 VGA 1024i, VRAM II) 79646221 Landing Parkway 797Fremont, CA 94538 798(415) 623-7857 799 800Oak Technology, Inc (OTI-067,OTI-077) 801139 Kifer Ct. 802Sunnyvale, CA 94086 803(408) 737-0888 804(408) 737-3838 (fax) 805 806S3 (911, 924, 801/805, 928) 807(408) 980-5400 808 809Trident Microsystems Inc (8800, 8900, 9000) 810205 Ravendale Dr 811Mountainside, CA 94043 812(415) 691-9211 813 814Tseng Labs Inc, 8156 Terry Drive 816Newtown, PA 18940 817(215) 968-0502 818 819Weitek (Power9000, 5186) 8201060 E. Arques Ave, 821Sunnyvale, CA 94086 822(408) 738-5765 823 824Western Digital 825(714) 932-4900 826 827$XFree86: mit/server/ddx/x386/VGADriverDoc/VGADriver.Doc,v 2.5 1993/10/08 15:55:11 dawes Exp $ 828