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