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 % defs SYSTEM "/xserver/doc/xml/xserver.ent"> %defs;
5 <!-- config file keyword markup -->
6 <!-- specific config file keywords -->
7 <!ENTITY k.device "<emphasis>Device</emphasis>">
8 <!ENTITY k.monitor "<emphasis>Monitor</emphasis>">
9 <!ENTITY k.display "<emphasis>Display</emphasis>">
10 <!ENTITY k.inputdevice "<emphasis>InputDevice</emphasis>">
11 <!ENTITY k.screen "<emphasis>Screen</emphasis>">
12 <!ENTITY k.serverlayout "<emphasis>ServerLayout</emphasis>">
13 <!ENTITY k.driver "<emphasis>Driver</emphasis>">
14 <!ENTITY k.module "<emphasis>Module</emphasis>">
15 <!ENTITY k.identifier "<emphasis>Identifier</emphasis>">
16 <!ENTITY k.serverflags "<emphasis>ServerFlags</emphasis>">
22 <title>XFree86 DDX Design (Xorg server version &xserver.version;)</title>
25 <corpauthor><ulink url="http://www.xfree86.org/">
26 The XFree86 Project, Inc.</ulink></corpauthor>
27 <corpauthor><ulink url="http://www.x.org/">
28 The X.Org Foundation, Inc.</ulink></corpauthor>
31 <firstname>Jim</firstname><surname>Gettys</surname>
32 <contrib>Updates for X11R6.7</contrib>
36 <pubdate>&xserver.reldate;</pubdate>
37 <releaseinfo>Xorg server version &xserver.version;</releaseinfo>
42 This document describes software undergoing continual evolution, and
43 the interfaces described here are subject to change without notice.
44 This document is intended to cover the interfaces as found in the
45 xorg-server-&xserver.version; release, but is probably not completely
46 in sync with the code base.
51 <title>Preface</title>
54 This document was originally the design spec for the DDX layer of the
55 XFree86 4.0 X server. The X.Org Foundation adopted the XFree86 4.4rc2
56 version of that server as the basis of the Xorg server project, and has
57 evolved the XFree86 DDX layer greatly since forking. This document thus
58 covers only the current implementation of the XFree86 DDX as found in the
59 Xorg server &xserver.version; release, and no longer matches the XFree86
64 The XFree86 Project's broad design principles for XFree86 4.0 were:
66 <listitem><para>keep it reasonable
68 <listitem><para>We cannot rewrite the complete server
70 <listitem><para>We don't want to re-invent the wheel
72 </itemizedlist></para></listitem>
73 <listitem><para>keep it modular
75 <listitem><para>As many things as possible should go into modules
77 <listitem><para>The basic loader binary should be minimal
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
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
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
95 <listitem><para>better control of the PCI device used
97 <listitem><para>better config file parser</para></listitem>
98 <listitem><para>get rid of all VGA compatibility assumptions
100 </itemizedlist></para></listitem>
105 While the XFree86 project had a goal of avoiding changes to the DIX
106 layer unless they found major deficiencies there, to avoid divergence from
107 the X.Org sample implementation they were integrating changes from, the
108 X.Org developers now maintain both sides, and make changes where they are
109 most appropriate. This document concentrates on the XFree86 DDX layer used
110 in the Xorg server itself (the code found in <filename>hw/xfree86</filename>
111 in the source tree), and developers will also want to refer to the
112 <filename>Xserver-spec</filename> documentation that covers the DIX layer
113 routines common to all the X servers in the sample implementation.
118 <title>The xorg.conf File</title>
121 The xorg.conf file format is based on the XF86Config format from XFree86 4.4,
122 which is in turn similar to the old XFree86 3.x XF86Config format, with the
127 <title>&k.device; section</title>
130 The &k.device; sections are similar to what they used to be, and
131 describe hardware-specific information for a single video card.
133 Some new keywords are added:
137 <varlistentry><term>Driver "drivername"</term>
139 Specifies the name of the driver to be used for the card. This
141 </para></listitem></varlistentry>
142 <varlistentry><term>BusID "busslot"</term>
144 Specifies uniquely the location of the card on the bus. The
145 purpose is to identify particular cards in a multi-headed
146 configuration. The format of the argument is intentionally
147 vague, and may be architecture dependent. For a PCI bus, it
148 is something like "bus:slot:func".
149 </para></listitem></varlistentry>
154 A &k.device; section is considered <quote>active</quote> if there is a reference
155 to it in an active &k.screen; section.
160 <title>&k.screen; section</title>
163 The &k.screen; sections are similar to what they used to be. They
164 no longer have a &k.driver; keyword, but an &k.identifier; keyword
165 is added. (The &k.driver; keyword may be accepted in place of the
166 &k.identifier; keyword for compatibility purposes.) The identifier
167 can be used to identify which screen is to be active when multiple
168 &k.screen; sections are present. It is possible to specify the active
169 screen from the command line. A default is chosen in the absence
170 of one being specified. A &k.screen; section is considered <quote>active</quote>
171 if there is a reference to it either from the command line, or from
172 an active &k.serverlayout; section.
177 <title>&k.inputdevice; section</title>
180 The &k.inputdevice; section is a new section that describes
181 configuration information for input devices. It replaces the old
182 <emphasis>Keyboard</emphasis>, <emphasis>Pointer</emphasis> and <emphasis>XInput</emphasis>
183 sections. Like the &k.device; section, it has two mandatory keywords:
184 &k.identifier; and &k.driver;. For compatibility purposes the old
185 <emphasis>Keyboard</emphasis> and <emphasis>Pointer</emphasis> sections are
186 converted by the parser into &k.inputdevice; sections as follows:
189 <varlistentry><term><emphasis>Keyboard</emphasis></term>
190 <listitem><literallayout>
191 &k.identifier; "Implicit Core Keyboard"
192 &k.driver; "keyboard"
193 </literallayout></listitem></varlistentry>
194 <varlistentry><term><emphasis>Pointer</emphasis></term>
195 <listitem><literallayout>
196 &k.identifier; "Implicit Core Pointer"
198 </literallayout></listitem></varlistentry>
203 An &k.inputdevice; section is considered active if there is a
204 reference to it in an active &k.serverlayout; section. An
205 &k.inputdevice; section may also be referenced implicitly if there
206 is no &k.serverlayout; section, if the <option>-screen</option> command
207 line options is used, or if the &k.serverlayout; section doesn't
208 reference any &k.inputdevice; sections. In this case, the first
209 sections with drivers "keyboard" and "mouse" are used as the core
210 keyboard and pointer respectively.
215 <title>&k.serverlayout; section</title>
218 The &k.serverlayout; section is a new section that is used to identify
219 which &k.screen; sections are to be used in a multi-headed configuration,
220 and the relative layout of those screens. It also identifies which
221 &k.inputdevice; sections are to be used. Each &k.serverlayout; section
222 has an identifier, a list of &k.screen; section identifiers, and a list of
223 &k.inputdevice; section identifiers. &k.serverflags; options may also be
224 included in a &k.serverlayout; section, making it possible to override
225 the global values in the &k.serverflags; section.
229 A &k.serverlayout; section can be made active by being referenced on
230 the command line. In the absence of this, a default will be chosen
231 (the first one found). The screen names may optionally be followed
232 by a number specifying the preferred screen number, and optionally
233 by information specifying the physical positioning of the screen,
234 either in absolute terms or relative to another screen (or screens).
235 When no screen number is specified, they are numbered according to
236 the order in which they are listed. The old (now obsolete) method
237 of providing the positioning information is to give the names of
238 the four adjacent screens. The order of these is top, bottom, left,
239 right. Here is an example of a &k.serverlayout; section for two
240 screens using the old method, with the second located to the right
244 Section "ServerLayout"
245 Identifier "Main Layout"
246 Screen 0 "Screen 1" "" "" "" "Screen 2"
254 The preferred way of specifying the layout is to explicitly specify
255 the screen's location in absolute terms or relative to another
260 In the absolute case, the upper left corner's coordinates are given
261 after the <emphasis>Absolute</emphasis> keyword. If the coordinates are
262 omitted, a value of <code>(0,0)</code> is assumed. An example
263 of absolute positioning follows:
266 Section "ServerLayout"
267 Identifier "Main Layout"
268 Screen 0 "Screen 1" Absolute 0 0
269 Screen 1 "Screen 2" Absolute 1024 0
270 Screen "Screen 3" Absolute 2048 0
276 In the relative case, the position is specified by either using one of
277 the following keywords followed by the name of the reference screen:
279 <simplelist type='vert' columns='1'>
280 <member><emphasis>RightOf</emphasis></member>
281 <member><emphasis>LeftOf</emphasis></member>
282 <member><emphasis>Above</emphasis></member>
283 <member><emphasis>Below</emphasis></member>
284 <member><emphasis>Relative</emphasis></member>
289 When the <emphasis>Relative</emphasis> keyword is used, the reference screen
290 name is followed by the coordinates of the new screen's origin
291 relative to reference screen. The following example shows how to use
292 some of the relative positioning options.
295 Section "ServerLayout"
296 Identifier "Main Layout"
298 Screen 1 "Screen 2" RightOf "Screen 1"
299 Screen "Screen 3" Relative "Screen 1" 2048 0
306 <title>Options</title>
309 Options are used more extensively. They may appear in most sections
310 now. Options related to drivers can be present in the &k.screen;,
311 &k.device; and &k.monitor; sections and the &k.display; subsections.
312 The order of precedence is &k.display;, &k.screen;, &k.monitor;,
313 &k.device;. Options have been extended to allow an optional value
314 to be specified in addition to the option name. For more details
315 about options, see the <link linkend="options">Options</link> section
322 <title>Driver Interface</title>
325 The driver interface consists of a minimal set of entry points that are
326 required based on the external events that the driver must react to.
327 No non-essential structure is imposed on the way they are used beyond
328 that. This is a significant difference compared with the old design.
332 The entry points for drawing operations are already taken care of by
333 the framebuffer code (including, XAA). Extensions and enhancements to
334 framebuffer code are outside the scope of this document.
338 This approach to the driver interface provides good flexibility, but does
339 increase the complexity of drivers. To help address this, the XFree86
340 common layer provides a set of <quote>helper</quote> functions to take care of things
341 that most drivers need. These helpers help minimise the amount of code
342 duplication between drivers. The use of helper functions by drivers is
343 however optional, though encouraged. The basic philosophy behind the
344 helper functions is that they should be useful to many drivers, that
345 they should balance this against the complexity of their interface. It
346 is inevitable that some drivers may find some helpers unsuitable and
347 need to provide their own code.
351 Events that a driver needs to react to are:
354 <varlistentry><term>ScreenInit</term>
357 An initialisation function is called from the DIX layer for each
358 screen at the start of each server generation.
359 </para></listitem></varlistentry>
361 <varlistentry><term>Enter VT</term>
364 The server takes control of the console.
365 </para></listitem></varlistentry>
367 <varlistentry><term>Leave VT</term>
370 The server releases control of the console.
371 </para></listitem></varlistentry>
373 <varlistentry><term>Mode Switch</term>
377 </para></listitem></varlistentry>
379 <varlistentry><term>ViewPort change</term>
382 Change the origin of the physical view port.
383 </para></listitem></varlistentry>
385 <varlistentry><term>ScreenSaver state change</term>
388 Screen saver activation/deactivation.
389 </para></listitem></varlistentry>
391 <varlistentry><term>CloseScreen</term>
394 A close screen function is called from the DIX layer for each screen
395 at the end of each server generation.
396 </para></listitem></varlistentry>
402 In addition to these events, the following functions are required by
403 the XFree86 common layer:
406 <varlistentry><term>Identify</term>
409 Print a driver identifying message.
410 </para></listitem></varlistentry>
412 <varlistentry><term>Probe</term>
415 This is how a driver identifies if there is any hardware present that
416 it knows how to drive.
417 </para></listitem></varlistentry>
419 <varlistentry><term>PreInit</term>
422 Process information from the xorg.conf file, determine the
423 full characteristics of the hardware, and determine if a valid
424 configuration is present.
425 </para></listitem></varlistentry>
430 The VidMode extension also requires:
433 <varlistentry><term>ValidMode</term>
436 Identify if a new mode is usable with the current configuration.
437 The PreInit function (and/or helpers it calls) may also make use
438 of the ValidMode function or something similar.
439 </para></listitem></varlistentry>
445 Other extensions may require other entry points. The drivers will
446 inform the common layer of these in such cases.
451 <title>Resource Access Control Introduction</title>
454 Graphics devices are accessed through ranges in I/O or memory space.
455 While most modern graphics devices allow relocation of such ranges many
456 of them still require the use of well established interfaces such as
457 VGA memory and IO ranges or 8514/A IO ranges. With modern buses (like
458 PCI) it is possible for multiple video devices to share access to these
459 resources. The RAC (Resource Access Control) subsystem provides a
464 <title>Terms and Definitions</title>
470 <quote>Bus</quote> is ambiguous as it is used for different things: it may refer
471 to physical incompatible extension connectors in a computer system.
472 The RAC system knows two such systems: The ISA bus and the PCI bus.
473 (On the software level EISA, MCA and VL buses are currently treated
474 like ISA buses). <quote>Bus</quote> may also refer to logically different
475 entities on a single bus system which are connected via bridges. A
476 PCI system may have several distinct PCI buses connecting each other
477 by PCI-PCI bridges or to the host CPU by HOST-PCI bridges.
481 Systems that host more than one bus system link these together using
482 bridges. Bridges are a concern to RAC as they might block or pass
483 specific resources. PCI-PCI bridges may be set up to pass VGA
484 resources to the secondary bus. PCI-ISA buses pass any resources not
485 decoded on the primary PCI bus to the ISA bus. This way VGA resources
486 (although exclusive on the ISA bus) can be shared by ISA and PCI
487 cards. Currently HOST-PCI bridges are not yet handled by RAC as they
488 require specific drivers.
493 <title>Entity</title>
496 The smallest independently addressable unit on a system bus is
497 referred to as an entity. So far we know ISA and PCI entities. PCI
498 entities can be located on the PCI bus by an unique ID consisting of
499 the bus, card and function number.
504 <title>Resource</title>
507 <quote>Resource</quote> refers to a range of memory or I/O addresses an entity
512 If a device is capable of disabling this decoding the resource is
513 called sharable. For PCI devices a generic method is provided to
514 control resource decoding. Other devices will have to provide a
515 device specific function to control decoding.
519 If the entity is capable of decoding this range at a different
520 location this resource is considered relocatable.
524 Resources which start at a specific address and occupy a single
525 continuous range are called block resources.
529 Alternatively resource addresses can be decoded in a way that they
530 satisfy the conditions:
532 address & mask == base
536 base & mask == base
538 Resources addressed in such a way are called sparse resources.
544 <title>Server States</title>
547 The resource access control system knows two server states: the
548 SETUP and the OPERATING state. The SETUP state is entered whenever
549 a mode change takes place or the server exits or does VT switching.
550 During this state all entity resources are under resource access
551 control. During OPERATING state only those entities are controlled
552 which actually have shared resources that conflict with others.
559 <title>Control Flow in the Server and Mandatory Driver Functions</title>
562 At the start of each server generation, <function>main()</function>
563 (<filename>dix/main.c</filename>) calls the DDX function
564 <function>InitOutput()</function>. This is the first place that the DDX gets
565 control. <function>InitOutput()</function> is expected to fill in the global
566 <structname>screenInfo</structname> struct, and one
567 <structfield>screenInfo.screen[]</structfield> entry for each screen present.
568 Here is what <function>InitOutput()</function> does:
572 <title>Parse the xorg.conf file</title>
575 This is done at the start of the first server generation only.
579 The xorg.conf file is read in full, and the resulting information
580 stored in data structures. None of the parsed information is
581 processed at this point. The parser data structures are opaque to
582 the video drivers and to most of the common layer code.
586 The entire file is parsed first to remove any section ordering
593 <title>Initial processing of parsed information and command line options
597 This is done at the start of the first server generation only.
601 The initial processing is to determine paths like the
602 <emphasis>ModulePath</emphasis>, etc, and to determine which &k.serverlayout;,
603 &k.screen; and &k.device; sections are active.
609 <title>Enable port I/O access</title>
612 Port I/O access is controlled from the XFree86 common layer, and is
613 <quote>all or nothing</quote>. It is enabled prior to calling driver probes, at
614 the start of subsequent server generations, and when VT switching
615 back to the Xserver. It is disabled at the end of server generations,
616 and when VT switching away from the Xserver.
620 The implementation details of this may vary on different platforms.
626 <title>General bus probe</title>
629 This is done at the start of the first server generation only.
633 In the case of ix86 machines, this will be a general PCI probe.
634 The full information obtained here will be available to the drivers.
635 This information persists for the life of the Xserver. In the PCI
636 case, the PCI information for all video cards found is available by
637 calling <function>xf86GetPciVideoInfo()</function>.
642 pciVideoPtr *xf86GetPciVideoInfo(void);
645 returns a pointer to a list of pointers to
646 <structname>pciVideoRec</structname> entries, of which there is one for
647 each detected PCI video card. The list is terminated with a
648 <constant>NULL</constant> pointer. If no PCI video cards were
649 detected, the return value is <constant>NULL</constant>.
655 After the bus probe, the resource broker is initialised.
661 <title>Load initial set of modules</title>
664 This is done at the start of the first server generation only.
668 The core server contains a list of mandatory modules. These are loaded
669 first. Currently the only module on this list is the bitmap font module.
673 The next set of modules loaded are those specified explicitly in the
674 &k.module; section of the config file.
678 The final set of initial modules are the driver modules referenced
679 by the active &k.device; and &k.inputdevice; sections in the config
680 file. Each of these modules is loaded exactly once.
686 <title>Register Video and Input Drivers</title>
689 This is done at the start of the first server generation only.
693 When a driver module is loaded, the loader calls its
694 <function>Setup</function> function. For video drivers, this function
695 calls <function>xf86AddDriver()</function> to register the driver's
696 <structname>DriverRec</structname>, which contains a small set of essential
697 details and driver entry points required during the early phase of
698 <function>InitOutput()</function>. <function>xf86AddDriver()</function>
699 adds it to the global <varname>xf86DriverList[]</varname> array.
703 The <structname>DriverRec</structname> contains the driver canonical name,
704 the <function>Identify()</function>,
705 <function>Probe()</function> and <function>AvailableOptions()</function>
706 function entry points as well as a pointer
707 to the driver's module (as returned from the loader when the driver
708 was loaded) and a reference count which keeps track of how many
709 screens are using the driver. The entry driver entry points are
710 those required prior to the driver allocating and filling in its
711 <structname>ScrnInfoRec</structname>.
715 For a static server, the <varname>xf86DriverList[]</varname> array is
716 initialised at build time, and the loading of modules is not done.
720 A similar procedure is used for input drivers. The input driver's
721 <function>Setup</function> function calls
722 <function>xf86AddInputDriver()</function> to register the driver's
723 <structname>InputDriverRec</structname>, which contains a small set of
724 essential details and driver entry points required during the early
725 phase of <function>InitInput()</function>.
726 <function>xf86AddInputDriver()</function> adds it to the global
727 <varname>xf86InputDriverList[]</varname> array. For a static server,
728 the <varname>xf86InputDriverList[]</varname> array is initialised at
733 Both the <varname>xf86DriverList[]</varname> and
734 <varname>xf86InputDriverList[]</varname> arrays have been initialised
735 by the end of this stage.
739 Once all the drivers are registered, their
740 <function>ChipIdentify()</function> functions are called.
745 void ChipIdentify(int flags);
748 This is expected to print a message indicating the driver name,
749 a short summary of what it supports, and a list of the chipset
750 names that it supports. It may use the xf86PrintChipsets() helper
757 void xf86PrintChipsets(const char *drvname, const char *drvmsg,
761 This function provides an easy way for a driver's ChipIdentify
762 function to format the identification message.
768 <title>Initialise Access Control</title>
771 This is done at the start of the first server generation only.
775 The Resource Access Control (RAC) subsystem is initialised before
776 calling any driver functions that may access hardware. All generic
777 bus information is probed and saved (for restoration later). All
778 (shared resource) video devices are disabled at the generic bus
779 level, and a probe is done to find the <quote>primary</quote> video device. These
780 devices remain disabled for the next step.
786 <title>Video Driver Probe</title>
789 This is done at the start of the first server generation only. The
790 <function>ChipProbe()</function> function of each registered video driver
796 Bool ChipProbe(DriverPtr drv, int flags);
799 The purpose of this is to identify all instances of hardware
800 supported by the driver. The flags value is currently either 0,
801 <constant>PROBE_DEFAULT</constant> or <constant>PROBE_DETECT</constant>.
802 <constant>PROBE_DETECT</constant> is used if "-configure" or "-probe"
803 command line arguments are given and indicates to the
804 <function>Probe()</function> function that it should not configure the
805 bus entities and that no xorg.conf information is available.
809 The probe must find the active device sections that match the
810 driver by calling <function>xf86MatchDevice()</function>. The number
811 of matches found limits the maximum number of instances for this
812 driver. If no matches are found, the function should return
813 <constant>FALSE</constant> immediately.
817 Devices that cannot be identified by using device-independent
818 methods should be probed at this stage (keeping in mind that access
819 to all resources that can be disabled in a device-independent way
820 are disabled during this phase). The probe must be a minimal
821 probe. It should just determine if there is a card present that
822 the driver can drive. It should use the least intrusive probe
823 methods possible. It must not do anything that is not essential,
824 like probing for other details such as the amount of memory
825 installed, etc. It is recommended that the
826 <function>xf86MatchPciInstances()</function> helper function be used
827 for identifying matching PCI devices, and similarly the
828 <function>xf86MatchIsaInstances()</function> for ISA (non-PCI) devices
829 (see the <link linkend="rac">RAC</link> section). These helpers also
830 checks and claims the appropriate entity. When not using the
831 helper, that should be done with <function>xf86CheckPciSlot()</function>
832 and <function>xf86ClaimPciSlot()</function> for PCI devices and
833 <function>xf86ClaimIsaSlot()</function> for ISA devices (see the
834 <link linkend="rac">RAC</link> section).
838 The probe must register all non-relocatable resources at this
839 stage. If a resource conflict is found between exclusive resources
840 the driver will fail immediately. This is usually best done with
841 the <function>xf86ConfigPciEntity()</function> helper function
842 for PCI and <function>xf86ConfigIsaEntity()</function> for ISA
843 (see the <link linkend="rac">RAC</link> section). It is possible to
844 register some entity specific functions with those helpers. When
845 not using the helpers, the <function>xf86AddEntityToScreen()</function>
846 <function>xf86ClaimFixedResources()</function> and
847 <function>xf86SetEntityFuncs()</function> should be used instead (see
848 the <link linkend="rac">RAC</link> section).
852 If a chipset is specified in an active device section which the
853 driver considers relevant (ie it has no driver specified, or the
854 driver specified matches the driver doing the probe), the Probe
855 must return <constant>FALSE</constant> if the chipset doesn't match
856 one supported by the driver.
860 If there are no active device sections that the driver considers
861 relevant, it must return <constant>FALSE</constant>.
865 Allocate a <structname>ScrnInfoRec</structname> for each active instance of the
866 hardware found, and fill in the basic information, including the
867 other driver entry points. This is best done with the
868 <function>xf86ConfigIsaEntity()</function> helper function for ISA
869 instances or <function>xf86ConfigPciEntity()</function> for PCI instances.
870 These functions allocate a <structname>ScrnInfoRec</structname> for active
871 entities. Optionally <function>xf86AllocateScreen()</function>
872 function may also be used to allocate the <structname>ScrnInfoRec</structname>.
873 Any of these functions take care of initialising fields to defined
874 <quote>unused</quote> values.
878 Claim the entities for each instance of the hardware found. This
879 prevents other drivers from claiming the same hardware.
883 Must leave hardware in the same state it found it in, and must not
884 do any hardware initialisation.
888 All detection can be overridden via the config file, and that
889 parsed information is available to the driver at this stage.
893 Returns <constant>TRUE</constant> if one or more instances are found,
894 and <constant>FALSE</constant> otherwise.
897 </blockquote></para></blockquote>
901 int xf86MatchDevice(const char *drivername,
902 GDevPtr **driversectlist)
905 This function takes the name of the driver and returns via
906 <parameter>driversectlist</parameter> a list of device sections that
907 match the driver name. The function return value is the number
908 of matches found. If a fatal error is encountered the return
909 value is <literal>-1</literal>.
913 The caller should use <function>xfree()</function> to free
914 <parameter>*driversectlist</parameter> when it is no longer needed.
917 </blockquote></para></blockquote>
921 ScrnInfoPtr xf86AllocateScreen(DriverPtr drv, int flags)
924 This function allocates a new <structname>ScrnInfoRec</structname> in the
925 <varname>xf86Screens[]</varname> array. This function is normally
926 called by the video driver <function>ChipProbe()</function> functions.
927 The return value is a pointer to the newly allocated
928 <structname>ScrnInfoRec</structname>. The <structfield>scrnIndex</structfield>,
929 <structfield>origIndex</structfield>, <structfield>module</structfield> and
930 <structfield>drv</structfield> fields are initialised. The reference count
931 in <parameter>drv</parameter> is incremented. The storage for any
932 currently allocated <quote>privates</quote> pointers is also allocated and
933 the <structfield>privates</structfield> field initialised (the privates data
934 is of course not allocated or initialised). This function never
935 returns on failure. If the allocation fails, the server exits
936 with a fatal error. The flags value is not currently used, and
937 should be set to zero.
942 At the completion of this, a list of <structname>ScrnInfoRecs</structname>
943 have been allocated in the <varname>xf86Screens[]</varname> array, and
944 the associated entities and fixed resources have been claimed. The
945 following <structname>ScrnInfoRec</structname> fields must be initialised at
966 <literal>(*)</literal> These are initialised when the <structname>ScrnInfoRec</structname>
967 is allocated, and not explicitly by the driver.
971 The following <structname>ScrnInfoRec</structname> fields must be initialised
972 if the driver is going to use them:
984 <title>Matching Screens</title>
987 This is done at the start of the first server generation only.
991 After the Probe phase is finished, there will be some number of
992 <structname>ScrnInfoRec</structname>s. These are then matched with the active
993 &k.screen; sections in the xorg.conf, and those not having an active
994 &k.screen; section are deleted. If the number of remaining screens
995 is 0, <function>InitOutput()</function> sets
996 <structfield>screenInfo.numScreens</structfield> to <constant>0</constant> and
1001 At this point the following fields of the <structname>ScrnInfoRec</structname>s
1002 must be initialised:
1012 <title>Allocate non-conflicting resources</title>
1015 This is done at the start of the first server generation only.
1019 Before calling the drivers again, the resource information collected
1020 from the Probe phase is processed. This includes checking the extent
1021 of PCI resources for the probed devices, and resolving any conflicts
1022 in the relocatable PCI resources. It also reports conflicts, checks
1023 bus routing issues, and anything else that is needed to enable the
1024 entities for the next phase.
1028 If any drivers registered an <function>EntityInit()</function> function
1029 during the Probe phase, then they are called here.
1035 <title>Sort the Screens and pre-check Monitor Information</title>
1038 This is done at the start of the first server generation only.
1042 The list of screens is sorted to match the ordering requested in the
1047 The list of modes for each active monitor is checked against the
1048 monitor's parameters. Invalid modes are pruned.
1054 <title>PreInit</title>
1057 This is done at the start of the first server generation only.
1061 For each <structname>ScrnInfoRec</structname>, enable access to the screens entities and call
1062 the <function>ChipPreInit()</function> function.
1067 Bool ChipPreInit(ScrnInfoRec screen, int flags);
1070 The purpose of this function is to find out all the information
1071 required to determine if the configuration is usable, and to
1072 initialise those parts of the <structname>ScrnInfoRec</structname> that
1073 can be set once at the beginning of the first server generation.
1077 The number of entities registered for the screen should be checked
1078 against the expected number (most drivers expect only one). The
1079 entity information for each of them should be retrieved (with
1080 <function>xf86GetEntityInfo()</function>) and checked for the correct
1081 bus type and that none of the sharable resources registered during
1082 the Probe phase was rejected.
1086 Access to resources for the entities that can be controlled in a
1087 device-independent way are enabled before this function is called.
1088 If the driver needs to access any resources that it has disabled
1089 in an <function>EntityInit()</function> function that it registered,
1090 then it may enable them here providing that it disables them before
1091 this function returns.
1095 This includes probing for video memory, clocks, ramdac, and all
1096 other HW info that is needed. It includes determining the
1097 depth/bpp/visual and related info. It includes validating and
1098 determining the set of video modes that will be used (and anything
1099 that is required to determine that).
1103 This information should be determined in the least intrusive way
1104 possible. The state of the HW must remain unchanged by this
1105 function. Although video memory (including MMIO) may be mapped
1106 within this function, it must be unmapped before returning. Driver
1107 specific information should be stored in a structure hooked into
1108 the <structname>ScrnInfoRec</structname>'s <structfield>driverPrivate</structfield>
1109 field. Any other modules which require persistent data (ie data
1110 that persists across server generations) should be initialised in
1111 this function, and they should allocate a <quote>privates</quote> index to
1112 hook their data into by calling
1113 <function>xf86AllocateScrnInfoPrivateIndex()</function>. The <quote>privates</quote>
1118 Helper functions for some of these things are provided at the
1119 XFree86 common level, and the driver can choose to make use of
1124 All additional resources that the screen needs must be registered
1125 here. This should be done with
1126 <function>xf86RegisterResources()</function>. If some of the fixed
1127 resources registered in the Probe phase are not needed or not
1128 decoded by the hardware when in the OPERATING server state, their
1129 status should be updated with
1130 <function>xf86SetOperatingState()</function>.
1134 Modules may be loaded at any point in this function, and all
1135 modules that the driver will need must be loaded before the end
1136 of this function. Either the <function>xf86LoadSubModule()</function>
1137 or the <function>xf86LoadDrvSubModule()</function> function should be
1138 used to load modules depending on whether a
1139 <structname>ScrnInfoRec</structname> has been set up. A driver may unload
1140 a module within this function if it was only needed temporarily,
1141 and the <function>xf86UnloadSubModule()</function> function should be used
1142 to do that. Otherwise there is no need to explicitly unload modules
1143 because the loader takes care of module dependencies and will
1144 unload submodules automatically if/when the driver module is
1149 The bulk of the <structname>ScrnInfoRec</structname> fields should be filled
1150 out in this function.
1154 <function>ChipPreInit()</function> returns <constant>FALSE</constant> when
1155 the configuration is unusable in some way (unsupported depth, no
1156 valid modes, not enough video memory, etc), and <constant>TRUE</constant>
1161 It is expected that if the <function>ChipPreInit()</function> function
1162 returns <constant>TRUE</constant>, then the only reasons that subsequent
1163 stages in the driver might fail are lack or resources (like xalloc
1164 failures). All other possible reasons for failure should be
1165 determined by the <function>ChipPreInit()</function> function.
1166 </para></blockquote>
1167 </para></blockquote>
1170 The <structname>ScrnInfoRec</structname>s for screens where the <function>ChipPreInit()</function> fails are removed.
1171 If none remain, <function>InitOutput()</function> sets <structfield>screenInfo.numScreens</structfield> to <constant>0</constant> and returns.
1175 At this point, further fields of the <structname>ScrnInfoRec</structname>s would normally be
1176 filled in. Most are not strictly mandatory, but many are required
1177 by other layers and/or helper functions that the driver may choose
1178 to use. The documentation for those layers and helper functions
1179 indicates which they require.
1183 The following fields of the <structname>ScrnInfoRec</structname>s should be filled in if the
1184 driver is going to use them:
1192 weight (>8bpp only)
1193 mask (>8bpp only)
1194 offset (>8bpp only)
1211 progClock (TRUE if clock is programmable)
1215 numClocks (if not programmable)
1216 clock[] (if not programmable)
1229 pointer xf86LoadSubModule(ScrnInfoPtr pScrn, const char *name);
1231 pointer xf86LoadDrvSubModule(DriverPtr drv, const char *name);
1234 Load a module that a driver depends on. This function loads the
1235 module <parameter>name</parameter> as a sub module of the driver. The
1236 return value is a handle identifying the new module. If the load
1237 fails, the return value will be <constant>NULL</constant>. If a driver
1238 needs to explicitly unload a module it has loaded in this way,
1239 the return value must be saved and passed to
1240 <function>xf86UnloadSubModule()</function> when unloading.
1242 </para></blockquote>
1243 </para></blockquote>
1247 void xf86UnloadSubModule(pointer module);
1250 Unloads the module referenced by <parameter>module</parameter>.
1251 <parameter>module</parameter> should be a pointer returned previously
1252 by <function>xf86LoadSubModule()</function> or
1253 <function>xf86LoadDrvSubModule()</function> .
1255 </para></blockquote>
1256 </para></blockquote>
1260 <title>Cleaning up Unused Drivers</title>
1263 At this point it is known which screens will be in use, and which
1264 drivers are being used. Unreferenced drivers (and modules they
1265 may have loaded) are unloaded here.
1271 <title>Consistency Checks</title>
1274 The parameters that must be global to the server, like pixmap formats,
1275 bitmap bit order, bitmap scanline unit and image byte order are
1276 compared for each of the screens. If a mismatch is found, the server
1277 exits with an appropriate message.
1283 <title>Check if Resource Control is Needed</title>
1286 Determine if resource access control is needed. This is the case
1287 if more than one screen is used. If necessary the RAC wrapper module
1293 <title>AddScreen (ScreenInit)</title>
1296 At this point, the valid screens are known.
1297 <function>AddScreen()</function> is called for each of them, passing
1298 <function>ChipScreenInit()</function> as the argument.
1299 <function>AddScreen()</function> is a DIX function that allocates a new
1300 <structfield>screenInfo.screen[]</structfield> entry (aka
1301 <varname>pScreen</varname>), and does some basic initialisation of it.
1302 It then calls the <function>ChipScreenInit()</function> function, with
1303 <parameter>pScreen</parameter> as one of its arguments. If
1304 <function>ChipScreenInit()</function> returns <constant>FALSE</constant>,
1305 <function>AddScreen()</function> returns <constant>-1</constant>. Otherwise
1306 it returns the index of the screen. <function>AddScreen()</function>
1307 should only fail because of programming errors or failure to allocate
1308 resources (like memory). All configuration problems should be
1309 detected BEFORE this point.
1314 Bool ChipScreenInit(int index, ScreenPtr pScreen,
1315 int argc, char **argv);
1318 This is called at the start of each server generation.
1322 Fill in all of <parameter>pScreen</parameter>, possibly doing some of
1323 this by calling ScreenInit functions from other layers like mi,
1324 framebuffers (cfb, etc), and extensions.
1328 Decide which operations need to be placed under resource access
1329 control. The classes of operations are the frame buffer operations
1330 (<constant>RAC_FB</constant>), the pointer operations
1331 (<constant>RAC_CURSOR</constant>), the viewport change operations
1332 (<constant>RAC_VIEWPORT</constant>) and the colormap operations
1333 (<constant>RAC_COLORMAP</constant>). Any operation that requires
1334 resources which might be disabled during OPERATING state should
1335 be set to use RAC. This can be specified separately for memory
1336 and IO resources (the <structfield>racMemFlags</structfield> and
1337 <structfield>racIoFlags</structfield> fields of the <structname>ScrnInfoRec</structname>
1342 Map any video memory or other memory regions.
1346 Save the video card state. Enough state must be saved so that
1347 the original state can later be restored.
1351 Initialise the initial video mode. The <structname>ScrnInfoRec</structname>'s
1352 <structfield>vtSema</structfield> field should be set to <constant>TRUE</constant>
1353 just prior to changing the video hardware's state.
1355 </para></blockquote>
1356 </para></blockquote>
1360 The <function>ChipScreenInit()</function> function (or functions from other
1361 layers that it calls) should allocate entries in the
1362 <structname>ScreenRec</structname>'s <structfield>devPrivates</structfield> area by
1363 calling <function>AllocateScreenPrivateIndex()</function> if it needs
1364 per-generation storage. Since the <structname>ScreenRec</structname>'s
1365 <structfield>devPrivates</structfield> information is cleared for each server
1366 generation, this is the correct place to initialise it.
1370 After <function>AddScreen()</function> has successfully returned, the
1371 following <structname>ScrnInfoRec</structname> fields are initialised:
1381 The <function>ChipScreenInit()</function> function should initialise the
1382 <structfield>CloseScreen</structfield> and <structfield>SaveScreen</structfield> fields
1383 of <parameter>pScreen</parameter>. The old value of
1384 <structfield>pScreen->CloseScreen</structfield> should be saved as part of
1385 the driver's per-screen private data, allowing it to be called from
1386 <function>ChipCloseScreen()</function>. This means that the existing
1387 <function>CloseScreen()</function> function is wrapped.
1392 <title>Finalising RAC Initialisation</title>
1395 After all the <function>ChipScreenInit()</function> functions have been
1396 called, each screen has registered its RAC requirements. This
1397 information is used to determine which shared resources are requested
1398 by more than one driver and set the access functions accordingly.
1399 This is done following these rules:
1403 The sharable resources registered by each entity are compared.
1404 If a resource is registered by more than one entity the entity
1405 will be marked to indicate that it needs to share this resources
1410 A resource marked <quote>disabled</quote> during OPERATING state will be
1415 A resource marked <quote>unused</quote> will only conflict with an overlapping
1416 resource of an other entity if the second is actually in use
1417 during OPERATING state.
1421 If an <quote>unused</quote> resource was found to conflict but the entity
1422 does not use any other resource of this type the entire resource
1423 type will be disabled for that entity.
1431 <title>Finishing InitOutput()</title>
1434 At this point <function>InitOutput()</function> is finished, and all the
1435 screens have been setup in their initial video mode.
1441 <title>Mode Switching</title>
1444 When a SwitchMode event is received, <function>ChipSwitchMode()</function>
1445 is called (when it exists):
1450 Bool ChipSwitchMode(int index, DisplayModePtr mode, int flags);
1453 Initialises the new mode for the screen identified by
1454 <parameter>index;</parameter>. The viewport may need to be adjusted
1457 </para></blockquote>
1458 </para></blockquote>
1463 <title>Changing Viewport</title>
1466 When a Change Viewport event is received,
1467 <function>ChipAdjustFrame()</function> is called (when it exists):
1472 void ChipAdjustFrame(int index, int x, int y, int flags);
1475 Changes the viewport for the screen identified by
1476 <parameter>index;</parameter>.
1480 It should be noted that many chipsets impose restrictions on where the
1481 viewport may be placed in the virtual resolution, either for alignment
1482 reasons, or to prevent the start of the viewport from being positioned
1483 within a pixel (as can happen in a 24bpp mode). After calculating the
1484 value the chipset's panning registers need to be set to for non-DGA
1485 modes, this function should recalculate the ScrnInfoRec's
1486 <structfield>frameX0</structfield>, <structfield>frameY0</structfield>, <structfield>frameX1</structfield>
1487 and <structfield>frameY1</structfield> fields to correspond to that value. If
1488 this is not done, switching to another mode might cause the position
1489 of a hardware cursor to change.
1491 </para></blockquote>
1492 </para></blockquote>
1497 <title>VT Switching</title>
1500 When a VT switch event is received, <function>xf86VTSwitch()</function>
1501 is called. <function>xf86VTSwitch()</function> does the following:
1504 <varlistentry><term>On ENTER:</term>
1508 enable port I/O access
1512 save and initialise the bus/resource state
1516 enter the SETUP server state
1520 calls <function>ChipEnterVT()</function> for each screen
1524 enter the OPERATING server state
1532 Restore fb from saved pixmap for each screen
1536 Enable all input devices
1542 <term>On LEAVE:</term>
1546 Save fb to pixmap for each screen
1554 enter the SETUP server state
1558 calls <function>ChipLeaveVT()</function> for each screen
1562 disable all input devices
1566 restore bus/resource state
1570 disables port I/O access
1580 Bool ChipEnterVT(int index, int flags);
1583 This function should initialise the current video mode and
1584 initialise the viewport, turn on the HW cursor if appropriate,
1589 Should it re-save the video state before initialising the video
1593 </blockquote></para></blockquote>
1597 void ChipLeaveVT(int index, int flags);
1600 This function should restore the saved video state. If
1601 appropriate it should also turn off the HW cursor, and invalidate
1602 any pixmap/font caches.
1605 </blockquote></para></blockquote>
1608 Optionally, <function>ChipLeaveVT()</function> may also unmap memory
1609 regions. If so, <function>ChipEnterVT()</function> will need to remap
1610 them. Additionally, if an aperture used to access video memory is
1611 unmapped and remapped in this fashion, <function>ChipEnterVT()</function>
1612 will also need to notify the framebuffer layers of the aperture's new
1613 location in virtual memory. This is done with a call to the screen's
1614 <function>ModifyPixmapHeader()</function> function, as follows
1619 (*pScreen->ModifyPixmapHeader)(pScrn->ppix,
1620 -1, -1, -1, -1, -1, NewApertureAddress);
1623 where the <structfield>ppix</structfield> field in a ScrnInfoRec
1624 points to the pixmap used by the screen's
1625 <function>SaveRestoreImage()</function> function to hold the screen's
1626 contents while switched out.
1629 </blockquote></para></blockquote>
1632 Currently, aperture remapping, as described here, should not be
1633 attempted if the driver uses the <literal remap="tt">xf8_16bpp</literal> or
1634 <literal remap="tt">xf8_32bpp</literal> framebuffer layers. A pending
1635 restructuring of VT switching will address this restriction in
1640 Other layers may wrap the <function>ChipEnterVT()</function> and
1641 <function>ChipLeaveVT()</function> functions if they need to take some
1642 action when these events are received.
1647 <title>End of server generation</title>
1650 At the end of each server generation, the DIX layer calls
1651 <function>ChipCloseScreen()</function> for each screen:
1656 Bool ChipCloseScreen(int index, ScreenPtr pScreen);
1659 This function should restore the saved video state and unmap the
1664 It should also free per-screen data structures allocated by the
1665 driver. Note that the persistent data held in the
1666 <structname>ScrnInfoRec</structname>'s <structfield>driverPrivate</structfield> field
1667 should not be freed here because it is needed by subsequent server
1672 The <structname>ScrnInfoRec</structname>'s <structfield>vtSema</structfield> field
1673 should be set to <constant>FALSE</constant> once the video HW state
1678 Before freeing the per-screen driver data the saved
1679 <structfield>CloseScreen</structfield> value should be restored to
1680 <structfield>pScreen->CloseScreen</structfield>, and that function should
1681 be called after freeing the data.
1683 </para></blockquote>
1684 </para></blockquote>
1689 <title>Optional Driver Functions</title>
1692 The functions outlined here can be called from the XFree86 common layer,
1693 but their presence is optional.
1697 <title>Mode Validation</title>
1700 When a mode validation helper supplied by the XFree86-common layer is
1701 being used, it can be useful to provide a function to check for hw
1702 specific mode constraints:
1707 ModeStatus ChipValidMode(int index, DisplayModePtr mode,
1708 Bool verbose, int flags);
1711 Check the passed mode for hw-specific constraints, and return the
1712 appropriate status value.
1714 </para></blockquote>
1715 </para></blockquote>
1718 This function may also modify the effective timings and clock of the passed
1719 mode. These have been stored in the mode's <structfield>Crtc*</structfield> and
1720 <structfield>SynthClock</structfield> elements, and have already been adjusted for
1721 interlacing, doublescanning, multiscanning and clock multipliers and dividers.
1722 The function should not modify any other mode field, unless it wants to modify
1723 the mode timings reported to the user by <function>xf86PrintModes()</function>.
1727 The function is called once for every mode in the xorg.conf Monitor section
1728 assigned to the screen, with <parameter>flags</parameter> set to
1729 <constant>MODECHECK_INITIAL</constant>. It is subsequently called for every mode
1730 in the xorg.conf Display subsection assigned to the screen, with
1731 <parameter>flags</parameter> set to <constant>MODECHECK_FINAL</constant>. In the second
1732 case, the mode will have successfully passed all other tests. In addition,
1733 the <structname>ScrnInfoRec</structname>'s <structfield>virtualX</structfield>,
1734 <structfield>virtualY</structfield> and <structfield>displayWidth</structfield> fields will have been
1735 set as if the mode to be validated were to be the last mode accepted.
1739 In effect, calls with MODECHECK_INITIAL are intended for checks that do not
1740 depend on any mode other than the one being validated, while calls with
1741 MODECHECK_FINAL are intended for checks that may involve more than one mode.
1746 <title>Free screen data</title>
1749 When a screen is deleted prior to the completion of the ScreenInit
1750 phase the <function>ChipFreeScreen()</function> function is called when defined.
1755 void ChipFreeScreen(int scrnindex, int flags);
1758 Free any driver-allocated data that may have been allocated up to
1759 and including an unsuccessful <function>ChipScreenInit()</function>
1760 call. This would predominantly be data allocated by
1761 <function>ChipPreInit()</function> that persists across server
1762 generations. It would include the <structfield>driverPrivate</structfield>,
1763 and any <quote>privates</quote> entries that modules may have allocated.
1765 </para></blockquote>
1766 </para></blockquote>
1772 <title>Recommended driver functions</title>
1775 The functions outlined here are for internal use by the driver only.
1776 They are entirely optional, and are never accessed directly from higher
1777 layers. The sample function declarations shown here are just examples.
1778 The interface (if any) used is up to the driver.
1785 Save the video state. This could be called from <function>ChipScreenInit()</function> and
1786 (possibly) <function>ChipEnterVT()</function>.
1791 void ChipSave(ScrnInfoPtr pScrn);
1794 Saves the current state. This will only be saving pre-server
1795 states or states before returning to the server. There is only
1796 one current saved state per screen and it is stored in private
1797 storage in the screen.
1799 </para></blockquote>
1800 </para></blockquote>
1804 <title>Restore</title>
1807 Restore the original video state. This could be called from the
1808 <function>ChipLeaveVT()</function> and <function>ChipCloseScreen()</function>
1814 void ChipRestore(ScrnInfoPtr pScrn);
1817 Restores the saved state from the private storage. Usually only
1818 used for restoring text modes.
1820 </para></blockquote>
1821 </para></blockquote>
1826 <title>Initialise Mode</title>
1829 Initialise a video mode. This could be called from the
1830 <function>ChipScreenInit()</function>, <function>ChipSwitchMode()</function>
1831 and <function>ChipEnterVT()</function> functions.
1836 Bool ChipModeInit(ScrnInfoPtr pScrn, DisplayModePtr mode);
1839 Programs the hardware for the given video mode.
1841 </para></blockquote>
1842 </para></blockquote>
1848 <title>Data and Data Structures</title>
1851 <title>Command line data</title>
1854 Command line options are typically global, and are stored in global
1855 variables. These variables are read-only and are available to drivers
1856 via a function call interface. Most of these command line values are
1857 processed via helper functions to ensure that they are treated consistently
1858 by all drivers. The other means of access is provided for cases where
1859 the supplied helper functions might not be appropriate.
1866 xf86Verbose verbosity level
1867 xf86Bpp -bpp from the command line
1868 xf86Depth -depth from the command line
1869 xf86Weight -weight from the command line
1870 xf86Gamma -{r,g,b,}gamma from the command line
1871 xf86FlipPixels -flippixels from the command line
1872 xf86ProbeOnly -probeonly from the command line
1873 defaultColorVisualClass -cc from the command line
1878 If we ever do allow for screen-specific command line options, we may
1879 need to rethink this.
1883 These can be accessed in a read-only manner by drivers with the following
1889 int xf86GetVerbosity();
1892 Returns the value of <varname>xf86Verbose</varname>.
1893 </para></blockquote>
1895 </para></blockquote>
1902 Returns the <option>-depth</option> command line setting. If not
1903 set on the command line, <constant>-1</constant> is returned.
1904 </para></blockquote>
1906 </para></blockquote>
1910 rgb xf86GetWeight();
1913 Returns the <option>-weight</option> command line setting. If not
1914 set on the command line, <literal remap="tt">{0, 0, 0}</literal> is returned.
1915 </para></blockquote>
1917 </para></blockquote>
1921 Gamma xf86GetGamma();
1924 Returns the <option>-gamma</option> or <option>-rgamma</option>,
1925 <option>-ggamma</option>, <option>-bgamma</option> command line settings.
1926 If not set on the command line, <literal remap="tt">{0.0, 0.0, 0.0}</literal>
1928 </para></blockquote>
1930 </para></blockquote>
1934 Bool xf86GetFlipPixels();
1937 Returns <constant>TRUE</constant> if <option>-flippixels</option> is
1938 present on the command line, and <constant>FALSE</constant> otherwise.
1939 </para></blockquote>
1941 </para></blockquote>
1945 const char *xf86GetServerName();
1948 Returns the name of the X server from the command line.
1949 </para></blockquote>
1951 </para></blockquote>
1955 <title>Data handling</title>
1958 Config file data contains parts that are global, and parts that are
1959 Screen specific. All of it is parsed into data structures that neither
1960 the drivers or most other parts of the server need to know about.
1964 The global data is typically not required by drivers, and as such, most
1965 of it is stored in the private <structname>xf86InfoRec</structname>.
1969 The screen-specific data collected from the config file is stored in
1970 screen, device, display, monitor-specific data structures that are separate
1971 from the <varname>ScrnInfoRecs</varname>, with the appropriate elements/fields
1972 hooked into the <varname>ScrnInfoRecs</varname> as required. The screen
1973 config data is held in <structname>confScreenRec</structname>, device data in
1974 the <structname>GDevRec</structname>, monitor data in the <structname>MonRec</structname>,
1975 and display data in the <structname>DispRec</structname>.
1979 The XFree86 common layer's screen specific data (the actual data in use
1980 for each screen) is held in the <varname>ScrnInfoRecs</varname>. As has
1981 been outlined above, the <varname>ScrnInfoRecs</varname> are allocated at probe
1982 time, and it is the responsibility of the Drivers' <function>Probe()</function>
1983 and <function>PreInit()</function> functions to finish filling them in based
1984 on both data provided on the command line and data provided from the
1985 Config file. The precedence for this is:
1988 command line -> config file -> probed/default data
1989 </para></blockquote>
1993 For most things in this category there are helper functions that the
1994 drivers can use to ensure that the above precedence is consistently
1999 As well as containing screen-specific data that the XFree86 common layer
2000 (including essential parts of the server infrastructure as well as helper
2001 functions) needs to access, it also contains some data that drivers use
2002 internally. When considering whether to add a new field to the
2003 <structname>ScrnInfoRec</structname>, consider the balance between the convenience
2004 of things that lots of drivers need and the size/obscurity of the
2005 <structname>ScrnInfoRec</structname>.
2009 Per-screen driver specific data that cannot be accommodated with the
2010 static <structname>ScrnInfoRec</structname> fields is held in a driver-defined
2011 data structure, a pointer to which is assigned to the
2012 <structname>ScrnInfoRec</structname>'s <structfield>driverPrivate</structfield> field. This
2013 is per-screen data that persists across server generations (as does the
2014 bulk of the static <structname>ScrnInfoRec</structname> data). It would typically
2015 also include the video card's saved state.
2019 Per-screen data for other modules that the driver uses (for example,
2020 the XAA module) that is reset for each server generation is hooked into
2021 the <structname>ScrnInfoRec</structname> through it's <structfield>privates</structfield>
2026 Once it has stabilised, the data structures and variables accessible to
2027 video drivers will be documented here. In the meantime, those things
2028 defined in the <filename>xf86.h</filename> and <filename>xf86str.h</filename>
2029 files are visible to video drivers. Things defined in
2030 <filename>xf86Priv.h</filename> and <filename>xf86Privstr.h</filename> are NOT
2031 intended to be visible to video drivers, and it is an error for a driver
2032 to include those files.
2038 <title>Accessing global data</title>
2041 Some other global state information that the drivers may access via
2042 functions is as follows:
2047 Bool xf86ServerIsExiting();
2050 Returns <constant>TRUE</constant> if the server is at the end of a
2051 generation and is in the process of exiting, and
2052 <constant>FALSE</constant> otherwise.
2053 </para></blockquote>
2055 </para></blockquote>
2059 Bool xf86ServerIsResetting();
2062 Returns <constant>TRUE</constant> if the server is at the end of a
2063 generation and is in the process of resetting, and
2064 <constant>FALSE</constant> otherwise.
2065 </para></blockquote>
2067 </para></blockquote>
2071 Bool xf86ServerIsInitialising();
2074 Returns <constant>TRUE</constant> if the server is at the beginning of
2075 a generation and is in the process of initialising, and
2076 <constant>FALSE</constant> otherwise.
2077 </para></blockquote>
2079 </para></blockquote>
2083 Bool xf86ServerIsOnlyProbing();
2086 Returns <constant>TRUE</constant> if the -probeonly command line flag
2087 was specified, and <constant>FALSE</constant> otherwise.
2088 </para></blockquote>
2090 </para></blockquote>
2094 Bool xf86CaughtSignal();
2097 Returns <constant>TRUE</constant> if the server has caught a signal,
2098 and <constant>FALSE</constant> otherwise.
2099 </para></blockquote>
2101 </para></blockquote>
2105 <title>Allocating private data</title>
2108 A driver and any module it uses may allocate per-screen private storage
2109 in either the <structname>ScreenRec</structname> (DIX level) or
2110 <structname>ScrnInfoRec</structname> (XFree86 common layer level).
2111 <structname>ScreenRec</structname> storage persists only for a single server
2112 generation, and <structname>ScrnInfoRec</structname> storage persists across
2113 generations for the lifetime of the server.
2117 The <structname>ScreenRec</structname> <structfield>devPrivates</structfield> data must be
2118 reallocated/initialised at the start of each new generation. This is
2119 normally done from the <function>ChipScreenInit()</function> function, and
2120 Init functions for other modules that it calls. Data allocated in this
2121 way should be freed by the driver's <function>ChipCloseScreen()</function>
2122 functions, and Close functions for other modules that it calls. A new
2123 <structfield>devPrivates</structfield> entry is allocated by calling the
2124 <function>AllocateScreenPrivateIndex()</function> function.
2129 int AllocateScreenPrivateIndex();
2132 This function allocates a new element in the
2133 <structfield>devPrivates</structfield> field of all currently existing
2134 <literal remap="tt">ScreenRecs</literal>. The return value is the index of this
2135 new element in the <structfield>devPrivates</structfield> array. The
2136 <structfield>devPrivates</structfield> field is of type
2137 <structname>DevUnion</structname>:
2140 typedef union _DevUnion {
2144 pointer (*fptr)(void);
2148 which allows the element to be used for any of the above types.
2149 It is commonly used as a pointer to data that the caller allocates
2150 after the new index has been allocated.
2154 This function will return <constant>-1</constant> when there is an
2155 error allocating the new index.
2159 </para></blockquote>
2162 The <structname>ScrnInfoRec</structname> <structfield>privates</structfield> data persists
2163 for the life of the server, so only needs to be allocated once. This
2164 should be done from the <function>ChipPreInit()</function> function, and Init
2165 functions for other modules that it calls. Data allocated in this way
2166 should be freed by the driver's <function>ChipFreeScreen()</function> functions,
2167 and Free functions for other modules that it calls. A new
2168 <structfield>privates</structfield> entry is allocated by calling the
2169 <function>xf86AllocateScrnInfoPrivateIndex()</function> function.
2174 int xf86AllocateScrnInfoPrivateIndex();
2177 This function allocates a new element in the <structfield>privates</structfield>
2178 field of all currently existing <varname>ScrnInfoRecs</varname>.
2179 The return value is the index of this new element in the
2180 <structfield>privates</structfield> array. The <structfield>privates</structfield>
2181 field is of type <structfield>DevUnion</structfield>:
2184 typedef union _DevUnion {
2188 pointer (*fptr)(void);
2192 which allows the element to be used for any of the above types.
2193 It is commonly used as a pointer to data that the caller allocates
2194 after the new index has been allocated.
2198 This function will not return when there is an error allocating
2199 the new index. When there is an error it will cause the server
2200 to exit with a fatal error. The similar function for allocation
2201 privates in the <structname>ScreenRec</structname>
2202 (<function>AllocateScreenPrivateIndex()</function>) differs in this
2203 respect by returning <constant>-1</constant> when the allocation fails.
2207 </para></blockquote>
2212 <title>Keeping Track of Bus Resources</title>
2215 <title>Theory of Operation</title>
2218 The XFree86 common layer has knowledge of generic access control mechanisms
2219 for devices on certain bus systems (currently the PCI bus) as well as
2220 of methods to enable or disable access to the buses itself. Furthermore
2221 it can access information on resources decoded by these devices and if
2222 necessary modify it.
2226 When first starting the Xserver collects all this information, saves it
2227 for restoration, checks it for consistency, and if necessary, corrects
2228 it. Finally it disables all resources on a generic level prior to
2229 calling any driver function.
2233 When the <function>Probe()</function> function of each driver is called the
2234 device sections are matched against the devices found in the system.
2235 The driver may probe devices at this stage that cannot be identified by
2236 using device independent methods. Access to all resources that can be
2237 controlled in a device independent way is disabled. The
2238 <function>Probe()</function> function should register all non-relocatable
2239 resources at this stage. If a resource conflict is found between
2240 exclusive resources the driver will fail immediately. Optionally the
2241 driver might specify an <function>EntityInit()</function>,
2242 <function>EntityLeave()</function> and <function>EntityEnter()</function> function.
2246 <function>EntityInit()</function> can be used to disable any shared resources
2247 that are not controlled by the generic access control functions. It is
2248 called prior to the PreInit phase regardless if an entity is active or
2249 not. When calling the <function>EntityInit()</function>,
2250 <function>EntityEnter()</function> and <function>EntityLeave()</function> functions
2251 the common level will disable access to all other entities on a generic
2252 level. Since the common level has no knowledge of device specific
2253 methods to disable access to resources it cannot be guaranteed that
2254 certain resources are not decoded by any other entity until the
2255 <function>EntityInit()</function> or <function>EntityEnter()</function> phase is
2256 finished. Device drivers should therefore register all those resources
2257 which they are going to disable. If these resources are never to be
2258 used by any driver function they may be flagged <constant>ResInit</constant>
2259 so that they can be removed from the resource list after processing all
2260 <function>EntityInit()</function> functions. <function>EntityEnter()</function>
2261 should disable decoding of all resources which are not registered as
2262 exclusive and which are not handled by the generic access control in
2263 the common level. The difference to <function>EntityInit()</function> is
2264 that the latter one is only called once during lifetime of the server.
2265 It can therefore be used to set up variables prior to disabling resources.
2266 <function>EntityLeave()</function> should restore the original state when
2267 exiting the server or switching to a different VT. It also needs to
2268 disable device specific access functions if they need to be disabled on
2269 server exit or VT switch. The default state is to enable them before
2274 In <function>PreInit()</function> phase each driver should check if any
2275 sharable resources it has registered during <function>Probe()</function> has
2276 been denied and take appropriate action which could simply be to fail.
2277 If it needs to access resources it has disabled during
2278 <function>EntitySetup()</function> it can do so provided it has registered
2279 these and will disable them before returning from
2280 <function>PreInit()</function>. This also applies to all other driver
2281 functions. Several functions are provided to request resource ranges,
2282 register these, correct PCI config space and add replacements for the
2283 generic access functions. Resources may be marked <quote>disabled</quote> or
2284 <quote>unused</quote> during OPERATING stage. Although these steps could also be
2285 performed in <function>ScreenInit()</function>, this is not desirable.
2289 Following <function>PreInit()</function> phase the common level determines
2290 if resource access control is needed. This is the case if more than
2291 one screen is used. If necessary the RAC wrapper module is loaded. In
2292 <function>ScreenInit()</function> the drivers can decide which operations
2293 need to be placed under RAC. Available are the frame buffer operations,
2294 the pointer operations and the colormap operations. Any operation that
2295 requires resources which might be disabled during OPERATING state should
2296 be set to use RAC. This can be specified separately for memory and IO
2301 When <function>ScreenInit()</function> phase is done the common level will
2302 determine which shared resources are requested by more than one driver
2303 and set the access functions accordingly. This is done following these
2308 The sharable resources registered by each entity are compared. If
2309 a resource is registered by more than one entity the entity will be
2310 marked to need to share this resources type (<constant>IO</constant> or
2311 <constant>MEM</constant>).
2315 A resource marked <quote>disabled</quote> during OPERATING state will be ignored
2320 A resource marked <quote>unused</quote> will only conflicts with an overlapping
2321 resource of an other entity if the second is actually in use during
2326 If an <quote>unused</quote> resource was found to conflict however the entity
2327 does not use any other resource of this type the entire resource type
2328 will be disabled for that entity.
2334 The driver has the choice among different ways to control access to
2339 It can rely on the generic access functions. This is probably the
2340 most common case. Here the driver only needs to register any resource
2345 It can replace the generic access functions by driver specific
2346 ones. This will mostly be used in cases where no generic access
2347 functions are available. In this case the driver has to make sure
2348 these resources are disabled when entering the <function>PreInit()</function>
2349 stage. Since the replacement functions are registered in
2350 <function>PreInit()</function> the driver will have to enable these
2351 resources itself if it needs to access them during this state. The
2352 driver can specify if the replacement functions can control memory
2353 and/or I/O resources separately.
2357 The driver can enable resources itself when it needs them. Each
2358 driver function enabling them needs to disable them before it will
2359 return. This should be used if a resource which can be controlled
2360 in a device dependent way is only required during SETUP state. This
2361 way it can be marked <quote>unused</quote> during OPERATING state.
2367 A resource which is decoded during OPERATING state however never accessed
2368 by the driver should be marked unused.
2372 Since access switching latencies are an issue during Xserver operation,
2373 the common level attempts to minimize the number of entities that need
2374 to be placed under RAC control. When a wrapped operation is called,
2375 the <function>EnableAccess()</function> function is called before control is
2376 passed on. <function>EnableAccess()</function> checks if a screen is under
2377 access control. If not it just establishes bus routing and returns.
2378 If the screen needs to be under access control,
2379 <function>EnableAccess()</function> determines which resource types
2380 (<literal remap="tt">MEM</literal>, <literal remap="tt">IO</literal>) are required. Then it tests
2381 if this access is already established. If so it simply returns. If
2382 not it disables the currently established access, fixes bus routing and
2383 enables access to all entities registered for this screen.
2387 Whenever a mode switch or a VT-switch is performed the common level will
2388 return to SETUP state.
2393 <title>Resource Types</title>
2396 Resource have certain properties. When registering resources each range
2397 is accompanied by a flag consisting of the ORed flags of the different
2398 properties the resource has. Each resource range may be classified
2403 its physical properties i.e., if it addresses
2404 memory (<constant>ResMem</constant>) or
2405 I/O space (<constant>ResIo</constant>),
2409 block (<constant>ResBlock</constant>) or
2410 sparse (<constant>ResSparse</constant>)
2414 its access properties.
2420 There are two known access properties:
2424 <constant>ResExclusive</constant>
2425 for resources which may not be shared with any other device and
2428 <constant>ResShared</constant>
2429 for resources which can be disabled and therefore can be shared.
2435 If it is necessary to test a resource against any type a generic access
2436 type <constant>ResAny</constant> is provided. If this is set the resource
2437 will conflict with any resource of a different entity intersecting its
2438 range. Further it can be specified that a resource is decoded however
2439 never used during any stage (<constant>ResUnused</constant>) or during
2440 OPERATING state (<constant>ResUnusedOpr</constant>). A resource only visible
2441 during the init functions (ie. <function>EntityInit()</function>,
2442 <function>EntityEnter()</function> and <function>EntityLeave()</function> should
2443 be registered with the flag <constant>ResInit</constant>. A resource that
2444 might conflict with background resource ranges may be flagged with
2445 <constant>ResBios</constant>. This might be useful when registering resources
2446 ranges that were assigned by the system Bios.
2450 Several predefined resource lists are available for VGA and 8514/A
2451 resources in <filename>common/xf86Resources.h</filename>.
2456 <title>Available Functions</title>
2459 The functions provided for resource management are listed in their order
2460 of use in the driver.
2464 <title>Probe Phase</title>
2467 In this phase each driver detects those resources it is able to drive,
2468 creates an entity record for each of them, registers non-relocatable
2469 resources and allocates screens and adds the resources to screens.
2473 Two helper functions are provided for matching device sections in the
2474 xorg.conf file to the devices:
2479 int xf86MatchPciInstances(const char *driverName, int vendorID,
2480 SymTabPtr chipsets, PciChipsets *PCIchipsets,
2481 GDevPtr *devList, int numDevs, DriverPtr drvp,
2482 int **foundEntities);
2485 This function finds matches between PCI cards that a driver supports
2486 and config file device sections. It is intended for use in the
2487 <function>ChipProbe()</function> function of drivers for PCI cards.
2488 Only probed PCI devices with a vendor ID matching
2489 <parameter>vendorID</parameter> are considered. <parameter>devList</parameter>
2490 and <parameter>numDevs</parameter> are typically those found from
2491 calling <function>xf86MatchDevice()</function>, and represent the active
2492 config file device sections relevant to the driver.
2493 <parameter>PCIchipsets</parameter> is a table that provides a mapping
2494 between the PCI device IDs, the driver's internal chipset tokens
2495 and a list of fixed resources.
2499 When a device section doesn't have a <emphasis>BusID</emphasis> entry it
2500 can only match the primary video device. Secondary devices are
2501 only matched with device sections that have a matching
2502 <emphasis>BusID</emphasis> entry.
2506 Once the preliminary matches have been found, a final match is
2507 confirmed by checking if the chipset override, ChipID override or
2508 probed PCI chipset type match one of those given in the
2509 <parameter>chipsets</parameter> and <parameter>PCIchipsets</parameter> lists.
2510 The <parameter>PCIchipsets</parameter> list includes a list of the PCI
2511 device IDs supported by the driver. The list should be terminated
2512 with an entry with PCI ID <constant>-1</constant>". The
2513 <parameter>chipsets</parameter> list is a table mapping the driver's
2514 internal chipset tokens to names, and should be terminated with
2515 a <constant>NULL</constant> entry. Only those entries with a
2516 corresponding entry in the <parameter>PCIchipsets</parameter> list are
2517 considered. The order of precedence is: config file chipset,
2518 config file ChipID, probed PCI device ID.
2522 In cases where a driver handles PCI chipsets with more than one
2523 vendor ID, it may set <parameter>vendorID</parameter> to
2524 <constant>0</constant>, and OR each devID in the list with (the
2525 vendor ID << 16).
2529 Entity index numbers for confirmed matches are returned as an
2530 array via <parameter>foundEntities</parameter>. The PCI information,
2531 chipset token and device section for each match are found in the
2532 <structname>EntityInfoRec</structname> referenced by the indices.
2536 The function return value is the number of confirmed matches. A
2537 return value of <constant>-1</constant> indicates an internal error.
2538 The returned <parameter>foundEntities</parameter> array should be freed
2539 by the driver with <function>xfree()</function> when it is no longer
2540 needed in cases where the return value is greater than zero.
2543 </blockquote></para></blockquote>
2547 int xf86MatchIsaInstances(const char *driverName,
2548 SymTabPtr chipsets, IsaChipsets *ISAchipsets,
2549 DriverPtr drvp, FindIsaDevProc FindIsaDevice,
2550 GDevPtr *devList, int numDevs,
2551 int **foundEntities);
2554 This function finds matches between ISA cards that a driver supports
2555 and config file device sections. It is intended for use in the
2556 <function>ChipProbe()</function> function of drivers for ISA cards.
2557 <parameter>devList</parameter> and <parameter>numDevs</parameter> are
2558 typically those found from calling <function>xf86MatchDevice()</function>,
2559 and represent the active config file device sections relevant to
2560 the driver. <parameter>ISAchipsets</parameter> is a table that provides
2561 a mapping between the driver's internal chipset tokens and the
2562 resource classes. <parameter>FindIsaDevice</parameter> is a
2563 driver-provided function that probes the hardware and returns the
2564 chipset token corresponding to what was detected, and
2565 <constant>-1</constant> if nothing was detected.
2569 If the config file device section contains a chipset entry, then
2570 it is checked against the <parameter>chipsets</parameter> list. When
2571 no chipset entry is present, the <parameter>FindIsaDevice</parameter>
2572 function is called instead.
2576 Entity index numbers for confirmed matches are returned as an
2577 array via <parameter>foundEntities</parameter>. The chipset token and
2578 device section for each match are found in the
2579 <structname>EntityInfoRec</structname> referenced by the indices.
2583 The function return value is the number of confirmed matches. A
2584 return value of <constant>-1</constant> indicates an internal error.
2585 The returned <parameter>foundEntities</parameter> array should be freed
2586 by the driver with <function>xfree()</function> when it is no longer
2587 needed in cases where the return value is greater than zero.
2590 </blockquote></para></blockquote>
2593 These two helper functions make use of several core functions that are
2594 available at the driver level:
2599 Bool xf86ParsePciBusString(const char *busID, int *bus,
2600 int *device, int *func);
2603 Takes a <parameter>BusID</parameter> string, and if it is in the correct
2604 format, returns the PCI <parameter>bus</parameter>, <parameter>device</parameter>,
2605 <parameter>func</parameter> values that it indicates. The format of the
2606 string is expected to be "PCI:bus:device:func" where each of <quote>bus</quote>,
2607 <quote>device</quote> and <quote>func</quote> are decimal integers. The ":func" part may
2608 be omitted, and the func value assumed to be zero, but this isn't
2609 encouraged. The "PCI" prefix may also be omitted. The prefix
2610 "AGP" is currently equivalent to the "PCI" prefix. If the string
2611 isn't a valid PCI BusID, the return value is <constant>FALSE</constant>.
2614 </blockquote></para></blockquote>
2618 Bool xf86ComparePciBusString(const char *busID, int bus,
2619 int device, int func);
2622 Compares a <parameter>BusID</parameter> string with PCI <parameter>bus</parameter>,
2623 <parameter>device</parameter>, <parameter>func</parameter> values. If they
2624 match <constant>TRUE</constant> is returned, and <constant>FALSE</constant>
2628 </blockquote></para></blockquote>
2632 Bool xf86ParseIsaBusString(const char *busID);
2635 Compares a <parameter>BusID</parameter> string with the ISA bus ID string
2636 ("ISA" or "ISA:"). If they match <constant>TRUE</constant> is returned,
2637 and <constant>FALSE</constant> if they don't.
2640 </blockquote></para></blockquote>
2644 Bool xf86CheckPciSlot(int bus, int device, int func);
2647 Checks if the PCI slot <literal remap="tt">bus:device:func</literal> has been
2648 claimed. If so, it returns <constant>FALSE</constant>, and otherwise
2649 <constant>TRUE</constant>.
2652 </blockquote></para></blockquote>
2656 int xf86ClaimPciSlot(int bus, int device, int func, DriverPtr drvp,
2657 int chipset, GDevPtr dev, Bool active);
2660 This function is used to claim a PCI slot, allocate the associated
2661 entity record and initialise their data structures. The return
2662 value is the index of the newly allocated entity record, or
2663 <constant>-1</constant> if the claim fails. This function should always
2664 succeed if <function>xf86CheckPciSlot()</function> returned
2665 <constant>TRUE</constant> for the same PCI slot.
2668 </blockquote></para></blockquote>
2672 Bool xf86IsPrimaryPci(void);
2675 This function returns <constant>TRUE</constant> if the primary card is
2676 a PCI device, and <constant>FALSE</constant> otherwise.
2679 </blockquote></para></blockquote>
2683 int xf86ClaimIsaSlot(DriverPtr drvp, int chipset,
2684 GDevPtr dev, Bool active);
2687 This allocates an entity record entity and initialise the data
2688 structures. The return value is the index of the newly allocated
2692 </blockquote></para></blockquote>
2696 Bool xf86IsPrimaryIsa(void);
2699 This function returns <constant>TRUE</constant> if the primary card is
2700 an ISA (non-PCI) device, and <constant>FALSE</constant> otherwise.
2703 </blockquote></para></blockquote>
2706 Two helper functions are provided to aid configuring entities:
2711 ScrnInfoPtr xf86ConfigPciEntity(ScrnInfoPtr pScrn,
2712 int scrnFlag, int entityIndex,
2713 PciChipsets *p_chip,
2714 resList res, EntityProc init,
2715 EntityProc enter, EntityProc leave,
2718 ScrnInfoPtr xf86ConfigIsaEntity(ScrnInfoPtr pScrn,
2719 int scrnFlag, int entityIndex,
2720 IsaChipsets *i_chip,
2721 resList res, EntityProc init,
2722 EntityProc enter, EntityProc leave,
2726 These functions are used to register the non-relocatable resources
2727 for an entity, and the optional entity-specific <parameter>Init</parameter>, <parameter>Enter</parameter> and
2728 <parameter>Leave</parameter> functions. Usually the list of fixed resources is obtained
2729 from the Isa/PciChipsets lists. However an additional list of
2730 resources may be passed. Generally this is not required.
2731 For active entities a <structname>ScrnInfoRec</structname> is allocated
2732 if the <parameter>pScrn</parameter> argument is <constant>NULL</constant>.
2734 return value is <constant>TRUE</constant> when successful. The init, enter, leave
2735 functions are defined as follows:
2739 typedef void (*EntityProc)(int entityIndex,
2742 </para></blockquote>
2744 They are passed the entity index and a pointer to a private scratch
2745 area. This can be set up during <function>Probe()</function> and
2746 its address can be passed to
2747 <function>xf86ConfigIsaEntity()</function> and
2748 <function>xf86ConfigPciEntity()</function> as the last argument.
2751 </blockquote></para></blockquote>
2754 These two helper functions make use of several core functions that are
2755 available at the driver level:
2759 void xf86ClaimFixedResources(resList list, int entityIndex);
2762 This function registers the non-relocatable resources which cannot
2763 be disabled and which therefore would cause the server to fail
2764 immediately if they were found to conflict. It also records
2765 non-relocatable but sharable resources for processing after the
2766 <function>Probe()</function> phase.
2769 </blockquote></para></blockquote>
2773 Bool xf86SetEntityFuncs(int entityIndex, EntityProc init,
2774 EntityProc enter, EntityProc leave, pointer);
2777 This function registers with an entity the <parameter>init</parameter>,
2778 <parameter>enter</parameter>, <parameter>leave</parameter> functions along
2779 with the pointer to their private area.
2782 </blockquote></para></blockquote>
2786 void xf86AddEntityToScreen(ScrnInfoPtr pScrn, int entityIndex);
2789 This function associates the entity referenced by
2790 <parameter>entityIndex</parameter> with the screen.
2793 </blockquote></para></blockquote>
2798 <title>PreInit Phase</title>
2801 During this phase the remaining resources should be registered.
2802 <function>PreInit()</function> should call <function>xf86GetEntityInfo()</function>
2803 to obtain a pointer to an <structname>EntityInfoRec</structname> for each entity
2804 it is able to drive and check if any resource are listed in its
2805 <structfield>resources</structfield> field. If resources registered in the Probe
2806 phase have been rejected in the post-Probe phase
2807 (<structfield>resources</structfield> is non-<constant>NULL</constant>), then the driver should
2808 decide if it can continue without using these or if it should fail.
2813 EntityInfoPtr xf86GetEntityInfo(int entityIndex);
2816 This function returns a pointer to the <structname>EntityInfoRec</structname>
2817 referenced by <parameter>entityIndex</parameter>. The returned
2818 <structname>EntityInfoRec</structname> should be freed with
2819 <function>xfree()</function> when no longer needed.
2822 </blockquote></para></blockquote>
2825 Several functions are provided to simplify resource registration:
2828 Bool xf86IsEntityPrimary(int entityIndex);
2831 This function returns <constant>TRUE</constant> if the entity referenced
2832 by <parameter>entityIndex</parameter> is the primary display device (i.e.,
2833 the one initialised at boot time and used in text mode).
2836 </blockquote></para></blockquote>
2840 Bool xf86IsScreenPrimary(int scrnIndex);
2843 This function returns <constant>TRUE</constant> if the primary entity
2844 is registered with the screen referenced by
2845 <parameter>scrnIndex</parameter>.
2848 </blockquote></para></blockquote>
2852 pciVideoPtr xf86GetPciInfoForEntity(int entityIndex);
2855 This function returns a pointer to the <structname>pciVideoRec</structname>
2856 for the specified entity. If the entity is not a PCI device,
2857 <constant>NULL</constant> is returned.
2860 </blockquote></para></blockquote>
2864 The primary function for registration of resources is:
2867 resPtr xf86RegisterResources(int entityIndex, resList list,
2871 This function tries to register the resources in
2872 <parameter>list</parameter>. If list is <constant>NULL</constant> it tries
2873 to determine the resources automatically. This only works for
2874 entities that provide a generic way to read out the resource ranges
2875 they decode. So far this is only the case for PCI devices. By
2876 default the PCI resources are registered as shared
2877 (<constant>ResShared</constant>) if the driver wants to set a different
2878 access type it can do so by specifying the access flags in the
2879 third argument. A value of <constant>0</constant> means to use the
2880 default settings. If for any reason the resource broker is not
2881 able to register some of the requested resources the function will
2882 return a pointer to a list of the failed ones. In this case the
2883 driver may be able to move the resource to different locations.
2884 In case of PCI bus entities this is done by passing the list of
2885 failed resources to <function>xf86ReallocatePciResources()</function>.
2886 When the registration succeeds, the return value is
2887 <constant>NULL</constant>.
2890 </blockquote></para></blockquote>
2895 resPtr xf86ReallocatePciResources(int entityIndex, resPtr pRes);
2898 This function takes a list of PCI resources that need to be
2899 reallocated and returns <constant>NULL</constant> when all relocations are
2901 <function>xf86RegisterResources()</function> should be called again to
2902 register the relocated resources with the broker.
2903 If the reallocation fails, a list of the resources that could not be
2904 relocated is returned.
2907 </blockquote></para></blockquote>
2910 Two functions are provided to obtain a resource range of a given type:
2913 resRange xf86GetBlock(long type, memType size,
2914 memType window_start, memType window_end,
2915 memType align_mask, resPtr avoid);
2918 This function tries to find a block range of size
2919 <parameter>size</parameter> and type <parameter>type</parameter> in a window
2920 bound by <parameter>window_start</parameter> and <parameter>window_end</parameter>
2921 with the alignment specified in <parameter>align_mask</parameter>.
2922 Optionally a list of resource ranges which should be avoided within
2923 the window can be supplied. On failure a zero-length range of
2924 type <constant>ResEnd</constant> will be returned.
2926 </blockquote></para></blockquote>
2930 resRange xf86GetSparse(long type, memType fixed_bits,
2931 memType decode_mask, memType address_mask,
2935 This function is like the previous one, but attempts to find a
2936 sparse range instead of a block range. Here three values have to
2937 be specified: the <parameter>address_mask</parameter> which marks all
2938 bits of the mask part of the address, the <parameter>decode_mask</parameter>
2939 which masks out the bits which are hardcoded and are therefore
2940 not available for relocation and the values of the fixed bits.
2941 The function tries to find a base that satisfies the given condition.
2942 If the function fails it will return a zero range of type
2943 <constant>ResEnd</constant>. Optionally it might be passed a list of
2944 resource ranges to avoid.
2947 </blockquote></para></blockquote>
2951 Some PCI devices are broken in the sense that they return invalid size
2952 information for a certain resource. In this case the driver can supply
2953 the correct size and make sure that the resource range allocated for
2954 the card is large enough to hold the address range decoded by the card.
2955 The function <function>xf86FixPciResource()</function> can be used to do this:
2958 Bool xf86FixPciResource(int entityIndex, unsigned int prt,
2959 CARD32 alignment, long type);
2962 This function fixes a PCI resource allocation. The
2963 <parameter>prt</parameter> parameter contains the number of the PCI base
2964 register that needs to be fixed (<constant>0-5</constant>, and
2965 <constant>6</constant> for the BIOS base register). The size is
2966 specified by the alignment. Since PCI resources need to span an
2967 integral range of size <literal remap="tt">2ˆn</literal>, the alignm ent also
2968 specifies the number of addresses that will be decoded. If the
2969 driver specifies a type mask it can override the default type for
2970 PCI resources which is <constant>ResShared</constant>. The resource
2971 broker needs to know that to find a matching resource range. This
2972 function should be called before calling
2973 <function>xf86RegisterResources()</function>. The return value is
2974 <constant>TRUE</constant> when the function succeeds.
2977 </blockquote></para></blockquote>
2981 Bool xf86CheckPciMemBase(pciVideoPtr pPci, memType base);
2984 This function checks that the memory base address specified matches
2985 one of the PCI base address register values for the given PCI
2986 device. This is mostly used to check that an externally provided
2987 base address (e.g., from a config file) matches an actual value
2988 allocated to a device.
2991 </blockquote></para></blockquote>
2995 The driver may replace the generic access control functions for an entity.
2996 This is done with the <function>xf86SetAccessFuncs()</function>:
2999 void xf86SetAccessFuncs(EntityInfoPtr pEnt,
3000 xf86SetAccessFuncPtr funcs,
3001 xf86SetAccessFuncPtr oldFuncs);
3008 xf86AccessPtr io_mem;
3009 } xf86SetAccessFuncRec, *xf86SetAccessFuncPtr;
3012 The driver can pass three functions: one for I/O access, one for
3013 memory access and one for combined memory and I/O access. If the
3014 memory access and combined access functions are identical the
3015 common level assumes that the memory access cannot be controlled
3016 independently of I/O access, if the I/O access function and the
3017 combined access functions are the same it is assumed that I/O can
3018 not be controlled independently. If memory and I/O have to be
3019 controlled together all three values should be the same. If a
3020 non <constant>NULL</constant> value is passed as third argument it is
3021 interpreted as an address where to store the old access record.
3022 If the third argument is <constant>NULL</constant> it will be assumed
3023 that the generic access should be enabled before replacing the
3024 access functions. Otherwise it will be disabled. The driver may
3025 enable them itself using the returned values. It should do this
3026 from its replacement access functions as the generic access may
3027 be disabled by the common level on certain occasions. If replacement
3028 functions are specified they must control all resources of the
3029 specific type registered for the entity.
3032 </blockquote></para></blockquote>
3036 To find out if a specific resource range conflicts with another
3037 resource the <function>xf86ChkConflict()</function> function may be used:
3040 memType xf86ChkConflict(resRange *rgp, int entityIndex);
3043 This function checks if the resource range <parameter>rgp</parameter> of
3044 for the specified entity conflicts with with another resource.
3045 If a conflict is found, the address of the start of the conflict
3046 is returned. The return value is zero when there is no conflict.
3049 </blockquote></para></blockquote>
3053 The OPERATING state properties of previously registered fixed resources
3054 can be set with the <function>xf86SetOperatingState()</function> function:
3057 resPtr xf86SetOperatingState(resList list, int entityIndex,
3061 This function is used to set the status of a resource during
3062 OPERATING state. <parameter>list</parameter> holds a list to which
3063 <parameter>mask</parameter> is to be applied. The parameter
3064 <parameter>mask</parameter> may have the value <constant>ResUnusedOpr</constant>
3065 and <constant>ResDisableOpr</constant>. The first one should be used
3066 if a resource isn't used by the driver during OPERATING state
3067 although it is decoded by the device, while the latter one indicates
3068 that the resource is not decoded during OPERATING state. Note
3069 that the resource ranges have to match those specified during
3070 registration. If a range has been specified starting at
3071 <literal remap="tt">A</literal> and ending at <literal remap="tt">B</literal> and suppose
3072 <literal remap="tt">C</literal> us a value satisfying
3073 <literal remap="tt">A < C < B</literal> one may not
3074 specify the resource range <literal remap="tt">(A,B)</literal> by splitting it
3075 into two ranges <literal remap="tt">(A,C)</literal> and <literal remap="tt">(C,B)</literal>.
3078 </blockquote></para></blockquote>
3082 The following two functions are provided for special cases:
3085 void xf86RemoveEntityFromScreen(ScrnInfoPtr pScrn, int entityIndex);
3088 This function may be used to remove an entity from a screen. This
3089 only makes sense if a screen has more than one entity assigned or
3090 the screen is to be deleted. No test is made if the screen has
3094 </blockquote></para></blockquote>
3098 void xf86DeallocateResourcesForEntity(int entityIndex, long type);
3101 This function deallocates all resources of a given type registered
3102 for a certain entity from the resource broker list.
3105 </blockquote></para></blockquote>
3111 <title>ScreenInit Phase</title>
3114 All that is required in this phase is to setup the RAC flags. Note that
3115 it is also permissible to set these flags up in the PreInit phase. The
3116 RAC flags are held in the <structfield>racIoFlags</structfield> and <structfield>racMemFlags</structfield> fields of the
3117 <structname>ScrnInfoRec</structname> for each screen. They specify which graphics operations
3118 might require the use of shared resources. This can be specified
3119 separately for memory and I/O resources. The available flags are defined
3120 in <filename>rac/xf86RAC.h</filename>. They are:
3123 <varlistentry><term><constant>RAC_FB</constant></term>
3125 for framebuffer operations (including hw acceleration)
3126 </para></listitem></varlistentry>
3127 <varlistentry><term><constant>RAC_CURSOR</constant></term>
3129 for Cursor operations
3130 (??? I'm not sure if we need this for SW cursor it depends
3131 on which level the sw cursor is drawn)
3132 </para></listitem></varlistentry>
3133 <varlistentry><term><constant>RAC_COLORMAP</constant></term>
3135 for colormap operations
3136 </para></listitem></varlistentry>
3137 <varlistentry><term><constant>RAC_VIEWPORT</constant></term>
3139 for the call to <function>ChipAdjustFrame()</function>
3140 </para></listitem></varlistentry>
3144 The flags are ORed together.
3150 <sect1 id="options">
3151 <title>Config file <quote>Option</quote> entries</title>
3154 Option entries are permitted in most sections and subsections of the
3155 config file. There are two forms of option entries:
3158 <varlistentry><term>Option "option-name"</term>
3161 </para></listitem></varlistentry>
3162 <varlistentry><term>Option "option-name" "option-value"</term>
3164 An option with an arbitrary value.
3165 </para></listitem></varlistentry>
3170 The option entries are handled by the parser, and a list of the parsed
3171 options is included with each of the appropriate data structures that
3172 the drivers have access to. The data structures used to hold the option
3173 information are opaque to the driver, and a driver must not access the
3174 option data directly. Instead, the common layer provides a set of
3175 functions that may be used to access, check and manipulate the option
3180 First, the low level option handling functions. In most cases drivers
3181 would not need to use these directly.
3186 pointer xf86FindOption(pointer options, const char *name);
3189 Takes a list of options and an option name, and returns a handle
3190 for the first option entry in the list matching the name. Returns
3191 <constant>NULL</constant> if no match is found.
3194 </blockquote></para></blockquote>
3198 char *xf86FindOptionValue(pointer options, const char *name);
3201 Takes a list of options and an option name, and returns the value
3202 associated with the first option entry in the list matching the
3203 name. If the matching option has no value, an empty string
3204 (<constant>""</constant>) is returned. Returns <constant>NULL</constant>
3205 if no match is found.
3208 </blockquote></para></blockquote>
3212 void xf86MarkOptionUsed(pointer option);
3215 Takes a handle for an option, and marks that option as used.
3218 </blockquote></para></blockquote>
3222 void xf86MarkOptionUsedByName(pointer options, const char *name);
3225 Takes a list of options and an option name and marks the first
3226 option entry in the list matching the name as used.
3229 </blockquote></para></blockquote>
3232 Next, the higher level functions that most drivers would use.
3236 void xf86CollectOptions(ScrnInfoPtr pScrn, pointer extraOpts);
3239 Collect the options from each of the config file sections used by
3240 the screen (<parameter>pScrn</parameter>) and return the merged list as
3241 <structfield>pScrn->options</structfield>. This function requires that
3242 <structfield>pScrn->confScreen</structfield>, <structfield>pScrn->display</structfield>,
3243 <structfield>pScrn->monitor</structfield>,
3244 <structfield>pScrn->numEntities</structfield>, and
3245 <structfield>pScrn->entityList</structfield> are initialised.
3246 <parameter>extraOpts</parameter> may optionally be set to an additional
3247 list of options to be combined with the others. The order of
3248 precedence for options is <parameter>extraOpts</parameter>, display,
3249 confScreen, monitor, device.
3252 </blockquote></para></blockquote>
3256 void xf86ProcessOptions(int scrnIndex, pointer options,
3257 OptionInfoPtr optinfo);
3260 Processes a list of options according to the information in the
3261 array of <structname>OptionInfoRecs</structname> (<parameter>optinfo</parameter>).
3262 The resulting information is stored in the <structfield>value</structfield>
3263 fields of the appropriate <parameter>optinfo</parameter> entries. The
3264 <structfield>found</structfield> fields are set to <constant>TRUE</constant>
3265 when an option with a value of the correct type if found, and
3266 <constant>FALSE</constant> otherwise. The <structfield>type</structfield> field
3267 is used to determine the expected value type for each option.
3268 Each option in the list of options for which there is a name match
3269 (but not necessarily a value type match) is marked as used.
3270 Warning messages are printed when option values don't match the
3271 types specified in the optinfo data.
3275 NOTE: If this function is called before a driver's screen number
3276 is known (e.g., from the <function>ChipProbe()</function> function) a
3277 <parameter>scrnIndex</parameter> value of <constant>-1</constant> should be
3282 NOTE 2: Given that this function stores into the
3283 <literal remap="tt">OptionInfoRecs</literal> pointed to by <parameter>optinfo</parameter>,
3284 the caller should ensure the <literal remap="tt">OptionInfoRecs</literal> are
3285 (re-)initialised before the call, especially if the caller expects
3286 to use the predefined option values as defaults.
3290 The <structname>OptionInfoRec</structname> is defined as follows:
3309 OPTV_STRING, /* a non-empty string */
3310 OPTV_ANYSTR, /* Any string, including an empty one */
3326 OptionValueType type;
3329 } OptionInfoRec, *OptionInfoPtr;
3333 <constant>OPTV_FREQ</constant> can be used for options values that are
3334 frequencies. These values are a floating point number with an
3335 optional unit name appended. The unit name can be one of "Hz",
3336 "kHz", "k", "MHz", "M". The multiplier associated with the unit
3337 is stored in <structfield>freq.units</structfield>, and the scaled frequency
3338 is stored in <structfield>freq.freq</structfield>. When no unit is specified,
3339 <structfield>freq.units</structfield> is set to <constant>0</constant>, and
3340 <structfield>freq.freq</structfield> is unscaled.
3344 <constant>OPTV_PERCENT</constant> can be used for option values that are
3345 specified in percent (e.g. "20%"). These values are a floating point
3346 number with a percent sign appended. If the percent sign is missing,
3347 the parser will fail to match the value.
3351 Typical usage is to setup an array of
3352 <structname>OptionInfoRec</structname>s with all fields initialised.
3353 The <structfield>value</structfield> and <structfield>found</structfield> fields get
3354 set by <function>xf86ProcessOptions()</function>. For cases where the
3355 value parsing is more complex, the driver should specify
3356 <constant>OPTV_STRING</constant>, and parse the string itself. An
3357 example of using this option handling is included in the
3358 <link linkend="sample">Sample Driver</link> section.
3361 </blockquote></para></blockquote>
3365 void xf86ShowUnusedOptions(int scrnIndex, pointer options);
3368 Prints out warning messages for each option in the list of options
3369 that isn't marked as used. This is intended to show options that
3370 the driver hasn't recognised. It would normally be called near
3371 the end of the <function>ChipScreenInit()</function> function, but only
3372 when <code>serverGeneration == 1</code>
3374 </blockquote></para></blockquote>
3378 OptionInfoPtr xf86TokenToOptinfo(const OptionInfoRec *table,
3382 Returns a pointer to the <structname>OptionInfoRec</structname> in
3383 <parameter>table</parameter> with a token field matching
3384 <parameter>token</parameter>. Returns <constant>NULL</constant> if no match
3388 </blockquote></para></blockquote>
3392 Bool xf86IsOptionSet(const OptionInfoRec *table, int token);
3395 Returns the <literal remap="tt">found</literal> field of the
3396 <structname>OptionInfoRec</structname> in <parameter>table</parameter> with a
3397 <structfield>token</structfield> field matching <parameter>token</parameter>. This
3398 can be used for options of all types. Note that for options of
3399 type <constant>OPTV_BOOLEAN</constant>, it isn't sufficient to check
3400 this to determine the value of the option. Returns
3401 <constant>FALSE</constant> if no match is found.
3404 </blockquote></para></blockquote>
3408 char *xf86GetOptValString(const OptionInfoRec *table, int token);
3411 Returns the <structfield>value.str</structfield> field of the
3412 <structname>OptionInfoRec</structname> in <parameter>table</parameter> with a
3413 token field matching <parameter>token</parameter>. Returns
3414 <constant>NULL</constant> if no match is found.
3417 </blockquote></para></blockquote>
3421 Bool xf86GetOptValInteger(const OptionInfoRec *table, int token,
3426 Returns via <parameter>*value</parameter> the <structfield>value.num</structfield>
3427 field of the <structname>OptionInfoRec</structname> in <parameter>table</parameter>
3428 with a <structfield>token</structfield> field matching <parameter>token</parameter>.
3429 <parameter>*value</parameter> is only changed when a match is found so
3430 it can be safely initialised with a default prior to calling this
3431 function. The function return value is as for
3432 <function>xf86IsOptionSet()</function>.
3435 </blockquote></para></blockquote>
3439 Bool xf86GetOptValULong(const OptionInfoRec *table, int token,
3440 unsigned long *value);
3443 Like <function>xf86GetOptValInteger()</function>, except the value is
3444 treated as an <type>unsigned long</type>.
3447 </blockquote></para></blockquote>
3451 Bool xf86GetOptValReal(const OptionInfoRec *table, int token,
3455 Like <function>xf86GetOptValInteger()</function>, except that
3456 <structfield>value.realnum</structfield> is used.
3459 </blockquote></para></blockquote>
3463 Bool xf86GetOptValFreq(const OptionInfoRec *table, int token,
3464 OptFreqUnits expectedUnits, double *value);
3467 Like <function>xf86GetOptValInteger()</function>, except that the
3468 <structfield>value.freq</structfield> data is returned. The frequency value
3469 is scaled to the units indicated by <parameter>expectedUnits</parameter>.
3470 The scaling is exact when the units were specified explicitly in
3471 the option's value. Otherwise, the <parameter>expectedUnits</parameter>
3472 field is used as a hint when doing the scaling. In this case,
3473 values larger than <constant>1000</constant> are assumed to have be
3474 specified in the next smallest units. For example, if the Option
3475 value is "10000" and expectedUnits is <constant>OPTUNITS_MHZ</constant>,
3476 the value returned is <constant>10</constant>.
3479 </blockquote></para></blockquote>
3483 Bool xf86GetOptValBool(const OptionInfoRec *table, int token, Bool *value);
3486 This function is used to check boolean options
3487 (<constant>OPTV_BOOLEAN</constant>). If the function return value is
3488 <constant>FALSE</constant>, it means the option wasn't set. Otherwise
3489 <parameter>*value</parameter> is set to the boolean value indicated by
3490 the option's value. No option <parameter>value</parameter> is interpreted
3491 as <constant>TRUE</constant>. Option values meaning <constant>TRUE</constant>
3492 are "1", "yes", "on", "true", and option values meaning
3493 <constant>FALSE</constant> are "0", "no", "off", "false". Option names
3494 both with the "no" prefix in their names, and with that prefix
3495 removed are also checked and handled in the obvious way.
3496 <parameter>*value</parameter> is not changed when the option isn't present.
3497 It should normally be set to a default value before calling this
3501 </blockquote></para></blockquote>
3505 Bool xf86ReturnOptValBool(const OptionInfoRec *table, int token, Bool def);
3508 This function is used to check boolean options
3509 (<constant>OPTV_BOOLEAN</constant>). If the option is set, its value
3510 is returned. If the options is not set, the default value specified
3511 by <parameter>def</parameter> is returned. The option interpretation is
3512 the same as for <function>xf86GetOptValBool()</function>.
3515 </blockquote></para></blockquote>
3519 int xf86NameCmp(const char *s1, const char *s2);
3522 This function should be used when comparing strings from the config
3523 file with expected values. It works like <function>strcmp()</function>,
3524 but is not case sensitive and space, tab, and <quote><literal>_</literal></quote> characters
3525 are ignored in the comparison. The use of this function isn't
3526 restricted to parsing option values. It may be used anywhere
3527 where this functionality required.
3530 </blockquote></para></blockquote>
3534 <title>Modules, Drivers, Include Files and Interface Issues</title>
3537 NOTE: this section is incomplete.
3542 <title>Include files</title>
3545 The following include files are typically required by video drivers:
3548 All drivers should include these:
3549 <literallayout><filename>
3554 </filename></literallayout>
3555 Wherever inb/outb (and related things) are used the following should be
3557 <literallayout><filename>
3559 </filename></literallayout>
3560 Note: in drivers, this must be included after <filename>"xf86_ansic.h"</filename>.
3564 Drivers that need to access PCI vendor/device definitions need this:
3565 <literallayout><filename>
3567 </filename></literallayout>
3571 Drivers that need to access the PCI config space need this:
3572 <literallayout><filename>
3574 </filename></literallayout>
3578 Drivers that initialise a SW cursor need this:
3579 <literallayout><filename>
3581 </filename></literallayout>
3585 All drivers implementing backing store need this:
3586 <literallayout><filename>
3588 </filename></literallayout>
3592 All drivers using the mi colourmap code need this:
3593 <literallayout><filename>
3595 </filename></literallayout>
3599 If a driver uses the vgahw module, it needs this:
3600 <literallayout><filename>
3602 </filename></literallayout>
3606 Drivers supporting VGA or Hercules monochrome screens need:
3607 <literallayout><filename>
3609 </filename></literallayout>
3613 Drivers supporting VGA or EGC 16-colour screens need:
3614 <literallayout><filename>
3616 </filename></literallayout>
3620 Drivers using cfb need:
3629 Drivers supporting bpp 16, 24 or 32 with cfb need one or more of:
3630 <literallayout><filename>
3634 </filename></literallayout>
3638 If a driver uses XAA, it needs these:
3639 <literallayout><filename>
3642 </filename></literallayout>
3646 If a driver uses the fb manager, it needs this:
3647 <literallayout><filename>
3649 </filename></literallayout>
3655 Non-driver modules should include <filename>"xf86_ansic.h"</filename> to get the correct
3656 wrapping of ANSI C/libc functions.
3660 All modules must NOT include any system include files, or the following:
3662 <literallayout><filename>
3667 </filename></literallayout>
3671 In addition, "xf86_libc.h" must not be included explicitly. It is
3672 included implicitly by "xf86_ansic.h".
3679 <title>Offscreen Memory Manager</title>
3682 Management of offscreen video memory may be handled by the XFree86
3683 framebuffer manager. Once the offscreen memory manager is running,
3684 drivers or extensions may allocate, free or resize areas of offscreen
3685 video memory using the following functions (definitions taken from
3686 <filename>xf86fbman.h</filename>):
3689 typedef struct _FBArea {
3693 void (*MoveAreaCallback)(struct _FBArea*, struct _FBArea*)
3694 void (*RemoveAreaCallback)(struct _FBArea*)
3695 DevUnion devPrivate;
3696 } FBArea, *FBAreaPtr;
3698 typedef void (*MoveAreaCallbackProcPtr)(FBAreaPtr from, FBAreaPtr to)
3699 typedef void (*RemoveAreaCallbackProcPtr)(FBAreaPtr)
3701 FBAreaPtr xf86AllocateOffscreenArea (
3703 int width, int height,
3705 MoveAreaCallbackProcPtr MoveAreaCallback,
3706 RemoveAreaCallbackProcPtr RemoveAreaCallback,
3710 void xf86FreeOffscreenArea (FBAreaPtr area)
3712 Bool xf86ResizeOffscreenArea (
3722 Bool xf86FBManagerRunning(ScreenPtr pScreen);
3725 can be used by an extension to check if the driver has initialized
3726 the memory manager. The manager is not available if this returns
3727 <constant>FALSE</constant> and the functions above will all fail.
3732 <function>xf86AllocateOffscreenArea()</function> can be used to request a
3733 rectangle of dimensions <parameter>width</parameter> × <parameter>height</parameter>
3734 (in pixels) from unused offscreen memory. <parameter>granularity</parameter>
3735 specifies that the leftmost edge of the rectangle must lie on some
3736 multiple of <parameter>granularity</parameter> pixels. A granularity of zero
3737 means the same thing as a granularity of one - no alignment preference.
3738 A <parameter>MoveAreaCallback</parameter> can be provided to notify the requester
3739 when the offscreen area is moved. If no <parameter>MoveAreaCallback</parameter>
3740 is supplied then the area is considered to be immovable. The
3741 <parameter>privData</parameter> field will be stored in the manager's internal
3742 structure for that allocated area and will be returned to the requester
3743 in the <parameter>FBArea</parameter> passed via the
3744 <parameter>MoveAreaCallback</parameter>. An optional
3745 <parameter>RemoveAreaCallback</parameter> is provided. If the driver provides
3746 this it indicates that the area should be allocated with a lower priority.
3747 Such an area may be removed when a higher priority request (one that
3748 doesn't have a <parameter>RemoveAreaCallback</parameter>) is made. When this
3749 function is called, the driver will have an opportunity to do whatever
3750 cleanup it needs to do to deal with the loss of the area, but it must
3751 finish its cleanup before the function exits since the offscreen memory
3752 manager will free the area immediately after.
3756 <function>xf86AllocateOffscreenArea()</function> returns <constant>NULL</constant>
3757 if it was unable to allocate the requested area. When no longer needed,
3758 areas should be freed with <function>xf86FreeOffscreenArea()</function>.
3762 <function>xf86ResizeOffscreenArea()</function> resizes an existing
3763 <literal remap="tt">FBArea</literal>. <function>xf86ResizeOffscreenArea()</function>
3764 returns <constant>TRUE</constant> if the resize was successful. If
3765 <function>xf86ResizeOffscreenArea()</function> returns <constant>FALSE</constant>,
3766 the original <literal remap="tt">FBArea</literal> is left unmodified. Resizing an
3767 area maintains the area's original <literal remap="tt">granularity</literal>,
3768 <literal remap="tt">devPrivate</literal>, and <literal remap="tt">MoveAreaCallback</literal>.
3769 <function>xf86ResizeOffscreenArea()</function> has considerably less overhead
3770 than freeing the old area then reallocating the new size, so it should
3771 be used whenever possible.
3777 Bool xf86QueryLargestOffscreenArea(
3779 int *width, int *height,
3786 is provided to query the width and height of the largest single
3787 <structname>FBArea</structname> allocatable given a particular priority.
3788 <parameter>preferences</parameter> can be one of the following to indicate
3789 whether width, height or area should be considered when determining
3790 which is the largest single <structname>FBArea</structname> available.
3793 FAVOR_AREA_THEN_WIDTH
3794 FAVOR_AREA_THEN_HEIGHT
3795 FAVOR_WIDTH_THEN_AREA
3796 FAVOR_HEIGHT_THEN_AREA
3801 <parameter>priority</parameter> is one of the following:
3805 <constant>PRIORITY_LOW</constant>
3807 Return the largest block available without stealing anyone else's
3808 space. This corresponds to the priority of allocating a
3809 <structname>FBArea</structname> when a <function>RemoveAreaCallback</function>
3811 </para></blockquote>
3815 <constant>PRIORITY_NORMAL</constant>
3817 Return the largest block available if it is acceptable to steal a
3818 lower priority area from someone. This corresponds to the priority
3819 of allocating a <structname>FBArea</structname> without providing a
3820 <function>RemoveAreaCallback</function>.
3821 </para></blockquote>
3825 <constant>PRIORITY_EXTREME</constant>
3827 Return the largest block available if all <structname>FBArea</structname>s
3828 that aren't locked down were expunged from memory first. This
3829 corresponds to any allocation made directly after a call to
3830 <function>xf86PurgeUnlockedOffscreenAreas()</function>.
3831 </para></blockquote>
3842 Bool xf86PurgeUnlockedOffscreenAreas(ScreenPtr pScreen);
3845 is provided as an extreme method to free up offscreen memory. This
3846 will remove all removable <structname>FBArea</structname> allocations.
3851 Initialization of the XFree86 framebuffer manager is done via
3854 Bool xf86InitFBManager(ScreenPtr pScreen, BoxPtr FullBox);
3857 <parameter>FullBox</parameter> represents the area of the framebuffer that the
3858 manager is allowed to manage. This is typically a box with a width of
3859 <structfield>pScrn->displayWidth</structfield> and a height of as many lines as
3860 can be fit within the total video memory, however, the driver can reserve
3861 areas at the extremities by passing a smaller area to the manager.
3865 <function>xf86InitFBManager()</function> must be called before XAA is
3866 initialized since XAA uses the manager for it's pixmap cache.
3870 An alternative function is provided to allow the driver to initialize
3871 the framebuffer manager with a Region rather than a box.
3874 Bool xf86InitFBManagerRegion(ScreenPtr pScreen,
3875 RegionPtr FullRegion);
3878 <function>xf86InitFBManagerRegion()</function>, unlike
3879 <function>xf86InitFBManager()</function>, does not remove the area used for
3880 the visible screen so that area should not be included in the region
3881 passed to the function. <function>xf86InitFBManagerRegion()</function> is
3882 useful when non-contiguous areas are available to be managed, and is
3883 required when multiple framebuffers are stored in video memory (as in
3884 the case where an overlay of a different depth is stored as a second
3885 framebuffer in offscreen memory).
3891 <title>Colormap Handling</title>
3894 A generic colormap handling layer is provided within the XFree86 common
3895 layer. This layer takes care of most of the details, and only requires
3896 a function from the driver that loads the hardware palette when required.
3897 To use the colormap layer, a driver calls the
3898 <function>xf86HandleColormaps()</function> function.
3902 Bool xf86HandleColormaps(ScreenPtr pScreen, int maxColors,
3903 int sigRGBbits, LoadPaletteFuncPtr loadPalette,
3904 SetOverscanFuncPtr setOverscan,
3905 unsigned int flags);
3908 This function must be called after the default colormap has been
3909 initialised. The <structfield>pScrn->gamma</structfield> field must also
3910 be initialised, preferably by calling <function>xf86SetGamma()</function>.
3911 <parameter>maxColors</parameter> is the number of entries in the palette.
3912 <parameter>sigRGBbits</parameter> is the size in bits of each color
3913 component in the DAC's palette. <parameter>loadPalette</parameter>
3914 is a driver-provided function for loading a colormap into the
3915 hardware, and is described below. <parameter>setOverscan</parameter> is
3916 an optional function that may be provided when the overscan color
3917 is an index from the standard LUT and when it needs to be adjusted
3918 to keep it as close to black as possible. The
3919 <parameter>setOverscan</parameter> function programs the overscan index.
3920 It shouldn't normally be used for depths other than 8.
3921 <parameter>setOverscan</parameter> should be set to <constant>NULL</constant>
3922 when it isn't needed. <parameter>flags</parameter> may be set to the
3923 following (which may be ORed together):
3927 <term><constant>CMAP_PALETTED_TRUECOLOR</constant></term>
3929 the TrueColor visual is paletted and is
3930 just a special case of DirectColor.
3931 This flag is only valid for
3932 <code>bpp > 8</code>.
3934 </para></listitem></varlistentry>
3936 <term><constant>CMAP_RELOAD_ON_MODE_SWITCH</constant></term>
3938 reload the colormap automatically
3939 after mode switches. This is useful
3940 for when the driver is resetting the
3941 hardware during mode switches and
3942 corrupting or erasing the hardware
3945 </para></listitem></varlistentry>
3947 <term><constant>CMAP_LOAD_EVEN_IF_OFFSCREEN</constant></term>
3949 reload the colormap even if the screen
3950 is switched out of the server's VC.
3951 The palette is <emphasis>not</emphasis> reloaded when
3952 the screen is switched back in, nor after
3953 mode switches. This is useful when the
3954 driver needs to keep track of palette
3957 </para></listitem></varlistentry>
3962 The colormap layer normally reloads the palette after VT enters so it
3963 is not necessary for the driver to save and restore the palette
3964 when switching VTs. The driver must, however, still save the
3965 initial palette during server start up and restore it during
3969 </blockquote></para></blockquote>
3973 void LoadPalette(ScrnInfoPtr pScrn, int numColors, int *indices,
3974 LOCO *colors, VisualPtr pVisual);
3977 <function>LoadPalette()</function> is a driver-provided function for
3978 loading a colormap into hardware. <parameter>colors</parameter> is the
3979 array of RGB values that represent the full colormap.
3980 <parameter>indices</parameter> is a list of index values into the colors
3981 array. These indices indicate the entries that need to be updated.
3982 <parameter>numColors</parameter> is the number of the indices to be
3986 </blockquote></para></blockquote>
3990 void SetOverscan(ScrnInfoPtr pScrn, int overscan);
3993 <function>SetOverscan()</function> is a driver-provided function for
3994 programming the <parameter>overscan</parameter> index. As described
3995 above, it is normally only appropriate for LUT modes where all
3996 colormap entries are available for the display, but where one of
3997 them is also used for the overscan (typically 8bpp for VGA compatible
3998 LUTs). It isn't required in cases where the overscan area is
4002 </blockquote></para>
4003 </blockquote></para>
4008 <title>DPMS Extension</title>
4011 Support code for the DPMS extension is included in the XFree86 common layer.
4012 This code provides an interface between the main extension code, and a means
4013 for drivers to initialise DPMS when they support it. One function is
4014 available to drivers to do this initialisation, and it is always available,
4015 even when the DPMS extension is not supported by the core server (in
4016 which case it returns a failure result).
4021 Bool xf86DPMSInit(ScreenPtr pScreen, DPMSSetProcPtr set, int flags);
4024 This function registers a driver's DPMS level programming function
4025 <parameter>set</parameter>. It also checks
4026 <structfield>pScrn->options</structfield> for the "dpms" option, and when
4027 present marks DPMS as being enabled for that screen. The
4028 <parameter>set</parameter> function is called whenever the DPMS level
4029 changes, and is used to program the requested level.
4030 <parameter>flags</parameter> is currently not used, and should be
4031 <constant>0</constant>. If the initialisation fails for any reason,
4032 including when there is no DPMS support in the core server, the
4033 function returns <constant>FALSE</constant>.
4036 </blockquote></para></blockquote>
4040 Drivers that implement DPMS support must provide the following function,
4041 that gets called when the DPMS level is changed:
4046 void ChipDPMSSet(ScrnInfoPtr pScrn, int level, int flags);
4049 Program the DPMS level specified by <parameter>level</parameter>. Valid
4050 values of <parameter>level</parameter> are <constant>DPMSModeOn</constant>,
4051 <constant>DPMSModeStandby</constant>, <constant>DPMSModeSuspend</constant>,
4052 <constant>DPMSModeOff</constant>. These values are defined in
4053 <filename>"extensions/dpms.h"</filename>.
4056 </blockquote></para></blockquote>
4062 <title>DGA Extension</title>
4065 Drivers can support the XFree86 Direct Graphics Architecture (DGA) by
4066 filling out a structure of function pointers and a list of modes and
4067 passing them to DGAInit.
4072 Bool DGAInit(ScreenPtr pScreen, DGAFunctionPtr funcs,
4073 DGAModePtr modes, int num);
4075 /** The DGAModeRec **/
4079 DisplayModePtr mode;
4085 int bytesPerScanline;
4089 unsigned long red_mask;
4090 unsigned long green_mask;
4091 unsigned long blue_mask;
4100 unsigned char *address;
4103 } DGAModeRec, *DGAModePtr;
4108 <term><structfield>num</structfield></term>
4110 Can be ignored. The DGA DDX will assign these numbers.
4111 </para></listitem></varlistentry>
4114 <term><structfield>mode</structfield></term>
4116 A pointer to the <structname>DisplayModeRec</structname> for this mode.
4117 </para></listitem></varlistentry>
4120 <term><structfield>flags</structfield></term>
4122 The following flags are defined and may be OR'd together:
4126 <term><constant>DGA_CONCURRENT_ACCESS</constant></term>
4128 Indicates that the driver supports concurrent graphics
4129 accelerator and linear framebuffer access.
4131 </para></listitem></varlistentry>
4134 <term><constant>DGA_FILL_RECT
4136 DGA_BLIT_RECT_TRANS</constant></term>
4138 Indicates that the driver supports the FillRect, BlitRect
4139 or BlitTransRect functions in this mode.
4141 </para></listitem></varlistentry>
4144 <term><constant>DGA_PIXMAP_AVAILABLE</constant></term>
4146 Indicates that Xlib may be used on the framebuffer.
4147 This flag will usually be set unless the driver wishes
4148 to prohibit this for some reason.
4150 </para></listitem></varlistentry>
4153 <term><constant>DGA_INTERLACED
4154 DGA_DOUBLESCAN</constant></term>
4156 Indicates that these are interlaced or double scan modes.
4158 </para></listitem></varlistentry>
4160 </para></listitem></varlistentry>
4163 <term><structfield>imageWidth
4164 imageHeight</structfield></term>
4166 These are the dimensions of the linear framebuffer
4167 accessible by the client.
4169 </para></listitem></varlistentry>
4172 <term><structfield>pixmapWidth
4173 pixmapHeight</structfield></term>
4175 These are the dimensions of the area of the
4176 framebuffer accessible by the graphics accelerator.
4178 </para></listitem></varlistentry>
4181 <term><structfield>bytesPerScanline</structfield></term>
4183 Pitch of the framebuffer in bytes.
4185 </para></listitem></varlistentry>
4188 <term><structfield>byteOrder</structfield></term>
4191 <structfield>pScrn->imageByteOrder</structfield>.
4193 </para></listitem></varlistentry>
4196 <term><structfield>depth</structfield></term>
4198 The depth of the framebuffer in this mode.
4200 </para></listitem></varlistentry>
4203 <term><structfield>bitsPerPixel</structfield></term>
4205 The number of bits per pixel in this mode.
4207 </para></listitem></varlistentry>
4210 <term><structfield>red_mask</structfield></term>
4211 <term><structfield>green_mask</structfield></term>
4212 <term><structfield>blue_mask</structfield></term>
4214 The RGB masks for this mode, if applicable.
4216 </para></listitem></varlistentry>
4219 <term><structfield>viewportWidth</structfield></term>
4220 <term><structfield>viewportHeight</structfield></term>
4222 Dimensions of the visible part of the framebuffer.
4223 Usually <structfield>mode->HDisplay</structfield> and
4224 <structfield>mode->VDisplay</structfield>.
4226 </para></listitem></varlistentry>
4229 <term><structfield>xViewportStep
4230 yViewportStep</structfield></term>
4232 The granularity of x and y viewport positions that
4233 the driver supports in this mode.
4235 </para></listitem></varlistentry>
4238 <term><structfield>maxViewportX
4239 maxViewportY</structfield></term>
4241 The maximum viewport position supported by the
4242 driver in this mode.
4243 </para></listitem></varlistentry>
4246 <term><structfield>viewportFlags</structfield></term>
4248 The following may be OR'd together:
4252 <term><constant>DGA_FLIP_IMMEDIATE</constant></term>
4254 The driver supports immediate viewport changes.
4255 </para></listitem></varlistentry>
4258 <term><constant>DGA_FLIP_RETRACE</constant></term>
4261 The driver supports viewport changes at retrace.
4262 </para></listitem></varlistentry>
4264 </para></listitem></varlistentry>
4267 <term><structfield>offset</structfield></term>
4269 The offset into the linear framebuffer that corresponds to
4270 pixel (0,0) for this mode.
4271 </para></listitem></varlistentry>
4274 <term><structfield>address</structfield></term>
4276 The virtual address of the framebuffer as mapped by the driver.
4277 This is needed when DGA_PIXMAP_AVAILABLE is set.
4278 </para></listitem></varlistentry>
4283 /** The DGAFunctionRec **/
4286 Bool (*OpenFramebuffer)(
4289 unsigned char **mem,
4294 void (*CloseFramebuffer)(ScrnInfoPtr pScrn);
4295 Bool (*SetMode)(ScrnInfoPtr pScrn, DGAModePtr pMode);
4296 void (*SetViewport)(ScrnInfoPtr pScrn, int x, int y, int flags);
4297 int (*GetViewport)(ScrnInfoPtr pScrn);
4298 void (*Sync)(ScrnInfoPtr);
4301 int x, int y, int w, int h,
4310 void (*BlitTransRect)(
4317 } DGAFunctionRec, *DGAFunctionPtr;
4323 Bool OpenFramebuffer (pScrn, name, mem, size, offset, extra);
4326 <function>OpenFramebuffer()</function> should pass the client everything
4327 it needs to know to be able to open the framebuffer. These
4328 parameters are OS specific and their meanings are to be interpreted
4329 by an OS specific client library.
4333 <term><parameter>name</parameter></term>
4335 The name of the device to open or <constant>NULL</constant> if
4336 there is no special device to open. A <constant>NULL</constant>
4337 name tells the client that it should open whatever device
4338 one would usually open to access physical memory.
4339 </para></listitem></varlistentry>
4342 <term><parameter>mem</parameter></term>
4344 The physical address of the start of the framebuffer.
4345 </para></listitem></varlistentry>
4348 <term><parameter>size</parameter></term>
4350 The size of the framebuffer in bytes.
4351 </para></listitem></varlistentry>
4354 <term><parameter>offset</parameter></term>
4356 Any offset into the device, if applicable.
4357 </para></listitem></varlistentry>
4360 <term><parameter>flags</parameter></term>
4362 Any additional information that the client may need.
4363 Currently, only the <constant>DGA_NEED_ROOT</constant> flag is
4365 </para></listitem></varlistentry>
4368 </para></blockquote>
4369 </para></blockquote>
4373 void CloseFramebuffer (pScrn);
4376 <function>CloseFramebuffer()</function> merely informs the driver (if it
4377 even cares) that client no longer needs to access the framebuffer
4378 directly. This function is optional.
4381 </blockquote></para></blockquote>
4385 Bool SetMode (pScrn, pMode);
4388 <function>SetMode()</function> tells the driver to initialize the mode
4389 passed to it. If <parameter>pMode</parameter> is <constant>NULL</constant>,
4390 then the driver should restore the original pre-DGA mode.
4393 </blockquote></para></blockquote>
4397 void SetViewport (pScrn, x, y, flags);
4400 <function>SetViewport()</function> tells the driver to make the upper
4401 left-hand corner of the visible screen correspond to coordinate
4402 <literal remap="tt">(x,y)</literal> on the framebuffer. <parameter>flags</parameter>
4403 currently defined are:
4407 <term><constant>DGA_FLIP_IMMEDIATE</constant></term>
4409 The viewport change should occur immediately.
4410 </para></listitem></varlistentry>
4413 <term><constant>DGA_FLIP_RETRACE</constant></term>
4415 The viewport change should occur at the
4416 vertical retrace, but this function should
4417 return sooner if possible.
4418 </para></listitem></varlistentry>
4423 The <literal remap="tt">(x,y)</literal> locations will be passed as the client
4424 specified them, however, the driver is expected to round these
4425 locations down to the next supported location as specified by the
4426 <structfield>xViewportStep</structfield> and <structfield>yViewportStep</structfield>
4427 for the current mode.
4429 </blockquote></para></blockquote>
4433 int GetViewport (pScrn);
4436 <function>GetViewport()</function> gets the current page flip status.
4437 Set bits in the returned int correspond to viewport change requests
4438 still pending. For instance, set bit zero if the last SetViewport
4439 request is still pending, bit one if the one before that is still
4443 </blockquote></para></blockquote>
4450 This function should ensure that any graphics accelerator operations
4451 have finished. This function should not return until the graphics
4452 accelerator is idle.
4455 </blockquote></para></blockquote>
4459 void FillRect (pScrn, x, y, w, h, color);
4462 This optional function should fill a rectangle
4463 <parameter>w × h</parameter> located at
4464 <parameter>(x,y)</parameter> in the given color.
4467 </blockquote></para></blockquote>
4471 void BlitRect (pScrn, srcx, srcy, w, h, dstx, dsty);
4474 This optional function should copy an area
4475 <parameter>w × h</parameter> located at
4476 <parameter>(srcx,srcy)</parameter> to location <parameter>(dstx,dsty)</parameter>.
4477 This function will need to handle copy directions as appropriate.
4480 </blockquote></para></blockquote>
4484 void BlitTransRect (pScrn, srcx, srcy, w, h, dstx, dsty, color);
4487 This optional function is the same as BlitRect except that pixels
4488 in the source corresponding to the color key <parameter>color</parameter>
4492 </blockquote></para></blockquote>
4493 </para></blockquote>
4498 <title>The XFree86 X Video Extension (Xv) Device Dependent Layer</title>
4501 XFree86 offers the X Video Extension which allows clients to treat video
4502 as any another primitive and <quote>Put</quote> video into drawables. By default,
4503 the extension reports no video adaptors as being available since the
4504 DDX layer has not been initialized. The driver can initialize the DDX
4505 layer by filling out one or more <literal remap="tt">XF86VideoAdaptorRecs</literal>
4506 as described later in this document and passing a list of
4507 <literal remap="tt">XF86VideoAdaptorPtr</literal> pointers to the following function:
4510 Bool xf86XVScreenInit(ScreenPtr pScreen,
4511 XF86VideoAdaptorPtr *adaptPtrs,
4517 After doing this, the extension will report video adaptors as being
4518 available, providing the data in their respective
4519 <literal remap="tt">XF86VideoAdaptorRecs</literal> was valid.
4520 <function>xf86XVScreenInit()</function> <emphasis>copies</emphasis> data from the structure
4521 passed to it so the driver may free it after the initialization. At
4522 the moment, the DDX only supports rendering into Window drawables.
4523 Pixmap rendering will be supported after a sufficient survey of suitable
4524 hardware is completed.
4528 The <structname>XF86VideoAdaptorRec</structname>:
4536 XF86VideoEncodingPtr pEncodings;
4538 XF86VideoFormatPtr pFormats;
4540 DevUnion *pPortPrivates;
4542 XF86AttributePtr pAttributes;
4544 XF86ImagePtr pImages;
4545 PutVideoFuncPtr PutVideo;
4546 PutStillFuncPtr PutStill;
4547 GetVideoFuncPtr GetVideo;
4548 GetStillFuncPtr GetStill;
4549 StopVideoFuncPtr StopVideo;
4550 SetPortAttributeFuncPtr SetPortAttribute;
4551 GetPortAttributeFuncPtr GetPortAttribute;
4552 QueryBestSizeFuncPtr QueryBestSize;
4553 PutImageFuncPtr PutImage;
4554 QueryImageAttributesFuncPtr QueryImageAttributes;
4555 } XF86VideoAdaptorRec, *XF86VideoAdaptorPtr;
4556 </programlisting></para>
4559 Each adaptor will have its own XF86VideoAdaptorRec. The fields are
4564 <term><structfield>type</structfield></term>
4566 This can be any of the following flags OR'd together.
4570 <term><constant>XvInputMask</constant>
4571 <constant>XvOutputMask</constant></term>
4573 These refer to the target drawable and are similar to a Window's
4574 class. <literal remap="tt">XvInputMask</literal> indicates that the adaptor
4575 can put video into a drawable. <literal remap="tt">XvOutputMask</literal>
4576 indicates that the adaptor can get video from a drawable.
4577 </para></listitem></varlistentry>
4580 <term><constant>XvVideoMask</constant>
4581 <constant>XvStillMask</constant>
4582 <constant>XvImageMask</constant></term>
4584 These indicate that the adaptor supports video, still or
4585 image primitives respectively.
4586 </para></listitem></varlistentry>
4589 <term><constant>XvWindowMask</constant>
4590 <constant>XvPixmapMask</constant></term>
4592 These indicate the types of drawables the adaptor is capable
4593 of rendering into. At the moment, Pixmap rendering is not
4594 supported and the <constant>XvPixmapMask</constant> flag is ignored.
4595 </para></listitem></varlistentry>
4598 </para></listitem></varlistentry>
4601 <term><structfield>flags</structfield></term>
4603 Currently, the following flags are defined:
4607 <term><constant>VIDEO_NO_CLIPPING</constant></term>
4609 This indicates that the video adaptor does not support
4610 clipping. The driver will never receive <quote>Put</quote> requests
4611 where less than the entire area determined by
4612 <parameter>drw_x</parameter>, <parameter>drw_y</parameter>,
4613 <parameter>drw_w</parameter> and <parameter>drw_h</parameter> is visible.
4614 This flag does not apply to <quote>Get</quote> requests. Hardware
4615 that is incapable of clipping <quote>Gets</quote> may punt or get
4616 the extents of the clipping region passed to it.
4622 <term><constant>VIDEO_INVERT_CLIPLIST</constant></term>
4624 This indicates that the video driver requires the clip
4625 list to contain the regions which are obscured rather
4626 than the regions which are are visible.
4632 <term><constant>VIDEO_OVERLAID_STILLS</constant></term>
4634 Implementing PutStill for hardware that does video as an
4635 overlay can be awkward since it's unclear how long to leave
4636 the video up for. When this flag is set, StopVideo will be
4637 called whenever the destination gets clipped or moved so that
4638 the still can be left up until then.
4644 <term><constant>VIDEO_OVERLAID_IMAGES</constant></term>
4646 Same as <constant>VIDEO_OVERLAID_STILLS</constant> but for images.
4651 <term><constant>VIDEO_CLIP_TO_VIEWPORT</constant></term>
4653 Indicates that the clip region passed to the driver functions
4654 should be clipped to the visible portion of the screen in the
4655 case where the viewport is smaller than the virtual desktop.
4656 </para></listitem></varlistentry>
4659 </para></listitem></varlistentry>
4662 <term><structfield>name</structfield></term>
4664 The name of the adaptor.
4665 </para></listitem></varlistentry>
4669 <term><structfield>nEncodings</structfield>
4670 <structfield>pEncodings</structfield></term>
4672 The number of encodings the adaptor is capable of and pointer
4673 to the <structname>XF86VideoEncodingRec</structname> array. The
4674 <structname>XF86VideoEncodingRec</structname> is described later on.
4675 For drivers that only support XvImages there should be an encoding
4676 named "XV_IMAGE" and the width and height should specify
4677 the maximum size source image supported.
4678 </para></listitem></varlistentry>
4682 <term><structfield>nFormats</structfield>
4683 <structfield>pFormats</structfield></term>
4685 The number of formats the adaptor is capable of and pointer to
4686 the <structname>XF86VideoFormatRec</structname> array. The
4687 <structname>XF86VideoFormatRec</structname> is described later on.
4688 </para></listitem></varlistentry>
4692 <term><structfield>nPorts</structfield>
4693 <structfield>pPortPrivates</structfield></term>
4695 The number of ports is the number of separate data streams which
4696 the adaptor can handle simultaneously. If you have more than
4697 one port, the adaptor is expected to be able to render into more
4698 than one window at a time. <structfield>pPortPrivates</structfield> is
4699 an array of pointers or ints - one for each port. A port's
4700 private data will be passed to the driver any time the port is
4701 requested to do something like put the video or stop the video.
4702 In the case where there may be many ports, this enables the
4703 driver to know which port the request is intended for. Most
4704 commonly, this will contain a pointer to the data structure
4705 containing information about the port. In Xv, all ports on
4706 a particular adaptor are expected to be identical in their
4708 </para></listitem></varlistentry>
4712 <term><structfield>nAttributes</structfield>
4713 <structfield>pAttributes</structfield></term>
4715 The number of attributes recognized by the adaptor and a pointer to
4716 the array of <structname>XF86AttributeRecs</structname>. The
4717 <structname>XF86AttributeRec</structname> is described later on.
4718 </para></listitem></varlistentry>
4722 <term><structfield>nImages</structfield>
4723 <structfield>pImages</structfield></term>
4725 The number of <structname>XF86ImageRecs</structname> supported by the adaptor
4726 and a pointer to the array of <structname>XF86ImageRecs</structname>. The
4727 <structname>XF86ImageRec</structname> is described later on.
4728 </para></listitem></varlistentry>
4733 PutVideo PutStill GetVideo GetStill StopVideo
4734 SetPortAttribute GetPortAttribute QueryBestSize PutImage
4735 QueryImageAttributes
4736 </structfield></term>
4738 These functions define the DDX->driver interface. In each
4739 case, the pointer <parameter>data</parameter> is passed to the driver.
4740 This is the port private for that port as described above. All
4741 fields are required except under the following conditions:
4745 <structfield>PutVideo</structfield>, <structfield>PutStill</structfield> and
4746 the image routines <structfield>PutImage</structfield> and
4747 <structfield>QueryImageAttributes</structfield> are not required when the
4748 adaptor type does not contain <constant>XvInputMask</constant>.
4752 <structfield>GetVideo</structfield> and <structfield>GetStill</structfield>
4753 are not required when the adaptor type does not contain
4754 <constant>XvOutputMask</constant>.
4758 <structfield>GetVideo</structfield> and <structfield>PutVideo</structfield>
4759 are not required when the adaptor type does not contain
4760 <constant>XvVideoMask</constant>.
4764 <structfield>GetStill</structfield> and <structfield>PutStill</structfield>
4765 are not required when the adaptor type does not contain
4766 <constant>XvStillMask</constant>.
4770 <structfield>PutImage</structfield> and <structfield>QueryImageAttributes</structfield>
4771 are not required when the adaptor type does not contain
4772 <constant>XvImageMask</constant>.
4780 With the exception of <structfield>QueryImageAttributes</structfield>, these
4781 functions should return <constant>Success</constant> if the operation was
4782 completed successfully. They can return <constant>XvBadAlloc</constant>
4783 otherwise. <structfield>QueryImageAttributes</structfield> returns the size
4784 of the XvImage queried.
4788 If the <constant>VIDEO_NO_CLIPPING</constant>
4789 flag is set, the <literal remap="tt">clipBoxes</literal> may be ignored by
4790 the driver. <literal remap="tt">ClipBoxes</literal> is an <literal remap="tt">X-Y</literal>
4791 banded region identical to those used throughout the server.
4792 The clipBoxes represent the visible portions of the area determined
4793 by <literal remap="tt">drw_x</literal>, <literal remap="tt">drw_y</literal>,
4794 <literal remap="tt">drw_w</literal> and <literal remap="tt">drw_h</literal> in the Get/Put
4795 function. The boxes are in screen coordinates, are guaranteed
4796 not to overlap and an empty region will never be passed.
4797 If the driver has specified <constant>VIDEO_INVERT_CLIPLIST</constant>,
4798 <literal remap="tt">clipBoxes</literal> will indicate the areas of the primitive
4799 which are obscured rather than the areas visible.
4801 </para></listitem></varlistentry>
4806 typedef int (* PutVideoFuncPtr)( ScrnInfoPtr pScrn,
4807 short vid_x, short vid_y, short drw_x, short drw_y,
4808 short vid_w, short vid_h, short drw_w, short drw_h,
4809 RegionPtr clipBoxes, pointer data );
4812 This indicates that the driver should take a subsection
4813 <parameter>vid_w</parameter> by <parameter>vid_h</parameter> at location
4814 <parameter>(vid_x,vid_y)</parameter> from the video stream and direct
4815 it into the rectangle <parameter>drw_w</parameter> by <parameter>drw_h</parameter>
4816 at location <parameter>(drw_x,drw_y)</parameter> on the screen, scaling as
4817 necessary. Due to the large variations in capabilities of
4818 the various hardware expected to be used with this extension,
4819 it is not expected that all hardware will be able to do this
4820 exactly as described. In that case the driver should just do
4821 <quote>the best it can,</quote> scaling as closely to the target rectangle
4822 as it can without rendering outside of it. In the worst case,
4823 the driver can opt to just not turn on the video.
4826 </blockquote></para></blockquote>
4830 typedef int (* PutStillFuncPtr)( ScrnInfoPtr pScrn,
4831 short vid_x, short vid_y, short drw_x, short drw_y,
4832 short vid_w, short vid_h, short drw_w, short drw_h,
4833 RegionPtr clipBoxes, pointer data );
4836 This is same as <structfield>PutVideo</structfield> except that the driver
4837 should place only one frame from the stream on the screen.
4840 </blockquote></para></blockquote>
4844 typedef int (* GetVideoFuncPtr)( ScrnInfoPtr pScrn,
4845 short vid_x, short vid_y, short drw_x, short drw_y,
4846 short vid_w, short vid_h, short drw_w, short drw_h,
4847 RegionPtr clipBoxes, pointer data );
4850 This is same as <structfield>PutVideo</structfield> except that the driver
4851 gets video from the screen and outputs it. The driver should
4852 do the best it can to get the requested dimensions correct
4853 without reading from an area larger than requested.
4856 </blockquote></para></blockquote>
4860 typedef int (* GetStillFuncPtr)( ScrnInfoPtr pScrn,
4861 short vid_x, short vid_y, short drw_x, short drw_y,
4862 short vid_w, short vid_h, short drw_w, short drw_h,
4863 RegionPtr clipBoxes, pointer data );
4866 This is the same as <literal remap="tt">GetVideo</literal> except that the
4867 driver should place only one frame from the screen into the
4871 </blockquote></para></blockquote>
4875 typedef void (* StopVideoFuncPtr)(ScrnInfoPtr pScrn,
4876 pointer data, Bool cleanup);
4879 This indicates the driver should stop displaying the video.
4880 This is used to stop both input and output video. The
4881 <parameter>cleanup</parameter> field indicates that the video is
4882 being stopped because the client requested it to stop or
4883 because the server is exiting the current VT. In that case
4884 the driver should deallocate any offscreen memory areas (if
4885 there are any) being used to put the video to the screen. If
4886 <parameter>cleanup</parameter> is not set, the video is being stopped
4887 temporarily due to clipping or moving of the window, etc...
4888 and video will likely be restarted soon so the driver should
4889 not deallocate any offscreen areas associated with that port.
4892 </blockquote></para></blockquote>
4895 typedef int (* SetPortAttributeFuncPtr)(ScrnInfoPtr pScrn,
4896 Atom attribute,INT32 value, pointer data);
4900 typedef int (* GetPortAttributeFuncPtr)(ScrnInfoPtr pScrn,
4901 Atom attribute,INT32 *value, pointer data);
4904 A port may have particular attributes such as hue,
4905 saturation, brightness or contrast. Xv clients set and
4906 get these attribute values by sending attribute strings
4907 (Atoms) to the server. Such requests end up at these
4908 driver functions. It is recommended that the driver provide
4909 at least the following attributes mentioned in the Xv client
4911 <literallayout><constant>
4917 </constant></literallayout>
4918 but the driver may recognize as many atoms as it wishes. If
4919 a requested attribute is unknown by the driver it should return
4920 <constant>BadMatch</constant>. <constant>XV_ENCODING</constant> is the
4921 attribute intended to let the client specify which video
4922 encoding the particular port should be using (see the description
4923 of <structname>XF86VideoEncodingRec</structname> below). If the
4924 requested encoding is unsupported, the driver should return
4925 <constant>XvBadEncoding</constant>. If the value lies outside the
4926 advertised range <constant>BadValue</constant> may be returned.
4927 <constant>Success</constant> should be returned otherwise.
4930 </blockquote></para></blockquote>
4934 typedef void (* QueryBestSizeFuncPtr)(ScrnInfoPtr pScrn,
4935 Bool motion, short vid_w, short vid_h,
4936 short drw_w, short drw_h,
4937 unsigned int *p_w, unsigned int *p_h, pointer data);
4940 <function>QueryBestSize</function> provides the client with a way
4941 to query what the destination dimensions would end up being
4942 if they were to request that an area
4943 <parameter>vid_w</parameter> by <parameter>vid_h</parameter> from the video
4944 stream be scaled to rectangle of
4945 <parameter>drw_w</parameter> by <parameter>drw_h</parameter> on the screen.
4946 Since it is not expected that all hardware will be able to
4947 get the target dimensions exactly, it is important that the
4948 driver provide this function.
4951 </blockquote></para></blockquote>
4955 typedef int (* PutImageFuncPtr)( ScrnInfoPtr pScrn,
4956 short src_x, short src_y, short drw_x, short drw_y,
4957 short src_w, short src_h, short drw_w, short drw_h,
4958 int image, char *buf, short width, short height,
4959 Bool sync, RegionPtr clipBoxes, pointer data );
4962 This is similar to <structfield>PutStill</structfield> except that the
4963 source of the video is not a port but the data stored in a system
4964 memory buffer at <parameter>buf</parameter>. The data is in the format
4965 indicated by the <parameter>image</parameter> descriptor and represents a
4966 source of size <parameter>width</parameter> by <parameter>height</parameter>.
4967 If <parameter>sync</parameter> is TRUE the driver should not return
4968 from this function until it is through reading the data
4969 from <parameter>buf</parameter>. Returning when <parameter>sync</parameter>
4970 is TRUE indicates that it is safe for the data at <parameter>buf</parameter>
4971 to be replaced, freed, or modified.
4974 </blockquote></para></blockquote>
4978 typedef int (* QueryImageAttributesFuncPtr)( ScrnInfoPtr pScrn,
4979 int image, short *width, short *height,
4980 int *pitches, int *offsets);
4983 This function is called to let the driver specify how data for
4984 a particular <parameter>image</parameter> of size <parameter>width</parameter>
4985 by <parameter>height</parameter> should be stored. Sometimes only
4986 the size and corrected width and height are needed. In that
4987 case <parameter>pitches</parameter> and <parameter>offsets</parameter> are
4988 NULL. The size of the memory required for the image is returned
4989 by this function. The <parameter>width</parameter> and
4990 <parameter>height</parameter> of the requested image can be altered by
4991 the driver to reflect format limitations (such as component
4992 sampling periods that are larger than one). If
4993 <parameter>pitches</parameter> and <parameter>offsets</parameter> are not NULL,
4994 these will be arrays with as many elements in them as there
4995 are planes in the <parameter>image</parameter> format. The driver
4996 should specify the pitch (in bytes) of each scanline in the
4997 particular plane as well as the offset to that plane (in bytes)
4998 from the beginning of the image.
5001 </blockquote></para></blockquote>
5005 The XF86VideoEncodingRec:
5012 unsigned short width, height;
5014 } XF86VideoEncodingRec, *XF86VideoEncodingPtr;
5018 The <structname>XF86VideoEncodingRec</structname> specifies what encodings
5019 the adaptor can support. Most of this data is just informational
5020 and for the client's benefit, and is what will be reported by
5021 <function>XvQueryEncodings</function>. The <parameter>id</parameter> field is
5022 expected to be a unique identifier to allow the client to request a
5023 certain encoding via the <constant>XV_ENCODING</constant> attribute string.
5026 </blockquote></para></blockquote>
5030 The XF86VideoFormatRec:
5037 } XF86VideoFormatRec, *XF86VideoFormatPtr;
5041 This specifies what visuals the video is viewable in.
5042 <parameter>depth</parameter> is the depth of the visual (not bpp).
5043 <parameter>class</parameter> is the visual class such as
5044 <constant>TrueColor</constant>, <constant>DirectColor</constant> or
5045 <constant>PseudoColor</constant>. Initialization of an adaptor will fail
5046 if none of the visuals on that screen are supported.
5049 </blockquote></para></blockquote>
5053 The XF86AttributeRec:
5062 } XF86AttributeListRec, *XF86AttributeListPtr;
5066 Each adaptor may have an array of these advertising the attributes
5067 for its ports. Currently defined flags are <literal remap="tt">XvGettable</literal>
5068 and <literal remap="tt">XvSettable</literal> which may be OR'd together indicating that
5069 attribute is <quote>gettable</quote> or <quote>settable</quote> by the client. The
5070 <literal remap="tt">min</literal> and <literal remap="tt">max</literal> field specify the valid range
5071 for the value. <literal remap="tt">Name</literal> is a text string describing the
5075 </blockquote></para></blockquote>
5093 /* for RGB formats */
5095 unsigned int red_mask;
5096 unsigned int green_mask;
5097 unsigned int blue_mask;
5099 /* for YUV formats */
5100 unsigned int y_sample_bits;
5101 unsigned int u_sample_bits;
5102 unsigned int v_sample_bits;
5103 unsigned int horz_y_period;
5104 unsigned int horz_u_period;
5105 unsigned int horz_v_period;
5106 unsigned int vert_y_period;
5107 unsigned int vert_u_period;
5108 unsigned int vert_v_period;
5109 char component_order[32];
5111 } XF86ImageRec, *XF86ImagePtr;
5115 XF86ImageRec describes how video source data is laid out in memory.
5116 The fields are as follows:
5120 <term><structfield>id</structfield></term>
5122 This is a unique descriptor for the format. It is often good to
5123 set this value to the FOURCC for the format when applicable.
5124 </para></listitem></varlistentry>
5127 <term><structfield>type</structfield></term>
5129 This is <constant>XvRGB</constant> or <constant>XvYUV</constant>.
5130 </para></listitem></varlistentry>
5133 <term><structfield>byte_order</structfield></term>
5135 This is <constant>LSBFirst</constant> or <constant>MSBFirst</constant>.
5136 </para></listitem></varlistentry>
5139 <term><structfield>guid</structfield></term>
5141 This is the Globally Unique IDentifier for the format. When
5142 not applicable, all characters should be NULL.
5143 </para></listitem></varlistentry>
5146 <term><structfield>bits_per_pixel</structfield></term>
5148 The number of bits taken up (but not necessarily used) by each
5149 pixel. Note that for some planar formats which have fractional
5150 bits per pixel (such as IF09) this number may be rounded _down_.
5151 </para></listitem></varlistentry>
5154 <term><structfield>format</structfield></term>
5156 This is <constant>XvPlanar</constant> or <constant>XvPacked</constant>.
5157 </para></listitem></varlistentry>
5160 <term><structfield>num_planes</structfield></term>
5162 The number of planes in planar formats. This should be set to
5163 one for packed formats.
5164 </para></listitem></varlistentry>
5167 <term><structfield>depth</structfield></term>
5169 The significant bits per pixel in RGB formats (analgous to the
5170 depth of a pixmap format).
5171 </para></listitem></varlistentry>
5174 <term><structfield>red_mask</structfield></term>
5175 <term><structfield>green_mask</structfield></term>
5176 <term><structfield>blue_mask</structfield></term>
5178 The red, green and blue bitmasks for packed RGB formats.
5179 </para></listitem></varlistentry>
5182 <term><structfield>y_sample_bits</structfield></term>
5183 <term><structfield>u_sample_bits</structfield></term>
5184 <term><structfield>v_sample_bits</structfield></term>
5186 The y, u and v sample sizes (in bits).
5187 </para></listitem></varlistentry>
5190 <term><structfield>horz_y_period</structfield></term>
5191 <term><structfield>horz_u_period</structfield></term>
5192 <term><structfield>horz_v_period</structfield></term>
5194 The y, u and v sampling periods in the horizontal direction.
5195 </para></listitem></varlistentry>
5198 <term><structfield>vert_y_period</structfield></term>
5199 <term><structfield>vert_u_period</structfield></term>
5200 <term><structfield>vert_v_period</structfield></term>
5202 The y, u and v sampling periods in the vertical direction.
5203 </para></listitem></varlistentry>
5206 <term><structfield>component_order</structfield></term>
5208 Uppercase ascii characters representing the order that
5209 samples are stored within packed formats. For planar formats
5210 this represents the ordering of the planes. Unused characters
5211 in the 32 byte string should be set to NULL.
5212 </para></listitem></varlistentry>
5215 <term><structfield>scanline_order</structfield></term>
5217 This is <constant>XvTopToBottom</constant> or <constant>XvBottomToTop</constant>.
5218 </para></listitem></varlistentry>
5224 Since some formats (particular some planar YUV formats) may not
5225 be completely defined by the parameters above, the guid, when
5226 available, should provide the most accurate description of the
5230 </blockquote></para></blockquote>
5235 <title>The Loader</title>
5238 This section describes the interfaces to the module loader. The loader
5239 interfaces can be divided into two groups: those that are only available to
5240 the XFree86 common layer, and those that are also available to modules.
5244 <title>Loader Overview</title>
5247 The loader is capable of loading modules in a range of object formats,
5248 and knowledge of these formats is built in to the loader. Knowledge of
5249 new object formats can be added to the loader in a straightforward
5250 manner. This makes it possible to provide OS-independent modules (for
5251 a given CPU architecture type). In addition to this, the loader can
5252 load modules via the OS-provided <function>dlopen(3)</function> service where
5253 available. Such modules are not platform independent, and the semantics
5254 of <function>dlopen()</function> on most systems results in significant
5255 limitations in the use of modules of this type. Support for
5256 <function>dlopen()</function> modules in the loader is primarily for
5257 experimental and development purposes.
5261 Symbols exported by the loader (on behalf of the core X server) to
5262 modules are determined at compile time. Only those symbols explicitly
5263 exported are available to modules. All external symbols of loaded
5264 modules are exported to other modules, and to the core X server. The
5265 loader can be requested to check for unresolved symbols at any time,
5266 and the action to be taken for unresolved symbols can be controlled by
5267 the caller of the loader. Typically the caller identifies which symbols
5268 can safely remain unresolved and which cannot.
5272 NOTE: Now that ISO-C allows pointers to functions and pointers to data to
5273 have different internal representations, some of the following interfaces
5274 will need to be revisited.
5279 <title>Semi-private Loader Interface</title>
5282 The following is the semi-private loader interface that is available to the
5283 XFree86 common layer.
5288 void LoaderInit(void);
5291 The <function>LoaderInit()</function> function initialises the loader,
5292 and it must be called once before calling any other loader functions.
5293 This function initialises the tables of exported symbols, and anything
5294 else that might need to be initialised.
5297 </blockquote></para></blockquote>
5301 void LoaderSetPath(const char *path);
5304 The <function>LoaderSetPath()</function> function initialises a default
5305 module search path. This must be called if calls to other functions
5306 are to be made without explicitly specifying a module search path.
5307 The search path <parameter>path</parameter> must be a string of one or more
5308 comma separated absolute paths. Modules are expected to be located
5309 below these paths, possibly in subdirectories of these paths.
5312 </blockquote></para></blockquote>
5316 pointer LoadModule(const char *module, const char *path,
5317 const char **subdirlist, const char **patternlist,
5318 pointer options, const XF86ModReqInfo * modreq,
5319 int *errmaj, int *errmin);
5322 The <function>LoadModule()</function> function loads the module called
5323 <parameter>module</parameter>. The return value is a module handle, and
5324 may be used in future calls to the loader that require a reference
5325 to a loaded module. The module name <parameter>module</parameter> is
5326 normally the module's canonical name, which doesn't contain any
5327 directory path information, or any object/library file prefixes of
5328 suffixes. Currently a full pathname and/or filename is also accepted.
5329 This might change. The other parameters are:
5333 <term><parameter>path</parameter></term>
5335 An optional comma-separated list of module search paths.
5336 When <constant>NULL</constant>, the default search path is used.
5337 </para></listitem></varlistentry>
5341 <term><parameter>subdirlist</parameter></term>
5343 An optional <constant>NULL</constant> terminated list of
5344 subdirectories to search. When <constant>NULL</constant>,
5345 the default built-in list is used (refer to
5346 <varname>stdSubdirs</varname> in <filename>loadmod.c</filename>).
5347 The default list is also substituted for entries in
5348 <parameter>subdirlist</parameter> with the value
5349 <constant>DEFAULT_LIST</constant>. This makes is possible
5350 to augment the default list instead of replacing it.
5351 Subdir elements must be relative, and must not contain
5352 <literal remap="tt">".."</literal>. If any violate this requirement,
5354 </para></listitem></varlistentry>
5358 <term><parameter>patternlist</parameter></term>
5360 An optional <constant>NULL</constant> terminated list of
5361 POSIX regular expressions used to connect module
5362 filenames with canonical module names. Each regex
5363 should contain exactly one subexpression that corresponds
5364 to the canonical module name. When <constant>NULL</constant>,
5365 the default built-in list is used (refer to
5366 <varname>stdPatterns</varname> in
5367 <filename>loadmod.c</filename>). The default list is also
5368 substituted for entries in <parameter>patternlist</parameter>
5369 with the value <constant>DEFAULT_LIST</constant>. This
5370 makes it possible to augment the default list instead
5372 </para></listitem></varlistentry>
5376 <term><parameter>options</parameter></term>
5378 An optional parameter that is passed to the newly
5379 loaded module's <literal remap="tt">SetupProc</literal> function
5380 (if it has one). This argument is normally a
5381 <constant>NULL</constant> terminated list of
5382 <structname>Options</structname>, and must be interpreted that
5383 way by modules loaded directly by the XFree86 common
5384 layer. However, it may be used for application-specific
5385 parameter passing in other situations.
5389 When loading <quote>external</quote> modules (modules that don't
5390 have the standard entry point, for example a
5391 special shared library) the options parameter can be
5392 set to <constant>EXTERN_MODULE</constant> to tell the
5393 loader not to reject the module when it doesn't find
5394 the standard entry point.
5395 </para></listitem></varlistentry>
5399 <term><parameter>modreq</parameter></term>
5401 An optional <structname>XF86ModReqInfo*</structname> containing
5402 version/ABI/vendor information to requirements to
5403 check the newly loaded module against. The main
5404 purpose of this is to allow the loader to verify that
5405 a module of the correct type/version before running
5406 its <function>SetupProc</function> function.
5410 The <literal remap="tt">XF86ModReqInfo</literal> struct is defined
5414 CARD8 majorversion; /* MAJOR_UNSPEC */
5415 CARD8 minorversion; /* MINOR_UNSPEC */
5416 CARD16 patchlevel; /* PATCH_UNSPEC */
5417 const char * abiclass; /* ABI_CLASS_NONE */
5418 CARD32 abiversion; /* ABI_VERS_UNSPEC */
5419 const char * moduleclass; /* MOD_CLASS_NONE */
5423 The information here is compared against the equivalent
5424 information in the module's
5425 <structname>XF86ModuleVersionInfo</structname> record (which
5426 is described below). The values in comments above
5427 indicate <quote>don't care</quote> settings for each of the fields.
5428 The comparisons made are as follows:
5432 <term><structfield>majorversion</structfield></term>
5434 Must match the module's majorversion
5436 </para></listitem></varlistentry>
5439 <term><structfield>minorversion</structfield></term>
5441 The module's minor version must be
5442 no less than this value. This
5443 comparison is only made if
5444 <structfield>majorversion</structfield> is
5445 specified and matches.
5446 </para></listitem></varlistentry>
5449 <term><structfield>patchlevel</structfield></term>
5451 The module's patchlevel must be no
5452 less than this value. This comparison
5454 <structfield>minorversion</structfield> is
5455 specified and matches.
5456 </para></listitem></varlistentry>
5459 <term><structfield>abiclass</structfield></term>
5461 String must match the module's abiclass
5463 </para></listitem></varlistentry>
5466 <term><structfield>abiversion</structfield></term>
5468 Must be consistent with the module's
5469 abiversion (major equal, minor no
5471 </para></listitem></varlistentry>
5474 <term><structfield>moduleclass</structfield></term>
5476 String must match the module's
5478 </para></listitem></varlistentry>
5481 </para></listitem></varlistentry>
5484 <term><parameter>errmaj</parameter></term>
5486 An optional pointer to a variable holding the major
5487 part or the error code. When provided,
5488 <parameter>*errmaj</parameter> is filled in when
5489 <function>LoadModule()</function> fails.
5490 </para></listitem></varlistentry>
5493 <term><parameter>errmin</parameter></term>
5495 Like <parameter>errmaj</parameter>, but for the minor part
5497 </para></listitem></varlistentry>
5501 </para></blockquote>
5502 </para></blockquote>
5506 void UnloadModule(pointer mod);
5509 This function unloads the module referred to by the handle mod.
5510 All child modules are also unloaded recursively. This function must
5511 not be used to directly unload modules that are child modules (i.e.,
5512 those that have been loaded with the <function>LoadSubModule()</function>
5516 </blockquote></para></blockquote>
5520 <title>Module Requirements</title>
5523 Modules must provide information about themselves to the loader, and
5524 may optionally provide entry points for "setup" and "teardown" functions
5525 (those two functions are referred to here as <function>SetupProc</function>
5526 and <function>TearDownProc</function>).
5530 The module information is contained in the
5531 <structname>XF86ModuleVersionInfo</structname> struct, which is defined as follows:
5535 const char * modname; /* name of module, e.g. "foo" */
5536 const char * vendor; /* vendor specific string */
5537 CARD32 _modinfo1_; /* constant MODINFOSTRING1/2 to find */
5538 CARD32 _modinfo2_; /* infoarea with a binary editor/sign tool */
5539 CARD32 xf86version; /* contains XF86_VERSION_CURRENT */
5540 CARD8 majorversion; /* module-specific major version */
5541 CARD8 minorversion; /* module-specific minor version */
5542 CARD16 patchlevel; /* module-specific patch level */
5543 const char * abiclass; /* ABI class that the module uses */
5544 CARD32 abiversion; /* ABI version */
5545 const char * moduleclass; /* module class */
5546 CARD32 checksum[4]; /* contains a digital signature of the */
5547 /* version info structure */
5548 } XF86ModuleVersionInfo;
5551 The fields are used as follows:
5555 <term><structfield>modname</structfield></term>
5557 The module's name. This field is currently only for
5558 informational purposes, but the loader may be modified
5559 in future to require it to match the module's canonical
5561 </para></listitem></varlistentry>
5565 <term><structfield>vendor</structfield></term>
5567 The module vendor. This field is for informational purposes
5569 </para></listitem></varlistentry>
5573 <term><structfield>_modinfo1_</structfield></term>
5575 This field holds the first part of a signature that can
5576 be used to locate this structure in the binary. It should
5577 always be initialised to <constant>MODINFOSTRING1</constant>.
5578 </para></listitem></varlistentry>
5582 <term><structfield>_modinfo2_</structfield></term>
5584 This field holds the second part of a signature that can
5585 be used to locate this structure in the binary. It should
5586 always be initialised to <constant>MODINFOSTRING2</constant>.
5587 </para></listitem></varlistentry>
5591 <term><structfield>xf86version</structfield></term>
5593 The XFree86 version against which the module was compiled.
5594 This is mostly for informational/diagnostic purposes. It
5595 should be initialised to <constant>XF86_VERSION_CURRENT</constant>, which is
5596 defined in <filename>xf86Version.h</filename>.
5597 </para></listitem></varlistentry>
5601 <term><structfield>majorversion</structfield></term>
5603 The module-specific major version. For modules where this
5604 version is used for more than simply informational
5605 purposes, the major version should only change (be
5606 incremented) when ABI incompatibilities are introduced,
5607 or ABI components are removed.
5608 </para></listitem></varlistentry>
5612 <term><structfield>minorversion</structfield></term>
5614 The module-specific minor version. For modules where this
5615 version is used for more than simply informational
5616 purposes, the minor version should only change (be
5617 incremented) when ABI additions are made in a backward
5618 compatible way. It should be reset to zero when the major
5619 version is increased.
5620 </para></listitem></varlistentry>
5624 <term><structfield>patchlevel</structfield></term>
5626 The module-specific patch level. The patch level should
5627 increase with new revisions of the module where there
5628 are no ABI changes, and it should be reset to zero when
5629 the minor version is increased.
5630 </para></listitem></varlistentry>
5634 <term><structfield>abiclass</structfield></term>
5636 The ABI class that the module requires. The class is
5637 specified as a string for easy extensibility. It should
5638 indicate which (if any) of the X server's built-in ABI
5639 classes that the module relies on, or a third-party ABI
5640 if appropriate. Built-in ABI classes currently defined are:
5644 <term><constant>ABI_CLASS_NONE</constant></term>
5645 <listitem><para>no class
5646 </para></listitem></varlistentry>
5648 <term><constant>ABI_CLASS_ANSIC</constant></term>
5649 <listitem><para>only requires the ANSI C interfaces
5650 </para></listitem></varlistentry>
5652 <term><constant>ABI_CLASS_VIDEODRV</constant></term>
5653 <listitem><para>requires the video driver ABI
5654 </para></listitem></varlistentry>
5656 <term><constant>ABI_CLASS_XINPUT</constant></term>
5657 <listitem><para>requires the XInput driver ABI
5658 </para></listitem></varlistentry>
5660 <term><constant>ABI_CLASS_EXTENSION</constant></term>
5661 <listitem><para>requires the extension module ABI
5662 </para></listitem></varlistentry>
5664 <term><constant>ABI_CLASS_FONT</constant></term>
5665 <listitem><para>requires the font module ABI
5666 </para></listitem></varlistentry>
5669 </para></listitem></varlistentry>
5672 <term><structfield>abiversion</structfield></term>
5674 The version of abiclass that the module requires. The
5675 version consists of major and minor components. The
5676 major version must match and the minor version must be
5677 no newer than that provided by the server or parent
5678 module. Version identifiers for the built-in classes
5679 currently defined are:
5681 <literallayout><constant>
5683 ABI_VIDEODRV_VERSION
5685 ABI_EXTENSION_VERSION
5687 </constant></literallayout>
5689 </para></listitem></varlistentry>
5692 <term><structfield>moduleclass</structfield></term>
5694 This is similar to the abiclass field, except that it
5695 defines the type of module rather than the ABI it
5696 requires. For example, although all video drivers require
5697 the video driver ABI, not all modules that require the
5698 video driver ABI are video drivers. This distinction
5699 can be made with the moduleclass. Currently pre-defined
5702 <literallayout><constant>
5708 </constant></literallayout>
5710 </para></listitem></varlistentry>
5713 <term><structfield>checksum</structfield></term>
5716 </para></listitem></varlistentry>
5722 The module version information, and the optional <function>SetupProc</function>
5723 and <function>TearDownProc</function> entry points are found by the loader
5724 by locating a data object in the module called "modnameModuleData",
5725 where "modname" is the canonical name of the module. Modules must
5726 contain such a data object, and it must be declared with global scope,
5727 be compile-time initialised, and is of the following type:
5731 XF86ModuleVersionInfo * vers;
5732 ModuleSetupProc setup;
5733 ModuleTearDownProc teardown;
5739 The vers parameter must be initialised to a pointer to a correctly
5740 initialised <structname>XF86ModuleVersionInfo</structname> struct. The other
5741 two parameter are optional, and should be initialised to
5742 <constant>NULL</constant> when not required. The other parameters are defined
5747 typedef pointer (*ModuleSetupProc)(pointer, pointer, int *, int *);
5749 typedef void (*ModuleTearDownProc)(pointer);
5751 pointer SetupProc(pointer module, pointer options,
5752 int *errmaj, int *errmin);
5755 When defined, this function is called by the loader after successfully
5756 loading a module. module is a handle for the newly loaded module,
5757 and maybe used by the <function>SetupProc</function> if it calls other
5758 loader functions that require a reference to it. The remaining
5759 arguments are those that were passed to the
5760 <function>LoadModule()</function> (or <function>LoadSubModule()</function>),
5761 and are described above. When the <function>SetupProc</function> is
5762 successful it must return a non-<constant>NULL</constant> value. The
5763 loader checks this, and if it is <constant>NULL</constant> it unloads
5764 the module and reports the failure to the caller of
5765 <function>LoadModule()</function>. If the <function>SetupProc</function>
5766 does things that need to be undone when the module is unloaded,
5767 it should define a <function>TearDownProc</function>, and return a
5768 pointer that the <function>TearDownProc</function> can use to undo what
5773 When a module is loaded multiple times, the <function>SetupProc</function>
5774 is called once for each time it is loaded.
5777 </blockquote></para></blockquote>
5781 void TearDownProc(pointer tearDownData);
5784 When defined, this function is called when the loader unloads a
5785 module. The <parameter>tearDownData</parameter> parameter is the return
5786 value of the <function>SetupProc()</function> that was called when the
5787 module was loaded. The purpose of this function is to clean up
5788 before the module is unloaded (for example, by freeing allocated
5792 </blockquote></para></blockquote>
5797 <title>Public Loader Interface</title>
5800 The following is the Loader interface that is available to any part of
5801 the server, and may also be used from within modules.
5806 pointer LoadSubModule(pointer parent, const char *module,
5807 const char **subdirlist, const char **patternlist,
5808 pointer options, const XF86ModReqInfo * modreq,
5809 int *errmaj, int *errmin);
5812 This function is like the <function>LoadModule()</function> function
5813 described above, except that the module loaded is registered as a
5814 child of the calling module. The <parameter>parent</parameter> parameter
5815 is the calling module's handle. Modules loaded with this function
5816 are automatically unloaded when the parent module is unloaded. The
5817 other difference is that the path parameter may not be specified.
5818 The module search path used for modules loaded with this function
5819 is the default search path as initialised with
5820 <function>LoaderSetPath()</function>.
5823 </blockquote></para></blockquote>
5827 void UnloadSubModule(pointer module);
5830 This function unloads the module with handle <parameter>module</parameter>.
5831 If that module itself has children, they are also unloaded. It is
5832 like <function>UnloadModule()</function>, except that it is safe to use
5833 for unloading child modules.
5836 </blockquote></para></blockquote>
5840 pointer LoaderSymbol(const char *symbol);
5843 This function returns the address of the symbol with name
5844 <parameter>symbol</parameter>. This may be used to locate a module entry
5845 point with a known name.
5848 </blockquote></para></blockquote>
5852 char **LoaderlistDirs(const char **subdirlist,
5853 const char **patternlist);
5856 This function returns a <constant>NULL</constant> terminated list of
5857 canonical modules names for modules found in the default module
5858 search path. The <parameter>subdirlist</parameter> and
5859 <parameter>patternlist</parameter> parameters are as described above, and
5860 can be used to control the locations and names that are searched.
5861 If no modules are found, the return value is <constant>NULL</constant>.
5862 The returned list should be freed by calling
5863 <function>LoaderFreeDirList()</function> when it is no longer needed.
5866 </blockquote></para></blockquote>
5870 void LoaderFreeDirList(char **list);
5873 This function frees a module list created by
5874 <function>LoaderlistDirs()</function>.
5877 </blockquote></para></blockquote>
5881 void LoaderReqSymLists(const char **list0, ...);
5884 This function allows the registration of required symbols with the
5885 loader. It is normally used by a caller of
5886 <function>LoadSubModule()</function>. If any symbols registered in this
5887 way are found to be unresolved when
5888 <function>LoaderCheckUnresolved()</function> is called then
5889 <function>LoaderCheckUnresolved()</function> will report a failure.
5890 The function takes one or more <constant>NULL</constant> terminated
5891 lists of symbols. The end of the argument list is indicated by a
5892 <constant>NULL</constant> argument.
5895 </blockquote></para></blockquote>
5899 void LoaderReqSymbols(const char *sym0, ...);
5902 This function is like <function>LoaderReqSymLists()</function> except
5903 that its arguments are symbols rather than lists of symbols. This
5904 function is more convenient when single functions are to be registered,
5905 especially when the single function might depend on runtime factors.
5906 The end of the argument list is indicated by a <constant>NULL</constant>
5910 </blockquote></para></blockquote>
5914 void LoaderRefSymLists(const char **list0, ...);
5917 This function allows the registration of possibly unresolved symbols
5918 with the loader. When <function>LoaderCheckUnresolved()</function> is
5919 run it won't generate warnings for symbols registered in this way
5920 unless they were also registered as required symbols.
5921 The function takes one or more <constant>NULL</constant> terminated
5922 lists of symbols. The end of the argument list is indicated by a
5923 <constant>NULL</constant> argument.
5926 </blockquote></para></blockquote>
5930 void LoaderRefSymbols(const char *sym0, ...);
5933 This function is like <function>LoaderRefSymLists()</function> except
5934 that its arguments are symbols rather than lists of symbols. This
5935 function is more convenient when single functions are to be registered,
5936 especially when the single function might depend on runtime factors.
5937 The end of the argument list is indicated by a <constant>NULL</constant>
5941 </blockquote></para></blockquote>
5945 int LoaderCheckUnresolved(int delayflag);
5948 This function checks for unresolved symbols. It generates warnings
5949 for unresolved symbols that have not been registered with
5950 <function>LoaderRefSymLists()</function>, and maps them to a dummy
5951 function. This behaviour may change in future. If unresolved
5952 symbols are found that have been registered with
5953 <function>LoaderReqSymLists()</function> or
5954 <function>LoaderReqSymbols()</function> then this function returns a
5955 non-zero value. If none of these symbols are unresolved the return
5956 value is zero, indicating success.
5960 The <parameter>delayflag</parameter> parameter should normally be set to
5961 <constant>LD_RESOLV_IFDONE</constant>.
5964 </blockquote></para></blockquote>
5968 LoaderErrorMsg(const char *name, const char *modname,
5969 int errmaj, int errmin);
5972 This function prints an error message that includes the text <quote>Failed
5973 to load module</quote>, the module name <parameter>modname</parameter>, a message
5974 specific to the <parameter>errmaj</parameter> value, and the value if
5975 <parameter>errmin</parameter>. If <parameter>name</parameter> is
5976 non-<constant>NULL</constant>, it is printed as an identifying prefix
5977 to the message (followed by a <quote>:</quote>).
5980 </blockquote></para></blockquote>
5984 <title>Special Registration Functions</title>
5987 The loader contains some functions for registering some classes of modules.
5988 These may be moved out of the loader at some point.
5993 void LoadExtension(ExtensionModule *ext);
5996 This registers the entry points for the extension identified by
5997 <parameter>ext</parameter>. The <structname>ExtensionModule</structname> struct is
6002 InitExtension initFunc;
6005 InitExtension setupFunc;
6010 </blockquote></para></blockquote>
6014 void LoadFont(FontModule *font);
6017 This registers the entry points for the font rasteriser module
6018 identified by <parameter>font</parameter>. The <structname>FontModule</structname>
6019 struct is defined as:
6030 </blockquote></para></blockquote>
6037 <title>Helper Functions</title>
6040 This section describe <quote>helper</quote> functions that video driver
6041 might find useful. While video drivers are not required to use any of
6042 these to be considered <quote>compliant</quote>, the use of appropriate helpers is
6043 strongly encouraged to improve the consistency of driver behaviour.
6047 <title>Functions for printing messages</title>
6051 ErrorF(const char *format, ...);
6054 This is the basic function for writing to the error log (typically
6055 stderr and/or a log file). Video drivers should usually avoid
6056 using this directly in favour of the more specialised functions
6057 described below. This function is useful for printing messages
6058 while debugging a driver.
6061 </blockquote></para></blockquote>
6065 FatalError(const char *format, ...);
6068 This prints a message and causes the Xserver to abort. It should
6069 rarely be used within a video driver, as most error conditions
6070 should be flagged by the return values of the driver functions.
6071 This allows the higher layers to decide how to proceed. In rare
6072 cases, this can be used within a driver if a fatal unexpected
6076 </blockquote></para></blockquote>
6080 xf86ErrorF(const char *format, ...);
6083 This is like <function>ErrorF()</function>, except that the message is
6084 only printed when the Xserver's verbosity level is set to the
6085 default (<constant>1</constant>) or higher. It means that the messages
6086 are not printed when the server is started with the
6087 <option>-quiet</option> flag. Typically this function would only be
6088 used for continuing messages started with one of the more specialised
6089 functions described below.
6092 </blockquote></para></blockquote>
6096 xf86ErrorFVerb(int verb, const char *format, ...);
6099 Like <function>xf86ErrorF()</function>, except the minimum verbosity
6100 level for which the message is to be printed is given explicitly.
6101 Passing a <parameter>verb</parameter> value of zero means the message
6102 is always printed. A value higher than <constant>1</constant> can be
6103 used for information would normally not be needed, but which might
6104 be useful when diagnosing problems.
6107 </blockquote></para></blockquote>
6112 xf86Msg(MessageType type, const char *format, ...);
6115 This is like <function>xf86ErrorF()</function>, except that the message
6116 is prefixed with a marker determined by the value of
6117 <parameter>type</parameter>. The marker is used to indicate the type of
6118 message (warning, error, probed value, config value, etc). Note
6119 the <varname>xf86Verbose</varname> value is ignored for messages of
6120 type <constant>X_ERROR</constant>.
6124 The marker values are:
6128 <term><constant>X_PROBED</constant></term>
6129 <listitem><para>Value was probed.
6130 </para></listitem></varlistentry>
6132 <term><constant>X_CONFIG</constant></term>
6133 <listitem><para>Value was given in the config file.
6134 </para></listitem></varlistentry>
6136 <term><constant>X_DEFAULT</constant></term>
6137 <listitem><para>Value is a default.
6138 </para></listitem></varlistentry>
6140 <term><constant>X_CMDLINE</constant></term>
6141 <listitem><para>Value was given on the command line.
6142 </para></listitem></varlistentry>
6144 <term><constant>X_NOTICE</constant></term>
6145 <listitem><para>Notice.
6146 </para></listitem></varlistentry>
6148 <term><constant>X_ERROR</constant></term>
6149 <listitem><para>Error message.
6150 </para></listitem></varlistentry>
6152 <term><constant>X_WARNING</constant></term>
6153 <listitem><para>Warning message.
6154 </para></listitem></varlistentry>
6156 <term><constant>X_INFO</constant></term>
6157 <listitem><para>Informational message.
6158 </para></listitem></varlistentry>
6160 <term><constant>X_NONE</constant></term>
6161 <listitem><para>No prefix.
6162 </para></listitem></varlistentry>
6164 <term><constant>X_NOT_IMPLEMENTED</constant></term>
6165 <listitem><para>The message relates to functionality
6166 that is not yetimplemented.
6167 </para></listitem></varlistentry>
6172 </blockquote></para></blockquote>
6176 xf86MsgVerb(MessageType type, int verb, const char *format, ...);
6179 Like <function>xf86Msg()</function>, but with the verbosity level given
6183 </blockquote></para></blockquote>
6187 xf86DrvMsg(int scrnIndex, MessageType type, const char *format, ...);
6190 This is like <function>xf86Msg()</function> except that the driver's
6191 name (the <structfield>name</structfield> field of the
6192 <structname>ScrnInfoRec</structname>) followed by the
6193 <parameter>scrnIndex</parameter> in parentheses is printed following the
6194 prefix. This should be used by video drivers in most cases as it
6195 clearly indicates which driver/screen the message is for. If
6196 <parameter>scrnIndex</parameter> is negative, this function behaves
6197 exactly like <function>xf86Msg()</function>.
6201 NOTE: This function can only be used after the
6202 <structname>ScrnInfoRec</structname> and its <structfield>name</structfield> field
6203 have been allocated. Normally, this means that it can not be
6204 used before the END of the <function>ChipProbe()</function> function.
6205 Prior to that, use <function>xf86Msg()</function>, providing the
6206 driver's name explicitly. No screen number can be supplied at
6210 </blockquote></para></blockquote>
6214 xf86DrvMsgVerb(int scrnIndex, MessageType type, int verb,
6215 const char *format, ...);
6218 Like <function>xf86DrvMsg()</function>, but with the verbosity level
6222 </blockquote></para></blockquote>
6227 <title>Functions for setting values based on command line and config file</title>
6231 Bool xf86SetDepthBpp(ScrnInfoPtr scrp, int depth, int bpp,
6233 int fbbpp, int depth24flags);
6236 This function sets the <structfield>depth</structfield>, <structfield>pixmapBPP</structfield> and <structfield>bitsPerPixel</structfield> fields
6237 of the <structname>ScrnInfoRec</structname>. It also determines the defaults for display-wide
6238 attributes and pixmap formats the screen will support, and finds
6239 the Display subsection that matches the depth/bpp. This function
6240 should normally be called very early from the
6241 <function>ChipPreInit()</function> function.
6245 It requires that the <structfield>confScreen</structfield> field of the <structname>ScrnInfoRec</structname> be
6246 initialised prior to calling it. This is done by the XFree86
6247 common layer prior to calling <function>ChipPreInit()</function>.
6251 The parameters passed are:
6255 <term><parameter>depth</parameter></term>
6257 driver's preferred default depth if no other is given.
6258 If zero, use the overall server default.
6259 </para></listitem></varlistentry>
6262 <term><parameter>bpp</parameter></term>
6264 Same, but for the pixmap bpp.
6265 </para></listitem></varlistentry>
6268 <term><parameter>fbbpp</parameter></term>
6270 Same, but for the framebuffer bpp.
6271 </para></listitem></varlistentry>
6274 <term><parameter>depth24flags</parameter></term>
6276 Flags that indicate the level of 24/32bpp support
6277 and whether conversion between different framebuffer
6278 and pixmap formats is supported. The flags for this
6279 argument are defined as follows, and multiple flags
6280 may be ORed together:
6284 <term><constant>NoDepth24Support</constant></term>
6285 <listitem><para>No depth 24 formats supported
6286 </para></listitem></varlistentry>
6288 <term><constant>Support24bppFb</constant></term>
6289 <listitem><para>24bpp framebuffer supported
6290 </para></listitem></varlistentry>
6292 <term><constant>Support32bppFb</constant></term>
6293 <listitem><para>32bpp framebuffer supported
6294 </para></listitem></varlistentry>
6296 <term><constant>SupportConvert24to32</constant></term>
6297 <listitem><para>Can convert 24bpp pixmap to 32bpp fb
6298 </para></listitem></varlistentry>
6300 <term><constant>SupportConvert32to24</constant></term>
6301 <listitem><para>Can convert 32bpp pixmap to 24bpp fb
6302 </para></listitem></varlistentry>
6304 <term><constant>ForceConvert24to32</constant></term>
6305 <listitem><para>Force 24bpp pixmap to 32bpp fb conversion
6306 </para></listitem></varlistentry>
6308 <term><constant>ForceConvert32to24</constant></term>
6309 <listitem><para>Force 32bpp pixmap to 24bpp fb conversion
6310 </para></listitem></varlistentry>
6312 </para></listitem></varlistentry>
6318 It uses the command line, config file, and default values in the
6319 correct order of precedence to determine the depth and bpp values.
6320 It is up to the driver to check the results to see that it supports
6321 them. If not the <function>ChipPreInit()</function> function should
6322 return <constant>FALSE</constant>.
6326 If only one of depth/bpp is given, the other is set to a reasonable
6327 (and consistent) default.
6331 If a driver finds that the initial <parameter>depth24flags</parameter>
6332 it uses later results in a fb format that requires more video
6333 memory than is available it may call this function a second time
6334 with a different <parameter>depth24flags</parameter> setting.
6338 On success, the return value is <constant>TRUE</constant>. On failure
6339 it prints an error message and returns <constant>FALSE</constant>.
6343 The following fields of the <structname>ScrnInfoRec</structname> are
6344 initialised by this function:
6347 <structfield>depth</structfield>, <structfield>bitsPerPixel</structfield>,
6348 <structfield>display</structfield>, <structfield>imageByteOrder</structfield>,
6349 <structfield>bitmapScanlinePad</structfield>,
6350 <structfield>bitmapScanlineUnit</structfield>, <structfield>bitmapBitOrder</structfield>,
6351 <structfield>numFormats</structfield>, <structfield>formats</structfield>,
6352 <structfield>fbFormat</structfield>.
6353 </para></blockquote>
6356 </blockquote></para></blockquote>
6360 void xf86PrintDepthBpp(scrnInfoPtr scrp);
6363 This function can be used to print out the depth and bpp settings.
6364 It should be called after the final call to
6365 <function>xf86SetDepthBpp()</function>.
6368 </blockquote></para></blockquote>
6372 Bool xf86SetWeight(ScrnInfoPtr scrp, rgb weight, rgb mask);
6375 This function sets the <structfield>weight</structfield>, <structfield>mask</structfield>,
6376 <structfield>offset</structfield> and <structfield>rgbBits</structfield> fields of the
6377 <structname>ScrnInfoRec</structname>. It would normally be called fairly
6378 early in the <function>ChipPreInit()</function> function for
6379 depths > 8bpp.
6383 It requires that the <structfield>depth</structfield> and
6384 <structfield>display</structfield> fields of the <structname>ScrnInfoRec</structname>
6385 be initialised prior to calling it.
6389 The parameters passed are:
6393 <term><parameter>weight</parameter></term>
6395 driver's preferred default weight if no other is given.
6396 If zero, use the overall server default.
6398 </para></listitem></varlistentry>
6401 <term><parameter>mask</parameter></term>
6405 </para></listitem></varlistentry>
6410 It uses the command line, config file, and default values in the
6411 correct order of precedence to determine the weight value. It
6412 derives the mask and offset values from the weight and the defaults.
6413 It is up to the driver to check the results to see that it supports
6414 them. If not the <function>ChipPreInit()</function> function should
6415 return <constant>FALSE</constant>.
6419 On success, this function prints a message showing the weight
6420 values selected, and returns <constant>TRUE</constant>.
6424 On failure it prints an error message and returns <constant>FALSE</constant>.
6428 The following fields of the <structname>ScrnInfoRec</structname> are
6429 initialised by this function:
6432 <structfield>weight</structfield>,
6433 <structfield>mask</structfield>,
6434 <structfield>offset</structfield>.
6435 </para></blockquote>
6438 </blockquote></para></blockquote>
6442 Bool xf86SetDefaultVisual(ScrnInfoPtr scrp, int visual);
6445 This function sets the <structfield>defaultVisual</structfield> field of the
6446 <structname>ScrnInfoRec</structname>. It would normally be called fairly
6447 early from the <function>ChipPreInit()</function> function.
6451 It requires that the <structfield>depth</structfield> and
6452 <structfield>display</structfield> fields of the <structname>ScrnInfoRec</structname>
6453 be initialised prior to calling it.
6457 The parameters passed are:
6461 <term><parameter>visual</parameter></term>
6463 driver's preferred default visual if no other is given.
6464 If <constant>-1</constant>, use the overall server default.
6465 </para></listitem></varlistentry>
6471 It uses the command line, config file, and default values in the
6472 correct order of precedence to determine the default visual value.
6473 It is up to the driver to check the result to see that it supports
6474 it. If not the <function>ChipPreInit()</function> function should
6475 return <constant>FALSE</constant>.
6479 On success, this function prints a message showing the default visual
6480 selected, and returns <constant>TRUE</constant>.
6484 On failure it prints an error message and returns <constant>FALSE</constant>.
6487 </blockquote></para></blockquote>
6491 Bool xf86SetGamma(ScrnInfoPtr scrp, Gamma gamma);
6494 This function sets the <structfield>gamma</structfield> field of the
6495 <structname>ScrnInfoRec</structname>. It would normally be called fairly
6496 early from the <function>ChipPreInit()</function> function in cases
6497 where the driver supports gamma correction.
6501 It requires that the <structfield>monitor</structfield> field of the
6502 <structname>ScrnInfoRec</structname> be initialised prior to calling it.
6506 The parameters passed are:
6510 <term><parameter>gamma</parameter></term>
6512 driver's preferred default gamma if no other is given.
6513 If zero (<code>< 0.01</code>), use the overall server
6515 </para></listitem></varlistentry>
6521 It uses the command line, config file, and default values in the
6522 correct order of precedence to determine the gamma value. It is
6523 up to the driver to check the results to see that it supports
6524 them. If not the <function>ChipPreInit()</function> function should
6525 return <constant>FALSE</constant>.
6529 On success, this function prints a message showing the gamma
6530 value selected, and returns <constant>TRUE</constant>.
6534 On failure it prints an error message and returns <constant>FALSE</constant>.
6537 </blockquote></para></blockquote>
6542 void xf86SetDpi(ScrnInfoPtr pScrn, int x, int y);
6545 This function sets the <structfield>xDpi</structfield> and <structfield>yDpi</structfield>
6546 fields of the <structname>ScrnInfoRec</structname>. The driver can specify
6547 preferred defaults by setting <parameter>x</parameter> and <parameter>y</parameter>
6548 to non-zero values. The <option>-dpi</option> command line option
6549 overrides all other settings. Otherwise, if the
6550 <emphasis>DisplaySize</emphasis> entry is present in the screen's &k.monitor;
6551 config file section, it is used together with the virtual size to
6552 calculate the dpi values. This function should be called after
6553 all the mode resolution has been done.
6556 </blockquote></para></blockquote>
6560 void xf86SetBlackWhitePixels(ScrnInfoPtr pScrn);
6563 This functions sets the <structfield>blackPixel</structfield> and
6564 <structfield>whitePixel</structfield> fields of the <structname>ScrnInfoRec</structname>
6565 according to whether or not the <option>-flipPixels</option> command
6566 line options is present.
6569 </blockquote></para></blockquote>
6573 const char *xf86GetVisualName(int visual);
6576 Returns a printable string with the visual name matching the
6577 numerical visual class provided. If the value is outside the
6578 range of valid visual classes, <constant>NULL</constant> is returned.
6581 </blockquote></para></blockquote>
6586 <title>Primary Mode functions</title>
6589 The primary mode helper functions are those which would normally be
6590 used by a driver, unless it has unusual requirements which cannot
6591 be catered for the by the helpers.
6596 int xf86ValidateModes(ScrnInfoPtr scrp, DisplayModePtr availModes,
6597 char **modeNames, ClockRangePtr clockRanges,
6598 int *linePitches, int minPitch, int maxPitch,
6599 int pitchInc, int minHeight, int maxHeight,
6600 int virtualX, int virtualY,
6601 unsigned long apertureSize,
6602 LookupModeFlags strategy);
6605 This function basically selects the set of modes to use based on
6606 those available and the various constraints. It also sets some
6607 other related parameters. It is normally called near the end of
6608 the <function>ChipPreInit()</function> function.
6612 The parameters passed to the function are:
6616 <term><parameter>availModes</parameter></term>
6618 List of modes available for the monitor.
6619 </para></listitem></varlistentry>
6622 <term><parameter>modeNames</parameter></term>
6624 List of mode names that the screen is requesting.
6625 </para></listitem></varlistentry>
6628 <term><parameter>clockRanges</parameter></term>
6630 A list of clock ranges allowed by the driver. Each
6631 range includes whether interlaced or multiscan modes
6632 are supported for that range. See below for more on
6633 <parameter>clockRanges</parameter>.
6634 </para></listitem></varlistentry>
6637 <term><parameter>linePitches</parameter></term>
6639 List of line pitches supported by the driver.
6640 This is optional and should be <constant>NULL</constant> when
6642 </para></listitem></varlistentry>
6645 <term><parameter>minPitch</parameter></term>
6647 Minimum line pitch supported by the driver. This must
6648 be supplied when <parameter>linePitches</parameter> is
6649 <constant>NULL</constant>, and is ignored otherwise.
6650 </para></listitem></varlistentry>
6653 <term><parameter>maxPitch</parameter></term>
6655 Maximum line pitch supported by the driver. This is
6656 required when <parameter>minPitch</parameter> is required.
6657 </para></listitem></varlistentry>
6660 <term><parameter>pitchInc</parameter></term>
6662 Granularity of horizontal pitch values as supported by
6663 the chipset. This is expressed in bits. This must be
6665 </para></listitem></varlistentry>
6668 <term><parameter>minHeight</parameter></term>
6670 minimum virtual height allowed. If zero, no limit is
6672 </para></listitem></varlistentry>
6675 <term><parameter>maxHeight</parameter></term>
6677 maximum virtual height allowed. If zero, no limit is
6679 </para></listitem></varlistentry>
6682 <term><parameter>virtualX</parameter></term>
6684 If greater than zero, this is the virtual width value
6685 that will be used. Otherwise, the virtual width is
6686 chosen to be the smallest that can accommodate the modes
6688 </para></listitem></varlistentry>
6691 <term><parameter>virtualY</parameter></term>
6693 If greater than zero, this is the virtual height value
6694 that will be used. Otherwise, the virtual height is
6695 chosen to be the smallest that can accommodate the modes
6697 </para></listitem></varlistentry>
6700 <term><parameter>apertureSize</parameter></term>
6702 The size (in bytes) of the aperture used to access video
6704 </para></listitem></varlistentry>
6707 <term><parameter>strategy</parameter></term>
6709 The strategy to use when choosing from multiple modes
6710 with the same name. The options are:
6714 <term><constant>LOOKUP_DEFAULT</constant></term>
6716 </para></listitem></varlistentry>
6718 <term><constant>LOOKUP_BEST_REFRESH</constant></term>
6719 <listitem><para>mode with best refresh rate
6720 </para></listitem></varlistentry>
6722 <term><constant>LOOKUP_CLOSEST_CLOCK</constant></term>
6723 <listitem><para>mode with closest matching clock
6724 </para></listitem></varlistentry>
6726 <term><constant>LOOKUP_LIST_ORDER</constant></term>
6727 <listitem><para>first usable mode in list
6728 </para></listitem></varlistentry>
6731 The following options can also be combined (OR'ed) with
6736 <term><constant>LOOKUP_CLKDIV2</constant></term>
6737 <listitem><para>Allow halved clocks
6738 </para></listitem></varlistentry>
6740 <term><constant>LOOKUP_OPTIONAL_TOLERANCES</constant></term>
6742 Allow missing horizontal sync and/or vertical refresh
6743 ranges in the xorg.conf Monitor section
6744 </para></listitem></varlistentry>
6747 <constant>LOOKUP_OPTIONAL_TOLERANCES</constant> should only be
6748 specified when the driver can ensure all modes it generates
6749 can sync on, or at least not damage, the monitor or digital
6750 flat panel. Horizontal sync and/or vertical refresh ranges
6751 specified by the user will still be honoured (and acted upon).
6753 </para></listitem></varlistentry>
6758 This function requires that the following fields of the
6759 <structname>ScrnInfoRec</structname> are initialised prior to calling it:
6763 <term><structfield>clock[]</structfield></term>
6765 List of discrete clocks (when non-programmable)
6766 </para></listitem></varlistentry>
6768 <term><structfield>numClocks</structfield></term>
6770 Number of discrete clocks (when non-programmable)
6771 </para></listitem></varlistentry>
6773 <term><structfield>progClock</structfield></term>
6775 Whether the clock is programmable or not
6776 </para></listitem></varlistentry>
6778 <term><structfield>monitor</structfield></term>
6780 Pointer to the applicable xorg.conf monitor section
6781 </para></listitem></varlistentry>
6783 <term><structfield>fdFormat</structfield></term>
6785 Format of the screen buffer
6786 </para></listitem></varlistentry>
6788 <term><structfield>videoRam</structfield></term>
6790 total video memory size (in bytes)
6791 </para></listitem></varlistentry>
6793 <term><structfield>maxHValue</structfield></term>
6795 Maximum horizontal timing value allowed
6796 </para></listitem></varlistentry>
6798 <term><structfield>maxVValue</structfield></term>
6800 Maximum vertical timing value allowed
6801 </para></listitem></varlistentry>
6803 <term><structfield>xInc</structfield></term>
6805 Horizontal timing increment in pixels (defaults to 8)
6806 </para></listitem></varlistentry>
6811 This function fills in the following <structname>ScrnInfoRec</structname>
6816 <term><structfield>modePool</structfield></term>
6818 A subset of the modes available to the monitor which
6819 are compatible with the driver.
6820 </para></listitem></varlistentry>
6823 <term><structfield>modes</structfield></term>
6825 One mode entry for each of the requested modes, with
6826 the status field of each filled in to indicate if
6827 the mode has been accepted or not. This list of
6828 modes is a circular list.
6829 </para></listitem></varlistentry>
6832 <term><structfield>virtualX</structfield></term>
6834 The resulting virtual width.
6835 </para></listitem></varlistentry>
6838 <term><structfield>virtualY</structfield></term>
6840 The resulting virtual height.
6841 </para></listitem></varlistentry>
6844 <term><structfield>displayWidth</structfield></term>
6846 The resulting line pitch.
6847 </para></listitem></varlistentry>
6850 <term><structfield>virtualFrom</structfield></term>
6852 Where the virtual size was determined from.
6853 </para></listitem></varlistentry>
6859 The first stage of this function checks that the
6860 <parameter>virtualX</parameter> and <parameter>virtualY</parameter> values
6861 supplied (if greater than zero) are consistent with the line pitch
6862 and <parameter>maxHeight</parameter> limitations. If not, an error
6863 message is printed, and the return value is <constant>-1</constant>.
6867 The second stage sets up the mode pool, eliminating immediately
6868 any modes that exceed the driver's line pitch limits, and also
6869 the virtual width and height limits (if greater than zero). For
6870 each mode removed an informational message is printed at verbosity
6871 level <constant>2</constant>. If the mode pool ends up being empty,
6872 a warning message is printed, and the return value is
6873 <constant>0</constant>.
6877 The final stage is to lookup each mode name, and fill in the remaining
6878 parameters. If an error condition is encountered, a message is
6879 printed, and the return value is <constant>-1</constant>. Otherwise,
6880 the return value is the number of valid modes found
6881 (<constant>0</constant> if none are found).
6885 Even if the supplied mode names include duplicates, no two names will
6886 ever match the same mode. Furthermore, if the supplied mode names do not
6887 yield a valid mode (including the case where no names are passed at all),
6888 the function will continue looking through the mode pool until it finds
6889 a mode that survives all checks, or until the mode pool is exhausted.
6893 A message is only printed by this function when a fundamental
6894 problem is found. It is intended that this function may be called
6895 more than once if there is more than one set of constraints that
6896 the driver can work within.
6900 If this function returns <constant>-1</constant>, the
6901 <function>ChipPreInit()</function> function should return
6902 <constant>FALSE</constant>.
6906 <parameter>clockRanges</parameter> is a linked list of clock ranges
6907 allowed by the driver. If a mode doesn't fit in any of the defined
6908 <parameter>clockRanges</parameter>, it is rejected. The first
6909 <literal remap="tt">clockRange</literal> that matches all requirements is used.
6910 This structure needs to be initialized to NULL when allocated.
6914 <parameter>clockRanges</parameter> contains the following fields:
6918 <term><structfield>minClock</structfield></term>
6919 <term><structfield>maxClock</structfield></term>
6921 The lower and upper mode clock bounds for which the rest
6922 of the <structname>clockRange</structname> parameters apply.
6923 Since these are the mode clocks, they are not scaled
6924 with the <structfield>ClockMulFactor</structfield> and
6925 <structfield>ClockDivFactor</structfield>. It is up to the driver
6926 to adjust these values if they depend on the clock
6928 </para></listitem></varlistentry>
6931 <term><structfield>clockIndex</structfield></term>
6933 (not used yet) <constant>-1</constant> for programmable clocks
6934 </para></listitem></varlistentry>
6937 <term><structfield>interlaceAllowed</structfield></term>
6939 <constant>TRUE</constant> if interlacing is allowed for this
6941 </para></listitem></varlistentry>
6944 <term><structfield>doubleScanAllowed</structfield></term>
6946 <constant>TRUE</constant> if doublescan or multiscan is allowed
6948 </para></listitem></varlistentry>
6951 <term><structfield>ClockMulFactor</structfield></term>
6952 <term><structfield>ClockDivFactor</structfield></term>
6954 Scaling factors that are applied to the mode clocks ONLY
6955 before selecting a clock index (when there is no
6956 programmable clock) or a <structfield>SynthClock</structfield>
6957 value. This is useful for drivers that support pixel
6958 multiplexing or that need to scale the clocks because
6959 of hardware restrictions (like sending 24bpp data to an
6960 8 bit RAMDAC using a tripled clock).
6964 Note that these parameters describe what must be done
6965 to the mode clock to achieve the data transport clock
6966 between graphics controller and RAMDAC. For example
6967 for <literal remap="tt">2:1</literal> pixel multiplexing, two pixels
6968 are sent to the RAMDAC on each clock. This allows the
6969 RAMDAC clock to be half of the actual pixel clock.
6970 Hence, <code>ClockMulFactor=1</code> and
6971 <code>ClockDivFactor=2</code>. This means that the
6972 clock used for clock selection (ie, determining the
6973 correct clock index from the list of discrete clocks)
6974 or for the <structfield>SynthClock</structfield> field in case of
6975 a programmable clock is: (<code>mode->Clock *
6976 ClockMulFactor) / ClockDivFactor</code>.
6977 </para></listitem></varlistentry>
6980 <term><structfield>PrivFlags</structfield></term>
6982 This field is copied into the
6983 <literal remap="tt">mode->PrivFlags</literal> field when this
6984 <literal remap="tt">clockRange</literal> is selected by
6985 <function>xf86ValidateModes()</function>. It allows the
6986 driver to find out what clock range was selected, so it
6987 knows it needs to set up pixel multiplexing or any other
6988 range-dependent feature. This field is purely
6989 driver-defined: it may contain flag bits, an index or
6990 anything else (as long as it is an <literal remap="tt">INT</literal>).
6991 </para></listitem></varlistentry>
6996 Note that the <structfield>mode->SynthClock</structfield> field is always
6997 filled in by <function>xf86ValidateModes()</function>: it will contain
6998 the <quote>data transport clock</quote>, which is the clock that will have
6999 to be programmed in the chip when it has a programmable clock, or
7000 the clock that will be picked from the clocks list when it is not
7001 a programmable one. Thus:
7004 mode->SynthClock = (mode->Clock * ClockMulFactor) / ClockDivFactor
7008 </blockquote></para></blockquote>
7012 void xf86PruneDriverModes(ScrnInfoPtr scrp);
7015 This function deletes modes in the modes field of the
7016 <structname>ScrnInfoRec</structname> that have been marked as invalid.
7017 This is normally run after having run
7018 <function>xf86ValidateModes()</function> for the last time. For each
7019 mode that is deleted, a warning message is printed out indicating
7020 the reason for it being deleted.
7023 </blockquote></para></blockquote>
7027 void xf86SetCrtcForModes(ScrnInfoPtr scrp, int adjustFlags);
7030 This function fills in the <structname>Crtc*</structname> fields for all
7031 the modes in the <structfield>modes</structfield> field of the
7032 <structname>ScrnInfoRec</structname>. The <parameter>adjustFlags</parameter>
7033 parameter determines how the vertical CRTC values are scaled for
7034 interlaced modes. They are halved if it is
7035 <constant>INTERLACE_HALVE_V</constant>. The vertical CRTC values are
7036 doubled for doublescan modes, and are further multiplied by the
7037 <literal remap="tt">VScan</literal> value.
7041 This function is normally called after calling
7042 <function>xf86PruneDriverModes()</function>.
7045 </blockquote></para></blockquote>
7049 void xf86PrintModes(ScrnInfoPtr scrp);
7052 This function prints out the virtual size setting, and the line
7053 pitch being used. It also prints out two lines for each mode being
7054 used. The first line includes the mode's pixel clock, horizontal sync
7055 rate, refresh rate, and whether it is interlaced, doublescanned and/or
7056 multi-scanned. The second line is the mode's Modeline.
7060 This function is normally called after calling
7061 <function>xf86SetCrtcForModes()</function>.
7064 </blockquote></para></blockquote>
7069 <title>Secondary Mode functions</title>
7072 The secondary mode helper functions are functions which are normally
7073 used by the primary mode helper functions, and which are not normally
7074 called directly by a driver. If a driver has unusual requirements
7075 and needs to do its own mode validation, it might be able to make
7076 use of some of these secondary mode helper functions.
7081 int xf86GetNearestClock(ScrnInfoPtr scrp, int freq, Bool allowDiv2,
7085 This function returns the index of the closest clock to the
7086 frequency <parameter>freq</parameter> given (in kHz). It assumes that
7087 the number of clocks is greater than zero. It requires that the
7088 <structfield>numClocks</structfield> and <structfield>clock</structfield> fields of the
7089 <structname>ScrnInfoRec</structname> are initialised. The
7090 <structfield>allowDiv2</structfield> field determines if the clocks can be
7091 halved. The <parameter>*divider</parameter> return value indicates
7092 whether clock division is used when determining the clock returned.
7096 This function is only for non-programmable clocks.
7099 </blockquote></para></blockquote>
7103 const char *xf86ModeStatusToString(ModeStatus status);
7106 This function converts the <parameter>status</parameter> value to a
7107 descriptive printable string.
7110 </blockquote></para></blockquote>
7114 ModeStatus xf86LookupMode(ScrnInfoPtr scrp, DisplayModePtr modep,
7115 ClockRangePtr clockRanges, LookupModeFlags strategy);
7118 This function takes a pointer to a mode with the name filled in,
7119 and looks for a mode in the <structfield>modePool</structfield> list which
7120 matches. The parameters of the matching mode are filled in to
7121 <parameter>*modep</parameter>. The <parameter>clockRanges</parameter> and
7122 <parameter>strategy</parameter> parameters are as for the
7123 <function>xf86ValidateModes()</function> function above.
7127 This function requires the <structfield>modePool</structfield>,
7128 <structfield>clock[]</structfield>, <structfield>numClocks</structfield> and
7129 <structfield>progClock</structfield> fields of the <structname>ScrnInfoRec</structname>
7130 to be initialised before being called.
7134 The return value is <constant>MODE_OK</constant> if a mode was found.
7135 Otherwise it indicates why a matching mode could not be found.
7138 </blockquote></para></blockquote>
7142 ModeStatus xf86InitialCheckModeForDriver(ScrnInfoPtr scrp,
7143 DisplayModePtr mode, ClockRangePtr clockRanges,
7144 LookupModeFlags strategy, int maxPitch,
7145 int virtualX, int virtualY);
7148 This function checks the passed mode against some basic driver
7149 constraints. Apart from the ones passed explicitly, the
7150 <structfield>maxHValue</structfield> and <structfield>maxVValue</structfield> fields of
7151 the <structname>ScrnInfoRec</structname> are also used. If the
7152 <structfield>ValidMode</structfield> field of the <structname>ScrnInfoRec</structname>
7153 is set, that function is also called to check the mode. Next, the
7154 mode is checked against the monitor's constraints.
7158 If the mode is consistent with all constraints, the return value
7159 is <constant>MODE_OK</constant>. Otherwise the return value indicates
7160 which constraint wasn't met.
7163 </blockquote></para></blockquote>
7167 void xf86DeleteMode(DisplayModePtr *modeList, DisplayModePtr mode);
7170 This function deletes the <parameter>mode</parameter> given from the
7171 <parameter>modeList</parameter>. It never prints any messages, so it is
7172 up to the caller to print a message if required.
7175 </blockquote></para></blockquote>
7179 <title>Functions for handling strings and tokens</title>
7182 Tables associating strings and numerical tokens combined with the
7183 following functions provide a compact way of handling strings from
7184 the config file, and for converting tokens into printable strings.
7185 The table data structure is:
7191 } SymTabRec, *SymTabPtr;
7196 A table is an initialised array of <structname>SymTabRec</structname>. The
7197 tokens must be non-negative integers. Multiple names may be mapped
7198 to a single token. The table is terminated with an element with a
7199 <structfield>token</structfield> value of <constant>-1</constant> and
7200 <constant>NULL</constant> for the <structfield>name</structfield>.
7205 const char *xf86TokenToString(SymTabPtr table, int token);
7208 This function returns the first string in <parameter>table</parameter>
7209 that matches <parameter>token</parameter>. If no match is found,
7210 <constant>NULL</constant> is returned (NOTE, older versions of this
7211 function would return the string "unknown" when no match is found).
7214 </blockquote></para></blockquote>
7218 int xf86StringToToken(SymTabPtr table, const char *string);
7221 This function returns the first token in <parameter>table</parameter>
7222 that matches <parameter>string</parameter>. The
7223 <function>xf86NameCmp()</function> function is used to determine the
7224 match. If no match is found, <constant>-1</constant> is returned.
7227 </blockquote></para></blockquote>
7232 <title>Functions for finding which config file entries to use</title>
7235 These functions can be used to select the appropriate config file
7236 entries that match the detected hardware. They are described above
7237 in the <link linkend="probe">Probe</link> and
7238 <link linkend="avail">Available Functions</link> sections.
7244 <title>Probing discrete clocks on old hardware</title>
7247 The <function>xf86GetClocks()</function> function may be used to assist
7248 in finding the discrete pixel clock values on older hardware.
7253 void xf86GetClocks(ScrnInfoPtr pScrn, int num,
7254 Bool (*ClockFunc)(ScrnInfoPtr, int),
7255 void (*ProtectRegs)(ScrnInfoPtr, Bool),
7256 void (*BlankScreen)(ScrnInfoPtr, Bool),
7257 int vertsyncreg, int maskval, int knownclkindex,
7261 This function uses a comparative sampling method to measure the
7262 discrete pixel clock values. The number of discrete clocks to
7263 measure is given by <parameter>num</parameter>. <parameter>clockFunc</parameter>
7264 is a function that selects the <parameter>n</parameter>'th clock. It
7265 should also save or restore any state affected by programming the
7266 clocks when the index passed is <constant>CLK_REG_SAVE</constant> or
7267 <constant>CLK_REG_RESTORE</constant>. <parameter>ProtectRegs</parameter> is
7268 a function that does whatever is required to protect the hardware
7269 state while selecting a new clock. <parameter>BlankScreen</parameter>
7270 is a function that blanks the screen. <parameter>vertsyncreg</parameter>
7271 and <parameter>maskval</parameter> are the register and bitmask to
7272 check for the presence of vertical sync pulses.
7273 <parameter>knownclkindex</parameter> and <parameter>knownclkvalue</parameter>
7274 are the index and value of a known clock. These are the known
7275 references on which the comparative measurements are based. The
7276 number of clocks probed is set in <structfield>pScrn->numClocks</structfield>,
7277 and the probed clocks are set in the <structfield>pScrn->clock[]</structfield>
7278 array. All of the clock values are in units of kHz.
7281 </blockquote></para></blockquote>
7285 void xf86ShowClocks(ScrnInfoPtr scrp, MessageType from);
7288 Print out the pixel clocks <parameter>scrp->clock[]</parameter>.
7289 <parameter>from</parameter> indicates whether the clocks were probed
7290 or from the config file.
7293 </blockquote></para></blockquote>
7297 <title>Other helper functions</title>
7301 Bool xf86IsUnblank(int mode);
7304 Returns <constant>TRUE</constant> when the screen saver mode specified
7305 by <parameter>mode</parameter> requires the screen be unblanked,
7306 and <constant>FALSE</constant> otherwise. The screen saver modes that
7307 require blanking are <constant>SCREEN_SAVER_ON</constant> and
7308 <constant>SCREEN_SAVER_CYCLE</constant>, and the screen saver modes that
7309 require unblanking are <constant>SCREEN_SAVER_OFF</constant> and
7310 <constant>SCREEN_SAVER_FORCER</constant>. Drivers may call this helper
7311 from their <function>SaveScreen()</function> function to interpret the
7315 </blockquote></para></blockquote>
7320 <title>The vgahw module</title>
7323 The vgahw modules provides an interface for saving, restoring and
7324 programming the standard VGA registers, and for handling VGA colourmaps.
7328 <title>Data Structures</title>
7331 The public data structures used by the vgahw module are
7332 <structname>vgaRegRec</structname> and <structname>vgaHWRec</structname>. They are
7333 defined in <filename>vgaHW.h.</filename>
7339 <title>General vgahw Functions</title>
7343 Bool vgaHWGetHWRec(ScrnInfoPtr pScrn);
7346 This function allocates a <structname>vgaHWRec</structname> structure, and
7347 hooks it into the <structname>ScrnInfoRec</structname>'s
7348 <structfield>privates</structfield>. Like all information hooked into the
7349 <structfield>privates</structfield>, it is persistent, and only needs to be
7350 allocated once per screen. This function should normally be called
7351 from the driver's <function>ChipPreInit()</function> function. The
7352 <structname>vgaHWRec</structname> is zero-allocated, and the following
7353 fields are explicitly initialised:
7357 <term><structfield>ModeReg.DAC[]</structfield></term>
7358 <listitem><para>initialised with a default colourmap
7359 </para></listitem></varlistentry>
7361 <term><structfield>ModeReg.Attribute[0x11]</structfield></term>
7362 <listitem><para>initialised with the default overscan index
7363 </para></listitem></varlistentry>
7365 <term><structfield>ShowOverscan</structfield></term>
7366 <listitem><para>initialised according to the "ShowOverscan" option
7367 </para></listitem></varlistentry>
7369 <term><structfield>paletteEnabled</structfield></term>
7370 <listitem><para>initialised to FALSE
7371 </para></listitem></varlistentry>
7373 <term><structfield>cmapSaved</structfield></term>
7374 <listitem><para>initialised to FALSE
7375 </para></listitem></varlistentry>
7377 <term><structfield>pScrn</structfield></term>
7378 <listitem><para>initialised to pScrn
7379 </para></listitem></varlistentry>
7384 In addition to the above, <function>vgaHWSetStdFuncs()</function> is
7385 called to initialise the register access function fields with the
7386 standard VGA set of functions.
7390 Once allocated, a pointer to the <structname>vgaHWRec</structname> can be
7391 obtained from the <literal remap="tt">ScrnInfoPtr</literal> with the
7392 <literal remap="tt">VGAHWPTR(pScrn)</literal> macro.
7395 </blockquote></para></blockquote>
7399 void vgaHWFreeHWRec(ScrnInfoPtr pScrn);
7402 This function frees a <structname>vgaHWRec</structname> structure. It
7403 should be called from a driver's <function>ChipFreeScreen()</function>
7407 </blockquote></para></blockquote>
7411 Bool vgaHWSetRegCounts(ScrnInfoPtr pScrn, int numCRTC,
7412 int numSequencer, int numGraphics, int numAttribute);
7415 This function allows the number of CRTC, Sequencer, Graphics and
7416 Attribute registers to be changed. This makes it possible for
7417 extended registers to be saved and restored with
7418 <function>vgaHWSave()</function> and <function>vgaHWRestore()</function>.
7419 This function should be called after a <structname>vgaHWRec</structname>
7420 has been allocated with <function>vgaHWGetHWRec()</function>. The
7421 default values are defined in <filename>vgaHW.h</filename> as follows:
7424 #define VGA_NUM_CRTC 25
7425 #define VGA_NUM_SEQ 5
7426 #define VGA_NUM_GFX 9
7427 #define VGA_NUM_ATTR 21
7431 </blockquote></para></blockquote>
7435 Bool vgaHWCopyReg(vgaRegPtr dst, vgaRegPtr src);
7438 This function copies the contents of the VGA saved registers in
7439 <parameter>src</parameter> to <parameter>dst</parameter>. Note that it isn't
7440 possible to simply do this with <function>memcpy()</function> (or
7441 similar). This function returns <constant>TRUE</constant> unless there
7442 is a problem allocating space for the <structfield>CRTC</structfield> and
7443 related fields in <parameter>dst</parameter>.
7446 </blockquote></para></blockquote>
7450 void vgaHWSetStdFuncs(vgaHWPtr hwp);
7453 This function initialises the register access function fields of
7454 <parameter>hwp</parameter> with the standard VGA set of functions. This
7455 is called by <function>vgaHWGetHWRec()</function>, so there is usually
7456 no need to call this explicitly. The register access functions
7457 are described below. If the registers are shadowed in some other
7458 port I/O space (for example a PCI I/O region), these functions
7459 can be used to access the shadowed registers if
7460 <structfield>hwp->PIOOffset</structfield> is initialised with
7461 <literal remap="tt">offset</literal>, calculated in such a way that when the
7462 standard VGA I/O port value is added to it the correct offset into
7463 the PIO area results. This value is initialised to zero in
7464 <function>vgaHWGetHWRec()</function>. (Note: the PIOOffset functionality
7465 is present in XFree86 4.1.0 and later.)
7468 </blockquote></para></blockquote>
7472 void vgaHWSetMmioFuncs(vgaHWPtr hwp, CARD8 *base, int offset);
7475 This function initialised the register access function fields of
7476 hwp with a generic MMIO set of functions.
7477 <structfield>hwp->MMIOBase</structfield> is initialised with
7478 <parameter>base</parameter>, which must be the virtual address that the
7479 start of MMIO area is mapped to. <structfield>hwp->MMIOOffset</structfield>
7480 is initialised with <parameter>offset</parameter>, which must be calculated
7481 in such a way that when the standard VGA I/O port value is added
7482 to it the correct offset into the MMIO area results. That means
7483 that these functions are only suitable when the VGA I/O ports are
7484 made available in a direct mapping to the MMIO space. If that is
7485 not the case, the driver will need to provide its own register
7486 access functions. The register access functions are described
7490 </blockquote></para></blockquote>
7494 Bool vgaHWMapMem(ScrnInfoPtr pScrn);
7497 This function maps the VGA memory window. It requires that the
7498 <structname>vgaHWRec</structname> be allocated. If a driver requires
7499 non-default <structfield>MapPhys</structfield> or <structfield>MapSize</structfield>
7500 settings (the physical location and size of the VGA memory window)
7501 then those fields of the <structname>vgaHWRec</structname> must be initialised
7502 before calling this function. Otherwise, this function initialiases
7503 the default values of <constant>0xA0000</constant> for
7504 <structfield>MapPhys</structfield> and <code>(64 * 1024)</code> for
7505 <structfield>MapSize</structfield>. This function must be called before
7506 attempting to save or restore the VGA state. If the driver doesn't
7507 call it explicitly, the <function>vgaHWSave()</function> and
7508 <function>vgaHWRestore()</function> functions may call it if they need
7509 to access the VGA memory (in which case they will also call
7510 <function>vgaHWUnmapMem()</function> to unmap the VGA memory before
7514 </blockquote></para></blockquote>
7518 void vgaHWUnmapMem(ScrnInfoPtr pScrn);
7521 This function unmaps the VGA memory window. It must only be called
7522 after the memory has been mapped. The <structfield>Base</structfield> field
7523 of the <structname>vgaHWRec</structname> field is set to <constant>NULL</constant>
7524 to indicate that the memory is no longer mapped.
7527 </blockquote></para></blockquote>
7531 void vgaHWGetIOBase(vgaHWPtr hwp);
7534 This function initialises the <structfield>IOBase</structfield> field of the
7535 <structname>vgaHWRec</structname>. This function must be called before
7536 using any other functions that access the video hardware.
7540 A macro <function>VGAHW_GET_IOBASE()</function> is also available in
7541 <filename>vgaHW.h</filename> that returns the I/O base, and this may
7542 be used when the vgahw module is not loaded (for example, in the
7543 <function>ChipProbe()</function> function).
7546 </blockquote></para></blockquote>
7550 void vgaHWUnlock(vgaHWPtr hwp);
7553 This function unlocks the VGA <literal remap="tt">CRTC[0-7]</literal> registers,
7554 and must be called before attempting to write to those registers.
7557 </blockquote></para></blockquote>
7561 void vgaHWLock(vgaHWPtr hwp);
7564 This function locks the VGA <literal remap="tt">CRTC[0-7]</literal> registers.
7567 </blockquote></para></blockquote>
7571 void vgaHWEnable(vgaHWPtr hwp);
7574 This function enables the VGA subsystem. (Note, this function is
7575 present in XFree86 4.1.0 and later.).
7578 </blockquote></para></blockquote>
7582 void vgaHWDisable(vgaHWPtr hwp);
7585 This function disables the VGA subsystem. (Note, this function is
7586 present in XFree86 4.1.0 and later.).
7589 </blockquote></para></blockquote>
7593 void vgaHWSave(ScrnInfoPtr pScrn, vgaRegPtr save, int flags);
7596 This function saves the VGA state. The state is written to the
7597 <structname>vgaRegRec</structname> pointed to by <parameter>save</parameter>.
7598 <parameter>flags</parameter> is set to one or more of the following flags
7603 <term><constant>VGA_SR_MODE</constant></term>
7604 <listitem><para>the mode setting registers are saved
7605 </para></listitem></varlistentry>
7607 <term><constant>VGA_SR_FONTS</constant></term>
7608 <listitem><para>the text mode font/text data is saved
7609 </para></listitem></varlistentry>
7611 <term><constant>VGA_SR_CMAP</constant></term>
7612 <listitem><para>the colourmap (LUT) is saved
7613 </para></listitem></varlistentry>
7615 <term><constant>VGA_SR_ALL</constant></term>
7616 <listitem><para>all of the above are saved
7617 </para></listitem></varlistentry>
7622 The <structname>vgaHWRec</structname> and its <structfield>IOBase</structfield> fields
7623 must be initialised before this function is called. If
7624 <constant>VGA_SR_FONTS</constant> is set in <parameter>flags</parameter>, the
7625 VGA memory window must be mapped. If it isn't then
7626 <function>vgaHWMapMem()</function> will be called to map it, and
7627 <function>vgaHWUnmapMem()</function> will be called to unmap it
7628 afterwards. <function>vgaHWSave()</function> uses the three functions
7629 below in the order <function>vgaHWSaveColormap()</function>,
7630 <function>vgaHWSaveMode()</function>, <function>vgaHWSaveFonts()</function> to
7631 carry out the different save phases. It is undecided at this
7632 stage whether they will remain part of the vgahw module's public
7636 </blockquote></para></blockquote>
7640 void vgaHWSaveMode(ScrnInfoPtr pScrn, vgaRegPtr save);
7643 This function saves the VGA mode registers. They are saved to
7644 the <structname>vgaRegRec</structname> pointed to by <parameter>save</parameter>.
7645 The registers saved are:
7657 The number of registers actually saved may be modified by a prior call
7658 to <function>vgaHWSetRegCounts()</function>.
7661 </blockquote></para></blockquote>
7665 void vgaHWSaveFonts(ScrnInfoPtr pScrn, vgaRegPtr save);
7668 This function saves the text mode font and text data held in the
7669 video memory. If called while in a graphics mode, no save is
7670 done. The VGA memory window must be mapped with
7671 <function>vgaHWMapMem()</function> before to calling this function.
7675 On some platforms, one or more of the font/text plane saves may be
7676 no-ops. This is the case when the platform's VC driver already
7680 </blockquote></para></blockquote>
7684 void vgaHWSaveColormap(ScrnInfoPtr pScrn, vgaRegPtr save);
7687 This function saves the VGA colourmap (LUT). Before saving it, it
7688 attempts to verify that the colourmap is readable. In rare cases
7689 where it isn't readable, a default colourmap is saved instead.
7692 </blockquote></para></blockquote>
7696 void vgaHWRestore(ScrnInfoPtr pScrn, vgaRegPtr restore, int flags);
7699 This function programs the VGA state. The state programmed is
7700 that contained in the <structname>vgaRegRec</structname> pointed to by
7701 <parameter>restore</parameter>. <parameter>flags</parameter> is the same
7702 as described above for the <function>vgaHWSave()</function> function.
7706 The <structname>vgaHWRec</structname> and its <structfield>IOBase</structfield> fields
7707 must be initialised before this function is called. If
7708 <constant>VGA_SR_FONTS</constant> is set in <parameter>flags</parameter>, the
7709 VGA memory window must be mapped. If it isn't then
7710 <function>vgaHWMapMem()</function> will be called to map it, and
7711 <function>vgaHWUnmapMem()</function> will be called to unmap it
7712 afterwards. <function>vgaHWRestore()</function> uses the three functions
7713 below in the order <function>vgaHWRestoreFonts()</function>,
7714 <function>vgaHWRestoreMode()</function>,
7715 <function>vgaHWRestoreColormap()</function> to carry out the different
7716 restore phases. It is undecided at this stage whether they will
7717 remain part of the vgahw module's public interface or not.
7720 </blockquote></para></blockquote>
7724 void vgaHWRestoreMode(ScrnInfoPtr pScrn, vgaRegPtr restore);
7727 This function restores the VGA mode registers. They are restored
7728 from the data in the <structname>vgaRegRec</structname> pointed to by
7729 <parameter>restore</parameter>. The registers restored are:
7741 The number of registers actually restored may be modified by a prior call
7742 to <function>vgaHWSetRegCounts()</function>.
7745 </blockquote></para></blockquote>
7749 void vgaHWRestoreFonts(ScrnInfoPtr pScrn, vgaRegPtr restore);
7752 This function restores the text mode font and text data to the
7753 video memory. The VGA memory window must be mapped with
7754 <function>vgaHWMapMem()</function> before to calling this function.
7758 On some platforms, one or more of the font/text plane restores
7759 may be no-ops. This is the case when the platform's VC driver
7760 already takes care of this.
7763 </blockquote></para></blockquote>
7767 void vgaHWRestoreColormap(ScrnInfoPtr pScrn, vgaRegPtr restore);
7770 This function restores the VGA colourmap (LUT).
7773 </blockquote></para></blockquote>
7777 void vgaHWInit(ScrnInfoPtr pScrn, DisplayModePtr mode);
7780 This function fills in the <structname>vgaHWRec</structname>'s
7781 <structfield>ModeReg</structfield> field with the values appropriate for
7782 programming the given video mode. It requires that the
7783 <structname>ScrnInfoRec</structname>'s <structfield>depth</structfield> field is
7784 initialised, which determines how the registers are programmed.
7787 </blockquote></para></blockquote>
7791 void vgaHWSeqReset(vgaHWPtr hwp, Bool start);
7794 Do a VGA sequencer reset. If start is <constant>TRUE</constant>, the
7795 reset is started. If start is <constant>FALSE</constant>, the reset
7799 </blockquote></para></blockquote>
7803 void vgaHWProtect(ScrnInfoPtr pScrn, Bool on);
7806 This function protects VGA registers and memory from corruption
7807 during loads. It is typically called with on set to
7808 <constant>TRUE</constant> before programming, and with on set to
7809 <constant>FALSE</constant> after programming.
7812 </blockquote></para></blockquote>
7816 Bool vgaHWSaveScreen(ScreenPtr pScreen, int mode);
7819 This function blanks and unblanks the screen. It is blanked when
7820 <parameter>mode</parameter> is <constant>SCREEN_SAVER_ON</constant> or
7821 <constant>SCREEN_SAVER_CYCLE</constant>, and unblanked when
7822 <parameter>mode</parameter> is <constant>SCREEN_SAVER_OFF</constant> or
7823 <constant>SCREEN_SAVER_FORCER</constant>.
7826 </blockquote></para></blockquote>
7830 void vgaHWBlankScreen(ScrnInfoPtr pScrn, Bool on);
7833 This function blanks and unblanks the screen. It is blanked when
7834 <parameter>on</parameter> is <constant>FALSE</constant>, and unblanked when
7835 <parameter>on</parameter> is <constant>TRUE</constant>. This function is
7836 provided for use in cases where the <structname>ScrnInfoRec</structname>
7837 can't be derived from the <structname>ScreenRec</structname> (while probing
7838 for clocks, for example).
7841 </blockquote></para></blockquote>
7846 <title>VGA Colormap Functions</title>
7849 The vgahw module uses the standard colormap support (see the
7850 <link linkend="cmap">Colormap Handling</link> section. This is initialised
7851 with the following function:
7855 Bool vgaHWHandleColormaps(ScreenPtr pScreen);
7857 </para></blockquote>
7863 <title>VGA Register Access Functions</title>
7866 The vgahw module abstracts access to the standard VGA registers by
7867 using a set of functions held in the <structname>vgaHWRec</structname>. When
7868 the <structname>vgaHWRec</structname> is created these function pointers are
7869 initialised with the set of standard VGA I/O register access functions.
7870 In addition to these, the vgahw module includes a basic set of MMIO
7871 register access functions, and the <structname>vgaHWRec</structname> function
7872 pointers can be initialised to these by calling the
7873 <function>vgaHWSetMmioFuncs()</function> function described above. Some
7874 drivers/platforms may require a different set of functions for VGA
7875 access. The access functions are described here.
7881 void writeCrtc(vgaHWPtr hwp, CARD8 index, CARD8 value);
7884 Write <parameter>value</parameter> to CRTC register <parameter>index</parameter>.
7887 </blockquote></para></blockquote>
7891 CARD8 readCrtc(vgaHWPtr hwp, CARD8 index);
7894 Return the value read from CRTC register <parameter>index</parameter>.
7897 </blockquote></para></blockquote>
7901 void writeGr(vgaHWPtr hwp, CARD8 index, CARD8 value);
7904 Write <parameter>value</parameter> to Graphics Controller register
7905 <parameter>index</parameter>.
7908 </blockquote></para></blockquote>
7912 CARD8 readGR(vgaHWPtr hwp, CARD8 index);
7915 Return the value read from Graphics Controller register
7916 <parameter>index</parameter>.
7919 </blockquote></para></blockquote>
7923 void writeSeq(vgaHWPtr hwp, CARD8 index, CARD8, value);
7926 Write <parameter>value</parameter> to Sequencer register
7927 <parameter>index</parameter>.
7930 </blockquote></para></blockquote>
7934 CARD8 readSeq(vgaHWPtr hwp, CARD8 index);
7937 Return the value read from Sequencer register <parameter>index</parameter>.
7940 </blockquote></para></blockquote>
7944 void writeAttr(vgaHWPtr hwp, CARD8 index, CARD8, value);
7947 Write <parameter>value</parameter> to Attribute Controller register
7948 <parameter>index</parameter>. When writing out the index value this
7949 function should set bit 5 (<constant>0x20</constant>) according to the
7950 setting of <structfield>hwp->paletteEnabled</structfield> in order to
7951 preserve the palette access state. It should be cleared when
7952 <structfield>hwp->paletteEnabled</structfield> is <constant>TRUE</constant>
7953 and set when it is <constant>FALSE</constant>.
7956 </blockquote></para></blockquote>
7960 CARD8 readAttr(vgaHWPtr hwp, CARD8 index);
7963 Return the value read from Attribute Controller register
7964 <parameter>index</parameter>. When writing out the index value this
7965 function should set bit 5 (<constant>0x20</constant>) according to the
7966 setting of <structfield>hwp->paletteEnabled</structfield> in order to
7967 preserve the palette access state. It should be cleared when
7968 <structfield>hwp->paletteEnabled</structfield> is <constant>TRUE</constant>
7969 and set when it is <constant>FALSE</constant>.
7972 </blockquote></para></blockquote>
7976 void writeMiscOut(vgaHWPtr hwp, CARD8 value);
7979 Write <quote><parameter>value</parameter></quote> to the Miscellaneous Output register.
7982 </blockquote></para></blockquote>
7986 CARD8 readMiscOut(vgwHWPtr hwp);
7989 Return the value read from the Miscellaneous Output register.
7992 </blockquote></para></blockquote>
7996 void enablePalette(vgaHWPtr hwp);
7999 Clear the palette address source bit in the Attribute Controller
8000 index register and set <literal remap="tt">hwp->paletteEnabled</literal> to
8001 <constant>TRUE</constant>.
8004 </blockquote></para></blockquote>
8008 void disablePalette(vgaHWPtr hwp);
8011 Set the palette address source bit in the Attribute Controller
8012 index register and set <literal remap="tt">hwp->paletteEnabled</literal> to
8013 <constant>FALSE</constant>.
8016 </blockquote></para></blockquote>
8020 void writeDacMask(vgaHWPtr hwp, CARD8 value);
8023 Write <parameter>value</parameter> to the DAC Mask register.
8026 </blockquote></para></blockquote>
8030 CARD8 readDacMask(vgaHWptr hwp);
8033 Return the value read from the DAC Mask register.
8036 </blockquote></para></blockquote>
8040 void writeDacReadAddress(vgaHWPtr hwp, CARD8 value);
8043 Write <parameter>value</parameter> to the DAC Read Address register.
8046 </blockquote></para></blockquote>
8050 void writeDacWriteAddress(vgaHWPtr hwp, CARD8 value);
8053 Write <parameter>value</parameter> to the DAC Write Address register.
8056 </blockquote></para></blockquote>
8060 void writeDacData(vgaHWPtr hwp, CARD8 value);
8063 Write <parameter>value</parameter> to the DAC Data register.
8066 </blockquote></para></blockquote>
8070 CARD8 readDacData(vgaHWptr hwp);
8073 Return the value read from the DAC Data register.
8076 </blockquote></para></blockquote>
8080 CARD8 readEnable(vgaHWptr hwp);
8083 Return the value read from the VGA Enable register. (Note: This
8084 function is present in XFree86 4.1.0 and later.)
8087 </blockquote></para></blockquote>
8091 void writeEnable(vgaHWPtr hwp, CARD8 value);
8094 Write <parameter>value</parameter> to the VGA Enable register. (Note: This
8095 function is present in XFree86 4.1.0 and later.)
8098 </blockquote></para></blockquote>
8103 <title>Some notes about writing a driver</title>
8105 <note><para>NOTE: some parts of this are not up to date</para></note>
8108 The following is an outline for writing a basic unaccelerated driver
8109 for a PCI video card with a linear mapped framebuffer, and which has a
8110 VGA core. It is includes some general information that is relevant to
8111 most drivers (even those which don't fit that basic description).
8115 The information here is based on the initial conversion of the Matrox
8116 Millennium driver to the <quote>new design</quote>. For a fleshing out and sample
8117 implementation of some of the bits outlined here, refer to that driver.
8118 Note that this is an example only. The approach used here will not be
8119 appropriate for all drivers.
8123 Each driver must reserve a unique driver name, and a string that is used
8124 to prefix all of its externally visible symbols. This is to avoid name
8125 space clashes when loading multiple drivers. The examples here are for
8126 the <quote>ZZZ</quote> driver, which uses the <quote>ZZZ</quote> or <quote>zzz</quote> prefix for its externally
8131 <title>Include files</title>
8134 All drivers normally include the following headers:
8135 <literallayout><filename>
8140 </filename></literallayout>
8141 Wherever inb/outb (and related things) are used the following should be
8143 <literallayout><filename>
8145 </filename></literallayout>
8146 Note: in drivers, this must be included after <filename>"xf86_ansic.h"</filename>.
8150 Drivers that need to access PCI vendor/device definitions need this:
8151 <literallayout><filename>
8153 </filename></literallayout>
8157 Drivers that need to access the PCI config space need this:
8158 <literallayout><filename>
8160 </filename></literallayout>
8164 Drivers using the mi banking wrapper need:
8166 <literallayout><filename>
8168 </filename></literallayout>
8172 Drivers that initialise a SW cursor need this:
8173 <literallayout><filename>
8175 </filename></literallayout>
8179 All drivers implementing backing store need this:
8180 <literallayout><filename>
8182 </filename></literallayout>
8186 All drivers using the mi colourmap code need this:
8187 <literallayout><filename>
8189 </filename></literallayout>
8193 If a driver uses the vgahw module, it needs this:
8194 <literallayout><filename>
8196 </filename></literallayout>
8200 Drivers supporting VGA or Hercules monochrome screens need:
8201 <literallayout><filename>
8203 </filename></literallayout>
8207 Drivers supporting VGA or EGC 16-colour screens need:
8208 <literallayout><filename>
8210 </filename></literallayout>
8214 Drivers using cfb need:
8223 Drivers supporting bpp 16, 24 or 32 with cfb need one or more of:
8224 <literallayout><filename>
8228 </filename></literallayout>
8232 The driver's own header file:
8233 <literallayout><filename>
8235 </filename></literallayout>
8239 Drivers must NOT include the following:
8241 <literallayout><filename>
8254 <title>Data structures and initialisation</title>
8258 <para>The following macros should be defined:
8260 #define VERSION <version-as-an-int>
8261 #define ZZZ_NAME "ZZZ" /* the name used to prefix messages */
8262 #define ZZZ_DRIVER_NAME "zzz" /* the driver name as used in config file */
8263 #define ZZZ_MAJOR_VERSION <int>
8264 #define ZZZ_MINOR_VERSION <int>
8265 #define ZZZ_PATCHLEVEL <int>
8269 NOTE: <constant>ZZZ_DRIVER_NAME</constant> should match the name of the
8270 driver module without things like the "lib" prefix, the "_drv" suffix
8271 or filename extensions.
8277 A DriverRec must be defined, which includes the functions required
8278 at the pre-probe phase. The name of this DriverRec must be an
8279 upper-case version of ZZZ_DRIVER_NAME (for the purposes of static
8287 ZZZAvailableOptions,
8296 <para>Define list of supported chips and their matching ID:
8298 static SymTabRec ZZZChipsets[] = {
8299 { PCI_CHIP_ZZZ1234, "zzz1234a" },
8300 { PCI_CHIP_ZZZ5678, "zzz5678a" },
8306 The token field may be any integer value that the driver may use to
8307 uniquely identify the supported chipsets. For drivers that support
8308 only PCI devices using the PCI device IDs might be a natural choice,
8309 but this isn't mandatory. For drivers that support both PCI and other
8310 devices (like ISA), some other ID should probably used. When other
8311 IDs are used as the tokens it is recommended that the names be
8312 defined as an <type>enum</type> type.
8318 If the driver uses the <function>xf86MatchPciInstances()</function>
8319 helper (recommended for drivers that support PCI cards) a list that
8320 maps PCI IDs to chip IDs and fixed resources must be defined:
8322 static PciChipsets ZZZPciChipsets[] = {
8323 { PCI_CHIP_ZZZ1234, PCI_CHIP_ZZZ1234, RES_SHARED_VGA },
8324 { PCI_CHIP_ZZZ5678, PCI_CHIP_ZZZ5678, RES_SHARED_VGA },
8325 { -1, -1, RES_UNDEFINED }
8333 Define the <structname>XF86ModuleVersionInfo</structname> struct for the
8334 driver. This is required for the dynamically loaded version:
8336 static XF86ModuleVersionInfo zzzVersRec =
8342 XF86_VERSION_CURRENT,
8343 ZZZ_MAJOR_VERSION, ZZZ_MINOR_VERSION, ZZZ_PATCHLEVEL,
8345 ABI_VIDEODRV_VERSION,
8355 Define a data structure to hold the driver's screen-specific data.
8356 This must be used instead of global variables. This would be defined
8357 in the <filename>"zzz.h"</filename> file, something like:
8366 CloseScreenProcPtr CloseScreen;
8367 OptionInfoPtr Options;
8376 Define the list of config file Options that the driver accepts. For
8377 consistency between drivers those in the list of <quote>standard</quote> options
8378 should be used where appropriate before inventing new options.
8388 static const OptionInfoRec ZZZOptions[] = {
8389 { OPTION_FOO_HACK, "FooHack", OPTV_INTEGER, {0}, FALSE },
8390 { OPTION_PCI_RETRY, "PciRetry", OPTV_BOOLEAN, {0}, FALSE },
8391 { OPTION_HW_CURSOR, "HWcursor", OPTV_BOOLEAN, {0}, FALSE },
8392 { OPTION_NOACCEL, "NoAccel", OPTV_BOOLEAN, {0}, FALSE },
8393 { -1, NULL, OPTV_NONE, {0}, FALSE }
8402 <title>Functions</title>
8406 <title>SetupProc</title>
8409 For dynamically loaded modules, a <varname>ModuleData</varname>
8410 variable is required. It is should be the name of the driver
8411 prepended to "ModuleData". A <function>Setup()</function> function is
8412 also required, which calls <function>xf86AddDriver()</function> to add
8413 the driver to the main list of drivers.
8417 static MODULESETUPPROTO(zzzSetup);
8419 XF86ModuleData zzzModuleData = { &zzzVersRec, zzzSetup, NULL };
8422 zzzSetup(pointer module, pointer opts, int *errmaj, int *errmin)
8424 static Bool setupDone = FALSE;
8426 /* This module should be loaded only once, but check to be sure. */
8430 * Modules that this driver always requires may be loaded
8431 * here by calling LoadSubModule().
8435 xf86AddDriver(&MGA, module, 0);
8438 * The return value must be non-NULL on success even though
8439 * there is no TearDownProc.
8443 if (errmaj) *errmaj = LDR_ONCEONLY;
8451 <title>GetRec, FreeRec</title>
8454 A function is usually required to allocate the driver's
8455 screen-specific data structure and hook it into the
8456 <structname>ScrnInfoRec</structname>'s <structfield>driverPrivate</structfield> field.
8457 The <structname>ScrnInfoRec</structname>'s <structfield>driverPrivate</structfield> is
8458 initialised to <constant>NULL</constant>, so it is easy to check if the
8459 initialisation has already been done. After allocating it, initialise
8460 the fields. By using <function>xnfcalloc()</function> to do the allocation
8461 it is zeroed, and if the allocation fails the server exits.
8466 When allocating structures from inside the driver which are defined
8467 on the common level it is important to initialize the structure to
8469 Only this guarantees that the server remains source compatible to
8470 future changes in common level structures.
8475 ZZZGetRec(ScrnInfoPtr pScrn)
8477 if (pScrn->driverPrivate != NULL)
8479 pScrn->driverPrivate = xnfcalloc(sizeof(ZZZRec), 1);
8480 /* Initialise as required */
8487 Define a macro in <filename>"zzz.h"</filename> which gets a pointer to
8488 the <structname>ZZZRec</structname> when given <parameter>pScrn</parameter>:
8491 #define ZZZPTR(p) ((ZZZPtr)((p)->driverPrivate))
8496 Define a function to free the above, setting it to <constant>NULL</constant>
8497 once it has been freed:
8501 ZZZFreeRec(ScrnInfoPtr pScrn)
8503 if (pScrn->driverPrivate == NULL)
8505 xfree(pScrn->driverPrivate);
8506 pScrn->driverPrivate = NULL;
8513 <title>Identify</title>
8516 Define the <function>Identify()</function> function. It is run before
8517 the Probe, and typically prints out an identifying message, which
8518 might include the chipsets it supports. This function is mandatory:
8522 ZZZIdentify(int flags)
8524 xf86PrintChipsets(ZZZ_NAME, "driver for ZZZ Tech chipsets",
8532 <title>Probe</title>
8535 Define the <function>Probe()</function> function. The purpose of this
8536 is to find all instances of the hardware that the driver supports,
8537 and for the ones not already claimed by another driver, claim the
8538 slot, and allocate a <structname>ScrnInfoRec</structname>. This should be
8539 a minimal probe, and it should under no circumstances leave the
8540 state of the hardware changed. Because a device is found, don't
8541 assume that it will be used. Don't do any initialisations other
8542 than the required <structname>ScrnInfoRec</structname> initialisations.
8543 Don't allocate any new data structures.
8547 This function is mandatory.
8551 NOTE: The <function>xf86DrvMsg()</function> functions cannot be used from
8557 ZZZProbe(DriverPtr drv, int flags)
8559 Bool foundScreen = FALSE;
8560 int numDevSections, numUsed;
8561 GDevPtr *devSections;
8566 * Find the config file Device sections that match this
8567 * driver, and return if there are none.
8569 if ((numDevSections = xf86MatchDevice(ZZZ_DRIVER_NAME,
8570 &devSections)) <= 0) {
8575 * Since this is a PCI card, "probing" just amounts to checking
8576 * the PCI data that the server has already collected. If there
8579 * Although the config file is allowed to override things, it
8580 * is reasonable to not allow it to override the detection
8581 * of no PCI video cards.
8583 * The provided xf86MatchPciInstances() helper takes care of
8586 /* test if PCI bus present */
8587 if (xf86GetPciVideoInfo()) {
8589 numUsed = xf86MatchPciInstances(ZZZ_NAME, PCI_VENDOR_ZZZ,
8590 ZZZChipsets, ZZZPciChipsets, devSections,
8591 numDevSections, drv, &usedChips);
8593 for (i = 0; i < numUsed; i++) {
8594 ScrnInfoPtr pScrn = NULL;
8595 if ((pScrn = xf86ConfigPciEntity(pScrn, flags, usedChips[i],
8596 ZZZPciChipsets, NULL, NULL,
8597 NULL, NULL, NULL))) {
8598 /* Allocate a ScrnInfoRec */
8599 pScrn->driverVersion = VERSION;
8600 pScrn->driverName = ZZZ_DRIVER_NAME;
8601 pScrn->name = ZZZ_NAME;
8602 pScrn->Probe = ZZZProbe;
8603 pScrn->PreInit = ZZZPreInit;
8604 pScrn->ScreenInit = ZZZScreenInit;
8605 pScrn->SwitchMode = ZZZSwitchMode;
8606 pScrn->AdjustFrame = ZZZAdjustFrame;
8607 pScrn->EnterVT = ZZZEnterVT;
8608 pScrn->LeaveVT = ZZZLeaveVT;
8609 pScrn->FreeScreen = ZZZFreeScreen;
8610 pScrn->ValidMode = ZZZValidMode;
8612 /* add screen to entity */
8620 * If the driver supports ISA hardware, the following block
8621 * can be included too.
8623 numUsed = xf86MatchIsaInstances(ZZZ_NAME, ZZZChipsets,
8624 ZZZIsaChipsets, drv, ZZZFindIsaDevice,
8625 devSections, numDevSections, &usedChips);
8626 for (i = 0; i < numUsed; i++) {
8627 ScrnInfoPtr pScrn = NULL;
8628 if ((pScrn = xf86ConfigIsaEntity(pScrn, flags, usedChips[i],
8629 ZZZIsaChipsets, NULL, NULL, NULL,
8631 pScrn->driverVersion = VERSION;
8632 pScrn->driverName = ZZZ_DRIVER_NAME;
8633 pScrn->name = ZZZ_NAME;
8634 pScrn->Probe = ZZZProbe;
8635 pScrn->PreInit = ZZZPreInit;
8636 pScrn->ScreenInit = ZZZScreenInit;
8637 pScrn->SwitchMode = ZZZSwitchMode;
8638 pScrn->AdjustFrame = ZZZAdjustFrame;
8639 pScrn->EnterVT = ZZZEnterVT;
8640 pScrn->LeaveVT = ZZZLeaveVT;
8641 pScrn->FreeScreen = ZZZFreeScreen;
8642 pScrn->ValidMode = ZZZValidMode;
8647 #endif /* HAS_ISA_DEVS */
8655 <title>AvailableOptions</title>
8658 Define the <function>AvailableOptions()</function> function. The purpose
8659 of this is to return the available driver options back to the
8660 -configure option, so that an xorg.conf file can be built and the
8661 user can see which options are available for them to use.
8666 <title>PreInit</title>
8669 Define the <function>PreInit()</function> function. The purpose of
8670 this is to find all the information required to determine if the
8671 configuration is usable, and to initialise those parts of the
8672 <structname>ScrnInfoRec</structname> that can be set once at the beginning
8673 of the first server generation. The information should be found in
8674 the least intrusive way possible.
8678 This function is mandatory.
8685 The <function>PreInit()</function> function is only called once
8686 during the life of the X server (at the start of the first
8691 Data allocated here must be of the type that persists for
8692 the life of the X server. This means that data that hooks into
8693 the <structname>ScrnInfoRec</structname>'s <structfield>privates</structfield>
8694 field should be allocated here, but data that hooks into the
8695 <structname>ScreenRec</structname>'s <structfield>devPrivates</structfield> field
8696 should not be allocated here. The <structfield>driverPrivate</structfield>
8697 field should also be allocated here.
8701 Although the <structname>ScrnInfoRec</structname> has been allocated
8702 before this function is called, the <structname>ScreenRec</structname>
8703 has not been allocated. That means that things requiring it
8704 cannot be used in this function.
8708 Very little of the <structname>ScrnInfoRec</structname> has been
8709 initialised when this function is called. It is important to
8710 get the order of doing things right in this function.
8718 ZZZPreInit(ScrnInfoPtr pScrn, int flags)
8720 /* Fill in the monitor field */
8721 pScrn->monitor = pScrn->confScreen->monitor;
8724 * If using the vgahw module, it will typically be loaded
8725 * here by calling xf86LoadSubModule(pScrn, "vgahw");
8729 * Set the depth/bpp. Use the globally preferred depth/bpp. If the
8730 * driver has special default depth/bpp requirements, the defaults should
8731 * be specified here explicitly.
8732 * We support both 24bpp and 32bpp framebuffer layouts.
8733 * This sets pScrn->display also.
8735 if (!xf86SetDepthBpp(pScrn, 0, 0, 0,
8736 Support24bppFb | Support32bppFb)) {
8739 if (depth/bpp isn't one we support) {
8740 print error message;
8744 /* Print out the depth/bpp that was set */
8745 xf86PrintDepthBpp(pScrn);
8747 /* Set bits per RGB for 8bpp */
8748 if (pScrn->depth <= 8) {
8749 /* Take into account a dac_6_bit option here */
8750 pScrn->rgbBits = 6 or 8;
8754 * xf86SetWeight() and xf86SetDefaultVisual() must be called
8755 * after pScrn->display is initialised.
8758 /* Set weight/mask/offset for depth > 8 */
8759 if (pScrn->depth > 8) {
8760 if (!xf86SetWeight(pScrn, defaultWeight, defaultMask)) {
8763 if (weight isn't one we support) {
8764 print error message;
8770 /* Set the default visual. */
8771 if (!xf86SetDefaultVisual(pScrn, -1)) {
8774 if (visual isn't one we support) {
8775 print error message;
8780 /* If the driver supports gamma correction, set the gamma. */
8781 if (!xf86SetGamma(pScrn, default_gamma)) {
8785 /* This driver uses a programmable clock */
8786 pScrn->progClock = TRUE;
8788 /* Allocate the ZZZRec driverPrivate */
8789 if (!ZZZGetRec(pScrn)) {
8793 pZzz = ZZZPTR(pScrn);
8795 /* Collect all of the option flags (fill in pScrn->options) */
8796 xf86CollectOptions(pScrn, NULL);
8799 * Process the options based on the information in ZZZOptions.
8800 * The results are written to pZzz->Options. If all of the options
8801 * processing is done within this function a local variable "options"
8802 * can be used instead of pZzz->Options.
8804 if (!(pZzz->Options = xalloc(sizeof(ZZZOptions))))
8806 (void)memcpy(pZzz->Options, ZZZOptions, sizeof(ZZZOptions));
8807 xf86ProcessOptions(pScrn->scrnIndex, pScrn->options, pZzz->Options);
8810 * Set various fields of ScrnInfoRec and/or ZZZRec based on
8811 * the options found.
8814 pZzz->hwCursor = FALSE;
8815 if (xf86IsOptionSet(pZzz->Options, OPTION_HW_CURSOR)) {
8817 pZzz->hwCursor = TRUE;
8819 xf86DrvMsg(pScrn->scrnIndex, from, "Using %s cursor\n",
8820 pZzz->hwCursor ? "HW" : "SW");
8821 if (xf86IsOptionSet(pZzz->Options, OPTION_NOACCEL)) {
8822 pZzz->noAccel = TRUE;
8823 xf86DrvMsg(pScrn->scrnIndex, X_CONFIG,
8824 "Acceleration disabled\n");
8826 pZzz->noAccel = FALSE;
8828 if (xf86IsOptionSet(pZzz->Options, OPTION_PCI_RETRY)) {
8829 pZzz->UsePCIRetry = TRUE;
8830 xf86DrvMsg(pScrn->scrnIndex, X_CONFIG, "PCI retry enabled\n");
8832 pZzz->fooHack = 0;
8833 if (xf86GetOptValInteger(pZzz->Options, OPTION_FOO_HACK,
8834 &pZzz->fooHack)) {
8835 xf86DrvMsg(pScrn->scrnIndex, X_CONFIG, "Foo Hack set to %d\n",
8840 * Find the PCI slot(s) that this screen claimed in the probe.
8841 * In this case, exactly one is expected, so complain otherwise.
8842 * Note in this case we're not interested in the card types so
8843 * that parameter is set to NULL.
8845 if ((i = xf86GetPciInfoForScreen(pScrn->scrnIndex, &pciList, NULL))
8847 print error message;
8853 /* Note that pciList should be freed below when no longer needed */
8856 * Determine the chipset, allowing config file chipset and
8857 * chipid values to override the probed information. The config
8858 * chipset value has precedence over its chipid value if both
8861 * It isn't necessary to fill in pScrn->chipset if the driver
8862 * keeps track of the chipset in its ZZZRec.
8868 * Determine video memory, fb base address, I/O addresses, etc,
8869 * allowing the config file to override probed values.
8871 * Set the appropriate pScrn fields (videoRam is probably the
8872 * most important one that other code might require), and
8873 * print out the settings.
8878 /* Initialise a clockRanges list. */
8882 /* Set any other chipset specific things in the ZZZRec */
8886 /* Select valid modes from those available */
8888 i = xf86ValidateModes(pScrn, pScrn->monitor->Modes,
8889 pScrn->display->modes, clockRanges,
8890 NULL, minPitch, maxPitch, rounding,
8891 minHeight, maxHeight,
8892 pScrn->display->virtualX,
8893 pScrn->display->virtualY,
8894 pScrn->videoRam * 1024,
8895 LOOKUP_BEST_REFRESH);
8901 /* Prune the modes marked as invalid */
8903 xf86PruneDriverModes(pScrn);
8905 /* If no valid modes, return */
8907 if (i == 0 || pScrn->modes == NULL) {
8908 print error message;
8914 * Initialise the CRTC fields for the modes. This driver expects
8915 * vertical values to be halved for interlaced modes.
8917 xf86SetCrtcForModes(pScrn, INTERLACE_HALVE_V);
8919 /* Set the current mode to the first in the list. */
8920 pScrn->currentMode = pScrn->modes;
8922 /* Print the list of modes being used. */
8923 xf86PrintModes(pScrn);
8926 xf86SetDpi(pScrn, 0, 0);
8928 /* Load bpp-specific modules */
8929 switch (pScrn->bitsPerPixel) {
8949 if (mod && !xf86LoadSubModule(pScrn, mod))
8953 /* Load XAA if needed */
8954 if (!pZzz->noAccel || pZzz->hwCursor)
8955 if (!xf86LoadSubModule(pScrn, "xaa")) {
8967 <title>MapMem, UnmapMem</title>
8970 Define functions to map and unmap the video memory and any other
8971 memory apertures required. These functions are not mandatory, but
8972 it is often useful to have such functions.
8977 ZZZMapMem(ScrnInfoPtr pScrn)
8979 /* Call xf86MapPciMem() to map each PCI memory area */
8981 return TRUE or FALSE;
8985 ZZZUnmapMem(ScrnInfoPtr pScrn)
8987 /* Call xf86UnMapVidMem() to unmap each memory area */
8989 return TRUE or FALSE;
8995 <title>Save, Restore</title>
8998 Define functions to save and restore the original video state. These
8999 functions are not mandatory, but are often useful.
9004 ZZZSave(ScrnInfoPtr pScrn)
9007 * Save state into per-screen data structures.
9008 * If using the vgahw module, vgaHWSave will typically be
9015 ZZZRestore(ScrnInfoPtr pScrn)
9018 * Restore state from per-screen data structures.
9019 * If using the vgahw module, vgaHWRestore will typically be
9028 <title>ModeInit</title>
9031 Define a function to initialise a new video mode. This function isn't
9032 mandatory, but is often useful.
9037 ZZZModeInit(ScrnInfoPtr pScrn, DisplayModePtr mode)
9040 * Program a video mode. If using the vgahw module,
9041 * vgaHWInit and vgaRestore will typically be called here.
9042 * Once up to the point where there can't be a failure
9043 * set pScrn->vtSema to TRUE.
9051 <title>ScreenInit</title>
9054 Define the <function>ScreenInit()</function> function. This is called
9055 at the start of each server generation, and should fill in as much
9056 of the <structname>ScreenRec</structname> as possible as well as any other
9057 data that is initialised once per generation. It should initialise
9058 the framebuffer layers it is using, and initialise the initial video
9063 This function is mandatory.
9067 NOTE: The <structname>ScreenRec</structname> (<parameter>pScreen</parameter>) is
9068 passed to this driver, but it and the
9069 <varname>ScrnInfoRecs</varname> are not yet hooked into each
9070 other. This means that in this function, and functions it
9071 calls, one cannot be found from the other.
9076 ZZZScreenInit(int scrnIndex, ScreenPtr pScreen, int argc, char **argv)
9078 /* Get the ScrnInfoRec */
9079 pScrn = xf86Screens[pScreen->myNum];
9082 * If using the vgahw module, its data structures and related
9083 * things are typically initialised/mapped here.
9086 /* Save the current video state */
9089 /* Initialise the first mode */
9090 ZZZModeInit(pScrn, pScrn->currentMode);
9092 /* Set the viewport if supported */
9094 ZZZAdjustFrame(scrnIndex, pScrn->frameX0, pScrn->frameY0, 0);
9097 * Setup the screen's visuals, and initialise the framebuffer
9101 /* Reset the visual list */
9102 miClearVisualTypes();
9105 * Setup the visuals supported. This driver only supports
9106 * TrueColor for bpp > 8, so the default set of visuals isn't
9107 * acceptable. To deal with this, call miSetVisualTypes with
9108 * the appropriate visual mask.
9111 if (pScrn->bitsPerPixel > 8) {
9112 if (!miSetVisualTypes(pScrn->depth, TrueColorMask,
9113 pScrn->rgbBits, pScrn->defaultVisual))
9116 if (!miSetVisualTypes(pScrn->depth,
9117 miGetDefaultVisualMask(pScrn->depth),
9118 pScrn->rgbBits, pScrn->defaultVisual))
9123 * Initialise the framebuffer.
9126 switch (pScrn->bitsPerPixel) {
9128 ret = xf1bppScreenInit(pScreen, FbBase,
9129 pScrn->virtualX, pScrn->virtualY,
9130 pScrn->xDpi, pScrn->yDpi,
9131 pScrn->displayWidth);
9134 ret = xf4bppScreenInit(pScreen, FbBase,
9135 pScrn->virtualX, pScrn->virtualY,
9136 pScrn->xDpi, pScrn->yDpi,
9137 pScrn->displayWidth);
9140 ret = cfbScreenInit(pScreen, FbBase,
9141 pScrn->virtualX, pScrn->virtualY,
9142 pScrn->xDpi, pScrn->yDpi,
9143 pScrn->displayWidth);
9146 ret = cfb16ScreenInit(pScreen, FbBase,
9147 pScrn->virtualX, pScrn->virtualY,
9148 pScrn->xDpi, pScrn->yDpi,
9149 pScrn->displayWidth);
9152 ret = cfb24ScreenInit(pScreen, FbBase,
9153 pScrn->virtualX, pScrn->virtualY,
9154 pScrn->xDpi, pScrn->yDpi,
9155 pScrn->displayWidth);
9158 ret = cfb32ScreenInit(pScreen, FbBase,
9159 pScrn->virtualX, pScrn->virtualY,
9160 pScrn->xDpi, pScrn->yDpi,
9161 pScrn->displayWidth);
9164 print a message about an internal error;
9172 /* Override the default mask/offset settings */
9173 if (pScrn->bitsPerPixel > 8) {
9174 for (i = 0, visual = pScreen->visuals;
9175 i < pScreen->numVisuals; i++, visual++) {
9176 if ((visual->class | DynamicClass) == DirectColor) {
9177 visual->offsetRed = pScrn->offset.red;
9178 visual->offsetGreen = pScrn->offset.green;
9179 visual->offsetBlue = pScrn->offset.blue;
9180 visual->redMask = pScrn->mask.red;
9181 visual->greenMask = pScrn->mask.green;
9182 visual->blueMask = pScrn->mask.blue;
9188 * If banking is needed, initialise an miBankInfoRec (defined in
9189 * "mibank.h"), and call miInitializeBanking().
9191 if (!miInitializeBanking(pScreen, pScrn->virtualX, pScrn->virtualY,
9192 pScrn->displayWidth, pBankInfo))
9196 * If backing store is to be supported (as is usually the case),
9199 miInitializeBackingStore(pScreen);
9202 * Set initial black & white colourmap indices.
9204 xf86SetBlackWhitePixels(pScreen);
9207 * Install colourmap functions. If using the vgahw module,
9208 * vgaHandleColormaps would usually be called here.
9214 * Initialise cursor functions. This example is for the mi
9217 miDCInitialize(pScreen, xf86GetPointerScreenFuncs());
9219 /* Initialise the default colourmap */
9220 switch (pScrn->depth) {
9222 if (!xf1bppCreateDefColormap(pScreen))
9226 if (!xf4bppCreateDefColormap(pScreen))
9230 if (!cfbCreateDefColormap(pScreen))
9236 * Wrap the CloseScreen vector and set SaveScreen.
9238 ZZZPTR(pScrn)->CloseScreen = pScreen->CloseScreen;
9239 pScreen->CloseScreen = ZZZCloseScreen;
9240 pScreen->SaveScreen = ZZZSaveScreen;
9242 /* Report any unused options (only for the first generation) */
9243 if (serverGeneration == 1) {
9244 xf86ShowUnusedOptions(pScrn->scrnIndex, pScrn->options);
9254 <title>SwitchMode</title>
9257 Define the <function>SwitchMode()</function> function if mode switching
9258 is supported by the driver.
9263 ZZZSwitchMode(int scrnIndex, DisplayModePtr mode, int flags)
9265 return ZZZModeInit(xf86Screens[scrnIndex], mode);
9271 <title>AdjustFrame</title>
9274 Define the <function>AdjustFrame()</function> function if the driver
9280 ZZZAdjustFrame(int scrnIndex, int x, int y, int flags)
9282 /* Adjust the viewport */
9288 <title>EnterVT, LeaveVT</title>
9291 Define the <function>EnterVT()</function> and <function>LeaveVT()</function>
9296 These functions are mandatory.
9301 ZZZEnterVT(int scrnIndex, int flags)
9303 ScrnInfoPtr pScrn = xf86Screens[scrnIndex];
9304 return ZZZModeInit(pScrn, pScrn->currentMode);
9308 ZZZLeaveVT(int scrnIndex, int flags)
9310 ScrnInfoPtr pScrn = xf86Screens[scrnIndex];
9317 <title>CloseScreen</title>
9320 Define the <function>CloseScreen()</function> function:
9324 This function is mandatory. Note that it unwraps the previously
9325 wrapped <structfield>pScreen->CloseScreen</structfield>, and finishes by
9331 ZZZCloseScreen(int scrnIndex, ScreenPtr pScreen)
9333 ScrnInfoPtr pScrn = xf86Screens[scrnIndex];
9334 if (pScrn->vtSema) {
9338 pScrn->vtSema = FALSE;
9339 pScreen->CloseScreen = ZZZPTR(pScrn)->CloseScreen;
9340 return (*pScreen->CloseScreen)(scrnIndex, pScreen);
9346 <title>SaveScreen</title>
9349 Define the <function>SaveScreen()</function> function (the screen
9350 blanking function). When using the vgahw module, this will typically
9355 ZZZSaveScreen(ScreenPtr pScreen, int mode)
9357 return vgaHWSaveScreen(pScreen, mode);
9363 This function is mandatory. Before modifying any hardware register
9364 directly this function needs to make sure that the Xserver is active
9365 by checking if <parameter>pScrn</parameter> is non-NULL and for
9366 <literal remap="tt">pScrn->vtSema == TRUE</literal>.
9371 <title>FreeScreen</title>
9374 Define the <function>FreeScreen()</function> function. This function
9375 is optional. It should be defined if the <structname>ScrnInfoRec</structname>
9376 <structfield>driverPrivate</structfield> field is used so that it can be freed
9377 when a screen is deleted by the common layer for reasons possibly
9378 beyond the driver's control. This function is not used in during
9379 normal (error free) operation. The per-generation data is freed by
9380 the <function>CloseScreen()</function> function.
9385 ZZZFreeScreen(int scrnIndex, int flags)
9388 * If the vgahw module is used vgaHWFreeHWRec() would be called
9391 ZZZFreeRec(xf86Screens[scrnIndex]);