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 using the mi colourmap code need this:
3565             <literallayout><filename>
3566     "micmap.h"
3567               </filename></literallayout>
3568           </para>
3569
3570           <para>
3571   If a driver uses the vgahw module, it needs this:
3572             <literallayout><filename>
3573     "vgaHW.h"
3574               </filename></literallayout>
3575           </para>
3576
3577           <para>
3578   Drivers supporting VGA or Hercules monochrome screens need:
3579             <literallayout><filename>
3580     "xf1bpp.h"
3581               </filename></literallayout>
3582           </para>
3583
3584           <para>
3585   Drivers supporting VGA or EGC 16-colour screens need:
3586             <literallayout><filename>
3587     "xf4bpp.h"
3588               </filename></literallayout>
3589           </para>
3590
3591           <para>
3592   Drivers using cfb need:
3593             <programlisting>
3594     #define PSZ 8
3595     #include "cfb.h"
3596     #undef PSZ
3597             </programlisting>
3598           </para>
3599
3600           <para>
3601   Drivers supporting bpp 16, 24 or 32 with cfb need one or more of:
3602             <literallayout><filename>
3603     "cfb16.h"
3604     "cfb24.h"
3605     "cfb32.h"
3606               </filename></literallayout>
3607           </para>
3608
3609           <para>
3610   If a driver uses the fb manager, it needs this:
3611             <literallayout><filename>
3612     "xf86fbman.h"
3613               </filename></literallayout>
3614           </para>
3615         </blockquote>
3616       </para>
3617
3618       <para>
3619 Non-driver modules should include <filename>"xf86_ansic.h"</filename> to get the correct
3620 wrapping of ANSI C/libc functions.
3621       </para>
3622
3623       <para>
3624 All modules must NOT include any system include files, or the following:
3625
3626         <literallayout><filename>
3627     "xf86Priv.h"
3628     "xf86Privstr.h"
3629     "xf86_OSlib.h"
3630     "Xos.h"
3631           </filename></literallayout>
3632       </para>
3633
3634       <para>
3635 In addition, "xf86_libc.h" must not be included explicitly.  It is
3636 included implicitly by "xf86_ansic.h".
3637       </para>
3638
3639     </sect2>
3640   </sect1>
3641
3642   <sect1>
3643     <title>Offscreen Memory Manager</title>
3644
3645     <para>
3646 Management of offscreen video memory may be handled by the XFree86
3647 framebuffer manager.  Once the offscreen memory manager is running,
3648 drivers or extensions may allocate, free or resize areas of offscreen
3649 video memory using the following functions (definitions taken from
3650 <filename>xf86fbman.h</filename>):
3651
3652       <programlisting>
3653     typedef struct _FBArea {
3654         ScreenPtr    pScreen;
3655         BoxRec       box;
3656         int          granularity;
3657         void         (*MoveAreaCallback)(struct _FBArea*, struct _FBArea*)
3658         void         (*RemoveAreaCallback)(struct _FBArea*)
3659         DevUnion     devPrivate;
3660     } FBArea, *FBAreaPtr;
3661
3662     typedef void (*MoveAreaCallbackProcPtr)(FBAreaPtr from, FBAreaPtr to)
3663     typedef void (*RemoveAreaCallbackProcPtr)(FBAreaPtr)
3664
3665     FBAreaPtr xf86AllocateOffscreenArea (
3666         ScreenPtr pScreen,
3667         int width, int height,
3668         int granularity,
3669         MoveAreaCallbackProcPtr MoveAreaCallback,
3670         RemoveAreaCallbackProcPtr RemoveAreaCallback,
3671         pointer privData
3672     )
3673
3674     void xf86FreeOffscreenArea (FBAreaPtr area)
3675
3676     Bool xf86ResizeOffscreenArea (
3677         FBAreaPtr area
3678         int w, int h
3679     )
3680       </programlisting>
3681     </para>
3682
3683     <para>
3684 The function:
3685       <programlisting>
3686     Bool xf86FBManagerRunning(ScreenPtr pScreen);
3687       </programlisting>
3688
3689 can be used by an extension to check if the driver has initialized
3690 the memory manager.  The manager is not available if this returns
3691 <constant>FALSE</constant> and the functions above will all fail.
3692     </para>
3693
3694
3695     <para>
3696 <function>xf86AllocateOffscreenArea()</function> can be used to request a
3697 rectangle of dimensions <parameter>width</parameter>&nbsp;&times;&nbsp;<parameter>height</parameter>
3698 (in pixels) from unused offscreen memory.  <parameter>granularity</parameter>
3699 specifies that the leftmost edge of the rectangle must lie on some
3700 multiple of <parameter>granularity</parameter> pixels.  A granularity of zero
3701 means the same thing as a granularity of one - no alignment preference.
3702 A <parameter>MoveAreaCallback</parameter> can be provided to notify the requester
3703 when the offscreen area is moved.  If no <parameter>MoveAreaCallback</parameter>
3704 is supplied then the area is considered to be immovable.  The
3705 <parameter>privData</parameter> field will be stored in the manager's internal
3706 structure for that allocated area and will be returned to the requester
3707 in the <parameter>FBArea</parameter> passed via the
3708 <parameter>MoveAreaCallback</parameter>.  An optional
3709 <parameter>RemoveAreaCallback</parameter> is provided.  If the driver provides
3710 this it indicates that the area should be allocated with a lower priority.
3711 Such an area may be removed when a higher priority request (one that
3712 doesn't have a <parameter>RemoveAreaCallback</parameter>) is made.  When this
3713 function is called, the driver will have an opportunity to do whatever
3714 cleanup it needs to do to deal with the loss of the area, but it must
3715 finish its cleanup before the function exits since the offscreen memory
3716 manager will free the area immediately after.
3717     </para>
3718
3719     <para>
3720 <function>xf86AllocateOffscreenArea()</function> returns <constant>NULL</constant>
3721 if it was unable to allocate the requested area.  When no longer needed,
3722 areas should be freed with <function>xf86FreeOffscreenArea()</function>.
3723     </para>
3724
3725     <para>
3726 <function>xf86ResizeOffscreenArea()</function> resizes an existing
3727 <literal remap="tt">FBArea</literal>.  <function>xf86ResizeOffscreenArea()</function>
3728 returns <constant>TRUE</constant> if the resize was successful.  If
3729 <function>xf86ResizeOffscreenArea()</function> returns <constant>FALSE</constant>,
3730 the original <literal remap="tt">FBArea</literal> is left unmodified.  Resizing an
3731 area maintains the area's original <literal remap="tt">granularity</literal>,
3732 <literal remap="tt">devPrivate</literal>, and <literal remap="tt">MoveAreaCallback</literal>.
3733 <function>xf86ResizeOffscreenArea()</function> has considerably less overhead
3734 than freeing the old area then reallocating the new size, so it should
3735 be used whenever possible.
3736     </para>
3737
3738     <para>
3739 The function:
3740       <programlisting>
3741     Bool xf86QueryLargestOffscreenArea(
3742       ScreenPtr pScreen,
3743       int *width, int *height,
3744       int granularity,
3745       int preferences,
3746       int priority
3747     );
3748         </programlisting>
3749
3750 is provided to query the width and height of the largest single
3751 <structname>FBArea</structname> allocatable given a particular priority.
3752 <parameter>preferences</parameter> can be one of the following to indicate
3753 whether width, height or area should be considered when determining
3754 which is the largest single <structname>FBArea</structname> available.
3755
3756       <programlisting>
3757   FAVOR_AREA_THEN_WIDTH
3758   FAVOR_AREA_THEN_HEIGHT
3759   FAVOR_WIDTH_THEN_AREA
3760   FAVOR_HEIGHT_THEN_AREA
3761       </programlisting>
3762     </para>
3763
3764     <para>
3765 <parameter>priority</parameter> is one of the following:
3766
3767       <blockquote>
3768         <para>
3769   <constant>PRIORITY_LOW</constant>
3770           <blockquote><para>
3771      Return the largest block available without stealing anyone else's
3772      space.  This corresponds to the priority of allocating a
3773      <structname>FBArea</structname> when a <function>RemoveAreaCallback</function>
3774      is provided.
3775             </para></blockquote>
3776         </para>
3777
3778         <para>
3779    <constant>PRIORITY_NORMAL</constant>
3780           <blockquote><para>
3781      Return the largest block available if it is acceptable to steal a
3782      lower priority area from someone.  This corresponds to the priority
3783      of allocating a <structname>FBArea</structname> without providing a
3784      <function>RemoveAreaCallback</function>.
3785             </para></blockquote>
3786         </para>
3787
3788         <para>
3789     <constant>PRIORITY_EXTREME</constant>
3790           <blockquote><para>
3791      Return the largest block available if all <structname>FBArea</structname>s
3792      that aren't locked down were expunged from memory first.  This
3793      corresponds to any allocation made directly after a call to
3794      <function>xf86PurgeUnlockedOffscreenAreas()</function>.
3795             </para></blockquote>
3796         </para>
3797
3798       </blockquote>
3799     </para>
3800
3801
3802     <para>
3803 The function:
3804
3805       <programlisting>
3806     Bool xf86PurgeUnlockedOffscreenAreas(ScreenPtr pScreen);
3807       </programlisting>
3808
3809 is provided as an extreme method to free up offscreen memory.  This
3810 will remove all removable <structname>FBArea</structname> allocations.
3811     </para>
3812
3813
3814     <para>
3815 Initialization of the XFree86 framebuffer manager is done via
3816
3817       <programlisting>
3818     Bool xf86InitFBManager(ScreenPtr pScreen, BoxPtr FullBox);
3819       </programlisting>
3820
3821 <parameter>FullBox</parameter> represents the area of the framebuffer that the
3822 manager is allowed to manage.  This is typically a box with a width of
3823 <structfield>pScrn-&gt;displayWidth</structfield> and a height of as many lines as
3824 can be fit within the total video memory, however, the driver can reserve
3825 areas at the extremities by passing a smaller area to the manager.
3826     </para>
3827   </sect1>
3828
3829   <sect1 id="cmap">
3830     <title>Colormap Handling</title>
3831
3832     <para>
3833 A generic colormap handling layer is provided within the XFree86 common
3834 layer.  This layer takes care of most of the details, and only requires
3835 a function from the driver that loads the hardware palette when required.
3836 To use the colormap layer, a driver calls the
3837 <function>xf86HandleColormaps()</function> function.
3838
3839       <blockquote><para>
3840           <programlisting>
3841     Bool xf86HandleColormaps(ScreenPtr pScreen, int maxColors,
3842                              int sigRGBbits, LoadPaletteFuncPtr loadPalette,
3843                              SetOverscanFuncPtr setOverscan,
3844                              unsigned int flags);
3845           </programlisting>
3846           <blockquote><para>
3847       This function must be called after the default colormap has been
3848       initialised.  The <structfield>pScrn-&gt;gamma</structfield> field must also
3849       be initialised, preferably by calling <function>xf86SetGamma()</function>.
3850       <parameter>maxColors</parameter> is the number of entries in the palette.
3851       <parameter>sigRGBbits</parameter> is the size in bits of each color
3852       component in the DAC's palette.  <parameter>loadPalette</parameter>
3853       is a driver-provided function for loading a colormap into the
3854       hardware, and is described below.  <parameter>setOverscan</parameter> is
3855       an optional function that may be provided when the overscan color
3856       is an index from the standard LUT and when it needs to be adjusted
3857       to keep it as close to black as possible.  The
3858       <parameter>setOverscan</parameter> function programs the overscan index.
3859       It shouldn't normally be used for depths other than 8.
3860       <parameter>setOverscan</parameter> should be set to <constant>NULL</constant>
3861       when it isn't needed.  <parameter>flags</parameter> may be set to the
3862       following (which may be ORed together):
3863
3864               <variablelist>
3865                 <varlistentry>
3866                   <term><constant>CMAP_PALETTED_TRUECOLOR</constant></term>
3867                   <listitem><para>
3868                                     the TrueColor visual is paletted and is
3869                                     just a special case of DirectColor.
3870                                     This flag is only valid for
3871                                     <code>bpp&nbsp;&gt;&nbsp;8</code>.
3872
3873                     </para></listitem></varlistentry>
3874                 <varlistentry>
3875                   <term><constant>CMAP_RELOAD_ON_MODE_SWITCH</constant></term>
3876                   <listitem><para>
3877                                     reload the colormap automatically
3878                                     after mode switches.  This is useful
3879                                     for when the driver is resetting the
3880                                     hardware during mode switches and
3881                                     corrupting or erasing the hardware
3882                                     palette.
3883
3884                     </para></listitem></varlistentry>
3885                 <varlistentry>
3886                   <term><constant>CMAP_LOAD_EVEN_IF_OFFSCREEN</constant></term>
3887                   <listitem><para>
3888                                     reload the colormap even if the screen
3889                                     is switched out of the server's VC.
3890                                     The palette is <emphasis>not</emphasis> reloaded when
3891                                     the screen is switched back in, nor after
3892                                     mode switches.  This is useful when the
3893                                     driver needs to keep track of palette
3894                                     changes.
3895
3896                     </para></listitem></varlistentry>
3897               </variablelist>
3898             </para>
3899
3900             <para>
3901       The colormap layer normally reloads the palette after VT enters so it
3902       is not necessary for the driver to save and restore the palette
3903       when switching VTs.  The driver must, however, still save the
3904       initial palette during server start up and restore it during
3905       server exit.
3906             </para>
3907
3908           </blockquote></para></blockquote>
3909
3910       <blockquote><para>
3911           <programlisting>
3912     void LoadPalette(ScrnInfoPtr pScrn, int numColors, int *indices,
3913                      LOCO *colors, VisualPtr pVisual);
3914           </programlisting>
3915           <blockquote><para>
3916       <function>LoadPalette()</function> is a driver-provided function for
3917       loading a colormap into hardware.  <parameter>colors</parameter> is the
3918       array of RGB values that represent the full colormap.
3919       <parameter>indices</parameter> is a list of index values into the colors
3920       array.  These indices indicate the entries that need to be updated.
3921       <parameter>numColors</parameter> is the number of the indices to be
3922       updated.
3923             </para>
3924
3925           </blockquote></para></blockquote>
3926
3927       <blockquote><para>
3928           <programlisting>
3929     void SetOverscan(ScrnInfoPtr pScrn, int overscan);
3930           </programlisting>
3931           <blockquote><para>
3932       <function>SetOverscan()</function> is a driver-provided function for
3933       programming the <parameter>overscan</parameter> index.  As described
3934       above, it is normally only appropriate for LUT modes where all
3935       colormap entries are available for the display, but where one of
3936       them is also used for the overscan (typically 8bpp for VGA compatible
3937       LUTs).  It isn't required in cases where the overscan area is
3938       never visible.
3939             </para>
3940
3941           </blockquote></para>
3942       </blockquote></para>
3943
3944   </sect1>
3945
3946   <sect1>
3947     <title>DPMS Extension</title>
3948
3949     <para>
3950 Support code for the DPMS extension is included in the XFree86 common layer.
3951 This code provides an interface between the main extension code, and a means
3952 for drivers to initialise DPMS when they support it.  One function is
3953 available to drivers to do this initialisation, and it is always available,
3954 even when the DPMS extension is not supported by the core server (in
3955 which case it returns a failure result).
3956     </para>
3957
3958     <blockquote><para>
3959         <programlisting>
3960     Bool xf86DPMSInit(ScreenPtr pScreen, DPMSSetProcPtr set, int flags);
3961         </programlisting>
3962         <blockquote><para>
3963       This function registers a driver's DPMS level programming function
3964       <parameter>set</parameter>.  It also checks
3965       <structfield>pScrn-&gt;options</structfield> for the "dpms" option, and when
3966       present marks DPMS as being enabled for that screen.  The
3967       <parameter>set</parameter> function is called whenever the DPMS level
3968       changes, and is used to program the requested level.
3969       <parameter>flags</parameter> is currently not used, and should be
3970       <constant>0</constant>.  If the initialisation fails for any reason,
3971       including when there is no DPMS support in the core server, the
3972       function returns <constant>FALSE</constant>.
3973           </para>
3974
3975         </blockquote></para></blockquote>
3976
3977
3978     <para>
3979 Drivers that implement DPMS support must provide the following function,
3980 that gets called when the DPMS level is changed:
3981
3982
3983       <blockquote><para>
3984           <programlisting>
3985     void ChipDPMSSet(ScrnInfoPtr pScrn, int level, int flags);
3986           </programlisting>
3987           <blockquote><para>
3988       Program the DPMS level specified by <parameter>level</parameter>.  Valid
3989       values of <parameter>level</parameter> are <constant>DPMSModeOn</constant>,
3990       <constant>DPMSModeStandby</constant>, <constant>DPMSModeSuspend</constant>,
3991       <constant>DPMSModeOff</constant>.  These values are defined in
3992       <filename>"extensions/dpms.h"</filename>.
3993             </para>
3994
3995           </blockquote></para></blockquote>
3996     </para>
3997
3998   </sect1>
3999
4000   <sect1>
4001     <title>DGA Extension</title>
4002
4003     <para>
4004 Drivers can support the XFree86 Direct Graphics Architecture (DGA) by
4005 filling out a structure of function pointers and a list of modes and
4006 passing them to DGAInit.
4007     </para>
4008
4009     <blockquote><para>
4010         <programlisting>
4011     Bool DGAInit(ScreenPtr pScreen, DGAFunctionPtr funcs,
4012                  DGAModePtr modes, int num);
4013
4014 /** The DGAModeRec **/
4015
4016 typedef struct {
4017   int num;
4018   DisplayModePtr mode;
4019   int flags;
4020   int imageWidth;
4021   int imageHeight;
4022   int pixmapWidth;
4023   int pixmapHeight;
4024   int bytesPerScanline;
4025   int byteOrder;
4026   int depth;
4027   int bitsPerPixel;
4028   unsigned long red_mask;
4029   unsigned long green_mask;
4030   unsigned long blue_mask;
4031   int viewportWidth;
4032   int viewportHeight;
4033   int xViewportStep;
4034   int yViewportStep;
4035   int maxViewportX;
4036   int maxViewportY;
4037   int viewportFlags;
4038   int offset;
4039   unsigned char *address;
4040   int reserved1;
4041   int reserved2;
4042 } DGAModeRec, *DGAModePtr;
4043         </programlisting>
4044
4045         <variablelist>
4046           <varlistentry>
4047             <term><structfield>num</structfield></term>
4048             <listitem><para>
4049          Can be ignored.  The DGA DDX will assign these numbers.
4050               </para></listitem></varlistentry>
4051
4052           <varlistentry>
4053             <term><structfield>mode</structfield></term>
4054             <listitem><para>
4055         A pointer to the <structname>DisplayModeRec</structname> for this mode.
4056               </para></listitem></varlistentry>
4057
4058           <varlistentry>
4059             <term><structfield>flags</structfield></term>
4060               <listitem><para>
4061         The following flags are defined and may be OR'd together:
4062
4063                   <variablelist>
4064                     <varlistentry>
4065                       <term><constant>DGA_CONCURRENT_ACCESS</constant></term>
4066                       <listitem><para>
4067             Indicates that the driver supports concurrent graphics
4068             accelerator and linear framebuffer access.
4069
4070                         </para></listitem></varlistentry>
4071
4072                     <varlistentry>
4073                       <term><constant>DGA_FILL_RECT
4074                           DGA_BLIT_RECT
4075                           DGA_BLIT_RECT_TRANS</constant></term>
4076                       <listitem><para>
4077             Indicates that the driver supports the FillRect, BlitRect
4078             or BlitTransRect functions in this mode.
4079
4080                         </para></listitem></varlistentry>
4081
4082                     <varlistentry>
4083                       <term><constant>DGA_PIXMAP_AVAILABLE</constant></term>
4084                       <listitem><para>
4085             Indicates that Xlib may be used on the framebuffer.
4086             This flag will usually be set unless the driver wishes
4087             to prohibit this for some reason.
4088
4089                         </para></listitem></varlistentry>
4090
4091                     <varlistentry>
4092                       <term><constant>DGA_INTERLACED
4093                           DGA_DOUBLESCAN</constant></term>
4094                       <listitem><para>
4095             Indicates that these are interlaced or double scan modes.
4096
4097                         </para></listitem></varlistentry>
4098                   </variablelist>
4099                 </para></listitem></varlistentry>
4100
4101           <varlistentry>
4102             <term><structfield>imageWidth
4103                 imageHeight</structfield></term>
4104             <listitem><para>
4105                     These are the dimensions of the linear framebuffer
4106                      accessible by the client.
4107
4108               </para></listitem></varlistentry>
4109
4110           <varlistentry>
4111             <term><structfield>pixmapWidth
4112                 pixmapHeight</structfield></term>
4113             <listitem><para>
4114                      These are the dimensions of the area of the
4115                      framebuffer accessible by the graphics accelerator.
4116
4117               </para></listitem></varlistentry>
4118
4119           <varlistentry>
4120             <term><structfield>bytesPerScanline</structfield></term>
4121             <listitem><para>
4122                       Pitch of the framebuffer in bytes.
4123
4124               </para></listitem></varlistentry>
4125
4126           <varlistentry>
4127             <term><structfield>byteOrder</structfield></term>
4128             <listitem><para>
4129                      Usually the same as
4130                      <structfield>pScrn-&gt;imageByteOrder</structfield>.
4131
4132               </para></listitem></varlistentry>
4133
4134           <varlistentry>
4135             <term><structfield>depth</structfield></term>
4136             <listitem><para>
4137                      The depth of the framebuffer in this mode.
4138
4139               </para></listitem></varlistentry>
4140
4141           <varlistentry>
4142             <term><structfield>bitsPerPixel</structfield></term>
4143             <listitem><para>
4144                       The number of bits per pixel in this mode.
4145
4146               </para></listitem></varlistentry>
4147
4148           <varlistentry>
4149             <term><structfield>red_mask</structfield></term>
4150             <term><structfield>green_mask</structfield></term>
4151             <term><structfield>blue_mask</structfield></term>
4152             <listitem><para>
4153                       The RGB masks for this mode, if applicable.
4154
4155               </para></listitem></varlistentry>
4156
4157           <varlistentry>
4158             <term><structfield>viewportWidth</structfield></term>
4159             <term><structfield>viewportHeight</structfield></term>
4160             <listitem><para>
4161                       Dimensions of the visible part of the framebuffer.
4162                       Usually <structfield>mode-&gt;HDisplay</structfield> and
4163                       <structfield>mode-&gt;VDisplay</structfield>.
4164
4165               </para></listitem></varlistentry>
4166
4167           <varlistentry>
4168             <term><structfield>xViewportStep
4169                 yViewportStep</structfield></term>
4170             <listitem><para>
4171                      The granularity of x and y viewport positions that
4172                      the driver supports in this mode.
4173
4174               </para></listitem></varlistentry>
4175
4176           <varlistentry>
4177             <term><structfield>maxViewportX
4178                 maxViewportY</structfield></term>
4179             <listitem><para>
4180                       The maximum viewport position supported by the
4181                        driver in this mode.
4182               </para></listitem></varlistentry>
4183
4184           <varlistentry>
4185             <term><structfield>viewportFlags</structfield></term>
4186             <listitem><para>
4187                      The following may be OR'd together:
4188
4189                 <variablelist>
4190                   <varlistentry>
4191                     <term><constant>DGA_FLIP_IMMEDIATE</constant></term>
4192                     <listitem><para>
4193                 The driver supports immediate viewport changes.
4194                       </para></listitem></varlistentry>
4195
4196                   <varlistentry>
4197                     <term><constant>DGA_FLIP_RETRACE</constant></term>
4198
4199                     <listitem><para>
4200                 The driver supports viewport changes at retrace.
4201                       </para></listitem></varlistentry>
4202                   </variablelist>
4203               </para></listitem></varlistentry>
4204
4205           <varlistentry>
4206             <term><structfield>offset</structfield></term>
4207             <listitem><para>
4208                 The offset into the linear framebuffer that corresponds to
4209                 pixel (0,0) for this mode.
4210               </para></listitem></varlistentry>
4211
4212           <varlistentry>
4213             <term><structfield>address</structfield></term>
4214             <listitem><para>
4215                 The virtual address of the framebuffer as mapped by the driver.
4216                 This is needed when DGA_PIXMAP_AVAILABLE is set.
4217               </para></listitem></varlistentry>
4218
4219         </variablelist>
4220
4221         <programlisting>
4222 /** The DGAFunctionRec **/
4223
4224 typedef struct {
4225   Bool (*OpenFramebuffer)(
4226        ScrnInfoPtr pScrn,
4227        char **name,
4228        unsigned char **mem,
4229        int *size,
4230        int *offset,
4231        int *extra
4232   );
4233   void (*CloseFramebuffer)(ScrnInfoPtr pScrn);
4234   Bool (*SetMode)(ScrnInfoPtr pScrn, DGAModePtr pMode);
4235   void (*SetViewport)(ScrnInfoPtr pScrn, int x, int y, int flags);
4236   int  (*GetViewport)(ScrnInfoPtr pScrn);
4237   void (*Sync)(ScrnInfoPtr);
4238   void (*FillRect)(
4239        ScrnInfoPtr pScrn,
4240        int x, int y, int w, int h,
4241        unsigned long color
4242   );
4243   void (*BlitRect)(
4244        ScrnInfoPtr pScrn,
4245        int srcx, int srcy,
4246        int w, int h,
4247        int dstx, int dsty
4248   );
4249   void (*BlitTransRect)(
4250        ScrnInfoPtr pScrn,
4251        int srcx, int srcy,
4252        int w, int h,
4253        int dstx, int dsty,
4254        unsigned long color
4255   );
4256 } DGAFunctionRec, *DGAFunctionPtr;
4257         </programlisting>
4258
4259
4260         <blockquote><para>
4261             <programlisting>
4262     Bool OpenFramebuffer (pScrn, name, mem, size, offset, extra);
4263             </programlisting>
4264             <blockquote><para>
4265       <function>OpenFramebuffer()</function> should pass the client everything
4266       it needs to know to be able to open the framebuffer.  These
4267       parameters are OS specific and their meanings are to be interpreted
4268       by an OS specific client library.
4269
4270                 <variablelist>
4271                   <varlistentry>
4272                     <term><parameter>name</parameter></term>
4273                     <listitem><para>
4274               The name of the device to open or <constant>NULL</constant> if
4275               there is no special device to open.  A <constant>NULL</constant>
4276               name tells the client that it should open whatever device
4277               one would usually open to access physical memory.
4278                       </para></listitem></varlistentry>
4279
4280                   <varlistentry>
4281                     <term><parameter>mem</parameter></term>
4282                     <listitem><para>
4283               The physical address of the start of the framebuffer.
4284                       </para></listitem></varlistentry>
4285
4286                   <varlistentry>
4287                     <term><parameter>size</parameter></term>
4288                     <listitem><para>
4289               The size of the framebuffer in bytes.
4290                       </para></listitem></varlistentry>
4291
4292                   <varlistentry>
4293                     <term><parameter>offset</parameter></term>
4294                     <listitem><para>
4295               Any offset into the device, if applicable.
4296                       </para></listitem></varlistentry>
4297
4298                   <varlistentry>
4299                     <term><parameter>flags</parameter></term>
4300                     <listitem><para>
4301               Any additional information that the client may need.
4302               Currently, only the <constant>DGA_NEED_ROOT</constant> flag is
4303               defined.
4304                       </para></listitem></varlistentry>
4305
4306                 </variablelist>
4307               </para></blockquote>
4308           </para></blockquote>
4309
4310         <blockquote><para>
4311             <programlisting>
4312     void CloseFramebuffer (pScrn);
4313             </programlisting>
4314             <blockquote><para>
4315       <function>CloseFramebuffer()</function> merely informs the driver (if it
4316       even cares) that client no longer needs to access the framebuffer
4317       directly.  This function is optional.
4318               </para>
4319
4320             </blockquote></para></blockquote>
4321
4322         <blockquote><para>
4323             <programlisting>
4324     Bool SetMode (pScrn, pMode);
4325             </programlisting>
4326             <blockquote><para>
4327       <function>SetMode()</function> tells the driver to initialize the mode
4328       passed to it.  If <parameter>pMode</parameter> is <constant>NULL</constant>,
4329       then the driver should restore the original pre-DGA mode.
4330               </para>
4331
4332             </blockquote></para></blockquote>
4333
4334         <blockquote><para>
4335             <programlisting>
4336     void SetViewport (pScrn, x, y, flags);
4337             </programlisting>
4338             <blockquote><para>
4339       <function>SetViewport()</function> tells the driver to make the upper
4340       left-hand corner of the visible screen correspond to coordinate
4341       <literal remap="tt">(x,y)</literal> on the framebuffer.  <parameter>flags</parameter>
4342       currently defined are:
4343
4344                 <variablelist>
4345                   <varlistentry>
4346                     <term><constant>DGA_FLIP_IMMEDIATE</constant></term>
4347                     <listitem><para>
4348             The viewport change should occur immediately.
4349                       </para></listitem></varlistentry>
4350
4351                   <varlistentry>
4352                     <term><constant>DGA_FLIP_RETRACE</constant></term>
4353                     <listitem><para>
4354             The viewport change should occur at the
4355             vertical retrace, but this function should
4356             return sooner if possible.
4357                         </para></listitem></varlistentry>
4358                 </variablelist>
4359               </para>
4360
4361               <para>
4362       The <literal remap="tt">(x,y)</literal> locations will be passed as the client
4363       specified them, however, the driver is expected to round these
4364       locations down to the next supported location as specified by the
4365       <structfield>xViewportStep</structfield> and <structfield>yViewportStep</structfield>
4366       for the current mode.
4367               </para>
4368             </blockquote></para></blockquote>
4369
4370         <blockquote><para>
4371             <programlisting>
4372     int GetViewport (pScrn);
4373             </programlisting>
4374             <blockquote><para>
4375       <function>GetViewport()</function> gets the current page flip status.
4376       Set bits in the returned int correspond to viewport change requests
4377       still pending.  For instance, set bit zero if the last SetViewport
4378       request is still pending, bit one if the one before that is still
4379       pending, etc.
4380               </para>
4381
4382             </blockquote></para></blockquote>
4383
4384         <blockquote><para>
4385             <programlisting>
4386     void Sync (pScrn);
4387             </programlisting>
4388             <blockquote><para>
4389       This function should ensure that any graphics accelerator operations
4390       have finished.  This function should not return until the graphics
4391       accelerator is idle.
4392               </para>
4393
4394             </blockquote></para></blockquote>
4395
4396         <blockquote><para>
4397             <programlisting>
4398     void FillRect (pScrn, x, y, w, h, color);
4399             </programlisting>
4400             <blockquote><para>
4401       This optional function should fill a rectangle
4402       <parameter>w&nbsp;&times;&nbsp;h</parameter> located at
4403       <parameter>(x,y)</parameter> in the given color.
4404               </para>
4405
4406             </blockquote></para></blockquote>
4407
4408         <blockquote><para>
4409             <programlisting>
4410     void BlitRect (pScrn, srcx, srcy, w, h, dstx, dsty);
4411             </programlisting>
4412             <blockquote><para>
4413       This optional function should copy an area
4414       <parameter>w&nbsp;&times;&nbsp;h</parameter> located at
4415       <parameter>(srcx,srcy)</parameter> to location <parameter>(dstx,dsty)</parameter>.
4416       This function will need to handle copy directions as appropriate.
4417               </para>
4418
4419             </blockquote></para></blockquote>
4420
4421         <blockquote><para>
4422             <programlisting>
4423     void BlitTransRect (pScrn, srcx, srcy, w, h, dstx, dsty, color);
4424             </programlisting>
4425             <blockquote><para>
4426       This optional function is the same as BlitRect except that pixels
4427       in the source corresponding to the color key <parameter>color</parameter>
4428       should be skipped.
4429               </para>
4430
4431             </blockquote></para></blockquote>
4432     </para></blockquote>
4433
4434   </sect1>
4435
4436   <sect1>
4437     <title>The XFree86 X Video Extension (Xv) Device Dependent Layer</title>
4438
4439     <para>
4440 XFree86 offers the X Video Extension which allows clients to treat video
4441 as any another primitive and <quote>Put</quote> video into drawables.  By default,
4442 the extension reports no video adaptors as being available since the
4443 DDX layer has not been initialized.  The driver can initialize the DDX
4444 layer by filling out one or more <literal remap="tt">XF86VideoAdaptorRecs</literal>
4445 as described later in this document and passing a list of
4446 <literal remap="tt">XF86VideoAdaptorPtr</literal> pointers to the following function:
4447
4448       <programlisting>
4449     Bool xf86XVScreenInit(ScreenPtr pScreen,
4450                           XF86VideoAdaptorPtr *adaptPtrs,
4451                           int num);
4452       </programlisting>
4453     </para>
4454
4455     <para>
4456 After doing this, the extension will report video adaptors as being
4457 available, providing the data in their respective
4458 <literal remap="tt">XF86VideoAdaptorRecs</literal> was valid.
4459 <function>xf86XVScreenInit()</function> <emphasis>copies</emphasis> data from the structure
4460 passed to it so the driver may free it after the initialization.  At
4461 the moment, the DDX only supports rendering into Window drawables.
4462 Pixmap rendering will be supported after a sufficient survey of suitable
4463 hardware is completed.
4464     </para>
4465
4466     <para>
4467 The <structname>XF86VideoAdaptorRec</structname>:
4468
4469       <programlisting>
4470 typedef struct {
4471         unsigned int type;
4472         int flags;
4473         char *name;
4474         int nEncodings;
4475         XF86VideoEncodingPtr pEncodings;
4476         int nFormats;
4477         XF86VideoFormatPtr pFormats;
4478         int nPorts;
4479         DevUnion *pPortPrivates;
4480         int nAttributes;
4481         XF86AttributePtr pAttributes;
4482         int nImages;
4483         XF86ImagePtr pImages;
4484         PutVideoFuncPtr PutVideo;
4485         PutStillFuncPtr PutStill;
4486         GetVideoFuncPtr GetVideo;
4487         GetStillFuncPtr GetStill;
4488         StopVideoFuncPtr StopVideo;
4489         SetPortAttributeFuncPtr SetPortAttribute;
4490         GetPortAttributeFuncPtr GetPortAttribute;
4491         QueryBestSizeFuncPtr QueryBestSize;
4492         PutImageFuncPtr PutImage;
4493         QueryImageAttributesFuncPtr QueryImageAttributes;
4494 } XF86VideoAdaptorRec, *XF86VideoAdaptorPtr;
4495       </programlisting></para>
4496
4497     <para>
4498 Each adaptor will have its own XF86VideoAdaptorRec.  The fields are
4499 as follows:
4500
4501       <variablelist>
4502         <varlistentry>
4503           <term><structfield>type</structfield></term>
4504           <listitem><para>
4505         This can be any of the following flags OR'd together.
4506
4507               <variablelist>
4508                 <varlistentry>
4509                   <term><constant>XvInputMask</constant>
4510                     <constant>XvOutputMask</constant></term>
4511                   <listitem><para>
4512             These refer to the target drawable and are similar to a Window's
4513             class. <literal remap="tt">XvInputMask</literal> indicates that the adaptor
4514             can put video into a drawable.  <literal remap="tt">XvOutputMask</literal>
4515             indicates that the adaptor can get video from a drawable.
4516                     </para></listitem></varlistentry>
4517
4518                 <varlistentry>
4519                   <term><constant>XvVideoMask</constant>
4520                     <constant>XvStillMask</constant>
4521                     <constant>XvImageMask</constant></term>
4522                   <listitem><para>
4523             These indicate that the adaptor supports video, still or
4524             image primitives respectively.
4525                     </para></listitem></varlistentry>
4526
4527                 <varlistentry>
4528                   <term><constant>XvWindowMask</constant>
4529                     <constant>XvPixmapMask</constant></term>
4530                   <listitem><para>
4531             These indicate the types of drawables the adaptor is capable
4532             of rendering into.  At the moment, Pixmap rendering is not
4533             supported and the <constant>XvPixmapMask</constant> flag is ignored.
4534                     </para></listitem></varlistentry>
4535               </variablelist>
4536
4537             </para></listitem></varlistentry>
4538
4539         <varlistentry>
4540           <term><structfield>flags</structfield></term>
4541           <listitem><para>
4542         Currently, the following flags are defined:
4543
4544               <variablelist>
4545                 <varlistentry>
4546                   <term><constant>VIDEO_NO_CLIPPING</constant></term>
4547                   <listitem><para>
4548            This indicates that the video adaptor does not support
4549            clipping.  The driver will never receive <quote>Put</quote> requests
4550            where less than the entire area determined by
4551            <parameter>drw_x</parameter>, <parameter>drw_y</parameter>,
4552            <parameter>drw_w</parameter> and <parameter>drw_h</parameter> is visible.
4553            This flag does not apply to <quote>Get</quote> requests.  Hardware
4554            that is incapable of clipping <quote>Gets</quote> may punt or get
4555            the extents of the clipping region passed to it.
4556                     </para></listitem>
4557
4558                 </varlistentry>
4559
4560                 <varlistentry>
4561                   <term><constant>VIDEO_INVERT_CLIPLIST</constant></term>
4562                   <listitem><para>
4563            This indicates that the video driver requires the clip
4564            list to contain the regions which are obscured rather
4565            than the regions which are are visible.
4566                     </para></listitem>
4567
4568                 </varlistentry>
4569
4570                 <varlistentry>
4571                   <term><constant>VIDEO_OVERLAID_STILLS</constant></term>
4572                   <listitem><para>
4573            Implementing PutStill for hardware that does video as an
4574            overlay can be awkward since it's unclear how long to leave
4575            the video up for.  When this flag is set, StopVideo will be
4576            called whenever the destination gets clipped or moved so that
4577            the still can be left up until then.
4578                     </para></listitem>
4579
4580                 </varlistentry>
4581
4582                 <varlistentry>
4583                   <term><constant>VIDEO_OVERLAID_IMAGES</constant></term>
4584                   <listitem><para>
4585            Same as <constant>VIDEO_OVERLAID_STILLS</constant> but for images.
4586                     </para></listitem>
4587                 </varlistentry>
4588
4589                 <varlistentry>
4590                   <term><constant>VIDEO_CLIP_TO_VIEWPORT</constant></term>
4591                   <listitem><para>
4592             Indicates that the clip region passed to the driver functions
4593             should be clipped to the visible portion of the screen in the
4594             case where the viewport is smaller than the virtual desktop.
4595                     </para></listitem></varlistentry>
4596
4597               </variablelist>
4598             </para></listitem></varlistentry>
4599
4600         <varlistentry>
4601           <term><structfield>name</structfield></term>
4602           <listitem><para>
4603         The name of the adaptor.
4604             </para></listitem></varlistentry>
4605
4606
4607         <varlistentry>
4608           <term><structfield>nEncodings</structfield>
4609             <structfield>pEncodings</structfield></term>
4610           <listitem><para>
4611         The number of encodings the adaptor is capable of and pointer
4612         to the <structname>XF86VideoEncodingRec</structname> array.  The
4613         <structname>XF86VideoEncodingRec</structname> is described later on.
4614         For drivers that only support XvImages there should be an encoding
4615         named "XV_IMAGE" and the width and height should specify
4616         the maximum size source image supported.
4617           </para></listitem></varlistentry>
4618
4619
4620         <varlistentry>
4621           <term><structfield>nFormats</structfield>
4622               <structfield>pFormats</structfield></term>
4623           <listitem><para>
4624         The number of formats the adaptor is capable of and pointer to
4625         the <structname>XF86VideoFormatRec</structname> array.  The
4626         <structname>XF86VideoFormatRec</structname> is described later on.
4627             </para></listitem></varlistentry>
4628
4629
4630         <varlistentry>
4631           <term><structfield>nPorts</structfield>
4632             <structfield>pPortPrivates</structfield></term>
4633           <listitem><para>
4634         The number of ports is the number of separate data streams which
4635         the adaptor can handle simultaneously.  If you have more than
4636         one port, the adaptor is expected to be able to render into more
4637         than one window at a time.  <structfield>pPortPrivates</structfield> is
4638         an array of pointers or ints - one for each port.  A port's
4639         private data will be passed to the driver any time the port is
4640         requested to do something like put the video or stop the video.
4641         In the case where there may be many ports, this enables the
4642         driver to know which port the request is intended for.  Most
4643         commonly, this will contain a pointer to the data structure
4644         containing information about the port.  In Xv, all ports on
4645         a particular adaptor are expected to be identical in their
4646         functionality.
4647             </para></listitem></varlistentry>
4648
4649
4650         <varlistentry>
4651           <term><structfield>nAttributes</structfield>
4652             <structfield>pAttributes</structfield></term>
4653           <listitem><para>
4654         The number of attributes recognized by the adaptor and a pointer to
4655         the array of <structname>XF86AttributeRecs</structname>.  The
4656         <structname>XF86AttributeRec</structname> is described later on.
4657             </para></listitem></varlistentry>
4658
4659
4660         <varlistentry>
4661           <term><structfield>nImages</structfield>
4662             <structfield>pImages</structfield></term>
4663           <listitem><para>
4664         The number of <structname>XF86ImageRecs</structname> supported by the adaptor
4665         and a pointer to the array of <structname>XF86ImageRecs</structname>. The
4666         <structname>XF86ImageRec</structname> is described later on.
4667             </para></listitem></varlistentry>
4668
4669
4670         <varlistentry>
4671           <term><structfield>
4672      PutVideo PutStill GetVideo GetStill StopVideo
4673      SetPortAttribute GetPortAttribute QueryBestSize PutImage
4674      QueryImageAttributes
4675             </structfield></term>
4676           <listitem><para>
4677         These functions define the DDX-&gt;driver interface.  In each
4678         case, the pointer <parameter>data</parameter> is passed to the driver.
4679         This is the port private for that port as described above.  All
4680         fields are required except under the following conditions:
4681
4682               <orderedlist>
4683                 <listitem><para>
4684              <structfield>PutVideo</structfield>, <structfield>PutStill</structfield> and
4685              the image routines <structfield>PutImage</structfield> and
4686              <structfield>QueryImageAttributes</structfield> are not required when the
4687              adaptor type does not contain <constant>XvInputMask</constant>.
4688                   </para></listitem>
4689
4690                 <listitem><para>
4691              <structfield>GetVideo</structfield> and <structfield>GetStill</structfield>
4692              are not required when the adaptor type does not contain
4693              <constant>XvOutputMask</constant>.
4694                   </para></listitem>
4695
4696                 <listitem><para>
4697              <structfield>GetVideo</structfield> and <structfield>PutVideo</structfield>
4698              are not required when the adaptor type does not contain
4699              <constant>XvVideoMask</constant>.
4700                   </para></listitem>
4701
4702                 <listitem><para>
4703              <structfield>GetStill</structfield> and <structfield>PutStill</structfield>
4704              are not required when the adaptor type does not contain
4705              <constant>XvStillMask</constant>.
4706                   </para></listitem>
4707
4708                 <listitem><para>
4709              <structfield>PutImage</structfield> and <structfield>QueryImageAttributes</structfield>
4710              are not required when the adaptor type does not contain
4711              <constant>XvImageMask</constant>.
4712                   </para></listitem>
4713
4714               </orderedlist>
4715
4716             </para>
4717
4718             <para>
4719         With the exception of <structfield>QueryImageAttributes</structfield>, these
4720         functions should return <constant>Success</constant> if the operation was
4721         completed successfully.  They can return <constant>XvBadAlloc</constant>
4722         otherwise. <structfield>QueryImageAttributes</structfield> returns the size
4723         of the XvImage queried.
4724             </para>
4725
4726             <para>
4727         If the <constant>VIDEO_NO_CLIPPING</constant>
4728         flag is set, the <literal remap="tt">clipBoxes</literal> may be ignored by
4729         the driver.  <literal remap="tt">ClipBoxes</literal> is an <literal remap="tt">X-Y</literal>
4730         banded region identical to those used throughout the server.
4731         The clipBoxes represent the visible portions of the area determined
4732         by <literal remap="tt">drw_x</literal>, <literal remap="tt">drw_y</literal>,
4733         <literal remap="tt">drw_w</literal> and <literal remap="tt">drw_h</literal> in the Get/Put
4734         function.  The boxes are in screen coordinates, are guaranteed
4735         not to overlap and an empty region will never be passed.
4736         If the driver has specified <constant>VIDEO_INVERT_CLIPLIST</constant>,
4737         <literal remap="tt">clipBoxes</literal> will indicate the areas of the primitive
4738         which are obscured rather than the areas visible.
4739
4740             </para></listitem></varlistentry>
4741       </variablelist>
4742
4743       <blockquote><para>
4744           <programlisting>
4745     typedef  int (* PutVideoFuncPtr)( ScrnInfoPtr pScrn,
4746                    short vid_x, short vid_y, short drw_x, short drw_y,
4747                    short vid_w, short vid_h, short drw_w, short drw_h,
4748                    RegionPtr clipBoxes, pointer data );
4749           </programlisting>
4750               <blockquote><para>
4751           This indicates that the driver should take a subsection
4752           <parameter>vid_w</parameter> by <parameter>vid_h</parameter> at location
4753           <parameter>(vid_x,vid_y)</parameter> from the video stream and direct
4754           it into the rectangle <parameter>drw_w</parameter> by <parameter>drw_h</parameter>
4755           at location <parameter>(drw_x,drw_y)</parameter> on the screen, scaling as
4756           necessary.  Due to the large variations in capabilities of
4757           the various hardware expected to be used with this extension,
4758           it is not expected that all hardware will be able to do this
4759           exactly as described.  In that case the driver should just do
4760           <quote>the best it can,</quote> scaling as closely to the target rectangle
4761           as it can without rendering outside of it.  In the worst case,
4762           the driver can opt to just not turn on the video.
4763               </para>
4764
4765             </blockquote></para></blockquote>
4766
4767           <blockquote><para>
4768               <programlisting>
4769     typedef  int (* PutStillFuncPtr)( ScrnInfoPtr pScrn,
4770                    short vid_x, short vid_y, short drw_x, short drw_y,
4771                    short vid_w, short vid_h, short drw_w, short drw_h,
4772                    RegionPtr clipBoxes, pointer data );
4773               </programlisting>
4774               <blockquote><para>
4775           This is same as <structfield>PutVideo</structfield> except that the driver
4776           should place only one frame from the stream on the screen.
4777               </para>
4778
4779             </blockquote></para></blockquote>
4780
4781           <blockquote><para>
4782               <programlisting>
4783     typedef int (* GetVideoFuncPtr)( ScrnInfoPtr pScrn,
4784                   short vid_x, short vid_y, short drw_x, short drw_y,
4785                   short vid_w, short vid_h, short drw_w, short drw_h,
4786                   RegionPtr clipBoxes, pointer data );
4787               </programlisting>
4788               <blockquote><para>
4789           This is same as <structfield>PutVideo</structfield> except that the driver
4790           gets video from the screen and outputs it.  The driver should
4791           do the best it can to get the requested dimensions correct
4792           without reading from an area larger than requested.
4793               </para>
4794
4795             </blockquote></para></blockquote>
4796
4797           <blockquote><para>
4798               <programlisting>
4799     typedef int (* GetStillFuncPtr)( ScrnInfoPtr pScrn,
4800                   short vid_x, short vid_y, short drw_x, short drw_y,
4801                   short vid_w, short vid_h, short drw_w, short drw_h,
4802                   RegionPtr clipBoxes, pointer data );
4803               </programlisting>
4804               <blockquote><para>
4805           This is the same as <literal remap="tt">GetVideo</literal> except that the
4806           driver should place only one frame from the screen into the
4807           output stream.
4808               </para>
4809
4810             </blockquote></para></blockquote>
4811
4812           <blockquote><para>
4813               <programlisting>
4814     typedef void (* StopVideoFuncPtr)(ScrnInfoPtr pScrn,
4815                                       pointer data, Bool cleanup);
4816               </programlisting>
4817               <blockquote><para>
4818           This indicates the driver should stop displaying the video.
4819           This is used to stop both input and output video.  The
4820           <parameter>cleanup</parameter> field indicates that the video is
4821           being stopped because the client requested it to stop or
4822           because the server is exiting the current VT.  In that case
4823           the driver should deallocate any offscreen memory areas (if
4824           there are any) being used to put the video to the screen.  If
4825           <parameter>cleanup</parameter> is not set, the video is being stopped
4826           temporarily due to clipping or moving of the window, etc...
4827           and video will likely be restarted soon so the driver should
4828           not deallocate any offscreen areas associated with that port.
4829               </para>
4830
4831             </blockquote></para></blockquote>
4832           <blockquote><para>
4833               <programlisting>
4834     typedef int (* SetPortAttributeFuncPtr)(ScrnInfoPtr pScrn,
4835                                 Atom attribute,INT32 value, pointer data);
4836               </programlisting>
4837
4838               <programlisting>
4839     typedef int (* GetPortAttributeFuncPtr)(ScrnInfoPtr pScrn,
4840                                 Atom attribute,INT32 *value, pointer data);
4841               </programlisting>
4842               <blockquote><para>
4843           A port may have particular attributes such as hue,
4844           saturation, brightness or contrast.  Xv clients set and
4845           get these attribute values by sending attribute strings
4846           (Atoms) to the server.  Such requests end up at these
4847           driver functions.  It is recommended that the driver provide
4848           at least the following attributes mentioned in the Xv client
4849           library docs:
4850                 <literallayout><constant>
4851                 XV_ENCODING
4852                 XV_HUE
4853                 XV_SATURATION
4854                 XV_BRIGHTNESS
4855                 XV_CONTRAST
4856                   </constant></literallayout>
4857           but the driver may recognize as many atoms as it wishes.  If
4858           a requested attribute is unknown by the driver it should return
4859           <constant>BadMatch</constant>.  <constant>XV_ENCODING</constant> is the
4860           attribute intended to let the client specify which video
4861           encoding the particular port should be using (see the description
4862           of <structname>XF86VideoEncodingRec</structname> below).  If the
4863           requested encoding is unsupported, the driver should return
4864           <constant>XvBadEncoding</constant>.  If the value lies outside the
4865           advertised range <constant>BadValue</constant> may be returned.
4866           <constant>Success</constant> should be returned otherwise.
4867               </para>
4868
4869             </blockquote></para></blockquote>
4870
4871           <blockquote><para>
4872             <programlisting>
4873     typedef void (* QueryBestSizeFuncPtr)(ScrnInfoPtr pScrn,
4874                    Bool motion, short vid_w, short vid_h,
4875                    short drw_w, short drw_h,
4876                    unsigned int *p_w, unsigned int *p_h, pointer data);
4877             </programlisting>
4878             <blockquote><para>
4879            <function>QueryBestSize</function> provides the client with a way
4880            to query what the destination dimensions would end up being
4881            if they were to request that an area
4882            <parameter>vid_w</parameter> by <parameter>vid_h</parameter> from the video
4883            stream be scaled to rectangle of
4884            <parameter>drw_w</parameter> by <parameter>drw_h</parameter> on the screen.
4885            Since it is not expected that all hardware will be able to
4886            get the target dimensions exactly, it is important that the
4887            driver provide this function.
4888               </para>
4889
4890             </blockquote></para></blockquote>
4891
4892         <blockquote><para>
4893             <programlisting>
4894     typedef  int (* PutImageFuncPtr)( ScrnInfoPtr pScrn,
4895                    short src_x, short src_y, short drw_x, short drw_y,
4896                    short src_w, short src_h, short drw_w, short drw_h,
4897                    int image, char *buf, short width, short height,
4898                    Bool sync, RegionPtr clipBoxes, pointer data );
4899               </programlisting>
4900               <blockquote><para>
4901           This is similar to <structfield>PutStill</structfield> except that the
4902           source of the video is not a port but the data stored in a system
4903           memory buffer at <parameter>buf</parameter>.  The data is in the format
4904           indicated by the <parameter>image</parameter> descriptor and represents a
4905           source of size <parameter>width</parameter> by <parameter>height</parameter>.
4906           If <parameter>sync</parameter> is TRUE the driver should not return
4907           from this function until it is through reading the data
4908           from <parameter>buf</parameter>.  Returning when <parameter>sync</parameter>
4909           is TRUE indicates that it is safe for the data at <parameter>buf</parameter>
4910           to be replaced, freed, or modified.
4911               </para>
4912
4913             </blockquote></para></blockquote>
4914
4915         <blockquote><para>
4916             <programlisting>
4917     typedef  int (* QueryImageAttributesFuncPtr)( ScrnInfoPtr pScrn,
4918                                 int image, short *width, short *height,
4919                                 int *pitches, int *offsets);
4920             </programlisting>
4921             <blockquote><para>
4922           This function is called to let the driver specify how data for
4923           a particular <parameter>image</parameter> of size <parameter>width</parameter>
4924           by <parameter>height</parameter> should be stored.  Sometimes only
4925           the size and corrected width and height are needed.  In that
4926           case <parameter>pitches</parameter> and <parameter>offsets</parameter> are
4927           NULL.  The size of the memory required for the image is returned
4928           by this function.  The <parameter>width</parameter> and
4929           <parameter>height</parameter> of the requested image can be altered by
4930           the driver to reflect format limitations (such as component
4931           sampling periods that are larger than one).  If
4932           <parameter>pitches</parameter> and <parameter>offsets</parameter> are not NULL,
4933           these will be arrays with as many elements in them as there
4934           are planes in the <parameter>image</parameter> format.  The driver
4935           should specify the pitch (in bytes) of each scanline in the
4936           particular plane as well as the offset to that plane (in bytes)
4937           from the beginning of the image.
4938               </para>
4939
4940           </blockquote></para></blockquote>
4941     </para>
4942
4943     <para>
4944 The XF86VideoEncodingRec:
4945
4946       <blockquote><para>
4947           <programlisting>
4948 typedef struct {
4949         int id;
4950         char *name;
4951         unsigned short width, height;
4952         XvRationalRec rate;
4953 } XF86VideoEncodingRec, *XF86VideoEncodingPtr;
4954
4955           </programlisting>
4956           <blockquote><para>
4957    The <structname>XF86VideoEncodingRec</structname> specifies what encodings
4958    the adaptor can support.  Most of this data is just informational
4959    and for the client's benefit, and is what will be reported by
4960    <function>XvQueryEncodings</function>.  The <parameter>id</parameter> field is
4961    expected to be a unique identifier to allow the client to request a
4962    certain encoding via the <constant>XV_ENCODING</constant> attribute string.
4963
4964             </para>
4965           </blockquote></para></blockquote>
4966     </para>
4967
4968     <para>
4969 The XF86VideoFormatRec:
4970
4971       <blockquote><para>
4972           <programlisting>
4973 typedef struct {
4974         char  depth;
4975         short class;
4976 } XF86VideoFormatRec, *XF86VideoFormatPtr;
4977
4978           </programlisting>
4979           <blockquote><para>
4980     This specifies what visuals the video is viewable in.
4981     <parameter>depth</parameter> is the depth of the visual (not bpp).
4982     <parameter>class</parameter> is the visual class such as
4983     <constant>TrueColor</constant>, <constant>DirectColor</constant> or
4984     <constant>PseudoColor</constant>.  Initialization of an adaptor will fail
4985     if none of the visuals on that screen are supported.
4986             </para>
4987
4988           </blockquote></para></blockquote>
4989     </para>
4990
4991     <para>
4992 The XF86AttributeRec:
4993
4994       <blockquote><para>
4995           <programlisting>
4996 typedef struct {
4997         int   flags;
4998         int   min_value;
4999         int   max_value;
5000         char  *name;
5001 } XF86AttributeListRec, *XF86AttributeListPtr;
5002
5003           </programlisting>
5004           <blockquote><para>
5005    Each adaptor may have an array of these advertising the attributes
5006    for its ports.  Currently defined flags are <literal remap="tt">XvGettable</literal>
5007    and <literal remap="tt">XvSettable</literal> which may be OR'd together indicating that
5008    attribute is <quote>gettable</quote> or <quote>settable</quote> by the client.  The
5009    <literal remap="tt">min</literal> and <literal remap="tt">max</literal> field specify the valid range
5010    for the value.  <literal remap="tt">Name</literal> is a text string describing the
5011    attribute by name.
5012             </para>
5013
5014           </blockquote></para></blockquote>
5015
5016     </para>
5017
5018     <para>
5019 The XF86ImageRec:
5020
5021         <blockquote><para>
5022             <programlisting>
5023 typedef struct {
5024         int id;
5025         int type;
5026         int byte_order;
5027         char guid[16];
5028         int bits_per_pixel;
5029         int format;
5030         int num_planes;
5031
5032         /* for RGB formats */
5033         int depth;
5034         unsigned int red_mask;
5035         unsigned int green_mask;
5036         unsigned int blue_mask;
5037
5038         /* for YUV formats */
5039         unsigned int y_sample_bits;
5040         unsigned int u_sample_bits;
5041         unsigned int v_sample_bits;
5042         unsigned int horz_y_period;
5043         unsigned int horz_u_period;
5044         unsigned int horz_v_period;
5045         unsigned int vert_y_period;
5046         unsigned int vert_u_period;
5047         unsigned int vert_v_period;
5048         char component_order[32];
5049         int scanline_order;
5050 } XF86ImageRec, *XF86ImagePtr;
5051
5052             </programlisting>
5053             <blockquote><para>
5054    XF86ImageRec describes how video source data is laid out in memory.
5055    The fields are as follows:
5056
5057                 <variablelist>
5058                   <varlistentry>
5059                     <term><structfield>id</structfield></term>
5060                     <listitem><para>
5061         This is a unique descriptor for the format.  It is often good to
5062         set this value to the FOURCC for the format when applicable.
5063                       </para></listitem></varlistentry>
5064
5065                   <varlistentry>
5066                     <term><structfield>type</structfield></term>
5067                     <listitem><para>
5068         This is <constant>XvRGB</constant> or <constant>XvYUV</constant>.
5069                       </para></listitem></varlistentry>
5070
5071                   <varlistentry>
5072                     <term><structfield>byte_order</structfield></term>
5073                     <listitem><para>
5074         This is <constant>LSBFirst</constant> or <constant>MSBFirst</constant>.
5075                       </para></listitem></varlistentry>
5076
5077                   <varlistentry>
5078                     <term><structfield>guid</structfield></term>
5079                     <listitem><para>
5080         This is the Globally Unique IDentifier for the format.  When
5081         not applicable, all characters should be NULL.
5082                       </para></listitem></varlistentry>
5083
5084                   <varlistentry>
5085                     <term><structfield>bits_per_pixel</structfield></term>
5086                     <listitem><para>
5087         The number of bits taken up (but not necessarily used) by each
5088         pixel.  Note that for some planar formats which have fractional
5089         bits per pixel (such as IF09) this number may be rounded _down_.
5090                       </para></listitem></varlistentry>
5091
5092                   <varlistentry>
5093                     <term><structfield>format</structfield></term>
5094                     <listitem><para>
5095         This is <constant>XvPlanar</constant> or <constant>XvPacked</constant>.
5096                       </para></listitem></varlistentry>
5097
5098                   <varlistentry>
5099                     <term><structfield>num_planes</structfield></term>
5100                     <listitem><para>
5101         The number of planes in planar formats.  This should be set to
5102         one for packed formats.
5103                       </para></listitem></varlistentry>
5104
5105                   <varlistentry>
5106                     <term><structfield>depth</structfield></term>
5107                     <listitem><para>
5108         The significant bits per pixel in RGB formats (analgous to the
5109         depth of a pixmap format).
5110                       </para></listitem></varlistentry>
5111
5112                   <varlistentry>
5113                     <term><structfield>red_mask</structfield></term>
5114                     <term><structfield>green_mask</structfield></term>
5115                     <term><structfield>blue_mask</structfield></term>
5116                     <listitem><para>
5117         The red, green and blue bitmasks for packed RGB formats.
5118                       </para></listitem></varlistentry>
5119
5120                   <varlistentry>
5121                     <term><structfield>y_sample_bits</structfield></term>
5122                     <term><structfield>u_sample_bits</structfield></term>
5123                     <term><structfield>v_sample_bits</structfield></term>
5124                     <listitem><para>
5125         The y, u and v sample sizes (in bits).
5126                       </para></listitem></varlistentry>
5127
5128                   <varlistentry>
5129                     <term><structfield>horz_y_period</structfield></term>
5130                     <term><structfield>horz_u_period</structfield></term>
5131                     <term><structfield>horz_v_period</structfield></term>
5132                     <listitem><para>
5133         The y, u and v sampling periods in the horizontal direction.
5134                       </para></listitem></varlistentry>
5135
5136                   <varlistentry>
5137                     <term><structfield>vert_y_period</structfield></term>
5138                     <term><structfield>vert_u_period</structfield></term>
5139                     <term><structfield>vert_v_period</structfield></term>
5140                     <listitem><para>
5141         The y, u and v sampling periods in the vertical direction.
5142                       </para></listitem></varlistentry>
5143
5144                   <varlistentry>
5145                     <term><structfield>component_order</structfield></term>
5146                     <listitem><para>
5147         Uppercase ascii characters representing the order that
5148         samples are stored within packed formats.  For planar formats
5149         this represents the ordering of the planes.  Unused characters
5150         in the 32 byte string should be set to NULL.
5151                       </para></listitem></varlistentry>
5152
5153                   <varlistentry>
5154                     <term><structfield>scanline_order</structfield></term>
5155                     <listitem><para>
5156         This is <constant>XvTopToBottom</constant> or <constant>XvBottomToTop</constant>.
5157                       </para></listitem></varlistentry>
5158
5159                   </variablelist>
5160             </para>
5161
5162             <para>
5163   Since some formats (particular some planar YUV formats) may not
5164 be completely defined by the parameters above, the guid, when
5165 available, should provide the most accurate description of the
5166 format.
5167             </para>
5168
5169           </blockquote></para></blockquote>
5170     </para>
5171   </sect1>
5172
5173   <sect1>
5174     <title>The Loader</title>
5175
5176     <para>
5177 This section describes the interfaces to the module loader.  The loader
5178 interfaces can be divided into two groups: those that are only available to
5179 the XFree86 common layer, and those that are also available to modules.
5180     </para>
5181
5182     <sect2>
5183       <title>Loader Overview</title>
5184
5185       <para>
5186 The loader is capable of loading modules in a range of object formats,
5187 and knowledge of these formats is built in to the loader.  Knowledge of
5188 new object formats can be added to the loader in a straightforward
5189 manner.  This makes it possible to provide OS-independent modules (for
5190 a given CPU architecture type).  In addition to this, the loader can
5191 load modules via the OS-provided <function>dlopen(3)</function> service where
5192 available.  Such modules are not platform independent, and the semantics
5193 of <function>dlopen()</function> on most systems results in significant
5194 limitations in the use of modules of this type.  Support for
5195 <function>dlopen()</function> modules in the loader is primarily for
5196 experimental and development purposes.
5197       </para>
5198
5199       <para>
5200 Symbols exported by the loader (on behalf of the core X server) to
5201 modules are determined at compile time.  Only those symbols explicitly
5202 exported are available to modules.  All external symbols of loaded
5203 modules are exported to other modules, and to the core X server.  The
5204 loader can be requested to check for unresolved symbols at any time,
5205 and the action to be taken for unresolved symbols can be controlled by
5206 the caller of the loader.  Typically the caller identifies which symbols
5207 can safely remain unresolved and which cannot.
5208       </para>
5209
5210       <para>
5211 NOTE:  Now that ISO-C allows pointers to functions and pointers to data to
5212 have different internal representations, some of the following interfaces
5213 will need to be revisited.
5214       </para>
5215     </sect2>
5216
5217     <sect2>
5218       <title>Semi-private Loader Interface</title>
5219
5220       <para>
5221 The following is the semi-private loader interface that is available to the
5222 XFree86 common layer.
5223       </para>
5224
5225       <blockquote><para>
5226           <programlisting>
5227     void LoaderInit(void);
5228           </programlisting>
5229           <blockquote><para>
5230     The <function>LoaderInit()</function> function initialises the loader,
5231     and it must be called once before calling any other loader functions.
5232     This function initialises the tables of exported symbols, and anything
5233     else that might need to be initialised.
5234             </para>
5235
5236           </blockquote></para></blockquote>
5237
5238       <blockquote><para>
5239           <programlisting>
5240     void LoaderSetPath(const char *path);
5241           </programlisting>
5242           <blockquote><para>
5243     The <function>LoaderSetPath()</function> function initialises a default
5244     module search path.  This must be called if calls to other functions
5245     are to be made without explicitly specifying a module search path.
5246     The search path <parameter>path</parameter> must be a string of one or more
5247     comma separated absolute paths.  Modules are expected to be located
5248     below these paths, possibly in subdirectories of these paths.
5249             </para>
5250
5251           </blockquote></para></blockquote>
5252
5253       <blockquote><para>
5254           <programlisting>
5255     pointer LoadModule(const char *module, const char *path,
5256                        const char **subdirlist, const char **patternlist,
5257                        pointer options, const XF86ModReqInfo * modreq,
5258                        int *errmaj, int *errmin);
5259           </programlisting>
5260           <blockquote><para>
5261     The <function>LoadModule()</function> function loads the module called
5262     <parameter>module</parameter>.  The return value is a module handle, and
5263     may be used in future calls to the loader that require a reference
5264     to a loaded module.  The module name <parameter>module</parameter> is
5265     normally the module's canonical name, which doesn't contain any
5266     directory path information, or any object/library file prefixes of
5267     suffixes.  Currently a full pathname and/or filename is also accepted.
5268     This might change.  The other parameters are:
5269
5270               <variablelist>
5271                 <varlistentry>
5272                   <term><parameter>path</parameter></term>
5273                   <listitem><para>
5274                   An optional comma-separated list of module search paths.
5275                   When <constant>NULL</constant>, the default search path is used.
5276                     </para></listitem></varlistentry>
5277
5278
5279                 <varlistentry>
5280                   <term><parameter>subdirlist</parameter></term>
5281                   <listitem><para>
5282                   An optional <constant>NULL</constant> terminated list of
5283                   subdirectories to search.  When <constant>NULL</constant>,
5284                   the default built-in list is used (refer to
5285                   <varname>stdSubdirs</varname> in <filename>loadmod.c</filename>).
5286                   The default list is also substituted for entries in
5287                   <parameter>subdirlist</parameter> with the value
5288                   <constant>DEFAULT_LIST</constant>.  This makes is possible
5289                   to augment the default list instead of replacing it.
5290                   Subdir elements must be relative, and must not contain
5291                   <literal remap="tt">".."</literal>.  If any violate this requirement,
5292                   the load fails.
5293                     </para></listitem></varlistentry>
5294
5295
5296                 <varlistentry>
5297                   <term><parameter>patternlist</parameter></term>
5298                   <listitem><para>
5299                   An optional <constant>NULL</constant> terminated list of
5300                   POSIX regular expressions used to connect module
5301                   filenames with canonical module names.  Each regex
5302                   should contain exactly one subexpression that corresponds
5303                   to the canonical module name.  When <constant>NULL</constant>,
5304                   the default built-in list is used (refer to
5305                   <varname>stdPatterns</varname> in
5306                   <filename>loadmod.c</filename>).  The default list is also
5307                   substituted for entries in <parameter>patternlist</parameter>
5308                   with the value <constant>DEFAULT_LIST</constant>.  This
5309                   makes it possible to augment the default list instead
5310                   of replacing it.
5311                     </para></listitem></varlistentry>
5312
5313
5314                 <varlistentry>
5315                   <term><parameter>options</parameter></term>
5316                   <listitem><para>
5317                   An optional parameter that is passed to the newly
5318                   loaded module's <literal remap="tt">SetupProc</literal> function
5319                   (if it has one).  This argument is normally a
5320                   <constant>NULL</constant> terminated list of
5321                   <structname>Options</structname>, and must be interpreted that
5322                   way by modules loaded directly by the XFree86 common
5323                   layer.  However, it may be used for application-specific
5324                   parameter passing in other situations.
5325                     </para></listitem></varlistentry>
5326
5327
5328                 <varlistentry>
5329                   <term><parameter>modreq</parameter></term>
5330                   <listitem><para>
5331                   An optional <structname>XF86ModReqInfo*</structname> containing
5332                   version/ABI/vendor information to requirements to
5333                   check the newly loaded module against.  The main
5334                   purpose of this is to allow the loader to verify that
5335                   a module of the correct type/version before running
5336                   its <function>SetupProc</function> function.
5337                       </para>
5338
5339                     <para>
5340                   The <literal remap="tt">XF86ModReqInfo</literal> struct is defined
5341                   as follows:
5342                       <programlisting>
5343 typedef struct {
5344         CARD8        majorversion;  /* MAJOR_UNSPEC */
5345         CARD8        minorversion;  /* MINOR_UNSPEC */
5346         CARD16       patchlevel;    /* PATCH_UNSPEC */
5347         const char * abiclass;      /* ABI_CLASS_NONE */
5348         CARD32       abiversion;    /* ABI_VERS_UNSPEC */
5349         const char * moduleclass;   /* MOD_CLASS_NONE */
5350 } XF86ModReqInfo;
5351                         </programlisting>
5352
5353                   The information here is compared against the equivalent
5354                   information in the module's
5355                   <structname>XF86ModuleVersionInfo</structname> record (which
5356                   is described below).  The values in comments above
5357                   indicate <quote>don't care</quote> settings for each of the fields.
5358                   The comparisons made are as follows:
5359
5360                       <variablelist>
5361                         <varlistentry>
5362                           <term><structfield>majorversion</structfield></term>
5363                           <listitem><para>
5364                                    Must match the module's majorversion
5365                                    exactly.
5366                             </para></listitem></varlistentry>
5367
5368                         <varlistentry>
5369                           <term><structfield>minorversion</structfield></term>
5370                           <listitem><para>
5371                                    The module's minor version must be
5372                                    no less than this value.  This
5373                                    comparison is only made if
5374                                    <structfield>majorversion</structfield> is
5375                                    specified and matches.
5376                             </para></listitem></varlistentry>
5377
5378                         <varlistentry>
5379                           <term><structfield>patchlevel</structfield></term>
5380                           <listitem><para>
5381                                    The module's patchlevel must be no
5382                                    less than this value.  This comparison
5383                                    is only made if
5384                                    <structfield>minorversion</structfield> is
5385                                    specified and matches.
5386                             </para></listitem></varlistentry>
5387
5388                         <varlistentry>
5389                           <term><structfield>abiclass</structfield></term>
5390                           <listitem><para>
5391                                    String must match the module's abiclass
5392                                    string.
5393                             </para></listitem></varlistentry>
5394
5395                         <varlistentry>
5396                           <term><structfield>abiversion</structfield></term>
5397                           <listitem><para>
5398                                    Must be consistent with the module's
5399                                    abiversion (major equal, minor no
5400                                    older).
5401                             </para></listitem></varlistentry>
5402
5403                         <varlistentry>
5404                           <term><structfield>moduleclass</structfield></term>
5405                           <listitem><para>
5406                                    String must match the module's
5407                                    moduleclass string.
5408                             </para></listitem></varlistentry>
5409
5410                       </variablelist>
5411                     </para></listitem></varlistentry>
5412
5413                 <varlistentry>
5414                   <term><parameter>errmaj</parameter></term>
5415                   <listitem><para>
5416                   An optional pointer to a variable holding the major
5417                   part or the error code.  When provided,
5418                   <parameter>*errmaj</parameter> is filled in when
5419                   <function>LoadModule()</function> fails.
5420                     </para></listitem></varlistentry>
5421
5422                 <varlistentry>
5423                   <term><parameter>errmin</parameter></term>
5424                   <listitem><para>
5425                   Like <parameter>errmaj</parameter>, but for the minor part
5426                   of the error code.
5427                     </para></listitem></varlistentry>
5428
5429               </variablelist>
5430
5431             </para></blockquote>
5432         </para></blockquote>
5433
5434       <blockquote><para>
5435           <programlisting>
5436     void UnloadModule(pointer mod);
5437           </programlisting>
5438           <blockquote><para>
5439     This function unloads the module referred to by the handle mod.
5440     All child modules are also unloaded recursively.  This function must
5441     not be used to directly unload modules that are child modules (i.e.,
5442     those that have been loaded with the <function>LoadSubModule()</function>
5443     described below).
5444             </para>
5445
5446           </blockquote></para></blockquote>
5447     </sect2>
5448
5449     <sect2>
5450       <title>Module Requirements</title>
5451
5452       <para>
5453 Modules must provide information about themselves to the loader, and
5454 may optionally provide entry points for "setup" and "teardown" functions
5455 (those two functions are referred to here as <function>SetupProc</function>
5456 and <function>TearDownProc</function>).
5457       </para>
5458
5459       <para>
5460 The module information is contained in the
5461 <structname>XF86ModuleVersionInfo</structname> struct, which is defined as follows:
5462
5463         <programlisting>
5464 typedef struct {
5465     const char * modname;      /* name of module, e.g. "foo" */
5466     const char * vendor;       /* vendor specific string */
5467     CARD32       _modinfo1_;   /* constant MODINFOSTRING1/2 to find */
5468     CARD32       _modinfo2_;   /* infoarea with a binary editor/sign tool */
5469     CARD32       xf86version;  /* contains XF86_VERSION_CURRENT */
5470     CARD8        majorversion; /* module-specific major version */
5471     CARD8        minorversion; /* module-specific minor version */
5472     CARD16       patchlevel;   /* module-specific patch level */
5473     const char * abiclass;     /* ABI class that the module uses */
5474     CARD32       abiversion;   /* ABI version */
5475     const char * moduleclass;  /* module class */
5476     CARD32       checksum[4];  /* contains a digital signature of the */
5477                                /* version info structure */
5478 } XF86ModuleVersionInfo;
5479         </programlisting>
5480
5481 The fields are used as follows:
5482
5483         <variablelist>
5484           <varlistentry>
5485             <term><structfield>modname</structfield></term>
5486             <listitem><para>
5487                 The module's name.  This field is currently only for
5488                 informational purposes, but the loader may be modified
5489                 in future to require it to match the module's canonical
5490                 name.
5491               </para></listitem></varlistentry>
5492
5493
5494           <varlistentry>
5495             <term><structfield>vendor</structfield></term>
5496             <listitem><para>
5497                 The module vendor.  This field is for informational purposes
5498                 only.
5499               </para></listitem></varlistentry>
5500
5501
5502           <varlistentry>
5503             <term><structfield>_modinfo1_</structfield></term>
5504             <listitem><para>
5505                 This field holds the first part of a signature that can
5506                 be used to locate this structure in the binary.  It should
5507                 always be initialised to <constant>MODINFOSTRING1</constant>.
5508               </para></listitem></varlistentry>
5509
5510
5511           <varlistentry>
5512             <term><structfield>_modinfo2_</structfield></term>
5513             <listitem><para>
5514                 This field holds the second part of a signature that can
5515                 be used to locate this structure in the binary.  It should
5516                 always be initialised to <constant>MODINFOSTRING2</constant>.
5517               </para></listitem></varlistentry>
5518
5519
5520           <varlistentry>
5521             <term><structfield>xf86version</structfield></term>
5522             <listitem><para>
5523                 The XFree86 version against which the module was compiled.
5524                 This is mostly for informational/diagnostic purposes.  It
5525                 should be initialised to <constant>XF86_VERSION_CURRENT</constant>, which is
5526                 defined in <filename>xf86Version.h</filename>.
5527               </para></listitem></varlistentry>
5528
5529
5530           <varlistentry>
5531             <term><structfield>majorversion</structfield></term>
5532             <listitem><para>
5533                 The module-specific major version.  For modules where this
5534                 version is used for more than simply informational
5535                 purposes, the major version should only change (be
5536                 incremented) when ABI incompatibilities are introduced,
5537                 or ABI components are removed.
5538               </para></listitem></varlistentry>
5539
5540
5541           <varlistentry>
5542             <term><structfield>minorversion</structfield></term>
5543             <listitem><para>
5544                 The module-specific minor version.  For modules where this
5545                 version is used for more than simply informational
5546                 purposes, the minor version should only change (be
5547                 incremented) when ABI additions are made in a backward
5548                 compatible way.  It should be reset to zero when the major
5549                 version is increased.
5550               </para></listitem></varlistentry>
5551
5552
5553           <varlistentry>
5554             <term><structfield>patchlevel</structfield></term>
5555             <listitem><para>
5556                 The module-specific patch level.  The patch level should
5557                 increase with new revisions of the module where there
5558                 are no ABI changes, and it should be reset to zero when
5559                 the minor version is increased.
5560               </para></listitem></varlistentry>
5561
5562
5563           <varlistentry>
5564             <term><structfield>abiclass</structfield></term>
5565             <listitem><para>
5566                 The ABI class that the module requires.  The class is
5567                 specified as a string for easy extensibility.  It should
5568                 indicate which (if any) of the X server's built-in ABI
5569                 classes that the module relies on, or a third-party ABI
5570                 if appropriate.  Built-in ABI classes currently defined are:
5571
5572                 <variablelist>
5573                   <varlistentry>
5574                     <term><constant>ABI_CLASS_NONE</constant></term>
5575                     <listitem><para>no class
5576                       </para></listitem></varlistentry>
5577                   <varlistentry>
5578                     <term><constant>ABI_CLASS_ANSIC</constant></term>
5579                     <listitem><para>only requires the ANSI C interfaces
5580                       </para></listitem></varlistentry>
5581                   <varlistentry>
5582                     <term><constant>ABI_CLASS_VIDEODRV</constant></term>
5583                     <listitem><para>requires the video driver ABI
5584                       </para></listitem></varlistentry>
5585                   <varlistentry>
5586                     <term><constant>ABI_CLASS_XINPUT</constant></term>
5587                     <listitem><para>requires the XInput driver ABI
5588                       </para></listitem></varlistentry>
5589                   <varlistentry>
5590                     <term><constant>ABI_CLASS_EXTENSION</constant></term>
5591                     <listitem><para>requires the extension module ABI
5592                       </para></listitem></varlistentry>
5593                   <varlistentry>
5594                     <term><constant>ABI_CLASS_FONT</constant></term>
5595                     <listitem><para>requires the font module ABI
5596                       </para></listitem></varlistentry>
5597                 </variablelist>
5598
5599               </para></listitem></varlistentry>
5600
5601           <varlistentry>
5602             <term><structfield>abiversion</structfield></term>
5603             <listitem><para>
5604                 The version of abiclass that the module requires.  The
5605                 version consists of major and minor components.  The
5606                 major version must match and the minor version must be
5607                 no newer than that provided by the server or parent
5608                 module.  Version identifiers for the built-in classes
5609                 currently defined are:
5610
5611                 <literallayout><constant>
5612                    ABI_ANSIC_VERSION
5613                    ABI_VIDEODRV_VERSION
5614                    ABI_XINPUT_VERSION
5615                    ABI_EXTENSION_VERSION
5616                    ABI_FONT_VERSION
5617                   </constant></literallayout>
5618
5619               </para></listitem></varlistentry>
5620
5621           <varlistentry>
5622             <term><structfield>moduleclass</structfield></term>
5623             <listitem><para>
5624                 This is similar to the abiclass field, except that it
5625                 defines the type of module rather than the ABI it
5626                 requires.  For example, although all video drivers require
5627                 the video driver ABI, not all modules that require the
5628                 video driver ABI are video drivers.  This distinction
5629                 can be made with the moduleclass.  Currently pre-defined
5630                 module classes are:
5631
5632                 <literallayout><constant>
5633                    MOD_CLASS_NONE
5634                    MOD_CLASS_VIDEODRV
5635                    MOD_CLASS_XINPUT
5636                    MOD_CLASS_FONT
5637                    MOD_CLASS_EXTENSION
5638                   </constant></literallayout>
5639
5640               </para></listitem></varlistentry>
5641
5642           <varlistentry>
5643             <term><structfield>checksum</structfield></term>
5644             <listitem><para>
5645                 Not currently used.
5646               </para></listitem></varlistentry>
5647
5648         </variablelist>
5649       </para>
5650
5651       <para>
5652 The module version information, and the optional <function>SetupProc</function>
5653 and <function>TearDownProc</function> entry points are found by the loader
5654 by locating a data object in the module called "modnameModuleData",
5655 where "modname" is the canonical name of the module.  Modules must
5656 contain such a data object, and it must be declared with global scope,
5657 be compile-time initialised, and is of the following type:
5658
5659         <programlisting>
5660 typedef struct {
5661     XF86ModuleVersionInfo *     vers;
5662     ModuleSetupProc             setup;
5663     ModuleTearDownProc          teardown;
5664 } XF86ModuleData;
5665         </programlisting>
5666       </para>
5667
5668       <para>
5669 The vers parameter must be initialised to a pointer to a correctly
5670 initialised <structname>XF86ModuleVersionInfo</structname> struct.  The other
5671 two parameter are optional, and should be initialised to
5672 <constant>NULL</constant> when not required.  The other parameters are defined
5673 as
5674
5675         <blockquote><para>
5676             <programlisting>
5677     typedef pointer (*ModuleSetupProc)(pointer, pointer, int *, int *);
5678
5679     typedef void (*ModuleTearDownProc)(pointer);
5680
5681     pointer SetupProc(pointer module, pointer options,
5682                       int *errmaj, int *errmin);
5683             </programlisting>
5684             <blockquote><para>
5685     When defined, this function is called by the loader after successfully
5686     loading a module.  module is a handle for the newly loaded module,
5687     and maybe used by the <function>SetupProc</function> if it calls other
5688     loader functions that require a reference to it.   The remaining
5689     arguments are those that were passed to the
5690     <function>LoadModule()</function> (or <function>LoadSubModule()</function>),
5691     and are described above. When the <function>SetupProc</function> is
5692     successful it must return a non-<constant>NULL</constant> value.  The
5693     loader checks this, and if it is <constant>NULL</constant> it unloads
5694     the module and reports the failure to the caller of
5695     <function>LoadModule()</function>.  If the <function>SetupProc</function>
5696     does things that need to be undone when the module is unloaded,
5697     it should define a <function>TearDownProc</function>, and return a
5698     pointer that the <function>TearDownProc</function> can use to undo what
5699     has been done.
5700               </para>
5701
5702               <para>
5703     When a module is loaded multiple times, the <function>SetupProc</function>
5704     is called once for each time it is loaded.
5705               </para>
5706
5707             </blockquote></para></blockquote>
5708
5709         <blockquote><para>
5710             <programlisting>
5711     void TearDownProc(pointer tearDownData);
5712             </programlisting>
5713             <blockquote><para>
5714     When defined, this function is called when the loader unloads a
5715     module.  The <parameter>tearDownData</parameter> parameter is the return
5716     value of the <function>SetupProc()</function> that was called when the
5717     module was loaded.  The purpose of this function is to clean up
5718     before the module is unloaded (for example, by freeing allocated
5719     resources).
5720               </para>
5721
5722             </blockquote></para></blockquote>
5723       </para>
5724     </sect2>
5725
5726     <sect2>
5727       <title>Public Loader Interface</title>
5728
5729       <para>
5730 The following is the Loader interface that is available to any part of
5731 the server, and may also be used from within modules.
5732       </para>
5733
5734       <blockquote><para>
5735           <programlisting>
5736     pointer LoadSubModule(pointer parent, const char *module,
5737                           const char **subdirlist, const char **patternlist,
5738                           pointer options, const XF86ModReqInfo * modreq,
5739                           int *errmaj, int *errmin);
5740           </programlisting>
5741           <blockquote><para>
5742     This function is like the <function>LoadModule()</function> function
5743     described above, except that the module loaded is registered as a
5744     child of the calling module.  The <parameter>parent</parameter> parameter
5745     is the calling module's handle.  Modules loaded with this function
5746     are automatically unloaded when the parent module is unloaded.  The
5747     other difference is that the path parameter may not be specified.
5748     The module search path used for modules loaded with this function
5749     is the default search path as initialised with
5750     <function>LoaderSetPath()</function>.
5751             </para>
5752
5753           </blockquote></para></blockquote>
5754
5755       <blockquote><para>
5756           <programlisting>
5757     void UnloadSubModule(pointer module);
5758           </programlisting>
5759           <blockquote><para>
5760     This function unloads the module with handle <parameter>module</parameter>.
5761     If that module itself has children, they are also unloaded.  It is
5762     like <function>UnloadModule()</function>, except that it is safe to use
5763     for unloading child modules.
5764             </para>
5765
5766           </blockquote></para></blockquote>
5767
5768       <blockquote><para>
5769           <programlisting>
5770     pointer LoaderSymbol(const char *symbol);
5771           </programlisting>
5772         <blockquote><para>
5773     This function returns the address of the symbol with name
5774     <parameter>symbol</parameter>.  This may be used to locate a module entry
5775     point with a known name.
5776             </para>
5777
5778           </blockquote></para></blockquote>
5779
5780       <blockquote><para>
5781           <programlisting>
5782     char **LoaderlistDirs(const char **subdirlist,
5783                           const char **patternlist);
5784           </programlisting>
5785           <blockquote><para>
5786     This function returns a <constant>NULL</constant> terminated list of
5787     canonical modules names for modules found in the default module
5788     search path.  The <parameter>subdirlist</parameter> and
5789     <parameter>patternlist</parameter> parameters are as described above, and
5790     can be used to control the locations and names that are searched.
5791     If no modules are found, the return value is <constant>NULL</constant>.
5792     The returned list should be freed by calling
5793     <function>LoaderFreeDirList()</function> when it is no longer needed.
5794             </para>
5795
5796           </blockquote></para></blockquote>
5797
5798       <blockquote><para>
5799           <programlisting>
5800     void LoaderFreeDirList(char **list);
5801           </programlisting>
5802           <blockquote><para>
5803     This function frees a module list created by
5804     <function>LoaderlistDirs()</function>.
5805             </para>
5806
5807           </blockquote></para></blockquote>
5808
5809       <blockquote><para>
5810           <programlisting>
5811     void LoaderReqSymLists(const char **list0, ...);
5812           </programlisting>
5813           <blockquote><para>
5814     This function allows the registration of required symbols with the
5815     loader.  It is normally used by a caller of
5816     <function>LoadSubModule()</function>.  If any symbols registered in this
5817     way are found to be unresolved when
5818     <function>LoaderCheckUnresolved()</function> is called then
5819     <function>LoaderCheckUnresolved()</function> will report a failure.
5820     The function takes one or more <constant>NULL</constant> terminated
5821     lists of symbols.  The end of the argument list is indicated by a
5822     <constant>NULL</constant> argument.
5823             </para>
5824
5825           </blockquote></para></blockquote>
5826
5827       <blockquote><para>
5828           <programlisting>
5829     void LoaderReqSymbols(const char *sym0, ...);
5830           </programlisting>
5831         <blockquote><para>
5832     This function is like <function>LoaderReqSymLists()</function> except
5833     that its arguments are symbols rather than lists of symbols.  This
5834     function is more convenient when single functions are to be registered,
5835     especially when the single function might depend on runtime factors.
5836     The end of the argument list is indicated by a <constant>NULL</constant>
5837     argument.
5838             </para>
5839
5840           </blockquote></para></blockquote>
5841
5842       <blockquote><para>
5843           <programlisting>
5844     void LoaderRefSymLists(const char **list0, ...);
5845           </programlisting>
5846           <blockquote><para>
5847     This function allows the registration of possibly unresolved symbols
5848     with the loader.  When <function>LoaderCheckUnresolved()</function> is
5849     run it won't generate warnings for symbols registered in this way
5850     unless they were also registered as required symbols.
5851     The function takes one or more <constant>NULL</constant> terminated
5852     lists of symbols.  The end of the argument list is indicated by a
5853     <constant>NULL</constant> argument.
5854             </para>
5855
5856           </blockquote></para></blockquote>
5857
5858       <blockquote><para>
5859           <programlisting>
5860     void LoaderRefSymbols(const char *sym0, ...);
5861           </programlisting>
5862           <blockquote><para>
5863     This function is like <function>LoaderRefSymLists()</function> except
5864     that its arguments are symbols rather than lists of symbols.  This
5865     function is more convenient when single functions are to be registered,
5866     especially when the single function might depend on runtime factors.
5867     The end of the argument list is indicated by a <constant>NULL</constant>
5868     argument.
5869             </para>
5870
5871           </blockquote></para></blockquote>
5872
5873       <blockquote><para>
5874           <programlisting>
5875     int LoaderCheckUnresolved(int delayflag);
5876           </programlisting>
5877           <blockquote><para>
5878     This function checks for unresolved symbols.  It generates warnings
5879     for unresolved symbols that have not been registered with
5880     <function>LoaderRefSymLists()</function>, and maps them to a dummy
5881     function.  This behaviour may change in future.  If unresolved
5882     symbols are found that have been registered with
5883     <function>LoaderReqSymLists()</function> or
5884     <function>LoaderReqSymbols()</function> then this function returns a
5885     non-zero value.  If none of these symbols are unresolved the return
5886     value is zero, indicating success.
5887             </para>
5888
5889             <para>
5890     The <parameter>delayflag</parameter> parameter should normally be set to
5891     <constant>LD_RESOLV_IFDONE</constant>.
5892             </para>
5893
5894           </blockquote></para></blockquote>
5895
5896       <blockquote><para>
5897           <programlisting>
5898     LoaderErrorMsg(const char *name, const char *modname,
5899                    int errmaj, int errmin);
5900           </programlisting>
5901           <blockquote><para>
5902     This function prints an error message that includes the text <quote>Failed
5903     to load module</quote>, the module name <parameter>modname</parameter>, a message
5904     specific to the <parameter>errmaj</parameter> value, and the value if
5905     <parameter>errmin</parameter>.  If <parameter>name</parameter> is
5906     non-<constant>NULL</constant>, it is printed as an identifying prefix
5907     to the message (followed by a <quote>:</quote>).
5908             </para>
5909
5910           </blockquote></para></blockquote>
5911     </sect2>
5912
5913     <sect2>
5914       <title>Special Registration Functions</title>
5915
5916       <para>
5917 The loader contains some functions for registering some classes of modules.
5918 These may be moved out of the loader at some point.
5919       </para>
5920
5921       <blockquote><para>
5922           <programlisting>
5923     void LoadExtensionList(const ExtensionModule ext[]);
5924           </programlisting>
5925           <blockquote><para>
5926     This registers the entry points for the extension array identified by
5927     <parameter>ext</parameter>.  The <structname>ExtensionModule</structname> struct is
5928     defined as:
5929
5930               <programlisting>
5931 typedef struct {
5932     InitExtension       initFunc;
5933     char *              name;
5934     Bool                *disablePtr;
5935 } ExtensionModule;
5936               </programlisting>
5937             </para>
5938
5939           </blockquote></para></blockquote>
5940
5941     </sect2>
5942
5943   </sect1>
5944
5945   <sect1>
5946     <title>Helper Functions</title>
5947
5948     <para>
5949 This section describe <quote>helper</quote> functions that video driver
5950 might find useful.  While video drivers are not required to use any of
5951 these to be considered <quote>compliant</quote>, the use of appropriate helpers is
5952 strongly encouraged to improve the consistency of driver behaviour.
5953     </para>
5954
5955     <sect2>
5956       <title>Functions for printing messages</title>
5957
5958       <blockquote><para>
5959           <programlisting>
5960     ErrorF(const char *format, ...);
5961           </programlisting>
5962           <blockquote><para>
5963       This is the basic function for writing to the error log (typically
5964       stderr and/or a log file).  Video drivers should usually avoid
5965       using this directly in favour of the more specialised functions
5966       described below.  This function is useful for printing messages
5967       while debugging a driver.
5968             </para>
5969
5970           </blockquote></para></blockquote>
5971
5972       <blockquote><para>
5973           <programlisting>
5974     FatalError(const char *format, ...);
5975           </programlisting>
5976           <blockquote><para>
5977       This prints a message and causes the Xserver to abort.  It should
5978       rarely be used within a video driver, as most error conditions
5979       should be flagged by the return values of the driver functions.
5980       This allows the higher layers to decide how to proceed.  In rare
5981       cases, this can be used within a driver if a fatal unexpected
5982       condition is found.
5983             </para>
5984
5985           </blockquote></para></blockquote>
5986
5987       <blockquote><para>
5988           <programlisting>
5989     xf86ErrorF(const char *format, ...);
5990           </programlisting>
5991           <blockquote><para>
5992       This is like <function>ErrorF()</function>, except that the message is
5993       only printed when the Xserver's verbosity level is set to the
5994       default (<constant>1</constant>) or higher.  It means that the messages
5995       are not printed when the server is started with the
5996       <option>-quiet</option> flag.  Typically this function would only be
5997       used for continuing messages started with one of the more specialised
5998       functions described below.
5999             </para>
6000
6001           </blockquote></para></blockquote>
6002
6003       <blockquote><para>
6004           <programlisting>
6005     xf86ErrorFVerb(int verb, const char *format, ...);
6006           </programlisting>
6007           <blockquote><para>
6008       Like <function>xf86ErrorF()</function>, except the minimum verbosity
6009       level for which the message is to be printed is given explicitly.
6010       Passing a <parameter>verb</parameter> value of zero means the message
6011       is always printed.  A value higher than <constant>1</constant> can be
6012       used for information would normally not be needed, but which might
6013       be useful when diagnosing problems.
6014             </para>
6015
6016           </blockquote></para></blockquote>
6017
6018
6019       <blockquote><para>
6020           <programlisting>
6021     xf86Msg(MessageType type, const char *format, ...);
6022           </programlisting>
6023           <blockquote><para>
6024       This is like <function>xf86ErrorF()</function>, except that the message
6025       is prefixed with a marker determined by the value of
6026       <parameter>type</parameter>.  The marker is used to indicate the type of
6027       message (warning, error, probed value, config value, etc).  Note
6028       the <varname>xf86Verbose</varname> value is ignored for messages of
6029       type <constant>X_ERROR</constant>.
6030             </para>
6031
6032             <para>
6033       The marker values are:
6034
6035               <variablelist>
6036                 <varlistentry>
6037                   <term><constant>X_PROBED</constant></term>
6038                   <listitem><para>Value was probed.
6039                     </para></listitem></varlistentry>
6040                 <varlistentry>
6041                   <term><constant>X_CONFIG</constant></term>
6042                   <listitem><para>Value was given in the config file.
6043                     </para></listitem></varlistentry>
6044                 <varlistentry>
6045                   <term><constant>X_DEFAULT</constant></term>
6046                   <listitem><para>Value is a default.
6047                     </para></listitem></varlistentry>
6048                 <varlistentry>
6049                   <term><constant>X_CMDLINE</constant></term>
6050                   <listitem><para>Value was given on the command line.
6051                     </para></listitem></varlistentry>
6052                 <varlistentry>
6053                   <term><constant>X_NOTICE</constant></term>
6054                   <listitem><para>Notice.
6055                     </para></listitem></varlistentry>
6056                 <varlistentry>
6057                   <term><constant>X_ERROR</constant></term>
6058                   <listitem><para>Error message.
6059                     </para></listitem></varlistentry>
6060                 <varlistentry>
6061                   <term><constant>X_WARNING</constant></term>
6062                   <listitem><para>Warning message.
6063                     </para></listitem></varlistentry>
6064                 <varlistentry>
6065                   <term><constant>X_INFO</constant></term>
6066                   <listitem><para>Informational message.
6067                     </para></listitem></varlistentry>
6068                 <varlistentry>
6069                   <term><constant>X_NONE</constant></term>
6070                   <listitem><para>No prefix.
6071                     </para></listitem></varlistentry>
6072                 <varlistentry>
6073                   <term><constant>X_NOT_IMPLEMENTED</constant></term>
6074                   <listitem><para>The message relates to functionality
6075                       that is not yetimplemented.
6076                     </para></listitem></varlistentry>
6077                 </variablelist>
6078
6079             </para>
6080
6081           </blockquote></para></blockquote>
6082
6083       <blockquote><para>
6084           <programlisting>
6085     xf86MsgVerb(MessageType type, int verb, const char *format, ...);
6086           </programlisting>
6087           <blockquote><para>
6088       Like <function>xf86Msg()</function>, but with the verbosity level given
6089       explicitly.
6090             </para>
6091
6092           </blockquote></para></blockquote>
6093
6094       <blockquote><para>
6095           <programlisting>
6096     xf86DrvMsg(int scrnIndex, MessageType type, const char *format, ...);
6097           </programlisting>
6098           <blockquote><para>
6099       This is like <function>xf86Msg()</function> except that the driver's
6100       name (the <structfield>name</structfield> field of the
6101       <structname>ScrnInfoRec</structname>) followed by the
6102       <parameter>scrnIndex</parameter> in parentheses is printed following the
6103       prefix.  This should be used by video drivers in most cases as it
6104       clearly indicates which driver/screen the message is for.  If
6105       <parameter>scrnIndex</parameter> is negative, this function behaves
6106       exactly like <function>xf86Msg()</function>.
6107             </para>
6108
6109             <para>
6110       NOTE: This function can only be used after the
6111       <structname>ScrnInfoRec</structname> and its <structfield>name</structfield> field
6112       have been allocated.  Normally, this means that it can not be
6113       used before the END of the <function>ChipProbe()</function> function.
6114       Prior to that, use <function>xf86Msg()</function>, providing the
6115       driver's name explicitly.  No screen number can be supplied at
6116       that point.
6117             </para>
6118
6119           </blockquote></para></blockquote>
6120
6121       <blockquote><para>
6122           <programlisting>
6123     xf86DrvMsgVerb(int scrnIndex, MessageType type, int verb,
6124                                 const char *format, ...);
6125           </programlisting>
6126           <blockquote><para>
6127       Like <function>xf86DrvMsg()</function>, but with the verbosity level
6128       given explicitly.
6129             </para>
6130
6131           </blockquote></para></blockquote>
6132     </sect2>
6133
6134
6135     <sect2>
6136       <title>Functions for setting values based on command line and config file</title>
6137
6138       <blockquote><para>
6139           <programlisting>
6140     Bool xf86SetDepthBpp(ScrnInfoPtr scrp, int depth, int bpp,
6141
6142                                 int fbbpp, int depth24flags);
6143           </programlisting>
6144           <blockquote><para>
6145       This function sets the <structfield>depth</structfield>, <structfield>pixmapBPP</structfield> and <structfield>bitsPerPixel</structfield> fields
6146       of the <structname>ScrnInfoRec</structname>.  It also determines the defaults for display-wide
6147       attributes and pixmap formats the screen will support, and finds
6148       the Display subsection that matches the depth/bpp.  This function
6149       should normally be called very early from the
6150       <function>ChipPreInit()</function> function.
6151             </para>
6152
6153             <para>
6154       It requires that the <structfield>confScreen</structfield> field of the <structname>ScrnInfoRec</structname> be
6155       initialised prior to calling it.  This is done by the XFree86
6156       common layer prior to calling <function>ChipPreInit()</function>.
6157             </para>
6158
6159             <para>
6160       The parameters passed are:
6161
6162               <variablelist>
6163                 <varlistentry>
6164                   <term><parameter>depth</parameter></term>
6165                   <listitem><para>
6166                 driver's preferred default depth if no other is given.
6167                 If zero, use the overall server default.
6168                     </para></listitem></varlistentry>
6169
6170                 <varlistentry>
6171                   <term><parameter>bpp</parameter></term>
6172                   <listitem><para>
6173                 Same, but for the pixmap bpp.
6174                     </para></listitem></varlistentry>
6175
6176                 <varlistentry>
6177                   <term><parameter>fbbpp</parameter></term>
6178                   <listitem><para>
6179                 Same, but for the framebuffer bpp.
6180                     </para></listitem></varlistentry>
6181
6182                 <varlistentry>
6183                   <term><parameter>depth24flags</parameter></term>
6184                   <listitem><para>
6185                 Flags that indicate the level of 24/32bpp support
6186                 and whether conversion between different framebuffer
6187                 and pixmap formats is supported.  The flags for this
6188                 argument are defined as follows, and multiple flags
6189                 may be ORed together:
6190
6191                       <variablelist>
6192                         <varlistentry>
6193                           <term><constant>NoDepth24Support</constant></term>
6194                           <listitem><para>No depth 24 formats supported
6195                             </para></listitem></varlistentry>
6196                         <varlistentry>
6197                           <term><constant>Support24bppFb</constant></term>
6198                           <listitem><para>24bpp framebuffer supported
6199                             </para></listitem></varlistentry>
6200                         <varlistentry>
6201                           <term><constant>Support32bppFb</constant></term>
6202                           <listitem><para>32bpp framebuffer supported
6203                             </para></listitem></varlistentry>
6204                         <varlistentry>
6205                           <term><constant>SupportConvert24to32</constant></term>
6206                           <listitem><para>Can convert 24bpp pixmap to 32bpp fb
6207                             </para></listitem></varlistentry>
6208                         <varlistentry>
6209                           <term><constant>SupportConvert32to24</constant></term>
6210                           <listitem><para>Can convert 32bpp pixmap to 24bpp fb
6211                             </para></listitem></varlistentry>
6212                         <varlistentry>
6213                           <term><constant>ForceConvert24to32</constant></term>
6214                           <listitem><para>Force 24bpp pixmap to 32bpp fb conversion
6215                             </para></listitem></varlistentry>
6216                         <varlistentry>
6217                           <term><constant>ForceConvert32to24</constant></term>
6218                           <listitem><para>Force 32bpp pixmap to 24bpp fb conversion
6219                             </para></listitem></varlistentry>
6220                       </variablelist>
6221                     </para></listitem></varlistentry>
6222
6223               </variablelist>
6224             </para>
6225
6226             <para>
6227       It uses the command line, config file, and default values in the
6228       correct order of precedence to determine the depth and bpp values.
6229       It is up to the driver to check the results to see that it supports
6230       them.  If not the <function>ChipPreInit()</function> function should
6231       return <constant>FALSE</constant>.
6232             </para>
6233
6234             <para>
6235       If only one of depth/bpp is given, the other is set to a reasonable
6236       (and consistent) default.
6237             </para>
6238
6239             <para>
6240       If a driver finds that the initial <parameter>depth24flags</parameter>
6241       it uses later results in a fb format that requires more video
6242       memory than is available it may call this function a second time
6243       with a different <parameter>depth24flags</parameter> setting.
6244             </para>
6245
6246             <para>
6247       On success, the return value is <constant>TRUE</constant>.  On failure
6248       it prints an error message and returns <constant>FALSE</constant>.
6249             </para>
6250
6251             <para>
6252       The following fields of the <structname>ScrnInfoRec</structname> are
6253       initialised by this function:
6254
6255               <blockquote><para>
6256 <structfield>depth</structfield>, <structfield>bitsPerPixel</structfield>,
6257 <structfield>display</structfield>, <structfield>imageByteOrder</structfield>,
6258 <structfield>bitmapScanlinePad</structfield>,
6259 <structfield>bitmapScanlineUnit</structfield>, <structfield>bitmapBitOrder</structfield>,
6260 <structfield>numFormats</structfield>, <structfield>formats</structfield>,
6261 <structfield>fbFormat</structfield>.
6262                 </para></blockquote>
6263             </para>
6264
6265           </blockquote></para></blockquote>
6266
6267       <blockquote><para>
6268           <programlisting>
6269     void xf86PrintDepthBpp(scrnInfoPtr scrp);
6270           </programlisting>
6271           <blockquote><para>
6272       This function can be used to print out the depth and bpp settings.
6273       It should be called after the final call to
6274       <function>xf86SetDepthBpp()</function>.
6275             </para>
6276
6277           </blockquote></para></blockquote>
6278
6279       <blockquote><para>
6280           <programlisting>
6281     Bool xf86SetWeight(ScrnInfoPtr scrp, rgb weight, rgb mask);
6282           </programlisting>
6283           <blockquote><para>
6284       This function sets the <structfield>weight</structfield>, <structfield>mask</structfield>,
6285       <structfield>offset</structfield> and <structfield>rgbBits</structfield> fields of the
6286       <structname>ScrnInfoRec</structname>.  It would normally be called fairly
6287       early in the <function>ChipPreInit()</function> function for
6288       depths&nbsp;&gt;&nbsp;8bpp.
6289             </para>
6290
6291             <para>
6292       It requires that the <structfield>depth</structfield> and
6293       <structfield>display</structfield> fields of the <structname>ScrnInfoRec</structname>
6294       be initialised prior to calling it.
6295             </para>
6296
6297             <para>
6298       The parameters passed are:
6299
6300               <variablelist>
6301                 <varlistentry>
6302                   <term><parameter>weight</parameter></term>
6303                   <listitem><para>
6304                 driver's preferred default weight if no other is given.
6305                 If zero, use the overall server default.
6306
6307                     </para></listitem></varlistentry>
6308
6309                 <varlistentry>
6310                   <term><parameter>mask</parameter></term>
6311                   <listitem><para>
6312                 Same, but for mask.
6313
6314                     </para></listitem></varlistentry>
6315               </variablelist>
6316             </para>
6317
6318             <para>
6319       It uses the command line, config file, and default values in the
6320       correct order of precedence to determine the weight value.  It
6321       derives the mask and offset values from the weight and the defaults.
6322       It is up to the driver to check the results to see that it supports
6323       them.  If not the <function>ChipPreInit()</function> function should
6324       return <constant>FALSE</constant>.
6325             </para>
6326
6327             <para>
6328       On success, this function prints a message showing the weight
6329       values selected, and returns <constant>TRUE</constant>.
6330             </para>
6331
6332             <para>
6333       On failure it prints an error message and returns <constant>FALSE</constant>.
6334             </para>
6335
6336             <para>
6337       The following fields of the <structname>ScrnInfoRec</structname> are
6338       initialised by this function:
6339
6340               <blockquote><para>
6341                   <structfield>weight</structfield>,
6342                   <structfield>mask</structfield>,
6343                   <structfield>offset</structfield>.
6344                 </para></blockquote>
6345             </para>
6346
6347           </blockquote></para></blockquote>
6348
6349       <blockquote><para>
6350           <programlisting>
6351     Bool xf86SetDefaultVisual(ScrnInfoPtr scrp, int visual);
6352           </programlisting>
6353           <blockquote><para>
6354       This function sets the <structfield>defaultVisual</structfield> field of the
6355       <structname>ScrnInfoRec</structname>.  It would normally be called fairly
6356       early from the <function>ChipPreInit()</function> function.
6357             </para>
6358
6359             <para>
6360       It requires that the <structfield>depth</structfield> and
6361       <structfield>display</structfield> fields of the <structname>ScrnInfoRec</structname>
6362       be initialised prior to calling it.
6363             </para>
6364
6365             <para>
6366       The parameters passed are:
6367
6368               <variablelist>
6369                 <varlistentry>
6370                   <term><parameter>visual</parameter></term>
6371                   <listitem><para>
6372                 driver's preferred default visual if no other is given.
6373                 If <constant>-1</constant>, use the overall server default.
6374                     </para></listitem></varlistentry>
6375
6376               </variablelist>
6377             </para>
6378
6379             <para>
6380       It uses the command line, config file, and default values in the
6381       correct order of precedence to determine the default visual value.
6382       It is up to the driver to check the result to see that it supports
6383       it.  If not the <function>ChipPreInit()</function> function should
6384       return <constant>FALSE</constant>.
6385             </para>
6386
6387             <para>
6388       On success, this function prints a message showing the default visual
6389       selected, and returns <constant>TRUE</constant>.
6390             </para>
6391
6392             <para>
6393       On failure it prints an error message and returns <constant>FALSE</constant>.
6394             </para>
6395
6396           </blockquote></para></blockquote>
6397
6398       <blockquote><para>
6399           <programlisting>
6400     Bool xf86SetGamma(ScrnInfoPtr scrp, Gamma gamma);
6401           </programlisting>
6402           <blockquote><para>
6403       This function sets the <structfield>gamma</structfield> field of the
6404       <structname>ScrnInfoRec</structname>.  It would normally be called fairly
6405       early from the <function>ChipPreInit()</function> function in cases
6406       where the driver supports gamma correction.
6407             </para>
6408
6409             <para>
6410       It requires that the <structfield>monitor</structfield> field of the
6411       <structname>ScrnInfoRec</structname> be initialised prior to calling it.
6412             </para>
6413
6414             <para>
6415       The parameters passed are:
6416
6417               <variablelist>
6418                 <varlistentry>
6419                   <term><parameter>gamma</parameter></term>
6420                   <listitem><para>
6421                 driver's preferred default gamma if no other is given.
6422                 If zero (<code>&lt; 0.01</code>), use the overall server
6423                 default.
6424                     </para></listitem></varlistentry>
6425
6426               </variablelist>
6427             </para>
6428
6429             <para>
6430       It uses the command line, config file, and default values in the
6431       correct order of precedence to determine the gamma value.  It is
6432       up to the driver to check the results to see that it supports
6433       them.  If not the <function>ChipPreInit()</function> function should
6434       return <constant>FALSE</constant>.
6435             </para>
6436
6437             <para>
6438       On success, this function prints a message showing the gamma
6439       value selected, and returns <constant>TRUE</constant>.
6440             </para>
6441
6442             <para>
6443       On failure it prints an error message and returns <constant>FALSE</constant>.
6444             </para>
6445
6446           </blockquote></para></blockquote>
6447
6448
6449       <blockquote><para>
6450           <programlisting>
6451     void xf86SetDpi(ScrnInfoPtr pScrn, int x, int y);
6452           </programlisting>
6453           <blockquote><para>
6454       This function sets the <structfield>xDpi</structfield> and <structfield>yDpi</structfield>
6455       fields of the <structname>ScrnInfoRec</structname>.  The driver can specify
6456       preferred defaults by setting <parameter>x</parameter> and <parameter>y</parameter>
6457       to non-zero values.  The <option>-dpi</option> command line option
6458       overrides all other settings.  Otherwise, if the
6459       <emphasis>DisplaySize</emphasis> entry is present in the screen's &k.monitor;
6460       config file section, it is used together with the virtual size to
6461       calculate the dpi values.  This function should be called after
6462       all the mode resolution has been done.
6463             </para>
6464
6465           </blockquote></para></blockquote>
6466
6467       <blockquote><para>
6468           <programlisting>
6469     void xf86SetBlackWhitePixels(ScrnInfoPtr pScrn);
6470           </programlisting>
6471           <blockquote><para>
6472       This functions sets the <structfield>blackPixel</structfield> and
6473       <structfield>whitePixel</structfield> fields of the <structname>ScrnInfoRec</structname>
6474       according to whether or not the <option>-flipPixels</option> command
6475       line options is present.
6476             </para>
6477
6478           </blockquote></para></blockquote>
6479
6480       <blockquote><para>
6481           <programlisting>
6482     const char *xf86GetVisualName(int visual);
6483           </programlisting>
6484           <blockquote><para>
6485       Returns a printable string with the visual name matching the
6486       numerical visual class provided.  If the value is outside the
6487       range of valid visual classes, <constant>NULL</constant> is returned.
6488             </para>
6489
6490           </blockquote></para></blockquote>
6491
6492     </sect2>
6493
6494     <sect2>
6495       <title>Primary Mode functions</title>
6496
6497       <para>
6498 The primary mode helper functions are those which would normally be
6499 used by a driver, unless it has unusual requirements which cannot
6500 be catered for the by the helpers.
6501       </para>
6502
6503       <blockquote><para>
6504           <programlisting>
6505     int xf86ValidateModes(ScrnInfoPtr scrp, DisplayModePtr availModes,
6506                           char **modeNames, ClockRangePtr clockRanges,
6507                           int *linePitches, int minPitch, int maxPitch,
6508                           int pitchInc, int minHeight, int maxHeight,
6509                           int virtualX, int virtualY,
6510                           unsigned long apertureSize,
6511                           LookupModeFlags strategy);
6512           </programlisting>
6513           <blockquote><para>
6514       This function basically selects the set of modes to use based on
6515       those available and the various constraints.  It also sets some
6516       other related parameters.  It is normally called near the end of
6517       the <function>ChipPreInit()</function> function.
6518             </para>
6519
6520             <para>
6521       The parameters passed to the function are:
6522
6523               <variablelist>
6524                 <varlistentry>
6525                   <term><parameter>availModes</parameter></term>
6526                   <listitem><para>
6527                 List of modes available for the monitor.
6528                     </para></listitem></varlistentry>
6529
6530                 <varlistentry>
6531                   <term><parameter>modeNames</parameter></term>
6532                   <listitem><para>
6533                 List of mode names that the screen is requesting.
6534                     </para></listitem></varlistentry>
6535
6536                 <varlistentry>
6537                   <term><parameter>clockRanges</parameter></term>
6538                   <listitem><para>
6539                 A list of clock ranges allowed by the driver.  Each
6540                 range includes whether interlaced or multiscan modes
6541                 are supported for that range.  See below for more on
6542                 <parameter>clockRanges</parameter>.
6543                     </para></listitem></varlistentry>
6544
6545                 <varlistentry>
6546                   <term><parameter>linePitches</parameter></term>
6547                   <listitem><para>
6548                 List of line pitches supported by the driver.
6549                 This is optional and should be <constant>NULL</constant> when
6550                 not used.
6551                     </para></listitem></varlistentry>
6552
6553                 <varlistentry>
6554                   <term><parameter>minPitch</parameter></term>
6555                   <listitem><para>
6556                 Minimum line pitch supported by the driver.  This must
6557                 be supplied when <parameter>linePitches</parameter> is
6558                 <constant>NULL</constant>, and is ignored otherwise.
6559                     </para></listitem></varlistentry>
6560
6561                 <varlistentry>
6562                   <term><parameter>maxPitch</parameter></term>
6563                   <listitem><para>
6564                 Maximum line pitch supported by the driver.  This is
6565                 required when <parameter>minPitch</parameter> is required.
6566                     </para></listitem></varlistentry>
6567
6568                 <varlistentry>
6569                   <term><parameter>pitchInc</parameter></term>
6570                   <listitem><para>
6571                 Granularity of horizontal pitch values as supported by
6572                 the chipset.  This is expressed in bits.  This must be
6573                 supplied.
6574                     </para></listitem></varlistentry>
6575
6576                 <varlistentry>
6577                   <term><parameter>minHeight</parameter></term>
6578                   <listitem><para>
6579                 minimum virtual height allowed.  If zero, no limit is
6580                 imposed.
6581                     </para></listitem></varlistentry>
6582
6583                 <varlistentry>
6584                   <term><parameter>maxHeight</parameter></term>
6585                   <listitem><para>
6586                 maximum virtual height allowed.  If zero, no limit is
6587                 imposed.
6588                     </para></listitem></varlistentry>
6589
6590                 <varlistentry>
6591                   <term><parameter>virtualX</parameter></term>
6592                   <listitem><para>
6593                 If greater than zero, this is the virtual width value
6594                 that will be used.  Otherwise, the virtual width is
6595                 chosen to be the smallest that can accommodate the modes
6596                 selected.
6597                     </para></listitem></varlistentry>
6598
6599                 <varlistentry>
6600                   <term><parameter>virtualY</parameter></term>
6601                   <listitem><para>
6602                 If greater than zero, this is the virtual height value
6603                 that will be used.  Otherwise, the virtual height is
6604                 chosen to be the smallest that can accommodate the modes
6605                 selected.
6606                     </para></listitem></varlistentry>
6607
6608                 <varlistentry>
6609                   <term><parameter>apertureSize</parameter></term>
6610                   <listitem><para>
6611                 The size (in bytes) of the aperture used to access video
6612                 memory.
6613                     </para></listitem></varlistentry>
6614
6615                 <varlistentry>
6616                   <term><parameter>strategy</parameter></term>
6617                   <listitem><para>
6618                 The strategy to use when choosing from multiple modes
6619                 with the same name.  The options are:
6620
6621                       <variablelist>
6622                         <varlistentry>
6623                           <term><constant>LOOKUP_DEFAULT</constant></term>
6624                           <listitem><para>???
6625                             </para></listitem></varlistentry>
6626                         <varlistentry>
6627                           <term><constant>LOOKUP_BEST_REFRESH</constant></term>
6628                           <listitem><para>mode with best refresh rate
6629                             </para></listitem></varlistentry>
6630                         <varlistentry>
6631                           <term><constant>LOOKUP_CLOSEST_CLOCK</constant></term>
6632                           <listitem><para>mode with closest matching clock
6633                             </para></listitem></varlistentry>
6634                         <varlistentry>
6635                           <term><constant>LOOKUP_LIST_ORDER</constant></term>
6636                           <listitem><para>first usable mode in list
6637                             </para></listitem></varlistentry>
6638                       </variablelist>
6639
6640                 The following options can also be combined (OR'ed) with
6641                 one of the above:
6642
6643                       <variablelist>
6644                         <varlistentry>
6645                           <term><constant>LOOKUP_CLKDIV2</constant></term>
6646                           <listitem><para>Allow halved clocks
6647                             </para></listitem></varlistentry>
6648                         <varlistentry>
6649                           <term><constant>LOOKUP_OPTIONAL_TOLERANCES</constant></term>
6650                           <listitem><para>
6651                       Allow missing horizontal sync and/or vertical refresh
6652                       ranges in the xorg.conf Monitor section
6653                             </para></listitem></varlistentry>
6654                       </variablelist>
6655
6656                 <constant>LOOKUP_OPTIONAL_TOLERANCES</constant> should only be
6657                 specified when the driver can ensure all modes it generates
6658                 can sync on, or at least not damage, the monitor or digital
6659                 flat panel.  Horizontal sync and/or vertical refresh ranges
6660                 specified by the user will still be honoured (and acted upon).
6661
6662                     </para></listitem></varlistentry>
6663               </variablelist>
6664             </para>
6665
6666             <para>
6667       This function requires that the following fields of the
6668       <structname>ScrnInfoRec</structname> are initialised prior to calling it:
6669
6670               <variablelist>
6671                 <varlistentry>
6672                   <term><structfield>clock[]</structfield></term>
6673                   <listitem><para>
6674                       List of discrete clocks (when non-programmable)
6675                     </para></listitem></varlistentry>
6676                 <varlistentry>
6677                   <term><structfield>numClocks</structfield></term>
6678                   <listitem><para>
6679                       Number of discrete clocks (when non-programmable)
6680                     </para></listitem></varlistentry>
6681                 <varlistentry>
6682                   <term><structfield>progClock</structfield></term>
6683                   <listitem><para>
6684                       Whether the clock is programmable or not
6685                     </para></listitem></varlistentry>
6686                 <varlistentry>
6687                   <term><structfield>monitor</structfield></term>
6688                   <listitem><para>
6689                       Pointer to the applicable xorg.conf monitor section
6690                     </para></listitem></varlistentry>
6691                 <varlistentry>
6692                   <term><structfield>fdFormat</structfield></term>
6693                   <listitem><para>
6694                       Format of the screen buffer
6695                     </para></listitem></varlistentry>
6696                 <varlistentry>
6697                   <term><structfield>videoRam</structfield></term>
6698                   <listitem><para>
6699                       total video memory size (in bytes)
6700                     </para></listitem></varlistentry>
6701                 <varlistentry>
6702                   <term><structfield>maxHValue</structfield></term>
6703                   <listitem><para>
6704                       Maximum horizontal timing value allowed
6705                     </para></listitem></varlistentry>
6706                 <varlistentry>
6707                   <term><structfield>maxVValue</structfield></term>
6708                   <listitem><para>
6709                       Maximum vertical timing value allowed
6710                     </para></listitem></varlistentry>
6711                 <varlistentry>
6712                   <term><structfield>xInc</structfield></term>
6713                   <listitem><para>
6714                       Horizontal timing increment in pixels (defaults to 8)
6715                     </para></listitem></varlistentry>
6716               </variablelist>
6717             </para>
6718
6719             <para>
6720       This function fills in the following <structname>ScrnInfoRec</structname>
6721       fields:
6722
6723               <variablelist>
6724                 <varlistentry>
6725                   <term><structfield>modePool</structfield></term>
6726                   <listitem><para>
6727                 A subset of the modes available to the monitor which
6728                 are compatible with the driver.
6729                     </para></listitem></varlistentry>
6730
6731                 <varlistentry>
6732                   <term><structfield>modes</structfield></term>
6733                   <listitem><para>
6734                 One mode entry for each of the requested modes, with
6735                 the status field of each filled in to indicate if
6736                 the mode has been accepted or not.  This list of
6737                 modes is a circular list.
6738                     </para></listitem></varlistentry>
6739
6740                 <varlistentry>
6741                   <term><structfield>virtualX</structfield></term>
6742                   <listitem><para>
6743                 The resulting virtual width.
6744                     </para></listitem></varlistentry>
6745
6746                 <varlistentry>
6747                   <term><structfield>virtualY</structfield></term>
6748                   <listitem><para>
6749                 The resulting virtual height.
6750                     </para></listitem></varlistentry>
6751
6752                 <varlistentry>
6753                   <term><structfield>displayWidth</structfield></term>
6754                   <listitem><para>
6755                 The resulting line pitch.
6756                     </para></listitem></varlistentry>
6757
6758                 <varlistentry>
6759                   <term><structfield>virtualFrom</structfield></term>
6760                   <listitem><para>
6761                 Where the virtual size was determined from.
6762                     </para></listitem></varlistentry>
6763
6764               </variablelist>
6765             </para>
6766
6767             <para>
6768       The first stage of this function checks that the
6769       <parameter>virtualX</parameter> and <parameter>virtualY</parameter> values
6770       supplied (if greater than zero) are consistent with the line pitch
6771       and <parameter>maxHeight</parameter> limitations.  If not, an error
6772       message is printed, and the return value is <constant>-1</constant>.
6773             </para>
6774
6775             <para>
6776       The second stage sets up the mode pool, eliminating immediately
6777       any modes that exceed the driver's line pitch limits, and also
6778       the virtual width and height limits (if greater than zero).  For
6779       each mode removed an informational message is printed at verbosity
6780       level <constant>2</constant>.  If the mode pool ends up being empty,
6781       a warning message is printed, and the return value is
6782       <constant>0</constant>.
6783             </para>
6784
6785             <para>
6786       The final stage is to lookup each mode name, and fill in the remaining
6787       parameters.  If an error condition is encountered, a message is
6788       printed, and the return value is <constant>-1</constant>.  Otherwise,
6789       the return value is the number of valid modes found
6790       (<constant>0</constant> if none are found).
6791             </para>
6792
6793             <para>
6794       Even if the supplied mode names include duplicates, no two names will
6795       ever match the same mode.  Furthermore, if the supplied mode names do not
6796       yield a valid mode (including the case where no names are passed at all),
6797       the function will continue looking through the mode pool until it finds
6798       a mode that survives all checks, or until the mode pool is exhausted.
6799             </para>
6800
6801             <para>
6802       A message is only printed by this function when a fundamental
6803       problem is found.  It is intended that this function may be called
6804       more than once if there is more than one set of constraints that
6805       the driver can work within.
6806             </para>
6807
6808             <para>
6809       If this function returns <constant>-1</constant>, the
6810       <function>ChipPreInit()</function> function should return
6811       <constant>FALSE</constant>.
6812             </para>
6813
6814             <para>
6815       <parameter>clockRanges</parameter> is a linked list of clock ranges
6816       allowed by the driver.  If a mode doesn't fit in any of the defined
6817       <parameter>clockRanges</parameter>, it is rejected.  The first
6818       <literal remap="tt">clockRange</literal> that matches all requirements is used.
6819       This structure needs to be initialized to NULL when allocated.
6820             </para>
6821
6822             <para>
6823       <parameter>clockRanges</parameter> contains the following fields:
6824
6825               <variablelist>
6826                 <varlistentry>
6827                   <term><structfield>minClock</structfield></term>
6828                   <term><structfield>maxClock</structfield></term>
6829                   <listitem><para>
6830                 The lower and upper mode clock bounds for which the rest
6831                 of the <structname>clockRange</structname> parameters apply.
6832                 Since these are the mode clocks, they are not scaled
6833                 with the <structfield>ClockMulFactor</structfield> and
6834                 <structfield>ClockDivFactor</structfield>.  It is up to the driver
6835                 to adjust these values if they depend on the clock
6836                 scaling factors.
6837                     </para></listitem></varlistentry>
6838
6839                 <varlistentry>
6840                   <term><structfield>clockIndex</structfield></term>
6841                   <listitem><para>
6842                 (not used yet) <constant>-1</constant> for programmable clocks
6843                     </para></listitem></varlistentry>
6844
6845                 <varlistentry>
6846                   <term><structfield>interlaceAllowed</structfield></term>
6847                   <listitem><para>
6848                 <constant>TRUE</constant> if interlacing is allowed for this
6849                 range
6850                     </para></listitem></varlistentry>
6851
6852                 <varlistentry>
6853                   <term><structfield>doubleScanAllowed</structfield></term>
6854                   <listitem><para>
6855                 <constant>TRUE</constant> if doublescan or multiscan is allowed
6856                 for this range
6857                     </para></listitem></varlistentry>
6858
6859                 <varlistentry>
6860                   <term><structfield>ClockMulFactor</structfield></term>
6861                   <term><structfield>ClockDivFactor</structfield></term>
6862                   <listitem><para>
6863                 Scaling factors that are applied to the mode clocks ONLY
6864                 before selecting a clock index (when there is no
6865                 programmable clock) or a <structfield>SynthClock</structfield>
6866                 value.  This is useful for drivers that support pixel
6867                 multiplexing or that need to scale the clocks because
6868                 of hardware restrictions (like sending 24bpp data to an
6869                 8 bit RAMDAC using a tripled clock).
6870                     </para>
6871
6872                     <para>
6873                 Note that these parameters describe what must be done
6874                 to the mode clock to achieve the data transport clock
6875                 between graphics controller and RAMDAC.  For example
6876                 for <literal remap="tt">2:1</literal> pixel multiplexing, two pixels
6877                 are sent to the RAMDAC on each clock.  This allows the
6878                 RAMDAC clock to be half of the actual pixel clock.
6879                 Hence, <code>ClockMulFactor=1</code> and
6880                 <code>ClockDivFactor=2</code>.  This means that the
6881                 clock used for clock selection (ie, determining the
6882                 correct clock index from the list of discrete clocks)
6883                 or for the <structfield>SynthClock</structfield> field in case of
6884                 a programmable clock is:  (<code>mode-&gt;Clock *
6885                 ClockMulFactor) / ClockDivFactor</code>.
6886                     </para></listitem></varlistentry>
6887
6888                 <varlistentry>
6889                   <term><structfield>PrivFlags</structfield></term>
6890                   <listitem><para>
6891                 This field is copied into the
6892                 <literal remap="tt">mode-&gt;PrivFlags</literal> field when this
6893                 <literal remap="tt">clockRange</literal> is selected by
6894                 <function>xf86ValidateModes()</function>.  It allows the
6895                 driver to find out what clock range was selected, so it
6896                 knows it needs to set up pixel multiplexing or any other
6897                 range-dependent feature.  This field is purely
6898                 driver-defined: it may contain flag bits, an index or
6899                 anything else (as long as it is an <literal remap="tt">INT</literal>).
6900                     </para></listitem></varlistentry>
6901               </variablelist>
6902             </para>
6903
6904             <para>
6905       Note that the <structfield>mode-&gt;SynthClock</structfield> field is always
6906       filled in by <function>xf86ValidateModes()</function>: it will contain
6907       the <quote>data transport clock</quote>, which is the clock that will have
6908       to be programmed in the chip when it has a programmable clock, or
6909       the clock that will be picked from the clocks list when it is not
6910       a programmable one.  Thus:
6911
6912               <programlisting>
6913     mode-&gt;SynthClock = (mode-&gt;Clock * ClockMulFactor) / ClockDivFactor
6914               </programlisting>
6915             </para>
6916
6917           </blockquote></para></blockquote>
6918
6919       <blockquote><para>
6920           <programlisting>
6921     void xf86PruneDriverModes(ScrnInfoPtr scrp);
6922           </programlisting>
6923           <blockquote><para>
6924       This function deletes modes in the modes field of the
6925       <structname>ScrnInfoRec</structname> that have been marked as invalid.
6926       This is normally run after having run
6927       <function>xf86ValidateModes()</function> for the last time.  For each
6928       mode that is deleted, a warning message is printed out indicating
6929       the reason for it being deleted.
6930             </para>
6931
6932           </blockquote></para></blockquote>
6933
6934       <blockquote><para>
6935           <programlisting>
6936     void xf86SetCrtcForModes(ScrnInfoPtr scrp, int adjustFlags);
6937           </programlisting>
6938           <blockquote><para>
6939       This function fills in the <structname>Crtc*</structname> fields for all
6940       the modes in the <structfield>modes</structfield> field of the
6941       <structname>ScrnInfoRec</structname>.  The <parameter>adjustFlags</parameter>
6942       parameter determines how the vertical CRTC values are scaled for
6943       interlaced modes.  They are halved if it is
6944       <constant>INTERLACE_HALVE_V</constant>.  The vertical CRTC values are
6945       doubled for doublescan modes, and are further multiplied by the
6946       <literal remap="tt">VScan</literal> value.
6947             </para>
6948
6949             <para>
6950       This function is normally called after calling
6951       <function>xf86PruneDriverModes()</function>.
6952             </para>
6953
6954           </blockquote></para></blockquote>
6955
6956       <blockquote><para>
6957           <programlisting>
6958     void xf86PrintModes(ScrnInfoPtr scrp);
6959           </programlisting>
6960           <blockquote><para>
6961       This function prints out the virtual size setting, and the line
6962       pitch being used.  It also prints out two lines for each mode being
6963       used.  The first line includes the mode's pixel clock, horizontal sync
6964       rate, refresh rate, and whether it is interlaced, doublescanned and/or
6965       multi-scanned.  The second line is the mode's Modeline.
6966             </para>
6967
6968             <para>
6969       This function is normally called after calling
6970       <function>xf86SetCrtcForModes()</function>.
6971             </para>
6972
6973           </blockquote></para></blockquote>
6974
6975     </sect2>
6976
6977     <sect2>
6978       <title>Secondary Mode functions</title>
6979
6980       <para>
6981 The secondary mode helper functions are functions which are normally
6982 used by the primary mode helper functions, and which are not normally
6983 called directly by a driver.  If a driver has unusual requirements
6984 and needs to do its own mode validation, it might be able to make
6985 use of some of these secondary mode helper functions.
6986       </para>
6987
6988       <blockquote><para>
6989           <programlisting>
6990     int xf86GetNearestClock(ScrnInfoPtr scrp, int freq, Bool allowDiv2,
6991                             int *divider);
6992           </programlisting>
6993           <blockquote><para>
6994       This function returns the index of the closest clock to the
6995       frequency <parameter>freq</parameter> given (in kHz).  It assumes that
6996       the number of clocks is greater than zero.  It requires that the
6997       <structfield>numClocks</structfield> and <structfield>clock</structfield> fields of the
6998       <structname>ScrnInfoRec</structname> are initialised.  The
6999       <structfield>allowDiv2</structfield> field determines if the clocks can be
7000       halved.  The <parameter>*divider</parameter> return value indicates
7001       whether clock division is used when determining the clock returned.
7002             </para>
7003
7004             <para>
7005       This function is only for non-programmable clocks.
7006             </para>
7007
7008           </blockquote></para></blockquote>
7009
7010       <blockquote><para>
7011           <programlisting>
7012     const char *xf86ModeStatusToString(ModeStatus status);
7013           </programlisting>
7014           <blockquote><para>
7015       This function converts the <parameter>status</parameter> value to a
7016       descriptive printable string.
7017             </para>
7018
7019           </blockquote></para></blockquote>
7020
7021       <blockquote><para>
7022           <programlisting>
7023     ModeStatus xf86LookupMode(ScrnInfoPtr scrp, DisplayModePtr modep,
7024                      ClockRangePtr clockRanges, LookupModeFlags strategy);
7025           </programlisting>
7026           <blockquote><para>
7027       This function takes a pointer to a mode with the name filled in,
7028       and looks for a mode in the <structfield>modePool</structfield> list which
7029       matches.  The parameters of the matching mode are filled in to
7030       <parameter>*modep</parameter>.  The <parameter>clockRanges</parameter> and
7031       <parameter>strategy</parameter> parameters are as for the
7032       <function>xf86ValidateModes()</function> function above.
7033             </para>
7034
7035             <para>
7036       This function requires the <structfield>modePool</structfield>,
7037       <structfield>clock[]</structfield>, <structfield>numClocks</structfield> and
7038       <structfield>progClock</structfield> fields of the <structname>ScrnInfoRec</structname>
7039       to be initialised before being called.
7040             </para>
7041
7042             <para>
7043       The return value is <constant>MODE_OK</constant> if a mode was found.
7044       Otherwise it indicates why a matching mode could not be found.
7045             </para>
7046
7047           </blockquote></para></blockquote>
7048
7049       <blockquote><para>
7050           <programlisting>
7051     ModeStatus xf86InitialCheckModeForDriver(ScrnInfoPtr scrp,
7052                                 DisplayModePtr mode, ClockRangePtr clockRanges,
7053                                 LookupModeFlags strategy, int maxPitch,
7054                                 int virtualX, int virtualY);
7055           </programlisting>
7056           <blockquote><para>
7057       This function checks the passed mode against some basic driver
7058       constraints.  Apart from the ones passed explicitly, the
7059       <structfield>maxHValue</structfield> and <structfield>maxVValue</structfield> fields of
7060       the <structname>ScrnInfoRec</structname> are also used.  If the
7061       <structfield>ValidMode</structfield> field of the <structname>ScrnInfoRec</structname>
7062       is set, that function is also called to check the mode.  Next, the
7063       mode is checked against the monitor's constraints.
7064             </para>
7065
7066             <para>
7067       If the mode is consistent with all constraints, the return value
7068       is <constant>MODE_OK</constant>.  Otherwise the return value indicates
7069       which constraint wasn't met.
7070             </para>
7071
7072           </blockquote></para></blockquote>
7073
7074       <blockquote><para>
7075           <programlisting>
7076     void xf86DeleteMode(DisplayModePtr *modeList, DisplayModePtr mode);
7077           </programlisting>
7078           <blockquote><para>
7079       This function deletes the <parameter>mode</parameter> given from the
7080       <parameter>modeList</parameter>.  It never prints any messages, so it is
7081       up to the caller to print a message if required.
7082             </para>
7083
7084           </blockquote></para></blockquote>
7085     </sect2>
7086
7087     <sect2>
7088       <title>Functions for handling strings and tokens</title>
7089
7090       <para>
7091     Tables associating strings and numerical tokens combined with the
7092     following functions provide a compact way of handling strings from
7093     the config file, and for converting tokens into printable strings.
7094     The table data structure is:
7095
7096         <programlisting>
7097 typedef struct {
7098     int                 token;
7099     const char *        name;
7100 } SymTabRec, *SymTabPtr;
7101         </programlisting>
7102       </para>
7103
7104       <para>
7105     A table is an initialised array of <structname>SymTabRec</structname>.  The
7106     tokens must be non-negative integers.  Multiple names may be mapped
7107     to a single token.  The table is terminated with an element with a
7108     <structfield>token</structfield> value of <constant>-1</constant> and
7109     <constant>NULL</constant> for the <structfield>name</structfield>.
7110       </para>
7111
7112       <blockquote><para>
7113           <programlisting>
7114     const char *xf86TokenToString(SymTabPtr table, int token);
7115           </programlisting>
7116           <blockquote><para>
7117       This function returns the first string in <parameter>table</parameter>
7118       that matches <parameter>token</parameter>.  If no match is found,
7119       <constant>NULL</constant> is returned (NOTE, older versions of this
7120       function would return the string "unknown" when no match is found).
7121             </para>
7122
7123           </blockquote></para></blockquote>
7124
7125       <blockquote><para>
7126           <programlisting>
7127     int xf86StringToToken(SymTabPtr table, const char *string);
7128           </programlisting>
7129           <blockquote><para>
7130       This function returns the first token in <parameter>table</parameter>
7131       that matches <parameter>string</parameter>.  The
7132       <function>xf86NameCmp()</function> function is used to determine the
7133       match.  If no match is found, <constant>-1</constant> is returned.
7134             </para>
7135
7136           </blockquote></para></blockquote>
7137
7138     </sect2>
7139
7140     <sect2>
7141       <title>Functions for finding which config file entries to use</title>
7142
7143       <para>
7144     These functions can be used to select the appropriate config file
7145     entries that match the detected hardware.  They are described above
7146     in the <link linkend="probe">Probe</link> and
7147     <link linkend="avail">Available Functions</link> sections.
7148       </para>
7149
7150     </sect2>
7151
7152     <sect2>
7153       <title>Probing discrete clocks on old hardware</title>
7154
7155       <para>
7156     The <function>xf86GetClocks()</function> function may be used to assist
7157     in finding the discrete pixel clock values on older hardware.
7158       </para>
7159
7160       <blockquote><para>
7161           <programlisting>
7162     void xf86GetClocks(ScrnInfoPtr pScrn, int num,
7163                        Bool (*ClockFunc)(ScrnInfoPtr, int),
7164                        void (*ProtectRegs)(ScrnInfoPtr, Bool),
7165                        void (*BlankScreen)(ScrnInfoPtr, Bool),
7166                        int vertsyncreg, int maskval, int knownclkindex,
7167                        int knownclkvalue);
7168           </programlisting>
7169           <blockquote><para>
7170       This function uses a comparative sampling method to measure the
7171       discrete pixel clock values.  The number of discrete clocks to
7172       measure is given by <parameter>num</parameter>.  <parameter>clockFunc</parameter>
7173       is a function that selects the <parameter>n</parameter>'th clock.  It
7174       should also save or restore any state affected by programming the
7175       clocks when the index passed is <constant>CLK_REG_SAVE</constant> or
7176       <constant>CLK_REG_RESTORE</constant>.  <parameter>ProtectRegs</parameter> is
7177       a function that does whatever is required to protect the hardware
7178       state while selecting a new clock.  <parameter>BlankScreen</parameter>
7179       is a function that blanks the screen.  <parameter>vertsyncreg</parameter>
7180       and <parameter>maskval</parameter> are the register and bitmask to
7181       check for the presence of vertical sync pulses.
7182       <parameter>knownclkindex</parameter> and <parameter>knownclkvalue</parameter>
7183       are the index and value of a known clock.  These are the known
7184       references on which the comparative measurements are based.  The
7185       number of clocks probed is set in <structfield>pScrn-&gt;numClocks</structfield>,
7186       and the probed clocks are set in the <structfield>pScrn-&gt;clock[]</structfield>
7187       array.  All of the clock values are in units of kHz.
7188             </para>
7189
7190           </blockquote></para></blockquote>
7191
7192       <blockquote><para>
7193           <programlisting>
7194     void xf86ShowClocks(ScrnInfoPtr scrp, MessageType from);
7195           </programlisting>
7196           <blockquote><para>
7197       Print out the pixel clocks <parameter>scrp-&gt;clock[]</parameter>.
7198       <parameter>from</parameter> indicates whether the clocks were probed
7199       or from the config file.
7200             </para>
7201
7202           </blockquote></para></blockquote>
7203     </sect2>
7204
7205     <sect2>
7206       <title>Other helper functions</title>
7207
7208       <blockquote><para>
7209           <programlisting>
7210     Bool xf86IsUnblank(int mode);
7211           </programlisting>
7212           <blockquote><para>
7213       Returns <constant>TRUE</constant> when the screen saver mode specified
7214       by <parameter>mode</parameter> requires the screen be unblanked,
7215       and <constant>FALSE</constant> otherwise.  The screen saver modes that
7216       require blanking are <constant>SCREEN_SAVER_ON</constant> and
7217       <constant>SCREEN_SAVER_CYCLE</constant>, and the screen saver modes that
7218       require unblanking are <constant>SCREEN_SAVER_OFF</constant> and
7219       <constant>SCREEN_SAVER_FORCER</constant>.  Drivers may call this helper
7220       from their <function>SaveScreen()</function> function to interpret the
7221       screen saver modes.
7222             </para>
7223
7224           </blockquote></para></blockquote>
7225     </sect2>
7226   </sect1>
7227
7228   <sect1>
7229     <title>The vgahw module</title>
7230
7231     <para>
7232 The vgahw modules provides an interface for saving, restoring and
7233 programming the standard VGA registers, and for handling VGA colourmaps.
7234     </para>
7235
7236     <sect2>
7237       <title>Data Structures</title>
7238
7239       <para>
7240     The public data structures used by the vgahw module are
7241     <structname>vgaRegRec</structname> and <structname>vgaHWRec</structname>.  They are
7242     defined in <filename>vgaHW.h.</filename>
7243       </para>
7244
7245     </sect2>
7246
7247     <sect2>
7248       <title>General vgahw Functions</title>
7249
7250       <blockquote><para>
7251           <programlisting>
7252     Bool vgaHWGetHWRec(ScrnInfoPtr pScrn);
7253           </programlisting>
7254           <blockquote><para>
7255       This function allocates a <structname>vgaHWRec</structname> structure, and
7256       hooks it into the <structname>ScrnInfoRec</structname>'s
7257       <structfield>privates</structfield>.  Like all information hooked into the
7258       <structfield>privates</structfield>, it is persistent, and only needs to be
7259       allocated once per screen.  This function should normally be called
7260       from the driver's <function>ChipPreInit()</function> function.  The
7261       <structname>vgaHWRec</structname> is zero-allocated, and the following
7262       fields are explicitly initialised:
7263
7264               <variablelist>
7265                 <varlistentry>
7266                   <term><structfield>ModeReg.DAC[]</structfield></term>
7267                   <listitem><para>initialised with a default colourmap
7268                     </para></listitem></varlistentry>
7269                 <varlistentry>
7270                   <term><structfield>ModeReg.Attribute[0x11]</structfield></term>
7271                   <listitem><para>initialised with the default overscan index
7272                     </para></listitem></varlistentry>
7273                 <varlistentry>
7274                   <term><structfield>ShowOverscan</structfield></term>
7275                   <listitem><para>initialised according to the "ShowOverscan" option
7276                     </para></listitem></varlistentry>
7277                 <varlistentry>
7278                   <term><structfield>paletteEnabled</structfield></term>
7279                   <listitem><para>initialised to FALSE
7280                     </para></listitem></varlistentry>
7281                 <varlistentry>
7282                   <term><structfield>cmapSaved</structfield></term>
7283                   <listitem><para>initialised to FALSE
7284                     </para></listitem></varlistentry>
7285                 <varlistentry>
7286                   <term><structfield>pScrn</structfield></term>
7287                   <listitem><para>initialised to pScrn
7288                     </para></listitem></varlistentry>
7289               </variablelist>
7290             </para>
7291
7292             <para>
7293       In addition to the above, <function>vgaHWSetStdFuncs()</function> is
7294       called to initialise the register access function fields with the
7295       standard VGA set of functions.
7296             </para>
7297
7298             <para>
7299       Once allocated, a pointer to the <structname>vgaHWRec</structname> can be
7300       obtained from the <literal remap="tt">ScrnInfoPtr</literal> with the
7301       <literal remap="tt">VGAHWPTR(pScrn)</literal> macro.
7302             </para>
7303
7304           </blockquote></para></blockquote>
7305
7306       <blockquote><para>
7307           <programlisting>
7308     void vgaHWFreeHWRec(ScrnInfoPtr pScrn);
7309           </programlisting>
7310           <blockquote><para>
7311       This function frees a <structname>vgaHWRec</structname> structure.  It
7312       should be called from a driver's <function>ChipFreeScreen()</function>
7313       function.
7314             </para>
7315
7316           </blockquote></para></blockquote>
7317
7318       <blockquote><para>
7319           <programlisting>
7320     Bool vgaHWSetRegCounts(ScrnInfoPtr pScrn, int numCRTC,
7321                           int numSequencer, int numGraphics, int numAttribute);
7322           </programlisting>
7323           <blockquote><para>
7324       This function allows the number of CRTC, Sequencer, Graphics and
7325       Attribute registers to be changed.  This makes it possible for
7326       extended registers to be saved and restored with
7327       <function>vgaHWSave()</function> and <function>vgaHWRestore()</function>.
7328       This function should be called after a <structname>vgaHWRec</structname>
7329       has been allocated with <function>vgaHWGetHWRec()</function>.  The
7330       default values are defined in <filename>vgaHW.h</filename> as follows:
7331
7332               <programlisting>
7333 #define VGA_NUM_CRTC 25
7334 #define VGA_NUM_SEQ   5
7335 #define VGA_NUM_GFX   9
7336 #define VGA_NUM_ATTR 21
7337               </programlisting>
7338             </para>
7339
7340           </blockquote></para></blockquote>
7341
7342       <blockquote><para>
7343           <programlisting>
7344     Bool vgaHWCopyReg(vgaRegPtr dst, vgaRegPtr src);
7345           </programlisting>
7346           <blockquote><para>
7347       This function copies the contents of the VGA saved registers in
7348       <parameter>src</parameter> to <parameter>dst</parameter>.  Note that it isn't
7349       possible to simply do this with <function>memcpy()</function> (or
7350       similar).  This function returns <constant>TRUE</constant> unless there
7351       is a problem allocating space for the <structfield>CRTC</structfield> and
7352       related fields in <parameter>dst</parameter>.
7353             </para>
7354
7355           </blockquote></para></blockquote>
7356
7357       <blockquote><para>
7358           <programlisting>
7359     void vgaHWSetStdFuncs(vgaHWPtr hwp);
7360           </programlisting>
7361           <blockquote><para>
7362       This function initialises the register access function fields of
7363       <parameter>hwp</parameter> with the standard VGA set of functions.  This
7364       is called by <function>vgaHWGetHWRec()</function>, so there is usually
7365       no need to call this explicitly.  The register access functions
7366       are described below.  If the registers are shadowed in some other
7367       port I/O space (for example a PCI I/O region), these functions
7368       can be used to access the shadowed registers if
7369       <structfield>hwp-&gt;PIOOffset</structfield> is initialised with
7370       <literal remap="tt">offset</literal>, calculated in such a way that when the
7371       standard VGA I/O port value is added to it the correct offset into
7372       the PIO area results.  This value is initialised to zero in
7373       <function>vgaHWGetHWRec()</function>.  (Note: the PIOOffset functionality
7374       is present in XFree86 4.1.0 and later.)
7375             </para>
7376
7377           </blockquote></para></blockquote>
7378
7379       <blockquote><para>
7380           <programlisting>
7381     void vgaHWSetMmioFuncs(vgaHWPtr hwp, CARD8 *base, int offset);
7382           </programlisting>
7383           <blockquote><para>
7384       This function initialised the register access function fields of
7385       hwp with a generic MMIO set of functions.
7386       <structfield>hwp-&gt;MMIOBase</structfield> is initialised with
7387       <parameter>base</parameter>, which must be the virtual address that the
7388       start of MMIO area is mapped to.  <structfield>hwp-&gt;MMIOOffset</structfield>
7389       is initialised with <parameter>offset</parameter>, which must be calculated
7390       in such a way that when the standard VGA I/O port value is added
7391       to it the correct offset into the MMIO area results.  That means
7392       that these functions are only suitable when the VGA I/O ports are
7393       made available in a direct mapping to the MMIO space.  If that is
7394       not the case, the driver will need to provide its own register
7395       access functions.  The register access functions are described
7396       below.
7397             </para>
7398
7399           </blockquote></para></blockquote>
7400
7401       <blockquote><para>
7402           <programlisting>
7403     Bool vgaHWMapMem(ScrnInfoPtr pScrn);
7404           </programlisting>
7405           <blockquote><para>
7406       This function maps the VGA memory window.  It requires that the
7407       <structname>vgaHWRec</structname> be allocated.  If a driver requires
7408       non-default <structfield>MapPhys</structfield> or <structfield>MapSize</structfield>
7409       settings (the physical location and size of the VGA memory window)
7410       then those fields of the <structname>vgaHWRec</structname> must be initialised
7411       before calling this function.  Otherwise, this function initialiases
7412       the default values of <constant>0xA0000</constant> for
7413       <structfield>MapPhys</structfield> and <code>(64&nbsp;*&nbsp;1024)</code> for
7414       <structfield>MapSize</structfield>.  This function must be called before
7415       attempting to save or restore the VGA state.  If the driver doesn't
7416       call it explicitly, the <function>vgaHWSave()</function> and
7417       <function>vgaHWRestore()</function> functions may call it if they need
7418       to access the VGA memory (in which case they will also call
7419       <function>vgaHWUnmapMem()</function> to unmap the VGA memory before
7420       exiting).
7421             </para>
7422
7423           </blockquote></para></blockquote>
7424
7425       <blockquote><para>
7426           <programlisting>
7427     void vgaHWUnmapMem(ScrnInfoPtr pScrn);
7428           </programlisting>
7429           <blockquote><para>
7430       This function unmaps the VGA memory window.  It must only be called
7431       after the memory has been mapped.  The <structfield>Base</structfield> field
7432       of the <structname>vgaHWRec</structname> field is set to <constant>NULL</constant>
7433       to indicate that the memory is no longer mapped.
7434             </para>
7435
7436           </blockquote></para></blockquote>
7437
7438       <blockquote><para>
7439           <programlisting>
7440     void vgaHWGetIOBase(vgaHWPtr hwp);
7441           </programlisting>
7442           <blockquote><para>
7443       This function initialises the <structfield>IOBase</structfield> field of the
7444       <structname>vgaHWRec</structname>.  This function must be called before
7445       using any other functions that access the video hardware.
7446             </para>
7447
7448             <para>
7449       A macro <function>VGAHW_GET_IOBASE()</function> is also available in
7450       <filename>vgaHW.h</filename> that returns the I/O base, and this may
7451       be used when the vgahw module is not loaded (for example, in the
7452       <function>ChipProbe()</function> function).
7453             </para>
7454
7455           </blockquote></para></blockquote>
7456
7457       <blockquote><para>
7458           <programlisting>
7459     void vgaHWUnlock(vgaHWPtr hwp);
7460           </programlisting>
7461           <blockquote><para>
7462       This function unlocks the VGA <literal remap="tt">CRTC[0-7]</literal> registers,
7463       and must be called before attempting to write to those registers.
7464             </para>
7465
7466           </blockquote></para></blockquote>
7467
7468       <blockquote><para>
7469           <programlisting>
7470     void vgaHWLock(vgaHWPtr hwp);
7471           </programlisting>
7472           <blockquote><para>
7473       This function locks the VGA <literal remap="tt">CRTC[0-7]</literal> registers.
7474             </para>
7475
7476           </blockquote></para></blockquote>
7477
7478       <blockquote><para>
7479           <programlisting>
7480     void vgaHWEnable(vgaHWPtr hwp);
7481           </programlisting>
7482           <blockquote><para>
7483       This function enables the VGA subsystem.  (Note, this function is
7484       present in XFree86 4.1.0 and later.).
7485             </para>
7486
7487           </blockquote></para></blockquote>
7488
7489       <blockquote><para>
7490           <programlisting>
7491     void vgaHWDisable(vgaHWPtr hwp);
7492           </programlisting>
7493           <blockquote><para>
7494       This function disables the VGA subsystem.  (Note, this function is
7495       present in XFree86 4.1.0 and later.).
7496             </para>
7497
7498           </blockquote></para></blockquote>
7499
7500       <blockquote><para>
7501           <programlisting>
7502     void vgaHWSave(ScrnInfoPtr pScrn, vgaRegPtr save, int flags);
7503           </programlisting>
7504           <blockquote><para>
7505       This function saves the VGA state.  The state is written to the
7506       <structname>vgaRegRec</structname> pointed to by <parameter>save</parameter>.
7507       <parameter>flags</parameter> is set to one or more of the following flags
7508       ORed together:
7509
7510               <variablelist>
7511                 <varlistentry>
7512                   <term><constant>VGA_SR_MODE</constant></term>
7513                   <listitem><para>the mode setting registers are saved
7514                     </para></listitem></varlistentry>
7515                 <varlistentry>
7516                   <term><constant>VGA_SR_FONTS</constant></term>
7517                   <listitem><para>the text mode font/text data is saved
7518                     </para></listitem></varlistentry>
7519                 <varlistentry>
7520                   <term><constant>VGA_SR_CMAP</constant></term>
7521                   <listitem><para>the colourmap (LUT) is saved
7522                     </para></listitem></varlistentry>
7523                 <varlistentry>
7524                   <term><constant>VGA_SR_ALL</constant></term>
7525                   <listitem><para>all of the above are saved
7526                     </para></listitem></varlistentry>
7527               </variablelist>
7528             </para>
7529
7530             <para>
7531       The <structname>vgaHWRec</structname> and its <structfield>IOBase</structfield> fields
7532       must be initialised before this function is called.  If
7533       <constant>VGA_SR_FONTS</constant> is set in <parameter>flags</parameter>, the
7534       VGA memory window must be mapped.  If it isn't then
7535       <function>vgaHWMapMem()</function> will be called to map it, and
7536       <function>vgaHWUnmapMem()</function> will be called to unmap it
7537       afterwards.  <function>vgaHWSave()</function> uses the three functions
7538       below in the order <function>vgaHWSaveColormap()</function>,
7539       <function>vgaHWSaveMode()</function>, <function>vgaHWSaveFonts()</function> to
7540       carry out the different save phases.  It is undecided at this
7541       stage whether they will remain part of the vgahw module's public
7542       interface or not.
7543             </para>
7544
7545           </blockquote></para></blockquote>
7546
7547       <blockquote><para>
7548           <programlisting>
7549     void vgaHWSaveMode(ScrnInfoPtr pScrn, vgaRegPtr save);
7550           </programlisting>
7551           <blockquote><para>
7552       This function saves the VGA mode registers.  They are saved to
7553       the <structname>vgaRegRec</structname> pointed to by <parameter>save</parameter>.
7554       The registers saved are:
7555
7556               <literallayout>
7557         MiscOut
7558         CRTC[0-0x18]
7559         Attribute[0-0x14]
7560         Graphics[0-8]
7561         Sequencer[0-4]
7562               </literallayout>
7563             </para>
7564
7565             <para>
7566     The number of registers actually saved may be modified by a prior call
7567     to <function>vgaHWSetRegCounts()</function>.
7568             </para>
7569
7570           </blockquote></para></blockquote>
7571
7572       <blockquote><para>
7573           <programlisting>
7574     void vgaHWSaveFonts(ScrnInfoPtr pScrn, vgaRegPtr save);
7575           </programlisting>
7576           <blockquote><para>
7577       This function saves the text mode font and text data held in the
7578       video memory.  If called while in a graphics mode, no save is
7579       done.  The VGA memory window must be mapped with
7580       <function>vgaHWMapMem()</function> before to calling this function.
7581             </para>
7582
7583             <para>
7584       On some platforms, one or more of the font/text plane saves may be
7585       no-ops.  This is the case when the platform's VC driver already
7586       takes care of this.
7587             </para>
7588
7589           </blockquote></para></blockquote>
7590
7591       <blockquote><para>
7592           <programlisting>
7593     void vgaHWSaveColormap(ScrnInfoPtr pScrn, vgaRegPtr save);
7594           </programlisting>
7595           <blockquote><para>
7596       This function saves the VGA colourmap (LUT).  Before saving it, it
7597       attempts to verify that the colourmap is readable.  In rare cases
7598       where it isn't readable, a default colourmap is saved instead.
7599             </para>
7600
7601           </blockquote></para></blockquote>
7602
7603       <blockquote><para>
7604           <programlisting>
7605     void vgaHWRestore(ScrnInfoPtr pScrn, vgaRegPtr restore, int flags);
7606           </programlisting>
7607           <blockquote><para>
7608       This function programs the VGA state.  The state programmed is
7609       that contained in the <structname>vgaRegRec</structname> pointed to by
7610       <parameter>restore</parameter>.  <parameter>flags</parameter> is the same
7611       as described above for the <function>vgaHWSave()</function> function.
7612             </para>
7613
7614             <para>
7615       The <structname>vgaHWRec</structname> and its <structfield>IOBase</structfield> fields
7616       must be initialised before this function is called.  If
7617       <constant>VGA_SR_FONTS</constant> is set in <parameter>flags</parameter>, the
7618       VGA memory window must be mapped.  If it isn't then
7619       <function>vgaHWMapMem()</function> will be called to map it, and
7620       <function>vgaHWUnmapMem()</function> will be called to unmap it
7621       afterwards.  <function>vgaHWRestore()</function> uses the three functions
7622       below in the order <function>vgaHWRestoreFonts()</function>,
7623       <function>vgaHWRestoreMode()</function>,
7624       <function>vgaHWRestoreColormap()</function> to carry out the different
7625       restore phases.  It is undecided at this stage whether they will
7626       remain part of the vgahw module's public interface or not.
7627             </para>
7628
7629           </blockquote></para></blockquote>
7630
7631       <blockquote><para>
7632           <programlisting>
7633     void vgaHWRestoreMode(ScrnInfoPtr pScrn, vgaRegPtr restore);
7634           </programlisting>
7635           <blockquote><para>
7636       This function restores the VGA mode registers.  They are restored
7637       from the data in the <structname>vgaRegRec</structname> pointed to by
7638       <parameter>restore</parameter>.  The registers restored are:
7639
7640               <literallayout>
7641         MiscOut
7642         CRTC[0-0x18]
7643         Attribute[0-0x14]
7644         Graphics[0-8]
7645         Sequencer[0-4]
7646               </literallayout>
7647             </para>
7648
7649             <para>
7650     The number of registers actually restored may be modified by a prior call
7651     to <function>vgaHWSetRegCounts()</function>.
7652             </para>
7653
7654           </blockquote></para></blockquote>
7655
7656       <blockquote><para>
7657           <programlisting>
7658     void vgaHWRestoreFonts(ScrnInfoPtr pScrn, vgaRegPtr restore);
7659           </programlisting>
7660           <blockquote><para>
7661       This function restores the text mode font and text data to the
7662       video memory.  The VGA memory window must be mapped with
7663       <function>vgaHWMapMem()</function> before to calling this function.
7664             </para>
7665
7666             <para>
7667       On some platforms, one or more of the font/text plane restores
7668       may be no-ops.  This is the case when the platform's VC driver
7669       already takes care of this.
7670             </para>
7671
7672           </blockquote></para></blockquote>
7673
7674       <blockquote><para>
7675           <programlisting>
7676     void vgaHWRestoreColormap(ScrnInfoPtr pScrn, vgaRegPtr restore);
7677           </programlisting>
7678           <blockquote><para>
7679       This function restores the VGA colourmap (LUT).
7680             </para>
7681
7682           </blockquote></para></blockquote>
7683
7684       <blockquote><para>
7685           <programlisting>
7686     void vgaHWInit(ScrnInfoPtr pScrn, DisplayModePtr mode);
7687           </programlisting>
7688           <blockquote><para>
7689       This function fills in the <structname>vgaHWRec</structname>'s
7690       <structfield>ModeReg</structfield> field with the values appropriate for
7691       programming the given video mode.  It requires that the
7692       <structname>ScrnInfoRec</structname>'s <structfield>depth</structfield> field is
7693       initialised, which determines how the registers are programmed.
7694             </para>
7695
7696           </blockquote></para></blockquote>
7697
7698       <blockquote><para>
7699           <programlisting>
7700     void vgaHWSeqReset(vgaHWPtr hwp, Bool start);
7701           </programlisting>
7702           <blockquote><para>
7703       Do a VGA sequencer reset.  If start is <constant>TRUE</constant>, the
7704       reset is started.  If start is <constant>FALSE</constant>, the reset
7705       is ended.
7706             </para>
7707
7708           </blockquote></para></blockquote>
7709
7710       <blockquote><para>
7711           <programlisting>
7712     void vgaHWProtect(ScrnInfoPtr pScrn, Bool on);
7713           </programlisting>
7714           <blockquote><para>
7715       This function protects VGA registers and memory from corruption
7716       during loads.  It is typically called with on set to
7717       <constant>TRUE</constant> before programming, and with on set to
7718       <constant>FALSE</constant> after programming.
7719             </para>
7720
7721           </blockquote></para></blockquote>
7722
7723       <blockquote><para>
7724           <programlisting>
7725     Bool vgaHWSaveScreen(ScreenPtr pScreen, int mode);
7726           </programlisting>
7727           <blockquote><para>
7728       This function blanks and unblanks the screen.  It is blanked when
7729       <parameter>mode</parameter> is <constant>SCREEN_SAVER_ON</constant> or
7730       <constant>SCREEN_SAVER_CYCLE</constant>, and unblanked when
7731       <parameter>mode</parameter> is <constant>SCREEN_SAVER_OFF</constant> or
7732       <constant>SCREEN_SAVER_FORCER</constant>.
7733             </para>
7734
7735           </blockquote></para></blockquote>
7736
7737       <blockquote><para>
7738           <programlisting>
7739     void vgaHWBlankScreen(ScrnInfoPtr pScrn, Bool on);
7740           </programlisting>
7741           <blockquote><para>
7742       This function blanks and unblanks the screen.  It is blanked when
7743       <parameter>on</parameter> is <constant>FALSE</constant>, and unblanked when
7744       <parameter>on</parameter> is <constant>TRUE</constant>.  This function is
7745       provided for use in cases where the <structname>ScrnInfoRec</structname>
7746       can't be derived from the <structname>ScreenRec</structname> (while probing
7747       for clocks, for example).
7748             </para>
7749
7750           </blockquote></para></blockquote>
7751
7752     </sect2>
7753
7754     <sect2>
7755       <title>VGA Colormap Functions</title>
7756
7757       <para>
7758     The vgahw module uses the standard colormap support (see the
7759     <link linkend="cmap">Colormap Handling</link> section.  This is initialised
7760     with the following function:
7761
7762         <blockquote><para>
7763           <programlisting>
7764     Bool vgaHWHandleColormaps(ScreenPtr pScreen);
7765             </programlisting>
7766           </para></blockquote>
7767       </para>
7768
7769     </sect2>
7770
7771     <sect2>
7772       <title>VGA Register Access Functions</title>
7773
7774       <para>
7775     The vgahw module abstracts access to the standard VGA registers by
7776     using a set of functions held in the <structname>vgaHWRec</structname>.  When
7777     the <structname>vgaHWRec</structname> is created these function pointers are
7778     initialised with the set of standard VGA I/O register access functions.
7779     In addition to these, the vgahw module includes a basic set of MMIO
7780     register access functions, and the <structname>vgaHWRec</structname> function
7781     pointers can be initialised to these by calling the
7782     <function>vgaHWSetMmioFuncs()</function> function described above.  Some
7783     drivers/platforms may require a different set of functions for VGA
7784     access.  The access functions are described here.
7785       </para>
7786
7787
7788       <blockquote><para>
7789           <programlisting>
7790     void writeCrtc(vgaHWPtr hwp, CARD8 index, CARD8 value);
7791           </programlisting>
7792           <blockquote><para>
7793       Write <parameter>value</parameter> to CRTC register <parameter>index</parameter>.
7794             </para>
7795
7796           </blockquote></para></blockquote>
7797
7798       <blockquote><para>
7799           <programlisting>
7800     CARD8 readCrtc(vgaHWPtr hwp, CARD8 index);
7801           </programlisting>
7802           <blockquote><para>
7803       Return the value read from CRTC register <parameter>index</parameter>.
7804             </para>
7805
7806           </blockquote></para></blockquote>
7807
7808       <blockquote><para>
7809           <programlisting>
7810     void writeGr(vgaHWPtr hwp, CARD8 index, CARD8 value);
7811           </programlisting>
7812           <blockquote><para>
7813       Write <parameter>value</parameter> to Graphics Controller register
7814       <parameter>index</parameter>.
7815             </para>
7816
7817           </blockquote></para></blockquote>
7818
7819       <blockquote><para>
7820           <programlisting>
7821     CARD8 readGR(vgaHWPtr hwp, CARD8 index);
7822           </programlisting>
7823           <blockquote><para>
7824       Return the value read from Graphics Controller register
7825       <parameter>index</parameter>.
7826             </para>
7827
7828           </blockquote></para></blockquote>
7829
7830       <blockquote><para>
7831           <programlisting>
7832     void writeSeq(vgaHWPtr hwp, CARD8 index, CARD8, value);
7833           </programlisting>
7834           <blockquote><para>
7835       Write <parameter>value</parameter> to Sequencer register
7836       <parameter>index</parameter>.
7837             </para>
7838
7839           </blockquote></para></blockquote>
7840
7841       <blockquote><para>
7842           <programlisting>
7843     CARD8 readSeq(vgaHWPtr hwp, CARD8 index);
7844           </programlisting>
7845           <blockquote><para>
7846       Return the value read from Sequencer register <parameter>index</parameter>.
7847             </para>
7848
7849           </blockquote></para></blockquote>
7850
7851       <blockquote><para>
7852           <programlisting>
7853     void writeAttr(vgaHWPtr hwp, CARD8 index, CARD8, value);
7854           </programlisting>
7855           <blockquote><para>
7856       Write <parameter>value</parameter> to Attribute Controller register
7857       <parameter>index</parameter>.  When writing out the index value this
7858       function should set bit 5 (<constant>0x20</constant>) according to the
7859       setting of <structfield>hwp-&gt;paletteEnabled</structfield> in order to
7860       preserve the palette access state.  It should be cleared when
7861       <structfield>hwp-&gt;paletteEnabled</structfield> is <constant>TRUE</constant>
7862       and set when it is <constant>FALSE</constant>.
7863             </para>
7864
7865           </blockquote></para></blockquote>
7866
7867       <blockquote><para>
7868           <programlisting>
7869     CARD8 readAttr(vgaHWPtr hwp, CARD8 index);
7870           </programlisting>
7871           <blockquote><para>
7872       Return the value read from Attribute Controller register
7873       <parameter>index</parameter>.  When writing out the index value this
7874       function should set bit 5 (<constant>0x20</constant>) according to the
7875       setting of <structfield>hwp-&gt;paletteEnabled</structfield> in order to
7876       preserve the palette access state.  It should be cleared when
7877       <structfield>hwp-&gt;paletteEnabled</structfield> is <constant>TRUE</constant>
7878       and set when it is <constant>FALSE</constant>.
7879             </para>
7880
7881           </blockquote></para></blockquote>
7882
7883       <blockquote><para>
7884           <programlisting>
7885     void writeMiscOut(vgaHWPtr hwp, CARD8 value);
7886           </programlisting>
7887           <blockquote><para>
7888       Write <quote><parameter>value</parameter></quote> to the Miscellaneous Output register.
7889             </para>
7890
7891           </blockquote></para></blockquote>
7892
7893       <blockquote><para>
7894           <programlisting>
7895     CARD8 readMiscOut(vgwHWPtr hwp);
7896           </programlisting>
7897           <blockquote><para>
7898       Return the value read from the Miscellaneous Output register.
7899             </para>
7900
7901           </blockquote></para></blockquote>
7902
7903       <blockquote><para>
7904           <programlisting>
7905     void enablePalette(vgaHWPtr hwp);
7906           </programlisting>
7907           <blockquote><para>
7908       Clear the palette address source bit in the Attribute Controller
7909       index register and set <literal remap="tt">hwp-&gt;paletteEnabled</literal> to
7910       <constant>TRUE</constant>.
7911             </para>
7912
7913           </blockquote></para></blockquote>
7914
7915       <blockquote><para>
7916           <programlisting>
7917     void disablePalette(vgaHWPtr hwp);
7918           </programlisting>
7919           <blockquote><para>
7920       Set the palette address source bit in the Attribute Controller
7921       index register and set <literal remap="tt">hwp-&gt;paletteEnabled</literal> to
7922       <constant>FALSE</constant>.
7923             </para>
7924
7925           </blockquote></para></blockquote>
7926
7927       <blockquote><para>
7928           <programlisting>
7929     void writeDacMask(vgaHWPtr hwp, CARD8 value);
7930           </programlisting>
7931           <blockquote><para>
7932       Write <parameter>value</parameter> to the DAC Mask register.
7933             </para>
7934
7935           </blockquote></para></blockquote>
7936
7937       <blockquote><para>
7938           <programlisting>
7939     CARD8 readDacMask(vgaHWptr hwp);
7940           </programlisting>
7941           <blockquote><para>
7942       Return the value read from the DAC Mask register.
7943             </para>
7944
7945           </blockquote></para></blockquote>
7946
7947       <blockquote><para>
7948           <programlisting>
7949     void writeDacReadAddress(vgaHWPtr hwp, CARD8 value);
7950           </programlisting>
7951           <blockquote><para>
7952       Write <parameter>value</parameter> to the DAC Read Address register.
7953             </para>
7954
7955           </blockquote></para></blockquote>
7956
7957       <blockquote><para>
7958           <programlisting>
7959     void writeDacWriteAddress(vgaHWPtr hwp, CARD8 value);
7960           </programlisting>
7961           <blockquote><para>
7962       Write <parameter>value</parameter> to the DAC Write Address register.
7963             </para>
7964
7965           </blockquote></para></blockquote>
7966
7967       <blockquote><para>
7968           <programlisting>
7969     void writeDacData(vgaHWPtr hwp, CARD8 value);
7970           </programlisting>
7971           <blockquote><para>
7972       Write <parameter>value</parameter> to the DAC Data register.
7973             </para>
7974
7975           </blockquote></para></blockquote>
7976
7977       <blockquote><para>
7978           <programlisting>
7979     CARD8 readDacData(vgaHWptr hwp);
7980           </programlisting>
7981           <blockquote><para>
7982       Return the value read from the DAC Data register.
7983             </para>
7984
7985           </blockquote></para></blockquote>
7986
7987       <blockquote><para>
7988           <programlisting>
7989     CARD8 readEnable(vgaHWptr hwp);
7990           </programlisting>
7991           <blockquote><para>
7992       Return the value read from the VGA Enable register.  (Note: This
7993       function is present in XFree86 4.1.0 and later.)
7994             </para>
7995
7996           </blockquote></para></blockquote>
7997
7998       <blockquote><para>
7999           <programlisting>
8000     void writeEnable(vgaHWPtr hwp, CARD8 value);
8001           </programlisting>
8002           <blockquote><para>
8003       Write <parameter>value</parameter> to the VGA Enable register.  (Note: This
8004       function is present in XFree86 4.1.0 and later.)
8005             </para>
8006
8007           </blockquote></para></blockquote>
8008     </sect2>
8009   </sect1>
8010
8011   <sect1 id="sample">
8012     <title>Some notes about writing a driver</title>
8013
8014     <note><para>NOTE: some parts of this are not up to date</para></note>
8015
8016     <para>
8017 The following is an outline for writing a basic unaccelerated driver
8018 for a PCI video card with a linear mapped framebuffer, and which has a
8019 VGA core.  It is includes some general information that is relevant to
8020 most drivers (even those which don't fit that basic description).
8021     </para>
8022
8023     <para>
8024 The information here is based on the initial conversion of the Matrox
8025 Millennium driver to the <quote>new design</quote>.  For a fleshing out and sample
8026 implementation of some of the bits outlined here, refer to that driver.
8027 Note that this is an example only.  The approach used here will not be
8028 appropriate for all drivers.
8029     </para>
8030
8031     <para>
8032 Each driver must reserve a unique driver name, and a string that is used
8033 to prefix all of its externally visible symbols.  This is to avoid name
8034 space clashes when loading multiple drivers.  The examples here are for
8035 the <quote>ZZZ</quote> driver, which uses the <quote>ZZZ</quote> or <quote>zzz</quote> prefix for its externally
8036 visible symbols.
8037     </para>
8038
8039     <sect2>
8040       <title>Include files</title>
8041
8042       <para>
8043   All drivers normally include the following headers:
8044         <literallayout><filename>
8045     "xf86.h"
8046     "xf86_OSproc.h"
8047     "xf86_ansic.h"
8048     "xf86Resources.h"
8049           </filename></literallayout>
8050   Wherever inb/outb (and related things) are used the following should be
8051   included:
8052         <literallayout><filename>
8053     "compiler.h"
8054           </filename></literallayout>
8055   Note: in drivers, this must be included after <filename>"xf86_ansic.h"</filename>.
8056       </para>
8057
8058       <para>
8059   Drivers that need to access PCI vendor/device definitions need this:
8060         <literallayout><filename>
8061     "xf86PciInfo.h"
8062           </filename></literallayout>
8063       </para>
8064
8065       <para>
8066   Drivers that need to access the PCI config space need this:
8067         <literallayout><filename>
8068     "xf86Pci.h"
8069           </filename></literallayout>
8070       </para>
8071
8072       <para>
8073   Drivers using the mi banking wrapper need:
8074
8075         <literallayout><filename>
8076     "mibank.h"
8077           </filename></literallayout>
8078       </para>
8079
8080       <para>
8081   Drivers that initialise a SW cursor need this:
8082         <literallayout><filename>
8083     "mipointer.h"
8084           </filename></literallayout>
8085       </para>
8086
8087       <para>
8088   All drivers using the mi colourmap code need this:
8089         <literallayout><filename>
8090     "micmap.h"
8091           </filename></literallayout>
8092       </para>
8093
8094       <para>
8095   If a driver uses the vgahw module, it needs this:
8096         <literallayout><filename>
8097     "vgaHW.h"
8098           </filename></literallayout>
8099       </para>
8100
8101       <para>
8102   Drivers supporting VGA or Hercules monochrome screens need:
8103         <literallayout><filename>
8104     "xf1bpp.h"
8105           </filename></literallayout>
8106       </para>
8107
8108       <para>
8109   Drivers supporting VGA or EGC 16-colour screens need:
8110         <literallayout><filename>
8111     "xf4bpp.h"
8112           </filename></literallayout>
8113       </para>
8114
8115       <para>
8116   Drivers using cfb need:
8117         <programlisting>
8118     #define PSZ 8
8119     #include "cfb.h"
8120     #undef PSZ
8121         </programlisting>
8122       </para>
8123
8124       <para>
8125   Drivers supporting bpp 16, 24 or 32 with cfb need one or more of:
8126         <literallayout><filename>
8127     "cfb16.h"
8128     "cfb24.h"
8129     "cfb32.h"
8130           </filename></literallayout>
8131       </para>
8132
8133       <para>
8134   The driver's own header file:
8135         <literallayout><filename>
8136     "zzz.h"
8137           </filename></literallayout>
8138       </para>
8139
8140       <para>
8141   Drivers must NOT include the following:
8142
8143         <literallayout><filename>
8144     "xf86Priv.h"
8145     "xf86Privstr.h"
8146     "xf86_libc.h"
8147     "xf86_OSlib.h"
8148     "Xos.h"</filename>
8149     any OS header
8150         </literallayout>
8151       </para>
8152
8153     </sect2>
8154
8155     <sect2>
8156       <title>Data structures and initialisation</title>
8157
8158       <itemizedlist>
8159         <listitem>
8160           <para>The following macros should be defined:
8161             <programlisting>
8162 #define VERSION &lt;version-as-an-int&gt;
8163 #define ZZZ_NAME "ZZZ"         /* the name used to prefix messages */
8164 #define ZZZ_DRIVER_NAME "zzz"  /* the driver name as used in config file */
8165 #define ZZZ_MAJOR_VERSION &lt;int&gt;
8166 #define ZZZ_MINOR_VERSION &lt;int&gt;
8167 #define ZZZ_PATCHLEVEL    &lt;int&gt;
8168             </programlisting>
8169           </para>
8170           <para>
8171     NOTE: <constant>ZZZ_DRIVER_NAME</constant> should match the name of the
8172     driver module without things like the "lib" prefix, the "_drv" suffix
8173     or filename extensions.
8174           </para>
8175         </listitem>
8176
8177         <listitem>
8178           <para>
8179     A DriverRec must be defined, which includes the functions required
8180     at the pre-probe phase.  The name of this DriverRec must be an
8181     upper-case version of ZZZ_DRIVER_NAME (for the purposes of static
8182     linking).
8183             <programlisting>
8184 DriverRec ZZZ = {
8185     VERSION,
8186     ZZZ_DRIVER_NAME,
8187     ZZZIdentify,
8188     ZZZProbe,
8189     ZZZAvailableOptions,
8190     NULL,
8191     0
8192 };
8193             </programlisting>
8194           </para>
8195         </listitem>
8196
8197         <listitem>
8198           <para>Define list of supported chips and their matching ID:
8199             <programlisting>
8200 static SymTabRec ZZZChipsets[] = {
8201     { PCI_CHIP_ZZZ1234, "zzz1234a" },
8202     { PCI_CHIP_ZZZ5678, "zzz5678a" },
8203     { -1,               NULL }
8204 };
8205             </programlisting>
8206           </para>
8207           <para>
8208     The token field may be any integer value that the driver may use to
8209     uniquely identify the supported chipsets.  For drivers that support
8210     only PCI devices using the PCI device IDs might be a natural choice,
8211     but this isn't mandatory.  For drivers that support both PCI and other
8212     devices (like ISA), some other ID should probably used.  When other
8213     IDs are used as the tokens it is recommended that the names be
8214     defined as an <type>enum</type> type.
8215           </para>
8216         </listitem>
8217
8218         <listitem>
8219           <para>
8220     If the driver uses the <function>xf86MatchPciInstances()</function>
8221     helper (recommended for drivers that support PCI cards) a list that
8222     maps PCI IDs to chip IDs and fixed resources must be defined:
8223             <programlisting>
8224 static PciChipsets ZZZPciChipsets[] = {
8225     { PCI_CHIP_ZZZ1234, PCI_CHIP_ZZZ1234, RES_SHARED_VGA },
8226     { PCI_CHIP_ZZZ5678, PCI_CHIP_ZZZ5678, RES_SHARED_VGA },
8227     { -1,               -1,               RES_UNDEFINED }
8228 }
8229             </programlisting>
8230           </para>
8231         </listitem>
8232
8233         <listitem>
8234           <para>
8235     Define the <structname>XF86ModuleVersionInfo</structname> struct for the
8236     driver.  This is required for the dynamically loaded version:
8237             <programlisting>
8238 static XF86ModuleVersionInfo zzzVersRec =
8239 {
8240     "zzz",
8241     MODULEVENDORSTRING,
8242     MODINFOSTRING1,
8243     MODINFOSTRING2,
8244     XF86_VERSION_CURRENT,
8245     ZZZ_MAJOR_VERSION, ZZZ_MINOR_VERSION, ZZZ_PATCHLEVEL,
8246     ABI_CLASS_VIDEODRV,
8247     ABI_VIDEODRV_VERSION,
8248     MOD_CLASS_VIDEODRV,
8249     {0,0,0,0}
8250 };
8251             </programlisting>
8252           </para>
8253         </listitem>
8254
8255         <listitem>
8256           <para>
8257     Define a data structure to hold the driver's screen-specific data.
8258     This must be used instead of global variables.  This would be defined
8259     in the <filename>"zzz.h"</filename> file, something like:
8260             <programlisting>
8261 typedef struct {
8262     type1  field1;
8263     type2  field2;
8264     int    fooHack;
8265     Bool   pciRetry;
8266     Bool   noAccel;
8267     Bool   hwCursor;
8268     CloseScreenProcPtr CloseScreen;
8269     OptionInfoPtr Options;
8270     ...
8271 } ZZZRec, *ZZZPtr;
8272             </programlisting>
8273           </para>
8274         </listitem>
8275
8276         <listitem>
8277           <para>
8278     Define the list of config file Options that the driver accepts.  For
8279     consistency between drivers those in the list of <quote>standard</quote> options
8280     should be used where appropriate before inventing new options.
8281
8282             <programlisting>
8283 typedef enum {
8284     OPTION_FOO_HACK,
8285     OPTION_PCI_RETRY,
8286     OPTION_HW_CURSOR,
8287     OPTION_NOACCEL
8288 } ZZZOpts;
8289
8290 static const OptionInfoRec ZZZOptions[] = {
8291   { OPTION_FOO_HACK,  "FooHack",   OPTV_INTEGER, {0}, FALSE },
8292   { OPTION_PCI_RETRY, "PciRetry",  OPTV_BOOLEAN, {0}, FALSE },
8293   { OPTION_HW_CURSOR, "HWcursor",  OPTV_BOOLEAN, {0}, FALSE },
8294   { OPTION_NOACCEL,   "NoAccel",   OPTV_BOOLEAN, {0}, FALSE },
8295   { -1,               NULL,        OPTV_NONE,    {0}, FALSE }
8296 };
8297             </programlisting>
8298           </para>
8299         </listitem>
8300       </itemizedlist>
8301     </sect2>
8302
8303     <sect2>
8304       <title>Functions</title>
8305
8306
8307       <sect3>
8308         <title>SetupProc</title>
8309
8310         <para>
8311     For dynamically loaded modules, a <varname>ModuleData</varname>
8312     variable is required.  It is should be the name of the driver
8313     prepended to "ModuleData".  A <function>Setup()</function> function is
8314     also required, which calls <function>xf86AddDriver()</function> to add
8315     the driver to the main list of drivers.
8316         </para>
8317
8318         <programlisting>
8319 static MODULESETUPPROTO(zzzSetup);
8320
8321 XF86ModuleData zzzModuleData = { &amp;zzzVersRec, zzzSetup, NULL };
8322
8323 static pointer
8324 zzzSetup(pointer module, pointer opts, int *errmaj, int *errmin)
8325 {
8326     static Bool setupDone = FALSE;
8327
8328     /* This module should be loaded only once, but check to be sure. */
8329
8330     if (!setupDone) {
8331         /*
8332          * Modules that this driver always requires may be loaded
8333          * here  by calling LoadSubModule().
8334          */
8335
8336         setupDone = TRUE;
8337         xf86AddDriver(&amp;MGA, module, 0);
8338
8339         /*
8340          * The return value must be non-NULL on success even though
8341          * there is no TearDownProc.
8342          */
8343         return (pointer)1;
8344     } else {
8345         if (errmaj) *errmaj = LDR_ONCEONLY;
8346         return NULL;
8347     }
8348 }
8349         </programlisting>
8350       </sect3>
8351
8352       <sect3>
8353         <title>GetRec, FreeRec</title>
8354
8355         <para>
8356     A function is usually required to allocate the driver's
8357     screen-specific data structure and hook it into the
8358     <structname>ScrnInfoRec</structname>'s <structfield>driverPrivate</structfield> field.
8359     The <structname>ScrnInfoRec</structname>'s <structfield>driverPrivate</structfield> is
8360     initialised to <constant>NULL</constant>, so it is easy to check if the
8361     initialisation has already been done.  After allocating it, initialise
8362     the fields.  By using <function>xnfcalloc()</function> to do the allocation
8363     it is zeroed, and if the allocation fails the server exits.
8364         </para>
8365
8366         <para>
8367     NOTE:
8368     When allocating structures from inside the driver which are defined
8369     on the common level it is important to initialize the structure to
8370     zero.
8371     Only this guarantees that the server remains source compatible to
8372     future changes in common level structures.
8373         </para>
8374
8375         <programlisting>
8376 static Bool
8377 ZZZGetRec(ScrnInfoPtr pScrn)
8378 {
8379     if (pScrn-&gt;driverPrivate != NULL)
8380         return TRUE;
8381     pScrn-&gt;driverPrivate = xnfcalloc(sizeof(ZZZRec), 1);
8382     /* Initialise as required */
8383     ...
8384     return TRUE;
8385 }
8386         </programlisting>
8387
8388         <para>
8389     Define a macro in <filename>"zzz.h"</filename> which gets a pointer to
8390     the <structname>ZZZRec</structname> when given <parameter>pScrn</parameter>:
8391
8392           <programlisting>
8393 #define ZZZPTR(p) ((ZZZPtr)((p)-&gt;driverPrivate))
8394           </programlisting>
8395         </para>
8396
8397         <para>
8398     Define a function to free the above, setting it to <constant>NULL</constant>
8399     once it has been freed:
8400
8401           <programlisting>
8402 static void
8403 ZZZFreeRec(ScrnInfoPtr pScrn)
8404 {
8405     if (pScrn-&gt;driverPrivate == NULL)
8406         return;
8407     xfree(pScrn-&gt;driverPrivate);
8408     pScrn-&gt;driverPrivate = NULL;
8409 }
8410           </programlisting>
8411         </para>
8412       </sect3>
8413
8414       <sect3>
8415         <title>Identify</title>
8416
8417         <para>
8418     Define the <function>Identify()</function> function.  It is run before
8419     the Probe, and typically prints out an identifying message, which
8420     might include the chipsets it supports.  This function is mandatory:
8421
8422           <programlisting>
8423 static void
8424 ZZZIdentify(int flags)
8425 {
8426     xf86PrintChipsets(ZZZ_NAME, "driver for ZZZ Tech chipsets",
8427                       ZZZChipsets);
8428 }
8429           </programlisting>
8430         </para>
8431       </sect3>
8432
8433       <sect3>
8434         <title>Probe</title>
8435
8436         <para>
8437     Define the <function>Probe()</function> function.  The purpose of this
8438     is to find all instances of the hardware that the driver supports,
8439     and for the ones not already claimed by another driver, claim the
8440     slot, and allocate a <structname>ScrnInfoRec</structname>.  This should be
8441     a minimal probe, and it should under no circumstances leave the
8442     state of the hardware changed.  Because a device is found, don't
8443     assume that it will be used.  Don't do any initialisations other
8444     than the required <structname>ScrnInfoRec</structname> initialisations.
8445     Don't allocate any new data structures.
8446         </para>
8447
8448         <para>
8449     This function is mandatory.
8450         </para>
8451
8452         <para>
8453     NOTE: The <function>xf86DrvMsg()</function> functions cannot be used from
8454     the Probe.
8455         </para>
8456
8457         <programlisting>
8458 static Bool
8459 ZZZProbe(DriverPtr drv, int flags)
8460 {
8461     Bool foundScreen = FALSE;
8462     int numDevSections, numUsed;
8463     GDevPtr *devSections;
8464     int *usedChips;
8465     int i;
8466
8467     /*
8468      * Find the config file Device sections that match this
8469      * driver, and return if there are none.
8470      */
8471     if ((numDevSections = xf86MatchDevice(ZZZ_DRIVER_NAME,
8472                                           &amp;devSections)) &lt;= 0) {
8473         return FALSE;
8474     }
8475
8476     /*
8477      * Since this is a PCI card, "probing" just amounts to checking
8478      * the PCI data that the server has already collected.  If there
8479      * is none, return.
8480      *
8481      * Although the config file is allowed to override things, it
8482      * is reasonable to not allow it to override the detection
8483      * of no PCI video cards.
8484      *
8485      * The provided xf86MatchPciInstances() helper takes care of
8486      * the details.
8487      */
8488     /* test if PCI bus present */
8489     if (xf86GetPciVideoInfo()) {
8490
8491         numUsed = xf86MatchPciInstances(ZZZ_NAME, PCI_VENDOR_ZZZ,
8492                             ZZZChipsets, ZZZPciChipsets, devSections,
8493                             numDevSections, drv, &amp;usedChips);
8494
8495         for (i = 0; i &lt; numUsed; i++) {
8496             ScrnInfoPtr pScrn = NULL;
8497             if ((pScrn = xf86ConfigPciEntity(pScrn, flags, usedChips[i],
8498                                              ZZZPciChipsets, NULL, NULL,
8499                                              NULL, NULL, NULL))) {
8500                /* Allocate a ScrnInfoRec */
8501                pScrn-&gt;driverVersion = VERSION;
8502                pScrn-&gt;driverName    = ZZZ_DRIVER_NAME;
8503                pScrn-&gt;name          = ZZZ_NAME;
8504                pScrn-&gt;Probe         = ZZZProbe;
8505                pScrn-&gt;PreInit       = ZZZPreInit;
8506                pScrn-&gt;ScreenInit    = ZZZScreenInit;
8507                pScrn-&gt;SwitchMode    = ZZZSwitchMode;
8508                pScrn-&gt;AdjustFrame   = ZZZAdjustFrame;
8509                pScrn-&gt;EnterVT       = ZZZEnterVT;
8510                pScrn-&gt;LeaveVT       = ZZZLeaveVT;
8511                pScrn-&gt;FreeScreen    = ZZZFreeScreen;
8512                pScrn-&gt;ValidMode     = ZZZValidMode;
8513                foundScreen = TRUE;
8514                /* add screen to entity */
8515            }
8516         }
8517         xfree(usedChips);
8518     }
8519
8520 #ifdef HAS_ISA_DEVS
8521     /*
8522      * If the driver supports ISA hardware, the following block
8523      * can be included too.
8524      */
8525     numUsed = xf86MatchIsaInstances(ZZZ_NAME, ZZZChipsets,
8526                              ZZZIsaChipsets, drv, ZZZFindIsaDevice,
8527                              devSections, numDevSections, &amp;usedChips);
8528     for (i = 0; i &lt; numUsed; i++) {
8529         ScrnInfoPtr pScrn = NULL;
8530         if ((pScrn = xf86ConfigIsaEntity(pScrn, flags, usedChips[i],
8531                                          ZZZIsaChipsets, NULL, NULL, NULL,
8532                                          NULL, NULL))) {
8533             pScrn-&gt;driverVersion = VERSION;
8534             pScrn-&gt;driverName    = ZZZ_DRIVER_NAME;
8535             pScrn-&gt;name          = ZZZ_NAME;
8536             pScrn-&gt;Probe         = ZZZProbe;
8537             pScrn-&gt;PreInit       = ZZZPreInit;
8538             pScrn-&gt;ScreenInit    = ZZZScreenInit;
8539             pScrn-&gt;SwitchMode    = ZZZSwitchMode;
8540             pScrn-&gt;AdjustFrame   = ZZZAdjustFrame;
8541             pScrn-&gt;EnterVT       = ZZZEnterVT;
8542             pScrn-&gt;LeaveVT       = ZZZLeaveVT;
8543             pScrn-&gt;FreeScreen    = ZZZFreeScreen;
8544             pScrn-&gt;ValidMode     = ZZZValidMode;
8545             foundScreen = TRUE;
8546         }
8547     }
8548     xfree(usedChips);
8549 #endif /* HAS_ISA_DEVS */
8550
8551     xfree(devSections);
8552     return foundScreen;
8553         </programlisting>
8554       </sect3>
8555
8556       <sect3>
8557         <title>AvailableOptions</title>
8558
8559         <para>
8560     Define the <function>AvailableOptions()</function> function. The purpose
8561     of this is to return the available driver options back to the
8562     -configure option, so that an xorg.conf file can be built and the
8563     user can see which options are available for them to use.
8564         </para>
8565       </sect3>
8566
8567       <sect3>
8568         <title>PreInit</title>
8569
8570         <para>
8571     Define the <function>PreInit()</function> function.  The purpose of
8572     this is to find all the information required to determine if the
8573     configuration is usable, and to initialise those parts of the
8574     <structname>ScrnInfoRec</structname> that can be set once at the beginning
8575     of the first server generation.  The information should be found in
8576     the least intrusive way possible.
8577         </para>
8578
8579         <para>
8580     This function is mandatory.
8581         </para>
8582
8583         <para>
8584     NOTES:
8585           <orderedlist>
8586             <listitem><para>
8587          The <function>PreInit()</function> function is only called once
8588          during the life of the X server (at the start of the first
8589          generation).
8590               </para></listitem>
8591
8592             <listitem><para>
8593          Data allocated here must be of the type that persists for
8594          the life of the X server.  This means that data that hooks into
8595          the <structname>ScrnInfoRec</structname>'s <structfield>privates</structfield>
8596          field should be allocated here, but data that hooks into the
8597          <structname>ScreenRec</structname>'s <structfield>devPrivates</structfield> field
8598          should not be allocated here.  The <structfield>driverPrivate</structfield>
8599          field should also be allocated here.
8600               </para></listitem>
8601
8602             <listitem><para>
8603          Although the <structname>ScrnInfoRec</structname> has been allocated
8604          before this function is called, the <structname>ScreenRec</structname>
8605          has not been allocated.  That means that things requiring it
8606          cannot be used in this function.
8607               </para></listitem>
8608
8609             <listitem><para>
8610          Very little of the <structname>ScrnInfoRec</structname> has been
8611          initialised when this function is called.  It is important to
8612          get the order of doing things right in this function.
8613               </para></listitem>
8614
8615           </orderedlist>
8616         </para>
8617
8618         <programlisting>
8619 static Bool
8620 ZZZPreInit(ScrnInfoPtr pScrn, int flags)
8621 {
8622     /* Fill in the monitor field */
8623     pScrn-&gt;monitor = pScrn-&gt;confScreen-&gt;monitor;
8624
8625     /*
8626      * If using the vgahw module, it will typically be loaded
8627      * here by calling xf86LoadSubModule(pScrn, "vgahw");
8628      */
8629
8630     /*
8631      * Set the depth/bpp.  Use the globally preferred depth/bpp.  If the
8632      * driver has special default depth/bpp requirements, the defaults should
8633      * be specified here explicitly.
8634      * We support both 24bpp and 32bpp framebuffer layouts.
8635      * This sets pScrn-&gt;display also.
8636      */
8637     if (!xf86SetDepthBpp(pScrn, 0, 0, 0,
8638                          Support24bppFb | Support32bppFb)) {
8639         return FALSE;
8640     } else {
8641         if (depth/bpp isn't one we support) {
8642             print error message;
8643             return FALSE;
8644         }
8645     }
8646     /* Print out the depth/bpp that was set */
8647     xf86PrintDepthBpp(pScrn);
8648
8649     /* Set bits per RGB for 8bpp */
8650     if (pScrn-&gt;depth &lt;= 8) {
8651         /* Take into account a dac_6_bit option here */
8652         pScrn-&gt;rgbBits = 6 or 8;
8653     }
8654
8655     /*
8656      * xf86SetWeight() and xf86SetDefaultVisual() must be called
8657      * after pScrn-&gt;display is initialised.
8658      */
8659
8660     /* Set weight/mask/offset for depth &gt; 8 */
8661     if (pScrn-&gt;depth &gt; 8) {
8662         if (!xf86SetWeight(pScrn, defaultWeight, defaultMask)) {
8663             return FALSE;
8664         } else {
8665             if (weight isn't one we support) {
8666                 print error message;
8667                 return FALSE;
8668             }
8669         }
8670     }
8671
8672     /* Set the default visual. */
8673     if (!xf86SetDefaultVisual(pScrn, -1)) {
8674         return FALSE;
8675     } else {
8676         if (visual isn't one we support) {
8677             print error message;
8678             return FALSE;
8679         }
8680     }
8681
8682     /* If the driver supports gamma correction, set the gamma. */
8683     if (!xf86SetGamma(pScrn, default_gamma)) {
8684         return FALSE;
8685     }
8686
8687     /* This driver uses a programmable clock */
8688     pScrn-&gt;progClock = TRUE;
8689
8690     /* Allocate the ZZZRec driverPrivate */
8691     if (!ZZZGetRec(pScrn)) {
8692         return FALSE;
8693     }
8694
8695     pZzz = ZZZPTR(pScrn);
8696
8697     /* Collect all of the option flags (fill in pScrn-&gt;options) */
8698     xf86CollectOptions(pScrn, NULL);
8699
8700     /*
8701      * Process the options based on the information in ZZZOptions.
8702      * The results are written to pZzz-&gt;Options.  If all of the options
8703      * processing is done within this function a local variable "options"
8704      * can be used instead of pZzz-&gt;Options.
8705      */
8706     if (!(pZzz-&gt;Options = xalloc(sizeof(ZZZOptions))))
8707         return FALSE;
8708     (void)memcpy(pZzz-&gt;Options, ZZZOptions, sizeof(ZZZOptions));
8709     xf86ProcessOptions(pScrn-&gt;scrnIndex, pScrn-&gt;options, pZzz-&gt;Options);
8710
8711     /*
8712      * Set various fields of ScrnInfoRec and/or ZZZRec based on
8713      * the options found.
8714      */
8715     from = X_DEFAULT;
8716     pZzz-&gt;hwCursor = FALSE;
8717     if (xf86IsOptionSet(pZzz-&gt;Options, OPTION_HW_CURSOR)) {
8718         from = X_CONFIG;
8719         pZzz-&gt;hwCursor = TRUE;
8720     }
8721     xf86DrvMsg(pScrn-&gt;scrnIndex, from, "Using %s cursor\n",
8722                pZzz-&gt;hwCursor ? "HW" : "SW");
8723     if (xf86IsOptionSet(pZzz-&gt;Options, OPTION_NOACCEL)) {
8724         pZzz-&gt;noAccel = TRUE;
8725         xf86DrvMsg(pScrn-&gt;scrnIndex, X_CONFIG,
8726                    "Acceleration disabled\n");
8727     } else {
8728         pZzz-&gt;noAccel = FALSE;
8729     }
8730     if (xf86IsOptionSet(pZzz-&gt;Options, OPTION_PCI_RETRY)) {
8731         pZzz-&gt;UsePCIRetry = TRUE;
8732         xf86DrvMsg(pScrn-&gt;scrnIndex, X_CONFIG, "PCI retry enabled\n");
8733     }
8734     pZzz-&gt;fooHack = 0;
8735     if (xf86GetOptValInteger(pZzz-&gt;Options, OPTION_FOO_HACK,
8736                              &amp;pZzz-&gt;fooHack)) {
8737         xf86DrvMsg(pScrn-&gt;scrnIndex, X_CONFIG, "Foo Hack set to %d\n",
8738                    pZzz-&gt;fooHack);
8739     }
8740
8741     /*
8742      * Find the PCI slot(s) that this screen claimed in the probe.
8743      * In this case, exactly one is expected, so complain otherwise.
8744      * Note in this case we're not interested in the card types so
8745      * that parameter is set to NULL.
8746      */
8747     if ((i = xf86GetPciInfoForScreen(pScrn-&gt;scrnIndex, &amp;pciList, NULL))
8748         != 1) {
8749         print error message;
8750         ZZZFreeRec(pScrn);
8751         if (i &gt; 0)
8752             xfree(pciList);
8753         return FALSE;
8754     }
8755     /* Note that pciList should be freed below when no longer needed */
8756
8757     /*
8758      * Determine the chipset, allowing config file chipset and
8759      * chipid values to override the probed information.  The config
8760      * chipset value has precedence over its chipid value if both
8761      * are present.
8762      *
8763      * It isn't necessary to fill in pScrn-&gt;chipset if the driver
8764      * keeps track of the chipset in its ZZZRec.
8765      */
8766
8767     ...
8768
8769     /*
8770      * Determine video memory, fb base address, I/O addresses, etc,
8771      * allowing the config file to override probed values.
8772      *
8773      * Set the appropriate pScrn fields (videoRam is probably the
8774      * most important one that other code might require), and
8775      * print out the settings.
8776      */
8777
8778     ...
8779
8780     /* Initialise a clockRanges list. */
8781
8782     ...
8783
8784     /* Set any other chipset specific things in the ZZZRec */
8785
8786     ...
8787
8788     /* Select valid modes from those available */
8789
8790     i = xf86ValidateModes(pScrn, pScrn-&gt;monitor-&gt;Modes,
8791                           pScrn-&gt;display-&gt;modes, clockRanges,
8792                           NULL, minPitch, maxPitch, rounding,
8793                           minHeight, maxHeight,
8794                           pScrn-&gt;display-&gt;virtualX,
8795                           pScrn-&gt;display-&gt;virtualY,
8796                           pScrn-&gt;videoRam * 1024,
8797                           LOOKUP_BEST_REFRESH);
8798     if (i == -1) {
8799         ZZZFreeRec(pScrn);
8800         return FALSE;
8801     }
8802
8803     /* Prune the modes marked as invalid */
8804
8805     xf86PruneDriverModes(pScrn);
8806
8807     /* If no valid modes, return */
8808
8809     if (i == 0 || pScrn-&gt;modes == NULL) {
8810         print error message;
8811         ZZZFreeRec(pScrn);
8812         return FALSE;
8813     }
8814
8815     /*
8816      * Initialise the CRTC fields for the modes.  This driver expects
8817      * vertical values to be halved for interlaced modes.
8818      */
8819     xf86SetCrtcForModes(pScrn, INTERLACE_HALVE_V);
8820
8821     /* Set the current mode to the first in the list. */
8822     pScrn-&gt;currentMode = pScrn-&gt;modes;
8823
8824     /* Print the list of modes being used. */
8825     xf86PrintModes(pScrn);
8826
8827     /* Set the DPI */
8828     xf86SetDpi(pScrn, 0, 0);
8829
8830     /* Load bpp-specific modules */
8831     switch (pScrn-&gt;bitsPerPixel) {
8832     case 1:
8833         mod = "xf1bpp";
8834         break;
8835     case 4:
8836         mod = "xf4bpp";
8837         break;
8838     case 8:
8839         mod = "cfb";
8840         break;
8841     case 16:
8842         mod = "cfb16";
8843         break;
8844     case 24:
8845         mod = "cfb24";
8846         break;
8847     case 32:
8848         mod = "cfb32";
8849         break;
8850     }
8851     if (mod &amp;&amp; !xf86LoadSubModule(pScrn, mod))
8852         ZZZFreeRec(pScrn);
8853         return FALSE;
8854
8855
8856     /* Done */
8857     return TRUE;
8858 }
8859         </programlisting>
8860       </sect3>
8861
8862       <sect3>
8863         <title>MapMem, UnmapMem</title>
8864
8865         <para>
8866     Define functions to map and unmap the video memory and any other
8867     memory apertures required.  These functions are not mandatory, but
8868     it is often useful to have such functions.
8869         </para>
8870
8871         <programlisting>
8872 static Bool
8873 ZZZMapMem(ScrnInfoPtr pScrn)
8874 {
8875     /* Call xf86MapPciMem() to map each PCI memory area */
8876     ...
8877     return TRUE or FALSE;
8878 }
8879
8880 static Bool
8881 ZZZUnmapMem(ScrnInfoPtr pScrn)
8882 {
8883     /* Call xf86UnMapVidMem() to unmap each memory area */
8884     ...
8885     return TRUE or FALSE;
8886 }
8887         </programlisting>
8888       </sect3>
8889
8890       <sect3>
8891         <title>Save, Restore</title>
8892
8893         <para>
8894     Define functions to save and restore the original video state.  These
8895     functions are not mandatory, but are often useful.
8896         </para>
8897
8898         <programlisting>
8899 static void
8900 ZZZSave(ScrnInfoPtr pScrn)
8901 {
8902     /*
8903      * Save state into per-screen data structures.
8904      * If using the vgahw module, vgaHWSave will typically be
8905      * called here.
8906      */
8907     ...
8908 }
8909
8910 static void
8911 ZZZRestore(ScrnInfoPtr pScrn)
8912 {
8913     /*
8914      * Restore state from per-screen data structures.
8915      * If using the vgahw module, vgaHWRestore will typically be
8916      * called here.
8917      */
8918     ...
8919 }
8920         </programlisting>
8921       </sect3>
8922
8923       <sect3>
8924         <title>ModeInit</title>
8925
8926         <para>
8927     Define a function to initialise a new video mode.  This function isn't
8928     mandatory, but is often useful.
8929         </para>
8930
8931         <programlisting>
8932 static Bool
8933 ZZZModeInit(ScrnInfoPtr pScrn, DisplayModePtr mode)
8934 {
8935     /*
8936      * Program a video mode.  If using the vgahw module,
8937      * vgaHWInit and vgaRestore will typically be called here.
8938      * Once up to the point where there can't be a failure
8939      * set pScrn-&gt;vtSema to TRUE.
8940      */
8941     ...
8942 }
8943         </programlisting>
8944       </sect3>
8945
8946       <sect3>
8947         <title>ScreenInit</title>
8948
8949         <para>
8950     Define the <function>ScreenInit()</function> function.  This is called
8951     at the start of each server generation, and should fill in as much
8952     of the <structname>ScreenRec</structname> as possible as well as any other
8953     data that is initialised once per generation.  It should initialise
8954     the framebuffer layers it is using, and initialise the initial video
8955     mode.
8956         </para>
8957
8958         <para>
8959     This function is mandatory.
8960         </para>
8961
8962         <para>
8963     NOTE: The <structname>ScreenRec</structname> (<parameter>pScreen</parameter>) is
8964           passed to this driver, but it and the
8965           <varname>ScrnInfoRecs</varname> are not yet hooked into each
8966           other.  This means that in this function, and functions it
8967           calls, one cannot be found from the other.
8968         </para>
8969
8970         <programlisting>
8971 static Bool
8972 ZZZScreenInit(ScreenPtr pScreen, int argc, char **argv)
8973 {
8974     /* Get the ScrnInfoRec */
8975     pScrn = xf86ScreenToScrn(pScreen);
8976
8977     /*
8978      * If using the vgahw module, its data structures and related
8979      * things are typically initialised/mapped here.
8980      */
8981
8982     /* Save the current video state */
8983     ZZZSave(pScrn);
8984
8985     /* Initialise the first mode */
8986     ZZZModeInit(pScrn, pScrn-&gt;currentMode);
8987
8988     /* Set the viewport if supported */
8989
8990     ZZZAdjustFrame(pScrn, pScrn-&gt;frameX0, pScrn-&gt;frameY0);
8991
8992     /*
8993      * Setup the screen's visuals, and initialise the framebuffer
8994      * code.
8995      */
8996
8997     /* Reset the visual list */
8998     miClearVisualTypes();
8999
9000     /*
9001      * Setup the visuals supported.  This driver only supports
9002      * TrueColor for bpp &gt; 8, so the default set of visuals isn't
9003      * acceptable.  To deal with this, call miSetVisualTypes with
9004      * the appropriate visual mask.
9005      */
9006
9007     if (pScrn-&gt;bitsPerPixel &gt; 8) {
9008         if (!miSetVisualTypes(pScrn-&gt;depth, TrueColorMask,
9009                               pScrn-&gt;rgbBits, pScrn-&gt;defaultVisual))
9010             return FALSE;
9011     } else {
9012         if (!miSetVisualTypes(pScrn-&gt;depth,
9013                               miGetDefaultVisualMask(pScrn-&gt;depth),
9014                               pScrn-&gt;rgbBits, pScrn-&gt;defaultVisual))
9015             return FALSE;
9016     }
9017
9018     /*
9019      * Initialise the framebuffer.
9020      */
9021
9022     switch (pScrn-&gt;bitsPerPixel) {
9023     case 1:
9024         ret = xf1bppScreenInit(pScreen, FbBase,
9025                                pScrn-&gt;virtualX, pScrn-&gt;virtualY,
9026                                pScrn-&gt;xDpi, pScrn-&gt;yDpi,
9027                                pScrn-&gt;displayWidth);
9028         break;
9029     case 4:
9030         ret = xf4bppScreenInit(pScreen, FbBase,
9031                                pScrn-&gt;virtualX, pScrn-&gt;virtualY,
9032                                pScrn-&gt;xDpi, pScrn-&gt;yDpi,
9033                                pScrn-&gt;displayWidth);
9034         break;
9035     case 8:
9036         ret = cfbScreenInit(pScreen, FbBase,
9037                             pScrn-&gt;virtualX, pScrn-&gt;virtualY,
9038                             pScrn-&gt;xDpi, pScrn-&gt;yDpi,
9039                             pScrn-&gt;displayWidth);
9040         break;
9041     case 16:
9042         ret = cfb16ScreenInit(pScreen, FbBase,
9043                               pScrn-&gt;virtualX, pScrn-&gt;virtualY,
9044                               pScrn-&gt;xDpi, pScrn-&gt;yDpi,
9045                               pScrn-&gt;displayWidth);
9046         break;
9047     case 24:
9048         ret = cfb24ScreenInit(pScreen, FbBase,
9049                               pScrn-&gt;virtualX, pScrn-&gt;virtualY,
9050                               pScrn-&gt;xDpi, pScrn-&gt;yDpi,
9051                               pScrn-&gt;displayWidth);
9052         break;
9053     case 32:
9054         ret = cfb32ScreenInit(pScreen, FbBase,
9055                               pScrn-&gt;virtualX, pScrn-&gt;virtualY,
9056                               pScrn-&gt;xDpi, pScrn-&gt;yDpi,
9057                               pScrn-&gt;displayWidth);
9058         break;
9059     default:
9060         print a message about an internal error;
9061         ret = FALSE;
9062         break;
9063     }
9064
9065     if (!ret)
9066         return FALSE;
9067
9068     /* Override the default mask/offset settings */
9069     if (pScrn-&gt;bitsPerPixel &gt; 8) {
9070         for (i = 0, visual = pScreen-&gt;visuals;
9071              i &lt; pScreen-&gt;numVisuals; i++, visual++) {
9072             if ((visual-&gt;class | DynamicClass) == DirectColor) {
9073                 visual-&gt;offsetRed = pScrn-&gt;offset.red;
9074                 visual-&gt;offsetGreen = pScrn-&gt;offset.green;
9075                 visual-&gt;offsetBlue = pScrn-&gt;offset.blue;
9076                 visual-&gt;redMask = pScrn-&gt;mask.red;
9077                 visual-&gt;greenMask = pScrn-&gt;mask.green;
9078                 visual-&gt;blueMask = pScrn-&gt;mask.blue;
9079             }
9080         }
9081     }
9082
9083     /*
9084      * If banking is needed, initialise an miBankInfoRec (defined in
9085      * "mibank.h"), and call miInitializeBanking().
9086      */
9087     if (!miInitializeBanking(pScreen, pScrn-&gt;virtualX, pScrn-&gt;virtualY,
9088                                      pScrn-&gt;displayWidth, pBankInfo))
9089         return FALSE;
9090
9091     /*
9092      * Set initial black &amp; white colourmap indices.
9093      */
9094     xf86SetBlackWhitePixels(pScreen);
9095
9096     /*
9097      * Install colourmap functions.  If using the vgahw module,
9098      * vgaHandleColormaps would usually be called here.
9099      */
9100
9101     ...
9102
9103     /*
9104      * Initialise cursor functions.  This example is for the mi
9105      * software cursor.
9106      */
9107     miDCInitialize(pScreen, xf86GetPointerScreenFuncs());
9108
9109     /* Initialise the default colourmap */
9110     switch (pScrn-&gt;depth) {
9111     case 1:
9112         if (!xf1bppCreateDefColormap(pScreen))
9113             return FALSE;
9114         break;
9115     case 4:
9116         if (!xf4bppCreateDefColormap(pScreen))
9117             return FALSE;
9118         break;
9119     default:
9120         if (!cfbCreateDefColormap(pScreen))
9121             return FALSE;
9122         break;
9123     }
9124
9125     /*
9126      * Wrap the CloseScreen vector and set SaveScreen.
9127      */
9128     ZZZPTR(pScrn)-&gt;CloseScreen = pScreen-&gt;CloseScreen;
9129     pScreen-&gt;CloseScreen = ZZZCloseScreen;
9130     pScreen-&gt;SaveScreen = ZZZSaveScreen;
9131
9132     /* Report any unused options (only for the first generation) */
9133     if (serverGeneration == 1) {
9134         xf86ShowUnusedOptions(pScrn-&gt;scrnIndex, pScrn-&gt;options);
9135     }
9136
9137     /* Done */
9138     return TRUE;
9139 }
9140         </programlisting>
9141       </sect3>
9142
9143       <sect3>
9144         <title>SwitchMode</title>
9145
9146         <para>
9147     Define the <function>SwitchMode()</function> function if mode switching
9148     is supported by the driver.
9149         </para>
9150
9151         <programlisting>
9152 static Bool
9153 ZZZSwitchMode(ScrnInfoPtr pScrn, DisplayModePtr mode)
9154 {
9155     return ZZZModeInit(pScrn, mode);
9156 }
9157         </programlisting>
9158       </sect3>
9159
9160       <sect3>
9161         <title>AdjustFrame</title>
9162
9163         <para>
9164     Define the <function>AdjustFrame()</function> function if the driver
9165     supports this.
9166         </para>
9167
9168         <programlisting>
9169 static void
9170 ZZZAdjustFrame(ScrnInfoPtr pScrn, int x, int y)
9171 {
9172     /* Adjust the viewport */
9173 }
9174         </programlisting>
9175       </sect3>
9176
9177       <sect3>
9178         <title>EnterVT, LeaveVT</title>
9179
9180         <para>
9181     Define the <function>EnterVT()</function> and <function>LeaveVT()</function>
9182     functions.
9183         </para>
9184
9185         <para>
9186     These functions are mandatory.
9187         </para>
9188
9189         <programlisting>
9190 static Bool
9191 ZZZEnterVT(ScrnInfoPtr pScrn)
9192 {
9193     return ZZZModeInit(pScrn, pScrn-&gt;currentMode);
9194 }
9195
9196 static void
9197 ZZZLeaveVT(ScrnInfoPtr pScrn)
9198 {
9199     ZZZRestore(pScrn);
9200 }
9201         </programlisting>
9202       </sect3>
9203
9204       <sect3>
9205         <title>CloseScreen</title>
9206
9207         <para>
9208     Define the <function>CloseScreen()</function> function:
9209         </para>
9210
9211         <para>
9212     This function is mandatory.  Note that it unwraps the previously
9213     wrapped <structfield>pScreen-&gt;CloseScreen</structfield>, and finishes by
9214     calling it.
9215         </para>
9216
9217         <programlisting>
9218 static Bool
9219 ZZZCloseScreen(ScreenPtr pScreen)
9220 {
9221     ScrnInfoPtr pScrn = xf86ScreenToScrn(pScreen);
9222     if (pScrn-&gt;vtSema) {
9223         ZZZRestore(pScrn);
9224         ZZZUnmapMem(pScrn);
9225     }
9226     pScrn-&gt;vtSema = FALSE;
9227     pScreen-&gt;CloseScreen = ZZZPTR(pScrn)-&gt;CloseScreen;
9228     return (*pScreen-&gt;CloseScreen)(pScreen);
9229 }
9230         </programlisting>
9231       </sect3>
9232
9233       <sect3>
9234         <title>SaveScreen</title>
9235
9236         <para>
9237     Define the <function>SaveScreen()</function> function (the screen
9238     blanking function).  When using the vgahw module, this will typically
9239     be:
9240
9241           <programlisting>
9242 static Bool
9243 ZZZSaveScreen(ScreenPtr pScreen, int mode)
9244 {
9245     return vgaHWSaveScreen(pScreen, mode);
9246 }
9247           </programlisting>
9248         </para>
9249
9250         <para>
9251     This function is mandatory.  Before modifying any hardware register
9252     directly this function needs to make sure that the Xserver is active
9253     by checking if <parameter>pScrn</parameter> is non-NULL and for
9254     <literal remap="tt">pScrn-&gt;vtSema == TRUE</literal>.
9255         </para>
9256       </sect3>
9257
9258       <sect3>
9259         <title>FreeScreen</title>
9260
9261         <para>
9262     Define the <function>FreeScreen()</function> function.  This function
9263     is optional.  It should be defined if the <structname>ScrnInfoRec</structname>
9264     <structfield>driverPrivate</structfield> field is used so that it can be freed
9265     when a screen is deleted by the common layer for reasons possibly
9266     beyond the driver's control.  This function is not used in during
9267     normal (error free) operation.  The per-generation data is freed by
9268     the <function>CloseScreen()</function> function.
9269         </para>
9270
9271         <programlisting>
9272 static void
9273 ZZZFreeScreen(ScrnInfoPtr pScrn)
9274 {
9275     /*
9276      * If the vgahw module is used vgaHWFreeHWRec() would be called
9277      * here.
9278      */
9279     ZZZFreeRec(pScrn);
9280 }
9281
9282         </programlisting>
9283
9284       </sect3>
9285
9286     </sect2>
9287
9288   </sect1>
9289
9290 </article>