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