hw/xfree86/doc/ddxDesign.xml

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3  "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
   4  <!ENTITY % xorg-defs SYSTEM "defs.ent"> %xorg-defs;
   5  <!ENTITY % defs SYSTEM "/xserver/doc/xml/xserver.ent"> %defs;
   6  <!-- config file keyword markup -->
   7  <!-- specific config file keywords -->
   8  <!ENTITY k.device "<emphasis>Device</emphasis>">
   9  <!ENTITY k.monitor "<emphasis>Monitor</emphasis>">
  10  <!ENTITY k.display "<emphasis>Display</emphasis>">
  11  <!ENTITY k.inputdevice "<emphasis>InputDevice</emphasis>">
  12  <!ENTITY k.screen "<emphasis>Screen</emphasis>">
  13  <!ENTITY k.serverlayout "<emphasis>ServerLayout</emphasis>">
  14  <!ENTITY k.driver "<emphasis>Driver</emphasis>">
  15  <!ENTITY k.module "<emphasis>Module</emphasis>">
  16  <!ENTITY k.identifier "<emphasis>Identifier</emphasis>">
  17  <!ENTITY k.serverflags "<emphasis>ServerFlags</emphasis>">
  18 ] >
  19
  20 <article id="ddxDesign">
  21   <articleinfo>
  22
  23     <title>XFree86 DDX Design</title>
  24
  25     <authorgroup>
  26       <corpauthor>The XFree86 Project</corpauthor>
  27       <corpauthor>The X.Org Foundation</corpauthor>
  28
  29       <othercredit>
  30         <firstname>Jim</firstname><surname>Gettys</surname>
  31         <contrib>Updates for X11R6.7</contrib>
  32       </othercredit>
  33     </authorgroup>
  34
  35     <pubdate>&xserver.reldate;</pubdate>
  36     <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo>
  37     <releaseinfo>X Server Version &xserver.version;</releaseinfo>
  38
  39   </articleinfo>
  40
  41   <note><para>
  42 This document describes software undergoing continual evolution, and
  43 the interfaces described here are subject to change without notice.
  44 This document is intended to cover the interfaces as found in the
  45 xorg-server-&xserver.version; release, but is probably not completely
  46 in sync with the code base.
  47     </para></note>
  48
  49
  50   <sect1>
  51     <title>Preface</title>
  52
  53     <para>
  54 This document was originally the design spec for the DDX layer of the
  55 XFree86 4.0 X server.  The X.Org Foundation adopted the XFree86 4.4rc2
  56 version of that server as the basis of the Xorg server project, and has
  57 evolved the XFree86 DDX layer greatly since forking.   This document thus
  58 covers only the current implementation of the XFree86 DDX as found in the
  59 Xorg server &xserver.version; release, and no longer matches the XFree86
  60 server itself.
  61       </para>
  62
  63     <para>
  64 The XFree86 Project's broad design principles for XFree86 4.0 were:
  65       <itemizedlist>
  66         <listitem><para>keep it reasonable
  67             <itemizedlist>
  68               <listitem><para>We cannot rewrite the complete server
  69                 </para></listitem>
  70               <listitem><para>We don't want to re-invent the wheel
  71                 </para></listitem>
  72             </itemizedlist></para></listitem>
  73         <listitem><para>keep it modular
  74             <itemizedlist>
  75               <listitem><para>As many things as possible should go into modules
  76                 </para></listitem>
  77               <listitem><para>The basic loader binary should be minimal
  78                 </para></listitem>
  79               <listitem><para>A clean design with well defined layering is
  80                   important</para></listitem>
  81               <listitem><para>DDX specific global variables are a nono
  82                 </para></listitem>
  83               <listitem><para>The structure should be flexible enough to allow
  84                   future extensions</para></listitem>
  85               <listitem><para>The structure should minimize duplication of
  86                   common code</para></listitem>
  87             </itemizedlist></para></listitem>
  88         <listitem><para>keep important features in mind
  89             <itemizedlist>
  90               <listitem><para>multiple screens, including multiple instances
  91                   of drivers</para></listitem>
  92               <listitem><para>mixing different color depths and visuals on
  93                   different and ideally even on the same screen
  94                 </para></listitem>
  95               <listitem><para>better control of the PCI device used
  96                 </para></listitem>
  97               <listitem><para>better config file parser</para></listitem>
  98               <listitem><para>get rid of all VGA compatibility assumptions
  99                 </para></listitem>
 100             </itemizedlist></para></listitem>
 101       </itemizedlist>
 102     </para>
 103
 104     <para>
 105 While the XFree86 project had a goal of avoiding changes to the DIX
 106 layer unless they found major deficiencies there, to avoid divergence from
 107 the X.Org sample implementation they were integrating changes from, the
 108 X.Org developers now maintain both sides, and make changes where they are
 109 most appropriate.   This document concentrates on the XFree86 DDX layer used
 110 in the Xorg server itself (the code found in <filename>hw/xfree86</filename>
 111 in the source tree), and developers will also want to refer to the
 112 <filename>Xserver-spec</filename> documentation that covers the DIX layer
 113 routines common to all the X servers in the sample implementation.
 114     </para>
 115   </sect1>
 116
 117   <sect1>
 118     <title>The xorg.conf File</title>
 119
 120     <para>
 121 The xorg.conf file format is based on the XF86Config format from XFree86 4.4,
 122 which is in turn similar to the old XFree86 3.x XF86Config format, with the
 123 following changes:
 124     </para>
 125
 126     <sect2>
 127       <title>&k.device; section</title>
 128
 129       <para>
 130     The &k.device; sections are similar to what they used to be, and
 131     describe hardware-specific information for a single video card.
 132     &k.device;
 133     Some new keywords are added:
 134
 135
 136         <variablelist>
 137           <varlistentry><term>Driver "drivername"</term>
 138             <listitem><para>
 139         Specifies the name of the driver to be used for the card.  This
 140         is mandatory.
 141               </para></listitem></varlistentry>
 142           <varlistentry><term>BusID "busslot"</term>
 143             <listitem><para>
 144         Specifies uniquely the location of the card on the bus.  The
 145         purpose is to identify particular cards in a multi-headed
 146         configuration.  The format of the argument is intentionally
 147         vague, and may be architecture dependent.  For a PCI bus, it
 148         is something like "bus:slot:func".
 149               </para></listitem></varlistentry>
 150         </variablelist>
 151       </para>
 152
 153       <para>
 154     A &k.device; section is considered <quote>active</quote> if there is a reference
 155     to it in an active &k.screen; section.
 156       </para>
 157     </sect2>
 158
 159     <sect2>
 160       <title>&k.screen; section</title>
 161
 162       <para>
 163     The &k.screen; sections are similar to what they used to be.  They
 164     no longer have a &k.driver; keyword, but an &k.identifier; keyword
 165     is added.  (The &k.driver; keyword may be accepted in place of the
 166     &k.identifier; keyword for compatibility purposes.)  The identifier
 167     can be used to identify which screen is to be active when multiple
 168     &k.screen; sections are present.  It is possible to specify the active
 169     screen from the command line.  A default is chosen in the absence
 170     of one being specified.  A &k.screen; section is considered <quote>active</quote>
 171     if there is a reference to it either from the command line, or from
 172     an active &k.serverlayout; section.
 173       </para>
 174     </sect2>
 175
 176     <sect2>
 177       <title>&k.inputdevice; section</title>
 178
 179       <para>
 180     The &k.inputdevice; section is a new section that describes
 181     configuration information for input devices.  It replaces the old
 182     <emphasis>Keyboard</emphasis>, <emphasis>Pointer</emphasis> and <emphasis>XInput</emphasis>
 183     sections.  Like the &k.device; section, it has two mandatory keywords:
 184     &k.identifier; and &k.driver;.  For compatibility purposes the old
 185     <emphasis>Keyboard</emphasis> and <emphasis>Pointer</emphasis> sections are
 186     converted by the parser into &k.inputdevice; sections as follows:
 187
 188         <variablelist>
 189           <varlistentry><term><emphasis>Keyboard</emphasis></term>
 190             <listitem><literallayout>
 191              &k.identifier; "Implicit Core Keyboard"
 192              &k.driver; "kbd"
 193               </literallayout></listitem></varlistentry>
 194           <varlistentry><term><emphasis>Pointer</emphasis></term>
 195             <listitem><literallayout>
 196              &k.identifier; "Implicit Core Pointer"
 197              &k.driver; "mouse"
 198               </literallayout></listitem></varlistentry>
 199         </variablelist>
 200       </para>
 201
 202       <para>
 203     An &k.inputdevice; section is considered active if there is a
 204     reference to it in an active &k.serverlayout; section.  An
 205     &k.inputdevice; section may also be referenced implicitly if there
 206     is no &k.serverlayout; section, if the <option>-screen</option> command
 207     line options is used, or if the &k.serverlayout; section doesn't
 208     reference any &k.inputdevice; sections.  In this case, the first
 209     sections with drivers "kbd" and "mouse" are used as the core
 210     keyboard and pointer respectively.
 211       </para>
 212     </sect2>
 213
 214     <sect2>
 215       <title>&k.serverlayout; section</title>
 216
 217       <para>
 218     The &k.serverlayout; section is a new section that is used to identify
 219     which &k.screen; sections are to be used in a multi-headed configuration,
 220     and the relative layout of those screens.  It also identifies which
 221     &k.inputdevice; sections are to be used.  Each &k.serverlayout; section
 222     has an identifier, a list of &k.screen; section identifiers, and a list of
 223     &k.inputdevice; section identifiers.  &k.serverflags; options may also be
 224     included in a &k.serverlayout; section, making it possible to override
 225     the global values in the &k.serverflags; section.
 226       </para>
 227
 228       <para>
 229     A &k.serverlayout; section can be made active by being referenced on
 230     the command line.  In the absence of this, a default will be chosen
 231     (the first one found).  The screen names may optionally be followed
 232     by a number specifying the preferred screen number, and optionally
 233     by information specifying the physical positioning of the screen,
 234     either in absolute terms or relative to another screen (or screens).
 235     When no screen number is specified, they are numbered according to
 236     the order in which they are listed.  The old (now obsolete) method
 237     of providing the positioning information is to give the names of
 238     the four adjacent screens.  The order of these is top, bottom, left,
 239     right.  Here is an example of a &k.serverlayout; section for two
 240     screens using the old method, with the second located to the right
 241     of the first:
 242
 243         <programlisting>
 244       Section "ServerLayout"
 245         Identifier "Main Layout"
 246         Screen     0 "Screen 1" ""  ""  ""  "Screen 2"
 247         Screen     1 "Screen 2"
 248         Screen     "Screen 3"
 249       EndSection
 250         </programlisting>
 251       </para>
 252
 253       <para>
 254     The preferred way of specifying the layout is to explicitly specify
 255     the screen's location in absolute terms or relative to another
 256     screen.
 257       </para>
 258
 259       <para>
 260     In the absolute case, the upper left corner's coordinates are given
 261     after the <emphasis>Absolute</emphasis> keyword.  If the coordinates are
 262     omitted, a value of <code>(0,0)</code> is assumed.  An example
 263     of absolute positioning follows:
 264
 265         <programlisting>
 266       Section "ServerLayout"
 267         Identifier "Main Layout"
 268         Screen     0 "Screen 1" Absolute 0 0
 269         Screen     1 "Screen 2" Absolute 1024 0
 270         Screen     "Screen 3" Absolute 2048 0
 271       EndSection
 272         </programlisting>
 273       </para>
 274
 275       <para>
 276     In the relative case, the position is specified by either using one of
 277     the following keywords followed by the name of the reference screen:
 278
 279         <simplelist type='vert' columns='1'>
 280           <member><emphasis>RightOf</emphasis></member>
 281           <member><emphasis>LeftOf</emphasis></member>
 282           <member><emphasis>Above</emphasis></member>
 283           <member><emphasis>Below</emphasis></member>
 284           <member><emphasis>Relative</emphasis></member>
 285         </simplelist>
 286       </para>
 287
 288       <para>
 289     When the <emphasis>Relative</emphasis> keyword is used, the reference screen
 290     name is followed by the coordinates of the new screen's origin
 291     relative to reference screen.  The following example shows how to use
 292     some of the relative positioning options.
 293
 294         <programlisting>
 295       Section "ServerLayout"
 296         Identifier "Main Layout"
 297         Screen     0 "Screen 1"
 298         Screen     1 "Screen 2" RightOf "Screen 1"
 299         Screen     "Screen 3" Relative "Screen 1" 2048 0
 300       EndSection
 301         </programlisting>
 302       </para>
 303     </sect2>
 304
 305     <sect2>
 306       <title>Options</title>
 307
 308       <para>
 309     Options are used more extensively.  They may appear in most sections
 310     now.  Options related to drivers can be present in the &k.screen;,
 311     &k.device; and &k.monitor; sections and the &k.display; subsections.
 312     The order of precedence is &k.display;, &k.screen;, &k.monitor;,
 313     &k.device;.  Options have been extended to allow an optional value
 314     to be specified in addition to the option name.  For more details
 315     about options, see the <link linkend="options">Options</link> section
 316     for details.
 317       </para>
 318     </sect2>
 319   </sect1>
 320
 321   <sect1>
 322     <title>Driver Interface</title>
 323
 324     <para>
 325 The driver interface consists of a minimal set of entry points that are
 326 required based on the external events that the driver must react to.
 327 No non-essential structure is imposed on the way they are used beyond
 328 that.  This is a significant difference compared with the old design.
 329     </para>
 330
 331     <para>
 332 The entry points for drawing operations are already taken care of by
 333 the framebuffer code.  Extensions and enhancements to framebuffer code
 334 are outside the scope of this document.
 335     </para>
 336
 337     <para>
 338 This approach to the driver interface provides good flexibility, but does
 339 increase the complexity of drivers.  To help address this, the XFree86
 340 common layer provides a set of <quote>helper</quote> functions to take care of things
 341 that most drivers need.  These helpers help minimise the amount of code
 342 duplication between drivers.  The use of helper functions by drivers is
 343 however optional, though encouraged.  The basic philosophy behind the
 344 helper functions is that they should be useful to many drivers, that
 345 they should balance this against the complexity of their interface.  It
 346 is inevitable that some drivers may find some helpers unsuitable and
 347 need to provide their own code.
 348     </para>
 349
 350     <para>
 351 Events that a driver needs to react to are:
 352
 353       <variablelist>
 354         <varlistentry><term>ScreenInit</term>
 355
 356           <listitem><para>
 357      An initialisation function is called from the DIX layer for each
 358      screen at the start of each server generation.
 359             </para></listitem></varlistentry>
 360
 361         <varlistentry><term>Enter VT</term>
 362
 363           <listitem><para>
 364      The server takes control of the console.
 365             </para></listitem></varlistentry>
 366
 367         <varlistentry><term>Leave VT</term>
 368
 369           <listitem><para>
 370      The server releases control of the console.
 371             </para></listitem></varlistentry>
 372
 373         <varlistentry><term>Mode Switch</term>
 374
 375           <listitem><para>
 376      Change video mode.
 377             </para></listitem></varlistentry>
 378
 379         <varlistentry><term>ViewPort change</term>
 380
 381           <listitem><para>
 382      Change the origin of the physical view port.
 383             </para></listitem></varlistentry>
 384
 385         <varlistentry><term>ScreenSaver state change</term>
 386
 387           <listitem><para>
 388      Screen saver activation/deactivation.
 389             </para></listitem></varlistentry>
 390
 391         <varlistentry><term>CloseScreen</term>
 392
 393           <listitem><para>
 394      A close screen function is called from the DIX layer for each screen
 395      at the end of each server generation.
 396             </para></listitem></varlistentry>
 397       </variablelist>
 398     </para>
 399
 400
 401     <para>
 402 In addition to these events, the following functions are required by
 403 the XFree86 common layer:
 404
 405       <variablelist>
 406         <varlistentry><term>Identify</term>
 407
 408           <listitem><para>
 409      Print a driver identifying message.
 410             </para></listitem></varlistentry>
 411
 412         <varlistentry><term>Probe</term>
 413
 414           <listitem><para>
 415      This is how a driver identifies if there is any hardware present that
 416      it knows how to drive.
 417             </para></listitem></varlistentry>
 418
 419         <varlistentry><term>PreInit</term>
 420
 421           <listitem><para>
 422      Process information from the xorg.conf file, determine the
 423      full characteristics of the hardware, and determine if a valid
 424      configuration is present.
 425             </para></listitem></varlistentry>
 426       </variablelist>
 427     </para>
 428
 429     <para>
 430 The VidMode extension also requires:
 431
 432       <variablelist>
 433         <varlistentry><term>ValidMode</term>
 434
 435           <listitem><para>
 436      Identify if a new mode is usable with the current configuration.
 437      The PreInit function (and/or helpers it calls) may also make use
 438      of the ValidMode function or something similar.
 439             </para></listitem></varlistentry>
 440       </variablelist>
 441     </para>
 442
 443
 444     <para>
 445 Other extensions may require other entry points.  The drivers will
 446 inform the common layer of these in such cases.
 447     </para>
 448   </sect1>
 449
 450   <sect1>
 451     <title>Resource Access Control Introduction</title>
 452
 453     <para>
 454 Graphics devices are accessed through ranges in I/O or memory space.
 455 While most modern graphics devices allow relocation of such ranges many
 456 of them still require the use of well established interfaces such as
 457 VGA memory and IO ranges or 8514/A IO ranges.  With modern buses (like
 458 PCI) it is possible for multiple video devices to share access to these
 459 resources.  The RAC (Resource Access Control) subsystem provides a
 460 mechanism for this.
 461     </para>
 462
 463     <sect2>
 464       <title>Terms and Definitions</title>
 465
 466       <sect3>
 467         <title>Bus</title>
 468
 469         <para>
 470     <quote>Bus</quote> is ambiguous as it is used for different things: it may refer
 471     to physical incompatible extension connectors in a computer system.
 472     The RAC system knows two such systems: The ISA bus and the PCI bus.
 473     (On the software level EISA, MCA and VL buses are currently treated
 474     like ISA buses).  <quote>Bus</quote> may also refer to logically different
 475     entities on a single bus system which are connected via bridges.  A
 476     PCI system may have several distinct PCI buses connecting each other
 477     by PCI-PCI bridges or to the host CPU by HOST-PCI bridges.
 478         </para>
 479
 480         <para>
 481     Systems that host more than one bus system link these together using
 482     bridges.  Bridges are a concern to RAC as they might block or pass
 483     specific resources.  PCI-PCI bridges may be set up to pass VGA
 484     resources to the secondary bus.  PCI-ISA buses pass any resources not
 485     decoded on the primary PCI bus to the ISA bus.  This way VGA resources
 486     (although exclusive on the ISA bus) can be shared by ISA and PCI
 487     cards.  Currently HOST-PCI bridges are not yet handled by RAC as they
 488     require specific drivers.
 489         </para>
 490       </sect3>
 491
 492       <sect3>
 493         <title>Entity</title>
 494
 495         <para>
 496     The smallest independently addressable unit on a system bus is
 497     referred to as an entity.  So far we know ISA and PCI entities.  PCI
 498     entities can be located on the PCI bus by an unique ID consisting of
 499     the bus, card and function number.
 500         </para>
 501       </sect3>
 502
 503       <sect3>
 504         <title>Resource</title>
 505
 506         <para>
 507     <quote>Resource</quote> refers to a range of memory or I/O addresses an entity
 508     can decode.
 509         </para>
 510
 511         <para>
 512     If a device is capable of disabling this decoding the resource is
 513     called sharable.  For PCI devices a generic method is provided to
 514     control resource decoding.  Other devices will have to provide a
 515     device specific function to control decoding.
 516         </para>
 517
 518         <para>
 519     If the entity is capable of decoding this range at a different
 520     location this resource is considered relocatable.
 521         </para>
 522
 523         <para>
 524     Resources which start at a specific address and occupy a single
 525     continuous range are called block resources.
 526         </para>
 527
 528         <para>
 529     Alternatively resource addresses can be decoded in a way that they
 530     satisfy the conditions:
 531           <programlisting>
 532                     address &amp; mask == base
 533           </programlisting>
 534     and
 535           <programlisting>
 536                        base &amp; mask == base
 537           </programlisting>
 538     Resources addressed in such a way are called sparse resources.
 539         </para>
 540
 541       </sect3>
 542
 543       <sect3>
 544         <title>Server States</title>
 545
 546         <para>
 547     The resource access control system knows two server states: the
 548     SETUP and the OPERATING state.  The SETUP state is entered whenever
 549     a mode change takes place or the server exits or does VT switching.
 550     During this state all entity resources are under resource access
 551     control.  During OPERATING state only those entities are controlled
 552     which actually have shared resources that conflict with others.
 553         </para>
 554       </sect3>
 555     </sect2>
 556   </sect1>
 557
 558   <sect1>
 559     <title>Control Flow in the Server and Mandatory Driver Functions</title>
 560
 561     <para>
 562 At the start of each server generation, <function>main()</function>
 563 (<filename>dix/main.c</filename>) calls the DDX function
 564 <function>InitOutput()</function>.  This is the first place that the DDX gets
 565 control.  <function>InitOutput()</function> is expected to fill in the global
 566 <structname>screenInfo</structname> struct, and one
 567 <structfield>screenInfo.screen[]</structfield> entry for each screen present.
 568 Here is what <function>InitOutput()</function> does:
 569     </para>
 570
 571     <sect2>
 572       <title>Parse the xorg.conf file</title>
 573
 574       <para>
 575     This is done at the start of the first server generation only.
 576       </para>
 577
 578       <para>
 579     The xorg.conf file is read in full, and the resulting information
 580     stored in data structures.  None of the parsed information is
 581     processed at this point.  The parser data structures are opaque to
 582     the video drivers and to most of the common layer code.
 583       </para>
 584
 585       <para>
 586     The entire file is parsed first to remove any section ordering
 587     requirements.
 588       </para>
 589     </sect2>
 590
 591
 592     <sect2>
 593       <title>Initial processing of parsed information and command line options
 594       </title>
 595
 596       <para>
 597     This is done at the start of the first server generation only.
 598       </para>
 599
 600       <para>
 601     The initial processing is to determine paths like the
 602     <emphasis>ModulePath</emphasis>, etc, and to determine which &k.serverlayout;,
 603     &k.screen; and &k.device; sections are active.
 604       </para>
 605     </sect2>
 606
 607
 608     <sect2>
 609       <title>Enable port I/O access</title>
 610
 611       <para>
 612     Port I/O access is controlled from the XFree86 common layer, and is
 613     <quote>all or nothing</quote>.  It is enabled prior to calling driver probes, at
 614     the start of subsequent server generations, and when VT switching
 615     back to the Xserver.  It is disabled at the end of server generations,
 616     and when VT switching away from the Xserver.
 617       </para>
 618
 619       <para>
 620     The implementation details of this may vary on different platforms.
 621       </para>
 622     </sect2>
 623
 624
 625     <sect2>
 626       <title>General bus probe</title>
 627
 628       <para>
 629     This is done at the start of the first server generation only.
 630       </para>
 631
 632       <para>
 633     In the case of ix86 machines, this will be a general PCI probe.
 634     The full information obtained here will be available to the drivers.
 635     This information persists for the life of the Xserver.  In the PCI
 636     case, the PCI information for all video cards found is available by
 637     calling <function>xf86GetPciVideoInfo()</function>.
 638       </para>
 639
 640       <blockquote><para>
 641           <programlisting>
 642     pciVideoPtr *xf86GetPciVideoInfo(void);
 643           </programlisting>
 644           <blockquote><para>
 645         returns a pointer to a list of pointers to
 646         <structname>pciVideoRec</structname> entries, of which there is one for
 647         each detected PCI video card.  The list is terminated with a
 648         <constant>NULL</constant> pointer.  If no PCI video cards were
 649         detected, the return value is <constant>NULL</constant>.
 650
 651             </para></blockquote>
 652         </para></blockquote>
 653
 654       <para>
 655     After the bus probe, the resource broker is initialised.
 656       </para>
 657     </sect2>
 658
 659
 660     <sect2>
 661       <title>Load initial set of modules</title>
 662
 663       <para>
 664     This is done at the start of the first server generation only.
 665       </para>
 666
 667       <para>
 668     The next set of modules loaded are those specified explicitly in the
 669     &k.module; section of the config file.
 670       </para>
 671
 672       <para>
 673     The final set of initial modules are the driver modules referenced
 674     by the active &k.device; and &k.inputdevice; sections in the config
 675     file.  Each of these modules is loaded exactly once.
 676       </para>
 677     </sect2>
 678
 679
 680     <sect2>
 681       <title>Register Video and Input Drivers</title>
 682
 683       <para>
 684     This is done at the start of the first server generation only.
 685       </para>
 686
 687       <para>
 688     When a driver module is loaded, the loader calls its
 689     <function>Setup</function> function.  For video drivers, this function
 690     calls <function>xf86AddDriver()</function> to register the driver's
 691     <structname>DriverRec</structname>, which contains a small set of essential
 692     details and driver entry points required during the early phase of
 693     <function>InitOutput()</function>.  <function>xf86AddDriver()</function>
 694     adds it to the global <varname>xf86DriverList[]</varname> array.
 695       </para>
 696
 697       <para>
 698     The <structname>DriverRec</structname> contains the driver canonical name,
 699     the <function>Identify()</function>,
 700     <function>Probe()</function> and <function>AvailableOptions()</function>
 701     function entry points as well as a pointer
 702     to the driver's module (as returned from the loader when the driver
 703     was loaded) and a reference count which keeps track of how many
 704     screens are using the driver.  The entry driver entry points are
 705     those required prior to the driver allocating and filling in its
 706     <structname>ScrnInfoRec</structname>.
 707       </para>
 708
 709       <para>
 710     For a static server, the <varname>xf86DriverList[]</varname> array is
 711     initialised at build time, and the loading of modules is not done.
 712       </para>
 713
 714       <para>
 715     A similar procedure is used for input drivers.  The input driver's
 716     <function>Setup</function> function calls
 717     <function>xf86AddInputDriver()</function> to register the driver's
 718     <structname>InputDriverRec</structname>, which contains a small set of
 719     essential details and driver entry points required during the early
 720     phase of <function>InitInput()</function>.
 721     <function>xf86AddInputDriver()</function> adds it to the global
 722     <varname>xf86InputDriverList[]</varname> array.  For a static server,
 723     the <varname>xf86InputDriverList[]</varname> array is initialised at
 724     build time.
 725       </para>
 726
 727       <para>
 728     Both the <varname>xf86DriverList[]</varname> and
 729     <varname>xf86InputDriverList[]</varname> arrays have been initialised
 730     by the end of this stage.
 731       </para>
 732
 733       <para>
 734     Once all the drivers are registered, their
 735     <function>ChipIdentify()</function> functions are called.
 736       </para>
 737
 738       <blockquote><para>
 739           <programlisting>
 740     void ChipIdentify(int flags);
 741           </programlisting>
 742           <blockquote><para>
 743       This is expected to print a message indicating the driver name,
 744       a short summary of what it supports, and a list of the chipset
 745       names that it supports.  It may use the xf86PrintChipsets() helper
 746       to do this.
 747             </para></blockquote>
 748         </para></blockquote>
 749
 750       <blockquote><para>
 751           <programlisting>
 752     void xf86PrintChipsets(const char *drvname, const char *drvmsg,
 753                            SymTabPtr chips);
 754           </programlisting>
 755           <blockquote><para>
 756       This function provides an easy way for a driver's ChipIdentify
 757       function to format the identification message.
 758             </para></blockquote>
 759         </para></blockquote>
 760     </sect2>
 761
 762     <sect2>
 763       <title>Initialise Access Control</title>
 764
 765       <para>
 766     This is done at the start of the first server generation only.
 767       </para>
 768
 769       <para>
 770     The Resource Access Control (RAC) subsystem is initialised before
 771     calling any driver functions that may access hardware.  All generic
 772     bus information is probed and saved (for restoration later).  All
 773     (shared resource) video devices are disabled at the generic bus
 774     level, and a probe is done to find the <quote>primary</quote> video device.  These
 775     devices remain disabled for the next step.
 776       </para>
 777     </sect2>
 778
 779
 780     <sect2 id="probe">
 781       <title>Video Driver Probe</title>
 782
 783       <para>
 784     This is done at the start of the first server generation only.  The
 785     <function>ChipProbe()</function> function of each registered video driver
 786     is called.
 787       </para>
 788
 789       <blockquote><para>
 790           <programlisting>
 791     Bool ChipProbe(DriverPtr drv, int flags);
 792           </programlisting>
 793           <blockquote><para>
 794       The purpose of this is to identify all instances of hardware
 795       supported by the driver.  The flags value is currently either 0,
 796       <constant>PROBE_DEFAULT</constant> or <constant>PROBE_DETECT</constant>.
 797       <constant>PROBE_DETECT</constant> is used if "-configure" or "-probe"
 798       command line arguments are given and indicates to the
 799       <function>Probe()</function> function that it should not configure the
 800       bus entities and that no xorg.conf information is available.
 801             </para>
 802
 803           <para>
 804       The probe must find the active device sections that match the
 805       driver by calling <function>xf86MatchDevice()</function>.  The number
 806       of matches found limits the maximum number of instances for this
 807       driver.  If no matches are found, the function should return
 808       <constant>FALSE</constant> immediately.
 809           </para>
 810
 811         <para>
 812       Devices that cannot be identified by using device-independent
 813       methods should be probed at this stage (keeping in mind that access
 814       to all resources that can be disabled in a device-independent way
 815       are disabled during this phase).  The probe must be a minimal
 816       probe.  It should just determine if there is a card present that
 817       the driver can drive.  It should use the least intrusive probe
 818       methods possible.  It must not do anything that is not essential,
 819       like probing for other details such as the amount of memory
 820       installed, etc.  It is recommended that the
 821       <function>xf86MatchPciInstances()</function> helper function be used
 822       for identifying matching PCI devices, and similarly the
 823       <function>xf86MatchIsaInstances()</function> for ISA (non-PCI) devices
 824       (see the <link linkend="rac">RAC</link> section).  These helpers also
 825       checks and claims the appropriate entity.  When not using the
 826       helper, that should be done with <function>xf86CheckPciSlot()</function>
 827       and <function>xf86ClaimPciSlot()</function> for PCI devices and
 828       <function>xf86ClaimIsaSlot()</function> for ISA devices (see the
 829       <link linkend="rac">RAC</link> section).
 830         </para>
 831
 832         <para>
 833       The probe must register all non-relocatable resources at this
 834       stage.  If a resource conflict is found between exclusive resources
 835       the driver will fail immediately.  This is usually best done with
 836       the <function>xf86ConfigPciEntity()</function> helper function
 837       for PCI and <function>xf86ConfigIsaEntity()</function> for ISA
 838       (see the <link linkend="rac">RAC</link> section).  It is possible to
 839       register some entity specific functions with those helpers.  When
 840       not using the helpers, the <function>xf86AddEntityToScreen()</function>
 841       <function>xf86ClaimFixedResources()</function> and
 842       <function>xf86SetEntityFuncs()</function> should be used instead (see
 843       the <link linkend="rac">RAC</link> section).
 844         </para>
 845
 846         <para>
 847       If a chipset is specified in an active device section which the
 848       driver considers relevant (ie it has no driver specified, or the
 849       driver specified matches the driver doing the probe), the Probe
 850       must return <constant>FALSE</constant> if the chipset doesn't match
 851       one supported by the driver.
 852         </para>
 853
 854         <para>
 855       If there are no active device sections that the driver considers
 856       relevant, it must return <constant>FALSE</constant>.
 857         </para>
 858
 859         <para>
 860       Allocate a <structname>ScrnInfoRec</structname> for each active instance of the
 861       hardware found, and fill in the basic information, including the
 862       other driver entry points.   This is best done with the
 863       <function>xf86ConfigIsaEntity()</function> helper function for ISA
 864       instances or <function>xf86ConfigPciEntity()</function> for PCI instances.
 865       These functions allocate a <structname>ScrnInfoRec</structname> for active
 866       entities. Optionally <function>xf86AllocateScreen()</function>
 867       function may also be used to allocate the <structname>ScrnInfoRec</structname>.
 868       Any of these functions take care of initialising fields to defined
 869       <quote>unused</quote> values.
 870         </para>
 871
 872         <para>
 873       Claim the entities for each instance of the hardware found.  This
 874       prevents other drivers from claiming the same hardware.
 875         </para>
 876
 877         <para>
 878       Must leave hardware in the same state it found it in, and must not
 879       do any hardware initialisation.
 880         </para>
 881
 882         <para>
 883       All detection can be overridden via the config file, and that
 884       parsed information is available to the driver at this stage.
 885         </para>
 886
 887         <para>
 888       Returns <constant>TRUE</constant> if one or more instances are found,
 889       and <constant>FALSE</constant> otherwise.
 890         </para>
 891
 892           </blockquote></para></blockquote>
 893
 894       <blockquote><para>
 895           <programlisting>
 896     int xf86MatchDevice(const char *drivername,
 897                         GDevPtr **driversectlist)
 898           </programlisting>
 899           <blockquote><para>
 900       This function takes the name of the driver and returns via
 901       <parameter>driversectlist</parameter> a list of device sections that
 902       match the driver name.  The function return value is the number
 903       of matches found.  If a fatal error is encountered the return
 904       value is <literal>-1</literal>.
 905             </para>
 906
 907             <para>
 908       The caller should use <function>xfree()</function> to free
 909       <parameter>*driversectlist</parameter> when it is no longer needed.
 910             </para>
 911
 912           </blockquote></para></blockquote>
 913
 914       <blockquote><para>
 915           <programlisting>
 916     ScrnInfoPtr xf86AllocateScreen(DriverPtr drv, int flags)
 917           </programlisting>
 918           <blockquote><para>
 919       This function allocates a new <structname>ScrnInfoRec</structname> in the
 920       <varname>xf86Screens[]</varname> array.  This function is normally
 921       called by the video driver <function>ChipProbe()</function> functions.
 922       The return value is a pointer to the newly allocated
 923       <structname>ScrnInfoRec</structname>.  The <structfield>scrnIndex</structfield>,
 924       <structfield>origIndex</structfield>, <structfield>module</structfield> and
 925       <structfield>drv</structfield> fields are initialised.  The reference count
 926       in <parameter>drv</parameter> is incremented.  The storage for any
 927       currently allocated <quote>privates</quote> pointers is also allocated and
 928       the <structfield>privates</structfield> field initialised (the privates data
 929       is of course not allocated or initialised).  This function never
 930       returns on failure.  If the allocation fails, the server exits
 931       with a fatal error.  The flags value is not currently used, and
 932       should be set to zero.
 933             </para></blockquote>
 934         </para></blockquote>
 935
 936       <para>
 937     At the completion of this, a list of <structname>ScrnInfoRecs</structname>
 938     have been allocated in the <varname>xf86Screens[]</varname> array, and
 939     the associated entities and fixed resources have been claimed.  The
 940     following <structname>ScrnInfoRec</structname> fields must be initialised at
 941     this point:
 942
 943         <literallayout>
 944           driverVersion
 945           driverName
 946           scrnIndex(*)
 947           origIndex(*)
 948           drv(*)
 949           module(*)
 950           name
 951           Probe
 952           PreInit
 953           ScreenInit
 954           EnterVT
 955           LeaveVT
 956           numEntities
 957           entityList
 958           access
 959         </literallayout>
 960
 961     <literal>(*)</literal> These are initialised when the <structname>ScrnInfoRec</structname>
 962     is allocated, and not explicitly by the driver.
 963       </para>
 964
 965       <para>
 966     The following <structname>ScrnInfoRec</structname> fields must be initialised
 967     if the driver is going to use them:
 968
 969         <literallayout>
 970           SwitchMode
 971           AdjustFrame
 972           FreeScreen
 973           ValidMode
 974         </literallayout>
 975       </para>
 976     </sect2>
 977
 978     <sect2>
 979       <title>Matching Screens</title>
 980
 981       <para>
 982     This is done at the start of the first server generation only.
 983       </para>
 984
 985       <para>
 986     After the Probe phase is finished, there will be some number of
 987     <structname>ScrnInfoRec</structname>s.  These are then matched with the active
 988     &k.screen; sections in the xorg.conf, and those not having an active
 989     &k.screen; section are deleted.  If the number of remaining screens
 990     is 0, <function>InitOutput()</function> sets
 991     <structfield>screenInfo.numScreens</structfield> to <constant>0</constant> and
 992     returns.
 993       </para>
 994
 995       <para>
 996     At this point the following fields of the <structname>ScrnInfoRec</structname>s
 997     must be initialised:
 998
 999         <literallayout>
1000           confScreen
1001         </literallayout>
1002       </para>
1003
1004     </sect2>
1005
1006     <sect2>
1007       <title>Allocate non-conflicting resources</title>
1008
1009       <para>
1010     This is done at the start of the first server generation only.
1011       </para>
1012
1013       <para>
1014     Before calling the drivers again, the resource information collected
1015     from the Probe phase is processed.  This includes checking the extent
1016     of PCI resources for the probed devices, and resolving any conflicts
1017     in the relocatable PCI resources.  It also reports conflicts, checks
1018     bus routing issues, and anything else that is needed to enable the
1019     entities for the next phase.
1020       </para>
1021
1022       <para>
1023     If any drivers registered an <function>EntityInit()</function> function
1024     during the Probe phase, then they are called here.
1025       </para>
1026
1027     </sect2>
1028
1029     <sect2>
1030       <title>Sort the Screens and pre-check Monitor Information</title>
1031
1032       <para>
1033     This is done at the start of the first server generation only.
1034       </para>
1035
1036       <para>
1037     The list of screens is sorted to match the ordering requested in the
1038     config file.
1039       </para>
1040
1041       <para>
1042     The list of modes for each active monitor is checked against the
1043     monitor's parameters.  Invalid modes are pruned.
1044       </para>
1045
1046     </sect2>
1047
1048     <sect2>
1049       <title>PreInit</title>
1050
1051       <para>
1052     This is done at the start of the first server generation only.
1053       </para>
1054
1055       <para>
1056     For each <structname>ScrnInfoRec</structname>, enable access to the screens entities and call
1057     the <function>ChipPreInit()</function> function.
1058       </para>
1059
1060       <blockquote><para>
1061           <programlisting>
1062     Bool ChipPreInit(ScrnInfoRec screen, int flags);
1063           </programlisting>
1064           <blockquote><para>
1065       The purpose of this function is to find out all the information
1066       required to determine if the configuration is usable, and to
1067       initialise those parts of the <structname>ScrnInfoRec</structname> that
1068       can be set once at the beginning of the first server generation.
1069             </para>
1070
1071             <para>
1072       The number of entities registered for the screen should be checked
1073       against the expected number (most drivers expect only one).  The
1074       entity information for each of them should be retrieved (with
1075       <function>xf86GetEntityInfo()</function>) and checked for the correct
1076       bus type and that none of the sharable resources registered during
1077       the Probe phase was rejected.
1078             </para>
1079
1080             <para>
1081       Access to resources for the entities that can be controlled in a
1082       device-independent way are enabled before this function is called.
1083       If the driver needs to access any resources that it has disabled
1084       in an <function>EntityInit()</function> function that it registered,
1085       then it may enable them here providing that it disables them before
1086       this function returns.
1087             </para>
1088
1089             <para>
1090       This includes probing for video memory, clocks, ramdac, and all
1091       other HW info that is needed.  It includes determining the
1092       depth/bpp/visual and related info.  It includes validating and
1093       determining the set of video modes that will be used (and anything
1094       that is required to determine that).
1095             </para>
1096
1097             <para>
1098       This information should be determined in the least intrusive way
1099       possible.  The state of the HW must remain unchanged by this
1100       function.  Although video memory (including MMIO) may be mapped
1101       within this function, it must be unmapped before returning.  Driver
1102       specific information should be stored in a structure hooked into
1103       the <structname>ScrnInfoRec</structname>'s <structfield>driverPrivate</structfield>
1104       field.  Any other modules which require persistent data (ie data
1105       that persists across server generations) should be initialised in
1106       this function, and they should allocate a <quote>privates</quote> index to
1107       hook their data into by calling
1108       <function>xf86AllocateScrnInfoPrivateIndex()</function>.  The <quote>privates</quote>
1109       data is persistent.
1110             </para>
1111
1112             <para>
1113       Helper functions for some of these things are provided at the
1114       XFree86 common level, and the driver can choose to make use of
1115       them.
1116             </para>
1117
1118             <para>
1119       All additional resources that the screen needs must be registered
1120       here.  This should be done with
1121       <function>xf86RegisterResources()</function>.  If some of the fixed
1122       resources registered in the Probe phase are not needed or not
1123       decoded by the hardware when in the OPERATING server state, their
1124       status should be updated with
1125       <function>xf86SetOperatingState()</function>.
1126             </para>
1127
1128             <para>
1129       Modules may be loaded at any point in this function, and all
1130       modules that the driver will need must be loaded before the end
1131       of this function.  Either the  <function>xf86LoadSubModule()</function>
1132       or the <function>xf86LoadDrvSubModule()</function> function should be
1133       used to load modules depending on whether a
1134       <structname>ScrnInfoRec</structname> has been set up. A driver may unload
1135       a module within this function if it was only needed temporarily,
1136       and the <function>xf86UnloadSubModule()</function> function should be used
1137       to do that.  Otherwise there is no need to explicitly unload modules
1138       because the loader takes care of module dependencies and will
1139       unload submodules automatically if/when the driver module is
1140       unloaded.
1141             </para>
1142
1143             <para>
1144       The bulk of the <structname>ScrnInfoRec</structname> fields should be filled
1145       out in this function.
1146             </para>
1147
1148             <para>
1149       <function>ChipPreInit()</function> returns <constant>FALSE</constant> when
1150       the configuration is unusable in some way (unsupported depth, no
1151       valid modes, not enough video memory, etc), and <constant>TRUE</constant>
1152       if it is usable.
1153             </para>
1154
1155             <para>
1156       It is expected that if the <function>ChipPreInit()</function> function
1157       returns <constant>TRUE</constant>, then the only reasons that subsequent
1158       stages in the driver might fail are lack or resources (like xalloc
1159       failures).  All other possible reasons for failure should be
1160       determined by the <function>ChipPreInit()</function> function.
1161             </para></blockquote>
1162         </para></blockquote>
1163
1164       <para>
1165     The <structname>ScrnInfoRec</structname>s for screens where the <function>ChipPreInit()</function> fails are removed.
1166     If none remain, <function>InitOutput()</function> sets <structfield>screenInfo.numScreens</structfield> to <constant>0</constant> and returns.
1167       </para>
1168
1169       <para>
1170     At this point, further fields of the <structname>ScrnInfoRec</structname>s would normally be
1171     filled in.  Most are not strictly mandatory, but many are required
1172     by other layers and/or helper functions that the driver may choose
1173     to use.  The documentation for those layers and helper functions
1174     indicates which they require.
1175       </para>
1176
1177       <para>
1178     The following fields of the <structname>ScrnInfoRec</structname>s should be filled in if the
1179     driver is going to use them:
1180
1181         <literallayout>
1182           monitor
1183           display
1184           depth
1185           pixmapBPP
1186           bitsPerPixel
1187           weight                (&gt;8bpp only)
1188           mask                  (&gt;8bpp only)
1189           offset                (&gt;8bpp only)
1190           rgbBits               (8bpp only)
1191           gamma
1192           defaultVisual
1193           maxHValue
1194           maxVValue
1195           virtualX
1196           virtualY
1197           displayWidth
1198           frameX0
1199           frameY0
1200           frameX1
1201           frameY1
1202           zoomLocked
1203           modePool
1204           modes
1205           currentMode
1206           progClock             (TRUE if clock is programmable)
1207           chipset
1208           ramdac
1209           clockchip
1210           numClocks             (if not programmable)
1211           clock[]               (if not programmable)
1212           videoRam
1213           biosBase
1214           memBase
1215           memClk
1216           driverPrivate
1217           chipID
1218           chipRev
1219         </literallayout>
1220       </para>
1221
1222       <blockquote><para>
1223           <programlisting>
1224     pointer xf86LoadSubModule(ScrnInfoPtr pScrn, const char *name);
1225       and
1226     pointer xf86LoadDrvSubModule(DriverPtr drv, const char *name);
1227           </programlisting>
1228           <blockquote><para>
1229       Load a module that a driver depends on.  This function loads the
1230       module <parameter>name</parameter> as a sub module of the driver.  The
1231       return value is a handle identifying the new module.  If the load
1232       fails, the return value will be <constant>NULL</constant>.  If a driver
1233       needs to explicitly unload a module it has loaded in this way,
1234       the return value must be saved and passed to
1235       <function>xf86UnloadSubModule()</function> when unloading.
1236
1237             </para></blockquote>
1238         </para></blockquote>
1239
1240       <blockquote><para>
1241           <programlisting>
1242     void xf86UnloadSubModule(pointer module);
1243           </programlisting>
1244           <blockquote><para>
1245       Unloads the module referenced by <parameter>module</parameter>.
1246       <parameter>module</parameter> should be a pointer returned previously
1247       by <function>xf86LoadSubModule()</function> or
1248       <function>xf86LoadDrvSubModule()</function> .
1249
1250             </para></blockquote>
1251         </para></blockquote>
1252     </sect2>
1253
1254     <sect2>
1255       <title>Cleaning up Unused Drivers</title>
1256
1257       <para>
1258     At this point it is known which screens will be in use, and which
1259     drivers are being used.  Unreferenced drivers (and modules they
1260     may have loaded) are unloaded here.
1261       </para>
1262
1263     </sect2>
1264
1265     <sect2>
1266       <title>Consistency Checks</title>
1267
1268       <para>
1269     The parameters that must be global to the server, like pixmap formats,
1270     bitmap bit order, bitmap scanline unit and image byte order are
1271     compared for each of the screens.  If a mismatch is found, the server
1272     exits with an appropriate message.
1273       </para>
1274
1275     </sect2>
1276
1277     <sect2>
1278       <title>Check if Resource Control is Needed</title>
1279
1280       <para>
1281     Determine if resource access control is needed.  This is the case
1282     if more than one screen is used.  If necessary the RAC wrapper module
1283     is loaded.
1284       </para>
1285     </sect2>
1286
1287     <sect2>
1288       <title>AddScreen (ScreenInit)</title>
1289
1290       <para>
1291     At this point, the valid screens are known.
1292     <function>AddScreen()</function> is called for each of them, passing
1293     <function>ChipScreenInit()</function> as the argument.
1294     <function>AddScreen()</function> is a DIX function that allocates a new
1295     <structfield>screenInfo.screen[]</structfield> entry (aka
1296     <varname>pScreen</varname>), and does some basic initialisation of it.
1297     It then calls the <function>ChipScreenInit()</function> function, with
1298     <parameter>pScreen</parameter> as one of its arguments.  If
1299     <function>ChipScreenInit()</function> returns <constant>FALSE</constant>,
1300     <function>AddScreen()</function> returns <constant>-1</constant>.  Otherwise
1301     it returns the index of the screen.  <function>AddScreen()</function>
1302     should only fail because of programming errors or failure to allocate
1303     resources (like memory).  All configuration problems should be
1304     detected BEFORE this point.
1305       </para>
1306
1307       <blockquote><para>
1308           <programlisting>
1309     Bool ChipScreenInit(ScreenPtr pScreen,
1310                         int argc, char **argv);
1311           </programlisting>
1312           <blockquote><para>
1313       This is called at the start of each server generation.
1314             </para>
1315
1316             <para>
1317       Fill in all of <parameter>pScreen</parameter>, possibly doing some of
1318       this by calling ScreenInit functions from other layers like mi,
1319       framebuffers (cfb, etc), and extensions.
1320             </para>
1321
1322             <para>
1323       Decide which operations need to be placed under resource access
1324       control.  The classes of operations are the frame buffer operations
1325       (<constant>RAC_FB</constant>), the pointer operations
1326       (<constant>RAC_CURSOR</constant>), the viewport change operations
1327       (<constant>RAC_VIEWPORT</constant>) and the colormap operations
1328       (<constant>RAC_COLORMAP</constant>).  Any operation that requires
1329       resources which might be disabled during OPERATING state should
1330       be set to use RAC.  This can be specified separately for memory
1331       and IO resources (the <structfield>racMemFlags</structfield> and
1332       <structfield>racIoFlags</structfield> fields of the <structname>ScrnInfoRec</structname>
1333       respectively).
1334             </para>
1335
1336             <para>
1337       Map any video memory or other memory regions.
1338             </para>
1339
1340             <para>
1341       Save the video card state.  Enough state must be saved so that
1342       the original state can later be restored.
1343             </para>
1344
1345             <para>
1346       Initialise the initial video mode.  The <structname>ScrnInfoRec</structname>'s
1347       <structfield>vtSema</structfield> field should be set to <constant>TRUE</constant>
1348       just prior to changing the video hardware's state.
1349
1350             </para></blockquote>
1351         </para></blockquote>
1352
1353
1354       <para>
1355     The <function>ChipScreenInit()</function> function (or functions from other
1356     layers that it calls) should allocate entries in the
1357     <structname>ScreenRec</structname>'s <structfield>devPrivates</structfield> area by
1358     calling <function>AllocateScreenPrivateIndex()</function> if it needs
1359     per-generation storage.  Since the <structname>ScreenRec</structname>'s
1360     <structfield>devPrivates</structfield> information is cleared for each server
1361     generation, this is the correct place to initialise it.
1362       </para>
1363
1364       <para>
1365     After <function>AddScreen()</function> has successfully returned, the
1366     following <structname>ScrnInfoRec</structname> fields are initialised:
1367
1368         <literallayout>
1369           pScreen
1370           racMemFlags
1371           racIoFlags
1372         </literallayout>
1373       </para>
1374
1375       <para>
1376     The <function>ChipScreenInit()</function> function should initialise the
1377     <structfield>CloseScreen</structfield> and <structfield>SaveScreen</structfield> fields
1378     of <parameter>pScreen</parameter>.  The old value of
1379     <structfield>pScreen-&gt;CloseScreen</structfield> should be saved as part of
1380     the driver's per-screen private data, allowing it to be called from
1381     <function>ChipCloseScreen()</function>.  This means that the existing
1382     <function>CloseScreen()</function> function is wrapped.
1383       </para>
1384     </sect2>
1385
1386     <sect2>
1387       <title>Finalising RAC Initialisation</title>
1388
1389       <para>
1390     After all the <function>ChipScreenInit()</function> functions have been
1391     called, each screen has registered its RAC requirements.  This
1392     information is used to determine which shared resources are requested
1393     by more than one driver and set the access functions accordingly.
1394     This is done following these rules:
1395
1396         <orderedlist>
1397           <listitem><para>
1398         The sharable resources registered by each entity are compared.
1399         If a resource is registered by more than one entity the entity
1400         will be marked to indicate that it needs to share this resources
1401         type (IO or MEM).
1402             </para></listitem>
1403
1404           <listitem><para>
1405         A resource marked <quote>disabled</quote> during OPERATING state will be
1406         ignored entirely.
1407             </para></listitem>
1408
1409           <listitem><para>
1410         A resource marked <quote>unused</quote> will only conflict with an overlapping
1411         resource of an other entity if the second is actually in use
1412         during OPERATING state.
1413             </para></listitem>
1414
1415           <listitem><para>
1416         If an <quote>unused</quote> resource was found to conflict but the entity
1417         does not use any other resource of this type the entire resource
1418         type will be disabled for that entity.
1419             </para></listitem>
1420         </orderedlist>
1421       </para>
1422
1423     </sect2>
1424
1425     <sect2>
1426       <title>Finishing InitOutput()</title>
1427
1428       <para>
1429     At this point <function>InitOutput()</function> is finished, and all the
1430     screens have been setup in their initial video mode.
1431       </para>
1432
1433     </sect2>
1434
1435     <sect2>
1436       <title>Mode Switching</title>
1437
1438       <para>
1439     When a SwitchMode event is received, <function>ChipSwitchMode()</function>
1440     is called (when it exists):
1441       </para>
1442
1443       <blockquote><para>
1444           <programlisting>
1445     Bool ChipSwitchMode(int index, DisplayModePtr mode);
1446           </programlisting>
1447           <blockquote><para>
1448       Initialises the new mode for the screen identified by
1449       <parameter>index;</parameter>.  The viewport may need to be adjusted
1450       also.
1451
1452             </para></blockquote>
1453         </para></blockquote>
1454
1455     </sect2>
1456
1457     <sect2>
1458       <title>Changing Viewport</title>
1459
1460       <para>
1461     When a Change Viewport event is received,
1462     <function>ChipAdjustFrame()</function> is called (when it exists):
1463       </para>
1464
1465       <blockquote><para>
1466           <programlisting>
1467     void ChipAdjustFrame(int index, int x, int y);
1468           </programlisting>
1469           <blockquote><para>
1470       Changes the viewport for the screen identified by
1471       <parameter>index;</parameter>.
1472             </para>
1473
1474             <para>
1475       It should be noted that many chipsets impose restrictions on where the
1476       viewport may be placed in the virtual resolution, either for alignment
1477       reasons, or to prevent the start of the viewport from being positioned
1478       within a pixel (as can happen in a 24bpp mode).  After calculating the
1479       value the chipset's panning registers need to be set to for non-DGA
1480       modes, this function should recalculate the ScrnInfoRec's
1481       <structfield>frameX0</structfield>, <structfield>frameY0</structfield>, <structfield>frameX1</structfield>
1482       and <structfield>frameY1</structfield> fields to correspond to that value.  If
1483       this is not done, switching to another mode might cause the position
1484       of a hardware cursor to change.
1485
1486             </para></blockquote>
1487         </para></blockquote>
1488
1489     </sect2>
1490
1491     <sect2>
1492       <title>VT Switching</title>
1493
1494       <para>
1495     When a VT switch event is received, <function>xf86VTSwitch()</function>
1496     is called.  <function>xf86VTSwitch()</function> does the following:
1497
1498         <variablelist>
1499           <varlistentry><term>On ENTER:</term>
1500             <listitem>
1501               <itemizedlist>
1502                 <listitem><para>
1503                     enable port I/O access
1504                   </para></listitem>
1505
1506                 <listitem><para>
1507                     save and initialise the bus/resource state
1508                   </para></listitem>
1509
1510                 <listitem><para>
1511                     enter the SETUP server state
1512                   </para></listitem>
1513
1514                 <listitem><para>
1515                     calls <function>ChipEnterVT()</function> for each screen
1516                   </para></listitem>
1517
1518                 <listitem><para>
1519                     enter the OPERATING server state
1520                   </para></listitem>
1521
1522                 <listitem><para>
1523                     validate GCs
1524                   </para></listitem>
1525
1526                 <listitem><para>
1527                     Restore fb from saved pixmap for each screen
1528                   </para></listitem>
1529
1530                 <listitem><para>
1531                     Enable all input devices
1532                   </para></listitem>
1533               </itemizedlist>
1534             </listitem>
1535           </varlistentry>
1536           <varlistentry>
1537             <term>On LEAVE:</term>
1538             <listitem>
1539               <itemizedlist>
1540                 <listitem><para>
1541                     Save fb to pixmap for each screen
1542                   </para></listitem>
1543
1544                 <listitem><para>
1545                     validate GCs
1546                   </para></listitem>
1547
1548                 <listitem><para>
1549                     enter the SETUP server state
1550                   </para></listitem>
1551
1552                 <listitem><para>
1553                     calls <function>ChipLeaveVT()</function> for each screen
1554                   </para></listitem>
1555
1556                 <listitem><para>
1557                     disable all input devices
1558                   </para></listitem>
1559
1560                 <listitem><para>
1561                     restore bus/resource state
1562                   </para></listitem>
1563
1564                 <listitem><para>
1565                     disables port I/O access
1566                   </para></listitem>
1567               </itemizedlist>
1568             </listitem>
1569           </varlistentry>
1570         </variablelist>
1571       </para>
1572
1573       <blockquote><para>
1574           <programlisting>
1575     Bool ChipEnterVT(ScrnInfoPtr pScrn);
1576           </programlisting>
1577           <blockquote><para>
1578       This function should initialise the current video mode and
1579       initialise the viewport, turn on the HW cursor if appropriate,
1580       etc.
1581             </para>
1582
1583             <para>
1584       Should it re-save the video state before initialising the video
1585       mode?
1586             </para>
1587
1588           </blockquote></para></blockquote>
1589
1590       <blockquote><para>
1591           <programlisting>
1592     void ChipLeaveVT(ScrnInfoPtr pScrn);
1593           </programlisting>
1594           <blockquote><para>
1595       This function should restore the saved video state.  If
1596       appropriate it should also turn off the HW cursor, and invalidate
1597       any pixmap/font caches.
1598             </para>
1599
1600           </blockquote></para></blockquote>
1601
1602       <para>
1603     Optionally, <function>ChipLeaveVT()</function> may also unmap memory
1604     regions.  If so, <function>ChipEnterVT()</function> will need to remap
1605     them.  Additionally, if an aperture used to access video memory is
1606     unmapped and remapped in this fashion, <function>ChipEnterVT()</function>
1607     will also need to notify the framebuffer layers of the aperture's new
1608     location in virtual memory.  This is done with a call to the screen's
1609     <function>ModifyPixmapHeader()</function> function, as follows
1610       </para>
1611
1612       <blockquote><para>
1613           <programlisting>
1614     (*pScreen-&gt;ModifyPixmapHeader)(pScrn-&gt;ppix,
1615                                    -1, -1, -1, -1, -1, NewApertureAddress);
1616           </programlisting>
1617           <blockquote><para>
1618         where the <structfield>ppix</structfield> field in a ScrnInfoRec
1619         points to the pixmap used by the screen's
1620         <function>SaveRestoreImage()</function> function to hold the screen's
1621         contents while switched out.
1622             </para>
1623
1624           </blockquote></para></blockquote>
1625
1626       <para>
1627     Other layers may wrap the <function>ChipEnterVT()</function> and
1628     <function>ChipLeaveVT()</function> functions if they need to take some
1629     action when these events are received.
1630       </para>
1631     </sect2>
1632
1633     <sect2>
1634       <title>End of server generation</title>
1635
1636       <para>
1637     At the end of each server generation, the DIX layer calls
1638     <function>ChipCloseScreen()</function> for each screen:
1639       </para>
1640
1641       <blockquote><para>
1642           <programlisting>
1643     Bool ChipCloseScreen(int index, ScreenPtr pScreen);
1644           </programlisting>
1645           <blockquote><para>
1646       This function should restore the saved video state and unmap the
1647       memory regions.
1648             </para>
1649
1650             <para>
1651       It should also free per-screen data structures allocated by the
1652       driver.  Note that the persistent data held in the
1653       <structname>ScrnInfoRec</structname>'s <structfield>driverPrivate</structfield> field
1654       should not be freed here because it is needed by subsequent server
1655       generations.
1656             </para>
1657
1658             <para>
1659       The <structname>ScrnInfoRec</structname>'s <structfield>vtSema</structfield> field
1660       should be set to <constant>FALSE</constant> once the video HW state
1661       has been restored.
1662             </para>
1663
1664             <para>
1665       Before freeing the per-screen driver data the saved
1666       <structfield>CloseScreen</structfield> value should be restored to
1667       <structfield>pScreen-&gt;CloseScreen</structfield>, and that function should
1668       be called after freeing the data.
1669
1670             </para></blockquote>
1671         </para></blockquote>
1672     </sect2>
1673   </sect1>
1674
1675   <sect1>
1676     <title>Optional Driver Functions</title>
1677
1678     <para>
1679 The functions outlined here can be called from the XFree86 common layer,
1680 but their presence is optional.
1681     </para>
1682
1683     <sect2>
1684       <title>Mode Validation</title>
1685
1686       <para>
1687     When a mode validation helper supplied by the XFree86-common layer is
1688     being used, it can be useful to provide a function to check for hw
1689     specific mode constraints:
1690       </para>
1691
1692       <blockquote><para>
1693           <programlisting>
1694     ModeStatus ChipValidMode(ScrnInfoPtr pScrn, DisplayModePtr mode,
1695                              Bool verbose, int flags);
1696           </programlisting>
1697           <blockquote><para>
1698       Check the passed mode for hw-specific constraints, and return the
1699       appropriate status value.
1700
1701             </para></blockquote>
1702         </para></blockquote>
1703
1704       <para>
1705 This function may also modify the effective timings and clock of the passed
1706 mode.  These have been stored in the mode's <structfield>Crtc*</structfield> and
1707 <structfield>SynthClock</structfield> elements, and have already been adjusted for
1708 interlacing, doublescanning, multiscanning and clock multipliers and dividers.
1709 The function should not modify any other mode field, unless it wants to modify
1710 the mode timings reported to the user by <function>xf86PrintModes()</function>.
1711       </para>
1712
1713       <para>
1714 The function is called once for every mode in the xorg.conf Monitor section
1715 assigned to the screen, with <parameter>flags</parameter> set to
1716 <constant>MODECHECK_INITIAL</constant>.  It is subsequently called for every mode
1717 in the xorg.conf Display subsection assigned to the screen, with
1718 <parameter>flags</parameter> set to <constant>MODECHECK_FINAL</constant>.  In the second
1719 case, the mode will have successfully passed all other tests.  In addition,
1720 the <structname>ScrnInfoRec</structname>'s <structfield>virtualX</structfield>,
1721 <structfield>virtualY</structfield> and <structfield>displayWidth</structfield> fields will have been
1722 set as if the mode to be validated were to be the last mode accepted.
1723       </para>
1724
1725       <para>
1726 In effect, calls with MODECHECK_INITIAL are intended for checks that do not
1727 depend on any mode other than the one being validated, while calls with
1728 MODECHECK_FINAL are intended for checks that may involve more than one mode.
1729       </para>
1730     </sect2>
1731
1732     <sect2>
1733       <title>Free screen data</title>
1734
1735       <para>
1736     When a screen is deleted prior to the completion of the ScreenInit
1737     phase the <function>ChipFreeScreen()</function> function is called when defined.
1738       </para>
1739
1740       <blockquote><para>
1741           <programlisting>
1742     void ChipFreeScreen(ScrnInfoPtr pScrn);
1743           </programlisting>
1744           <blockquote><para>
1745       Free any driver-allocated data that may have been allocated up to
1746       and including an unsuccessful <function>ChipScreenInit()</function>
1747       call.  This would predominantly be data allocated by
1748       <function>ChipPreInit()</function> that persists across server
1749       generations.  It would include the <structfield>driverPrivate</structfield>,
1750       and any <quote>privates</quote> entries that modules may have allocated.
1751
1752             </para></blockquote>
1753         </para></blockquote>
1754
1755     </sect2>
1756 </sect1>
1757
1758   <sect1>
1759     <title>Recommended driver functions</title>
1760
1761     <para>
1762 The functions outlined here are for internal use by the driver only.
1763 They are entirely optional, and are never accessed directly from higher
1764 layers.  The sample function declarations shown here are just examples.
1765 The interface (if any) used is up to the driver.
1766     </para>
1767
1768     <sect2>
1769       <title>Save</title>
1770
1771       <para>
1772     Save the video state.  This could be called from <function>ChipScreenInit()</function> and
1773     (possibly) <function>ChipEnterVT()</function>.
1774       </para>
1775
1776       <blockquote><para>
1777           <programlisting>
1778     void ChipSave(ScrnInfoPtr pScrn);
1779           </programlisting>
1780           <blockquote><para>
1781       Saves the current state.  This will only be saving pre-server
1782       states or states before returning to the server.  There is only
1783       one current saved state per screen and it is stored in private
1784       storage in the screen.
1785
1786             </para></blockquote>
1787         </para></blockquote>
1788     </sect2>
1789
1790     <sect2>
1791       <title>Restore</title>
1792
1793       <para>
1794     Restore the original video state.  This could be called from the
1795     <function>ChipLeaveVT()</function> and <function>ChipCloseScreen()</function>
1796     functions.
1797       </para>
1798
1799       <blockquote><para>
1800           <programlisting>
1801     void ChipRestore(ScrnInfoPtr pScrn);
1802           </programlisting>
1803           <blockquote><para>
1804       Restores the saved state from the private storage.  Usually only
1805       used for restoring text modes.
1806
1807             </para></blockquote>
1808         </para></blockquote>
1809
1810     </sect2>
1811
1812     <sect2>
1813       <title>Initialise Mode</title>
1814
1815       <para>
1816     Initialise a video mode.  This could be called from the
1817     <function>ChipScreenInit()</function>, <function>ChipSwitchMode()</function>
1818     and <function>ChipEnterVT()</function> functions.
1819       </para>
1820
1821       <blockquote><para>
1822           <programlisting>
1823     Bool ChipModeInit(ScrnInfoPtr pScrn, DisplayModePtr mode);
1824           </programlisting>
1825           <blockquote><para>
1826       Programs the hardware for the given video mode.
1827
1828             </para></blockquote>
1829         </para></blockquote>
1830
1831     </sect2>
1832   </sect1>
1833
1834   <sect1>
1835     <title>Data and Data Structures</title>
1836
1837     <sect2>
1838       <title>Command line data</title>
1839
1840       <para>
1841 Command line options are typically global, and are stored in global
1842 variables.  These variables are read-only and are available to drivers
1843 via a function call interface.  Most of these command line values are
1844 processed via helper functions to ensure that they are treated consistently
1845 by all drivers.  The other means of access is provided for cases where
1846 the supplied helper functions might not be appropriate.
1847       </para>
1848
1849       <para>
1850 Some of them are:
1851
1852         <literallayout>
1853     xf86Verbose               verbosity level
1854     xf86Bpp                   -bpp from the command line
1855     xf86Depth                 -depth from the command line
1856     xf86Weight                -weight from the command line
1857     xf86Gamma                 -{r,g,b,}gamma from the command line
1858     xf86FlipPixels            -flippixels from the command line
1859     xf86ProbeOnly             -probeonly from the command line
1860     defaultColorVisualClass   -cc from the command line
1861         </literallayout>
1862       </para>
1863
1864       <para>
1865 If we ever do allow for screen-specific command line options, we may
1866 need to rethink this.
1867       </para>
1868
1869       <para>
1870 These can be accessed in a read-only manner by drivers with the following
1871 functions:
1872       </para>
1873
1874      <blockquote><para>
1875           <programlisting>
1876     int xf86GetVerbosity();
1877           </programlisting>
1878           <blockquote><para>
1879       Returns the value of <varname>xf86Verbose</varname>.
1880             </para></blockquote>
1881
1882         </para></blockquote>
1883
1884      <blockquote><para>
1885           <programlisting>
1886     int xf86GetDepth();
1887           </programlisting>
1888           <blockquote><para>
1889       Returns the <option>-depth</option> command line setting.  If not
1890       set on the command line, <constant>-1</constant> is returned.
1891             </para></blockquote>
1892
1893         </para></blockquote>
1894
1895      <blockquote><para>
1896           <programlisting>
1897     rgb xf86GetWeight();
1898           </programlisting>
1899           <blockquote><para>
1900       Returns the <option>-weight</option> command line setting.  If not
1901       set on the command line, <literal remap="tt">{0, 0, 0}</literal> is returned.
1902             </para></blockquote>
1903
1904         </para></blockquote>
1905
1906       <blockquote><para>
1907           <programlisting>
1908     Gamma xf86GetGamma();
1909           </programlisting>
1910           <blockquote><para>
1911       Returns the <option>-gamma</option> or <option>-rgamma</option>,
1912       <option>-ggamma</option>, <option>-bgamma</option> command line settings.
1913       If not set on the command line, <literal remap="tt">{0.0, 0.0, 0.0}</literal>
1914       is returned.
1915             </para></blockquote>
1916
1917         </para></blockquote>
1918
1919       <blockquote><para>
1920           <programlisting>
1921     Bool xf86GetFlipPixels();
1922           </programlisting>
1923           <blockquote><para>
1924       Returns <constant>TRUE</constant> if <option>-flippixels</option> is
1925       present on the command line, and <constant>FALSE</constant> otherwise.
1926             </para></blockquote>
1927
1928         </para></blockquote>
1929
1930       <blockquote><para>
1931           <programlisting>
1932     const char *xf86GetServerName();
1933           </programlisting>
1934           <blockquote><para>
1935       Returns the name of the X server from the command line.
1936             </para></blockquote>
1937
1938         </para></blockquote>
1939     </sect2>
1940
1941     <sect2>
1942       <title>Data handling</title>
1943
1944       <para>
1945 Config file data contains parts that are global, and parts that are
1946 Screen specific.  All of it is parsed into data structures that neither
1947 the drivers or most other parts of the server need to know about.
1948       </para>
1949
1950       <para>
1951 The global data is typically not required by drivers, and as such, most
1952 of it is stored in the private <structname>xf86InfoRec</structname>.
1953       </para>
1954
1955       <para>
1956 The screen-specific data collected from the config file is stored in
1957 screen, device, display, monitor-specific data structures that are separate
1958 from the <varname>ScrnInfoRecs</varname>, with the appropriate elements/fields
1959 hooked into the <varname>ScrnInfoRecs</varname> as required.  The screen
1960 config data is held in <structname>confScreenRec</structname>, device data in
1961 the <structname>GDevRec</structname>, monitor data in the <structname>MonRec</structname>,
1962 and display data in the <structname>DispRec</structname>.
1963       </para>
1964
1965       <para>
1966 The XFree86 common layer's screen specific data (the actual data in use
1967 for each screen) is held in the <varname>ScrnInfoRecs</varname>.  As has
1968 been outlined above, the <varname>ScrnInfoRecs</varname> are allocated at probe
1969 time, and it is the responsibility of the Drivers' <function>Probe()</function>
1970 and <function>PreInit()</function> functions to finish filling them in based
1971 on both data provided on the command line and data provided from the
1972 Config file.  The precedence for this is:
1973
1974         <blockquote><para>
1975     command line  -&gt;  config file  -&gt;  probed/default data
1976         </para></blockquote>
1977       </para>
1978
1979       <para>
1980 For most things in this category there are helper functions that the
1981 drivers can use to ensure that the above precedence is consistently
1982 used.
1983       </para>
1984
1985       <para>
1986 As well as containing screen-specific data that the XFree86 common layer
1987 (including essential parts of the server infrastructure as well as helper
1988 functions) needs to access, it also contains some data that drivers use
1989 internally.  When considering whether to add a new field to the
1990 <structname>ScrnInfoRec</structname>, consider the balance between the convenience
1991 of things that lots of drivers need and the size/obscurity of the
1992 <structname>ScrnInfoRec</structname>.
1993       </para>
1994
1995       <para>
1996 Per-screen driver specific data that cannot be accommodated with the
1997 static <structname>ScrnInfoRec</structname> fields is held in a driver-defined
1998 data structure, a pointer to which is assigned to the
1999 <structname>ScrnInfoRec</structname>'s <structfield>driverPrivate</structfield> field.  This
2000 is per-screen data that persists across server generations (as does the
2001 bulk of the static <structname>ScrnInfoRec</structname> data).  It would typically
2002 also include the video card's saved state.
2003       </para>
2004
2005       <para>
2006 Per-screen data for other modules that the driver uses that is reset for each
2007 server generation is hooked into the <structname>ScrnInfoRec</structname>
2008 through its <structfield>privates</structfield> field.
2009       </para>
2010
2011       <para>
2012 Once it has stabilised, the data structures and variables accessible to
2013 video drivers will be documented here.  In the meantime, those things
2014 defined in the <filename>xf86.h</filename> and <filename>xf86str.h</filename>
2015 files are visible to video drivers.  Things defined in
2016 <filename>xf86Priv.h</filename> and <filename>xf86Privstr.h</filename> are NOT
2017 intended to be visible to video drivers, and it is an error for a driver
2018 to include those files.
2019       </para>
2020
2021     </sect2>
2022
2023     <sect2>
2024       <title>Accessing global data</title>
2025
2026       <para>
2027 Some other global state information that the drivers may access via
2028 functions is as follows:
2029       </para>
2030
2031       <blockquote><para>
2032           <programlisting>
2033     Bool xf86ServerIsExiting();
2034           </programlisting>
2035           <blockquote><para>
2036       Returns <constant>TRUE</constant> if the server is at the end of a
2037       generation and is in the process of exiting, and
2038       <constant>FALSE</constant> otherwise.
2039             </para></blockquote>
2040
2041         </para></blockquote>
2042
2043       <blockquote><para>
2044           <programlisting>
2045     Bool xf86ServerIsResetting();
2046           </programlisting>
2047           <blockquote><para>
2048       Returns <constant>TRUE</constant> if the server is at the end of a
2049       generation and is in the process of resetting, and
2050       <constant>FALSE</constant> otherwise.
2051             </para></blockquote>
2052
2053         </para></blockquote>
2054
2055       <blockquote><para>
2056           <programlisting>
2057     Bool xf86ServerIsInitialising();
2058           </programlisting>
2059           <blockquote><para>
2060       Returns <constant>TRUE</constant> if the server is at the beginning of
2061       a generation and is in the process of initialising, and
2062       <constant>FALSE</constant> otherwise.
2063             </para></blockquote>
2064
2065         </para></blockquote>
2066
2067       <blockquote><para>
2068           <programlisting>
2069     Bool xf86ServerIsOnlyProbing();
2070           </programlisting>
2071           <blockquote><para>
2072       Returns <constant>TRUE</constant> if the -probeonly command line flag
2073       was specified, and <constant>FALSE</constant> otherwise.
2074             </para></blockquote>
2075
2076         </para></blockquote>
2077
2078       <blockquote><para>
2079           <programlisting>
2080     Bool xf86CaughtSignal();
2081           </programlisting>
2082           <blockquote><para>
2083       Returns <constant>TRUE</constant> if the server has caught a signal,
2084       and <constant>FALSE</constant> otherwise.
2085             </para></blockquote>
2086
2087         </para></blockquote>
2088     </sect2>
2089
2090     <sect2>
2091       <title>Allocating private data</title>
2092
2093       <para>
2094 A driver and any module it uses may allocate per-screen private storage
2095 in either the <structname>ScreenRec</structname> (DIX level) or
2096 <structname>ScrnInfoRec</structname> (XFree86 common layer level).
2097 <structname>ScreenRec</structname> storage persists only for a single server
2098 generation, and <structname>ScrnInfoRec</structname> storage persists across
2099 generations for the lifetime of the server.
2100       </para>
2101
2102       <para>
2103 The <structname>ScreenRec</structname> <structfield>devPrivates</structfield> data must be
2104 reallocated/initialised at the start of each new generation.  This is
2105 normally done from the <function>ChipScreenInit()</function> function, and
2106 Init functions for other modules that it calls.  Data allocated in this
2107 way should be freed by the driver's <function>ChipCloseScreen()</function>
2108 functions, and Close functions for other modules that it calls.  A new
2109 <structfield>devPrivates</structfield> entry is allocated by calling the
2110 <function>AllocateScreenPrivateIndex()</function> function.
2111       </para>
2112
2113       <blockquote><para>
2114           <programlisting>
2115     int AllocateScreenPrivateIndex();
2116           </programlisting>
2117           <blockquote><para>
2118       This function allocates a new element in the
2119       <structfield>devPrivates</structfield> field of all currently existing
2120       <literal remap="tt">ScreenRecs</literal>.  The return value is the index of this
2121       new element in the <structfield>devPrivates</structfield> array.  The
2122       <structfield>devPrivates</structfield> field is of type
2123       <structname>DevUnion</structname>:
2124
2125               <programlisting>
2126         typedef union _DevUnion {
2127             pointer             ptr;
2128             long                val;
2129             unsigned long       uval;
2130             pointer             (*fptr)(void);
2131         } DevUnion;
2132               </programlisting>
2133
2134       which allows the element to be used for any of the above types.
2135       It is commonly used as a pointer to data that the caller allocates
2136       after the new index has been allocated.
2137             </para>
2138
2139             <para>
2140       This function will return <constant>-1</constant> when there is an
2141       error allocating the new index.
2142             </para>
2143
2144           </blockquote>
2145         </para></blockquote>
2146
2147       <para>
2148 The <structname>ScrnInfoRec</structname> <structfield>privates</structfield> data persists
2149 for the life of the server, so only needs to be allocated once.  This
2150 should be done from the <function>ChipPreInit()</function> function, and Init
2151 functions for other modules that it calls.  Data allocated in this way
2152 should be freed by the driver's <function>ChipFreeScreen()</function> functions,
2153 and Free functions for other modules that it calls.  A new
2154 <structfield>privates</structfield> entry is allocated by calling the
2155 <function>xf86AllocateScrnInfoPrivateIndex()</function> function.
2156       </para>
2157
2158       <blockquote><para>
2159           <programlisting>
2160     int xf86AllocateScrnInfoPrivateIndex();
2161           </programlisting>
2162           <blockquote><para>
2163       This function allocates a new element in the <structfield>privates</structfield>
2164       field of all currently existing <varname>ScrnInfoRecs</varname>.
2165       The return value is the index of this new element in the
2166       <structfield>privates</structfield> array.  The <structfield>privates</structfield>
2167       field is of type <structfield>DevUnion</structfield>:
2168
2169               <programlisting>
2170         typedef union _DevUnion {
2171             pointer             ptr;
2172             long                val;
2173             unsigned long       uval;
2174             pointer             (*fptr)(void);
2175         } DevUnion;
2176               </programlisting>
2177
2178       which allows the element to be used for any of the above types.
2179       It is commonly used as a pointer to data that the caller allocates
2180       after the new index has been allocated.
2181             </para>
2182
2183             <para>
2184       This function will not return when there is an error allocating
2185       the new index.  When there is an error it will cause the server
2186       to exit with a fatal error.  The similar function for allocation
2187       privates in the <structname>ScreenRec</structname>
2188       (<function>AllocateScreenPrivateIndex()</function>) differs in this
2189       respect by returning <constant>-1</constant> when the allocation fails.
2190             </para>
2191
2192           </blockquote>
2193         </para></blockquote>
2194     </sect2>
2195   </sect1>
2196
2197   <sect1 id="rac">
2198     <title>Keeping Track of Bus Resources</title>
2199
2200     <sect2>
2201       <title>Theory of Operation</title>
2202
2203       <para>
2204 The XFree86 common layer has knowledge of generic access control mechanisms
2205 for devices on certain bus systems (currently the PCI bus) as well as
2206 of methods to enable or disable access to the buses itself.  Furthermore
2207 it can access information on resources decoded by these devices and if
2208 necessary modify it.
2209       </para>
2210
2211       <para>
2212 When first starting the Xserver collects all this information, saves it
2213 for restoration, checks it for consistency, and if necessary, corrects
2214 it.  Finally it disables all resources on a generic level prior to
2215 calling any driver function.
2216       </para>
2217
2218       <para>
2219 When the <function>Probe()</function> function of each driver is called the
2220 device sections are matched against the devices found in the system.
2221 The driver may probe devices at this stage that cannot be identified by
2222 using device independent methods.  Access to all resources that can be
2223 controlled in a device independent way is disabled.  The
2224 <function>Probe()</function> function should register all non-relocatable
2225 resources at this stage.  If a resource conflict is found between
2226 exclusive resources the driver will fail immediately.  Optionally the
2227 driver might specify an <function>EntityInit()</function>,
2228 <function>EntityLeave()</function> and <function>EntityEnter()</function> function.
2229       </para>
2230
2231       <para>
2232 <function>EntityInit()</function> can be used to disable any shared resources
2233 that are not controlled by the generic access control functions.  It is
2234 called prior to the PreInit phase regardless if an entity is active or
2235 not.  When calling the <function>EntityInit()</function>,
2236 <function>EntityEnter()</function> and <function>EntityLeave()</function> functions
2237 the common level will disable access to all other entities on a generic
2238 level.  Since the common level has no knowledge of device specific
2239 methods to disable access to resources it cannot be guaranteed that
2240 certain resources are not decoded by any other entity until the
2241 <function>EntityInit()</function> or <function>EntityEnter()</function> phase is
2242 finished.  Device drivers should therefore register all those resources
2243 which they are going to disable.  If these resources are never to be
2244 used by any driver function they may be flagged <constant>ResInit</constant>
2245 so that they can be removed from the resource list after processing all
2246 <function>EntityInit()</function> functions.  <function>EntityEnter()</function>
2247 should disable decoding of all resources which are not registered as
2248 exclusive and which are not handled by the generic access control in
2249 the common level.  The difference to <function>EntityInit()</function> is
2250 that the latter one is only called once during lifetime of the server.
2251 It can therefore be used to set up variables prior to disabling resources.
2252 <function>EntityLeave()</function> should restore the original state when
2253 exiting the server or switching to a different VT.  It also needs to
2254 disable device specific access functions if they need to be disabled on
2255 server exit or VT switch.  The default state is to enable them before
2256 giving up the VT.
2257       </para>
2258
2259       <para>
2260 In <function>PreInit()</function> phase each driver should check if any
2261 sharable resources it has registered during <function>Probe()</function> has
2262 been denied and take appropriate action which could simply be to fail.
2263 If it needs to access resources it has disabled during
2264 <function>EntitySetup()</function> it can do so provided it has registered
2265 these and will disable them before returning from
2266 <function>PreInit()</function>.  This also applies to all other driver
2267 functions.  Several functions are provided to request resource ranges,
2268 register these, correct PCI config space and add replacements for the
2269 generic access functions.  Resources may be marked <quote>disabled</quote> or
2270 <quote>unused</quote> during OPERATING stage.  Although these steps could also be
2271 performed in <function>ScreenInit()</function>, this is not desirable.
2272       </para>
2273
2274       <para>
2275 Following <function>PreInit()</function> phase the common level determines
2276 if resource access control is needed.  This is the case if more than
2277 one screen is used.  If necessary the RAC wrapper module is loaded.  In
2278 <function>ScreenInit()</function> the drivers can decide which operations
2279 need to be placed under RAC.  Available are the frame buffer operations,
2280 the pointer operations and the colormap operations.  Any operation that
2281 requires resources which might be disabled during OPERATING state should
2282 be set to use RAC.  This can be specified separately for memory and IO
2283 resources.
2284       </para>
2285
2286       <para>
2287 When <function>ScreenInit()</function> phase is done the common level will
2288 determine which shared resources are requested by more than one driver
2289 and set the access functions accordingly.  This is done following these
2290 rules:
2291
2292         <orderedlist>
2293           <listitem><para>
2294    The sharable resources registered by each entity are compared.  If
2295    a resource is registered by more than one entity the entity will be
2296    marked to need to share this resources type (<constant>IO</constant> or
2297    <constant>MEM</constant>).
2298             </para></listitem>
2299
2300           <listitem><para>
2301    A resource marked <quote>disabled</quote> during OPERATING state will be ignored
2302    entirely.
2303             </para></listitem>
2304
2305           <listitem><para>
2306    A resource marked <quote>unused</quote> will only conflicts with an overlapping
2307    resource of an other entity if the second is actually in use during
2308    OPERATING state.
2309             </para></listitem>
2310
2311           <listitem><para>
2312    If an <quote>unused</quote> resource was found to conflict however the entity
2313    does not use any other resource of this type the entire resource type
2314    will be disabled for that entity.
2315             </para></listitem>
2316         </orderedlist>
2317       </para>
2318
2319       <para>
2320 The driver has the choice among different ways to control access to
2321 certain resources:
2322
2323         <orderedlist>
2324           <listitem><para>
2325    It can rely on the generic access functions.  This is probably the
2326    most common case.  Here the driver only needs to register any resource
2327    it is going to use.
2328             </para></listitem>
2329
2330           <listitem><para>
2331    It can replace the generic access functions by driver specific
2332    ones.  This will mostly be used in cases where no generic access
2333    functions are available.  In this case the driver has to make sure
2334    these resources are disabled when entering the <function>PreInit()</function>
2335    stage.  Since the replacement functions are registered in
2336    <function>PreInit()</function> the driver will have to enable these
2337    resources itself if it needs to access them during this state.  The
2338    driver can specify if the replacement functions can control memory
2339    and/or I/O resources separately.
2340             </para></listitem>
2341
2342           <listitem><para>
2343    The driver can enable resources itself when it needs them.  Each
2344    driver function enabling them needs to disable them before it will
2345    return.  This should be used if a resource which can be controlled
2346    in a device dependent way is only required during SETUP state.  This
2347    way it can be marked <quote>unused</quote> during OPERATING state.
2348             </para></listitem>
2349         </orderedlist>
2350       </para>
2351
2352       <para>
2353 A resource which is decoded during OPERATING state however never accessed
2354 by the driver should be marked unused.
2355       </para>
2356
2357       <para>
2358 Since access switching latencies are an issue during Xserver operation,
2359 the common level attempts to minimize the number of entities that need
2360 to be placed under RAC control.  When a wrapped operation is called,
2361 the <function>EnableAccess()</function> function is called before control is
2362 passed on.  <function>EnableAccess()</function> checks if a screen is under
2363 access control.  If not it just establishes bus routing and returns.
2364 If the screen needs to be under access control,
2365 <function>EnableAccess()</function> determines which resource types
2366 (<literal remap="tt">MEM</literal>, <literal remap="tt">IO</literal>) are required.  Then it tests
2367 if this access is already established.  If so it simply returns.  If
2368 not it disables the currently established access, fixes bus routing and
2369 enables access to all entities registered for this screen.
2370       </para>
2371
2372       <para>
2373 Whenever a mode switch or a VT-switch is performed the common level will
2374 return to SETUP state.
2375       </para>
2376     </sect2>
2377
2378     <sect2>
2379       <title>Resource Types</title>
2380
2381       <para>
2382 Resource have certain properties.  When registering resources each range
2383 is accompanied by a flag consisting of the ORed flags of the different
2384 properties the resource has.  Each resource range may be classified
2385 according to
2386
2387         <itemizedlist>
2388           <listitem><para>
2389        its physical properties i.e., if it addresses
2390        memory (<constant>ResMem</constant>)  or
2391        I/O space (<constant>ResIo</constant>),
2392             </para></listitem>
2393           <listitem><para>
2394        if it addresses a
2395        block (<constant>ResBlock</constant>) or
2396        sparse (<constant>ResSparse</constant>)
2397        range,
2398             </para></listitem>
2399           <listitem><para>
2400        its access properties.
2401             </para></listitem>
2402         </itemizedlist>
2403       </para>
2404
2405       <para>
2406 There are two known access properties:
2407
2408         <itemizedlist>
2409           <listitem><para>
2410   <constant>ResExclusive</constant>
2411     for resources which may not be shared with any other device and
2412             </para></listitem>
2413           <listitem><para>
2414   <constant>ResShared</constant>
2415     for resources which can be disabled and therefore can be shared.
2416             </para></listitem>
2417         </itemizedlist>
2418       </para>
2419
2420       <para>
2421 If it is necessary to test a resource against any type a generic access
2422 type <constant>ResAny</constant> is provided.  If this is set the resource
2423 will conflict with any resource of a different entity intersecting its
2424 range.  Further it can be specified that a resource is decoded however
2425 never used during any stage (<constant>ResUnused</constant>) or during
2426 OPERATING state (<constant>ResUnusedOpr</constant>).  A resource only visible
2427 during the init functions (ie.  <function>EntityInit()</function>,
2428 <function>EntityEnter()</function> and <function>EntityLeave()</function> should
2429 be registered with the flag <constant>ResInit</constant>.  A resource that
2430 might conflict with background resource ranges may be flagged with
2431 <constant>ResBios</constant>.  This might be useful when registering resources
2432 ranges that were assigned by the system Bios.
2433       </para>
2434
2435       <para>
2436 Several predefined resource lists are available for VGA and 8514/A
2437 resources in <filename>common/xf86Resources.h</filename>.
2438       </para>
2439     </sect2>
2440
2441     <sect2 id="avail">
2442       <title>Available Functions</title>
2443
2444       <para>
2445 The functions provided for resource management are listed in their order
2446 of use in the driver.
2447       </para>
2448
2449       <sect3>
2450         <title>Probe Phase</title>
2451
2452         <para>
2453 In this phase each driver detects those resources it is able to drive,
2454 creates an entity record for each of them, registers non-relocatable
2455 resources and allocates screens and adds the resources to screens.
2456         </para>
2457
2458         <para>
2459 Two helper functions are provided for matching device sections in the
2460 xorg.conf file to the devices:
2461         </para>
2462
2463         <blockquote><para>
2464             <programlisting>
2465     int xf86MatchPciInstances(const char *driverName, int vendorID,
2466                               SymTabPtr chipsets, PciChipsets *PCIchipsets,
2467                               GDevPtr *devList, int numDevs, DriverPtr drvp,
2468                               int **foundEntities);
2469             </programlisting>
2470             <blockquote><para>
2471       This function finds matches between PCI cards that a driver supports
2472       and config file device sections.  It is intended for use in the
2473       <function>ChipProbe()</function> function of drivers for PCI cards.
2474       Only probed PCI devices with a vendor ID matching
2475       <parameter>vendorID</parameter> are considered.  <parameter>devList</parameter>
2476       and <parameter>numDevs</parameter> are typically those found from
2477       calling <function>xf86MatchDevice()</function>, and represent the active
2478       config file device sections relevant to the driver.
2479       <parameter>PCIchipsets</parameter> is a table that provides a mapping
2480       between the PCI device IDs, the driver's internal chipset tokens
2481       and a list of fixed resources.
2482               </para>
2483
2484               <para>
2485       When a device section doesn't have a <emphasis>BusID</emphasis> entry it
2486       can only match the primary video device.  Secondary devices are
2487       only matched with device sections that have a matching
2488       <emphasis>BusID</emphasis> entry.
2489               </para>
2490
2491               <para>
2492       Once the preliminary matches have been found, a final match is
2493       confirmed by checking if the chipset override, ChipID override or
2494       probed PCI chipset type match one of those given in the
2495       <parameter>chipsets</parameter> and <parameter>PCIchipsets</parameter> lists.
2496       The <parameter>PCIchipsets</parameter> list includes a list of the PCI
2497       device IDs supported by the driver.  The list should be terminated
2498       with an entry with PCI ID <constant>-1</constant>".  The
2499       <parameter>chipsets</parameter> list is a table mapping the driver's
2500       internal chipset tokens to names, and should be terminated with
2501       a <constant>NULL</constant> entry.  Only those entries with a
2502       corresponding entry in the <parameter>PCIchipsets</parameter> list are
2503       considered.  The order of precedence is: config file chipset,
2504       config file ChipID, probed PCI device ID.
2505               </para>
2506
2507               <para>
2508       In cases where a driver handles PCI chipsets with more than one
2509       vendor ID, it may set <parameter>vendorID</parameter> to
2510       <constant>0</constant>, and OR each devID in the list with (the
2511       vendor&nbsp;ID&nbsp;&lt;&lt;&nbsp;16).
2512               </para>
2513
2514               <para>
2515       Entity index numbers for confirmed matches are returned as an
2516       array via <parameter>foundEntities</parameter>.  The PCI information,
2517       chipset token and device section for each match are found in the
2518       <structname>EntityInfoRec</structname> referenced by the indices.
2519               </para>
2520
2521               <para>
2522       The function return value is the number of confirmed matches.  A
2523       return value of <constant>-1</constant> indicates an internal error.
2524       The returned <parameter>foundEntities</parameter> array should be freed
2525       by the driver with <function>xfree()</function> when it is no longer
2526       needed in cases where the return value is greater than zero.
2527               </para>
2528
2529             </blockquote></para></blockquote>
2530
2531         <blockquote><para>
2532             <programlisting>
2533     int xf86MatchIsaInstances(const char *driverName,
2534                               SymTabPtr chipsets, IsaChipsets *ISAchipsets,
2535                               DriverPtr drvp, FindIsaDevProc FindIsaDevice,
2536                               GDevPtr *devList, int numDevs,
2537                               int **foundEntities);
2538             </programlisting>
2539             <blockquote><para>
2540       This function finds matches between ISA cards that a driver supports
2541       and config file device sections.  It is intended for use in the
2542       <function>ChipProbe()</function> function of drivers for ISA cards.
2543       <parameter>devList</parameter> and <parameter>numDevs</parameter> are
2544       typically those found from calling <function>xf86MatchDevice()</function>,
2545       and represent the active config file device sections relevant to
2546       the driver.  <parameter>ISAchipsets</parameter> is a table that provides
2547       a mapping between the driver's internal chipset tokens and the
2548       resource classes.  <parameter>FindIsaDevice</parameter> is a
2549       driver-provided function that probes the hardware and returns the
2550       chipset token corresponding to what was detected, and
2551       <constant>-1</constant> if nothing was detected.
2552               </para>
2553
2554               <para>
2555       If the config file device section contains a chipset entry, then
2556       it is checked against the <parameter>chipsets</parameter> list.  When
2557       no chipset entry is present, the <parameter>FindIsaDevice</parameter>
2558       function is called instead.
2559               </para>
2560
2561               <para>
2562       Entity index numbers for confirmed matches are returned as an
2563       array via <parameter>foundEntities</parameter>.  The chipset token and
2564       device section for each match are found in the
2565       <structname>EntityInfoRec</structname> referenced by the indices.
2566               </para>
2567
2568               <para>
2569       The function return value is the number of confirmed matches.  A
2570       return value of <constant>-1</constant> indicates an internal error.
2571       The returned <parameter>foundEntities</parameter> array should be freed
2572       by the driver with <function>xfree()</function> when it is no longer
2573       needed in cases where the return value is greater than zero.
2574               </para>
2575
2576             </blockquote></para></blockquote>
2577
2578         <para>
2579 These two helper functions make use of several core functions that are
2580 available at the driver level:
2581         </para>
2582
2583         <blockquote><para>
2584             <programlisting>
2585     Bool xf86ParsePciBusString(const char *busID, int *bus,
2586                                int *device, int *func);
2587             </programlisting>
2588             <blockquote><para>
2589       Takes a <parameter>BusID</parameter> string, and if it is in the correct
2590       format, returns the PCI <parameter>bus</parameter>, <parameter>device</parameter>,
2591       <parameter>func</parameter> values that it indicates.  The format of the
2592       string is expected to be "PCI:bus:device:func" where each of <quote>bus</quote>,
2593       <quote>device</quote> and <quote>func</quote> are decimal integers.  The ":func" part may
2594       be omitted, and the func value assumed to be zero, but this isn't
2595       encouraged.  The "PCI" prefix may also be omitted.  The prefix
2596       "AGP" is currently equivalent to the "PCI" prefix.  If the string
2597       isn't a valid PCI BusID, the return value is <constant>FALSE</constant>.
2598               </para>
2599
2600             </blockquote></para></blockquote>
2601
2602         <blockquote><para>
2603             <programlisting>
2604     Bool xf86ComparePciBusString(const char *busID, int bus,
2605                                  int device, int func);
2606             </programlisting>
2607             <blockquote><para>
2608       Compares a <parameter>BusID</parameter> string with PCI <parameter>bus</parameter>,
2609       <parameter>device</parameter>, <parameter>func</parameter> values.  If they
2610       match <constant>TRUE</constant> is returned, and <constant>FALSE</constant>
2611       if they don't.
2612               </para>
2613
2614             </blockquote></para></blockquote>
2615
2616         <blockquote><para>
2617             <programlisting>
2618     Bool xf86ParseIsaBusString(const char *busID);
2619             </programlisting>
2620             <blockquote><para>
2621       Compares a <parameter>BusID</parameter> string with the ISA bus ID string
2622       ("ISA" or "ISA:").  If they match <constant>TRUE</constant> is returned,
2623       and <constant>FALSE</constant> if they don't.
2624               </para>
2625
2626             </blockquote></para></blockquote>
2627
2628         <blockquote><para>
2629             <programlisting>
2630     Bool xf86CheckPciSlot(int bus, int device, int func);
2631             </programlisting>
2632             <blockquote><para>
2633       Checks if the PCI slot <literal remap="tt">bus:device:func</literal> has been
2634       claimed.  If so, it returns <constant>FALSE</constant>, and otherwise
2635       <constant>TRUE</constant>.
2636               </para>
2637
2638             </blockquote></para></blockquote>
2639
2640         <blockquote><para>
2641             <programlisting>
2642     int xf86ClaimPciSlot(int bus, int device, int func, DriverPtr drvp,
2643                          int chipset, GDevPtr dev, Bool active);
2644             </programlisting>
2645             <blockquote><para>
2646       This function is used to claim a PCI slot, allocate the associated
2647       entity record and initialise their data structures.  The return
2648       value is the index of the newly allocated entity record, or
2649       <constant>-1</constant> if the claim fails.  This function should always
2650       succeed if <function>xf86CheckPciSlot()</function> returned
2651       <constant>TRUE</constant> for the same PCI slot.
2652               </para>
2653
2654             </blockquote></para></blockquote>
2655
2656         <blockquote><para>
2657             <programlisting>
2658     Bool xf86IsPrimaryPci(void);
2659             </programlisting>
2660             <blockquote><para>
2661       This function returns <constant>TRUE</constant> if the primary card is
2662       a PCI device, and <constant>FALSE</constant> otherwise.
2663               </para>
2664
2665             </blockquote></para></blockquote>
2666
2667         <blockquote><para>
2668             <programlisting>
2669     int xf86ClaimIsaSlot(DriverPtr drvp, int chipset,
2670                          GDevPtr dev, Bool active);
2671             </programlisting>
2672             <blockquote><para>
2673       This allocates an entity record entity and initialise the data
2674       structures.  The return value is the index of the newly allocated
2675       entity record.
2676               </para>
2677
2678             </blockquote></para></blockquote>
2679
2680         <blockquote><para>
2681             <programlisting>
2682     Bool xf86IsPrimaryIsa(void);
2683             </programlisting>
2684             <blockquote><para>
2685       This function returns <constant>TRUE</constant> if the primary card is
2686       an ISA (non-PCI) device, and <constant>FALSE</constant> otherwise.
2687               </para>
2688
2689             </blockquote></para></blockquote>
2690
2691         <para>
2692 Two helper functions are provided to aid configuring entities:
2693         </para>
2694
2695         <blockquote><para>
2696             <programlisting>
2697     ScrnInfoPtr xf86ConfigPciEntity(ScrnInfoPtr pScrn,
2698                                     int scrnFlag, int entityIndex,
2699                                     PciChipsets *p_chip,
2700                                     resList res, EntityProc init,
2701                                     EntityProc enter, EntityProc leave,
2702                                     pointer private);
2703
2704     ScrnInfoPtr xf86ConfigIsaEntity(ScrnInfoPtr pScrn,
2705                                     int scrnFlag, int entityIndex,
2706                                     IsaChipsets *i_chip,
2707                                     resList res, EntityProc init,
2708                                     EntityProc enter, EntityProc leave,
2709                                     pointer private);
2710             </programlisting>
2711             <blockquote><para>
2712       These functions are used to register the non-relocatable resources
2713       for an entity, and the optional entity-specific <parameter>Init</parameter>, <parameter>Enter</parameter> and
2714       <parameter>Leave</parameter> functions.  Usually the list of fixed resources is obtained
2715       from the Isa/PciChipsets lists.  However an additional list of
2716       resources may be passed.  Generally this is not required.
2717       For active entities a <structname>ScrnInfoRec</structname> is allocated
2718       if the <parameter>pScrn</parameter> argument is <constant>NULL</constant>.
2719 The
2720       return value is <constant>TRUE</constant> when successful.  The init, enter, leave
2721       functions are defined as follows:
2722
2723                 <blockquote><para>
2724                     <programlisting>
2725         typedef void (*EntityProc)(int entityIndex,
2726                                    pointer private);
2727                     </programlisting>
2728                   </para></blockquote>
2729
2730       They are passed the entity index and a pointer to a private scratch
2731       area.  This can be set up during <function>Probe()</function> and
2732       its address can be passed to
2733       <function>xf86ConfigIsaEntity()</function> and
2734       <function>xf86ConfigPciEntity()</function> as the last argument.
2735               </para>
2736
2737             </blockquote></para></blockquote>
2738
2739         <para>
2740 These two helper functions make use of several core functions that are
2741 available at the driver level:
2742
2743           <blockquote><para>
2744               <programlisting>
2745     void xf86ClaimFixedResources(resList list, int entityIndex);
2746               </programlisting>
2747               <blockquote><para>
2748       This function registers the non-relocatable resources which cannot
2749       be disabled and which therefore would cause the server to fail
2750       immediately if they were found to conflict.  It also records
2751       non-relocatable but sharable resources for processing after the
2752       <function>Probe()</function> phase.
2753                 </para>
2754
2755               </blockquote></para></blockquote>
2756
2757           <blockquote><para>
2758               <programlisting>
2759     Bool xf86SetEntityFuncs(int entityIndex, EntityProc init,
2760                             EntityProc enter, EntityProc leave, pointer);
2761               </programlisting>
2762               <blockquote><para>
2763       This function registers with an entity the <parameter>init</parameter>,
2764       <parameter>enter</parameter>, <parameter>leave</parameter> functions along
2765       with the pointer to their private area.
2766                 </para>
2767
2768             </blockquote></para></blockquote>
2769
2770           <blockquote><para>
2771               <programlisting>
2772     void xf86AddEntityToScreen(ScrnInfoPtr pScrn, int entityIndex);
2773               </programlisting>
2774               <blockquote><para>
2775       This function associates the entity referenced by
2776       <parameter>entityIndex</parameter> with the screen.
2777                 </para>
2778
2779               </blockquote></para></blockquote>
2780         </para>
2781       </sect3>
2782
2783       <sect3>
2784         <title>PreInit Phase</title>
2785
2786         <para>
2787 During this phase the remaining resources should be registered.
2788 <function>PreInit()</function> should call <function>xf86GetEntityInfo()</function>
2789 to obtain a pointer to an <structname>EntityInfoRec</structname> for each entity
2790 it is able to drive and check if any resource are listed in its
2791 <structfield>resources</structfield> field.  If resources registered in the Probe
2792 phase have been rejected in the post-Probe phase
2793 (<structfield>resources</structfield> is non-<constant>NULL</constant>), then the driver should
2794 decide if it can continue without using these or if it should fail.
2795         </para>
2796
2797         <blockquote><para>
2798             <programlisting>
2799     EntityInfoPtr xf86GetEntityInfo(int entityIndex);
2800             </programlisting>
2801             <blockquote><para>
2802       This function returns a pointer to the <structname>EntityInfoRec</structname>
2803       referenced by <parameter>entityIndex</parameter>.  The returned
2804       <structname>EntityInfoRec</structname> should be freed with
2805       <function>xfree()</function> when no longer needed.
2806               </para>
2807
2808             </blockquote></para></blockquote>
2809
2810         <para>
2811 Several functions are provided to simplify resource registration:
2812           <blockquote><para>
2813               <programlisting>
2814     Bool xf86IsEntityPrimary(int entityIndex);
2815               </programlisting>
2816               <blockquote><para>
2817       This function returns <constant>TRUE</constant> if the entity referenced
2818       by <parameter>entityIndex</parameter> is the primary display device (i.e.,
2819       the one initialised at boot time and used in text mode).
2820                 </para>
2821
2822               </blockquote></para></blockquote>
2823
2824           <blockquote><para>
2825               <programlisting>
2826     Bool xf86IsScreenPrimary(ScrnInfoPtr pScrn);
2827               </programlisting>
2828               <blockquote><para>
2829       This function returns <constant>TRUE</constant> if the primary entity
2830       is registered with the screen referenced by
2831       <parameter>pScrn</parameter>.
2832                 </para>
2833
2834               </blockquote></para></blockquote>
2835
2836           <blockquote><para>
2837               <programlisting>
2838     pciVideoPtr xf86GetPciInfoForEntity(int entityIndex);
2839               </programlisting>
2840               <blockquote><para>
2841       This function returns a pointer to the <structname>pciVideoRec</structname>
2842       for the specified entity.  If the entity is not a PCI device,
2843       <constant>NULL</constant> is returned.
2844                 </para>
2845
2846               </blockquote></para></blockquote>
2847         </para>
2848
2849         <para>
2850 The primary function for registration of resources is:
2851           <blockquote><para>
2852               <programlisting>
2853     resPtr xf86RegisterResources(int entityIndex, resList list,
2854                                  int access);
2855               </programlisting>
2856               <blockquote><para>
2857       This function tries to register the resources in
2858       <parameter>list</parameter>.  If list is <constant>NULL</constant> it tries
2859       to determine the resources automatically.  This only works for
2860       entities that provide a generic way to read out the resource ranges
2861       they decode.  So far this is only the case for PCI devices.  By
2862       default the PCI resources are registered as shared
2863       (<constant>ResShared</constant>) if the driver wants to set a different
2864       access type it can do so by specifying the access flags in the
2865       third argument.  A value of <constant>0</constant> means to use the
2866       default settings.  If for any reason the resource broker is not
2867       able to register some of the requested resources the function will
2868       return a pointer to a list of the failed ones.  In this case the
2869       driver may be able to move the resource to different locations.
2870       In case of PCI bus entities this is done by passing the list of
2871       failed resources to <function>xf86ReallocatePciResources()</function>.
2872       When the registration succeeds, the return value is
2873       <constant>NULL</constant>.
2874                 </para>
2875
2876               </blockquote></para></blockquote>
2877           </para>
2878
2879         <blockquote><para>
2880             <programlisting>
2881     resPtr xf86ReallocatePciResources(int entityIndex, resPtr pRes);
2882             </programlisting>
2883             <blockquote><para>
2884       This function takes a list of PCI resources that need to be
2885       reallocated and returns <constant>NULL</constant> when all relocations are
2886       successful.
2887       <function>xf86RegisterResources()</function> should be called again to
2888       register the relocated resources with the broker.
2889       If the reallocation fails, a list of the resources that could not be
2890       relocated is returned.
2891               </para>
2892
2893             </blockquote></para></blockquote>
2894
2895 <para>
2896 Two functions are provided to obtain a resource range of a given type:
2897           <blockquote><para>
2898               <programlisting>
2899     resRange xf86GetBlock(long type, memType size,
2900                           memType window_start, memType window_end,
2901                           memType align_mask, resPtr avoid);
2902               </programlisting>
2903               <blockquote><para>
2904       This function tries to find a block range of size
2905       <parameter>size</parameter> and type <parameter>type</parameter> in a window
2906       bound by <parameter>window_start</parameter> and <parameter>window_end</parameter>
2907       with the alignment specified in <parameter>align_mask</parameter>.
2908       Optionally a list of resource ranges which should be avoided within
2909       the window can be supplied.  On failure a zero-length range of
2910       type <constant>ResEnd</constant> will be returned.
2911                 </para>
2912               </blockquote></para></blockquote>
2913
2914           <blockquote><para>
2915               <programlisting>
2916     resRange xf86GetSparse(long type, memType fixed_bits,
2917                            memType decode_mask, memType address_mask,
2918                            resPtr avoid);
2919               </programlisting>
2920               <blockquote><para>
2921       This function is like the previous one, but attempts to find a
2922       sparse range instead of a block range.  Here three values have to
2923       be specified: the <parameter>address_mask</parameter> which marks all
2924       bits of the mask part of the address, the <parameter>decode_mask</parameter>
2925       which masks out the bits which are hardcoded and are therefore
2926       not available for relocation and the values of the fixed bits.
2927       The function tries to find a base that satisfies the given condition.
2928       If the function fails it will return a zero range of type
2929       <constant>ResEnd</constant>.  Optionally it might be passed a list of
2930       resource ranges to avoid.
2931                 </para>
2932
2933               </blockquote></para></blockquote>
2934         </para>
2935
2936         <para>
2937 Some PCI devices are broken in the sense that they return invalid size
2938 information for a certain resource.  In this case the driver can supply
2939 the correct size and make sure that the resource range allocated for
2940 the card is large enough to hold the address range decoded by the card.
2941 The function <function>xf86FixPciResource()</function> can be used to do this:
2942           <blockquote><para>
2943               <programlisting>
2944     Bool xf86FixPciResource(int entityIndex, unsigned int prt,
2945                             CARD32 alignment, long type);
2946               </programlisting>
2947               <blockquote><para>
2948       This function fixes a PCI resource allocation.  The
2949       <parameter>prt</parameter> parameter contains the number of the PCI base
2950       register that needs to be fixed (<constant>0-5</constant>, and
2951       <constant>6</constant> for the BIOS base register).  The size is
2952       specified by the alignment.  Since PCI resources need to span an
2953       integral range of size <literal remap="tt">2&circ;n</literal>, the alignm      ent also
2954       specifies the number of addresses that will be decoded.  If the
2955       driver specifies a type mask it can override the default type for
2956       PCI resources which is <constant>ResShared</constant>.  The resource
2957       broker needs to know that to find a matching resource range.  This
2958       function should be called before calling
2959       <function>xf86RegisterResources()</function>.  The return value is
2960       <constant>TRUE</constant> when the function succeeds.
2961                 </para>
2962
2963               </blockquote></para></blockquote>
2964
2965           <blockquote><para>
2966               <programlisting>
2967     Bool xf86CheckPciMemBase(pciVideoPtr pPci, memType base);
2968               </programlisting>
2969               <blockquote><para>
2970       This function checks that the memory base address specified matches
2971       one of the PCI base address register values for the given PCI
2972       device.  This is mostly used to check that an externally provided
2973       base address (e.g., from a config file) matches an actual value
2974       allocated to a device.
2975                 </para>
2976
2977               </blockquote></para></blockquote>
2978         </para>
2979
2980         <para>
2981 The driver may replace the generic access control functions for an entity.
2982 This is done with the <function>xf86SetAccessFuncs()</function>:
2983           <blockquote><para>
2984               <programlisting>
2985     void xf86SetAccessFuncs(EntityInfoPtr pEnt,
2986                             xf86SetAccessFuncPtr funcs,
2987                             xf86SetAccessFuncPtr oldFuncs);
2988               </programlisting>
2989      with:
2990               <programlisting>
2991       typedef struct {
2992           xf86AccessPtr mem;
2993           xf86AccessPtr io;
2994           xf86AccessPtr io_mem;
2995       } xf86SetAccessFuncRec, *xf86SetAccessFuncPtr;
2996               </programlisting>
2997               <blockquote><para>
2998       The driver can pass three functions: one for I/O access, one for
2999       memory access and one for combined memory and I/O access.  If the
3000       memory access and combined access functions are identical the
3001       common level assumes that the memory access cannot be controlled
3002       independently of I/O access, if the I/O access function and the
3003       combined access functions are the same it is assumed that I/O can
3004       not be controlled independently.  If memory and I/O have to be
3005       controlled together all three values should be the same.  If a
3006       non <constant>NULL</constant> value is passed as third argument it is
3007       interpreted as an address where to store the old access record.
3008       If the third argument is <constant>NULL</constant> it will be assumed
3009       that the generic access should be enabled before replacing the
3010       access functions.  Otherwise it will be disabled.  The driver may
3011       enable them itself using the returned values.  It should do this
3012       from its replacement access functions as the generic access may
3013       be disabled by the common level on certain occasions.  If replacement
3014       functions are specified they must control all resources of the
3015       specific type registered for the entity.
3016                 </para>
3017
3018               </blockquote></para></blockquote>
3019         </para>
3020
3021         <para>
3022 To find out if a specific resource range conflicts with another
3023 resource the <function>xf86ChkConflict()</function> function may be used:
3024           <blockquote><para>
3025               <programlisting>
3026     memType xf86ChkConflict(resRange *rgp, int entityIndex);
3027               </programlisting>
3028               <blockquote><para>
3029       This function checks if the resource range <parameter>rgp</parameter> of
3030       for the specified entity conflicts with with another resource.
3031       If a conflict is found, the address of the start of the conflict
3032       is returned.  The return value is zero when there is no conflict.
3033                 </para>
3034
3035               </blockquote></para></blockquote>
3036         </para>
3037
3038         <para>
3039 The OPERATING state properties of previously registered fixed resources
3040 can be set with the <function>xf86SetOperatingState()</function> function:
3041           <blockquote><para>
3042               <programlisting>
3043     resPtr xf86SetOperatingState(resList list, int entityIndex,
3044                                  int mask);
3045               </programlisting>
3046               <blockquote><para>
3047       This function is used to set the status of a resource during
3048       OPERATING state.  <parameter>list</parameter> holds a list to which
3049       <parameter>mask</parameter> is to be applied.  The parameter
3050       <parameter>mask</parameter> may have the value <constant>ResUnusedOpr</constant>
3051       and <constant>ResDisableOpr</constant>.  The first one should be used
3052       if a resource isn't used by the driver during OPERATING state
3053       although it is decoded by the device, while the latter one indicates
3054       that the resource is not decoded during OPERATING state.  Note
3055       that the resource ranges have to match those specified during
3056       registration.  If a range has been specified starting at
3057       <literal remap="tt">A</literal> and ending at <literal remap="tt">B</literal> and suppose
3058       <literal remap="tt">C</literal> us a value satisfying
3059       <literal remap="tt">A&nbsp;&lt;&nbsp;C&nbsp;&lt;&nbsp;B</literal> one may not
3060       specify the resource range <literal remap="tt">(A,B)</literal> by splitting it
3061       into two ranges <literal remap="tt">(A,C)</literal> and <literal remap="tt">(C,B)</literal>.
3062                 </para>
3063
3064               </blockquote></para></blockquote>
3065         </para>
3066
3067         <para>
3068 The following two functions are provided for special cases:
3069           <blockquote><para>
3070               <programlisting>
3071     void xf86RemoveEntityFromScreen(ScrnInfoPtr pScrn, int entityIndex);
3072               </programlisting>
3073               <blockquote><para>
3074       This function may be used to remove an entity from a screen.  This
3075       only makes sense if a screen has more than one entity assigned or
3076       the screen is to be deleted.  No test is made if the screen has
3077       any entities left.
3078                 </para>
3079
3080               </blockquote></para></blockquote>
3081
3082           <blockquote><para>
3083               <programlisting>
3084     void xf86DeallocateResourcesForEntity(int entityIndex, long type);
3085               </programlisting>
3086               <blockquote><para>
3087       This function deallocates all resources of a given type registered
3088       for a certain entity from the resource broker list.
3089                 </para>
3090
3091               </blockquote></para></blockquote>
3092         </para>
3093
3094       </sect3>
3095
3096       <sect3>
3097         <title>ScreenInit Phase</title>
3098
3099         <para>
3100 All that is required in this phase is to setup the RAC flags.  Note that
3101 it is also permissible to set these flags up in the PreInit phase.  The
3102 RAC flags are held in the <structfield>racIoFlags</structfield> and <structfield>racMemFlags</structfield> fields of the
3103 <structname>ScrnInfoRec</structname> for each screen.  They specify which graphics operations
3104 might require the use of shared resources.  This can be specified
3105 separately for memory and I/O resources.  The available flags are defined
3106 in <filename>rac/xf86RAC.h</filename>.  They are:
3107
3108           <variablelist>
3109             <varlistentry><term><constant>RAC_FB</constant></term>
3110               <listitem><para>
3111         for framebuffer operations (including hw acceleration)
3112                 </para></listitem></varlistentry>
3113             <varlistentry><term><constant>RAC_CURSOR</constant></term>
3114               <listitem><para>
3115         for Cursor operations
3116         (??? I'm not sure if we need this for SW cursor it depends
3117          on which level the sw cursor is drawn)
3118                 </para></listitem></varlistentry>
3119             <varlistentry><term><constant>RAC_COLORMAP</constant></term>
3120               <listitem><para>
3121         for colormap operations
3122                 </para></listitem></varlistentry>
3123             <varlistentry><term><constant>RAC_VIEWPORT</constant></term>
3124               <listitem><para>
3125         for the call to <function>ChipAdjustFrame()</function>
3126                 </para></listitem></varlistentry>
3127             </variablelist>
3128
3129
3130 The flags are ORed together.
3131         </para>
3132       </sect3>
3133     </sect2>
3134   </sect1>
3135
3136   <sect1 id="options">
3137     <title>Config file <quote>Option</quote> entries</title>
3138
3139     <para>
3140 Option entries are permitted in most sections and subsections of the
3141 config file.  There are two forms of option entries:
3142
3143       <variablelist>
3144         <varlistentry><term>Option "option-name"</term>
3145           <listitem><para>
3146         A boolean option.
3147             </para></listitem></varlistentry>
3148         <varlistentry><term>Option "option-name" "option-value"</term>
3149           <listitem><para>
3150         An option with an arbitrary value.
3151             </para></listitem></varlistentry>
3152       </variablelist>
3153     </para>
3154
3155     <para>
3156 The option entries are handled by the parser, and a list of the parsed
3157 options is included with each of the appropriate data structures that
3158 the drivers have access to.  The data structures used to hold the option
3159 information are opaque to the driver, and a driver must not access the
3160 option data directly.  Instead, the common layer provides a set of
3161 functions that may be used to access, check and manipulate the option
3162 data.
3163     </para>
3164
3165     <para>
3166 First, the low level option handling functions.  In most cases drivers
3167 would not need to use these directly.
3168     </para>
3169
3170     <blockquote><para>
3171         <programlisting>
3172     XF86OptionPtr xf86FindOption(XF86OptionPtr options, const char *name);
3173         </programlisting>
3174         <blockquote><para>
3175       Takes a list of options and an option name, and returns a handle
3176       for the first option entry in the list matching the name.  Returns
3177       <constant>NULL</constant> if no match is found.
3178           </para>
3179
3180         </blockquote></para></blockquote>
3181
3182     <blockquote><para>
3183         <programlisting>
3184     const char *xf86FindOptionValue(XF86OptionPtr options, const char *name);
3185         </programlisting>
3186         <blockquote><para>
3187       Takes a list of options and an option name, and returns the value
3188       associated with the first option entry in the list matching the
3189       name.  If the matching option has no value, an empty string
3190       (<constant>""</constant>) is returned.  Returns <constant>NULL</constant>
3191       if no match is found.
3192           </para>
3193
3194         </blockquote></para></blockquote>
3195
3196     <blockquote><para>
3197         <programlisting>
3198     void xf86MarkOptionUsed(XF86OptionPtr option);
3199         </programlisting>
3200         <blockquote><para>
3201       Takes a handle for an option, and marks that option as used.
3202           </para>
3203
3204         </blockquote></para></blockquote>
3205
3206     <blockquote><para>
3207         <programlisting>
3208     void xf86MarkOptionUsedByName(XF86OptionPtr options, const char *name);
3209         </programlisting>
3210         <blockquote><para>
3211       Takes a list of options and an option name and marks the first
3212       option entry in the list matching the name as used.
3213           </para>
3214
3215         </blockquote></para></blockquote>
3216
3217     <para>
3218 Next, the higher level functions that most drivers would use.
3219     </para>
3220     <blockquote><para>
3221         <programlisting>
3222     void xf86CollectOptions(ScrnInfoPtr pScrn, XF86OptionPtr extraOpts);
3223         </programlisting>
3224         <blockquote><para>
3225       Collect the options from each of the config file sections used by
3226       the screen (<parameter>pScrn</parameter>) and return the merged list as
3227       <structfield>pScrn-&gt;options</structfield>.  This function requires that
3228       <structfield>pScrn-&gt;confScreen</structfield>, <structfield>pScrn-&gt;display</structfield>,
3229       <structfield>pScrn-&gt;monitor</structfield>,
3230       <structfield>pScrn-&gt;numEntities</structfield>, and
3231       <structfield>pScrn-&gt;entityList</structfield> are initialised.
3232       <parameter>extraOpts</parameter> may optionally be set to an additional
3233       list of options to be combined with the others.  The order of
3234       precedence for options is <parameter>extraOpts</parameter>, display,
3235       confScreen, monitor, device.
3236           </para>
3237
3238         </blockquote></para></blockquote>
3239
3240     <blockquote><para>
3241         <programlisting>
3242     void xf86ProcessOptions(int scrnIndex, XF86OptionPtr options,
3243                             OptionInfoPtr optinfo);
3244         </programlisting>
3245         <blockquote><para>
3246       Processes a list of options according to the information in the
3247       array of <structname>OptionInfoRecs</structname> (<parameter>optinfo</parameter>).
3248       The resulting information is stored in the <structfield>value</structfield>
3249       fields of the appropriate <parameter>optinfo</parameter> entries.  The
3250       <structfield>found</structfield> fields are set to <constant>TRUE</constant>
3251       when an option with a value of the correct type if found, and
3252       <constant>FALSE</constant> otherwise.  The <structfield>type</structfield> field
3253       is used to determine the expected value type for each option.
3254       Each option in the list of options for which there is a name match
3255       (but not necessarily a value type match) is marked as used.
3256       Warning messages are printed when option values don't match the
3257       types specified in the optinfo data.
3258           </para>
3259
3260           <para>
3261       NOTE: If this function is called before a driver's screen number
3262       is known (e.g., from the <function>ChipProbe()</function> function) a
3263       <parameter>scrnIndex</parameter> value of <constant>-1</constant> should be
3264       used.
3265           </para>
3266
3267           <para>
3268       NOTE 2: Given that this function stores into the
3269       <literal remap="tt">OptionInfoRecs</literal> pointed to by <parameter>optinfo</parameter>,
3270       the caller should ensure the <literal remap="tt">OptionInfoRecs</literal> are
3271       (re-)initialised before the call, especially if the caller expects
3272       to use the predefined option values as defaults.
3273           </para>
3274
3275           <para>
3276       The <structname>OptionInfoRec</structname> is defined as follows:
3277
3278             <programlisting>
3279       typedef struct {
3280           double freq;
3281           int units;
3282       } OptFrequency;
3283
3284       typedef union {
3285           unsigned long       num;
3286           char *              str;
3287           double              realnum;
3288           Bool                bool;
3289           OptFrequency        freq;
3290       } ValueUnion;
3291
3292       typedef enum {
3293           OPTV_NONE = 0,
3294           OPTV_INTEGER,
3295           OPTV_STRING,  /* a non-empty string */
3296           OPTV_ANYSTR,  /* Any string, including an empty one */
3297           OPTV_REAL,
3298           OPTV_BOOLEAN,
3299           OPTV_PERCENT,
3300           OPTV_FREQ
3301       } OptionValueType;
3302
3303       typedef enum {
3304           OPTUNITS_HZ = 1,
3305           OPTUNITS_KHZ,
3306           OPTUNITS_MHZ
3307       } OptFreqUnits;
3308
3309       typedef struct {
3310           int                 token;
3311           const char*         name;
3312           OptionValueType     type;
3313           ValueUnion          value;
3314           Bool                found;
3315       } OptionInfoRec, *OptionInfoPtr;
3316             </programlisting>
3317           </para>
3318           <para>
3319       <constant>OPTV_FREQ</constant> can be used for options values that are
3320       frequencies.  These values are a floating point number with an
3321       optional unit name appended.  The unit name can be one of "Hz",
3322       "kHz", "k", "MHz", "M".  The multiplier associated with the unit
3323       is stored in <structfield>freq.units</structfield>, and the scaled frequency
3324       is stored in <structfield>freq.freq</structfield>.  When no unit is specified,
3325       <structfield>freq.units</structfield> is set to <constant>0</constant>, and
3326       <structfield>freq.freq</structfield> is unscaled.
3327           </para>
3328
3329           <para>
3330       <constant>OPTV_PERCENT</constant> can be used for option values that are
3331       specified in percent (e.g. "20%"). These values are a floating point
3332       number with a percent sign appended. If the percent sign is missing,
3333       the parser will fail to match the value.
3334           </para>
3335
3336           <para>
3337       Typical usage is to setup an array of
3338       <structname>OptionInfoRec</structname>s with all fields initialised.
3339       The <structfield>value</structfield> and <structfield>found</structfield> fields get
3340       set by <function>xf86ProcessOptions()</function>.  For cases where the
3341       value parsing is more complex, the driver should specify
3342       <constant>OPTV_STRING</constant>, and parse the string itself.  An
3343       example of using this option handling is included in the
3344       <link linkend="sample">Sample Driver</link> section.
3345           </para>
3346
3347         </blockquote></para></blockquote>
3348
3349     <blockquote><para>
3350         <programlisting>
3351     void xf86ShowUnusedOptions(int scrnIndex, XF86OptionPtr options);
3352         </programlisting>
3353         <blockquote><para>
3354       Prints out warning messages for each option in the list of options
3355       that isn't marked as used.  This is intended to show options that
3356       the driver hasn't recognised.  It would normally be called near
3357       the end of the <function>ChipScreenInit()</function> function, but only
3358       when <code>serverGeneration&nbsp;==&nbsp;1</code>
3359           </para>
3360         </blockquote></para></blockquote>
3361
3362     <blockquote><para>
3363         <programlisting>
3364     OptionInfoPtr xf86TokenToOptinfo(const OptionInfoRec *table,
3365                                      int token);
3366         </programlisting>
3367         <blockquote><para>
3368       Returns a pointer to the <structname>OptionInfoRec</structname> in
3369       <parameter>table</parameter> with a token field matching
3370       <parameter>token</parameter>.  Returns <constant>NULL</constant> if no match
3371       is found.
3372           </para>
3373
3374         </blockquote></para></blockquote>
3375
3376     <blockquote><para>
3377         <programlisting>
3378     Bool xf86IsOptionSet(const OptionInfoRec *table, int token);
3379         </programlisting>
3380         <blockquote><para>
3381       Returns the <literal remap="tt">found</literal> field of the
3382       <structname>OptionInfoRec</structname> in <parameter>table</parameter> with a
3383       <structfield>token</structfield> field matching <parameter>token</parameter>.  This
3384       can be used for options of all types.  Note that for options of
3385       type <constant>OPTV_BOOLEAN</constant>, it isn't sufficient to check
3386       this to determine the value of the option.  Returns
3387       <constant>FALSE</constant> if no match is found.
3388           </para>
3389
3390         </blockquote></para></blockquote>
3391
3392     <blockquote><para>
3393         <programlisting>
3394     char *xf86GetOptValString(const OptionInfoRec *table, int token);
3395         </programlisting>
3396         <blockquote><para>
3397       Returns the <structfield>value.str</structfield> field of the
3398       <structname>OptionInfoRec</structname> in <parameter>table</parameter> with a
3399       token field matching <parameter>token</parameter>.  Returns
3400       <constant>NULL</constant> if no match is found.
3401           </para>
3402
3403         </blockquote></para></blockquote>
3404
3405           <blockquote><para>
3406               <programlisting>
3407     Bool xf86GetOptValInteger(const OptionInfoRec *table, int token,
3408
3409                                 int *value);
3410               </programlisting>
3411               <blockquote><para>
3412       Returns via <parameter>*value</parameter> the <structfield>value.num</structfield>
3413       field of the <structname>OptionInfoRec</structname> in <parameter>table</parameter>
3414       with a <structfield>token</structfield> field matching <parameter>token</parameter>.
3415       <parameter>*value</parameter> is only changed when a match is found so
3416       it can be safely initialised with a default prior to calling this
3417       function.  The function return value is as for
3418       <function>xf86IsOptionSet()</function>.
3419           </para>
3420
3421         </blockquote></para></blockquote>
3422
3423     <blockquote><para>
3424         <programlisting>
3425     Bool xf86GetOptValULong(const OptionInfoRec *table, int token,
3426                             unsigned long *value);
3427         </programlisting>
3428         <blockquote><para>
3429       Like <function>xf86GetOptValInteger()</function>, except the value is
3430       treated as an <type>unsigned long</type>.
3431           </para>
3432
3433         </blockquote></para></blockquote>
3434
3435     <blockquote><para>
3436         <programlisting>
3437     Bool xf86GetOptValReal(const OptionInfoRec *table, int token,
3438                            double *value);
3439         </programlisting>
3440         <blockquote><para>
3441       Like <function>xf86GetOptValInteger()</function>, except that
3442       <structfield>value.realnum</structfield> is used.
3443           </para>
3444
3445         </blockquote></para></blockquote>
3446
3447     <blockquote><para>
3448         <programlisting>
3449     Bool xf86GetOptValFreq(const OptionInfoRec *table, int token,
3450                            OptFreqUnits expectedUnits, double *value);
3451         </programlisting>
3452         <blockquote><para>
3453       Like <function>xf86GetOptValInteger()</function>, except that the
3454       <structfield>value.freq</structfield> data is returned.  The frequency value
3455       is scaled to the units indicated by <parameter>expectedUnits</parameter>.
3456       The scaling is exact when the units were specified explicitly in
3457       the option's value.  Otherwise, the <parameter>expectedUnits</parameter>
3458       field is used as a hint when doing the scaling.  In this case,
3459       values larger than <constant>1000</constant> are assumed to have be
3460       specified in the next smallest units.  For example, if the Option
3461       value is "10000" and expectedUnits is <constant>OPTUNITS_MHZ</constant>,
3462       the value returned is <constant>10</constant>.
3463           </para>
3464
3465         </blockquote></para></blockquote>
3466
3467     <blockquote><para>
3468       <programlisting>
3469     Bool xf86GetOptValBool(const OptionInfoRec *table, int token, Bool *value);
3470       </programlisting>
3471         <blockquote><para>
3472       This function is used to check boolean options
3473       (<constant>OPTV_BOOLEAN</constant>).  If the function return value is
3474       <constant>FALSE</constant>, it means the option wasn't set.  Otherwise
3475       <parameter>*value</parameter> is set to the boolean value indicated by
3476       the option's value.  No option <parameter>value</parameter> is interpreted
3477       as <constant>TRUE</constant>.  Option values meaning <constant>TRUE</constant>
3478       are "1", "yes", "on", "true", and option values meaning
3479       <constant>FALSE</constant> are "0", "no", "off", "false".  Option names
3480       both with the "no" prefix in their names, and with that prefix
3481       removed are also checked and handled in the obvious way.
3482       <parameter>*value</parameter> is not changed when the option isn't present.
3483       It should normally be set to a default value before calling this
3484       function.
3485           </para>
3486
3487         </blockquote></para></blockquote>
3488
3489     <blockquote><para>
3490         <programlisting>
3491     Bool xf86ReturnOptValBool(const OptionInfoRec *table, int token, Bool def);
3492         </programlisting>
3493         <blockquote><para>
3494       This function is used to check boolean options
3495       (<constant>OPTV_BOOLEAN</constant>).  If the option is set, its value
3496       is returned.  If the options is not set, the default value specified
3497       by <parameter>def</parameter> is returned.  The option interpretation is
3498       the same as for <function>xf86GetOptValBool()</function>.
3499           </para>
3500
3501         </blockquote></para></blockquote>
3502
3503     <blockquote><para>
3504         <programlisting>
3505     int xf86NameCmp(const char *s1, const char *s2);
3506         </programlisting>
3507         <blockquote><para>
3508       This function should be used when comparing strings from the config
3509       file with expected values.  It works like <function>strcmp()</function>,
3510       but is not case sensitive and space, tab, and <quote><literal>_</literal></quote> characters
3511       are ignored in the comparison.  The use of this function isn't
3512       restricted to parsing option values.  It may be used anywhere
3513       where this functionality required.
3514           </para>
3515
3516         </blockquote></para></blockquote>
3517   </sect1>
3518
3519   <sect1>
3520     <title>Modules, Drivers, Include Files and Interface Issues</title>
3521
3522     <para>
3523 NOTE: this section is incomplete.
3524     </para>
3525
3526
3527     <sect2>
3528       <title>Include files</title>
3529
3530       <para>
3531 The following include files are typically required by video drivers:
3532
3533         <blockquote><para>
3534   All drivers should include these:
3535             <literallayout><filename>
3536     "xf86.h"
3537     "xf86_OSproc.h"
3538     "xf86_ansic.h"
3539     "xf86Resources.h"
3540             </filename></literallayout>
3541   Wherever inb/outb (and related things) are used the following should be
3542   included:
3543             <literallayout><filename>
3544     "compiler.h"
3545               </filename></literallayout>
3546   Note: in drivers, this must be included after <filename>"xf86_ansic.h"</filename>.
3547           </para>
3548
3549           <para>
3550   Drivers that need to access the PCI config space need this:
3551             <literallayout><filename>
3552     "xf86Pci.h"
3553               </filename></literallayout>
3554           </para>
3555
3556           <para>
3557   Drivers that initialise a SW cursor need this:
3558             <literallayout><filename>
3559     "mipointer.h"
3560               </filename></literallayout>
3561           </para>
3562
3563           <para>
3564   All drivers implementing backing store need this:
3565             <literallayout><filename>
3566     "mibstore.h"
3567               </filename></literallayout>
3568           </para>
3569
3570           <para>
3571   All drivers using the mi colourmap code need this:
3572             <literallayout><filename>
3573     "micmap.h"
3574               </filename></literallayout>
3575           </para>
3576
3577           <para>
3578   If a driver uses the vgahw module, it needs this:
3579             <literallayout><filename>
3580     "vgaHW.h"
3581               </filename></literallayout>
3582           </para>
3583
3584           <para>
3585   Drivers supporting VGA or Hercules monochrome screens need:
3586             <literallayout><filename>
3587     "xf1bpp.h"
3588               </filename></literallayout>
3589           </para>
3590
3591           <para>
3592   Drivers supporting VGA or EGC 16-colour screens need:
3593             <literallayout><filename>
3594     "xf4bpp.h"
3595               </filename></literallayout>
3596           </para>
3597
3598           <para>
3599   Drivers using cfb need:
3600             <programlisting>
3601     #define PSZ 8
3602     #include "cfb.h"
3603     #undef PSZ
3604             </programlisting>
3605           </para>
3606
3607           <para>
3608   Drivers supporting bpp 16, 24 or 32 with cfb need one or more of:
3609             <literallayout><filename>
3610     "cfb16.h"
3611     "cfb24.h"
3612     "cfb32.h"
3613               </filename></literallayout>
3614           </para>
3615
3616           <para>
3617   If a driver uses the fb manager, it needs this:
3618             <literallayout><filename>
3619     "xf86fbman.h"
3620               </filename></literallayout>
3621           </para>
3622         </blockquote>
3623       </para>
3624
3625       <para>
3626 Non-driver modules should include <filename>"xf86_ansic.h"</filename> to get the correct
3627 wrapping of ANSI C/libc functions.
3628       </para>
3629
3630       <para>
3631 All modules must NOT include any system include files, or the following:
3632
3633         <literallayout><filename>
3634     "xf86Priv.h"
3635     "xf86Privstr.h"
3636     "xf86_OSlib.h"
3637     "Xos.h"
3638           </filename></literallayout>
3639       </para>
3640
3641       <para>
3642 In addition, "xf86_libc.h" must not be included explicitly.  It is
3643 included implicitly by "xf86_ansic.h".
3644       </para>
3645
3646     </sect2>
3647   </sect1>
3648
3649   <sect1>
3650     <title>Offscreen Memory Manager</title>
3651
3652     <para>
3653 Management of offscreen video memory may be handled by the XFree86
3654 framebuffer manager.  Once the offscreen memory manager is running,
3655 drivers or extensions may allocate, free or resize areas of offscreen
3656 video memory using the following functions (definitions taken from
3657 <filename>xf86fbman.h</filename>):
3658
3659       <programlisting>
3660     typedef struct _FBArea {
3661         ScreenPtr    pScreen;
3662         BoxRec       box;
3663         int          granularity;
3664         void         (*MoveAreaCallback)(struct _FBArea*, struct _FBArea*)
3665         void         (*RemoveAreaCallback)(struct _FBArea*)
3666         DevUnion     devPrivate;
3667     } FBArea, *FBAreaPtr;
3668
3669     typedef void (*MoveAreaCallbackProcPtr)(FBAreaPtr from, FBAreaPtr to)
3670     typedef void (*RemoveAreaCallbackProcPtr)(FBAreaPtr)
3671
3672     FBAreaPtr xf86AllocateOffscreenArea (
3673         ScreenPtr pScreen,
3674         int width, int height,
3675         int granularity,
3676         MoveAreaCallbackProcPtr MoveAreaCallback,
3677         RemoveAreaCallbackProcPtr RemoveAreaCallback,
3678         pointer privData
3679     )
3680
3681     void xf86FreeOffscreenArea (FBAreaPtr area)
3682
3683     Bool xf86ResizeOffscreenArea (
3684         FBAreaPtr area
3685         int w, int h
3686     )
3687       </programlisting>
3688     </para>
3689
3690     <para>
3691 The function:
3692       <programlisting>
3693     Bool xf86FBManagerRunning(ScreenPtr pScreen);
3694       </programlisting>
3695
3696 can be used by an extension to check if the driver has initialized
3697 the memory manager.  The manager is not available if this returns
3698 <constant>FALSE</constant> and the functions above will all fail.
3699     </para>
3700
3701
3702     <para>
3703 <function>xf86AllocateOffscreenArea()</function> can be used to request a
3704 rectangle of dimensions <parameter>width</parameter>&nbsp;&times;&nbsp;<parameter>height</parameter>
3705 (in pixels) from unused offscreen memory.  <parameter>granularity</parameter>
3706 specifies that the leftmost edge of the rectangle must lie on some
3707 multiple of <parameter>granularity</parameter> pixels.  A granularity of zero
3708 means the same thing as a granularity of one - no alignment preference.
3709 A <parameter>MoveAreaCallback</parameter> can be provided to notify the requester
3710 when the offscreen area is moved.  If no <parameter>MoveAreaCallback</parameter>
3711 is supplied then the area is considered to be immovable.  The
3712 <parameter>privData</parameter> field will be stored in the manager's internal
3713 structure for that allocated area and will be returned to the requester
3714 in the <parameter>FBArea</parameter> passed via the
3715 <parameter>MoveAreaCallback</parameter>.  An optional
3716 <parameter>RemoveAreaCallback</parameter> is provided.  If the driver provides
3717 this it indicates that the area should be allocated with a lower priority.
3718 Such an area may be removed when a higher priority request (one that
3719 doesn't have a <parameter>RemoveAreaCallback</parameter>) is made.  When this
3720 function is called, the driver will have an opportunity to do whatever
3721 cleanup it needs to do to deal with the loss of the area, but it must
3722 finish its cleanup before the function exits since the offscreen memory
3723 manager will free the area immediately after.
3724     </para>
3725
3726     <para>
3727 <function>xf86AllocateOffscreenArea()</function> returns <constant>NULL</constant>
3728 if it was unable to allocate the requested area.  When no longer needed,
3729 areas should be freed with <function>xf86FreeOffscreenArea()</function>.
3730     </para>
3731
3732     <para>
3733 <function>xf86ResizeOffscreenArea()</function> resizes an existing
3734 <literal remap="tt">FBArea</literal>.  <function>xf86ResizeOffscreenArea()</function>
3735 returns <constant>TRUE</constant> if the resize was successful.  If
3736 <function>xf86ResizeOffscreenArea()</function> returns <constant>FALSE</constant>,
3737 the original <literal remap="tt">FBArea</literal> is left unmodified.  Resizing an
3738 area maintains the area's original <literal remap="tt">granularity</literal>,
3739 <literal remap="tt">devPrivate</literal>, and <literal remap="tt">MoveAreaCallback</literal>.
3740 <function>xf86ResizeOffscreenArea()</function> has considerably less overhead
3741 than freeing the old area then reallocating the new size, so it should
3742 be used whenever possible.
3743     </para>
3744
3745     <para>
3746 The function:
3747       <programlisting>
3748     Bool xf86QueryLargestOffscreenArea(
3749       ScreenPtr pScreen,
3750       int *width, int *height,
3751       int granularity,
3752       int preferences,
3753       int priority
3754     );
3755         </programlisting>
3756
3757 is provided to query the width and height of the largest single
3758 <structname>FBArea</structname> allocatable given a particular priority.
3759 <parameter>preferences</parameter> can be one of the following to indicate
3760 whether width, height or area should be considered when determining
3761 which is the largest single <structname>FBArea</structname> available.
3762
3763       <programlisting>
3764   FAVOR_AREA_THEN_WIDTH
3765   FAVOR_AREA_THEN_HEIGHT
3766   FAVOR_WIDTH_THEN_AREA
3767   FAVOR_HEIGHT_THEN_AREA
3768       </programlisting>
3769     </para>
3770
3771     <para>
3772 <parameter>priority</parameter> is one of the following:
3773
3774       <blockquote>
3775         <para>
3776   <constant>PRIORITY_LOW</constant>
3777           <blockquote><para>
3778      Return the largest block available without stealing anyone else's
3779      space.  This corresponds to the priority of allocating a
3780      <structname>FBArea</structname> when a <function>RemoveAreaCallback</function>
3781      is provided.
3782             </para></blockquote>
3783         </para>
3784
3785         <para>
3786    <constant>PRIORITY_NORMAL</constant>
3787           <blockquote><para>
3788      Return the largest block available if it is acceptable to steal a
3789      lower priority area from someone.  This corresponds to the priority
3790      of allocating a <structname>FBArea</structname> without providing a
3791      <function>RemoveAreaCallback</function>.
3792             </para></blockquote>
3793         </para>
3794
3795         <para>
3796     <constant>PRIORITY_EXTREME</constant>
3797           <blockquote><para>
3798      Return the largest block available if all <structname>FBArea</structname>s
3799      that aren't locked down were expunged from memory first.  This
3800      corresponds to any allocation made directly after a call to
3801      <function>xf86PurgeUnlockedOffscreenAreas()</function>.
3802             </para></blockquote>
3803         </para>
3804
3805       </blockquote>
3806     </para>
3807
3808
3809     <para>
3810 The function:
3811
3812       <programlisting>
3813     Bool xf86PurgeUnlockedOffscreenAreas(ScreenPtr pScreen);
3814       </programlisting>
3815
3816 is provided as an extreme method to free up offscreen memory.  This
3817 will remove all removable <structname>FBArea</structname> allocations.
3818     </para>
3819
3820
3821     <para>
3822 Initialization of the XFree86 framebuffer manager is done via
3823
3824       <programlisting>
3825     Bool xf86InitFBManager(ScreenPtr pScreen, BoxPtr FullBox);
3826       </programlisting>
3827
3828 <parameter>FullBox</parameter> represents the area of the framebuffer that the
3829 manager is allowed to manage.  This is typically a box with a width of
3830 <structfield>pScrn-&gt;displayWidth</structfield> and a height of as many lines as
3831 can be fit within the total video memory, however, the driver can reserve
3832 areas at the extremities by passing a smaller area to the manager.
3833     </para>
3834   </sect1>
3835
3836   <sect1 id="cmap">
3837     <title>Colormap Handling</title>
3838
3839     <para>
3840 A generic colormap handling layer is provided within the XFree86 common
3841 layer.  This layer takes care of most of the details, and only requires
3842 a function from the driver that loads the hardware palette when required.
3843 To use the colormap layer, a driver calls the
3844 <function>xf86HandleColormaps()</function> function.
3845
3846       <blockquote><para>
3847           <programlisting>
3848     Bool xf86HandleColormaps(ScreenPtr pScreen, int maxColors,
3849                              int sigRGBbits, LoadPaletteFuncPtr loadPalette,
3850                              SetOverscanFuncPtr setOverscan,
3851                              unsigned int flags);
3852           </programlisting>
3853           <blockquote><para>
3854       This function must be called after the default colormap has been
3855       initialised.  The <structfield>pScrn-&gt;gamma</structfield> field must also
3856       be initialised, preferably by calling <function>xf86SetGamma()</function>.
3857       <parameter>maxColors</parameter> is the number of entries in the palette.
3858       <parameter>sigRGBbits</parameter> is the size in bits of each color
3859       component in the DAC's palette.  <parameter>loadPalette</parameter>
3860       is a driver-provided function for loading a colormap into the
3861       hardware, and is described below.  <parameter>setOverscan</parameter> is
3862       an optional function that may be provided when the overscan color
3863       is an index from the standard LUT and when it needs to be adjusted
3864       to keep it as close to black as possible.  The
3865       <parameter>setOverscan</parameter> function programs the overscan index.
3866       It shouldn't normally be used for depths other than 8.
3867       <parameter>setOverscan</parameter> should be set to <constant>NULL</constant>
3868       when it isn't needed.  <parameter>flags</parameter> may be set to the
3869       following (which may be ORed together):
3870
3871               <variablelist>
3872                 <varlistentry>
3873                   <term><constant>CMAP_PALETTED_TRUECOLOR</constant></term>
3874                   <listitem><para>
3875                                     the TrueColor visual is paletted and is
3876                                     just a special case of DirectColor.
3877                                     This flag is only valid for
3878                                     <code>bpp&nbsp;&gt;&nbsp;8</code>.
3879
3880                     </para></listitem></varlistentry>
3881                 <varlistentry>
3882                   <term><constant>CMAP_RELOAD_ON_MODE_SWITCH</constant></term>
3883                   <listitem><para>
3884                                     reload the colormap automatically
3885                                     after mode switches.  This is useful
3886                                     for when the driver is resetting the
3887                                     hardware during mode switches and
3888                                     corrupting or erasing the hardware
3889                                     palette.
3890
3891                     </para></listitem></varlistentry>
3892                 <varlistentry>
3893                   <term><constant>CMAP_LOAD_EVEN_IF_OFFSCREEN</constant></term>
3894                   <listitem><para>
3895                                     reload the colormap even if the screen
3896                                     is switched out of the server's VC.
3897                                     The palette is <emphasis>not</emphasis> reloaded when
3898                                     the screen is switched back in, nor after
3899                                     mode switches.  This is useful when the
3900                                     driver needs to keep track of palette
3901                                     changes.
3902
3903                     </para></listitem></varlistentry>
3904               </variablelist>
3905             </para>
3906
3907             <para>
3908       The colormap layer normally reloads the palette after VT enters so it
3909       is not necessary for the driver to save and restore the palette
3910       when switching VTs.  The driver must, however, still save the
3911       initial palette during server start up and restore it during
3912       server exit.
3913             </para>
3914
3915           </blockquote></para></blockquote>
3916
3917       <blockquote><para>
3918           <programlisting>
3919     void LoadPalette(ScrnInfoPtr pScrn, int numColors, int *indices,
3920                      LOCO *colors, VisualPtr pVisual);
3921           </programlisting>
3922           <blockquote><para>
3923       <function>LoadPalette()</function> is a driver-provided function for
3924       loading a colormap into hardware.  <parameter>colors</parameter> is the
3925       array of RGB values that represent the full colormap.
3926       <parameter>indices</parameter> is a list of index values into the colors
3927       array.  These indices indicate the entries that need to be updated.
3928       <parameter>numColors</parameter> is the number of the indices to be
3929       updated.
3930             </para>
3931
3932           </blockquote></para></blockquote>
3933
3934       <blockquote><para>
3935           <programlisting>
3936     void SetOverscan(ScrnInfoPtr pScrn, int overscan);
3937           </programlisting>
3938           <blockquote><para>
3939       <function>SetOverscan()</function> is a driver-provided function for
3940       programming the <parameter>overscan</parameter> index.  As described
3941       above, it is normally only appropriate for LUT modes where all
3942       colormap entries are available for the display, but where one of
3943       them is also used for the overscan (typically 8bpp for VGA compatible
3944       LUTs).  It isn't required in cases where the overscan area is
3945       never visible.
3946             </para>
3947
3948           </blockquote></para>
3949       </blockquote></para>
3950
3951   </sect1>
3952
3953   <sect1>
3954     <title>DPMS Extension</title>
3955
3956     <para>
3957 Support code for the DPMS extension is included in the XFree86 common layer.
3958 This code provides an interface between the main extension code, and a means
3959 for drivers to initialise DPMS when they support it.  One function is
3960 available to drivers to do this initialisation, and it is always available,
3961 even when the DPMS extension is not supported by the core server (in
3962 which case it returns a failure result).
3963     </para>
3964
3965     <blockquote><para>
3966         <programlisting>
3967     Bool xf86DPMSInit(ScreenPtr pScreen, DPMSSetProcPtr set, int flags);
3968         </programlisting>
3969         <blockquote><para>
3970       This function registers a driver's DPMS level programming function
3971       <parameter>set</parameter>.  It also checks
3972       <structfield>pScrn-&gt;options</structfield> for the "dpms" option, and when
3973       present marks DPMS as being enabled for that screen.  The
3974       <parameter>set</parameter> function is called whenever the DPMS level
3975       changes, and is used to program the requested level.
3976       <parameter>flags</parameter> is currently not used, and should be
3977       <constant>0</constant>.  If the initialisation fails for any reason,
3978       including when there is no DPMS support in the core server, the
3979       function returns <constant>FALSE</constant>.
3980           </para>
3981
3982         </blockquote></para></blockquote>
3983
3984
3985     <para>
3986 Drivers that implement DPMS support must provide the following function,
3987 that gets called when the DPMS level is changed:
3988
3989
3990       <blockquote><para>
3991           <programlisting>
3992     void ChipDPMSSet(ScrnInfoPtr pScrn, int level, int flags);
3993           </programlisting>
3994           <blockquote><para>
3995       Program the DPMS level specified by <parameter>level</parameter>.  Valid
3996       values of <parameter>level</parameter> are <constant>DPMSModeOn</constant>,
3997       <constant>DPMSModeStandby</constant>, <constant>DPMSModeSuspend</constant>,
3998       <constant>DPMSModeOff</constant>.  These values are defined in
3999       <filename>"extensions/dpms.h"</filename>.
4000             </para>
4001
4002           </blockquote></para></blockquote>
4003     </para>
4004
4005   </sect1>
4006
4007   <sect1>
4008     <title>DGA Extension</title>
4009
4010     <para>
4011 Drivers can support the XFree86 Direct Graphics Architecture (DGA) by
4012 filling out a structure of function pointers and a list of modes and
4013 passing them to DGAInit.
4014     </para>
4015
4016     <blockquote><para>
4017         <programlisting>
4018     Bool DGAInit(ScreenPtr pScreen, DGAFunctionPtr funcs,
4019                  DGAModePtr modes, int num);
4020
4021 /** The DGAModeRec **/
4022
4023 typedef struct {
4024   int num;
4025   DisplayModePtr mode;
4026   int flags;
4027   int imageWidth;
4028   int imageHeight;
4029   int pixmapWidth;
4030   int pixmapHeight;
4031   int bytesPerScanline;
4032   int byteOrder;
4033   int depth;
4034   int bitsPerPixel;
4035   unsigned long red_mask;
4036   unsigned long green_mask;
4037   unsigned long blue_mask;
4038   int viewportWidth;
4039   int viewportHeight;
4040   int xViewportStep;
4041   int yViewportStep;
4042   int maxViewportX;
4043   int maxViewportY;
4044   int viewportFlags;
4045   int offset;
4046   unsigned char *address;
4047   int reserved1;
4048   int reserved2;
4049 } DGAModeRec, *DGAModePtr;
4050         </programlisting>
4051
4052         <variablelist>
4053           <varlistentry>
4054             <term><structfield>num</structfield></term>
4055             <listitem><para>
4056          Can be ignored.  The DGA DDX will assign these numbers.
4057               </para></listitem></varlistentry>
4058
4059           <varlistentry>
4060             <term><structfield>mode</structfield></term>
4061             <listitem><para>
4062         A pointer to the <structname>DisplayModeRec</structname> for this mode.
4063               </para></listitem></varlistentry>
4064
4065           <varlistentry>
4066             <term><structfield>flags</structfield></term>
4067               <listitem><para>
4068         The following flags are defined and may be OR'd together:
4069
4070                   <variablelist>
4071                     <varlistentry>
4072                       <term><constant>DGA_CONCURRENT_ACCESS</constant></term>
4073                       <listitem><para>
4074             Indicates that the driver supports concurrent graphics
4075             accelerator and linear framebuffer access.
4076
4077                         </para></listitem></varlistentry>
4078
4079                     <varlistentry>
4080                       <term><constant>DGA_FILL_RECT
4081                           DGA_BLIT_RECT
4082                           DGA_BLIT_RECT_TRANS</constant></term>
4083                       <listitem><para>
4084             Indicates that the driver supports the FillRect, BlitRect
4085             or BlitTransRect functions in this mode.
4086
4087                         </para></listitem></varlistentry>
4088
4089                     <varlistentry>
4090                       <term><constant>DGA_PIXMAP_AVAILABLE</constant></term>
4091                       <listitem><para>
4092             Indicates that Xlib may be used on the framebuffer.
4093             This flag will usually be set unless the driver wishes
4094             to prohibit this for some reason.
4095
4096                         </para></listitem></varlistentry>
4097
4098                     <varlistentry>
4099                       <term><constant>DGA_INTERLACED
4100                           DGA_DOUBLESCAN</constant></term>
4101                       <listitem><para>
4102             Indicates that these are interlaced or double scan modes.
4103
4104                         </para></listitem></varlistentry>
4105                   </variablelist>
4106                 </para></listitem></varlistentry>
4107
4108           <varlistentry>
4109             <term><structfield>imageWidth
4110                 imageHeight</structfield></term>
4111             <listitem><para>
4112                     These are the dimensions of the linear framebuffer
4113                      accessible by the client.
4114
4115               </para></listitem></varlistentry>
4116
4117           <varlistentry>
4118             <term><structfield>pixmapWidth
4119                 pixmapHeight</structfield></term>
4120             <listitem><para>
4121                      These are the dimensions of the area of the
4122                      framebuffer accessible by the graphics accelerator.
4123
4124               </para></listitem></varlistentry>
4125
4126           <varlistentry>
4127             <term><structfield>bytesPerScanline</structfield></term>
4128             <listitem><para>
4129                       Pitch of the framebuffer in bytes.
4130
4131               </para></listitem></varlistentry>
4132
4133           <varlistentry>
4134             <term><structfield>byteOrder</structfield></term>
4135             <listitem><para>
4136                      Usually the same as
4137                      <structfield>pScrn-&gt;imageByteOrder</structfield>.
4138
4139               </para></listitem></varlistentry>
4140
4141           <varlistentry>
4142             <term><structfield>depth</structfield></term>
4143             <listitem><para>
4144                      The depth of the framebuffer in this mode.
4145
4146               </para></listitem></varlistentry>
4147
4148           <varlistentry>
4149             <term><structfield>bitsPerPixel</structfield></term>
4150             <listitem><para>
4151                       The number of bits per pixel in this mode.
4152
4153               </para></listitem></varlistentry>
4154
4155           <varlistentry>
4156             <term><structfield>red_mask</structfield></term>
4157             <term><structfield>green_mask</structfield></term>
4158             <term><structfield>blue_mask</structfield></term>
4159             <listitem><para>
4160                       The RGB masks for this mode, if applicable.
4161
4162               </para></listitem></varlistentry>
4163
4164           <varlistentry>
4165             <term><structfield>viewportWidth</structfield></term>
4166             <term><structfield>viewportHeight</structfield></term>
4167             <listitem><para>
4168                       Dimensions of the visible part of the framebuffer.
4169                       Usually <structfield>mode-&gt;HDisplay</structfield> and
4170                       <structfield>mode-&gt;VDisplay</structfield>.
4171
4172               </para></listitem></varlistentry>
4173
4174           <varlistentry>
4175             <term><structfield>xViewportStep
4176                 yViewportStep</structfield></term>
4177             <listitem><para>
4178                      The granularity of x and y viewport positions that
4179                      the driver supports in this mode.
4180
4181               </para></listitem></varlistentry>
4182
4183           <varlistentry>
4184             <term><structfield>maxViewportX
4185                 maxViewportY</structfield></term>
4186             <listitem><para>
4187                       The maximum viewport position supported by the
4188                        driver in this mode.
4189               </para></listitem></varlistentry>
4190
4191           <varlistentry>
4192             <term><structfield>viewportFlags</structfield></term>
4193             <listitem><para>
4194                      The following may be OR'd together:
4195
4196                 <variablelist>
4197                   <varlistentry>
4198                     <term><constant>DGA_FLIP_IMMEDIATE</constant></term>
4199                     <listitem><para>
4200                 The driver supports immediate viewport changes.
4201                       </para></listitem></varlistentry>
4202
4203                   <varlistentry>
4204                     <term><constant>DGA_FLIP_RETRACE</constant></term>
4205
4206                     <listitem><para>
4207                 The driver supports viewport changes at retrace.
4208                       </para></listitem></varlistentry>
4209                   </variablelist>
4210               </para></listitem></varlistentry>
4211
4212           <varlistentry>
4213             <term><structfield>offset</structfield></term>
4214             <listitem><para>
4215                 The offset into the linear framebuffer that corresponds to
4216                 pixel (0,0) for this mode.
4217               </para></listitem></varlistentry>
4218
4219           <varlistentry>
4220             <term><structfield>address</structfield></term>
4221             <listitem><para>
4222                 The virtual address of the framebuffer as mapped by the driver.
4223                 This is needed when DGA_PIXMAP_AVAILABLE is set.
4224               </para></listitem></varlistentry>
4225
4226         </variablelist>
4227
4228         <programlisting>
4229 /** The DGAFunctionRec **/
4230
4231 typedef struct {
4232   Bool (*OpenFramebuffer)(
4233        ScrnInfoPtr pScrn,
4234        char **name,
4235        unsigned char **mem,
4236        int *size,
4237        int *offset,
4238        int *extra
4239   );
4240   void (*CloseFramebuffer)(ScrnInfoPtr pScrn);
4241   Bool (*SetMode)(ScrnInfoPtr pScrn, DGAModePtr pMode);
4242   void (*SetViewport)(ScrnInfoPtr pScrn, int x, int y, int flags);
4243   int  (*GetViewport)(ScrnInfoPtr pScrn);
4244   void (*Sync)(ScrnInfoPtr);
4245   void (*FillRect)(
4246        ScrnInfoPtr pScrn,
4247        int x, int y, int w, int h,
4248        unsigned long color
4249   );
4250   void (*BlitRect)(
4251        ScrnInfoPtr pScrn,
4252        int srcx, int srcy,
4253        int w, int h,
4254        int dstx, int dsty
4255   );
4256   void (*BlitTransRect)(
4257        ScrnInfoPtr pScrn,
4258        int srcx, int srcy,
4259        int w, int h,
4260        int dstx, int dsty,
4261        unsigned long color
4262   );
4263 } DGAFunctionRec, *DGAFunctionPtr;
4264         </programlisting>
4265
4266
4267         <blockquote><para>
4268             <programlisting>
4269     Bool OpenFramebuffer (pScrn, name, mem, size, offset, extra);
4270             </programlisting>
4271             <blockquote><para>
4272       <function>OpenFramebuffer()</function> should pass the client everything
4273       it needs to know to be able to open the framebuffer.  These
4274       parameters are OS specific and their meanings are to be interpreted
4275       by an OS specific client library.
4276
4277                 <variablelist>
4278                   <varlistentry>
4279                     <term><parameter>name</parameter></term>
4280                     <listitem><para>
4281               The name of the device to open or <constant>NULL</constant> if
4282               there is no special device to open.  A <constant>NULL</constant>
4283               name tells the client that it should open whatever device
4284               one would usually open to access physical memory.
4285                       </para></listitem></varlistentry>
4286
4287                   <varlistentry>
4288                     <term><parameter>mem</parameter></term>
4289                     <listitem><para>
4290               The physical address of the start of the framebuffer.
4291                       </para></listitem></varlistentry>
4292
4293                   <varlistentry>
4294                     <term><parameter>size</parameter></term>
4295                     <listitem><para>
4296               The size of the framebuffer in bytes.
4297                       </para></listitem></varlistentry>
4298
4299                   <varlistentry>
4300                     <term><parameter>offset</parameter></term>
4301                     <listitem><para>
4302               Any offset into the device, if applicable.
4303                       </para></listitem></varlistentry>
4304
4305                   <varlistentry>
4306                     <term><parameter>flags</parameter></term>
4307                     <listitem><para>
4308               Any additional information that the client may need.
4309               Currently, only the <constant>DGA_NEED_ROOT</constant> flag is
4310               defined.
4311                       </para></listitem></varlistentry>
4312
4313                 </variablelist>
4314               </para></blockquote>
4315           </para></blockquote>
4316
4317         <blockquote><para>
4318             <programlisting>
4319     void CloseFramebuffer (pScrn);
4320             </programlisting>
4321             <blockquote><para>
4322       <function>CloseFramebuffer()</function> merely informs the driver (if it
4323       even cares) that client no longer needs to access the framebuffer
4324       directly.  This function is optional.
4325               </para>
4326
4327             </blockquote></para></blockquote>
4328
4329         <blockquote><para>
4330             <programlisting>
4331     Bool SetMode (pScrn, pMode);
4332             </programlisting>
4333             <blockquote><para>
4334       <function>SetMode()</function> tells the driver to initialize the mode
4335       passed to it.  If <parameter>pMode</parameter> is <constant>NULL</constant>,
4336       then the driver should restore the original pre-DGA mode.
4337               </para>
4338
4339             </blockquote></para></blockquote>
4340
4341         <blockquote><para>
4342             <programlisting>
4343     void SetViewport (pScrn, x, y, flags);
4344             </programlisting>
4345             <blockquote><para>
4346       <function>SetViewport()</function> tells the driver to make the upper
4347       left-hand corner of the visible screen correspond to coordinate
4348       <literal remap="tt">(x,y)</literal> on the framebuffer.  <parameter>flags</parameter>
4349       currently defined are:
4350
4351                 <variablelist>
4352                   <varlistentry>
4353                     <term><constant>DGA_FLIP_IMMEDIATE</constant></term>
4354                     <listitem><para>
4355             The viewport change should occur immediately.
4356                       </para></listitem></varlistentry>
4357
4358                   <varlistentry>
4359                     <term><constant>DGA_FLIP_RETRACE</constant></term>
4360                     <listitem><para>
4361             The viewport change should occur at the
4362             vertical retrace, but this function should
4363             return sooner if possible.
4364                         </para></listitem></varlistentry>
4365                 </variablelist>
4366               </para>
4367
4368               <para>
4369       The <literal remap="tt">(x,y)</literal> locations will be passed as the client
4370       specified them, however, the driver is expected to round these
4371       locations down to the next supported location as specified by the
4372       <structfield>xViewportStep</structfield> and <structfield>yViewportStep</structfield>
4373       for the current mode.
4374               </para>
4375             </blockquote></para></blockquote>
4376
4377         <blockquote><para>
4378             <programlisting>
4379     int GetViewport (pScrn);
4380             </programlisting>
4381             <blockquote><para>
4382       <function>GetViewport()</function> gets the current page flip status.
4383       Set bits in the returned int correspond to viewport change requests
4384       still pending.  For instance, set bit zero if the last SetViewport
4385       request is still pending, bit one if the one before that is still
4386       pending, etc.
4387               </para>
4388
4389             </blockquote></para></blockquote>
4390
4391         <blockquote><para>
4392             <programlisting>
4393     void Sync (pScrn);
4394             </programlisting>
4395             <blockquote><para>
4396       This function should ensure that any graphics accelerator operations
4397       have finished.  This function should not return until the graphics
4398       accelerator is idle.
4399               </para>
4400
4401             </blockquote></para></blockquote>
4402
4403         <blockquote><para>
4404             <programlisting>
4405     void FillRect (pScrn, x, y, w, h, color);
4406             </programlisting>
4407             <blockquote><para>
4408       This optional function should fill a rectangle
4409       <parameter>w&nbsp;&times;&nbsp;h</parameter> located at
4410       <parameter>(x,y)</parameter> in the given color.
4411               </para>
4412
4413             </blockquote></para></blockquote>
4414
4415         <blockquote><para>
4416             <programlisting>
4417     void BlitRect (pScrn, srcx, srcy, w, h, dstx, dsty);
4418             </programlisting>
4419             <blockquote><para>
4420       This optional function should copy an area
4421       <parameter>w&nbsp;&times;&nbsp;h</parameter> located at
4422       <parameter>(srcx,srcy)</parameter> to location <parameter>(dstx,dsty)</parameter>.
4423       This function will need to handle copy directions as appropriate.
4424               </para>
4425
4426             </blockquote></para></blockquote>
4427
4428         <blockquote><para>
4429             <programlisting>
4430     void BlitTransRect (pScrn, srcx, srcy, w, h, dstx, dsty, color);
4431             </programlisting>
4432             <blockquote><para>
4433       This optional function is the same as BlitRect except that pixels
4434       in the source corresponding to the color key <parameter>color</parameter>
4435       should be skipped.
4436               </para>
4437
4438             </blockquote></para></blockquote>
4439     </para></blockquote>
4440
4441   </sect1>
4442
4443   <sect1>
4444     <title>The XFree86 X Video Extension (Xv) Device Dependent Layer</title>
4445
4446     <para>
4447 XFree86 offers the X Video Extension which allows clients to treat video
4448 as any another primitive and <quote>Put</quote> video into drawables.  By default,
4449 the extension reports no video adaptors as being available since the
4450 DDX layer has not been initialized.  The driver can initialize the DDX
4451 layer by filling out one or more <literal remap="tt">XF86VideoAdaptorRecs</literal>
4452 as described later in this document and passing a list of
4453 <literal remap="tt">XF86VideoAdaptorPtr</literal> pointers to the following function:
4454
4455       <programlisting>
4456     Bool xf86XVScreenInit(ScreenPtr pScreen,
4457                           XF86VideoAdaptorPtr *adaptPtrs,
4458                           int num);
4459       </programlisting>
4460     </para>
4461
4462     <para>
4463 After doing this, the extension will report video adaptors as being
4464 available, providing the data in their respective
4465 <literal remap="tt">XF86VideoAdaptorRecs</literal> was valid.
4466 <function>xf86XVScreenInit()</function> <emphasis>copies</emphasis> data from the structure
4467 passed to it so the driver may free it after the initialization.  At
4468 the moment, the DDX only supports rendering into Window drawables.
4469 Pixmap rendering will be supported after a sufficient survey of suitable
4470 hardware is completed.
4471     </para>
4472
4473     <para>
4474 The <structname>XF86VideoAdaptorRec</structname>:
4475
4476       <programlisting>
4477 typedef struct {
4478         unsigned int type;
4479         int flags;
4480         char *name;
4481         int nEncodings;
4482         XF86VideoEncodingPtr pEncodings;
4483         int nFormats;
4484         XF86VideoFormatPtr pFormats;
4485         int nPorts;
4486         DevUnion *pPortPrivates;
4487         int nAttributes;
4488         XF86AttributePtr pAttributes;
4489         int nImages;
4490         XF86ImagePtr pImages;
4491         PutVideoFuncPtr PutVideo;
4492         PutStillFuncPtr PutStill;
4493         GetVideoFuncPtr GetVideo;
4494         GetStillFuncPtr GetStill;
4495         StopVideoFuncPtr StopVideo;
4496         SetPortAttributeFuncPtr SetPortAttribute;
4497         GetPortAttributeFuncPtr GetPortAttribute;
4498         QueryBestSizeFuncPtr QueryBestSize;
4499         PutImageFuncPtr PutImage;
4500         QueryImageAttributesFuncPtr QueryImageAttributes;
4501 } XF86VideoAdaptorRec, *XF86VideoAdaptorPtr;
4502       </programlisting></para>
4503
4504     <para>
4505 Each adaptor will have its own XF86VideoAdaptorRec.  The fields are
4506 as follows:
4507
4508       <variablelist>
4509         <varlistentry>
4510           <term><structfield>type</structfield></term>
4511           <listitem><para>
4512         This can be any of the following flags OR'd together.
4513
4514               <variablelist>
4515                 <varlistentry>
4516                   <term><constant>XvInputMask</constant>
4517                     <constant>XvOutputMask</constant></term>
4518                   <listitem><para>
4519             These refer to the target drawable and are similar to a Window's
4520             class. <literal remap="tt">XvInputMask</literal> indicates that the adaptor
4521             can put video into a drawable.  <literal remap="tt">XvOutputMask</literal>
4522             indicates that the adaptor can get video from a drawable.
4523                     </para></listitem></varlistentry>
4524
4525                 <varlistentry>
4526                   <term><constant>XvVideoMask</constant>
4527                     <constant>XvStillMask</constant>
4528                     <constant>XvImageMask</constant></term>
4529                   <listitem><para>
4530             These indicate that the adaptor supports video, still or
4531             image primitives respectively.
4532                     </para></listitem></varlistentry>
4533
4534                 <varlistentry>
4535                   <term><constant>XvWindowMask</constant>
4536                     <constant>XvPixmapMask</constant></term>
4537                   <listitem><para>
4538             These indicate the types of drawables the adaptor is capable
4539             of rendering into.  At the moment, Pixmap rendering is not
4540             supported and the <constant>XvPixmapMask</constant> flag is ignored.
4541                     </para></listitem></varlistentry>
4542               </variablelist>
4543
4544             </para></listitem></varlistentry>
4545
4546         <varlistentry>
4547           <term><structfield>flags</structfield></term>
4548           <listitem><para>
4549         Currently, the following flags are defined:
4550
4551               <variablelist>
4552                 <varlistentry>
4553                   <term><constant>VIDEO_NO_CLIPPING</constant></term>
4554                   <listitem><para>
4555            This indicates that the video adaptor does not support
4556            clipping.  The driver will never receive <quote>Put</quote> requests
4557            where less than the entire area determined by
4558            <parameter>drw_x</parameter>, <parameter>drw_y</parameter>,
4559            <parameter>drw_w</parameter> and <parameter>drw_h</parameter> is visible.
4560            This flag does not apply to <quote>Get</quote> requests.  Hardware
4561            that is incapable of clipping <quote>Gets</quote> may punt or get
4562            the extents of the clipping region passed to it.
4563                     </para></listitem>
4564
4565                 </varlistentry>
4566
4567                 <varlistentry>
4568                   <term><constant>VIDEO_INVERT_CLIPLIST</constant></term>
4569                   <listitem><para>
4570            This indicates that the video driver requires the clip
4571            list to contain the regions which are obscured rather
4572            than the regions which are are visible.
4573                     </para></listitem>
4574
4575                 </varlistentry>
4576
4577                 <varlistentry>
4578                   <term><constant>VIDEO_OVERLAID_STILLS</constant></term>
4579                   <listitem><para>
4580            Implementing PutStill for hardware that does video as an
4581            overlay can be awkward since it's unclear how long to leave
4582            the video up for.  When this flag is set, StopVideo will be
4583            called whenever the destination gets clipped or moved so that
4584            the still can be left up until then.
4585                     </para></listitem>
4586
4587                 </varlistentry>
4588
4589                 <varlistentry>
4590                   <term><constant>VIDEO_OVERLAID_IMAGES</constant></term>
4591                   <listitem><para>
4592            Same as <constant>VIDEO_OVERLAID_STILLS</constant> but for images.
4593                     </para></listitem>
4594                 </varlistentry>
4595
4596                 <varlistentry>
4597                   <term><constant>VIDEO_CLIP_TO_VIEWPORT</constant></term>
4598                   <listitem><para>
4599             Indicates that the clip region passed to the driver functions
4600             should be clipped to the visible portion of the screen in the
4601             case where the viewport is smaller than the virtual desktop.
4602                     </para></listitem></varlistentry>
4603
4604               </variablelist>
4605             </para></listitem></varlistentry>
4606
4607         <varlistentry>
4608           <term><structfield>name</structfield></term>
4609           <listitem><para>
4610         The name of the adaptor.
4611             </para></listitem></varlistentry>
4612
4613
4614         <varlistentry>
4615           <term><structfield>nEncodings</structfield>
4616             <structfield>pEncodings</structfield></term>
4617           <listitem><para>
4618         The number of encodings the adaptor is capable of and pointer
4619         to the <structname>XF86VideoEncodingRec</structname> array.  The
4620         <structname>XF86VideoEncodingRec</structname> is described later on.
4621         For drivers that only support XvImages there should be an encoding
4622         named "XV_IMAGE" and the width and height should specify
4623         the maximum size source image supported.
4624           </para></listitem></varlistentry>
4625
4626
4627         <varlistentry>
4628           <term><structfield>nFormats</structfield>
4629               <structfield>pFormats</structfield></term>
4630           <listitem><para>
4631         The number of formats the adaptor is capable of and pointer to
4632         the <structname>XF86VideoFormatRec</structname> array.  The
4633         <structname>XF86VideoFormatRec</structname> is described later on.
4634             </para></listitem></varlistentry>
4635
4636
4637         <varlistentry>
4638           <term><structfield>nPorts</structfield>
4639             <structfield>pPortPrivates</structfield></term>
4640           <listitem><para>
4641         The number of ports is the number of separate data streams which
4642         the adaptor can handle simultaneously.  If you have more than
4643         one port, the adaptor is expected to be able to render into more
4644         than one window at a time.  <structfield>pPortPrivates</structfield> is
4645         an array of pointers or ints - one for each port.  A port's
4646         private data will be passed to the driver any time the port is
4647         requested to do something like put the video or stop the video.
4648         In the case where there may be many ports, this enables the
4649         driver to know which port the request is intended for.  Most
4650         commonly, this will contain a pointer to the data structure
4651         containing information about the port.  In Xv, all ports on
4652         a particular adaptor are expected to be identical in their
4653         functionality.
4654             </para></listitem></varlistentry>
4655
4656
4657         <varlistentry>
4658           <term><structfield>nAttributes</structfield>
4659             <structfield>pAttributes</structfield></term>
4660           <listitem><para>
4661         The number of attributes recognized by the adaptor and a pointer to
4662         the array of <structname>XF86AttributeRecs</structname>.  The
4663         <structname>XF86AttributeRec</structname> is described later on.
4664             </para></listitem></varlistentry>
4665
4666
4667         <varlistentry>
4668           <term><structfield>nImages</structfield>
4669             <structfield>pImages</structfield></term>
4670           <listitem><para>
4671         The number of <structname>XF86ImageRecs</structname> supported by the adaptor
4672         and a pointer to the array of <structname>XF86ImageRecs</structname>. The
4673         <structname>XF86ImageRec</structname> is described later on.
4674             </para></listitem></varlistentry>
4675
4676
4677         <varlistentry>
4678           <term><structfield>
4679      PutVideo PutStill GetVideo GetStill StopVideo
4680      SetPortAttribute GetPortAttribute QueryBestSize PutImage
4681      QueryImageAttributes
4682             </structfield></term>
4683           <listitem><para>
4684         These functions define the DDX-&gt;driver interface.  In each
4685         case, the pointer <parameter>data</parameter> is passed to the driver.
4686         This is the port private for that port as described above.  All
4687         fields are required except under the following conditions:
4688
4689               <orderedlist>
4690                 <listitem><para>
4691              <structfield>PutVideo</structfield>, <structfield>PutStill</structfield> and
4692              the image routines <structfield>PutImage</structfield> and
4693              <structfield>QueryImageAttributes</structfield> are not required when the
4694              adaptor type does not contain <constant>XvInputMask</constant>.
4695                   </para></listitem>
4696
4697                 <listitem><para>
4698              <structfield>GetVideo</structfield> and <structfield>GetStill</structfield>
4699              are not required when the adaptor type does not contain
4700              <constant>XvOutputMask</constant>.
4701                   </para></listitem>
4702
4703                 <listitem><para>
4704              <structfield>GetVideo</structfield> and <structfield>PutVideo</structfield>
4705              are not required when the adaptor type does not contain
4706              <constant>XvVideoMask</constant>.
4707                   </para></listitem>
4708
4709                 <listitem><para>
4710              <structfield>GetStill</structfield> and <structfield>PutStill</structfield>
4711              are not required when the adaptor type does not contain
4712              <constant>XvStillMask</constant>.
4713                   </para></listitem>
4714
4715                 <listitem><para>
4716              <structfield>PutImage</structfield> and <structfield>QueryImageAttributes</structfield>
4717              are not required when the adaptor type does not contain
4718              <constant>XvImageMask</constant>.
4719                   </para></listitem>
4720
4721               </orderedlist>
4722
4723             </para>
4724
4725             <para>
4726         With the exception of <structfield>QueryImageAttributes</structfield>, these
4727         functions should return <constant>Success</constant> if the operation was
4728         completed successfully.  They can return <constant>XvBadAlloc</constant>
4729         otherwise. <structfield>QueryImageAttributes</structfield> returns the size
4730         of the XvImage queried.
4731             </para>
4732
4733             <para>
4734         If the <constant>VIDEO_NO_CLIPPING</constant>
4735         flag is set, the <literal remap="tt">clipBoxes</literal> may be ignored by
4736         the driver.  <literal remap="tt">ClipBoxes</literal> is an <literal remap="tt">X-Y</literal>
4737         banded region identical to those used throughout the server.
4738         The clipBoxes represent the visible portions of the area determined
4739         by <literal remap="tt">drw_x</literal>, <literal remap="tt">drw_y</literal>,
4740         <literal remap="tt">drw_w</literal> and <literal remap="tt">drw_h</literal> in the Get/Put
4741         function.  The boxes are in screen coordinates, are guaranteed
4742         not to overlap and an empty region will never be passed.
4743         If the driver has specified <constant>VIDEO_INVERT_CLIPLIST</constant>,
4744         <literal remap="tt">clipBoxes</literal> will indicate the areas of the primitive
4745         which are obscured rather than the areas visible.
4746
4747             </para></listitem></varlistentry>
4748       </variablelist>
4749
4750       <blockquote><para>
4751           <programlisting>
4752     typedef  int (* PutVideoFuncPtr)( ScrnInfoPtr pScrn,
4753                    short vid_x, short vid_y, short drw_x, short drw_y,
4754                    short vid_w, short vid_h, short drw_w, short drw_h,
4755                    RegionPtr clipBoxes, pointer data );
4756           </programlisting>
4757               <blockquote><para>
4758           This indicates that the driver should take a subsection
4759           <parameter>vid_w</parameter> by <parameter>vid_h</parameter> at location
4760           <parameter>(vid_x,vid_y)</parameter> from the video stream and direct
4761           it into the rectangle <parameter>drw_w</parameter> by <parameter>drw_h</parameter>
4762           at location <parameter>(drw_x,drw_y)</parameter> on the screen, scaling as
4763           necessary.  Due to the large variations in capabilities of
4764           the various hardware expected to be used with this extension,
4765           it is not expected that all hardware will be able to do this
4766           exactly as described.  In that case the driver should just do
4767           <quote>the best it can,</quote> scaling as closely to the target rectangle
4768           as it can without rendering outside of it.  In the worst case,
4769           the driver can opt to just not turn on the video.
4770               </para>
4771
4772             </blockquote></para></blockquote>
4773
4774           <blockquote><para>
4775               <programlisting>
4776     typedef  int (* PutStillFuncPtr)( ScrnInfoPtr pScrn,
4777                    short vid_x, short vid_y, short drw_x, short drw_y,
4778                    short vid_w, short vid_h, short drw_w, short drw_h,
4779                    RegionPtr clipBoxes, pointer data );
4780               </programlisting>
4781               <blockquote><para>
4782           This is same as <structfield>PutVideo</structfield> except that the driver
4783           should place only one frame from the stream on the screen.
4784               </para>
4785
4786             </blockquote></para></blockquote>
4787
4788           <blockquote><para>
4789               <programlisting>
4790     typedef int (* GetVideoFuncPtr)( ScrnInfoPtr pScrn,
4791                   short vid_x, short vid_y, short drw_x, short drw_y,
4792                   short vid_w, short vid_h, short drw_w, short drw_h,
4793                   RegionPtr clipBoxes, pointer data );
4794               </programlisting>
4795               <blockquote><para>
4796           This is same as <structfield>PutVideo</structfield> except that the driver
4797           gets video from the screen and outputs it.  The driver should
4798           do the best it can to get the requested dimensions correct
4799           without reading from an area larger than requested.
4800               </para>
4801
4802             </blockquote></para></blockquote>
4803
4804           <blockquote><para>
4805               <programlisting>
4806     typedef int (* GetStillFuncPtr)( ScrnInfoPtr pScrn,
4807                   short vid_x, short vid_y, short drw_x, short drw_y,
4808                   short vid_w, short vid_h, short drw_w, short drw_h,
4809                   RegionPtr clipBoxes, pointer data );
4810               </programlisting>
4811               <blockquote><para>
4812           This is the same as <literal remap="tt">GetVideo</literal> except that the
4813           driver should place only one frame from the screen into the
4814           output stream.
4815               </para>
4816
4817             </blockquote></para></blockquote>
4818
4819           <blockquote><para>
4820               <programlisting>
4821     typedef void (* StopVideoFuncPtr)(ScrnInfoPtr pScrn,
4822                                       pointer data, Bool cleanup);
4823               </programlisting>
4824               <blockquote><para>
4825           This indicates the driver should stop displaying the video.
4826           This is used to stop both input and output video.  The
4827           <parameter>cleanup</parameter> field indicates that the video is
4828           being stopped because the client requested it to stop or
4829           because the server is exiting the current VT.  In that case
4830           the driver should deallocate any offscreen memory areas (if
4831           there are any) being used to put the video to the screen.  If
4832           <parameter>cleanup</parameter> is not set, the video is being stopped
4833           temporarily due to clipping or moving of the window, etc...
4834           and video will likely be restarted soon so the driver should
4835           not deallocate any offscreen areas associated with that port.
4836               </para>
4837
4838             </blockquote></para></blockquote>
4839           <blockquote><para>
4840               <programlisting>
4841     typedef int (* SetPortAttributeFuncPtr)(ScrnInfoPtr pScrn,
4842                                 Atom attribute,INT32 value, pointer data);
4843               </programlisting>
4844
4845               <programlisting>
4846     typedef int (* GetPortAttributeFuncPtr)(ScrnInfoPtr pScrn,
4847                                 Atom attribute,INT32 *value, pointer data);
4848               </programlisting>
4849               <blockquote><para>
4850           A port may have particular attributes such as hue,
4851           saturation, brightness or contrast.  Xv clients set and
4852           get these attribute values by sending attribute strings
4853           (Atoms) to the server.  Such requests end up at these
4854           driver functions.  It is recommended that the driver provide
4855           at least the following attributes mentioned in the Xv client
4856           library docs:
4857                 <literallayout><constant>
4858                 XV_ENCODING
4859                 XV_HUE
4860                 XV_SATURATION
4861                 XV_BRIGHTNESS
4862                 XV_CONTRAST
4863                   </constant></literallayout>
4864           but the driver may recognize as many atoms as it wishes.  If
4865           a requested attribute is unknown by the driver it should return
4866           <constant>BadMatch</constant>.  <constant>XV_ENCODING</constant> is the
4867           attribute intended to let the client specify which video
4868           encoding the particular port should be using (see the description
4869           of <structname>XF86VideoEncodingRec</structname> below).  If the
4870           requested encoding is unsupported, the driver should return
4871           <constant>XvBadEncoding</constant>.  If the value lies outside the
4872           advertised range <constant>BadValue</constant> may be returned.
4873           <constant>Success</constant> should be returned otherwise.
4874               </para>
4875
4876             </blockquote></para></blockquote>
4877
4878           <blockquote><para>
4879             <programlisting>
4880     typedef void (* QueryBestSizeFuncPtr)(ScrnInfoPtr pScrn,
4881                    Bool motion, short vid_w, short vid_h,
4882                    short drw_w, short drw_h,
4883                    unsigned int *p_w, unsigned int *p_h, pointer data);
4884             </programlisting>
4885             <blockquote><para>
4886            <function>QueryBestSize</function> provides the client with a way
4887            to query what the destination dimensions would end up being
4888            if they were to request that an area
4889            <parameter>vid_w</parameter> by <parameter>vid_h</parameter> from the video
4890            stream be scaled to rectangle of
4891            <parameter>drw_w</parameter> by <parameter>drw_h</parameter> on the screen.
4892            Since it is not expected that all hardware will be able to
4893            get the target dimensions exactly, it is important that the
4894            driver provide this function.
4895               </para>
4896
4897             </blockquote></para></blockquote>
4898
4899         <blockquote><para>
4900             <programlisting>
4901     typedef  int (* PutImageFuncPtr)( ScrnInfoPtr pScrn,
4902                    short src_x, short src_y, short drw_x, short drw_y,
4903                    short src_w, short src_h, short drw_w, short drw_h,
4904                    int image, char *buf, short width, short height,
4905                    Bool sync, RegionPtr clipBoxes, pointer data );
4906               </programlisting>
4907               <blockquote><para>
4908           This is similar to <structfield>PutStill</structfield> except that the
4909           source of the video is not a port but the data stored in a system
4910           memory buffer at <parameter>buf</parameter>.  The data is in the format
4911           indicated by the <parameter>image</parameter> descriptor and represents a
4912           source of size <parameter>width</parameter> by <parameter>height</parameter>.
4913           If <parameter>sync</parameter> is TRUE the driver should not return
4914           from this function until it is through reading the data
4915           from <parameter>buf</parameter>.  Returning when <parameter>sync</parameter>
4916           is TRUE indicates that it is safe for the data at <parameter>buf</parameter>
4917           to be replaced, freed, or modified.
4918               </para>
4919
4920             </blockquote></para></blockquote>
4921
4922         <blockquote><para>
4923             <programlisting>
4924     typedef  int (* QueryImageAttributesFuncPtr)( ScrnInfoPtr pScrn,
4925                                 int image, short *width, short *height,
4926                                 int *pitches, int *offsets);
4927             </programlisting>
4928             <blockquote><para>
4929           This function is called to let the driver specify how data for
4930           a particular <parameter>image</parameter> of size <parameter>width</parameter>
4931           by <parameter>height</parameter> should be stored.  Sometimes only
4932           the size and corrected width and height are needed.  In that
4933           case <parameter>pitches</parameter> and <parameter>offsets</parameter> are
4934           NULL.  The size of the memory required for the image is returned
4935           by this function.  The <parameter>width</parameter> and
4936           <parameter>height</parameter> of the requested image can be altered by
4937           the driver to reflect format limitations (such as component
4938           sampling periods that are larger than one).  If
4939           <parameter>pitches</parameter> and <parameter>offsets</parameter> are not NULL,
4940           these will be arrays with as many elements in them as there
4941           are planes in the <parameter>image</parameter> format.  The driver
4942           should specify the pitch (in bytes) of each scanline in the
4943           particular plane as well as the offset to that plane (in bytes)
4944           from the beginning of the image.
4945               </para>
4946
4947           </blockquote></para></blockquote>
4948     </para>
4949
4950     <para>
4951 The XF86VideoEncodingRec:
4952
4953       <blockquote><para>
4954           <programlisting>
4955 typedef struct {
4956         int id;
4957         char *name;
4958         unsigned short width, height;
4959         XvRationalRec rate;
4960 } XF86VideoEncodingRec, *XF86VideoEncodingPtr;
4961
4962           </programlisting>
4963           <blockquote><para>
4964    The <structname>XF86VideoEncodingRec</structname> specifies what encodings
4965    the adaptor can support.  Most of this data is just informational
4966    and for the client's benefit, and is what will be reported by
4967    <function>XvQueryEncodings</function>.  The <parameter>id</parameter> field is
4968    expected to be a unique identifier to allow the client to request a
4969    certain encoding via the <constant>XV_ENCODING</constant> attribute string.
4970
4971             </para>
4972           </blockquote></para></blockquote>
4973     </para>
4974
4975     <para>
4976 The XF86VideoFormatRec:
4977
4978       <blockquote><para>
4979           <programlisting>
4980 typedef struct {
4981         char  depth;
4982         short class;
4983 } XF86VideoFormatRec, *XF86VideoFormatPtr;
4984
4985           </programlisting>
4986           <blockquote><para>
4987     This specifies what visuals the video is viewable in.
4988     <parameter>depth</parameter> is the depth of the visual (not bpp).
4989     <parameter>class</parameter> is the visual class such as
4990     <constant>TrueColor</constant>, <constant>DirectColor</constant> or
4991     <constant>PseudoColor</constant>.  Initialization of an adaptor will fail
4992     if none of the visuals on that screen are supported.
4993             </para>
4994
4995           </blockquote></para></blockquote>
4996     </para>
4997
4998     <para>
4999 The XF86AttributeRec:
5000
5001       <blockquote><para>
5002           <programlisting>
5003 typedef struct {
5004         int   flags;
5005         int   min_value;
5006         int   max_value;
5007         char  *name;
5008 } XF86AttributeListRec, *XF86AttributeListPtr;
5009
5010           </programlisting>
5011           <blockquote><para>
5012    Each adaptor may have an array of these advertising the attributes
5013    for its ports.  Currently defined flags are <literal remap="tt">XvGettable</literal>
5014    and <literal remap="tt">XvSettable</literal> which may be OR'd together indicating that
5015    attribute is <quote>gettable</quote> or <quote>settable</quote> by the client.  The
5016    <literal remap="tt">min</literal> and <literal remap="tt">max</literal> field specify the valid range
5017    for the value.  <literal remap="tt">Name</literal> is a text string describing the
5018    attribute by name.
5019             </para>
5020
5021           </blockquote></para></blockquote>
5022
5023     </para>
5024
5025     <para>
5026 The XF86ImageRec:
5027
5028         <blockquote><para>
5029             <programlisting>
5030 typedef struct {
5031         int id;
5032         int type;
5033         int byte_order;
5034         char guid[16];
5035         int bits_per_pixel;
5036         int format;
5037         int num_planes;
5038
5039         /* for RGB formats */
5040         int depth;
5041         unsigned int red_mask;
5042         unsigned int green_mask;
5043         unsigned int blue_mask;
5044
5045         /* for YUV formats */
5046         unsigned int y_sample_bits;
5047         unsigned int u_sample_bits;
5048         unsigned int v_sample_bits;
5049         unsigned int horz_y_period;
5050         unsigned int horz_u_period;
5051         unsigned int horz_v_period;
5052         unsigned int vert_y_period;
5053         unsigned int vert_u_period;
5054         unsigned int vert_v_period;
5055         char component_order[32];
5056         int scanline_order;
5057 } XF86ImageRec, *XF86ImagePtr;
5058
5059             </programlisting>
5060             <blockquote><para>
5061    XF86ImageRec describes how video source data is laid out in memory.
5062    The fields are as follows:
5063
5064                 <variablelist>
5065                   <varlistentry>
5066                     <term><structfield>id</structfield></term>
5067                     <listitem><para>
5068         This is a unique descriptor for the format.  It is often good to
5069         set this value to the FOURCC for the format when applicable.
5070                       </para></listitem></varlistentry>
5071
5072                   <varlistentry>
5073                     <term><structfield>type</structfield></term>
5074                     <listitem><para>
5075         This is <constant>XvRGB</constant> or <constant>XvYUV</constant>.
5076                       </para></listitem></varlistentry>
5077
5078                   <varlistentry>
5079                     <term><structfield>byte_order</structfield></term>
5080                     <listitem><para>
5081         This is <constant>LSBFirst</constant> or <constant>MSBFirst</constant>.
5082                       </para></listitem></varlistentry>
5083
5084                   <varlistentry>
5085                     <term><structfield>guid</structfield></term>
5086                     <listitem><para>
5087         This is the Globally Unique IDentifier for the format.  When
5088         not applicable, all characters should be NULL.
5089                       </para></listitem></varlistentry>
5090
5091                   <varlistentry>
5092                     <term><structfield>bits_per_pixel</structfield></term>
5093                     <listitem><para>
5094         The number of bits taken up (but not necessarily used) by each
5095         pixel.  Note that for some planar formats which have fractional
5096         bits per pixel (such as IF09) this number may be rounded _down_.
5097                       </para></listitem></varlistentry>
5098
5099                   <varlistentry>
5100                     <term><structfield>format</structfield></term>
5101                     <listitem><para>
5102         This is <constant>XvPlanar</constant> or <constant>XvPacked</constant>.
5103                       </para></listitem></varlistentry>
5104
5105                   <varlistentry>
5106                     <term><structfield>num_planes</structfield></term>
5107                     <listitem><para>
5108         The number of planes in planar formats.  This should be set to
5109         one for packed formats.
5110                       </para></listitem></varlistentry>
5111
5112                   <varlistentry>
5113                     <term><structfield>depth</structfield></term>
5114                     <listitem><para>
5115         The significant bits per pixel in RGB formats (analgous to the
5116         depth of a pixmap format).
5117                       </para></listitem></varlistentry>
5118
5119                   <varlistentry>
5120                     <term><structfield>red_mask</structfield></term>
5121                     <term><structfield>green_mask</structfield></term>
5122                     <term><structfield>blue_mask</structfield></term>
5123                     <listitem><para>
5124         The red, green and blue bitmasks for packed RGB formats.
5125                       </para></listitem></varlistentry>
5126
5127                   <varlistentry>
5128                     <term><structfield>y_sample_bits</structfield></term>
5129                     <term><structfield>u_sample_bits</structfield></term>
5130                     <term><structfield>v_sample_bits</structfield></term>
5131                     <listitem><para>
5132         The y, u and v sample sizes (in bits).
5133                       </para></listitem></varlistentry>
5134
5135                   <varlistentry>
5136                     <term><structfield>horz_y_period</structfield></term>
5137                     <term><structfield>horz_u_period</structfield></term>
5138                     <term><structfield>horz_v_period</structfield></term>
5139                     <listitem><para>
5140         The y, u and v sampling periods in the horizontal direction.
5141                       </para></listitem></varlistentry>
5142
5143                   <varlistentry>
5144                     <term><structfield>vert_y_period</structfield></term>
5145                     <term><structfield>vert_u_period</structfield></term>
5146                     <term><structfield>vert_v_period</structfield></term>
5147                     <listitem><para>
5148         The y, u and v sampling periods in the vertical direction.
5149                       </para></listitem></varlistentry>
5150
5151                   <varlistentry>
5152                     <term><structfield>component_order</structfield></term>
5153                     <listitem><para>
5154         Uppercase ascii characters representing the order that
5155         samples are stored within packed formats.  For planar formats
5156         this represents the ordering of the planes.  Unused characters
5157         in the 32 byte string should be set to NULL.
5158                       </para></listitem></varlistentry>
5159
5160                   <varlistentry>
5161                     <term><structfield>scanline_order</structfield></term>
5162                     <listitem><para>
5163         This is <constant>XvTopToBottom</constant> or <constant>XvBottomToTop</constant>.
5164                       </para></listitem></varlistentry>
5165
5166                   </variablelist>
5167             </para>
5168
5169             <para>
5170   Since some formats (particular some planar YUV formats) may not
5171 be completely defined by the parameters above, the guid, when
5172 available, should provide the most accurate description of the
5173 format.
5174             </para>
5175
5176           </blockquote></para></blockquote>
5177     </para>
5178   </sect1>
5179
5180   <sect1>
5181     <title>The Loader</title>
5182
5183     <para>
5184 This section describes the interfaces to the module loader.  The loader
5185 interfaces can be divided into two groups: those that are only available to
5186 the XFree86 common layer, and those that are also available to modules.
5187     </para>
5188
5189     <sect2>
5190       <title>Loader Overview</title>
5191
5192       <para>
5193 The loader is capable of loading modules in a range of object formats,
5194 and knowledge of these formats is built in to the loader.  Knowledge of
5195 new object formats can be added to the loader in a straightforward
5196 manner.  This makes it possible to provide OS-independent modules (for
5197 a given CPU architecture type).  In addition to this, the loader can
5198 load modules via the OS-provided <function>dlopen(3)</function> service where
5199 available.  Such modules are not platform independent, and the semantics
5200 of <function>dlopen()</function> on most systems results in significant
5201 limitations in the use of modules of this type.  Support for
5202 <function>dlopen()</function> modules in the loader is primarily for
5203 experimental and development purposes.
5204       </para>
5205
5206       <para>
5207 Symbols exported by the loader (on behalf of the core X server) to
5208 modules are determined at compile time.  Only those symbols explicitly
5209 exported are available to modules.  All external symbols of loaded
5210 modules are exported to other modules, and to the core X server.  The
5211 loader can be requested to check for unresolved symbols at any time,
5212 and the action to be taken for unresolved symbols can be controlled by
5213 the caller of the loader.  Typically the caller identifies which symbols
5214 can safely remain unresolved and which cannot.
5215       </para>
5216
5217       <para>
5218 NOTE:  Now that ISO-C allows pointers to functions and pointers to data to
5219 have different internal representations, some of the following interfaces
5220 will need to be revisited.
5221       </para>
5222     </sect2>
5223
5224     <sect2>
5225       <title>Semi-private Loader Interface</title>
5226
5227       <para>
5228 The following is the semi-private loader interface that is available to the
5229 XFree86 common layer.
5230       </para>
5231
5232       <blockquote><para>
5233           <programlisting>
5234     void LoaderInit(void);
5235           </programlisting>
5236           <blockquote><para>
5237     The <function>LoaderInit()</function> function initialises the loader,
5238     and it must be called once before calling any other loader functions.
5239     This function initialises the tables of exported symbols, and anything
5240     else that might need to be initialised.
5241             </para>
5242
5243           </blockquote></para></blockquote>
5244
5245       <blockquote><para>
5246           <programlisting>
5247     void LoaderSetPath(const char *path);
5248           </programlisting>
5249           <blockquote><para>
5250     The <function>LoaderSetPath()</function> function initialises a default
5251     module search path.  This must be called if calls to other functions
5252     are to be made without explicitly specifying a module search path.
5253     The search path <parameter>path</parameter> must be a string of one or more
5254     comma separated absolute paths.  Modules are expected to be located
5255     below these paths, possibly in subdirectories of these paths.
5256             </para>
5257
5258           </blockquote></para></blockquote>
5259
5260       <blockquote><para>
5261           <programlisting>
5262     pointer LoadModule(const char *module, const char *path,
5263                        const char **subdirlist, const char **patternlist,
5264                        pointer options, const XF86ModReqInfo * modreq,
5265                        int *errmaj, int *errmin);
5266           </programlisting>
5267           <blockquote><para>
5268     The <function>LoadModule()</function> function loads the module called
5269     <parameter>module</parameter>.  The return value is a module handle, and
5270     may be used in future calls to the loader that require a reference
5271     to a loaded module.  The module name <parameter>module</parameter> is
5272     normally the module's canonical name, which doesn't contain any
5273     directory path information, or any object/library file prefixes of
5274     suffixes.  Currently a full pathname and/or filename is also accepted.
5275     This might change.  The other parameters are:
5276
5277               <variablelist>
5278                 <varlistentry>
5279                   <term><parameter>path</parameter></term>
5280                   <listitem><para>
5281                   An optional comma-separated list of module search paths.
5282                   When <constant>NULL</constant>, the default search path is used.
5283                     </para></listitem></varlistentry>
5284
5285
5286                 <varlistentry>
5287                   <term><parameter>subdirlist</parameter></term>
5288                   <listitem><para>
5289                   An optional <constant>NULL</constant> terminated list of
5290                   subdirectories to search.  When <constant>NULL</constant>,
5291                   the default built-in list is used (refer to
5292                   <varname>stdSubdirs</varname> in <filename>loadmod.c</filename>).
5293                   The default list is also substituted for entries in
5294                   <parameter>subdirlist</parameter> with the value
5295                   <constant>DEFAULT_LIST</constant>.  This makes is possible
5296                   to augment the default list instead of replacing it.
5297                   Subdir elements must be relative, and must not contain
5298                   <literal remap="tt">".."</literal>.  If any violate this requirement,
5299                   the load fails.
5300                     </para></listitem></varlistentry>
5301
5302
5303                 <varlistentry>
5304                   <term><parameter>patternlist</parameter></term>
5305                   <listitem><para>
5306                   An optional <constant>NULL</constant> terminated list of
5307                   POSIX regular expressions used to connect module
5308                   filenames with canonical module names.  Each regex
5309                   should contain exactly one subexpression that corresponds
5310                   to the canonical module name.  When <constant>NULL</constant>,
5311                   the default built-in list is used (refer to
5312                   <varname>stdPatterns</varname> in
5313                   <filename>loadmod.c</filename>).  The default list is also
5314                   substituted for entries in <parameter>patternlist</parameter>
5315                   with the value <constant>DEFAULT_LIST</constant>.  This
5316                   makes it possible to augment the default list instead
5317                   of replacing it.
5318                     </para></listitem></varlistentry>
5319
5320
5321                 <varlistentry>
5322                   <term><parameter>options</parameter></term>
5323                   <listitem><para>
5324                   An optional parameter that is passed to the newly
5325                   loaded module's <literal remap="tt">SetupProc</literal> function
5326                   (if it has one).  This argument is normally a
5327                   <constant>NULL</constant> terminated list of
5328                   <structname>Options</structname>, and must be interpreted that
5329                   way by modules loaded directly by the XFree86 common
5330                   layer.  However, it may be used for application-specific
5331                   parameter passing in other situations.
5332                     </para></listitem></varlistentry>
5333
5334
5335                 <varlistentry>
5336                   <term><parameter>modreq</parameter></term>
5337                   <listitem><para>
5338                   An optional <structname>XF86ModReqInfo*</structname> containing
5339                   version/ABI/vendor information to requirements to
5340                   check the newly loaded module against.  The main
5341                   purpose of this is to allow the loader to verify that
5342                   a module of the correct type/version before running
5343                   its <function>SetupProc</function> function.
5344                       </para>
5345
5346                     <para>
5347                   The <literal remap="tt">XF86ModReqInfo</literal> struct is defined
5348                   as follows:
5349                       <programlisting>
5350 typedef struct {
5351         CARD8        majorversion;  /* MAJOR_UNSPEC */
5352         CARD8        minorversion;  /* MINOR_UNSPEC */
5353         CARD16       patchlevel;    /* PATCH_UNSPEC */
5354         const char * abiclass;      /* ABI_CLASS_NONE */
5355         CARD32       abiversion;    /* ABI_VERS_UNSPEC */
5356         const char * moduleclass;   /* MOD_CLASS_NONE */
5357 } XF86ModReqInfo;
5358                         </programlisting>
5359
5360                   The information here is compared against the equivalent
5361                   information in the module's
5362                   <structname>XF86ModuleVersionInfo</structname> record (which
5363                   is described below).  The values in comments above
5364                   indicate <quote>don't care</quote> settings for each of the fields.
5365                   The comparisons made are as follows:
5366
5367                       <variablelist>
5368                         <varlistentry>
5369                           <term><structfield>majorversion</structfield></term>
5370                           <listitem><para>
5371                                    Must match the module's majorversion
5372                                    exactly.
5373                             </para></listitem></varlistentry>
5374
5375                         <varlistentry>
5376                           <term><structfield>minorversion</structfield></term>
5377                           <listitem><para>
5378                                    The module's minor version must be
5379                                    no less than this value.  This
5380                                    comparison is only made if
5381                                    <structfield>majorversion</structfield> is
5382                                    specified and matches.
5383                             </para></listitem></varlistentry>
5384
5385                         <varlistentry>
5386                           <term><structfield>patchlevel</structfield></term>
5387                           <listitem><para>
5388                                    The module's patchlevel must be no
5389                                    less than this value.  This comparison
5390                                    is only made if
5391                                    <structfield>minorversion</structfield> is
5392                                    specified and matches.
5393                             </para></listitem></varlistentry>
5394
5395                         <varlistentry>
5396                           <term><structfield>abiclass</structfield></term>
5397                           <listitem><para>
5398                                    String must match the module's abiclass
5399                                    string.
5400                             </para></listitem></varlistentry>
5401
5402                         <varlistentry>
5403                           <term><structfield>abiversion</structfield></term>
5404                           <listitem><para>
5405                                    Must be consistent with the module's
5406                                    abiversion (major equal, minor no
5407                                    older).
5408                             </para></listitem></varlistentry>
5409
5410                         <varlistentry>
5411                           <term><structfield>moduleclass</structfield></term>
5412                           <listitem><para>
5413                                    String must match the module's
5414                                    moduleclass string.
5415                             </para></listitem></varlistentry>
5416
5417                       </variablelist>
5418                     </para></listitem></varlistentry>
5419
5420                 <varlistentry>
5421                   <term><parameter>errmaj</parameter></term>
5422                   <listitem><para>
5423                   An optional pointer to a variable holding the major
5424                   part or the error code.  When provided,
5425                   <parameter>*errmaj</parameter> is filled in when
5426                   <function>LoadModule()</function> fails.
5427                     </para></listitem></varlistentry>
5428
5429                 <varlistentry>
5430                   <term><parameter>errmin</parameter></term>
5431                   <listitem><para>
5432                   Like <parameter>errmaj</parameter>, but for the minor part
5433                   of the error code.
5434                     </para></listitem></varlistentry>
5435
5436               </variablelist>
5437
5438             </para></blockquote>
5439         </para></blockquote>
5440
5441       <blockquote><para>
5442           <programlisting>
5443     void UnloadModule(pointer mod);
5444           </programlisting>
5445           <blockquote><para>
5446     This function unloads the module referred to by the handle mod.
5447     All child modules are also unloaded recursively.  This function must
5448     not be used to directly unload modules that are child modules (i.e.,
5449     those that have been loaded with the <function>LoadSubModule()</function>
5450     described below).
5451             </para>
5452
5453           </blockquote></para></blockquote>
5454     </sect2>
5455
5456     <sect2>
5457       <title>Module Requirements</title>
5458
5459       <para>
5460 Modules must provide information about themselves to the loader, and
5461 may optionally provide entry points for "setup" and "teardown" functions
5462 (those two functions are referred to here as <function>SetupProc</function>
5463 and <function>TearDownProc</function>).
5464       </para>
5465
5466       <para>
5467 The module information is contained in the
5468 <structname>XF86ModuleVersionInfo</structname> struct, which is defined as follows:
5469
5470         <programlisting>
5471 typedef struct {
5472     const char * modname;      /* name of module, e.g. "foo" */
5473     const char * vendor;       /* vendor specific string */
5474     CARD32       _modinfo1_;   /* constant MODINFOSTRING1/2 to find */
5475     CARD32       _modinfo2_;   /* infoarea with a binary editor/sign tool */
5476     CARD32       xf86version;  /* contains XF86_VERSION_CURRENT */
5477     CARD8        majorversion; /* module-specific major version */
5478     CARD8        minorversion; /* module-specific minor version */
5479     CARD16       patchlevel;   /* module-specific patch level */
5480     const char * abiclass;     /* ABI class that the module uses */
5481     CARD32       abiversion;   /* ABI version */
5482     const char * moduleclass;  /* module class */
5483     CARD32       checksum[4];  /* contains a digital signature of the */
5484                                /* version info structure */
5485 } XF86ModuleVersionInfo;
5486         </programlisting>
5487
5488 The fields are used as follows:
5489
5490         <variablelist>
5491           <varlistentry>
5492             <term><structfield>modname</structfield></term>
5493             <listitem><para>
5494                 The module's name.  This field is currently only for
5495                 informational purposes, but the loader may be modified
5496                 in future to require it to match the module's canonical
5497                 name.
5498               </para></listitem></varlistentry>
5499
5500
5501           <varlistentry>
5502             <term><structfield>vendor</structfield></term>
5503             <listitem><para>
5504                 The module vendor.  This field is for informational purposes
5505                 only.
5506               </para></listitem></varlistentry>
5507
5508
5509           <varlistentry>
5510             <term><structfield>_modinfo1_</structfield></term>
5511             <listitem><para>
5512                 This field holds the first part of a signature that can
5513                 be used to locate this structure in the binary.  It should
5514                 always be initialised to <constant>MODINFOSTRING1</constant>.
5515               </para></listitem></varlistentry>
5516
5517
5518           <varlistentry>
5519             <term><structfield>_modinfo2_</structfield></term>
5520             <listitem><para>
5521                 This field holds the second part of a signature that can
5522                 be used to locate this structure in the binary.  It should
5523                 always be initialised to <constant>MODINFOSTRING2</constant>.
5524               </para></listitem></varlistentry>
5525
5526
5527           <varlistentry>
5528             <term><structfield>xf86version</structfield></term>
5529             <listitem><para>
5530                 The XFree86 version against which the module was compiled.
5531                 This is mostly for informational/diagnostic purposes.  It
5532                 should be initialised to <constant>XF86_VERSION_CURRENT</constant>, which is
5533                 defined in <filename>xf86Version.h</filename>.
5534               </para></listitem></varlistentry>
5535
5536
5537           <varlistentry>
5538             <term><structfield>majorversion</structfield></term>
5539             <listitem><para>
5540                 The module-specific major version.  For modules where this
5541                 version is used for more than simply informational
5542                 purposes, the major version should only change (be
5543                 incremented) when ABI incompatibilities are introduced,
5544                 or ABI components are removed.
5545               </para></listitem></varlistentry>
5546
5547
5548           <varlistentry>
5549             <term><structfield>minorversion</structfield></term>
5550             <listitem><para>
5551                 The module-specific minor version.  For modules where this
5552                 version is used for more than simply informational
5553                 purposes, the minor version should only change (be
5554                 incremented) when ABI additions are made in a backward
5555                 compatible way.  It should be reset to zero when the major
5556                 version is increased.
5557               </para></listitem></varlistentry>
5558
5559
5560           <varlistentry>
5561             <term><structfield>patchlevel</structfield></term>
5562             <listitem><para>
5563                 The module-specific patch level.  The patch level should
5564                 increase with new revisions of the module where there
5565                 are no ABI changes, and it should be reset to zero when
5566                 the minor version is increased.
5567               </para></listitem></varlistentry>
5568
5569
5570           <varlistentry>
5571             <term><structfield>abiclass</structfield></term>
5572             <listitem><para>
5573                 The ABI class that the module requires.  The class is
5574                 specified as a string for easy extensibility.  It should
5575                 indicate which (if any) of the X server's built-in ABI
5576                 classes that the module relies on, or a third-party ABI
5577                 if appropriate.  Built-in ABI classes currently defined are:
5578
5579                 <variablelist>
5580                   <varlistentry>
5581                     <term><constant>ABI_CLASS_NONE</constant></term>
5582                     <listitem><para>no class
5583                       </para></listitem></varlistentry>
5584                   <varlistentry>
5585                     <term><constant>ABI_CLASS_ANSIC</constant></term>
5586                     <listitem><para>only requires the ANSI C interfaces
5587                       </para></listitem></varlistentry>
5588                   <varlistentry>
5589                     <term><constant>ABI_CLASS_VIDEODRV</constant></term>
5590                     <listitem><para>requires the video driver ABI
5591                       </para></listitem></varlistentry>
5592                   <varlistentry>
5593                     <term><constant>ABI_CLASS_XINPUT</constant></term>
5594                     <listitem><para>requires the XInput driver ABI
5595                       </para></listitem></varlistentry>
5596                   <varlistentry>
5597                     <term><constant>ABI_CLASS_EXTENSION</constant></term>
5598                     <listitem><para>requires the extension module ABI
5599                       </para></listitem></varlistentry>
5600                   <varlistentry>
5601                     <term><constant>ABI_CLASS_FONT</constant></term>
5602                     <listitem><para>requires the font module ABI
5603                       </para></listitem></varlistentry>
5604                 </variablelist>
5605
5606               </para></listitem></varlistentry>
5607
5608           <varlistentry>
5609             <term><structfield>abiversion</structfield></term>
5610             <listitem><para>
5611                 The version of abiclass that the module requires.  The
5612                 version consists of major and minor components.  The
5613                 major version must match and the minor version must be
5614                 no newer than that provided by the server or parent
5615                 module.  Version identifiers for the built-in classes
5616                 currently defined are:
5617
5618                 <literallayout><constant>
5619                    ABI_ANSIC_VERSION
5620                    ABI_VIDEODRV_VERSION
5621                    ABI_XINPUT_VERSION
5622                    ABI_EXTENSION_VERSION
5623                    ABI_FONT_VERSION
5624                   </constant></literallayout>
5625
5626               </para></listitem></varlistentry>
5627
5628           <varlistentry>
5629             <term><structfield>moduleclass</structfield></term>
5630             <listitem><para>
5631                 This is similar to the abiclass field, except that it
5632                 defines the type of module rather than the ABI it
5633                 requires.  For example, although all video drivers require
5634                 the video driver ABI, not all modules that require the
5635                 video driver ABI are video drivers.  This distinction
5636                 can be made with the moduleclass.  Currently pre-defined
5637                 module classes are:
5638
5639                 <literallayout><constant>
5640                    MOD_CLASS_NONE
5641                    MOD_CLASS_VIDEODRV
5642                    MOD_CLASS_XINPUT
5643                    MOD_CLASS_FONT
5644                    MOD_CLASS_EXTENSION
5645                   </constant></literallayout>
5646
5647               </para></listitem></varlistentry>
5648
5649           <varlistentry>
5650             <term><structfield>checksum</structfield></term>
5651             <listitem><para>
5652                 Not currently used.
5653               </para></listitem></varlistentry>
5654
5655         </variablelist>
5656       </para>
5657
5658       <para>
5659 The module version information, and the optional <function>SetupProc</function>
5660 and <function>TearDownProc</function> entry points are found by the loader
5661 by locating a data object in the module called "modnameModuleData",
5662 where "modname" is the canonical name of the module.  Modules must
5663 contain such a data object, and it must be declared with global scope,
5664 be compile-time initialised, and is of the following type:
5665
5666         <programlisting>
5667 typedef struct {
5668     XF86ModuleVersionInfo *     vers;
5669     ModuleSetupProc             setup;
5670     ModuleTearDownProc          teardown;
5671 } XF86ModuleData;
5672         </programlisting>
5673       </para>
5674
5675       <para>
5676 The vers parameter must be initialised to a pointer to a correctly
5677 initialised <structname>XF86ModuleVersionInfo</structname> struct.  The other
5678 two parameter are optional, and should be initialised to
5679 <constant>NULL</constant> when not required.  The other parameters are defined
5680 as
5681
5682         <blockquote><para>
5683             <programlisting>
5684     typedef pointer (*ModuleSetupProc)(pointer, pointer, int *, int *);
5685
5686     typedef void (*ModuleTearDownProc)(pointer);
5687
5688     pointer SetupProc(pointer module, pointer options,
5689                       int *errmaj, int *errmin);
5690             </programlisting>
5691             <blockquote><para>
5692     When defined, this function is called by the loader after successfully
5693     loading a module.  module is a handle for the newly loaded module,
5694     and maybe used by the <function>SetupProc</function> if it calls other
5695     loader functions that require a reference to it.   The remaining
5696     arguments are those that were passed to the
5697     <function>LoadModule()</function> (or <function>LoadSubModule()</function>),
5698     and are described above. When the <function>SetupProc</function> is
5699     successful it must return a non-<constant>NULL</constant> value.  The
5700     loader checks this, and if it is <constant>NULL</constant> it unloads
5701     the module and reports the failure to the caller of
5702     <function>LoadModule()</function>.  If the <function>SetupProc</function>
5703     does things that need to be undone when the module is unloaded,
5704     it should define a <function>TearDownProc</function>, and return a
5705     pointer that the <function>TearDownProc</function> can use to undo what
5706     has been done.
5707               </para>
5708
5709               <para>
5710     When a module is loaded multiple times, the <function>SetupProc</function>
5711     is called once for each time it is loaded.
5712               </para>
5713
5714             </blockquote></para></blockquote>
5715
5716         <blockquote><para>
5717             <programlisting>
5718     void TearDownProc(pointer tearDownData);
5719             </programlisting>
5720             <blockquote><para>
5721     When defined, this function is called when the loader unloads a
5722     module.  The <parameter>tearDownData</parameter> parameter is the return
5723     value of the <function>SetupProc()</function> that was called when the
5724     module was loaded.  The purpose of this function is to clean up
5725     before the module is unloaded (for example, by freeing allocated
5726     resources).
5727               </para>
5728
5729             </blockquote></para></blockquote>
5730       </para>
5731     </sect2>
5732
5733     <sect2>
5734       <title>Public Loader Interface</title>
5735
5736       <para>
5737 The following is the Loader interface that is available to any part of
5738 the server, and may also be used from within modules.
5739       </para>
5740
5741       <blockquote><para>
5742           <programlisting>
5743     pointer LoadSubModule(pointer parent, const char *module,
5744                           const char **subdirlist, const char **patternlist,
5745                           pointer options, const XF86ModReqInfo * modreq,
5746                           int *errmaj, int *errmin);
5747           </programlisting>
5748           <blockquote><para>
5749     This function is like the <function>LoadModule()</function> function
5750     described above, except that the module loaded is registered as a
5751     child of the calling module.  The <parameter>parent</parameter> parameter
5752     is the calling module's handle.  Modules loaded with this function
5753     are automatically unloaded when the parent module is unloaded.  The
5754     other difference is that the path parameter may not be specified.
5755     The module search path used for modules loaded with this function
5756     is the default search path as initialised with
5757     <function>LoaderSetPath()</function>.
5758             </para>
5759
5760           </blockquote></para></blockquote>
5761
5762       <blockquote><para>
5763           <programlisting>
5764     void UnloadSubModule(pointer module);
5765           </programlisting>
5766           <blockquote><para>
5767     This function unloads the module with handle <parameter>module</parameter>.
5768     If that module itself has children, they are also unloaded.  It is
5769     like <function>UnloadModule()</function>, except that it is safe to use
5770     for unloading child modules.
5771             </para>
5772
5773           </blockquote></para></blockquote>
5774
5775       <blockquote><para>
5776           <programlisting>
5777     pointer LoaderSymbol(const char *symbol);
5778           </programlisting>
5779         <blockquote><para>
5780     This function returns the address of the symbol with name
5781     <parameter>symbol</parameter>.  This may be used to locate a module entry
5782     point with a known name.
5783             </para>
5784
5785           </blockquote></para></blockquote>
5786
5787       <blockquote><para>
5788           <programlisting>
5789     char **LoaderlistDirs(const char **subdirlist,
5790                           const char **patternlist);
5791           </programlisting>
5792           <blockquote><para>
5793     This function returns a <constant>NULL</constant> terminated list of
5794     canonical modules names for modules found in the default module
5795     search path.  The <parameter>subdirlist</parameter> and
5796     <parameter>patternlist</parameter> parameters are as described above, and
5797     can be used to control the locations and names that are searched.
5798     If no modules are found, the return value is <constant>NULL</constant>.
5799     The returned list should be freed by calling
5800     <function>LoaderFreeDirList()</function> when it is no longer needed.
5801             </para>
5802
5803           </blockquote></para></blockquote>
5804
5805       <blockquote><para>
5806           <programlisting>
5807     void LoaderFreeDirList(char **list);
5808           </programlisting>
5809           <blockquote><para>
5810     This function frees a module list created by
5811     <function>LoaderlistDirs()</function>.
5812             </para>
5813
5814           </blockquote></para></blockquote>
5815
5816       <blockquote><para>
5817           <programlisting>
5818     void LoaderReqSymLists(const char **list0, ...);
5819           </programlisting>
5820           <blockquote><para>
5821     This function allows the registration of required symbols with the
5822     loader.  It is normally used by a caller of
5823     <function>LoadSubModule()</function>.  If any symbols registered in this
5824     way are found to be unresolved when
5825     <function>LoaderCheckUnresolved()</function> is called then
5826     <function>LoaderCheckUnresolved()</function> will report a failure.
5827     The function takes one or more <constant>NULL</constant> terminated
5828     lists of symbols.  The end of the argument list is indicated by a
5829     <constant>NULL</constant> argument.
5830             </para>
5831
5832           </blockquote></para></blockquote>
5833
5834       <blockquote><para>
5835           <programlisting>
5836     void LoaderReqSymbols(const char *sym0, ...);
5837           </programlisting>
5838         <blockquote><para>
5839     This function is like <function>LoaderReqSymLists()</function> except
5840     that its arguments are symbols rather than lists of symbols.  This
5841     function is more convenient when single functions are to be registered,
5842     especially when the single function might depend on runtime factors.
5843     The end of the argument list is indicated by a <constant>NULL</constant>
5844     argument.
5845             </para>
5846
5847           </blockquote></para></blockquote>
5848
5849       <blockquote><para>
5850           <programlisting>
5851     void LoaderRefSymLists(const char **list0, ...);
5852           </programlisting>
5853           <blockquote><para>
5854     This function allows the registration of possibly unresolved symbols
5855     with the loader.  When <function>LoaderCheckUnresolved()</function> is
5856     run it won't generate warnings for symbols registered in this way
5857     unless they were also registered as required symbols.
5858     The function takes one or more <constant>NULL</constant> terminated
5859     lists of symbols.  The end of the argument list is indicated by a
5860     <constant>NULL</constant> argument.
5861             </para>
5862
5863           </blockquote></para></blockquote>
5864
5865       <blockquote><para>
5866           <programlisting>
5867     void LoaderRefSymbols(const char *sym0, ...);
5868           </programlisting>
5869           <blockquote><para>
5870     This function is like <function>LoaderRefSymLists()</function> except
5871     that its arguments are symbols rather than lists of symbols.  This
5872     function is more convenient when single functions are to be registered,
5873     especially when the single function might depend on runtime factors.
5874     The end of the argument list is indicated by a <constant>NULL</constant>
5875     argument.
5876             </para>
5877
5878           </blockquote></para></blockquote>
5879
5880       <blockquote><para>
5881           <programlisting>
5882     int LoaderCheckUnresolved(int delayflag);
5883           </programlisting>
5884           <blockquote><para>
5885     This function checks for unresolved symbols.  It generates warnings
5886     for unresolved symbols that have not been registered with
5887     <function>LoaderRefSymLists()</function>, and maps them to a dummy
5888     function.  This behaviour may change in future.  If unresolved
5889     symbols are found that have been registered with
5890     <function>LoaderReqSymLists()</function> or
5891     <function>LoaderReqSymbols()</function> then this function returns a
5892     non-zero value.  If none of these symbols are unresolved the return
5893     value is zero, indicating success.
5894             </para>
5895
5896             <para>
5897     The <parameter>delayflag</parameter> parameter should normally be set to
5898     <constant>LD_RESOLV_IFDONE</constant>.
5899             </para>
5900
5901           </blockquote></para></blockquote>
5902
5903       <blockquote><para>
5904           <programlisting>
5905     LoaderErrorMsg(const char *name, const char *modname,
5906                    int errmaj, int errmin);
5907           </programlisting>
5908           <blockquote><para>
5909     This function prints an error message that includes the text <quote>Failed
5910     to load module</quote>, the module name <parameter>modname</parameter>, a message
5911     specific to the <parameter>errmaj</parameter> value, and the value if
5912     <parameter>errmin</parameter>.  If <parameter>name</parameter> is
5913     non-<constant>NULL</constant>, it is printed as an identifying prefix
5914     to the message (followed by a <quote>:</quote>).
5915             </para>
5916
5917           </blockquote></para></blockquote>
5918     </sect2>
5919
5920     <sect2>
5921       <title>Special Registration Functions</title>
5922
5923       <para>
5924 The loader contains some functions for registering some classes of modules.
5925 These may be moved out of the loader at some point.
5926       </para>
5927
5928       <blockquote><para>
5929           <programlisting>
5930     void LoadExtension(ExtensionModule *ext);
5931           </programlisting>
5932           <blockquote><para>
5933     This registers the entry points for the extension identified by
5934     <parameter>ext</parameter>.  The <structname>ExtensionModule</structname> struct is
5935     defined as:
5936
5937               <programlisting>
5938 typedef struct {
5939     InitExtension       initFunc;
5940     char *              name;
5941     Bool                *disablePtr;
5942 } ExtensionModule;
5943               </programlisting>
5944             </para>
5945
5946           </blockquote></para></blockquote>
5947
5948     </sect2>
5949
5950   </sect1>
5951
5952   <sect1>
5953     <title>Helper Functions</title>
5954
5955     <para>
5956 This section describe <quote>helper</quote> functions that video driver
5957 might find useful.  While video drivers are not required to use any of
5958 these to be considered <quote>compliant</quote>, the use of appropriate helpers is
5959 strongly encouraged to improve the consistency of driver behaviour.
5960     </para>
5961
5962     <sect2>
5963       <title>Functions for printing messages</title>
5964
5965       <blockquote><para>
5966           <programlisting>
5967     ErrorF(const char *format, ...);
5968           </programlisting>
5969           <blockquote><para>
5970       This is the basic function for writing to the error log (typically
5971       stderr and/or a log file).  Video drivers should usually avoid
5972       using this directly in favour of the more specialised functions
5973       described below.  This function is useful for printing messages
5974       while debugging a driver.
5975             </para>
5976
5977           </blockquote></para></blockquote>
5978
5979       <blockquote><para>
5980           <programlisting>
5981     FatalError(const char *format, ...);
5982           </programlisting>
5983           <blockquote><para>
5984       This prints a message and causes the Xserver to abort.  It should
5985       rarely be used within a video driver, as most error conditions
5986       should be flagged by the return values of the driver functions.
5987       This allows the higher layers to decide how to proceed.  In rare
5988       cases, this can be used within a driver if a fatal unexpected
5989       condition is found.
5990             </para>
5991
5992           </blockquote></para></blockquote>
5993
5994       <blockquote><para>
5995           <programlisting>
5996     xf86ErrorF(const char *format, ...);
5997           </programlisting>
5998           <blockquote><para>
5999       This is like <function>ErrorF()</function>, except that the message is
6000       only printed when the Xserver's verbosity level is set to the
6001       default (<constant>1</constant>) or higher.  It means that the messages
6002       are not printed when the server is started with the
6003       <option>-quiet</option> flag.  Typically this function would only be
6004       used for continuing messages started with one of the more specialised
6005       functions described below.
6006             </para>
6007
6008           </blockquote></para></blockquote>
6009
6010       <blockquote><para>
6011           <programlisting>
6012     xf86ErrorFVerb(int verb, const char *format, ...);
6013           </programlisting>
6014           <blockquote><para>
6015       Like <function>xf86ErrorF()</function>, except the minimum verbosity
6016       level for which the message is to be printed is given explicitly.
6017       Passing a <parameter>verb</parameter> value of zero means the message
6018       is always printed.  A value higher than <constant>1</constant> can be
6019       used for information would normally not be needed, but which might
6020       be useful when diagnosing problems.
6021             </para>
6022
6023           </blockquote></para></blockquote>
6024
6025
6026       <blockquote><para>
6027           <programlisting>
6028     xf86Msg(MessageType type, const char *format, ...);
6029           </programlisting>
6030           <blockquote><para>
6031       This is like <function>xf86ErrorF()</function>, except that the message
6032       is prefixed with a marker determined by the value of
6033       <parameter>type</parameter>.  The marker is used to indicate the type of
6034       message (warning, error, probed value, config value, etc).  Note
6035       the <varname>xf86Verbose</varname> value is ignored for messages of
6036       type <constant>X_ERROR</constant>.
6037             </para>
6038
6039             <para>
6040       The marker values are:
6041
6042               <variablelist>
6043                 <varlistentry>
6044                   <term><constant>X_PROBED</constant></term>
6045                   <listitem><para>Value was probed.
6046                     </para></listitem></varlistentry>
6047                 <varlistentry>
6048                   <term><constant>X_CONFIG</constant></term>
6049                   <listitem><para>Value was given in the config file.
6050                     </para></listitem></varlistentry>
6051                 <varlistentry>
6052                   <term><constant>X_DEFAULT</constant></term>
6053                   <listitem><para>Value is a default.
6054                     </para></listitem></varlistentry>
6055                 <varlistentry>
6056                   <term><constant>X_CMDLINE</constant></term>
6057                   <listitem><para>Value was given on the command line.
6058                     </para></listitem></varlistentry>
6059                 <varlistentry>
6060                   <term><constant>X_NOTICE</constant></term>
6061                   <listitem><para>Notice.
6062                     </para></listitem></varlistentry>
6063                 <varlistentry>
6064                   <term><constant>X_ERROR</constant></term>
6065                   <listitem><para>Error message.
6066                     </para></listitem></varlistentry>
6067                 <varlistentry>
6068                   <term><constant>X_WARNING</constant></term>
6069                   <listitem><para>Warning message.
6070                     </para></listitem></varlistentry>
6071                 <varlistentry>
6072                   <term><constant>X_INFO</constant></term>
6073                   <listitem><para>Informational message.
6074                     </para></listitem></varlistentry>
6075                 <varlistentry>
6076                   <term><constant>X_NONE</constant></term>
6077                   <listitem><para>No prefix.
6078                     </para></listitem></varlistentry>
6079                 <varlistentry>
6080                   <term><constant>X_NOT_IMPLEMENTED</constant></term>
6081                   <listitem><para>The message relates to functionality
6082                       that is not yetimplemented.
6083                     </para></listitem></varlistentry>
6084                 </variablelist>
6085
6086             </para>
6087
6088           </blockquote></para></blockquote>
6089
6090       <blockquote><para>
6091           <programlisting>
6092     xf86MsgVerb(MessageType type, int verb, const char *format, ...);
6093           </programlisting>
6094           <blockquote><para>
6095       Like <function>xf86Msg()</function>, but with the verbosity level given
6096       explicitly.
6097             </para>
6098
6099           </blockquote></para></blockquote>
6100
6101       <blockquote><para>
6102           <programlisting>
6103     xf86DrvMsg(int scrnIndex, MessageType type, const char *format, ...);
6104           </programlisting>
6105           <blockquote><para>
6106       This is like <function>xf86Msg()</function> except that the driver's
6107       name (the <structfield>name</structfield> field of the
6108       <structname>ScrnInfoRec</structname>) followed by the
6109       <parameter>scrnIndex</parameter> in parentheses is printed following the
6110       prefix.  This should be used by video drivers in most cases as it
6111       clearly indicates which driver/screen the message is for.  If
6112       <parameter>scrnIndex</parameter> is negative, this function behaves
6113       exactly like <function>xf86Msg()</function>.
6114             </para>
6115
6116             <para>
6117       NOTE: This function can only be used after the
6118       <structname>ScrnInfoRec</structname> and its <structfield>name</structfield> field
6119       have been allocated.  Normally, this means that it can not be
6120       used before the END of the <function>ChipProbe()</function> function.
6121       Prior to that, use <function>xf86Msg()</function>, providing the
6122       driver's name explicitly.  No screen number can be supplied at
6123       that point.
6124             </para>
6125
6126           </blockquote></para></blockquote>
6127
6128       <blockquote><para>
6129           <programlisting>
6130     xf86DrvMsgVerb(int scrnIndex, MessageType type, int verb,
6131                                 const char *format, ...);
6132           </programlisting>
6133           <blockquote><para>
6134       Like <function>xf86DrvMsg()</function>, but with the verbosity level
6135       given explicitly.
6136             </para>
6137
6138           </blockquote></para></blockquote>
6139     </sect2>
6140
6141
6142     <sect2>
6143       <title>Functions for setting values based on command line and config file</title>
6144
6145       <blockquote><para>
6146           <programlisting>
6147     Bool xf86SetDepthBpp(ScrnInfoPtr scrp, int depth, int bpp,
6148
6149                                 int fbbpp, int depth24flags);
6150           </programlisting>
6151           <blockquote><para>
6152       This function sets the <structfield>depth</structfield>, <structfield>pixmapBPP</structfield> and <structfield>bitsPerPixel</structfield> fields
6153       of the <structname>ScrnInfoRec</structname>.  It also determines the defaults for display-wide
6154       attributes and pixmap formats the screen will support, and finds
6155       the Display subsection that matches the depth/bpp.  This function
6156       should normally be called very early from the
6157       <function>ChipPreInit()</function> function.
6158             </para>
6159
6160             <para>
6161       It requires that the <structfield>confScreen</structfield> field of the <structname>ScrnInfoRec</structname> be
6162       initialised prior to calling it.  This is done by the XFree86
6163       common layer prior to calling <function>ChipPreInit()</function>.
6164             </para>
6165
6166             <para>
6167       The parameters passed are:
6168
6169               <variablelist>
6170                 <varlistentry>
6171                   <term><parameter>depth</parameter></term>
6172                   <listitem><para>
6173                 driver's preferred default depth if no other is given.
6174                 If zero, use the overall server default.
6175                     </para></listitem></varlistentry>
6176
6177                 <varlistentry>
6178                   <term><parameter>bpp</parameter></term>
6179                   <listitem><para>
6180                 Same, but for the pixmap bpp.
6181                     </para></listitem></varlistentry>
6182
6183                 <varlistentry>
6184                   <term><parameter>fbbpp</parameter></term>
6185                   <listitem><para>
6186                 Same, but for the framebuffer bpp.
6187                     </para></listitem></varlistentry>
6188
6189                 <varlistentry>
6190                   <term><parameter>depth24flags</parameter></term>
6191                   <listitem><para>
6192                 Flags that indicate the level of 24/32bpp support
6193                 and whether conversion between different framebuffer
6194                 and pixmap formats is supported.  The flags for this
6195                 argument are defined as follows, and multiple flags
6196                 may be ORed together:
6197
6198                       <variablelist>
6199                         <varlistentry>
6200                           <term><constant>NoDepth24Support</constant></term>
6201                           <listitem><para>No depth 24 formats supported
6202                             </para></listitem></varlistentry>
6203                         <varlistentry>
6204                           <term><constant>Support24bppFb</constant></term>
6205                           <listitem><para>24bpp framebuffer supported
6206                             </para></listitem></varlistentry>
6207                         <varlistentry>
6208                           <term><constant>Support32bppFb</constant></term>
6209                           <listitem><para>32bpp framebuffer supported
6210                             </para></listitem></varlistentry>
6211                         <varlistentry>
6212                           <term><constant>SupportConvert24to32</constant></term>
6213                           <listitem><para>Can convert 24bpp pixmap to 32bpp fb
6214                             </para></listitem></varlistentry>
6215                         <varlistentry>
6216                           <term><constant>SupportConvert32to24</constant></term>
6217                           <listitem><para>Can convert 32bpp pixmap to 24bpp fb
6218                             </para></listitem></varlistentry>
6219                         <varlistentry>
6220                           <term><constant>ForceConvert24to32</constant></term>
6221                           <listitem><para>Force 24bpp pixmap to 32bpp fb conversion
6222                             </para></listitem></varlistentry>
6223                         <varlistentry>
6224                           <term><constant>ForceConvert32to24</constant></term>
6225                           <listitem><para>Force 32bpp pixmap to 24bpp fb conversion
6226                             </para></listitem></varlistentry>
6227                       </variablelist>
6228                     </para></listitem></varlistentry>
6229
6230               </variablelist>
6231             </para>
6232
6233             <para>
6234       It uses the command line, config file, and default values in the
6235       correct order of precedence to determine the depth and bpp values.
6236       It is up to the driver to check the results to see that it supports
6237       them.  If not the <function>ChipPreInit()</function> function should
6238       return <constant>FALSE</constant>.
6239             </para>
6240
6241             <para>
6242       If only one of depth/bpp is given, the other is set to a reasonable
6243       (and consistent) default.
6244             </para>
6245
6246             <para>
6247       If a driver finds that the initial <parameter>depth24flags</parameter>
6248       it uses later results in a fb format that requires more video
6249       memory than is available it may call this function a second time
6250       with a different <parameter>depth24flags</parameter> setting.
6251             </para>
6252
6253             <para>
6254       On success, the return value is <constant>TRUE</constant>.  On failure
6255       it prints an error message and returns <constant>FALSE</constant>.
6256             </para>
6257
6258             <para>
6259       The following fields of the <structname>ScrnInfoRec</structname> are
6260       initialised by this function:
6261
6262               <blockquote><para>
6263 <structfield>depth</structfield>, <structfield>bitsPerPixel</structfield>,
6264 <structfield>display</structfield>, <structfield>imageByteOrder</structfield>,
6265 <structfield>bitmapScanlinePad</structfield>,
6266 <structfield>bitmapScanlineUnit</structfield>, <structfield>bitmapBitOrder</structfield>,
6267 <structfield>numFormats</structfield>, <structfield>formats</structfield>,
6268 <structfield>fbFormat</structfield>.
6269                 </para></blockquote>
6270             </para>
6271
6272           </blockquote></para></blockquote>
6273
6274       <blockquote><para>
6275           <programlisting>
6276     void xf86PrintDepthBpp(scrnInfoPtr scrp);
6277           </programlisting>
6278           <blockquote><para>
6279       This function can be used to print out the depth and bpp settings.
6280       It should be called after the final call to
6281       <function>xf86SetDepthBpp()</function>.
6282             </para>
6283
6284           </blockquote></para></blockquote>
6285
6286       <blockquote><para>
6287           <programlisting>
6288     Bool xf86SetWeight(ScrnInfoPtr scrp, rgb weight, rgb mask);
6289           </programlisting>
6290           <blockquote><para>
6291       This function sets the <structfield>weight</structfield>, <structfield>mask</structfield>,
6292       <structfield>offset</structfield> and <structfield>rgbBits</structfield> fields of the
6293       <structname>ScrnInfoRec</structname>.  It would normally be called fairly
6294       early in the <function>ChipPreInit()</function> function for
6295       depths&nbsp;&gt;&nbsp;8bpp.
6296             </para>
6297
6298             <para>
6299       It requires that the <structfield>depth</structfield> and
6300       <structfield>display</structfield> fields of the <structname>ScrnInfoRec</structname>
6301       be initialised prior to calling it.
6302             </para>
6303
6304             <para>
6305       The parameters passed are:
6306
6307               <variablelist>
6308                 <varlistentry>
6309                   <term><parameter>weight</parameter></term>
6310                   <listitem><para>
6311                 driver's preferred default weight if no other is given.
6312                 If zero, use the overall server default.
6313
6314                     </para></listitem></varlistentry>
6315
6316                 <varlistentry>
6317                   <term><parameter>mask</parameter></term>
6318                   <listitem><para>
6319                 Same, but for mask.
6320
6321                     </para></listitem></varlistentry>
6322               </variablelist>
6323             </para>
6324
6325             <para>
6326       It uses the command line, config file, and default values in the
6327       correct order of precedence to determine the weight value.  It
6328       derives the mask and offset values from the weight and the defaults.
6329       It is up to the driver to check the results to see that it supports
6330       them.  If not the <function>ChipPreInit()</function> function should
6331       return <constant>FALSE</constant>.
6332             </para>
6333
6334             <para>
6335       On success, this function prints a message showing the weight
6336       values selected, and returns <constant>TRUE</constant>.
6337             </para>
6338
6339             <para>
6340       On failure it prints an error message and returns <constant>FALSE</constant>.
6341             </para>
6342
6343             <para>
6344       The following fields of the <structname>ScrnInfoRec</structname> are
6345       initialised by this function:
6346
6347               <blockquote><para>
6348                   <structfield>weight</structfield>,
6349                   <structfield>mask</structfield>,
6350                   <structfield>offset</structfield>.
6351                 </para></blockquote>
6352             </para>
6353
6354           </blockquote></para></blockquote>
6355
6356       <blockquote><para>
6357           <programlisting>
6358     Bool xf86SetDefaultVisual(ScrnInfoPtr scrp, int visual);
6359           </programlisting>
6360           <blockquote><para>
6361       This function sets the <structfield>defaultVisual</structfield> field of the
6362       <structname>ScrnInfoRec</structname>.  It would normally be called fairly
6363       early from the <function>ChipPreInit()</function> function.
6364             </para>
6365
6366             <para>
6367       It requires that the <structfield>depth</structfield> and
6368       <structfield>display</structfield> fields of the <structname>ScrnInfoRec</structname>
6369       be initialised prior to calling it.
6370             </para>
6371
6372             <para>
6373       The parameters passed are:
6374
6375               <variablelist>
6376                 <varlistentry>
6377                   <term><parameter>visual</parameter></term>
6378                   <listitem><para>
6379                 driver's preferred default visual if no other is given.
6380                 If <constant>-1</constant>, use the overall server default.
6381                     </para></listitem></varlistentry>
6382
6383               </variablelist>
6384             </para>
6385
6386             <para>
6387       It uses the command line, config file, and default values in the
6388       correct order of precedence to determine the default visual value.
6389       It is up to the driver to check the result to see that it supports
6390       it.  If not the <function>ChipPreInit()</function> function should
6391       return <constant>FALSE</constant>.
6392             </para>
6393
6394             <para>
6395       On success, this function prints a message showing the default visual
6396       selected, and returns <constant>TRUE</constant>.
6397             </para>
6398
6399             <para>
6400       On failure it prints an error message and returns <constant>FALSE</constant>.
6401             </para>
6402
6403           </blockquote></para></blockquote>
6404
6405       <blockquote><para>
6406           <programlisting>
6407     Bool xf86SetGamma(ScrnInfoPtr scrp, Gamma gamma);
6408           </programlisting>
6409           <blockquote><para>
6410       This function sets the <structfield>gamma</structfield> field of the
6411       <structname>ScrnInfoRec</structname>.  It would normally be called fairly
6412       early from the <function>ChipPreInit()</function> function in cases
6413       where the driver supports gamma correction.
6414             </para>
6415
6416             <para>
6417       It requires that the <structfield>monitor</structfield> field of the
6418       <structname>ScrnInfoRec</structname> be initialised prior to calling it.
6419             </para>
6420
6421             <para>
6422       The parameters passed are:
6423
6424               <variablelist>
6425                 <varlistentry>
6426                   <term><parameter>gamma</parameter></term>
6427                   <listitem><para>
6428                 driver's preferred default gamma if no other is given.
6429                 If zero (<code>&lt; 0.01</code>), use the overall server
6430                 default.
6431                     </para></listitem></varlistentry>
6432
6433               </variablelist>
6434             </para>
6435
6436             <para>
6437       It uses the command line, config file, and default values in the
6438       correct order of precedence to determine the gamma value.  It is
6439       up to the driver to check the results to see that it supports
6440       them.  If not the <function>ChipPreInit()</function> function should
6441       return <constant>FALSE</constant>.
6442             </para>
6443
6444             <para>
6445       On success, this function prints a message showing the gamma
6446       value selected, and returns <constant>TRUE</constant>.
6447             </para>
6448
6449             <para>
6450       On failure it prints an error message and returns <constant>FALSE</constant>.
6451             </para>
6452
6453           </blockquote></para></blockquote>
6454
6455
6456       <blockquote><para>
6457           <programlisting>
6458     void xf86SetDpi(ScrnInfoPtr pScrn, int x, int y);
6459           </programlisting>
6460           <blockquote><para>
6461       This function sets the <structfield>xDpi</structfield> and <structfield>yDpi</structfield>
6462       fields of the <structname>ScrnInfoRec</structname>.  The driver can specify
6463       preferred defaults by setting <parameter>x</parameter> and <parameter>y</parameter>
6464       to non-zero values.  The <option>-dpi</option> command line option
6465       overrides all other settings.  Otherwise, if the
6466       <emphasis>DisplaySize</emphasis> entry is present in the screen's &k.monitor;
6467       config file section, it is used together with the virtual size to
6468       calculate the dpi values.  This function should be called after
6469       all the mode resolution has been done.
6470             </para>
6471
6472           </blockquote></para></blockquote>
6473
6474       <blockquote><para>
6475           <programlisting>
6476     void xf86SetBlackWhitePixels(ScrnInfoPtr pScrn);
6477           </programlisting>
6478           <blockquote><para>
6479       This functions sets the <structfield>blackPixel</structfield> and
6480       <structfield>whitePixel</structfield> fields of the <structname>ScrnInfoRec</structname>
6481       according to whether or not the <option>-flipPixels</option> command
6482       line options is present.
6483             </para>
6484
6485           </blockquote></para></blockquote>
6486
6487       <blockquote><para>
6488           <programlisting>
6489     const char *xf86GetVisualName(int visual);
6490           </programlisting>
6491           <blockquote><para>
6492       Returns a printable string with the visual name matching the
6493       numerical visual class provided.  If the value is outside the
6494       range of valid visual classes, <constant>NULL</constant> is returned.
6495             </para>
6496
6497           </blockquote></para></blockquote>
6498
6499     </sect2>
6500
6501     <sect2>
6502       <title>Primary Mode functions</title>
6503
6504       <para>
6505 The primary mode helper functions are those which would normally be
6506 used by a driver, unless it has unusual requirements which cannot
6507 be catered for the by the helpers.
6508       </para>
6509
6510       <blockquote><para>
6511           <programlisting>
6512     int xf86ValidateModes(ScrnInfoPtr scrp, DisplayModePtr availModes,
6513                           char **modeNames, ClockRangePtr clockRanges,
6514                           int *linePitches, int minPitch, int maxPitch,
6515                           int pitchInc, int minHeight, int maxHeight,
6516                           int virtualX, int virtualY,
6517                           unsigned long apertureSize,
6518                           LookupModeFlags strategy);
6519           </programlisting>
6520           <blockquote><para>
6521       This function basically selects the set of modes to use based on
6522       those available and the various constraints.  It also sets some
6523       other related parameters.  It is normally called near the end of
6524       the <function>ChipPreInit()</function> function.
6525             </para>
6526
6527             <para>
6528       The parameters passed to the function are:
6529
6530               <variablelist>
6531                 <varlistentry>
6532                   <term><parameter>availModes</parameter></term>
6533                   <listitem><para>
6534                 List of modes available for the monitor.
6535                     </para></listitem></varlistentry>
6536
6537                 <varlistentry>
6538                   <term><parameter>modeNames</parameter></term>
6539                   <listitem><para>
6540                 List of mode names that the screen is requesting.
6541                     </para></listitem></varlistentry>
6542
6543                 <varlistentry>
6544                   <term><parameter>clockRanges</parameter></term>
6545                   <listitem><para>
6546                 A list of clock ranges allowed by the driver.  Each
6547                 range includes whether interlaced or multiscan modes
6548                 are supported for that range.  See below for more on
6549                 <parameter>clockRanges</parameter>.
6550                     </para></listitem></varlistentry>
6551
6552                 <varlistentry>
6553                   <term><parameter>linePitches</parameter></term>
6554                   <listitem><para>
6555                 List of line pitches supported by the driver.
6556                 This is optional and should be <constant>NULL</constant> when
6557                 not used.
6558                     </para></listitem></varlistentry>
6559
6560                 <varlistentry>
6561                   <term><parameter>minPitch</parameter></term>
6562                   <listitem><para>
6563                 Minimum line pitch supported by the driver.  This must
6564                 be supplied when <parameter>linePitches</parameter> is
6565                 <constant>NULL</constant>, and is ignored otherwise.
6566                     </para></listitem></varlistentry>
6567
6568                 <varlistentry>
6569                   <term><parameter>maxPitch</parameter></term>
6570                   <listitem><para>
6571                 Maximum line pitch supported by the driver.  This is
6572                 required when <parameter>minPitch</parameter> is required.
6573                     </para></listitem></varlistentry>
6574
6575                 <varlistentry>
6576                   <term><parameter>pitchInc</parameter></term>
6577                   <listitem><para>
6578                 Granularity of horizontal pitch values as supported by
6579                 the chipset.  This is expressed in bits.  This must be
6580                 supplied.
6581                     </para></listitem></varlistentry>
6582
6583                 <varlistentry>
6584                   <term><parameter>minHeight</parameter></term>
6585                   <listitem><para>
6586                 minimum virtual height allowed.  If zero, no limit is
6587                 imposed.
6588                     </para></listitem></varlistentry>
6589
6590                 <varlistentry>
6591                   <term><parameter>maxHeight</parameter></term>
6592                   <listitem><para>
6593                 maximum virtual height allowed.  If zero, no limit is
6594                 imposed.
6595                     </para></listitem></varlistentry>
6596
6597                 <varlistentry>
6598                   <term><parameter>virtualX</parameter></term>
6599                   <listitem><para>
6600                 If greater than zero, this is the virtual width value
6601                 that will be used.  Otherwise, the virtual width is
6602                 chosen to be the smallest that can accommodate the modes
6603                 selected.
6604                     </para></listitem></varlistentry>
6605
6606                 <varlistentry>
6607                   <term><parameter>virtualY</parameter></term>
6608                   <listitem><para>
6609                 If greater than zero, this is the virtual height value
6610                 that will be used.  Otherwise, the virtual height is
6611                 chosen to be the smallest that can accommodate the modes
6612                 selected.
6613                     </para></listitem></varlistentry>
6614
6615                 <varlistentry>
6616                   <term><parameter>apertureSize</parameter></term>
6617                   <listitem><para>
6618                 The size (in bytes) of the aperture used to access video
6619                 memory.
6620                     </para></listitem></varlistentry>
6621
6622                 <varlistentry>
6623                   <term><parameter>strategy</parameter></term>
6624                   <listitem><para>
6625                 The strategy to use when choosing from multiple modes
6626                 with the same name.  The options are:
6627
6628                       <variablelist>
6629                         <varlistentry>
6630                           <term><constant>LOOKUP_DEFAULT</constant></term>
6631                           <listitem><para>???
6632                             </para></listitem></varlistentry>
6633                         <varlistentry>
6634                           <term><constant>LOOKUP_BEST_REFRESH</constant></term>
6635                           <listitem><para>mode with best refresh rate
6636                             </para></listitem></varlistentry>
6637                         <varlistentry>
6638                           <term><constant>LOOKUP_CLOSEST_CLOCK</constant></term>
6639                           <listitem><para>mode with closest matching clock
6640                             </para></listitem></varlistentry>
6641                         <varlistentry>
6642                           <term><constant>LOOKUP_LIST_ORDER</constant></term>
6643                           <listitem><para>first usable mode in list
6644                             </para></listitem></varlistentry>
6645                       </variablelist>
6646
6647                 The following options can also be combined (OR'ed) with
6648                 one of the above:
6649
6650                       <variablelist>
6651                         <varlistentry>
6652                           <term><constant>LOOKUP_CLKDIV2</constant></term>
6653                           <listitem><para>Allow halved clocks
6654                             </para></listitem></varlistentry>
6655                         <varlistentry>
6656                           <term><constant>LOOKUP_OPTIONAL_TOLERANCES</constant></term>
6657                           <listitem><para>
6658                       Allow missing horizontal sync and/or vertical refresh
6659                       ranges in the xorg.conf Monitor section
6660                             </para></listitem></varlistentry>
6661                       </variablelist>
6662
6663                 <constant>LOOKUP_OPTIONAL_TOLERANCES</constant> should only be
6664                 specified when the driver can ensure all modes it generates
6665                 can sync on, or at least not damage, the monitor or digital
6666                 flat panel.  Horizontal sync and/or vertical refresh ranges
6667                 specified by the user will still be honoured (and acted upon).
6668
6669                     </para></listitem></varlistentry>
6670               </variablelist>
6671             </para>
6672
6673             <para>
6674       This function requires that the following fields of the
6675       <structname>ScrnInfoRec</structname> are initialised prior to calling it:
6676
6677               <variablelist>
6678                 <varlistentry>
6679                   <term><structfield>clock[]</structfield></term>
6680                   <listitem><para>
6681                       List of discrete clocks (when non-programmable)
6682                     </para></listitem></varlistentry>
6683                 <varlistentry>
6684                   <term><structfield>numClocks</structfield></term>
6685                   <listitem><para>
6686                       Number of discrete clocks (when non-programmable)
6687                     </para></listitem></varlistentry>
6688                 <varlistentry>
6689                   <term><structfield>progClock</structfield></term>
6690                   <listitem><para>
6691                       Whether the clock is programmable or not
6692                     </para></listitem></varlistentry>
6693                 <varlistentry>
6694                   <term><structfield>monitor</structfield></term>
6695                   <listitem><para>
6696                       Pointer to the applicable xorg.conf monitor section
6697                     </para></listitem></varlistentry>
6698                 <varlistentry>
6699                   <term><structfield>fdFormat</structfield></term>
6700                   <listitem><para>
6701                       Format of the screen buffer
6702                     </para></listitem></varlistentry>
6703                 <varlistentry>
6704                   <term><structfield>videoRam</structfield></term>
6705                   <listitem><para>
6706                       total video memory size (in bytes)
6707                     </para></listitem></varlistentry>
6708                 <varlistentry>
6709                   <term><structfield>maxHValue</structfield></term>
6710                   <listitem><para>
6711                       Maximum horizontal timing value allowed
6712                     </para></listitem></varlistentry>
6713                 <varlistentry>
6714                   <term><structfield>maxVValue</structfield></term>
6715                   <listitem><para>
6716                       Maximum vertical timing value allowed
6717                     </para></listitem></varlistentry>
6718                 <varlistentry>
6719                   <term><structfield>xInc</structfield></term>
6720                   <listitem><para>
6721                       Horizontal timing increment in pixels (defaults to 8)
6722                     </para></listitem></varlistentry>
6723               </variablelist>
6724             </para>
6725
6726             <para>
6727       This function fills in the following <structname>ScrnInfoRec</structname>
6728       fields:
6729
6730               <variablelist>
6731                 <varlistentry>
6732                   <term><structfield>modePool</structfield></term>
6733                   <listitem><para>
6734                 A subset of the modes available to the monitor which
6735                 are compatible with the driver.
6736                     </para></listitem></varlistentry>
6737
6738                 <varlistentry>
6739                   <term><structfield>modes</structfield></term>
6740                   <listitem><para>
6741                 One mode entry for each of the requested modes, with
6742                 the status field of each filled in to indicate if
6743                 the mode has been accepted or not.  This list of
6744                 modes is a circular list.
6745                     </para></listitem></varlistentry>
6746
6747                 <varlistentry>
6748                   <term><structfield>virtualX</structfield></term>
6749                   <listitem><para>
6750                 The resulting virtual width.
6751                     </para></listitem></varlistentry>
6752
6753                 <varlistentry>
6754                   <term><structfield>virtualY</structfield></term>
6755                   <listitem><para>
6756                 The resulting virtual height.
6757                     </para></listitem></varlistentry>
6758
6759                 <varlistentry>
6760                   <term><structfield>displayWidth</structfield></term>
6761                   <listitem><para>
6762                 The resulting line pitch.
6763                     </para></listitem></varlistentry>
6764
6765                 <varlistentry>
6766                   <term><structfield>virtualFrom</structfield></term>
6767                   <listitem><para>
6768                 Where the virtual size was determined from.
6769                     </para></listitem></varlistentry>
6770
6771               </variablelist>
6772             </para>
6773
6774             <para>
6775       The first stage of this function checks that the
6776       <parameter>virtualX</parameter> and <parameter>virtualY</parameter> values
6777       supplied (if greater than zero) are consistent with the line pitch
6778       and <parameter>maxHeight</parameter> limitations.  If not, an error
6779       message is printed, and the return value is <constant>-1</constant>.
6780             </para>
6781
6782             <para>
6783       The second stage sets up the mode pool, eliminating immediately
6784       any modes that exceed the driver's line pitch limits, and also
6785       the virtual width and height limits (if greater than zero).  For
6786       each mode removed an informational message is printed at verbosity
6787       level <constant>2</constant>.  If the mode pool ends up being empty,
6788       a warning message is printed, and the return value is
6789       <constant>0</constant>.
6790             </para>
6791
6792             <para>
6793       The final stage is to lookup each mode name, and fill in the remaining
6794       parameters.  If an error condition is encountered, a message is
6795       printed, and the return value is <constant>-1</constant>.  Otherwise,
6796       the return value is the number of valid modes found
6797       (<constant>0</constant> if none are found).
6798             </para>
6799
6800             <para>
6801       Even if the supplied mode names include duplicates, no two names will
6802       ever match the same mode.  Furthermore, if the supplied mode names do not
6803       yield a valid mode (including the case where no names are passed at all),
6804       the function will continue looking through the mode pool until it finds
6805       a mode that survives all checks, or until the mode pool is exhausted.
6806             </para>
6807
6808             <para>
6809       A message is only printed by this function when a fundamental
6810       problem is found.  It is intended that this function may be called
6811       more than once if there is more than one set of constraints that
6812       the driver can work within.
6813             </para>
6814
6815             <para>
6816       If this function returns <constant>-1</constant>, the
6817       <function>ChipPreInit()</function> function should return
6818       <constant>FALSE</constant>.
6819             </para>
6820
6821             <para>
6822       <parameter>clockRanges</parameter> is a linked list of clock ranges
6823       allowed by the driver.  If a mode doesn't fit in any of the defined
6824       <parameter>clockRanges</parameter>, it is rejected.  The first
6825       <literal remap="tt">clockRange</literal> that matches all requirements is used.
6826       This structure needs to be initialized to NULL when allocated.
6827             </para>
6828
6829             <para>
6830       <parameter>clockRanges</parameter> contains the following fields:
6831
6832               <variablelist>
6833                 <varlistentry>
6834                   <term><structfield>minClock</structfield></term>
6835                   <term><structfield>maxClock</structfield></term>
6836                   <listitem><para>
6837                 The lower and upper mode clock bounds for which the rest
6838                 of the <structname>clockRange</structname> parameters apply.
6839                 Since these are the mode clocks, they are not scaled
6840                 with the <structfield>ClockMulFactor</structfield> and
6841                 <structfield>ClockDivFactor</structfield>.  It is up to the driver
6842                 to adjust these values if they depend on the clock
6843                 scaling factors.
6844                     </para></listitem></varlistentry>
6845
6846                 <varlistentry>
6847                   <term><structfield>clockIndex</structfield></term>
6848                   <listitem><para>
6849                 (not used yet) <constant>-1</constant> for programmable clocks
6850                     </para></listitem></varlistentry>
6851
6852                 <varlistentry>
6853                   <term><structfield>interlaceAllowed</structfield></term>
6854                   <listitem><para>
6855                 <constant>TRUE</constant> if interlacing is allowed for this
6856                 range
6857                     </para></listitem></varlistentry>
6858
6859                 <varlistentry>
6860                   <term><structfield>doubleScanAllowed</structfield></term>
6861                   <listitem><para>
6862                 <constant>TRUE</constant> if doublescan or multiscan is allowed
6863                 for this range
6864                     </para></listitem></varlistentry>
6865
6866                 <varlistentry>
6867                   <term><structfield>ClockMulFactor</structfield></term>
6868                   <term><structfield>ClockDivFactor</structfield></term>
6869                   <listitem><para>
6870                 Scaling factors that are applied to the mode clocks ONLY
6871                 before selecting a clock index (when there is no
6872                 programmable clock) or a <structfield>SynthClock</structfield>
6873                 value.  This is useful for drivers that support pixel
6874                 multiplexing or that need to scale the clocks because
6875                 of hardware restrictions (like sending 24bpp data to an
6876                 8 bit RAMDAC using a tripled clock).
6877                     </para>
6878
6879                     <para>
6880                 Note that these parameters describe what must be done
6881                 to the mode clock to achieve the data transport clock
6882                 between graphics controller and RAMDAC.  For example
6883                 for <literal remap="tt">2:1</literal> pixel multiplexing, two pixels
6884                 are sent to the RAMDAC on each clock.  This allows the
6885                 RAMDAC clock to be half of the actual pixel clock.
6886                 Hence, <code>ClockMulFactor=1</code> and
6887                 <code>ClockDivFactor=2</code>.  This means that the
6888                 clock used for clock selection (ie, determining the
6889                 correct clock index from the list of discrete clocks)
6890                 or for the <structfield>SynthClock</structfield> field in case of
6891                 a programmable clock is:  (<code>mode-&gt;Clock *
6892                 ClockMulFactor) / ClockDivFactor</code>.
6893                     </para></listitem></varlistentry>
6894
6895                 <varlistentry>
6896                   <term><structfield>PrivFlags</structfield></term>
6897                   <listitem><para>
6898                 This field is copied into the
6899                 <literal remap="tt">mode-&gt;PrivFlags</literal> field when this
6900                 <literal remap="tt">clockRange</literal> is selected by
6901                 <function>xf86ValidateModes()</function>.  It allows the
6902                 driver to find out what clock range was selected, so it
6903                 knows it needs to set up pixel multiplexing or any other
6904                 range-dependent feature.  This field is purely
6905                 driver-defined: it may contain flag bits, an index or
6906                 anything else (as long as it is an <literal remap="tt">INT</literal>).
6907                     </para></listitem></varlistentry>
6908               </variablelist>
6909             </para>
6910
6911             <para>
6912       Note that the <structfield>mode-&gt;SynthClock</structfield> field is always
6913       filled in by <function>xf86ValidateModes()</function>: it will contain
6914       the <quote>data transport clock</quote>, which is the clock that will have
6915       to be programmed in the chip when it has a programmable clock, or
6916       the clock that will be picked from the clocks list when it is not
6917       a programmable one.  Thus:
6918
6919               <programlisting>
6920     mode-&gt;SynthClock = (mode-&gt;Clock * ClockMulFactor) / ClockDivFactor
6921               </programlisting>
6922             </para>
6923
6924           </blockquote></para></blockquote>
6925
6926       <blockquote><para>
6927           <programlisting>
6928     void xf86PruneDriverModes(ScrnInfoPtr scrp);
6929           </programlisting>
6930           <blockquote><para>
6931       This function deletes modes in the modes field of the
6932       <structname>ScrnInfoRec</structname> that have been marked as invalid.
6933       This is normally run after having run
6934       <function>xf86ValidateModes()</function> for the last time.  For each
6935       mode that is deleted, a warning message is printed out indicating
6936       the reason for it being deleted.
6937             </para>
6938
6939           </blockquote></para></blockquote>
6940
6941       <blockquote><para>
6942           <programlisting>
6943     void xf86SetCrtcForModes(ScrnInfoPtr scrp, int adjustFlags);
6944           </programlisting>
6945           <blockquote><para>
6946       This function fills in the <structname>Crtc*</structname> fields for all
6947       the modes in the <structfield>modes</structfield> field of the
6948       <structname>ScrnInfoRec</structname>.  The <parameter>adjustFlags</parameter>
6949       parameter determines how the vertical CRTC values are scaled for
6950       interlaced modes.  They are halved if it is
6951       <constant>INTERLACE_HALVE_V</constant>.  The vertical CRTC values are
6952       doubled for doublescan modes, and are further multiplied by the
6953       <literal remap="tt">VScan</literal> value.
6954             </para>
6955
6956             <para>
6957       This function is normally called after calling
6958       <function>xf86PruneDriverModes()</function>.
6959             </para>
6960
6961           </blockquote></para></blockquote>
6962
6963       <blockquote><para>
6964           <programlisting>
6965     void xf86PrintModes(ScrnInfoPtr scrp);
6966           </programlisting>
6967           <blockquote><para>
6968       This function prints out the virtual size setting, and the line
6969       pitch being used.  It also prints out two lines for each mode being
6970       used.  The first line includes the mode's pixel clock, horizontal sync
6971       rate, refresh rate, and whether it is interlaced, doublescanned and/or
6972       multi-scanned.  The second line is the mode's Modeline.
6973             </para>
6974
6975             <para>
6976       This function is normally called after calling
6977       <function>xf86SetCrtcForModes()</function>.
6978             </para>
6979
6980           </blockquote></para></blockquote>
6981
6982     </sect2>
6983
6984     <sect2>
6985       <title>Secondary Mode functions</title>
6986
6987       <para>
6988 The secondary mode helper functions are functions which are normally
6989 used by the primary mode helper functions, and which are not normally
6990 called directly by a driver.  If a driver has unusual requirements
6991 and needs to do its own mode validation, it might be able to make
6992 use of some of these secondary mode helper functions.
6993       </para>
6994
6995       <blockquote><para>
6996           <programlisting>
6997     int xf86GetNearestClock(ScrnInfoPtr scrp, int freq, Bool allowDiv2,
6998                             int *divider);
6999           </programlisting>
7000           <blockquote><para>
7001       This function returns the index of the closest clock to the
7002       frequency <parameter>freq</parameter> given (in kHz).  It assumes that
7003       the number of clocks is greater than zero.  It requires that the
7004       <structfield>numClocks</structfield> and <structfield>clock</structfield> fields of the
7005       <structname>ScrnInfoRec</structname> are initialised.  The
7006       <structfield>allowDiv2</structfield> field determines if the clocks can be
7007       halved.  The <parameter>*divider</parameter> return value indicates
7008       whether clock division is used when determining the clock returned.
7009             </para>
7010
7011             <para>
7012       This function is only for non-programmable clocks.
7013             </para>
7014
7015           </blockquote></para></blockquote>
7016
7017       <blockquote><para>
7018           <programlisting>
7019     const char *xf86ModeStatusToString(ModeStatus status);
7020           </programlisting>
7021           <blockquote><para>
7022       This function converts the <parameter>status</parameter> value to a
7023       descriptive printable string.
7024             </para>
7025
7026           </blockquote></para></blockquote>
7027
7028       <blockquote><para>
7029           <programlisting>
7030     ModeStatus xf86LookupMode(ScrnInfoPtr scrp, DisplayModePtr modep,
7031                      ClockRangePtr clockRanges, LookupModeFlags strategy);
7032           </programlisting>
7033           <blockquote><para>
7034       This function takes a pointer to a mode with the name filled in,
7035       and looks for a mode in the <structfield>modePool</structfield> list which
7036       matches.  The parameters of the matching mode are filled in to
7037       <parameter>*modep</parameter>.  The <parameter>clockRanges</parameter> and
7038       <parameter>strategy</parameter> parameters are as for the
7039       <function>xf86ValidateModes()</function> function above.
7040             </para>
7041
7042             <para>
7043       This function requires the <structfield>modePool</structfield>,
7044       <structfield>clock[]</structfield>, <structfield>numClocks</structfield> and
7045       <structfield>progClock</structfield> fields of the <structname>ScrnInfoRec</structname>
7046       to be initialised before being called.
7047             </para>
7048
7049             <para>
7050       The return value is <constant>MODE_OK</constant> if a mode was found.
7051       Otherwise it indicates why a matching mode could not be found.
7052             </para>
7053
7054           </blockquote></para></blockquote>
7055
7056       <blockquote><para>
7057           <programlisting>
7058     ModeStatus xf86InitialCheckModeForDriver(ScrnInfoPtr scrp,
7059                                 DisplayModePtr mode, ClockRangePtr clockRanges,
7060                                 LookupModeFlags strategy, int maxPitch,
7061                                 int virtualX, int virtualY);
7062           </programlisting>
7063           <blockquote><para>
7064       This function checks the passed mode against some basic driver
7065       constraints.  Apart from the ones passed explicitly, the
7066       <structfield>maxHValue</structfield> and <structfield>maxVValue</structfield> fields of
7067       the <structname>ScrnInfoRec</structname> are also used.  If the
7068       <structfield>ValidMode</structfield> field of the <structname>ScrnInfoRec</structname>
7069       is set, that function is also called to check the mode.  Next, the
7070       mode is checked against the monitor's constraints.
7071             </para>
7072
7073             <para>
7074       If the mode is consistent with all constraints, the return value
7075       is <constant>MODE_OK</constant>.  Otherwise the return value indicates
7076       which constraint wasn't met.
7077             </para>
7078
7079           </blockquote></para></blockquote>
7080
7081       <blockquote><para>
7082           <programlisting>
7083     void xf86DeleteMode(DisplayModePtr *modeList, DisplayModePtr mode);
7084           </programlisting>
7085           <blockquote><para>
7086       This function deletes the <parameter>mode</parameter> given from the
7087       <parameter>modeList</parameter>.  It never prints any messages, so it is
7088       up to the caller to print a message if required.
7089             </para>
7090
7091           </blockquote></para></blockquote>
7092     </sect2>
7093
7094     <sect2>
7095       <title>Functions for handling strings and tokens</title>
7096
7097       <para>
7098     Tables associating strings and numerical tokens combined with the
7099     following functions provide a compact way of handling strings from
7100     the config file, and for converting tokens into printable strings.
7101     The table data structure is:
7102
7103         <programlisting>
7104 typedef struct {
7105     int                 token;
7106     const char *        name;
7107 } SymTabRec, *SymTabPtr;
7108         </programlisting>
7109       </para>
7110
7111       <para>
7112     A table is an initialised array of <structname>SymTabRec</structname>.  The
7113     tokens must be non-negative integers.  Multiple names may be mapped
7114     to a single token.  The table is terminated with an element with a
7115     <structfield>token</structfield> value of <constant>-1</constant> and
7116     <constant>NULL</constant> for the <structfield>name</structfield>.
7117       </para>
7118
7119       <blockquote><para>
7120           <programlisting>
7121     const char *xf86TokenToString(SymTabPtr table, int token);
7122           </programlisting>
7123           <blockquote><para>
7124       This function returns the first string in <parameter>table</parameter>
7125       that matches <parameter>token</parameter>.  If no match is found,
7126       <constant>NULL</constant> is returned (NOTE, older versions of this
7127       function would return the string "unknown" when no match is found).
7128             </para>
7129
7130           </blockquote></para></blockquote>
7131
7132       <blockquote><para>
7133           <programlisting>
7134     int xf86StringToToken(SymTabPtr table, const char *string);
7135           </programlisting>
7136           <blockquote><para>
7137       This function returns the first token in <parameter>table</parameter>
7138       that matches <parameter>string</parameter>.  The
7139       <function>xf86NameCmp()</function> function is used to determine the
7140       match.  If no match is found, <constant>-1</constant> is returned.
7141             </para>
7142
7143           </blockquote></para></blockquote>
7144
7145     </sect2>
7146
7147     <sect2>
7148       <title>Functions for finding which config file entries to use</title>
7149
7150       <para>
7151     These functions can be used to select the appropriate config file
7152     entries that match the detected hardware.  They are described above
7153     in the <link linkend="probe">Probe</link> and
7154     <link linkend="avail">Available Functions</link> sections.
7155       </para>
7156
7157     </sect2>
7158
7159     <sect2>
7160       <title>Probing discrete clocks on old hardware</title>
7161
7162       <para>
7163     The <function>xf86GetClocks()</function> function may be used to assist
7164     in finding the discrete pixel clock values on older hardware.
7165       </para>
7166
7167       <blockquote><para>
7168           <programlisting>
7169     void xf86GetClocks(ScrnInfoPtr pScrn, int num,
7170                        Bool (*ClockFunc)(ScrnInfoPtr, int),
7171                        void (*ProtectRegs)(ScrnInfoPtr, Bool),
7172                        void (*BlankScreen)(ScrnInfoPtr, Bool),
7173                        int vertsyncreg, int maskval, int knownclkindex,
7174                        int knownclkvalue);
7175           </programlisting>
7176           <blockquote><para>
7177       This function uses a comparative sampling method to measure the
7178       discrete pixel clock values.  The number of discrete clocks to
7179       measure is given by <parameter>num</parameter>.  <parameter>clockFunc</parameter>
7180       is a function that selects the <parameter>n</parameter>'th clock.  It
7181       should also save or restore any state affected by programming the
7182       clocks when the index passed is <constant>CLK_REG_SAVE</constant> or
7183       <constant>CLK_REG_RESTORE</constant>.  <parameter>ProtectRegs</parameter> is
7184       a function that does whatever is required to protect the hardware
7185       state while selecting a new clock.  <parameter>BlankScreen</parameter>
7186       is a function that blanks the screen.  <parameter>vertsyncreg</parameter>
7187       and <parameter>maskval</parameter> are the register and bitmask to
7188       check for the presence of vertical sync pulses.
7189       <parameter>knownclkindex</parameter> and <parameter>knownclkvalue</parameter>
7190       are the index and value of a known clock.  These are the known
7191       references on which the comparative measurements are based.  The
7192       number of clocks probed is set in <structfield>pScrn-&gt;numClocks</structfield>,
7193       and the probed clocks are set in the <structfield>pScrn-&gt;clock[]</structfield>
7194       array.  All of the clock values are in units of kHz.
7195             </para>
7196
7197           </blockquote></para></blockquote>
7198
7199       <blockquote><para>
7200           <programlisting>
7201     void xf86ShowClocks(ScrnInfoPtr scrp, MessageType from);
7202           </programlisting>
7203           <blockquote><para>
7204       Print out the pixel clocks <parameter>scrp-&gt;clock[]</parameter>.
7205       <parameter>from</parameter> indicates whether the clocks were probed
7206       or from the config file.
7207             </para>
7208
7209           </blockquote></para></blockquote>
7210     </sect2>
7211
7212     <sect2>
7213       <title>Other helper functions</title>
7214
7215       <blockquote><para>
7216           <programlisting>
7217     Bool xf86IsUnblank(int mode);
7218           </programlisting>
7219           <blockquote><para>
7220       Returns <constant>TRUE</constant> when the screen saver mode specified
7221       by <parameter>mode</parameter> requires the screen be unblanked,
7222       and <constant>FALSE</constant> otherwise.  The screen saver modes that
7223       require blanking are <constant>SCREEN_SAVER_ON</constant> and
7224       <constant>SCREEN_SAVER_CYCLE</constant>, and the screen saver modes that
7225       require unblanking are <constant>SCREEN_SAVER_OFF</constant> and
7226       <constant>SCREEN_SAVER_FORCER</constant>.  Drivers may call this helper
7227       from their <function>SaveScreen()</function> function to interpret the
7228       screen saver modes.
7229             </para>
7230
7231           </blockquote></para></blockquote>
7232     </sect2>
7233   </sect1>
7234
7235   <sect1>
7236     <title>The vgahw module</title>
7237
7238     <para>
7239 The vgahw modules provides an interface for saving, restoring and
7240 programming the standard VGA registers, and for handling VGA colourmaps.
7241     </para>
7242
7243     <sect2>
7244       <title>Data Structures</title>
7245
7246       <para>
7247     The public data structures used by the vgahw module are
7248     <structname>vgaRegRec</structname> and <structname>vgaHWRec</structname>.  They are
7249     defined in <filename>vgaHW.h.</filename>
7250       </para>
7251
7252     </sect2>
7253
7254     <sect2>
7255       <title>General vgahw Functions</title>
7256
7257       <blockquote><para>
7258           <programlisting>
7259     Bool vgaHWGetHWRec(ScrnInfoPtr pScrn);
7260           </programlisting>
7261           <blockquote><para>
7262       This function allocates a <structname>vgaHWRec</structname> structure, and
7263       hooks it into the <structname>ScrnInfoRec</structname>'s
7264       <structfield>privates</structfield>.  Like all information hooked into the
7265       <structfield>privates</structfield>, it is persistent, and only needs to be
7266       allocated once per screen.  This function should normally be called
7267       from the driver's <function>ChipPreInit()</function> function.  The
7268       <structname>vgaHWRec</structname> is zero-allocated, and the following
7269       fields are explicitly initialised:
7270
7271               <variablelist>
7272                 <varlistentry>
7273                   <term><structfield>ModeReg.DAC[]</structfield></term>
7274                   <listitem><para>initialised with a default colourmap
7275                     </para></listitem></varlistentry>
7276                 <varlistentry>
7277                   <term><structfield>ModeReg.Attribute[0x11]</structfield></term>
7278                   <listitem><para>initialised with the default overscan index
7279                     </para></listitem></varlistentry>
7280                 <varlistentry>
7281                   <term><structfield>ShowOverscan</structfield></term>
7282                   <listitem><para>initialised according to the "ShowOverscan" option
7283                     </para></listitem></varlistentry>
7284                 <varlistentry>
7285                   <term><structfield>paletteEnabled</structfield></term>
7286                   <listitem><para>initialised to FALSE
7287                     </para></listitem></varlistentry>
7288                 <varlistentry>
7289                   <term><structfield>cmapSaved</structfield></term>
7290                   <listitem><para>initialised to FALSE
7291                     </para></listitem></varlistentry>
7292                 <varlistentry>
7293                   <term><structfield>pScrn</structfield></term>
7294                   <listitem><para>initialised to pScrn
7295                     </para></listitem></varlistentry>
7296               </variablelist>
7297             </para>
7298
7299             <para>
7300       In addition to the above, <function>vgaHWSetStdFuncs()</function> is
7301       called to initialise the register access function fields with the
7302       standard VGA set of functions.
7303             </para>
7304
7305             <para>
7306       Once allocated, a pointer to the <structname>vgaHWRec</structname> can be
7307       obtained from the <literal remap="tt">ScrnInfoPtr</literal> with the
7308       <literal remap="tt">VGAHWPTR(pScrn)</literal> macro.
7309             </para>
7310
7311           </blockquote></para></blockquote>
7312
7313       <blockquote><para>
7314           <programlisting>
7315     void vgaHWFreeHWRec(ScrnInfoPtr pScrn);
7316           </programlisting>
7317           <blockquote><para>
7318       This function frees a <structname>vgaHWRec</structname> structure.  It
7319       should be called from a driver's <function>ChipFreeScreen()</function>
7320       function.
7321             </para>
7322
7323           </blockquote></para></blockquote>
7324
7325       <blockquote><para>
7326           <programlisting>
7327     Bool vgaHWSetRegCounts(ScrnInfoPtr pScrn, int numCRTC,
7328                           int numSequencer, int numGraphics, int numAttribute);
7329           </programlisting>
7330           <blockquote><para>
7331       This function allows the number of CRTC, Sequencer, Graphics and
7332       Attribute registers to be changed.  This makes it possible for
7333       extended registers to be saved and restored with
7334       <function>vgaHWSave()</function> and <function>vgaHWRestore()</function>.
7335       This function should be called after a <structname>vgaHWRec</structname>
7336       has been allocated with <function>vgaHWGetHWRec()</function>.  The
7337       default values are defined in <filename>vgaHW.h</filename> as follows:
7338
7339               <programlisting>
7340 #define VGA_NUM_CRTC 25
7341 #define VGA_NUM_SEQ   5
7342 #define VGA_NUM_GFX   9
7343 #define VGA_NUM_ATTR 21
7344               </programlisting>
7345             </para>
7346
7347           </blockquote></para></blockquote>
7348
7349       <blockquote><para>
7350           <programlisting>
7351     Bool vgaHWCopyReg(vgaRegPtr dst, vgaRegPtr src);
7352           </programlisting>
7353           <blockquote><para>
7354       This function copies the contents of the VGA saved registers in
7355       <parameter>src</parameter> to <parameter>dst</parameter>.  Note that it isn't
7356       possible to simply do this with <function>memcpy()</function> (or
7357       similar).  This function returns <constant>TRUE</constant> unless there
7358       is a problem allocating space for the <structfield>CRTC</structfield> and
7359       related fields in <parameter>dst</parameter>.
7360             </para>
7361
7362           </blockquote></para></blockquote>
7363
7364       <blockquote><para>
7365           <programlisting>
7366     void vgaHWSetStdFuncs(vgaHWPtr hwp);
7367           </programlisting>
7368           <blockquote><para>
7369       This function initialises the register access function fields of
7370       <parameter>hwp</parameter> with the standard VGA set of functions.  This
7371       is called by <function>vgaHWGetHWRec()</function>, so there is usually
7372       no need to call this explicitly.  The register access functions
7373       are described below.  If the registers are shadowed in some other
7374       port I/O space (for example a PCI I/O region), these functions
7375       can be used to access the shadowed registers if
7376       <structfield>hwp-&gt;PIOOffset</structfield> is initialised with
7377       <literal remap="tt">offset</literal>, calculated in such a way that when the
7378       standard VGA I/O port value is added to it the correct offset into
7379       the PIO area results.  This value is initialised to zero in
7380       <function>vgaHWGetHWRec()</function>.  (Note: the PIOOffset functionality
7381       is present in XFree86 4.1.0 and later.)
7382             </para>
7383
7384           </blockquote></para></blockquote>
7385
7386       <blockquote><para>
7387           <programlisting>
7388     void vgaHWSetMmioFuncs(vgaHWPtr hwp, CARD8 *base, int offset);
7389           </programlisting>
7390           <blockquote><para>
7391       This function initialised the register access function fields of
7392       hwp with a generic MMIO set of functions.
7393       <structfield>hwp-&gt;MMIOBase</structfield> is initialised with
7394       <parameter>base</parameter>, which must be the virtual address that the
7395       start of MMIO area is mapped to.  <structfield>hwp-&gt;MMIOOffset</structfield>
7396       is initialised with <parameter>offset</parameter>, which must be calculated
7397       in such a way that when the standard VGA I/O port value is added
7398       to it the correct offset into the MMIO area results.  That means
7399       that these functions are only suitable when the VGA I/O ports are
7400       made available in a direct mapping to the MMIO space.  If that is
7401       not the case, the driver will need to provide its own register
7402       access functions.  The register access functions are described
7403       below.
7404             </para>
7405
7406           </blockquote></para></blockquote>
7407
7408       <blockquote><para>
7409           <programlisting>
7410     Bool vgaHWMapMem(ScrnInfoPtr pScrn);
7411           </programlisting>
7412           <blockquote><para>
7413       This function maps the VGA memory window.  It requires that the
7414       <structname>vgaHWRec</structname> be allocated.  If a driver requires
7415       non-default <structfield>MapPhys</structfield> or <structfield>MapSize</structfield>
7416       settings (the physical location and size of the VGA memory window)
7417       then those fields of the <structname>vgaHWRec</structname> must be initialised
7418       before calling this function.  Otherwise, this function initialiases
7419       the default values of <constant>0xA0000</constant> for
7420       <structfield>MapPhys</structfield> and <code>(64&nbsp;*&nbsp;1024)</code> for
7421       <structfield>MapSize</structfield>.  This function must be called before
7422       attempting to save or restore the VGA state.  If the driver doesn't
7423       call it explicitly, the <function>vgaHWSave()</function> and
7424       <function>vgaHWRestore()</function> functions may call it if they need
7425       to access the VGA memory (in which case they will also call
7426       <function>vgaHWUnmapMem()</function> to unmap the VGA memory before
7427       exiting).
7428             </para>
7429
7430           </blockquote></para></blockquote>
7431
7432       <blockquote><para>
7433           <programlisting>
7434     void vgaHWUnmapMem(ScrnInfoPtr pScrn);
7435           </programlisting>
7436           <blockquote><para>
7437       This function unmaps the VGA memory window.  It must only be called
7438       after the memory has been mapped.  The <structfield>Base</structfield> field
7439       of the <structname>vgaHWRec</structname> field is set to <constant>NULL</constant>
7440       to indicate that the memory is no longer mapped.
7441             </para>
7442
7443           </blockquote></para></blockquote>
7444
7445       <blockquote><para>
7446           <programlisting>
7447     void vgaHWGetIOBase(vgaHWPtr hwp);
7448           </programlisting>
7449           <blockquote><para>
7450       This function initialises the <structfield>IOBase</structfield> field of the
7451       <structname>vgaHWRec</structname>.  This function must be called before
7452       using any other functions that access the video hardware.
7453             </para>
7454
7455             <para>
7456       A macro <function>VGAHW_GET_IOBASE()</function> is also available in
7457       <filename>vgaHW.h</filename> that returns the I/O base, and this may
7458       be used when the vgahw module is not loaded (for example, in the
7459       <function>ChipProbe()</function> function).
7460             </para>
7461
7462           </blockquote></para></blockquote>
7463
7464       <blockquote><para>
7465           <programlisting>
7466     void vgaHWUnlock(vgaHWPtr hwp);
7467           </programlisting>
7468           <blockquote><para>
7469       This function unlocks the VGA <literal remap="tt">CRTC[0-7]</literal> registers,
7470       and must be called before attempting to write to those registers.
7471             </para>
7472
7473           </blockquote></para></blockquote>
7474
7475       <blockquote><para>
7476           <programlisting>
7477     void vgaHWLock(vgaHWPtr hwp);
7478           </programlisting>
7479           <blockquote><para>
7480       This function locks the VGA <literal remap="tt">CRTC[0-7]</literal> registers.
7481             </para>
7482
7483           </blockquote></para></blockquote>
7484
7485       <blockquote><para>
7486           <programlisting>
7487     void vgaHWEnable(vgaHWPtr hwp);
7488           </programlisting>
7489           <blockquote><para>
7490       This function enables the VGA subsystem.  (Note, this function is
7491       present in XFree86 4.1.0 and later.).
7492             </para>
7493
7494           </blockquote></para></blockquote>
7495
7496       <blockquote><para>
7497           <programlisting>
7498     void vgaHWDisable(vgaHWPtr hwp);
7499           </programlisting>
7500           <blockquote><para>
7501       This function disables the VGA subsystem.  (Note, this function is
7502       present in XFree86 4.1.0 and later.).
7503             </para>
7504
7505           </blockquote></para></blockquote>
7506
7507       <blockquote><para>
7508           <programlisting>
7509     void vgaHWSave(ScrnInfoPtr pScrn, vgaRegPtr save, int flags);
7510           </programlisting>
7511           <blockquote><para>
7512       This function saves the VGA state.  The state is written to the
7513       <structname>vgaRegRec</structname> pointed to by <parameter>save</parameter>.
7514       <parameter>flags</parameter> is set to one or more of the following flags
7515       ORed together:
7516
7517               <variablelist>
7518                 <varlistentry>
7519                   <term><constant>VGA_SR_MODE</constant></term>
7520                   <listitem><para>the mode setting registers are saved
7521                     </para></listitem></varlistentry>
7522                 <varlistentry>
7523                   <term><constant>VGA_SR_FONTS</constant></term>
7524                   <listitem><para>the text mode font/text data is saved
7525                     </para></listitem></varlistentry>
7526                 <varlistentry>
7527                   <term><constant>VGA_SR_CMAP</constant></term>
7528                   <listitem><para>the colourmap (LUT) is saved
7529                     </para></listitem></varlistentry>
7530                 <varlistentry>
7531                   <term><constant>VGA_SR_ALL</constant></term>
7532                   <listitem><para>all of the above are saved
7533                     </para></listitem></varlistentry>
7534               </variablelist>
7535             </para>
7536
7537             <para>
7538       The <structname>vgaHWRec</structname> and its <structfield>IOBase</structfield> fields
7539       must be initialised before this function is called.  If
7540       <constant>VGA_SR_FONTS</constant> is set in <parameter>flags</parameter>, the
7541       VGA memory window must be mapped.  If it isn't then
7542       <function>vgaHWMapMem()</function> will be called to map it, and
7543       <function>vgaHWUnmapMem()</function> will be called to unmap it
7544       afterwards.  <function>vgaHWSave()</function> uses the three functions
7545       below in the order <function>vgaHWSaveColormap()</function>,
7546       <function>vgaHWSaveMode()</function>, <function>vgaHWSaveFonts()</function> to
7547       carry out the different save phases.  It is undecided at this
7548       stage whether they will remain part of the vgahw module's public
7549       interface or not.
7550             </para>
7551
7552           </blockquote></para></blockquote>
7553
7554       <blockquote><para>
7555           <programlisting>
7556     void vgaHWSaveMode(ScrnInfoPtr pScrn, vgaRegPtr save);
7557           </programlisting>
7558           <blockquote><para>
7559       This function saves the VGA mode registers.  They are saved to
7560       the <structname>vgaRegRec</structname> pointed to by <parameter>save</parameter>.
7561       The registers saved are:
7562
7563               <literallayout>
7564         MiscOut
7565         CRTC[0-0x18]
7566         Attribute[0-0x14]
7567         Graphics[0-8]
7568         Sequencer[0-4]
7569               </literallayout>
7570             </para>
7571
7572             <para>
7573     The number of registers actually saved may be modified by a prior call
7574     to <function>vgaHWSetRegCounts()</function>.
7575             </para>
7576
7577           </blockquote></para></blockquote>
7578
7579       <blockquote><para>
7580           <programlisting>
7581     void vgaHWSaveFonts(ScrnInfoPtr pScrn, vgaRegPtr save);
7582           </programlisting>
7583           <blockquote><para>
7584       This function saves the text mode font and text data held in the
7585       video memory.  If called while in a graphics mode, no save is
7586       done.  The VGA memory window must be mapped with
7587       <function>vgaHWMapMem()</function> before to calling this function.
7588             </para>
7589
7590             <para>
7591       On some platforms, one or more of the font/text plane saves may be
7592       no-ops.  This is the case when the platform's VC driver already
7593       takes care of this.
7594             </para>
7595
7596           </blockquote></para></blockquote>
7597
7598       <blockquote><para>
7599           <programlisting>
7600     void vgaHWSaveColormap(ScrnInfoPtr pScrn, vgaRegPtr save);
7601           </programlisting>
7602           <blockquote><para>
7603       This function saves the VGA colourmap (LUT).  Before saving it, it
7604       attempts to verify that the colourmap is readable.  In rare cases
7605       where it isn't readable, a default colourmap is saved instead.
7606             </para>
7607
7608           </blockquote></para></blockquote>
7609
7610       <blockquote><para>
7611           <programlisting>
7612     void vgaHWRestore(ScrnInfoPtr pScrn, vgaRegPtr restore, int flags);
7613           </programlisting>
7614           <blockquote><para>
7615       This function programs the VGA state.  The state programmed is
7616       that contained in the <structname>vgaRegRec</structname> pointed to by
7617       <parameter>restore</parameter>.  <parameter>flags</parameter> is the same
7618       as described above for the <function>vgaHWSave()</function> function.
7619             </para>
7620
7621             <para>
7622       The <structname>vgaHWRec</structname> and its <structfield>IOBase</structfield> fields
7623       must be initialised before this function is called.  If
7624       <constant>VGA_SR_FONTS</constant> is set in <parameter>flags</parameter>, the
7625       VGA memory window must be mapped.  If it isn't then
7626       <function>vgaHWMapMem()</function> will be called to map it, and
7627       <function>vgaHWUnmapMem()</function> will be called to unmap it
7628       afterwards.  <function>vgaHWRestore()</function> uses the three functions
7629       below in the order <function>vgaHWRestoreFonts()</function>,
7630       <function>vgaHWRestoreMode()</function>,
7631       <function>vgaHWRestoreColormap()</function> to carry out the different
7632       restore phases.  It is undecided at this stage whether they will
7633       remain part of the vgahw module's public interface or not.
7634             </para>
7635
7636           </blockquote></para></blockquote>
7637
7638       <blockquote><para>
7639           <programlisting>
7640     void vgaHWRestoreMode(ScrnInfoPtr pScrn, vgaRegPtr restore);
7641           </programlisting>
7642           <blockquote><para>
7643       This function restores the VGA mode registers.  They are restored
7644       from the data in the <structname>vgaRegRec</structname> pointed to by
7645       <parameter>restore</parameter>.  The registers restored are:
7646
7647               <literallayout>
7648         MiscOut
7649         CRTC[0-0x18]
7650         Attribute[0-0x14]
7651         Graphics[0-8]
7652         Sequencer[0-4]
7653               </literallayout>
7654             </para>
7655
7656             <para>
7657     The number of registers actually restored may be modified by a prior call
7658     to <function>vgaHWSetRegCounts()</function>.
7659             </para>
7660
7661           </blockquote></para></blockquote>
7662
7663       <blockquote><para>
7664           <programlisting>
7665     void vgaHWRestoreFonts(ScrnInfoPtr pScrn, vgaRegPtr restore);
7666           </programlisting>
7667           <blockquote><para>
7668       This function restores the text mode font and text data to the
7669       video memory.  The VGA memory window must be mapped with
7670       <function>vgaHWMapMem()</function> before to calling this function.
7671             </para>
7672
7673             <para>
7674       On some platforms, one or more of the font/text plane restores
7675       may be no-ops.  This is the case when the platform's VC driver
7676       already takes care of this.
7677             </para>
7678
7679           </blockquote></para></blockquote>
7680
7681       <blockquote><para>
7682           <programlisting>
7683     void vgaHWRestoreColormap(ScrnInfoPtr pScrn, vgaRegPtr restore);
7684           </programlisting>
7685           <blockquote><para>
7686       This function restores the VGA colourmap (LUT).
7687             </para>
7688
7689           </blockquote></para></blockquote>
7690
7691       <blockquote><para>
7692           <programlisting>
7693     void vgaHWInit(ScrnInfoPtr pScrn, DisplayModePtr mode);
7694           </programlisting>
7695           <blockquote><para>
7696       This function fills in the <structname>vgaHWRec</structname>'s
7697       <structfield>ModeReg</structfield> field with the values appropriate for
7698       programming the given video mode.  It requires that the
7699       <structname>ScrnInfoRec</structname>'s <structfield>depth</structfield> field is
7700       initialised, which determines how the registers are programmed.
7701             </para>
7702
7703           </blockquote></para></blockquote>
7704
7705       <blockquote><para>
7706           <programlisting>
7707     void vgaHWSeqReset(vgaHWPtr hwp, Bool start);
7708           </programlisting>
7709           <blockquote><para>
7710       Do a VGA sequencer reset.  If start is <constant>TRUE</constant>, the
7711       reset is started.  If start is <constant>FALSE</constant>, the reset
7712       is ended.
7713             </para>
7714
7715           </blockquote></para></blockquote>
7716
7717       <blockquote><para>
7718           <programlisting>
7719     void vgaHWProtect(ScrnInfoPtr pScrn, Bool on);
7720           </programlisting>
7721           <blockquote><para>
7722       This function protects VGA registers and memory from corruption
7723       during loads.  It is typically called with on set to
7724       <constant>TRUE</constant> before programming, and with on set to
7725       <constant>FALSE</constant> after programming.
7726             </para>
7727
7728           </blockquote></para></blockquote>
7729
7730       <blockquote><para>
7731           <programlisting>
7732     Bool vgaHWSaveScreen(ScreenPtr pScreen, int mode);
7733           </programlisting>
7734           <blockquote><para>
7735       This function blanks and unblanks the screen.  It is blanked when
7736       <parameter>mode</parameter> is <constant>SCREEN_SAVER_ON</constant> or
7737       <constant>SCREEN_SAVER_CYCLE</constant>, and unblanked when
7738       <parameter>mode</parameter> is <constant>SCREEN_SAVER_OFF</constant> or
7739       <constant>SCREEN_SAVER_FORCER</constant>.
7740             </para>
7741
7742           </blockquote></para></blockquote>
7743
7744       <blockquote><para>
7745           <programlisting>
7746     void vgaHWBlankScreen(ScrnInfoPtr pScrn, Bool on);
7747           </programlisting>
7748           <blockquote><para>
7749       This function blanks and unblanks the screen.  It is blanked when
7750       <parameter>on</parameter> is <constant>FALSE</constant>, and unblanked when
7751       <parameter>on</parameter> is <constant>TRUE</constant>.  This function is
7752       provided for use in cases where the <structname>ScrnInfoRec</structname>
7753       can't be derived from the <structname>ScreenRec</structname> (while probing
7754       for clocks, for example).
7755             </para>
7756
7757           </blockquote></para></blockquote>
7758
7759     </sect2>
7760
7761     <sect2>
7762       <title>VGA Colormap Functions</title>
7763
7764       <para>
7765     The vgahw module uses the standard colormap support (see the
7766     <link linkend="cmap">Colormap Handling</link> section.  This is initialised
7767     with the following function:
7768
7769         <blockquote><para>
7770           <programlisting>
7771     Bool vgaHWHandleColormaps(ScreenPtr pScreen);
7772             </programlisting>
7773           </para></blockquote>
7774       </para>
7775
7776     </sect2>
7777
7778     <sect2>
7779       <title>VGA Register Access Functions</title>
7780
7781       <para>
7782     The vgahw module abstracts access to the standard VGA registers by
7783     using a set of functions held in the <structname>vgaHWRec</structname>.  When
7784     the <structname>vgaHWRec</structname> is created these function pointers are
7785     initialised with the set of standard VGA I/O register access functions.
7786     In addition to these, the vgahw module includes a basic set of MMIO
7787     register access functions, and the <structname>vgaHWRec</structname> function
7788     pointers can be initialised to these by calling the
7789     <function>vgaHWSetMmioFuncs()</function> function described above.  Some
7790     drivers/platforms may require a different set of functions for VGA
7791     access.  The access functions are described here.
7792       </para>
7793
7794
7795       <blockquote><para>
7796           <programlisting>
7797     void writeCrtc(vgaHWPtr hwp, CARD8 index, CARD8 value);
7798           </programlisting>
7799           <blockquote><para>
7800       Write <parameter>value</parameter> to CRTC register <parameter>index</parameter>.
7801             </para>
7802
7803           </blockquote></para></blockquote>
7804
7805       <blockquote><para>
7806           <programlisting>
7807     CARD8 readCrtc(vgaHWPtr hwp, CARD8 index);
7808           </programlisting>
7809           <blockquote><para>
7810       Return the value read from CRTC register <parameter>index</parameter>.
7811             </para>
7812
7813           </blockquote></para></blockquote>
7814
7815       <blockquote><para>
7816           <programlisting>
7817     void writeGr(vgaHWPtr hwp, CARD8 index, CARD8 value);
7818           </programlisting>
7819           <blockquote><para>
7820       Write <parameter>value</parameter> to Graphics Controller register
7821       <parameter>index</parameter>.
7822             </para>
7823
7824           </blockquote></para></blockquote>
7825
7826       <blockquote><para>
7827           <programlisting>
7828     CARD8 readGR(vgaHWPtr hwp, CARD8 index);
7829           </programlisting>
7830           <blockquote><para>
7831       Return the value read from Graphics Controller register
7832       <parameter>index</parameter>.
7833             </para>
7834
7835           </blockquote></para></blockquote>
7836
7837       <blockquote><para>
7838           <programlisting>
7839     void writeSeq(vgaHWPtr hwp, CARD8 index, CARD8, value);
7840           </programlisting>
7841           <blockquote><para>
7842       Write <parameter>value</parameter> to Sequencer register
7843       <parameter>index</parameter>.
7844             </para>
7845
7846           </blockquote></para></blockquote>
7847
7848       <blockquote><para>
7849           <programlisting>
7850     CARD8 readSeq(vgaHWPtr hwp, CARD8 index);
7851           </programlisting>
7852           <blockquote><para>
7853       Return the value read from Sequencer register <parameter>index</parameter>.
7854             </para>
7855
7856           </blockquote></para></blockquote>
7857
7858       <blockquote><para>
7859           <programlisting>
7860     void writeAttr(vgaHWPtr hwp, CARD8 index, CARD8, value);
7861           </programlisting>
7862           <blockquote><para>
7863       Write <parameter>value</parameter> to Attribute Controller register
7864       <parameter>index</parameter>.  When writing out the index value this
7865       function should set bit 5 (<constant>0x20</constant>) according to the
7866       setting of <structfield>hwp-&gt;paletteEnabled</structfield> in order to
7867       preserve the palette access state.  It should be cleared when
7868       <structfield>hwp-&gt;paletteEnabled</structfield> is <constant>TRUE</constant>
7869       and set when it is <constant>FALSE</constant>.
7870             </para>
7871
7872           </blockquote></para></blockquote>
7873
7874       <blockquote><para>
7875           <programlisting>
7876     CARD8 readAttr(vgaHWPtr hwp, CARD8 index);
7877           </programlisting>
7878           <blockquote><para>
7879       Return the value read from Attribute Controller register
7880       <parameter>index</parameter>.  When writing out the index value this
7881       function should set bit 5 (<constant>0x20</constant>) according to the
7882       setting of <structfield>hwp-&gt;paletteEnabled</structfield> in order to
7883       preserve the palette access state.  It should be cleared when
7884       <structfield>hwp-&gt;paletteEnabled</structfield> is <constant>TRUE</constant>
7885       and set when it is <constant>FALSE</constant>.
7886             </para>
7887
7888           </blockquote></para></blockquote>
7889
7890       <blockquote><para>
7891           <programlisting>
7892     void writeMiscOut(vgaHWPtr hwp, CARD8 value);
7893           </programlisting>
7894           <blockquote><para>
7895       Write <quote><parameter>value</parameter></quote> to the Miscellaneous Output register.
7896             </para>
7897
7898           </blockquote></para></blockquote>
7899
7900       <blockquote><para>
7901           <programlisting>
7902     CARD8 readMiscOut(vgwHWPtr hwp);
7903           </programlisting>
7904           <blockquote><para>
7905       Return the value read from the Miscellaneous Output register.
7906             </para>
7907
7908           </blockquote></para></blockquote>
7909
7910       <blockquote><para>
7911           <programlisting>
7912     void enablePalette(vgaHWPtr hwp);
7913           </programlisting>
7914           <blockquote><para>
7915       Clear the palette address source bit in the Attribute Controller
7916       index register and set <literal remap="tt">hwp-&gt;paletteEnabled</literal> to
7917       <constant>TRUE</constant>.
7918             </para>
7919
7920           </blockquote></para></blockquote>
7921
7922       <blockquote><para>
7923           <programlisting>
7924     void disablePalette(vgaHWPtr hwp);
7925           </programlisting>
7926           <blockquote><para>
7927       Set the palette address source bit in the Attribute Controller
7928       index register and set <literal remap="tt">hwp-&gt;paletteEnabled</literal> to
7929       <constant>FALSE</constant>.
7930             </para>
7931
7932           </blockquote></para></blockquote>
7933
7934       <blockquote><para>
7935           <programlisting>
7936     void writeDacMask(vgaHWPtr hwp, CARD8 value);
7937           </programlisting>
7938           <blockquote><para>
7939       Write <parameter>value</parameter> to the DAC Mask register.
7940             </para>
7941
7942           </blockquote></para></blockquote>
7943
7944       <blockquote><para>
7945           <programlisting>
7946     CARD8 readDacMask(vgaHWptr hwp);
7947           </programlisting>
7948           <blockquote><para>
7949       Return the value read from the DAC Mask register.
7950             </para>
7951
7952           </blockquote></para></blockquote>
7953
7954       <blockquote><para>
7955           <programlisting>
7956     void writeDacReadAddress(vgaHWPtr hwp, CARD8 value);
7957           </programlisting>
7958           <blockquote><para>
7959       Write <parameter>value</parameter> to the DAC Read Address register.
7960             </para>
7961
7962           </blockquote></para></blockquote>
7963
7964       <blockquote><para>
7965           <programlisting>
7966     void writeDacWriteAddress(vgaHWPtr hwp, CARD8 value);
7967           </programlisting>
7968           <blockquote><para>
7969       Write <parameter>value</parameter> to the DAC Write Address register.
7970             </para>
7971
7972           </blockquote></para></blockquote>
7973
7974       <blockquote><para>
7975           <programlisting>
7976     void writeDacData(vgaHWPtr hwp, CARD8 value);
7977           </programlisting>
7978           <blockquote><para>
7979       Write <parameter>value</parameter> to the DAC Data register.
7980             </para>
7981
7982           </blockquote></para></blockquote>
7983
7984       <blockquote><para>
7985           <programlisting>
7986     CARD8 readDacData(vgaHWptr hwp);
7987           </programlisting>
7988           <blockquote><para>
7989       Return the value read from the DAC Data register.
7990             </para>
7991
7992           </blockquote></para></blockquote>
7993
7994       <blockquote><para>
7995           <programlisting>
7996     CARD8 readEnable(vgaHWptr hwp);
7997           </programlisting>
7998           <blockquote><para>
7999       Return the value read from the VGA Enable register.  (Note: This
8000       function is present in XFree86 4.1.0 and later.)
8001             </para>
8002
8003           </blockquote></para></blockquote>
8004
8005       <blockquote><para>
8006           <programlisting>
8007     void writeEnable(vgaHWPtr hwp, CARD8 value);
8008           </programlisting>
8009           <blockquote><para>
8010       Write <parameter>value</parameter> to the VGA Enable register.  (Note: This
8011       function is present in XFree86 4.1.0 and later.)
8012             </para>
8013
8014           </blockquote></para></blockquote>
8015     </sect2>
8016   </sect1>
8017
8018   <sect1 id="sample">
8019     <title>Some notes about writing a driver</title>
8020
8021     <note><para>NOTE: some parts of this are not up to date</para></note>
8022
8023     <para>
8024 The following is an outline for writing a basic unaccelerated driver
8025 for a PCI video card with a linear mapped framebuffer, and which has a
8026 VGA core.  It is includes some general information that is relevant to
8027 most drivers (even those which don't fit that basic description).
8028     </para>
8029
8030     <para>
8031 The information here is based on the initial conversion of the Matrox
8032 Millennium driver to the <quote>new design</quote>.  For a fleshing out and sample
8033 implementation of some of the bits outlined here, refer to that driver.
8034 Note that this is an example only.  The approach used here will not be
8035 appropriate for all drivers.
8036     </para>
8037
8038     <para>
8039 Each driver must reserve a unique driver name, and a string that is used
8040 to prefix all of its externally visible symbols.  This is to avoid name
8041 space clashes when loading multiple drivers.  The examples here are for
8042 the <quote>ZZZ</quote> driver, which uses the <quote>ZZZ</quote> or <quote>zzz</quote> prefix for its externally
8043 visible symbols.
8044     </para>
8045
8046     <sect2>
8047       <title>Include files</title>
8048
8049       <para>
8050   All drivers normally include the following headers:
8051         <literallayout><filename>
8052     "xf86.h"
8053     "xf86_OSproc.h"
8054     "xf86_ansic.h"
8055     "xf86Resources.h"
8056           </filename></literallayout>
8057   Wherever inb/outb (and related things) are used the following should be
8058   included:
8059         <literallayout><filename>
8060     "compiler.h"
8061           </filename></literallayout>
8062   Note: in drivers, this must be included after <filename>"xf86_ansic.h"</filename>.
8063       </para>
8064
8065       <para>
8066   Drivers that need to access PCI vendor/device definitions need this:
8067         <literallayout><filename>
8068     "xf86PciInfo.h"
8069           </filename></literallayout>
8070       </para>
8071
8072       <para>
8073   Drivers that need to access the PCI config space need this:
8074         <literallayout><filename>
8075     "xf86Pci.h"
8076           </filename></literallayout>
8077       </para>
8078
8079       <para>
8080   Drivers using the mi banking wrapper need:
8081
8082         <literallayout><filename>
8083     "mibank.h"
8084           </filename></literallayout>
8085       </para>
8086
8087       <para>
8088   Drivers that initialise a SW cursor need this:
8089         <literallayout><filename>
8090     "mipointer.h"
8091           </filename></literallayout>
8092       </para>
8093
8094       <para>
8095   All drivers implementing backing store need this:
8096         <literallayout><filename>
8097     "mibstore.h"
8098           </filename></literallayout>
8099       </para>
8100
8101       <para>
8102   All drivers using the mi colourmap code need this:
8103         <literallayout><filename>
8104     "micmap.h"
8105           </filename></literallayout>
8106       </para>
8107
8108       <para>
8109   If a driver uses the vgahw module, it needs this:
8110         <literallayout><filename>
8111     "vgaHW.h"
8112           </filename></literallayout>
8113       </para>
8114
8115       <para>
8116   Drivers supporting VGA or Hercules monochrome screens need:
8117         <literallayout><filename>
8118     "xf1bpp.h"
8119           </filename></literallayout>
8120       </para>
8121
8122       <para>
8123   Drivers supporting VGA or EGC 16-colour screens need:
8124         <literallayout><filename>
8125     "xf4bpp.h"
8126           </filename></literallayout>
8127       </para>
8128
8129       <para>
8130   Drivers using cfb need:
8131         <programlisting>
8132     #define PSZ 8
8133     #include "cfb.h"
8134     #undef PSZ
8135         </programlisting>
8136       </para>
8137
8138       <para>
8139   Drivers supporting bpp 16, 24 or 32 with cfb need one or more of:
8140         <literallayout><filename>
8141     "cfb16.h"
8142     "cfb24.h"
8143     "cfb32.h"
8144           </filename></literallayout>
8145       </para>
8146
8147       <para>
8148   The driver's own header file:
8149         <literallayout><filename>
8150     "zzz.h"
8151           </filename></literallayout>
8152       </para>
8153
8154       <para>
8155   Drivers must NOT include the following:
8156
8157         <literallayout><filename>
8158     "xf86Priv.h"
8159     "xf86Privstr.h"
8160     "xf86_libc.h"
8161     "xf86_OSlib.h"
8162     "Xos.h"</filename>
8163     any OS header
8164         </literallayout>
8165       </para>
8166
8167     </sect2>
8168
8169     <sect2>
8170       <title>Data structures and initialisation</title>
8171
8172       <itemizedlist>
8173         <listitem>
8174           <para>The following macros should be defined:
8175             <programlisting>
8176 #define VERSION &lt;version-as-an-int&gt;
8177 #define ZZZ_NAME "ZZZ"         /* the name used to prefix messages */
8178 #define ZZZ_DRIVER_NAME "zzz"  /* the driver name as used in config file */
8179 #define ZZZ_MAJOR_VERSION &lt;int&gt;
8180 #define ZZZ_MINOR_VERSION &lt;int&gt;
8181 #define ZZZ_PATCHLEVEL    &lt;int&gt;
8182             </programlisting>
8183           </para>
8184           <para>
8185     NOTE: <constant>ZZZ_DRIVER_NAME</constant> should match the name of the
8186     driver module without things like the "lib" prefix, the "_drv" suffix
8187     or filename extensions.
8188           </para>
8189         </listitem>
8190
8191         <listitem>
8192           <para>
8193     A DriverRec must be defined, which includes the functions required
8194     at the pre-probe phase.  The name of this DriverRec must be an
8195     upper-case version of ZZZ_DRIVER_NAME (for the purposes of static
8196     linking).
8197             <programlisting>
8198 DriverRec ZZZ = {
8199     VERSION,
8200     ZZZ_DRIVER_NAME,
8201     ZZZIdentify,
8202     ZZZProbe,
8203     ZZZAvailableOptions,
8204     NULL,
8205     0
8206 };
8207             </programlisting>
8208           </para>
8209         </listitem>
8210
8211         <listitem>
8212           <para>Define list of supported chips and their matching ID:
8213             <programlisting>
8214 static SymTabRec ZZZChipsets[] = {
8215     { PCI_CHIP_ZZZ1234, "zzz1234a" },
8216     { PCI_CHIP_ZZZ5678, "zzz5678a" },
8217     { -1,               NULL }
8218 };
8219             </programlisting>
8220           </para>
8221           <para>
8222     The token field may be any integer value that the driver may use to
8223     uniquely identify the supported chipsets.  For drivers that support
8224     only PCI devices using the PCI device IDs might be a natural choice,
8225     but this isn't mandatory.  For drivers that support both PCI and other
8226     devices (like ISA), some other ID should probably used.  When other
8227     IDs are used as the tokens it is recommended that the names be
8228     defined as an <type>enum</type> type.
8229           </para>
8230         </listitem>
8231
8232         <listitem>
8233           <para>
8234     If the driver uses the <function>xf86MatchPciInstances()</function>
8235     helper (recommended for drivers that support PCI cards) a list that
8236     maps PCI IDs to chip IDs and fixed resources must be defined:
8237             <programlisting>
8238 static PciChipsets ZZZPciChipsets[] = {
8239     { PCI_CHIP_ZZZ1234, PCI_CHIP_ZZZ1234, RES_SHARED_VGA },
8240     { PCI_CHIP_ZZZ5678, PCI_CHIP_ZZZ5678, RES_SHARED_VGA },
8241     { -1,               -1,               RES_UNDEFINED }
8242 }
8243             </programlisting>
8244           </para>
8245         </listitem>
8246
8247         <listitem>
8248           <para>
8249     Define the <structname>XF86ModuleVersionInfo</structname> struct for the
8250     driver.  This is required for the dynamically loaded version:
8251             <programlisting>
8252 static XF86ModuleVersionInfo zzzVersRec =
8253 {
8254     "zzz",
8255     MODULEVENDORSTRING,
8256     MODINFOSTRING1,
8257     MODINFOSTRING2,
8258     XF86_VERSION_CURRENT,
8259     ZZZ_MAJOR_VERSION, ZZZ_MINOR_VERSION, ZZZ_PATCHLEVEL,
8260     ABI_CLASS_VIDEODRV,
8261     ABI_VIDEODRV_VERSION,
8262     MOD_CLASS_VIDEODRV,
8263     {0,0,0,0}
8264 };
8265             </programlisting>
8266           </para>
8267         </listitem>
8268
8269         <listitem>
8270           <para>
8271     Define a data structure to hold the driver's screen-specific data.
8272     This must be used instead of global variables.  This would be defined
8273     in the <filename>"zzz.h"</filename> file, something like:
8274             <programlisting>
8275 typedef struct {
8276     type1  field1;
8277     type2  field2;
8278     int    fooHack;
8279     Bool   pciRetry;
8280     Bool   noAccel;
8281     Bool   hwCursor;
8282     CloseScreenProcPtr CloseScreen;
8283     OptionInfoPtr Options;
8284     ...
8285 } ZZZRec, *ZZZPtr;
8286             </programlisting>
8287           </para>
8288         </listitem>
8289
8290         <listitem>
8291           <para>
8292     Define the list of config file Options that the driver accepts.  For
8293     consistency between drivers those in the list of <quote>standard</quote> options
8294     should be used where appropriate before inventing new options.
8295
8296             <programlisting>
8297 typedef enum {
8298     OPTION_FOO_HACK,
8299     OPTION_PCI_RETRY,
8300     OPTION_HW_CURSOR,
8301     OPTION_NOACCEL
8302 } ZZZOpts;
8303
8304 static const OptionInfoRec ZZZOptions[] = {
8305   { OPTION_FOO_HACK,  "FooHack",   OPTV_INTEGER, {0}, FALSE },
8306   { OPTION_PCI_RETRY, "PciRetry",  OPTV_BOOLEAN, {0}, FALSE },
8307   { OPTION_HW_CURSOR, "HWcursor",  OPTV_BOOLEAN, {0}, FALSE },
8308   { OPTION_NOACCEL,   "NoAccel",   OPTV_BOOLEAN, {0}, FALSE },
8309   { -1,               NULL,        OPTV_NONE,    {0}, FALSE }
8310 };
8311             </programlisting>
8312           </para>
8313         </listitem>
8314       </itemizedlist>
8315     </sect2>
8316
8317     <sect2>
8318       <title>Functions</title>
8319
8320
8321       <sect3>
8322         <title>SetupProc</title>
8323
8324         <para>
8325     For dynamically loaded modules, a <varname>ModuleData</varname>
8326     variable is required.  It is should be the name of the driver
8327     prepended to "ModuleData".  A <function>Setup()</function> function is
8328     also required, which calls <function>xf86AddDriver()</function> to add
8329     the driver to the main list of drivers.
8330         </para>
8331
8332         <programlisting>
8333 static MODULESETUPPROTO(zzzSetup);
8334
8335 XF86ModuleData zzzModuleData = { &amp;zzzVersRec, zzzSetup, NULL };
8336
8337 static pointer
8338 zzzSetup(pointer module, pointer opts, int *errmaj, int *errmin)
8339 {
8340     static Bool setupDone = FALSE;
8341
8342     /* This module should be loaded only once, but check to be sure. */
8343
8344     if (!setupDone) {
8345         /*
8346          * Modules that this driver always requires may be loaded
8347          * here  by calling LoadSubModule().
8348          */
8349
8350         setupDone = TRUE;
8351         xf86AddDriver(&amp;MGA, module, 0);
8352
8353         /*
8354          * The return value must be non-NULL on success even though
8355          * there is no TearDownProc.
8356          */
8357         return (pointer)1;
8358     } else {
8359         if (errmaj) *errmaj = LDR_ONCEONLY;
8360         return NULL;
8361     }
8362 }
8363         </programlisting>
8364       </sect3>
8365
8366       <sect3>
8367         <title>GetRec, FreeRec</title>
8368
8369         <para>
8370     A function is usually required to allocate the driver's
8371     screen-specific data structure and hook it into the
8372     <structname>ScrnInfoRec</structname>'s <structfield>driverPrivate</structfield> field.
8373     The <structname>ScrnInfoRec</structname>'s <structfield>driverPrivate</structfield> is
8374     initialised to <constant>NULL</constant>, so it is easy to check if the
8375     initialisation has already been done.  After allocating it, initialise
8376     the fields.  By using <function>xnfcalloc()</function> to do the allocation
8377     it is zeroed, and if the allocation fails the server exits.
8378         </para>
8379
8380         <para>
8381     NOTE:
8382     When allocating structures from inside the driver which are defined
8383     on the common level it is important to initialize the structure to
8384     zero.
8385     Only this guarantees that the server remains source compatible to
8386     future changes in common level structures.
8387         </para>
8388
8389         <programlisting>
8390 static Bool
8391 ZZZGetRec(ScrnInfoPtr pScrn)
8392 {
8393     if (pScrn-&gt;driverPrivate != NULL)
8394         return TRUE;
8395     pScrn-&gt;driverPrivate = xnfcalloc(sizeof(ZZZRec), 1);
8396     /* Initialise as required */
8397     ...
8398     return TRUE;
8399 }
8400         </programlisting>
8401
8402         <para>
8403     Define a macro in <filename>"zzz.h"</filename> which gets a pointer to
8404     the <structname>ZZZRec</structname> when given <parameter>pScrn</parameter>:
8405
8406           <programlisting>
8407 #define ZZZPTR(p) ((ZZZPtr)((p)-&gt;driverPrivate))
8408           </programlisting>
8409         </para>
8410
8411         <para>
8412     Define a function to free the above, setting it to <constant>NULL</constant>
8413     once it has been freed:
8414
8415           <programlisting>
8416 static void
8417 ZZZFreeRec(ScrnInfoPtr pScrn)
8418 {
8419     if (pScrn-&gt;driverPrivate == NULL)
8420         return;
8421     xfree(pScrn-&gt;driverPrivate);
8422     pScrn-&gt;driverPrivate = NULL;
8423 }
8424           </programlisting>
8425         </para>
8426       </sect3>
8427
8428       <sect3>
8429         <title>Identify</title>
8430
8431         <para>
8432     Define the <function>Identify()</function> function.  It is run before
8433     the Probe, and typically prints out an identifying message, which
8434     might include the chipsets it supports.  This function is mandatory:
8435
8436           <programlisting>
8437 static void
8438 ZZZIdentify(int flags)
8439 {
8440     xf86PrintChipsets(ZZZ_NAME, "driver for ZZZ Tech chipsets",
8441                       ZZZChipsets);
8442 }
8443           </programlisting>
8444         </para>
8445       </sect3>
8446
8447       <sect3>
8448         <title>Probe</title>
8449
8450         <para>
8451     Define the <function>Probe()</function> function.  The purpose of this
8452     is to find all instances of the hardware that the driver supports,
8453     and for the ones not already claimed by another driver, claim the
8454     slot, and allocate a <structname>ScrnInfoRec</structname>.  This should be
8455     a minimal probe, and it should under no circumstances leave the
8456     state of the hardware changed.  Because a device is found, don't
8457     assume that it will be used.  Don't do any initialisations other
8458     than the required <structname>ScrnInfoRec</structname> initialisations.
8459     Don't allocate any new data structures.
8460         </para>
8461
8462         <para>
8463     This function is mandatory.
8464         </para>
8465
8466         <para>
8467     NOTE: The <function>xf86DrvMsg()</function> functions cannot be used from
8468     the Probe.
8469         </para>
8470
8471         <programlisting>
8472 static Bool
8473 ZZZProbe(DriverPtr drv, int flags)
8474 {
8475     Bool foundScreen = FALSE;
8476     int numDevSections, numUsed;
8477     GDevPtr *devSections;
8478     int *usedChips;
8479     int i;
8480
8481     /*
8482      * Find the config file Device sections that match this
8483      * driver, and return if there are none.
8484      */
8485     if ((numDevSections = xf86MatchDevice(ZZZ_DRIVER_NAME,
8486                                           &amp;devSections)) &lt;= 0) {
8487         return FALSE;
8488     }
8489
8490     /*
8491      * Since this is a PCI card, "probing" just amounts to checking
8492      * the PCI data that the server has already collected.  If there
8493      * is none, return.
8494      *
8495      * Although the config file is allowed to override things, it
8496      * is reasonable to not allow it to override the detection
8497      * of no PCI video cards.
8498      *
8499      * The provided xf86MatchPciInstances() helper takes care of
8500      * the details.
8501      */
8502     /* test if PCI bus present */
8503     if (xf86GetPciVideoInfo()) {
8504
8505         numUsed = xf86MatchPciInstances(ZZZ_NAME, PCI_VENDOR_ZZZ,
8506                             ZZZChipsets, ZZZPciChipsets, devSections,
8507                             numDevSections, drv, &amp;usedChips);
8508
8509         for (i = 0; i &lt; numUsed; i++) {
8510             ScrnInfoPtr pScrn = NULL;
8511             if ((pScrn = xf86ConfigPciEntity(pScrn, flags, usedChips[i],
8512                                              ZZZPciChipsets, NULL, NULL,
8513                                              NULL, NULL, NULL))) {
8514                /* Allocate a ScrnInfoRec */
8515                pScrn-&gt;driverVersion = VERSION;
8516                pScrn-&gt;driverName    = ZZZ_DRIVER_NAME;
8517                pScrn-&gt;name          = ZZZ_NAME;
8518                pScrn-&gt;Probe         = ZZZProbe;
8519                pScrn-&gt;PreInit       = ZZZPreInit;
8520                pScrn-&gt;ScreenInit    = ZZZScreenInit;
8521                pScrn-&gt;SwitchMode    = ZZZSwitchMode;
8522                pScrn-&gt;AdjustFrame   = ZZZAdjustFrame;
8523                pScrn-&gt;EnterVT       = ZZZEnterVT;
8524                pScrn-&gt;LeaveVT       = ZZZLeaveVT;
8525                pScrn-&gt;FreeScreen    = ZZZFreeScreen;
8526                pScrn-&gt;ValidMode     = ZZZValidMode;
8527                foundScreen = TRUE;
8528                /* add screen to entity */
8529            }
8530         }
8531         xfree(usedChips);
8532     }
8533
8534 #ifdef HAS_ISA_DEVS
8535     /*
8536      * If the driver supports ISA hardware, the following block
8537      * can be included too.
8538      */
8539     numUsed = xf86MatchIsaInstances(ZZZ_NAME, ZZZChipsets,
8540                              ZZZIsaChipsets, drv, ZZZFindIsaDevice,
8541                              devSections, numDevSections, &amp;usedChips);
8542     for (i = 0; i &lt; numUsed; i++) {
8543         ScrnInfoPtr pScrn = NULL;
8544         if ((pScrn = xf86ConfigIsaEntity(pScrn, flags, usedChips[i],
8545                                          ZZZIsaChipsets, NULL, NULL, NULL,
8546                                          NULL, NULL))) {
8547             pScrn-&gt;driverVersion = VERSION;
8548             pScrn-&gt;driverName    = ZZZ_DRIVER_NAME;
8549             pScrn-&gt;name          = ZZZ_NAME;
8550             pScrn-&gt;Probe         = ZZZProbe;
8551             pScrn-&gt;PreInit       = ZZZPreInit;
8552             pScrn-&gt;ScreenInit    = ZZZScreenInit;
8553             pScrn-&gt;SwitchMode    = ZZZSwitchMode;
8554             pScrn-&gt;AdjustFrame   = ZZZAdjustFrame;
8555             pScrn-&gt;EnterVT       = ZZZEnterVT;
8556             pScrn-&gt;LeaveVT       = ZZZLeaveVT;
8557             pScrn-&gt;FreeScreen    = ZZZFreeScreen;
8558             pScrn-&gt;ValidMode     = ZZZValidMode;
8559             foundScreen = TRUE;
8560         }
8561     }
8562     xfree(usedChips);
8563 #endif /* HAS_ISA_DEVS */
8564
8565     xfree(devSections);
8566     return foundScreen;
8567         </programlisting>
8568       </sect3>
8569
8570       <sect3>
8571         <title>AvailableOptions</title>
8572
8573         <para>
8574     Define the <function>AvailableOptions()</function> function. The purpose
8575     of this is to return the available driver options back to the
8576     -configure option, so that an xorg.conf file can be built and the
8577     user can see which options are available for them to use.
8578         </para>
8579       </sect3>
8580
8581       <sect3>
8582         <title>PreInit</title>
8583
8584         <para>
8585     Define the <function>PreInit()</function> function.  The purpose of
8586     this is to find all the information required to determine if the
8587     configuration is usable, and to initialise those parts of the
8588     <structname>ScrnInfoRec</structname> that can be set once at the beginning
8589     of the first server generation.  The information should be found in
8590     the least intrusive way possible.
8591         </para>
8592
8593         <para>
8594     This function is mandatory.
8595         </para>
8596
8597         <para>
8598     NOTES:
8599           <orderedlist>
8600             <listitem><para>
8601          The <function>PreInit()</function> function is only called once
8602          during the life of the X server (at the start of the first
8603          generation).
8604               </para></listitem>
8605
8606             <listitem><para>
8607          Data allocated here must be of the type that persists for
8608          the life of the X server.  This means that data that hooks into
8609          the <structname>ScrnInfoRec</structname>'s <structfield>privates</structfield>
8610          field should be allocated here, but data that hooks into the
8611          <structname>ScreenRec</structname>'s <structfield>devPrivates</structfield> field
8612          should not be allocated here.  The <structfield>driverPrivate</structfield>
8613          field should also be allocated here.
8614               </para></listitem>
8615
8616             <listitem><para>
8617          Although the <structname>ScrnInfoRec</structname> has been allocated
8618          before this function is called, the <structname>ScreenRec</structname>
8619          has not been allocated.  That means that things requiring it
8620          cannot be used in this function.
8621               </para></listitem>
8622
8623             <listitem><para>
8624          Very little of the <structname>ScrnInfoRec</structname> has been
8625          initialised when this function is called.  It is important to
8626          get the order of doing things right in this function.
8627               </para></listitem>
8628
8629           </orderedlist>
8630         </para>
8631
8632         <programlisting>
8633 static Bool
8634 ZZZPreInit(ScrnInfoPtr pScrn, int flags)
8635 {
8636     /* Fill in the monitor field */
8637     pScrn-&gt;monitor = pScrn-&gt;confScreen-&gt;monitor;
8638
8639     /*
8640      * If using the vgahw module, it will typically be loaded
8641      * here by calling xf86LoadSubModule(pScrn, "vgahw");
8642      */
8643
8644     /*
8645      * Set the depth/bpp.  Use the globally preferred depth/bpp.  If the
8646      * driver has special default depth/bpp requirements, the defaults should
8647      * be specified here explicitly.
8648      * We support both 24bpp and 32bpp framebuffer layouts.
8649      * This sets pScrn-&gt;display also.
8650      */
8651     if (!xf86SetDepthBpp(pScrn, 0, 0, 0,
8652                          Support24bppFb | Support32bppFb)) {
8653         return FALSE;
8654     } else {
8655         if (depth/bpp isn't one we support) {
8656             print error message;
8657             return FALSE;
8658         }
8659     }
8660     /* Print out the depth/bpp that was set */
8661     xf86PrintDepthBpp(pScrn);
8662
8663     /* Set bits per RGB for 8bpp */
8664     if (pScrn-&gt;depth &lt;= 8) {
8665         /* Take into account a dac_6_bit option here */
8666         pScrn-&gt;rgbBits = 6 or 8;
8667     }
8668
8669     /*
8670      * xf86SetWeight() and xf86SetDefaultVisual() must be called
8671      * after pScrn-&gt;display is initialised.
8672      */
8673
8674     /* Set weight/mask/offset for depth &gt; 8 */
8675     if (pScrn-&gt;depth &gt; 8) {
8676         if (!xf86SetWeight(pScrn, defaultWeight, defaultMask)) {
8677             return FALSE;
8678         } else {
8679             if (weight isn't one we support) {
8680                 print error message;
8681                 return FALSE;
8682             }
8683         }
8684     }
8685
8686     /* Set the default visual. */
8687     if (!xf86SetDefaultVisual(pScrn, -1)) {
8688         return FALSE;
8689     } else {
8690         if (visual isn't one we support) {
8691             print error message;
8692             return FALSE;
8693         }
8694     }
8695
8696     /* If the driver supports gamma correction, set the gamma. */
8697     if (!xf86SetGamma(pScrn, default_gamma)) {
8698         return FALSE;
8699     }
8700
8701     /* This driver uses a programmable clock */
8702     pScrn-&gt;progClock = TRUE;
8703
8704     /* Allocate the ZZZRec driverPrivate */
8705     if (!ZZZGetRec(pScrn)) {
8706         return FALSE;
8707     }
8708
8709     pZzz = ZZZPTR(pScrn);
8710
8711     /* Collect all of the option flags (fill in pScrn-&gt;options) */
8712     xf86CollectOptions(pScrn, NULL);
8713
8714     /*
8715      * Process the options based on the information in ZZZOptions.
8716      * The results are written to pZzz-&gt;Options.  If all of the options
8717      * processing is done within this function a local variable "options"
8718      * can be used instead of pZzz-&gt;Options.
8719      */
8720     if (!(pZzz-&gt;Options = xalloc(sizeof(ZZZOptions))))
8721         return FALSE;
8722     (void)memcpy(pZzz-&gt;Options, ZZZOptions, sizeof(ZZZOptions));
8723     xf86ProcessOptions(pScrn-&gt;scrnIndex, pScrn-&gt;options, pZzz-&gt;Options);
8724
8725     /*
8726      * Set various fields of ScrnInfoRec and/or ZZZRec based on
8727      * the options found.
8728      */
8729     from = X_DEFAULT;
8730     pZzz-&gt;hwCursor = FALSE;
8731     if (xf86IsOptionSet(pZzz-&gt;Options, OPTION_HW_CURSOR)) {
8732         from = X_CONFIG;
8733         pZzz-&gt;hwCursor = TRUE;
8734     }
8735     xf86DrvMsg(pScrn-&gt;scrnIndex, from, "Using %s cursor\n",
8736                pZzz-&gt;hwCursor ? "HW" : "SW");
8737     if (xf86IsOptionSet(pZzz-&gt;Options, OPTION_NOACCEL)) {
8738         pZzz-&gt;noAccel = TRUE;
8739         xf86DrvMsg(pScrn-&gt;scrnIndex, X_CONFIG,
8740                    "Acceleration disabled\n");
8741     } else {
8742         pZzz-&gt;noAccel = FALSE;
8743     }
8744     if (xf86IsOptionSet(pZzz-&gt;Options, OPTION_PCI_RETRY)) {
8745         pZzz-&gt;UsePCIRetry = TRUE;
8746         xf86DrvMsg(pScrn-&gt;scrnIndex, X_CONFIG, "PCI retry enabled\n");
8747     }
8748     pZzz-&gt;fooHack = 0;
8749     if (xf86GetOptValInteger(pZzz-&gt;Options, OPTION_FOO_HACK,
8750                              &amp;pZzz-&gt;fooHack)) {
8751         xf86DrvMsg(pScrn-&gt;scrnIndex, X_CONFIG, "Foo Hack set to %d\n",
8752                    pZzz-&gt;fooHack);
8753     }
8754
8755     /*
8756      * Find the PCI slot(s) that this screen claimed in the probe.
8757      * In this case, exactly one is expected, so complain otherwise.
8758      * Note in this case we're not interested in the card types so
8759      * that parameter is set to NULL.
8760      */
8761     if ((i = xf86GetPciInfoForScreen(pScrn-&gt;scrnIndex, &amp;pciList, NULL))
8762         != 1) {
8763         print error message;
8764         ZZZFreeRec(pScrn);
8765         if (i &gt; 0)
8766             xfree(pciList);
8767         return FALSE;
8768     }
8769     /* Note that pciList should be freed below when no longer needed */
8770
8771     /*
8772      * Determine the chipset, allowing config file chipset and
8773      * chipid values to override the probed information.  The config
8774      * chipset value has precedence over its chipid value if both
8775      * are present.
8776      *
8777      * It isn't necessary to fill in pScrn-&gt;chipset if the driver
8778      * keeps track of the chipset in its ZZZRec.
8779      */
8780
8781     ...
8782
8783     /*
8784      * Determine video memory, fb base address, I/O addresses, etc,
8785      * allowing the config file to override probed values.
8786      *
8787      * Set the appropriate pScrn fields (videoRam is probably the
8788      * most important one that other code might require), and
8789      * print out the settings.
8790      */
8791
8792     ...
8793
8794     /* Initialise a clockRanges list. */
8795
8796     ...
8797
8798     /* Set any other chipset specific things in the ZZZRec */
8799
8800     ...
8801
8802     /* Select valid modes from those available */
8803
8804     i = xf86ValidateModes(pScrn, pScrn-&gt;monitor-&gt;Modes,
8805                           pScrn-&gt;display-&gt;modes, clockRanges,
8806                           NULL, minPitch, maxPitch, rounding,
8807                           minHeight, maxHeight,
8808                           pScrn-&gt;display-&gt;virtualX,
8809                           pScrn-&gt;display-&gt;virtualY,
8810                           pScrn-&gt;videoRam * 1024,
8811                           LOOKUP_BEST_REFRESH);
8812     if (i == -1) {
8813         ZZZFreeRec(pScrn);
8814         return FALSE;
8815     }
8816
8817     /* Prune the modes marked as invalid */
8818
8819     xf86PruneDriverModes(pScrn);
8820
8821     /* If no valid modes, return */
8822
8823     if (i == 0 || pScrn-&gt;modes == NULL) {
8824         print error message;
8825         ZZZFreeRec(pScrn);
8826         return FALSE;
8827     }
8828
8829     /*
8830      * Initialise the CRTC fields for the modes.  This driver expects
8831      * vertical values to be halved for interlaced modes.
8832      */
8833     xf86SetCrtcForModes(pScrn, INTERLACE_HALVE_V);
8834
8835     /* Set the current mode to the first in the list. */
8836     pScrn-&gt;currentMode = pScrn-&gt;modes;
8837
8838     /* Print the list of modes being used. */
8839     xf86PrintModes(pScrn);
8840
8841     /* Set the DPI */
8842     xf86SetDpi(pScrn, 0, 0);
8843
8844     /* Load bpp-specific modules */
8845     switch (pScrn-&gt;bitsPerPixel) {
8846     case 1:
8847         mod = "xf1bpp";
8848         break;
8849     case 4:
8850         mod = "xf4bpp";
8851         break;
8852     case 8:
8853         mod = "cfb";
8854         break;
8855     case 16:
8856         mod = "cfb16";
8857         break;
8858     case 24:
8859         mod = "cfb24";
8860         break;
8861     case 32:
8862         mod = "cfb32";
8863         break;
8864     }
8865     if (mod &amp;&amp; !xf86LoadSubModule(pScrn, mod))
8866         ZZZFreeRec(pScrn);
8867         return FALSE;
8868
8869
8870     /* Done */
8871     return TRUE;
8872 }
8873         </programlisting>
8874       </sect3>
8875
8876       <sect3>
8877         <title>MapMem, UnmapMem</title>
8878
8879         <para>
8880     Define functions to map and unmap the video memory and any other
8881     memory apertures required.  These functions are not mandatory, but
8882     it is often useful to have such functions.
8883         </para>
8884
8885         <programlisting>
8886 static Bool
8887 ZZZMapMem(ScrnInfoPtr pScrn)
8888 {
8889     /* Call xf86MapPciMem() to map each PCI memory area */
8890     ...
8891     return TRUE or FALSE;
8892 }
8893
8894 static Bool
8895 ZZZUnmapMem(ScrnInfoPtr pScrn)
8896 {
8897     /* Call xf86UnMapVidMem() to unmap each memory area */
8898     ...
8899     return TRUE or FALSE;
8900 }
8901         </programlisting>
8902       </sect3>
8903
8904       <sect3>
8905         <title>Save, Restore</title>
8906
8907         <para>
8908     Define functions to save and restore the original video state.  These
8909     functions are not mandatory, but are often useful.
8910         </para>
8911
8912         <programlisting>
8913 static void
8914 ZZZSave(ScrnInfoPtr pScrn)
8915 {
8916     /*
8917      * Save state into per-screen data structures.
8918      * If using the vgahw module, vgaHWSave will typically be
8919      * called here.
8920      */
8921     ...
8922 }
8923
8924 static void
8925 ZZZRestore(ScrnInfoPtr pScrn)
8926 {
8927     /*
8928      * Restore state from per-screen data structures.
8929      * If using the vgahw module, vgaHWRestore will typically be
8930      * called here.
8931      */
8932     ...
8933 }
8934         </programlisting>
8935       </sect3>
8936
8937       <sect3>
8938         <title>ModeInit</title>
8939
8940         <para>
8941     Define a function to initialise a new video mode.  This function isn't
8942     mandatory, but is often useful.
8943         </para>
8944
8945         <programlisting>
8946 static Bool
8947 ZZZModeInit(ScrnInfoPtr pScrn, DisplayModePtr mode)
8948 {
8949     /*
8950      * Program a video mode.  If using the vgahw module,
8951      * vgaHWInit and vgaRestore will typically be called here.
8952      * Once up to the point where there can't be a failure
8953      * set pScrn-&gt;vtSema to TRUE.
8954      */
8955     ...
8956 }
8957         </programlisting>
8958       </sect3>
8959
8960       <sect3>
8961         <title>ScreenInit</title>
8962
8963         <para>
8964     Define the <function>ScreenInit()</function> function.  This is called
8965     at the start of each server generation, and should fill in as much
8966     of the <structname>ScreenRec</structname> as possible as well as any other
8967     data that is initialised once per generation.  It should initialise
8968     the framebuffer layers it is using, and initialise the initial video
8969     mode.
8970         </para>
8971
8972         <para>
8973     This function is mandatory.
8974         </para>
8975
8976         <para>
8977     NOTE: The <structname>ScreenRec</structname> (<parameter>pScreen</parameter>) is
8978           passed to this driver, but it and the
8979           <varname>ScrnInfoRecs</varname> are not yet hooked into each
8980           other.  This means that in this function, and functions it
8981           calls, one cannot be found from the other.
8982         </para>
8983
8984         <programlisting>
8985 static Bool
8986 ZZZScreenInit(ScreenPtr pScreen, int argc, char **argv)
8987 {
8988     /* Get the ScrnInfoRec */
8989     pScrn = xf86ScreenToScrn(pScreen);
8990
8991     /*
8992      * If using the vgahw module, its data structures and related
8993      * things are typically initialised/mapped here.
8994      */
8995
8996     /* Save the current video state */
8997     ZZZSave(pScrn);
8998
8999     /* Initialise the first mode */
9000     ZZZModeInit(pScrn, pScrn-&gt;currentMode);
9001
9002     /* Set the viewport if supported */
9003
9004     ZZZAdjustFrame(pScrn, pScrn-&gt;frameX0, pScrn-&gt;frameY0);
9005
9006     /*
9007      * Setup the screen's visuals, and initialise the framebuffer
9008      * code.
9009      */
9010
9011     /* Reset the visual list */
9012     miClearVisualTypes();
9013
9014     /*
9015      * Setup the visuals supported.  This driver only supports
9016      * TrueColor for bpp &gt; 8, so the default set of visuals isn't
9017      * acceptable.  To deal with this, call miSetVisualTypes with
9018      * the appropriate visual mask.
9019      */
9020
9021     if (pScrn-&gt;bitsPerPixel &gt; 8) {
9022         if (!miSetVisualTypes(pScrn-&gt;depth, TrueColorMask,
9023                               pScrn-&gt;rgbBits, pScrn-&gt;defaultVisual))
9024             return FALSE;
9025     } else {
9026         if (!miSetVisualTypes(pScrn-&gt;depth,
9027                               miGetDefaultVisualMask(pScrn-&gt;depth),
9028                               pScrn-&gt;rgbBits, pScrn-&gt;defaultVisual))
9029             return FALSE;
9030     }
9031
9032     /*
9033      * Initialise the framebuffer.
9034      */
9035
9036     switch (pScrn-&gt;bitsPerPixel) {
9037     case 1:
9038         ret = xf1bppScreenInit(pScreen, FbBase,
9039                                pScrn-&gt;virtualX, pScrn-&gt;virtualY,
9040                                pScrn-&gt;xDpi, pScrn-&gt;yDpi,
9041                                pScrn-&gt;displayWidth);
9042         break;
9043     case 4:
9044         ret = xf4bppScreenInit(pScreen, FbBase,
9045                                pScrn-&gt;virtualX, pScrn-&gt;virtualY,
9046                                pScrn-&gt;xDpi, pScrn-&gt;yDpi,
9047                                pScrn-&gt;displayWidth);
9048         break;
9049     case 8:
9050         ret = cfbScreenInit(pScreen, FbBase,
9051                             pScrn-&gt;virtualX, pScrn-&gt;virtualY,
9052                             pScrn-&gt;xDpi, pScrn-&gt;yDpi,
9053                             pScrn-&gt;displayWidth);
9054         break;
9055     case 16:
9056         ret = cfb16ScreenInit(pScreen, FbBase,
9057                               pScrn-&gt;virtualX, pScrn-&gt;virtualY,
9058                               pScrn-&gt;xDpi, pScrn-&gt;yDpi,
9059                               pScrn-&gt;displayWidth);
9060         break;
9061     case 24:
9062         ret = cfb24ScreenInit(pScreen, FbBase,
9063                               pScrn-&gt;virtualX, pScrn-&gt;virtualY,
9064                               pScrn-&gt;xDpi, pScrn-&gt;yDpi,
9065                               pScrn-&gt;displayWidth);
9066         break;
9067     case 32:
9068         ret = cfb32ScreenInit(pScreen, FbBase,
9069                               pScrn-&gt;virtualX, pScrn-&gt;virtualY,
9070                               pScrn-&gt;xDpi, pScrn-&gt;yDpi,
9071                               pScrn-&gt;displayWidth);
9072         break;
9073     default:
9074         print a message about an internal error;
9075         ret = FALSE;
9076         break;
9077     }
9078
9079     if (!ret)
9080         return FALSE;
9081
9082     /* Override the default mask/offset settings */
9083     if (pScrn-&gt;bitsPerPixel &gt; 8) {
9084         for (i = 0, visual = pScreen-&gt;visuals;
9085              i &lt; pScreen-&gt;numVisuals; i++, visual++) {
9086             if ((visual-&gt;class | DynamicClass) == DirectColor) {
9087                 visual-&gt;offsetRed = pScrn-&gt;offset.red;
9088                 visual-&gt;offsetGreen = pScrn-&gt;offset.green;
9089                 visual-&gt;offsetBlue = pScrn-&gt;offset.blue;
9090                 visual-&gt;redMask = pScrn-&gt;mask.red;
9091                 visual-&gt;greenMask = pScrn-&gt;mask.green;
9092                 visual-&gt;blueMask = pScrn-&gt;mask.blue;
9093             }
9094         }
9095     }
9096
9097     /*
9098      * If banking is needed, initialise an miBankInfoRec (defined in
9099      * "mibank.h"), and call miInitializeBanking().
9100      */
9101     if (!miInitializeBanking(pScreen, pScrn-&gt;virtualX, pScrn-&gt;virtualY,
9102                                      pScrn-&gt;displayWidth, pBankInfo))
9103         return FALSE;
9104
9105     /*
9106      * If backing store is to be supported (as is usually the case),
9107      * initialise it.
9108      */
9109     miInitializeBackingStore(pScreen);
9110
9111     /*
9112      * Set initial black &amp; white colourmap indices.
9113      */
9114     xf86SetBlackWhitePixels(pScreen);
9115
9116     /*
9117      * Install colourmap functions.  If using the vgahw module,
9118      * vgaHandleColormaps would usually be called here.
9119      */
9120
9121     ...
9122
9123     /*
9124      * Initialise cursor functions.  This example is for the mi
9125      * software cursor.
9126      */
9127     miDCInitialize(pScreen, xf86GetPointerScreenFuncs());
9128
9129     /* Initialise the default colourmap */
9130     switch (pScrn-&gt;depth) {
9131     case 1:
9132         if (!xf1bppCreateDefColormap(pScreen))
9133             return FALSE;
9134         break;
9135     case 4:
9136         if (!xf4bppCreateDefColormap(pScreen))
9137             return FALSE;
9138         break;
9139     default:
9140         if (!cfbCreateDefColormap(pScreen))
9141             return FALSE;
9142         break;
9143     }
9144
9145     /*
9146      * Wrap the CloseScreen vector and set SaveScreen.
9147      */
9148     ZZZPTR(pScrn)-&gt;CloseScreen = pScreen-&gt;CloseScreen;
9149     pScreen-&gt;CloseScreen = ZZZCloseScreen;
9150     pScreen-&gt;SaveScreen = ZZZSaveScreen;
9151
9152     /* Report any unused options (only for the first generation) */
9153     if (serverGeneration == 1) {
9154         xf86ShowUnusedOptions(pScrn-&gt;scrnIndex, pScrn-&gt;options);
9155     }
9156
9157     /* Done */
9158     return TRUE;
9159 }
9160         </programlisting>
9161       </sect3>
9162
9163       <sect3>
9164         <title>SwitchMode</title>
9165
9166         <para>
9167     Define the <function>SwitchMode()</function> function if mode switching
9168     is supported by the driver.
9169         </para>
9170
9171         <programlisting>
9172 static Bool
9173 ZZZSwitchMode(ScrnInfoPtr pScrn, DisplayModePtr mode)
9174 {
9175     return ZZZModeInit(pScrn, mode);
9176 }
9177         </programlisting>
9178       </sect3>
9179
9180       <sect3>
9181         <title>AdjustFrame</title>
9182
9183         <para>
9184     Define the <function>AdjustFrame()</function> function if the driver
9185     supports this.
9186         </para>
9187
9188         <programlisting>
9189 static void
9190 ZZZAdjustFrame(ScrnInfoPtr pScrn, int x, int y)
9191 {
9192     /* Adjust the viewport */
9193 }
9194         </programlisting>
9195       </sect3>
9196
9197       <sect3>
9198         <title>EnterVT, LeaveVT</title>
9199
9200         <para>
9201     Define the <function>EnterVT()</function> and <function>LeaveVT()</function>
9202     functions.
9203         </para>
9204
9205         <para>
9206     These functions are mandatory.
9207         </para>
9208
9209         <programlisting>
9210 static Bool
9211 ZZZEnterVT(ScrnInfoPtr pScrn)
9212 {
9213     return ZZZModeInit(pScrn, pScrn-&gt;currentMode);
9214 }
9215
9216 static void
9217 ZZZLeaveVT(ScrnInfoPtr pScrn)
9218 {
9219     ZZZRestore(pScrn);
9220 }
9221         </programlisting>
9222       </sect3>
9223
9224       <sect3>
9225         <title>CloseScreen</title>
9226
9227         <para>
9228     Define the <function>CloseScreen()</function> function:
9229         </para>
9230
9231         <para>
9232     This function is mandatory.  Note that it unwraps the previously
9233     wrapped <structfield>pScreen-&gt;CloseScreen</structfield>, and finishes by
9234     calling it.
9235         </para>
9236
9237         <programlisting>
9238 static Bool
9239 ZZZCloseScreen(ScreenPtr pScreen)
9240 {
9241     ScrnInfoPtr pScrn = xf86ScreenToScrn(pScreen);
9242     if (pScrn-&gt;vtSema) {
9243         ZZZRestore(pScrn);
9244         ZZZUnmapMem(pScrn);
9245     }
9246     pScrn-&gt;vtSema = FALSE;
9247     pScreen-&gt;CloseScreen = ZZZPTR(pScrn)-&gt;CloseScreen;
9248     return (*pScreen-&gt;CloseScreen)(pScreen);
9249 }
9250         </programlisting>
9251       </sect3>
9252
9253       <sect3>
9254         <title>SaveScreen</title>
9255
9256         <para>
9257     Define the <function>SaveScreen()</function> function (the screen
9258     blanking function).  When using the vgahw module, this will typically
9259     be:
9260
9261           <programlisting>
9262 static Bool
9263 ZZZSaveScreen(ScreenPtr pScreen, int mode)
9264 {
9265     return vgaHWSaveScreen(pScreen, mode);
9266 }
9267           </programlisting>
9268         </para>
9269
9270         <para>
9271     This function is mandatory.  Before modifying any hardware register
9272     directly this function needs to make sure that the Xserver is active
9273     by checking if <parameter>pScrn</parameter> is non-NULL and for
9274     <literal remap="tt">pScrn-&gt;vtSema == TRUE</literal>.
9275         </para>
9276       </sect3>
9277
9278       <sect3>
9279         <title>FreeScreen</title>
9280
9281         <para>
9282     Define the <function>FreeScreen()</function> function.  This function
9283     is optional.  It should be defined if the <structname>ScrnInfoRec</structname>
9284     <structfield>driverPrivate</structfield> field is used so that it can be freed
9285     when a screen is deleted by the common layer for reasons possibly
9286     beyond the driver's control.  This function is not used in during
9287     normal (error free) operation.  The per-generation data is freed by
9288     the <function>CloseScreen()</function> function.
9289         </para>
9290
9291         <programlisting>
9292 static void
9293 ZZZFreeScreen(ScrnInfoPtr pScrn)
9294 {
9295     /*
9296      * If the vgahw module is used vgaHWFreeHWRec() would be called
9297      * here.
9298      */
9299     ZZZFreeRec(pScrn);
9300 }
9301
9302         </programlisting>
9303
9304       </sect3>
9305
9306     </sect2>
9307
9308   </sect1>
9309
9310 </article>