Commit | Line | Data |
---|---|---|
a09e091a JB |
1 | <?xml version="1.0" encoding="ISO-8859-1"?> |
2 | <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" | |
3 | "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ | |
4 | <!ENTITY % xorg-defs SYSTEM "defs.ent"> %xorg-defs; | |
5 | <!ENTITY % defs SYSTEM "/xserver/doc/xml/xserver.ent"> %defs; | |
6 | <!-- config file keyword markup --> | |
7 | <!-- specific config file keywords --> | |
8 | <!ENTITY k.device "<emphasis>Device</emphasis>"> | |
9 | <!ENTITY k.monitor "<emphasis>Monitor</emphasis>"> | |
10 | <!ENTITY k.display "<emphasis>Display</emphasis>"> | |
11 | <!ENTITY k.inputdevice "<emphasis>InputDevice</emphasis>"> | |
12 | <!ENTITY k.screen "<emphasis>Screen</emphasis>"> | |
13 | <!ENTITY k.serverlayout "<emphasis>ServerLayout</emphasis>"> | |
14 | <!ENTITY k.driver "<emphasis>Driver</emphasis>"> | |
15 | <!ENTITY k.module "<emphasis>Module</emphasis>"> | |
16 | <!ENTITY k.identifier "<emphasis>Identifier</emphasis>"> | |
17 | <!ENTITY k.serverflags "<emphasis>ServerFlags</emphasis>"> | |
18 | ] > | |
19 | ||
20 | <article id="ddxDesign"> | |
21 | <articleinfo> | |
22 | ||
23 | <title>XFree86 DDX Design</title> | |
24 | ||
25 | <authorgroup> | |
26 | <corpauthor>The XFree86 Project</corpauthor> | |
27 | <corpauthor>The X.Org Foundation</corpauthor> | |
28 | ||
29 | <othercredit> | |
30 | <firstname>Jim</firstname><surname>Gettys</surname> | |
31 | <contrib>Updates for X11R6.7</contrib> | |
32 | </othercredit> | |
33 | </authorgroup> | |
34 | ||
35 | <pubdate>&xserver.reldate;</pubdate> | |
36 | <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo> | |
37 | <releaseinfo>X Server Version &xserver.version;</releaseinfo> | |
38 | ||
39 | </articleinfo> | |
40 | ||
41 | <note><para> | |
42 | This document describes software undergoing continual evolution, and | |
43 | the interfaces described here are subject to change without notice. | |
44 | This document is intended to cover the interfaces as found in the | |
45 | xorg-server-&xserver.version; release, but is probably not completely | |
46 | in sync with the code base. | |
47 | </para></note> | |
48 | ||
49 | ||
50 | <sect1> | |
51 | <title>Preface</title> | |
52 | ||
53 | <para> | |
54 | This document was originally the design spec for the DDX layer of the | |
55 | XFree86 4.0 X server. The X.Org Foundation adopted the XFree86 4.4rc2 | |
56 | version of that server as the basis of the Xorg server project, and has | |
57 | evolved the XFree86 DDX layer greatly since forking. This document thus | |
58 | covers only the current implementation of the XFree86 DDX as found in the | |
59 | Xorg server &xserver.version; release, and no longer matches the XFree86 | |
60 | server itself. | |
61 | </para> | |
62 | ||
63 | <para> | |
64 | The XFree86 Project's broad design principles for XFree86 4.0 were: | |
65 | <itemizedlist> | |
66 | <listitem><para>keep it reasonable | |
67 | <itemizedlist> | |
68 | <listitem><para>We cannot rewrite the complete server | |
69 | </para></listitem> | |
70 | <listitem><para>We don't want to re-invent the wheel | |
71 | </para></listitem> | |
72 | </itemizedlist></para></listitem> | |
73 | <listitem><para>keep it modular | |
74 | <itemizedlist> | |
75 | <listitem><para>As many things as possible should go into modules | |
76 | </para></listitem> | |
77 | <listitem><para>The basic loader binary should be minimal | |
78 | </para></listitem> | |
79 | <listitem><para>A clean design with well defined layering is | |
80 | important</para></listitem> | |
81 | <listitem><para>DDX specific global variables are a nono | |
82 | </para></listitem> | |
83 | <listitem><para>The structure should be flexible enough to allow | |
84 | future extensions</para></listitem> | |
85 | <listitem><para>The structure should minimize duplication of | |
86 | common code</para></listitem> | |
87 | </itemizedlist></para></listitem> | |
88 | <listitem><para>keep important features in mind | |
89 | <itemizedlist> | |
90 | <listitem><para>multiple screens, including multiple instances | |
91 | of drivers</para></listitem> | |
92 | <listitem><para>mixing different color depths and visuals on | |
93 | different and ideally even on the same screen | |
94 | </para></listitem> | |
95 | <listitem><para>better control of the PCI device used | |
96 | </para></listitem> | |
97 | <listitem><para>better config file parser</para></listitem> | |
98 | <listitem><para>get rid of all VGA compatibility assumptions | |
99 | </para></listitem> | |
100 | </itemizedlist></para></listitem> | |
101 | </itemizedlist> | |
102 | </para> | |
103 | ||
104 | <para> | |
105 | While the XFree86 project had a goal of avoiding changes to the DIX | |
106 | layer unless they found major deficiencies there, to avoid divergence from | |
107 | the X.Org sample implementation they were integrating changes from, the | |
108 | X.Org developers now maintain both sides, and make changes where they are | |
109 | most appropriate. This document concentrates on the XFree86 DDX layer used | |
110 | in the Xorg server itself (the code found in <filename>hw/xfree86</filename> | |
111 | in the source tree), and developers will also want to refer to the | |
112 | <filename>Xserver-spec</filename> documentation that covers the DIX layer | |
113 | routines common to all the X servers in the sample implementation. | |
114 | </para> | |
115 | </sect1> | |
116 | ||
117 | <sect1> | |
118 | <title>The xorg.conf File</title> | |
119 | ||
120 | <para> | |
121 | The xorg.conf file format is based on the XF86Config format from XFree86 4.4, | |
122 | which is in turn similar to the old XFree86 3.x XF86Config format, with the | |
123 | following changes: | |
124 | </para> | |
125 | ||
126 | <sect2> | |
127 | <title>&k.device; section</title> | |
128 | ||
129 | <para> | |
130 | The &k.device; sections are similar to what they used to be, and | |
131 | describe hardware-specific information for a single video card. | |
132 | &k.device; | |
133 | Some new keywords are added: | |
134 | ||
135 | ||
136 | <variablelist> | |
137 | <varlistentry><term>Driver "drivername"</term> | |
138 | <listitem><para> | |
139 | Specifies the name of the driver to be used for the card. This | |
140 | is mandatory. | |
141 | </para></listitem></varlistentry> | |
142 | <varlistentry><term>BusID "busslot"</term> | |
143 | <listitem><para> | |
144 | Specifies uniquely the location of the card on the bus. The | |
145 | purpose is to identify particular cards in a multi-headed | |
146 | configuration. The format of the argument is intentionally | |
147 | vague, and may be architecture dependent. For a PCI bus, it | |
148 | is something like "bus:slot:func". | |
149 | </para></listitem></varlistentry> | |
150 | </variablelist> | |
151 | </para> | |
152 | ||
153 | <para> | |
154 | A &k.device; section is considered <quote>active</quote> if there is a reference | |
155 | to it in an active &k.screen; section. | |
156 | </para> | |
157 | </sect2> | |
158 | ||
159 | <sect2> | |
160 | <title>&k.screen; section</title> | |
161 | ||
162 | <para> | |
163 | The &k.screen; sections are similar to what they used to be. They | |
164 | no longer have a &k.driver; keyword, but an &k.identifier; keyword | |
165 | is added. (The &k.driver; keyword may be accepted in place of the | |
166 | &k.identifier; keyword for compatibility purposes.) The identifier | |
167 | can be used to identify which screen is to be active when multiple | |
168 | &k.screen; sections are present. It is possible to specify the active | |
169 | screen from the command line. A default is chosen in the absence | |
170 | of one being specified. A &k.screen; section is considered <quote>active</quote> | |
171 | if there is a reference to it either from the command line, or from | |
172 | an active &k.serverlayout; section. | |
173 | </para> | |
174 | </sect2> | |
175 | ||
176 | <sect2> | |
177 | <title>&k.inputdevice; section</title> | |
178 | ||
179 | <para> | |
180 | The &k.inputdevice; section is a new section that describes | |
181 | configuration information for input devices. It replaces the old | |
182 | <emphasis>Keyboard</emphasis>, <emphasis>Pointer</emphasis> and <emphasis>XInput</emphasis> | |
183 | sections. Like the &k.device; section, it has two mandatory keywords: | |
184 | &k.identifier; and &k.driver;. For compatibility purposes the old | |
185 | <emphasis>Keyboard</emphasis> and <emphasis>Pointer</emphasis> sections are | |
186 | converted by the parser into &k.inputdevice; sections as follows: | |
187 | ||
188 | <variablelist> | |
189 | <varlistentry><term><emphasis>Keyboard</emphasis></term> | |
190 | <listitem><literallayout> | |
191 | &k.identifier; "Implicit Core Keyboard" | |
192 | &k.driver; "kbd" | |
193 | </literallayout></listitem></varlistentry> | |
194 | <varlistentry><term><emphasis>Pointer</emphasis></term> | |
195 | <listitem><literallayout> | |
196 | &k.identifier; "Implicit Core Pointer" | |
197 | &k.driver; "mouse" | |
198 | </literallayout></listitem></varlistentry> | |
199 | </variablelist> | |
200 | </para> | |
201 | ||
202 | <para> | |
203 | An &k.inputdevice; section is considered active if there is a | |
204 | reference to it in an active &k.serverlayout; section. An | |
205 | &k.inputdevice; section may also be referenced implicitly if there | |
206 | is no &k.serverlayout; section, if the <option>-screen</option> command | |
207 | line options is used, or if the &k.serverlayout; section doesn't | |
208 | reference any &k.inputdevice; sections. In this case, the first | |
209 | sections with drivers "kbd" and "mouse" are used as the core | |
210 | keyboard and pointer respectively. | |
211 | </para> | |
212 | </sect2> | |
213 | ||
214 | <sect2> | |
215 | <title>&k.serverlayout; section</title> | |
216 | ||
217 | <para> | |
218 | The &k.serverlayout; section is a new section that is used to identify | |
219 | which &k.screen; sections are to be used in a multi-headed configuration, | |
220 | and the relative layout of those screens. It also identifies which | |
221 | &k.inputdevice; sections are to be used. Each &k.serverlayout; section | |
222 | has an identifier, a list of &k.screen; section identifiers, and a list of | |
223 | &k.inputdevice; section identifiers. &k.serverflags; options may also be | |
224 | included in a &k.serverlayout; section, making it possible to override | |
225 | the global values in the &k.serverflags; section. | |
226 | </para> | |
227 | ||
228 | <para> | |
229 | A &k.serverlayout; section can be made active by being referenced on | |
230 | the command line. In the absence of this, a default will be chosen | |
231 | (the first one found). The screen names may optionally be followed | |
232 | by a number specifying the preferred screen number, and optionally | |
233 | by information specifying the physical positioning of the screen, | |
234 | either in absolute terms or relative to another screen (or screens). | |
235 | When no screen number is specified, they are numbered according to | |
236 | the order in which they are listed. The old (now obsolete) method | |
237 | of providing the positioning information is to give the names of | |
238 | the four adjacent screens. The order of these is top, bottom, left, | |
239 | right. Here is an example of a &k.serverlayout; section for two | |
240 | screens using the old method, with the second located to the right | |
241 | of the first: | |
242 | ||
243 | <programlisting> | |
244 | Section "ServerLayout" | |
245 | Identifier "Main Layout" | |
246 | Screen 0 "Screen 1" "" "" "" "Screen 2" | |
247 | Screen 1 "Screen 2" | |
248 | Screen "Screen 3" | |
249 | EndSection | |
250 | </programlisting> | |
251 | </para> | |
252 | ||
253 | <para> | |
254 | The preferred way of specifying the layout is to explicitly specify | |
255 | the screen's location in absolute terms or relative to another | |
256 | screen. | |
257 | </para> | |
258 | ||
259 | <para> | |
260 | In the absolute case, the upper left corner's coordinates are given | |
261 | after the <emphasis>Absolute</emphasis> keyword. If the coordinates are | |
262 | omitted, a value of <code>(0,0)</code> is assumed. An example | |
263 | of absolute positioning follows: | |
264 | ||
265 | <programlisting> | |
266 | Section "ServerLayout" | |
267 | Identifier "Main Layout" | |
268 | Screen 0 "Screen 1" Absolute 0 0 | |
269 | Screen 1 "Screen 2" Absolute 1024 0 | |
270 | Screen "Screen 3" Absolute 2048 0 | |
271 | EndSection | |
272 | </programlisting> | |
273 | </para> | |
274 | ||
275 | <para> | |
276 | In the relative case, the position is specified by either using one of | |
277 | the following keywords followed by the name of the reference screen: | |
278 | ||
279 | <simplelist type='vert' columns='1'> | |
280 | <member><emphasis>RightOf</emphasis></member> | |
281 | <member><emphasis>LeftOf</emphasis></member> | |
282 | <member><emphasis>Above</emphasis></member> | |
283 | <member><emphasis>Below</emphasis></member> | |
284 | <member><emphasis>Relative</emphasis></member> | |
285 | </simplelist> | |
286 | </para> | |
287 | ||
288 | <para> | |
289 | When the <emphasis>Relative</emphasis> keyword is used, the reference screen | |
290 | name is followed by the coordinates of the new screen's origin | |
291 | relative to reference screen. The following example shows how to use | |
292 | some of the relative positioning options. | |
293 | ||
294 | <programlisting> | |
295 | Section "ServerLayout" | |
296 | Identifier "Main Layout" | |
297 | Screen 0 "Screen 1" | |
298 | Screen 1 "Screen 2" RightOf "Screen 1" | |
299 | Screen "Screen 3" Relative "Screen 1" 2048 0 | |
300 | EndSection | |
301 | </programlisting> | |
302 | </para> | |
303 | </sect2> | |
304 | ||
305 | <sect2> | |
306 | <title>Options</title> | |
307 | ||
308 | <para> | |
309 | Options are used more extensively. They may appear in most sections | |
310 | now. Options related to drivers can be present in the &k.screen;, | |
311 | &k.device; and &k.monitor; sections and the &k.display; subsections. | |
312 | The order of precedence is &k.display;, &k.screen;, &k.monitor;, | |
313 | &k.device;. Options have been extended to allow an optional value | |
314 | to be specified in addition to the option name. For more details | |
315 | about options, see the <link linkend="options">Options</link> section | |
316 | for details. | |
317 | </para> | |
318 | </sect2> | |
319 | </sect1> | |
320 | ||
321 | <sect1> | |
322 | <title>Driver Interface</title> | |
323 | ||
324 | <para> | |
325 | The driver interface consists of a minimal set of entry points that are | |
326 | required based on the external events that the driver must react to. | |
327 | No non-essential structure is imposed on the way they are used beyond | |
328 | that. This is a significant difference compared with the old design. | |
329 | </para> | |
330 | ||
331 | <para> | |
332 | The entry points for drawing operations are already taken care of by | |
333 | the framebuffer code. Extensions and enhancements to framebuffer code | |
334 | are outside the scope of this document. | |
335 | </para> | |
336 | ||
337 | <para> | |
338 | This approach to the driver interface provides good flexibility, but does | |
339 | increase the complexity of drivers. To help address this, the XFree86 | |
340 | common layer provides a set of <quote>helper</quote> functions to take care of things | |
341 | that most drivers need. These helpers help minimise the amount of code | |
342 | duplication between drivers. The use of helper functions by drivers is | |
343 | however optional, though encouraged. The basic philosophy behind the | |
344 | helper functions is that they should be useful to many drivers, that | |
345 | they should balance this against the complexity of their interface. It | |
346 | is inevitable that some drivers may find some helpers unsuitable and | |
347 | need to provide their own code. | |
348 | </para> | |
349 | ||
350 | <para> | |
351 | Events that a driver needs to react to are: | |
352 | ||
353 | <variablelist> | |
354 | <varlistentry><term>ScreenInit</term> | |
355 | ||
356 | <listitem><para> | |
357 | An initialisation function is called from the DIX layer for each | |
358 | screen at the start of each server generation. | |
359 | </para></listitem></varlistentry> | |
360 | ||
361 | <varlistentry><term>Enter VT</term> | |
362 | ||
363 | <listitem><para> | |
364 | The server takes control of the console. | |
365 | </para></listitem></varlistentry> | |
366 | ||
367 | <varlistentry><term>Leave VT</term> | |
368 | ||
369 | <listitem><para> | |
370 | The server releases control of the console. | |
371 | </para></listitem></varlistentry> | |
372 | ||
373 | <varlistentry><term>Mode Switch</term> | |
374 | ||
375 | <listitem><para> | |
376 | Change video mode. | |
377 | </para></listitem></varlistentry> | |
378 | ||
379 | <varlistentry><term>ViewPort change</term> | |
380 | ||
381 | <listitem><para> | |
382 | Change the origin of the physical view port. | |
383 | </para></listitem></varlistentry> | |
384 | ||
385 | <varlistentry><term>ScreenSaver state change</term> | |
386 | ||
387 | <listitem><para> | |
388 | Screen saver activation/deactivation. | |
389 | </para></listitem></varlistentry> | |
390 | ||
391 | <varlistentry><term>CloseScreen</term> | |
392 | ||
393 | <listitem><para> | |
394 | A close screen function is called from the DIX layer for each screen | |
395 | at the end of each server generation. | |
396 | </para></listitem></varlistentry> | |
397 | </variablelist> | |
398 | </para> | |
399 | ||
400 | ||
401 | <para> | |
402 | In addition to these events, the following functions are required by | |
403 | the XFree86 common layer: | |
404 | ||
405 | <variablelist> | |
406 | <varlistentry><term>Identify</term> | |
407 | ||
408 | <listitem><para> | |
409 | Print a driver identifying message. | |
410 | </para></listitem></varlistentry> | |
411 | ||
412 | <varlistentry><term>Probe</term> | |
413 | ||
414 | <listitem><para> | |
415 | This is how a driver identifies if there is any hardware present that | |
416 | it knows how to drive. | |
417 | </para></listitem></varlistentry> | |
418 | ||
419 | <varlistentry><term>PreInit</term> | |
420 | ||
421 | <listitem><para> | |
422 | Process information from the xorg.conf file, determine the | |
423 | full characteristics of the hardware, and determine if a valid | |
424 | configuration is present. | |
425 | </para></listitem></varlistentry> | |
426 | </variablelist> | |
427 | </para> | |
428 | ||
429 | <para> | |
430 | The VidMode extension also requires: | |
431 | ||
432 | <variablelist> | |
433 | <varlistentry><term>ValidMode</term> | |
434 | ||
435 | <listitem><para> | |
436 | Identify if a new mode is usable with the current configuration. | |
437 | The PreInit function (and/or helpers it calls) may also make use | |
438 | of the ValidMode function or something similar. | |
439 | </para></listitem></varlistentry> | |
440 | </variablelist> | |
441 | </para> | |
442 | ||
443 | ||
444 | <para> | |
445 | Other extensions may require other entry points. The drivers will | |
446 | inform the common layer of these in such cases. | |
447 | </para> | |
448 | </sect1> | |
449 | ||
450 | <sect1> | |
451 | <title>Resource Access Control Introduction</title> | |
452 | ||
453 | <para> | |
454 | Graphics devices are accessed through ranges in I/O or memory space. | |
455 | While most modern graphics devices allow relocation of such ranges many | |
456 | of them still require the use of well established interfaces such as | |
457 | VGA memory and IO ranges or 8514/A IO ranges. With modern buses (like | |
458 | PCI) it is possible for multiple video devices to share access to these | |
459 | resources. The RAC (Resource Access Control) subsystem provides a | |
460 | mechanism for this. | |
461 | </para> | |
462 | ||
463 | <sect2> | |
464 | <title>Terms and Definitions</title> | |
465 | ||
466 | <sect3> | |
467 | <title>Bus</title> | |
468 | ||
469 | <para> | |
470 | <quote>Bus</quote> is ambiguous as it is used for different things: it may refer | |
471 | to physical incompatible extension connectors in a computer system. | |
472 | The RAC system knows two such systems: The ISA bus and the PCI bus. | |
473 | (On the software level EISA, MCA and VL buses are currently treated | |
474 | like ISA buses). <quote>Bus</quote> may also refer to logically different | |
475 | entities on a single bus system which are connected via bridges. A | |
476 | PCI system may have several distinct PCI buses connecting each other | |
477 | by PCI-PCI bridges or to the host CPU by HOST-PCI bridges. | |
478 | </para> | |
479 | ||
480 | <para> | |
481 | Systems that host more than one bus system link these together using | |
482 | bridges. Bridges are a concern to RAC as they might block or pass | |
483 | specific resources. PCI-PCI bridges may be set up to pass VGA | |
484 | resources to the secondary bus. PCI-ISA buses pass any resources not | |
485 | decoded on the primary PCI bus to the ISA bus. This way VGA resources | |
486 | (although exclusive on the ISA bus) can be shared by ISA and PCI | |
487 | cards. Currently HOST-PCI bridges are not yet handled by RAC as they | |
488 | require specific drivers. | |
489 | </para> | |
490 | </sect3> | |
491 | ||
492 | <sect3> | |
493 | <title>Entity</title> | |
494 | ||
495 | <para> | |
496 | The smallest independently addressable unit on a system bus is | |
497 | referred to as an entity. So far we know ISA and PCI entities. PCI | |
498 | entities can be located on the PCI bus by an unique ID consisting of | |
499 | the bus, card and function number. | |
500 | </para> | |
501 | </sect3> | |
502 | ||
503 | <sect3> | |
504 | <title>Resource</title> | |
505 | ||
506 | <para> | |
507 | <quote>Resource</quote> refers to a range of memory or I/O addresses an entity | |
508 | can decode. | |
509 | </para> | |
510 | ||
511 | <para> | |
512 | If a device is capable of disabling this decoding the resource is | |
513 | called sharable. For PCI devices a generic method is provided to | |
514 | control resource decoding. Other devices will have to provide a | |
515 | device specific function to control decoding. | |
516 | </para> | |
517 | ||
518 | <para> | |
519 | If the entity is capable of decoding this range at a different | |
520 | location this resource is considered relocatable. | |
521 | </para> | |
522 | ||
523 | <para> | |
524 | Resources which start at a specific address and occupy a single | |
525 | continuous range are called block resources. | |
526 | </para> | |
527 | ||
528 | <para> | |
529 | Alternatively resource addresses can be decoded in a way that they | |
530 | satisfy the conditions: | |
531 | <programlisting> | |
532 | address & mask == base | |
533 | </programlisting> | |
534 | and | |
535 | <programlisting> | |
536 | base & mask == base | |
537 | </programlisting> | |
538 | Resources addressed in such a way are called sparse resources. | |
539 | </para> | |
540 | ||
541 | </sect3> | |
542 | ||
543 | <sect3> | |
544 | <title>Server States</title> | |
545 | ||
546 | <para> | |
547 | The resource access control system knows two server states: the | |
548 | SETUP and the OPERATING state. The SETUP state is entered whenever | |
549 | a mode change takes place or the server exits or does VT switching. | |
550 | During this state all entity resources are under resource access | |
551 | control. During OPERATING state only those entities are controlled | |
552 | which actually have shared resources that conflict with others. | |
553 | </para> | |
554 | </sect3> | |
555 | </sect2> | |
556 | </sect1> | |
557 | ||
558 | <sect1> | |
559 | <title>Control Flow in the Server and Mandatory Driver Functions</title> | |
560 | ||
561 | <para> | |
562 | At the start of each server generation, <function>main()</function> | |
563 | (<filename>dix/main.c</filename>) calls the DDX function | |
564 | <function>InitOutput()</function>. This is the first place that the DDX gets | |
565 | control. <function>InitOutput()</function> is expected to fill in the global | |
566 | <structname>screenInfo</structname> struct, and one | |
567 | <structfield>screenInfo.screen[]</structfield> entry for each screen present. | |
568 | Here is what <function>InitOutput()</function> does: | |
569 | </para> | |
570 | ||
571 | <sect2> | |
572 | <title>Parse the xorg.conf file</title> | |
573 | ||
574 | <para> | |
575 | This is done at the start of the first server generation only. | |
576 | </para> | |
577 | ||
578 | <para> | |
579 | The xorg.conf file is read in full, and the resulting information | |
580 | stored in data structures. None of the parsed information is | |
581 | processed at this point. The parser data structures are opaque to | |
582 | the video drivers and to most of the common layer code. | |
583 | </para> | |
584 | ||
585 | <para> | |
586 | The entire file is parsed first to remove any section ordering | |
587 | requirements. | |
588 | </para> | |
589 | </sect2> | |
590 | ||
591 | ||
592 | <sect2> | |
593 | <title>Initial processing of parsed information and command line options | |
594 | </title> | |
595 | ||
596 | <para> | |
597 | This is done at the start of the first server generation only. | |
598 | </para> | |
599 | ||
600 | <para> | |
601 | The initial processing is to determine paths like the | |
602 | <emphasis>ModulePath</emphasis>, etc, and to determine which &k.serverlayout;, | |
603 | &k.screen; and &k.device; sections are active. | |
604 | </para> | |
605 | </sect2> | |
606 | ||
607 | ||
608 | <sect2> | |
609 | <title>Enable port I/O access</title> | |
610 | ||
611 | <para> | |
612 | Port I/O access is controlled from the XFree86 common layer, and is | |
613 | <quote>all or nothing</quote>. It is enabled prior to calling driver probes, at | |
614 | the start of subsequent server generations, and when VT switching | |
615 | back to the Xserver. It is disabled at the end of server generations, | |
616 | and when VT switching away from the Xserver. | |
617 | </para> | |
618 | ||
619 | <para> | |
620 | The implementation details of this may vary on different platforms. | |
621 | </para> | |
622 | </sect2> | |
623 | ||
624 | ||
625 | <sect2> | |
626 | <title>General bus probe</title> | |
627 | ||
628 | <para> | |
629 | This is done at the start of the first server generation only. | |
630 | </para> | |
631 | ||
632 | <para> | |
633 | In the case of ix86 machines, this will be a general PCI probe. | |
634 | The full information obtained here will be available to the drivers. | |
635 | This information persists for the life of the Xserver. In the PCI | |
636 | case, the PCI information for all video cards found is available by | |
637 | calling <function>xf86GetPciVideoInfo()</function>. | |
638 | </para> | |
639 | ||
640 | <blockquote><para> | |
641 | <programlisting> | |
642 | pciVideoPtr *xf86GetPciVideoInfo(void); | |
643 | </programlisting> | |
644 | <blockquote><para> | |
645 | returns a pointer to a list of pointers to | |
646 | <structname>pciVideoRec</structname> entries, of which there is one for | |
647 | each detected PCI video card. The list is terminated with a | |
648 | <constant>NULL</constant> pointer. If no PCI video cards were | |
649 | detected, the return value is <constant>NULL</constant>. | |
650 | ||
651 | </para></blockquote> | |
652 | </para></blockquote> | |
653 | ||
654 | <para> | |
655 | After the bus probe, the resource broker is initialised. | |
656 | </para> | |
657 | </sect2> | |
658 | ||
659 | ||
660 | <sect2> | |
661 | <title>Load initial set of modules</title> | |
662 | ||
663 | <para> | |
664 | This is done at the start of the first server generation only. | |
665 | </para> | |
666 | ||
667 | <para> | |
668 | The next set of modules loaded are those specified explicitly in the | |
669 | &k.module; section of the config file. | |
670 | </para> | |
671 | ||
672 | <para> | |
673 | The final set of initial modules are the driver modules referenced | |
674 | by the active &k.device; and &k.inputdevice; sections in the config | |
675 | file. Each of these modules is loaded exactly once. | |
676 | </para> | |
677 | </sect2> | |
678 | ||
679 | ||
680 | <sect2> | |
681 | <title>Register Video and Input Drivers</title> | |
682 | ||
683 | <para> | |
684 | This is done at the start of the first server generation only. | |
685 | </para> | |
686 | ||
687 | <para> | |
688 | When a driver module is loaded, the loader calls its | |
689 | <function>Setup</function> function. For video drivers, this function | |
690 | calls <function>xf86AddDriver()</function> to register the driver's | |
691 | <structname>DriverRec</structname>, which contains a small set of essential | |
692 | details and driver entry points required during the early phase of | |
693 | <function>InitOutput()</function>. <function>xf86AddDriver()</function> | |
694 | adds it to the global <varname>xf86DriverList[]</varname> array. | |
695 | </para> | |
696 | ||
697 | <para> | |
698 | The <structname>DriverRec</structname> contains the driver canonical name, | |
699 | the <function>Identify()</function>, | |
700 | <function>Probe()</function> and <function>AvailableOptions()</function> | |
701 | function entry points as well as a pointer | |
702 | to the driver's module (as returned from the loader when the driver | |
703 | was loaded) and a reference count which keeps track of how many | |
704 | screens are using the driver. The entry driver entry points are | |
705 | those required prior to the driver allocating and filling in its | |
706 | <structname>ScrnInfoRec</structname>. | |
707 | </para> | |
708 | ||
709 | <para> | |
710 | For a static server, the <varname>xf86DriverList[]</varname> array is | |
711 | initialised at build time, and the loading of modules is not done. | |
712 | </para> | |
713 | ||
714 | <para> | |
715 | A similar procedure is used for input drivers. The input driver's | |
716 | <function>Setup</function> function calls | |
717 | <function>xf86AddInputDriver()</function> to register the driver's | |
718 | <structname>InputDriverRec</structname>, which contains a small set of | |
719 | essential details and driver entry points required during the early | |
720 | phase of <function>InitInput()</function>. | |
721 | <function>xf86AddInputDriver()</function> adds it to the global | |
722 | <varname>xf86InputDriverList[]</varname> array. For a static server, | |
723 | the <varname>xf86InputDriverList[]</varname> array is initialised at | |
724 | build time. | |
725 | </para> | |
726 | ||
727 | <para> | |
728 | Both the <varname>xf86DriverList[]</varname> and | |
729 | <varname>xf86InputDriverList[]</varname> arrays have been initialised | |
730 | by the end of this stage. | |
731 | </para> | |
732 | ||
733 | <para> | |
734 | Once all the drivers are registered, their | |
735 | <function>ChipIdentify()</function> functions are called. | |
736 | </para> | |
737 | ||
738 | <blockquote><para> | |
739 | <programlisting> | |
740 | void ChipIdentify(int flags); | |
741 | </programlisting> | |
742 | <blockquote><para> | |
743 | This is expected to print a message indicating the driver name, | |
744 | a short summary of what it supports, and a list of the chipset | |
745 | names that it supports. It may use the xf86PrintChipsets() helper | |
746 | to do this. | |
747 | </para></blockquote> | |
748 | </para></blockquote> | |
749 | ||
750 | <blockquote><para> | |
751 | <programlisting> | |
752 | void xf86PrintChipsets(const char *drvname, const char *drvmsg, | |
753 | SymTabPtr chips); | |
754 | </programlisting> | |
755 | <blockquote><para> | |
756 | This function provides an easy way for a driver's ChipIdentify | |
757 | function to format the identification message. | |
758 | </para></blockquote> | |
759 | </para></blockquote> | |
760 | </sect2> | |
761 | ||
762 | <sect2> | |
763 | <title>Initialise Access Control</title> | |
764 | ||
765 | <para> | |
766 | This is done at the start of the first server generation only. | |
767 | </para> | |
768 | ||
769 | <para> | |
770 | The Resource Access Control (RAC) subsystem is initialised before | |
771 | calling any driver functions that may access hardware. All generic | |
772 | bus information is probed and saved (for restoration later). All | |
773 | (shared resource) video devices are disabled at the generic bus | |
774 | level, and a probe is done to find the <quote>primary</quote> video device. These | |
775 | devices remain disabled for the next step. | |
776 | </para> | |
777 | </sect2> | |
778 | ||
779 | ||
780 | <sect2 id="probe"> | |
781 | <title>Video Driver Probe</title> | |
782 | ||
783 | <para> | |
784 | This is done at the start of the first server generation only. The | |
785 | <function>ChipProbe()</function> function of each registered video driver | |
786 | is called. | |
787 | </para> | |
788 | ||
789 | <blockquote><para> | |
790 | <programlisting> | |
791 | Bool ChipProbe(DriverPtr drv, int flags); | |
792 | </programlisting> | |
793 | <blockquote><para> | |
794 | The purpose of this is to identify all instances of hardware | |
795 | supported by the driver. The flags value is currently either 0, | |
796 | <constant>PROBE_DEFAULT</constant> or <constant>PROBE_DETECT</constant>. | |
797 | <constant>PROBE_DETECT</constant> is used if "-configure" or "-probe" | |
798 | command line arguments are given and indicates to the | |
799 | <function>Probe()</function> function that it should not configure the | |
800 | bus entities and that no xorg.conf information is available. | |
801 | </para> | |
802 | ||
803 | <para> | |
804 | The probe must find the active device sections that match the | |
805 | driver by calling <function>xf86MatchDevice()</function>. The number | |
806 | of matches found limits the maximum number of instances for this | |
807 | driver. If no matches are found, the function should return | |
808 | <constant>FALSE</constant> immediately. | |
809 | </para> | |
810 | ||
811 | <para> | |
812 | Devices that cannot be identified by using device-independent | |
813 | methods should be probed at this stage (keeping in mind that access | |
814 | to all resources that can be disabled in a device-independent way | |
815 | are disabled during this phase). The probe must be a minimal | |
816 | probe. It should just determine if there is a card present that | |
817 | the driver can drive. It should use the least intrusive probe | |
818 | methods possible. It must not do anything that is not essential, | |
819 | like probing for other details such as the amount of memory | |
820 | installed, etc. It is recommended that the | |
821 | <function>xf86MatchPciInstances()</function> helper function be used | |
822 | for identifying matching PCI devices, and similarly the | |
823 | <function>xf86MatchIsaInstances()</function> for ISA (non-PCI) devices | |
824 | (see the <link linkend="rac">RAC</link> section). These helpers also | |
825 | checks and claims the appropriate entity. When not using the | |
826 | helper, that should be done with <function>xf86CheckPciSlot()</function> | |
827 | and <function>xf86ClaimPciSlot()</function> for PCI devices and | |
828 | <function>xf86ClaimIsaSlot()</function> for ISA devices (see the | |
829 | <link linkend="rac">RAC</link> section). | |
830 | </para> | |
831 | ||
832 | <para> | |
833 | The probe must register all non-relocatable resources at this | |
834 | stage. If a resource conflict is found between exclusive resources | |
835 | the driver will fail immediately. This is usually best done with | |
836 | the <function>xf86ConfigPciEntity()</function> helper function | |
837 | for PCI and <function>xf86ConfigIsaEntity()</function> for ISA | |
838 | (see the <link linkend="rac">RAC</link> section). It is possible to | |
839 | register some entity specific functions with those helpers. When | |
840 | not using the helpers, the <function>xf86AddEntityToScreen()</function> | |
841 | <function>xf86ClaimFixedResources()</function> and | |
842 | <function>xf86SetEntityFuncs()</function> should be used instead (see | |
843 | the <link linkend="rac">RAC</link> section). | |
844 | </para> | |
845 | ||
846 | <para> | |
847 | If a chipset is specified in an active device section which the | |
848 | driver considers relevant (ie it has no driver specified, or the | |
849 | driver specified matches the driver doing the probe), the Probe | |
850 | must return <constant>FALSE</constant> if the chipset doesn't match | |
851 | one supported by the driver. | |
852 | </para> | |
853 | ||
854 | <para> | |
855 | If there are no active device sections that the driver considers | |
856 | relevant, it must return <constant>FALSE</constant>. | |
857 | </para> | |
858 | ||
859 | <para> | |
860 | Allocate a <structname>ScrnInfoRec</structname> for each active instance of the | |
861 | hardware found, and fill in the basic information, including the | |
862 | other driver entry points. This is best done with the | |
863 | <function>xf86ConfigIsaEntity()</function> helper function for ISA | |
864 | instances or <function>xf86ConfigPciEntity()</function> for PCI instances. | |
865 | These functions allocate a <structname>ScrnInfoRec</structname> for active | |
866 | entities. Optionally <function>xf86AllocateScreen()</function> | |
867 | function may also be used to allocate the <structname>ScrnInfoRec</structname>. | |
868 | Any of these functions take care of initialising fields to defined | |
869 | <quote>unused</quote> values. | |
870 | </para> | |
871 | ||
872 | <para> | |
873 | Claim the entities for each instance of the hardware found. This | |
874 | prevents other drivers from claiming the same hardware. | |
875 | </para> | |
876 | ||
877 | <para> | |
878 | Must leave hardware in the same state it found it in, and must not | |
879 | do any hardware initialisation. | |
880 | </para> | |
881 | ||
882 | <para> | |
883 | All detection can be overridden via the config file, and that | |
884 | parsed information is available to the driver at this stage. | |
885 | </para> | |
886 | ||
887 | <para> | |
888 | Returns <constant>TRUE</constant> if one or more instances are found, | |
889 | and <constant>FALSE</constant> otherwise. | |
890 | </para> | |
891 | ||
892 | </blockquote></para></blockquote> | |
893 | ||
894 | <blockquote><para> | |
895 | <programlisting> | |
896 | int xf86MatchDevice(const char *drivername, | |
897 | GDevPtr **driversectlist) | |
898 | </programlisting> | |
899 | <blockquote><para> | |
900 | This function takes the name of the driver and returns via | |
901 | <parameter>driversectlist</parameter> a list of device sections that | |
902 | match the driver name. The function return value is the number | |
903 | of matches found. If a fatal error is encountered the return | |
904 | value is <literal>-1</literal>. | |
905 | </para> | |
906 | ||
907 | <para> | |
908 | The caller should use <function>xfree()</function> to free | |
909 | <parameter>*driversectlist</parameter> when it is no longer needed. | |
910 | </para> | |
911 | ||
912 | </blockquote></para></blockquote> | |
913 | ||
914 | <blockquote><para> | |
915 | <programlisting> | |
916 | ScrnInfoPtr xf86AllocateScreen(DriverPtr drv, int flags) | |
917 | </programlisting> | |
918 | <blockquote><para> | |
919 | This function allocates a new <structname>ScrnInfoRec</structname> in the | |
920 | <varname>xf86Screens[]</varname> array. This function is normally | |
921 | called by the video driver <function>ChipProbe()</function> functions. | |
922 | The return value is a pointer to the newly allocated | |
923 | <structname>ScrnInfoRec</structname>. The <structfield>scrnIndex</structfield>, | |
924 | <structfield>origIndex</structfield>, <structfield>module</structfield> and | |
925 | <structfield>drv</structfield> fields are initialised. The reference count | |
926 | in <parameter>drv</parameter> is incremented. The storage for any | |
927 | currently allocated <quote>privates</quote> pointers is also allocated and | |
928 | the <structfield>privates</structfield> field initialised (the privates data | |
929 | is of course not allocated or initialised). This function never | |
930 | returns on failure. If the allocation fails, the server exits | |
931 | with a fatal error. The flags value is not currently used, and | |
932 | should be set to zero. | |
933 | </para></blockquote> | |
934 | </para></blockquote> | |
935 | ||
936 | <para> | |
937 | At the completion of this, a list of <structname>ScrnInfoRecs</structname> | |
938 | have been allocated in the <varname>xf86Screens[]</varname> array, and | |
939 | the associated entities and fixed resources have been claimed. The | |
940 | following <structname>ScrnInfoRec</structname> fields must be initialised at | |
941 | this point: | |
942 | ||
943 | <literallayout> | |
944 | driverVersion | |
945 | driverName | |
946 | scrnIndex(*) | |
947 | origIndex(*) | |
948 | drv(*) | |
949 | module(*) | |
950 | name | |
951 | Probe | |
952 | PreInit | |
953 | ScreenInit | |
954 | EnterVT | |
955 | LeaveVT | |
956 | numEntities | |
957 | entityList | |
958 | access | |
959 | </literallayout> | |
960 | ||
961 | <literal>(*)</literal> These are initialised when the <structname>ScrnInfoRec</structname> | |
962 | is allocated, and not explicitly by the driver. | |
963 | </para> | |
964 | ||
965 | <para> | |
966 | The following <structname>ScrnInfoRec</structname> fields must be initialised | |
967 | if the driver is going to use them: | |
968 | ||
969 | <literallayout> | |
970 | SwitchMode | |
971 | AdjustFrame | |
972 | FreeScreen | |
973 | ValidMode | |
974 | </literallayout> | |
975 | </para> | |
976 | </sect2> | |
977 | ||
978 | <sect2> | |
979 | <title>Matching Screens</title> | |
980 | ||
981 | <para> | |
982 | This is done at the start of the first server generation only. | |
983 | </para> | |
984 | ||
985 | <para> | |
986 | After the Probe phase is finished, there will be some number of | |
987 | <structname>ScrnInfoRec</structname>s. These are then matched with the active | |
988 | &k.screen; sections in the xorg.conf, and those not having an active | |
989 | &k.screen; section are deleted. If the number of remaining screens | |
990 | is 0, <function>InitOutput()</function> sets | |
991 | <structfield>screenInfo.numScreens</structfield> to <constant>0</constant> and | |
992 | returns. | |
993 | </para> | |
994 | ||
995 | <para> | |
996 | At this point the following fields of the <structname>ScrnInfoRec</structname>s | |
997 | must be initialised: | |
998 | ||
999 | <literallayout> | |
1000 | confScreen | |
1001 | </literallayout> | |
1002 | </para> | |
1003 | ||
1004 | </sect2> | |
1005 | ||
1006 | <sect2> | |
1007 | <title>Allocate non-conflicting resources</title> | |
1008 | ||
1009 | <para> | |
1010 | This is done at the start of the first server generation only. | |
1011 | </para> | |
1012 | ||
1013 | <para> | |
1014 | Before calling the drivers again, the resource information collected | |
1015 | from the Probe phase is processed. This includes checking the extent | |
1016 | of PCI resources for the probed devices, and resolving any conflicts | |
1017 | in the relocatable PCI resources. It also reports conflicts, checks | |
1018 | bus routing issues, and anything else that is needed to enable the | |
1019 | entities for the next phase. | |
1020 | </para> | |
1021 | ||
1022 | <para> | |
1023 | If any drivers registered an <function>EntityInit()</function> function | |
1024 | during the Probe phase, then they are called here. | |
1025 | </para> | |
1026 | ||
1027 | </sect2> | |
1028 | ||
1029 | <sect2> | |
1030 | <title>Sort the Screens and pre-check Monitor Information</title> | |
1031 | ||
1032 | <para> | |
1033 | This is done at the start of the first server generation only. | |
1034 | </para> | |
1035 | ||
1036 | <para> | |
1037 | The list of screens is sorted to match the ordering requested in the | |
1038 | config file. | |
1039 | </para> | |
1040 | ||
1041 | <para> | |
1042 | The list of modes for each active monitor is checked against the | |
1043 | monitor's parameters. Invalid modes are pruned. | |
1044 | </para> | |
1045 | ||
1046 | </sect2> | |
1047 | ||
1048 | <sect2> | |
1049 | <title>PreInit</title> | |
1050 | ||
1051 | <para> | |
1052 | This is done at the start of the first server generation only. | |
1053 | </para> | |
1054 | ||
1055 | <para> | |
1056 | For each <structname>ScrnInfoRec</structname>, enable access to the screens entities and call | |
1057 | the <function>ChipPreInit()</function> function. | |
1058 | </para> | |
1059 | ||
1060 | <blockquote><para> | |
1061 | <programlisting> | |
1062 | Bool ChipPreInit(ScrnInfoRec screen, int flags); | |
1063 | </programlisting> | |
1064 | <blockquote><para> | |
1065 | The purpose of this function is to find out all the information | |
1066 | required to determine if the configuration is usable, and to | |
1067 | initialise those parts of the <structname>ScrnInfoRec</structname> that | |
1068 | can be set once at the beginning of the first server generation. | |
1069 | </para> | |
1070 | ||
1071 | <para> | |
1072 | The number of entities registered for the screen should be checked | |
1073 | against the expected number (most drivers expect only one). The | |
1074 | entity information for each of them should be retrieved (with | |
1075 | <function>xf86GetEntityInfo()</function>) and checked for the correct | |
1076 | bus type and that none of the sharable resources registered during | |
1077 | the Probe phase was rejected. | |
1078 | </para> | |
1079 | ||
1080 | <para> | |
1081 | Access to resources for the entities that can be controlled in a | |
1082 | device-independent way are enabled before this function is called. | |
1083 | If the driver needs to access any resources that it has disabled | |
1084 | in an <function>EntityInit()</function> function that it registered, | |
1085 | then it may enable them here providing that it disables them before | |
1086 | this function returns. | |
1087 | </para> | |
1088 | ||
1089 | <para> | |
1090 | This includes probing for video memory, clocks, ramdac, and all | |
1091 | other HW info that is needed. It includes determining the | |
1092 | depth/bpp/visual and related info. It includes validating and | |
1093 | determining the set of video modes that will be used (and anything | |
1094 | that is required to determine that). | |
1095 | </para> | |
1096 | ||
1097 | <para> | |
1098 | This information should be determined in the least intrusive way | |
1099 | possible. The state of the HW must remain unchanged by this | |
1100 | function. Although video memory (including MMIO) may be mapped | |
1101 | within this function, it must be unmapped before returning. Driver | |
1102 | specific information should be stored in a structure hooked into | |
1103 | the <structname>ScrnInfoRec</structname>'s <structfield>driverPrivate</structfield> | |
1104 | field. Any other modules which require persistent data (ie data | |
1105 | that persists across server generations) should be initialised in | |
1106 | this function, and they should allocate a <quote>privates</quote> index to | |
1107 | hook their data into by calling | |
1108 | <function>xf86AllocateScrnInfoPrivateIndex()</function>. The <quote>privates</quote> | |
1109 | data is persistent. | |
1110 | </para> | |
1111 | ||
1112 | <para> | |
1113 | Helper functions for some of these things are provided at the | |
1114 | XFree86 common level, and the driver can choose to make use of | |
1115 | them. | |
1116 | </para> | |
1117 | ||
1118 | <para> | |
1119 | All additional resources that the screen needs must be registered | |
1120 | here. This should be done with | |
1121 | <function>xf86RegisterResources()</function>. If some of the fixed | |
1122 | resources registered in the Probe phase are not needed or not | |
1123 | decoded by the hardware when in the OPERATING server state, their | |
1124 | status should be updated with | |
1125 | <function>xf86SetOperatingState()</function>. | |
1126 | </para> | |
1127 | ||
1128 | <para> | |
1129 | Modules may be loaded at any point in this function, and all | |
1130 | modules that the driver will need must be loaded before the end | |
1131 | of this function. Either the <function>xf86LoadSubModule()</function> | |
1132 | or the <function>xf86LoadDrvSubModule()</function> function should be | |
1133 | used to load modules depending on whether a | |
1134 | <structname>ScrnInfoRec</structname> has been set up. A driver may unload | |
1135 | a module within this function if it was only needed temporarily, | |
1136 | and the <function>xf86UnloadSubModule()</function> function should be used | |
1137 | to do that. Otherwise there is no need to explicitly unload modules | |
1138 | because the loader takes care of module dependencies and will | |
1139 | unload submodules automatically if/when the driver module is | |
1140 | unloaded. | |
1141 | </para> | |
1142 | ||
1143 | <para> | |
1144 | The bulk of the <structname>ScrnInfoRec</structname> fields should be filled | |
1145 | out in this function. | |
1146 | </para> | |
1147 | ||
1148 | <para> | |
1149 | <function>ChipPreInit()</function> returns <constant>FALSE</constant> when | |
1150 | the configuration is unusable in some way (unsupported depth, no | |
1151 | valid modes, not enough video memory, etc), and <constant>TRUE</constant> | |
1152 | if it is usable. | |
1153 | </para> | |
1154 | ||
1155 | <para> | |
1156 | It is expected that if the <function>ChipPreInit()</function> function | |
1157 | returns <constant>TRUE</constant>, then the only reasons that subsequent | |
1158 | stages in the driver might fail are lack or resources (like xalloc | |
1159 | failures). All other possible reasons for failure should be | |
1160 | determined by the <function>ChipPreInit()</function> function. | |
1161 | </para></blockquote> | |
1162 | </para></blockquote> | |
1163 | ||
1164 | <para> | |
1165 | The <structname>ScrnInfoRec</structname>s for screens where the <function>ChipPreInit()</function> fails are removed. | |
1166 | If none remain, <function>InitOutput()</function> sets <structfield>screenInfo.numScreens</structfield> to <constant>0</constant> and returns. | |
1167 | </para> | |
1168 | ||
1169 | <para> | |
1170 | At this point, further fields of the <structname>ScrnInfoRec</structname>s would normally be | |
1171 | filled in. Most are not strictly mandatory, but many are required | |
1172 | by other layers and/or helper functions that the driver may choose | |
1173 | to use. The documentation for those layers and helper functions | |
1174 | indicates which they require. | |
1175 | </para> | |
1176 | ||
1177 | <para> | |
1178 | The following fields of the <structname>ScrnInfoRec</structname>s should be filled in if the | |
1179 | driver is going to use them: | |
1180 | ||
1181 | <literallayout> | |
1182 | monitor | |
1183 | display | |
1184 | depth | |
1185 | pixmapBPP | |
1186 | bitsPerPixel | |
1187 | weight (>8bpp only) | |
1188 | mask (>8bpp only) | |
1189 | offset (>8bpp only) | |
1190 | rgbBits (8bpp only) | |
1191 | gamma | |
1192 | defaultVisual | |
1193 | maxHValue | |
1194 | maxVValue | |
1195 | virtualX | |
1196 | virtualY | |
1197 | displayWidth | |
1198 | frameX0 | |
1199 | frameY0 | |
1200 | frameX1 | |
1201 | frameY1 | |
1202 | zoomLocked | |
1203 | modePool | |
1204 | modes | |
1205 | currentMode | |
1206 | progClock (TRUE if clock is programmable) | |
1207 | chipset | |
1208 | ramdac | |
1209 | clockchip | |
1210 | numClocks (if not programmable) | |
1211 | clock[] (if not programmable) | |
1212 | videoRam | |
1213 | biosBase | |
1214 | memBase | |
1215 | memClk | |
1216 | driverPrivate | |
1217 | chipID | |
1218 | chipRev | |
1219 | </literallayout> | |
1220 | </para> | |
1221 | ||
1222 | <blockquote><para> | |
1223 | <programlisting> | |
1224 | pointer xf86LoadSubModule(ScrnInfoPtr pScrn, const char *name); | |
1225 | and | |
1226 | pointer xf86LoadDrvSubModule(DriverPtr drv, const char *name); | |
1227 | </programlisting> | |
1228 | <blockquote><para> | |
1229 | Load a module that a driver depends on. This function loads the | |
1230 | module <parameter>name</parameter> as a sub module of the driver. The | |
1231 | return value is a handle identifying the new module. If the load | |
1232 | fails, the return value will be <constant>NULL</constant>. If a driver | |
1233 | needs to explicitly unload a module it has loaded in this way, | |
1234 | the return value must be saved and passed to | |
1235 | <function>xf86UnloadSubModule()</function> when unloading. | |
1236 | ||
1237 | </para></blockquote> | |
1238 | </para></blockquote> | |
1239 | ||
1240 | <blockquote><para> | |
1241 | <programlisting> | |
1242 | void xf86UnloadSubModule(pointer module); | |
1243 | </programlisting> | |
1244 | <blockquote><para> | |
1245 | Unloads the module referenced by <parameter>module</parameter>. | |
1246 | <parameter>module</parameter> should be a pointer returned previously | |
1247 | by <function>xf86LoadSubModule()</function> or | |
1248 | <function>xf86LoadDrvSubModule()</function> . | |
1249 | ||
1250 | </para></blockquote> | |
1251 | </para></blockquote> | |
1252 | </sect2> | |
1253 | ||
1254 | <sect2> | |
1255 | <title>Cleaning up Unused Drivers</title> | |
1256 | ||
1257 | <para> | |
1258 | At this point it is known which screens will be in use, and which | |
1259 | drivers are being used. Unreferenced drivers (and modules they | |
1260 | may have loaded) are unloaded here. | |
1261 | </para> | |
1262 | ||
1263 | </sect2> | |
1264 | ||
1265 | <sect2> | |
1266 | <title>Consistency Checks</title> | |
1267 | ||
1268 | <para> | |
1269 | The parameters that must be global to the server, like pixmap formats, | |
1270 | bitmap bit order, bitmap scanline unit and image byte order are | |
1271 | compared for each of the screens. If a mismatch is found, the server | |
1272 | exits with an appropriate message. | |
1273 | </para> | |
1274 | ||
1275 | </sect2> | |
1276 | ||
1277 | <sect2> | |
1278 | <title>Check if Resource Control is Needed</title> | |
1279 | ||
1280 | <para> | |
1281 | Determine if resource access control is needed. This is the case | |
1282 | if more than one screen is used. If necessary the RAC wrapper module | |
1283 | is loaded. | |
1284 | </para> | |
1285 | </sect2> | |
1286 | ||
1287 | <sect2> | |
1288 | <title>AddScreen (ScreenInit)</title> | |
1289 | ||
1290 | <para> | |
1291 | At this point, the valid screens are known. | |
1292 | <function>AddScreen()</function> is called for each of them, passing | |
1293 | <function>ChipScreenInit()</function> as the argument. | |
1294 | <function>AddScreen()</function> is a DIX function that allocates a new | |
1295 | <structfield>screenInfo.screen[]</structfield> entry (aka | |
1296 | <varname>pScreen</varname>), and does some basic initialisation of it. | |
1297 | It then calls the <function>ChipScreenInit()</function> function, with | |
1298 | <parameter>pScreen</parameter> as one of its arguments. If | |
1299 | <function>ChipScreenInit()</function> returns <constant>FALSE</constant>, | |
1300 | <function>AddScreen()</function> returns <constant>-1</constant>. Otherwise | |
1301 | it returns the index of the screen. <function>AddScreen()</function> | |
1302 | should only fail because of programming errors or failure to allocate | |
1303 | resources (like memory). All configuration problems should be | |
1304 | detected BEFORE this point. | |
1305 | </para> | |
1306 | ||
1307 | <blockquote><para> | |
1308 | <programlisting> | |
1309 | Bool ChipScreenInit(ScreenPtr pScreen, | |
1310 | int argc, char **argv); | |
1311 | </programlisting> | |
1312 | <blockquote><para> | |
1313 | This is called at the start of each server generation. | |
1314 | </para> | |
1315 | ||
1316 | <para> | |
1317 | Fill in all of <parameter>pScreen</parameter>, possibly doing some of | |
1318 | this by calling ScreenInit functions from other layers like mi, | |
1319 | framebuffers (cfb, etc), and extensions. | |
1320 | </para> | |
1321 | ||
1322 | <para> | |
1323 | Decide which operations need to be placed under resource access | |
1324 | control. The classes of operations are the frame buffer operations | |
1325 | (<constant>RAC_FB</constant>), the pointer operations | |
1326 | (<constant>RAC_CURSOR</constant>), the viewport change operations | |
1327 | (<constant>RAC_VIEWPORT</constant>) and the colormap operations | |
1328 | (<constant>RAC_COLORMAP</constant>). Any operation that requires | |
1329 | resources which might be disabled during OPERATING state should | |
1330 | be set to use RAC. This can be specified separately for memory | |
1331 | and IO resources (the <structfield>racMemFlags</structfield> and | |
1332 | <structfield>racIoFlags</structfield> fields of the <structname>ScrnInfoRec</structname> | |
1333 | respectively). | |
1334 | </para> | |
1335 | ||
1336 | <para> | |
1337 | Map any video memory or other memory regions. | |
1338 | </para> | |
1339 | ||
1340 | <para> | |
1341 | Save the video card state. Enough state must be saved so that | |
1342 | the original state can later be restored. | |
1343 | </para> | |
1344 | ||
1345 | <para> | |
1346 | Initialise the initial video mode. The <structname>ScrnInfoRec</structname>'s | |
1347 | <structfield>vtSema</structfield> field should be set to <constant>TRUE</constant> | |
1348 | just prior to changing the video hardware's state. | |
1349 | ||
1350 | </para></blockquote> | |
1351 | </para></blockquote> | |
1352 | ||
1353 | ||
1354 | <para> | |
1355 | The <function>ChipScreenInit()</function> function (or functions from other | |
1356 | layers that it calls) should allocate entries in the | |
1357 | <structname>ScreenRec</structname>'s <structfield>devPrivates</structfield> area by | |
1358 | calling <function>AllocateScreenPrivateIndex()</function> if it needs | |
1359 | per-generation storage. Since the <structname>ScreenRec</structname>'s | |
1360 | <structfield>devPrivates</structfield> information is cleared for each server | |
1361 | generation, this is the correct place to initialise it. | |
1362 | </para> | |
1363 | ||
1364 | <para> | |
1365 | After <function>AddScreen()</function> has successfully returned, the | |
1366 | following <structname>ScrnInfoRec</structname> fields are initialised: | |
1367 | ||
1368 | <literallayout> | |
1369 | pScreen | |
1370 | racMemFlags | |
1371 | racIoFlags | |
1372 | </literallayout> | |
1373 | </para> | |
1374 | ||
1375 | <para> | |
1376 | The <function>ChipScreenInit()</function> function should initialise the | |
1377 | <structfield>CloseScreen</structfield> and <structfield>SaveScreen</structfield> fields | |
1378 | of <parameter>pScreen</parameter>. The old value of | |
1379 | <structfield>pScreen->CloseScreen</structfield> should be saved as part of | |
1380 | the driver's per-screen private data, allowing it to be called from | |
1381 | <function>ChipCloseScreen()</function>. This means that the existing | |
1382 | <function>CloseScreen()</function> function is wrapped. | |
1383 | </para> | |
1384 | </sect2> | |
1385 | ||
1386 | <sect2> | |
1387 | <title>Finalising RAC Initialisation</title> | |
1388 | ||
1389 | <para> | |
1390 | After all the <function>ChipScreenInit()</function> functions have been | |
1391 | called, each screen has registered its RAC requirements. This | |
1392 | information is used to determine which shared resources are requested | |
1393 | by more than one driver and set the access functions accordingly. | |
1394 | This is done following these rules: | |
1395 | ||
1396 | <orderedlist> | |
1397 | <listitem><para> | |
1398 | The sharable resources registered by each entity are compared. | |
1399 | If a resource is registered by more than one entity the entity | |
1400 | will be marked to indicate that it needs to share this resources | |
1401 | type (IO or MEM). | |
1402 | </para></listitem> | |
1403 | ||
1404 | <listitem><para> | |
1405 | A resource marked <quote>disabled</quote> during OPERATING state will be | |
1406 | ignored entirely. | |
1407 | </para></listitem> | |
1408 | ||
1409 | <listitem><para> | |
1410 | A resource marked <quote>unused</quote> will only conflict with an overlapping | |
1411 | resource of an other entity if the second is actually in use | |
1412 | during OPERATING state. | |
1413 | </para></listitem> | |
1414 | ||
1415 | <listitem><para> | |
1416 | If an <quote>unused</quote> resource was found to conflict but the entity | |
1417 | does not use any other resource of this type the entire resource | |
1418 | type will be disabled for that entity. | |
1419 | </para></listitem> | |
1420 | </orderedlist> | |
1421 | </para> | |
1422 | ||
1423 | </sect2> | |
1424 | ||
1425 | <sect2> | |
1426 | <title>Finishing InitOutput()</title> | |
1427 | ||
1428 | <para> | |
1429 | At this point <function>InitOutput()</function> is finished, and all the | |
1430 | screens have been setup in their initial video mode. | |
1431 | </para> | |
1432 | ||
1433 | </sect2> | |
1434 | ||
1435 | <sect2> | |
1436 | <title>Mode Switching</title> | |
1437 | ||
1438 | <para> | |
1439 | When a SwitchMode event is received, <function>ChipSwitchMode()</function> | |
1440 | is called (when it exists): | |
1441 | </para> | |
1442 | ||
1443 | <blockquote><para> | |
1444 | <programlisting> | |
1445 | Bool ChipSwitchMode(int index, DisplayModePtr mode); | |
1446 | </programlisting> | |
1447 | <blockquote><para> | |
1448 | Initialises the new mode for the screen identified by | |
1449 | <parameter>index;</parameter>. The viewport may need to be adjusted | |
1450 | also. | |
1451 | ||
1452 | </para></blockquote> | |
1453 | </para></blockquote> | |
1454 | ||
1455 | </sect2> | |
1456 | ||
1457 | <sect2> | |
1458 | <title>Changing Viewport</title> | |
1459 | ||
1460 | <para> | |
1461 | When a Change Viewport event is received, | |
1462 | <function>ChipAdjustFrame()</function> is called (when it exists): | |
1463 | </para> | |
1464 | ||
1465 | <blockquote><para> | |
1466 | <programlisting> | |
1467 | void ChipAdjustFrame(int index, int x, int y); | |
1468 | </programlisting> | |
1469 | <blockquote><para> | |
1470 | Changes the viewport for the screen identified by | |
1471 | <parameter>index;</parameter>. | |
1472 | </para> | |
1473 | ||
1474 | <para> | |
1475 | It should be noted that many chipsets impose restrictions on where the | |
1476 | viewport may be placed in the virtual resolution, either for alignment | |
1477 | reasons, or to prevent the start of the viewport from being positioned | |
1478 | within a pixel (as can happen in a 24bpp mode). After calculating the | |
1479 | value the chipset's panning registers need to be set to for non-DGA | |
1480 | modes, this function should recalculate the ScrnInfoRec's | |
1481 | <structfield>frameX0</structfield>, <structfield>frameY0</structfield>, <structfield>frameX1</structfield> | |
1482 | and <structfield>frameY1</structfield> fields to correspond to that value. If | |
1483 | this is not done, switching to another mode might cause the position | |
1484 | of a hardware cursor to change. | |
1485 | ||
1486 | </para></blockquote> | |
1487 | </para></blockquote> | |
1488 | ||
1489 | </sect2> | |
1490 | ||
1491 | <sect2> | |
1492 | <title>VT Switching</title> | |
1493 | ||
1494 | <para> | |
1495 | When a VT switch event is received, <function>xf86VTSwitch()</function> | |
1496 | is called. <function>xf86VTSwitch()</function> does the following: | |
1497 | ||
1498 | <variablelist> | |
1499 | <varlistentry><term>On ENTER:</term> | |
1500 | <listitem> | |
1501 | <itemizedlist> | |
1502 | <listitem><para> | |
1503 | enable port I/O access | |
1504 | </para></listitem> | |
1505 | ||
1506 | <listitem><para> | |
1507 | save and initialise the bus/resource state | |
1508 | </para></listitem> | |
1509 | ||
1510 | <listitem><para> | |
1511 | enter the SETUP server state | |
1512 | </para></listitem> | |
1513 | ||
1514 | <listitem><para> | |
1515 | calls <function>ChipEnterVT()</function> for each screen | |
1516 | </para></listitem> | |
1517 | ||
1518 | <listitem><para> | |
1519 | enter the OPERATING server state | |
1520 | </para></listitem> | |
1521 | ||
1522 | <listitem><para> | |
1523 | validate GCs | |
1524 | </para></listitem> | |
1525 | ||
1526 | <listitem><para> | |
1527 | Restore fb from saved pixmap for each screen | |
1528 | </para></listitem> | |
1529 | ||
1530 | <listitem><para> | |
1531 | Enable all input devices | |
1532 | </para></listitem> | |
1533 | </itemizedlist> | |
1534 | </listitem> | |
1535 | </varlistentry> | |
1536 | <varlistentry> | |
1537 | <term>On LEAVE:</term> | |
1538 | <listitem> | |
1539 | <itemizedlist> | |
1540 | <listitem><para> | |
1541 | Save fb to pixmap for each screen | |
1542 | </para></listitem> | |
1543 | ||
1544 | <listitem><para> | |
1545 | validate GCs | |
1546 | </para></listitem> | |
1547 | ||
1548 | <listitem><para> | |
1549 | enter the SETUP server state | |
1550 | </para></listitem> | |
1551 | ||
1552 | <listitem><para> | |
1553 | calls <function>ChipLeaveVT()</function> for each screen | |
1554 | </para></listitem> | |
1555 | ||
1556 | <listitem><para> | |
1557 | disable all input devices | |
1558 | </para></listitem> | |
1559 | ||
1560 | <listitem><para> | |
1561 | restore bus/resource state | |
1562 | </para></listitem> | |
1563 | ||
1564 | <listitem><para> | |
1565 | disables port I/O access | |
1566 | </para></listitem> | |
1567 | </itemizedlist> | |
1568 | </listitem> | |
1569 | </varlistentry> | |
1570 | </variablelist> | |
1571 | </para> | |
1572 | ||
1573 | <blockquote><para> | |
1574 | <programlisting> | |
1575 | Bool ChipEnterVT(ScrnInfoPtr pScrn); | |
1576 | </programlisting> | |
1577 | <blockquote><para> | |
1578 | This function should initialise the current video mode and | |
1579 | initialise the viewport, turn on the HW cursor if appropriate, | |
1580 | etc. | |
1581 | </para> | |
1582 | ||
1583 | <para> | |
1584 | Should it re-save the video state before initialising the video | |
1585 | mode? | |
1586 | </para> | |
1587 | ||
1588 | </blockquote></para></blockquote> | |
1589 | ||
1590 | <blockquote><para> | |
1591 | <programlisting> | |
1592 | void ChipLeaveVT(ScrnInfoPtr pScrn); | |
1593 | </programlisting> | |
1594 | <blockquote><para> | |
1595 | This function should restore the saved video state. If | |
1596 | appropriate it should also turn off the HW cursor, and invalidate | |
1597 | any pixmap/font caches. | |
1598 | </para> | |
1599 | ||
1600 | </blockquote></para></blockquote> | |
1601 | ||
1602 | <para> | |
1603 | Optionally, <function>ChipLeaveVT()</function> may also unmap memory | |
1604 | regions. If so, <function>ChipEnterVT()</function> will need to remap | |
1605 | them. Additionally, if an aperture used to access video memory is | |
1606 | unmapped and remapped in this fashion, <function>ChipEnterVT()</function> | |
1607 | will also need to notify the framebuffer layers of the aperture's new | |
1608 | location in virtual memory. This is done with a call to the screen's | |
1609 | <function>ModifyPixmapHeader()</function> function, as follows | |
1610 | </para> | |
1611 | ||
1612 | <blockquote><para> | |
1613 | <programlisting> | |
1614 | (*pScreen->ModifyPixmapHeader)(pScrn->ppix, | |
1615 | -1, -1, -1, -1, -1, NewApertureAddress); | |
1616 | </programlisting> | |
1617 | <blockquote><para> | |
1618 | where the <structfield>ppix</structfield> field in a ScrnInfoRec | |
1619 | points to the pixmap used by the screen's | |
1620 | <function>SaveRestoreImage()</function> function to hold the screen's | |
1621 | contents while switched out. | |
1622 | </para> | |
1623 | ||
1624 | </blockquote></para></blockquote> | |
1625 | ||
1626 | <para> | |
1627 | Other layers may wrap the <function>ChipEnterVT()</function> and | |
1628 | <function>ChipLeaveVT()</function> functions if they need to take some | |
1629 | action when these events are received. | |
1630 | </para> | |
1631 | </sect2> | |
1632 | ||
1633 | <sect2> | |
1634 | <title>End of server generation</title> | |
1635 | ||
1636 | <para> | |
1637 | At the end of each server generation, the DIX layer calls | |
1638 | <function>ChipCloseScreen()</function> for each screen: | |
1639 | </para> | |
1640 | ||
1641 | <blockquote><para> | |
1642 | <programlisting> | |
1643 | Bool ChipCloseScreen(int index, ScreenPtr pScreen); | |
1644 | </programlisting> | |
1645 | <blockquote><para> | |
1646 | This function should restore the saved video state and unmap the | |
1647 | memory regions. | |
1648 | </para> | |
1649 | ||
1650 | <para> | |
1651 | It should also free per-screen data structures allocated by the | |
1652 | driver. Note that the persistent data held in the | |
1653 | <structname>ScrnInfoRec</structname>'s <structfield>driverPrivate</structfield> field | |
1654 | should not be freed here because it is needed by subsequent server | |
1655 | generations. | |
1656 | </para> | |
1657 | ||
1658 | <para> | |
1659 | The <structname>ScrnInfoRec</structname>'s <structfield>vtSema</structfield> field | |
1660 | should be set to <constant>FALSE</constant> once the video HW state | |
1661 | has been restored. | |
1662 | </para> | |
1663 | ||
1664 | <para> | |
1665 | Before freeing the per-screen driver data the saved | |
1666 | <structfield>CloseScreen</structfield> value should be restored to | |
1667 | <structfield>pScreen->CloseScreen</structfield>, and that function should | |
1668 | be called after freeing the data. | |
1669 | ||
1670 | </para></blockquote> | |
1671 | </para></blockquote> | |
1672 | </sect2> | |
1673 | </sect1> | |
1674 | ||
1675 | <sect1> | |
1676 | <title>Optional Driver Functions</title> | |
1677 | ||
1678 | <para> | |
1679 | The functions outlined here can be called from the XFree86 common layer, | |
1680 | but their presence is optional. | |
1681 | </para> | |
1682 | ||
1683 | <sect2> | |
1684 | <title>Mode Validation</title> | |
1685 | ||
1686 | <para> | |
1687 | When a mode validation helper supplied by the XFree86-common layer is | |
1688 | being used, it can be useful to provide a function to check for hw | |
1689 | specific mode constraints: | |
1690 | </para> | |
1691 | ||
1692 | <blockquote><para> | |
1693 | <programlisting> | |
1694 | ModeStatus ChipValidMode(ScrnInfoPtr pScrn, DisplayModePtr mode, | |
1695 | Bool verbose, int flags); | |
1696 | </programlisting> | |
1697 | <blockquote><para> | |
1698 | Check the passed mode for hw-specific constraints, and return the | |
1699 | appropriate status value. | |
1700 | ||
1701 | </para></blockquote> | |
1702 | </para></blockquote> | |
1703 | ||
1704 | <para> | |
1705 | This function may also modify the effective timings and clock of the passed | |
1706 | mode. These have been stored in the mode's <structfield>Crtc*</structfield> and | |
1707 | <structfield>SynthClock</structfield> elements, and have already been adjusted for | |
1708 | interlacing, doublescanning, multiscanning and clock multipliers and dividers. | |
1709 | The function should not modify any other mode field, unless it wants to modify | |
1710 | the mode timings reported to the user by <function>xf86PrintModes()</function>. | |
1711 | </para> | |
1712 | ||
1713 | <para> | |
1714 | The function is called once for every mode in the xorg.conf Monitor section | |
1715 | assigned to the screen, with <parameter>flags</parameter> set to | |
1716 | <constant>MODECHECK_INITIAL</constant>. It is subsequently called for every mode | |
1717 | in the xorg.conf Display subsection assigned to the screen, with | |
1718 | <parameter>flags</parameter> set to <constant>MODECHECK_FINAL</constant>. In the second | |
1719 | case, the mode will have successfully passed all other tests. In addition, | |
1720 | the <structname>ScrnInfoRec</structname>'s <structfield>virtualX</structfield>, | |
1721 | <structfield>virtualY</structfield> and <structfield>displayWidth</structfield> fields will have been | |
1722 | set as if the mode to be validated were to be the last mode accepted. | |
1723 | </para> | |
1724 | ||
1725 | <para> | |
1726 | In effect, calls with MODECHECK_INITIAL are intended for checks that do not | |
1727 | depend on any mode other than the one being validated, while calls with | |
1728 | MODECHECK_FINAL are intended for checks that may involve more than one mode. | |
1729 | </para> | |
1730 | </sect2> | |
1731 | ||
1732 | <sect2> | |
1733 | <title>Free screen data</title> | |
1734 | ||
1735 | <para> | |
1736 | When a screen is deleted prior to the completion of the ScreenInit | |
1737 | phase the <function>ChipFreeScreen()</function> function is called when defined. | |
1738 | </para> | |
1739 | ||
1740 | <blockquote><para> | |
1741 | <programlisting> | |
1742 | void ChipFreeScreen(ScrnInfoPtr pScrn); | |
1743 | </programlisting> | |
1744 | <blockquote><para> | |
1745 | Free any driver-allocated data that may have been allocated up to | |
1746 | and including an unsuccessful <function>ChipScreenInit()</function> | |
1747 | call. This would predominantly be data allocated by | |
1748 | <function>ChipPreInit()</function> that persists across server | |
1749 | generations. It would include the <structfield>driverPrivate</structfield>, | |
1750 | and any <quote>privates</quote> entries that modules may have allocated. | |
1751 | ||
1752 | </para></blockquote> | |
1753 | </para></blockquote> | |
1754 | ||
1755 | </sect2> | |
1756 | </sect1> | |
1757 | ||
1758 | <sect1> | |
1759 | <title>Recommended driver functions</title> | |
1760 | ||
1761 | <para> | |
1762 | The functions outlined here are for internal use by the driver only. | |
1763 | They are entirely optional, and are never accessed directly from higher | |
1764 | layers. The sample function declarations shown here are just examples. | |
1765 | The interface (if any) used is up to the driver. | |
1766 | </para> | |
1767 | ||
1768 | <sect2> | |
1769 | <title>Save</title> | |
1770 | ||
1771 | <para> | |
1772 | Save the video state. This could be called from <function>ChipScreenInit()</function> and | |
1773 | (possibly) <function>ChipEnterVT()</function>. | |
1774 | </para> | |
1775 | ||
1776 | <blockquote><para> | |
1777 | <programlisting> | |
1778 | void ChipSave(ScrnInfoPtr pScrn); | |
1779 | </programlisting> | |
1780 | <blockquote><para> | |
1781 | Saves the current state. This will only be saving pre-server | |
1782 | states or states before returning to the server. There is only | |
1783 | one current saved state per screen and it is stored in private | |
1784 | storage in the screen. | |
1785 | ||
1786 | </para></blockquote> | |
1787 | </para></blockquote> | |
1788 | </sect2> | |
1789 | ||
1790 | <sect2> | |
1791 | <title>Restore</title> | |
1792 | ||
1793 | <para> | |
1794 | Restore the original video state. This could be called from the | |
1795 | <function>ChipLeaveVT()</function> and <function>ChipCloseScreen()</function> | |
1796 | functions. | |
1797 | </para> | |
1798 | ||
1799 | <blockquote><para> | |
1800 | <programlisting> | |
1801 | void ChipRestore(ScrnInfoPtr pScrn); | |
1802 | </programlisting> | |
1803 | <blockquote><para> | |
1804 | Restores the saved state from the private storage. Usually only | |
1805 | used for restoring text modes. | |
1806 | ||
1807 | </para></blockquote> | |
1808 | </para></blockquote> | |
1809 | ||
1810 | </sect2> | |
1811 | ||
1812 | <sect2> | |
1813 | <title>Initialise Mode</title> | |
1814 | ||
1815 | <para> | |
1816 | Initialise a video mode. This could be called from the | |
1817 | <function>ChipScreenInit()</function>, <function>ChipSwitchMode()</function> | |
1818 | and <function>ChipEnterVT()</function> functions. | |
1819 | </para> | |
1820 | ||
1821 | <blockquote><para> | |
1822 | <programlisting> | |
1823 | Bool ChipModeInit(ScrnInfoPtr pScrn, DisplayModePtr mode); | |
1824 | </programlisting> | |
1825 | <blockquote><para> | |
1826 | Programs the hardware for the given video mode. | |
1827 | ||
1828 | </para></blockquote> | |
1829 | </para></blockquote> | |
1830 | ||
1831 | </sect2> | |
1832 | </sect1> | |
1833 | ||
1834 | <sect1> | |
1835 | <title>Data and Data Structures</title> | |
1836 | ||
1837 | <sect2> | |
1838 | <title>Command line data</title> | |
1839 | ||
1840 | <para> | |
1841 | Command line options are typically global, and are stored in global | |
1842 | variables. These variables are read-only and are available to drivers | |
1843 | via a function call interface. Most of these command line values are | |
1844 | processed via helper functions to ensure that they are treated consistently | |
1845 | by all drivers. The other means of access is provided for cases where | |
1846 | the supplied helper functions might not be appropriate. | |
1847 | </para> | |
1848 | ||
1849 | <para> | |
1850 | Some of them are: | |
1851 | ||
1852 | <literallayout> | |
1853 | xf86Verbose verbosity level | |
1854 | xf86Bpp -bpp from the command line | |
1855 | xf86Depth -depth from the command line | |
1856 | xf86Weight -weight from the command line | |
1857 | xf86Gamma -{r,g,b,}gamma from the command line | |
1858 | xf86FlipPixels -flippixels from the command line | |
1859 | xf86ProbeOnly -probeonly from the command line | |
1860 | defaultColorVisualClass -cc from the command line | |
1861 | </literallayout> | |
1862 | </para> | |
1863 | ||
1864 | <para> | |
1865 | If we ever do allow for screen-specific command line options, we may | |
1866 | need to rethink this. | |
1867 | </para> | |
1868 | ||
1869 | <para> | |
1870 | These can be accessed in a read-only manner by drivers with the following | |
1871 | functions: | |
1872 | </para> | |
1873 | ||
1874 | <blockquote><para> | |
1875 | <programlisting> | |
1876 | int xf86GetVerbosity(); | |
1877 | </programlisting> | |
1878 | <blockquote><para> | |
1879 | Returns the value of <varname>xf86Verbose</varname>. | |
1880 | </para></blockquote> | |
1881 | ||
1882 | </para></blockquote> | |
1883 | ||
1884 | <blockquote><para> | |
1885 | <programlisting> | |
1886 | int xf86GetDepth(); | |
1887 | </programlisting> | |
1888 | <blockquote><para> | |
1889 | Returns the <option>-depth</option> command line setting. If not | |
1890 | set on the command line, <constant>-1</constant> is returned. | |
1891 | </para></blockquote> | |
1892 | ||
1893 | </para></blockquote> | |
1894 | ||
1895 | <blockquote><para> | |
1896 | <programlisting> | |
1897 | rgb xf86GetWeight(); | |
1898 | </programlisting> | |
1899 | <blockquote><para> | |
1900 | Returns the <option>-weight</option> command line setting. If not | |
1901 | set on the command line, <literal remap="tt">{0, 0, 0}</literal> is returned. | |
1902 | </para></blockquote> | |
1903 | ||
1904 | </para></blockquote> | |
1905 | ||
1906 | <blockquote><para> | |
1907 | <programlisting> | |
1908 | Gamma xf86GetGamma(); | |
1909 | </programlisting> | |
1910 | <blockquote><para> | |
1911 | Returns the <option>-gamma</option> or <option>-rgamma</option>, | |
1912 | <option>-ggamma</option>, <option>-bgamma</option> command line settings. | |
1913 | If not set on the command line, <literal remap="tt">{0.0, 0.0, 0.0}</literal> | |
1914 | is returned. | |
1915 | </para></blockquote> | |
1916 | ||
1917 | </para></blockquote> | |
1918 | ||
1919 | <blockquote><para> | |
1920 | <programlisting> | |
1921 | Bool xf86GetFlipPixels(); | |
1922 | </programlisting> | |
1923 | <blockquote><para> | |
1924 | Returns <constant>TRUE</constant> if <option>-flippixels</option> is | |
1925 | present on the command line, and <constant>FALSE</constant> otherwise. | |
1926 | </para></blockquote> | |
1927 | ||
1928 | </para></blockquote> | |
1929 | ||
1930 | <blockquote><para> | |
1931 | <programlisting> | |
1932 | const char *xf86GetServerName(); | |
1933 | </programlisting> | |
1934 | <blockquote><para> | |
1935 | Returns the name of the X server from the command line. | |
1936 | </para></blockquote> | |
1937 | ||
1938 | </para></blockquote> | |
1939 | </sect2> | |
1940 | ||
1941 | <sect2> | |
1942 | <title>Data handling</title> | |
1943 | ||
1944 | <para> | |
1945 | Config file data contains parts that are global, and parts that are | |
1946 | Screen specific. All of it is parsed into data structures that neither | |
1947 | the drivers or most other parts of the server need to know about. | |
1948 | </para> | |
1949 | ||
1950 | <para> | |
1951 | The global data is typically not required by drivers, and as such, most | |
1952 | of it is stored in the private <structname>xf86InfoRec</structname>. | |
1953 | </para> | |
1954 | ||
1955 | <para> | |
1956 | The screen-specific data collected from the config file is stored in | |
1957 | screen, device, display, monitor-specific data structures that are separate | |
1958 | from the <varname>ScrnInfoRecs</varname>, with the appropriate elements/fields | |
1959 | hooked into the <varname>ScrnInfoRecs</varname> as required. The screen | |
1960 | config data is held in <structname>confScreenRec</structname>, device data in | |
1961 | the <structname>GDevRec</structname>, monitor data in the <structname>MonRec</structname>, | |
1962 | and display data in the <structname>DispRec</structname>. | |
1963 | </para> | |
1964 | ||
1965 | <para> | |
1966 | The XFree86 common layer's screen specific data (the actual data in use | |
1967 | for each screen) is held in the <varname>ScrnInfoRecs</varname>. As has | |
1968 | been outlined above, the <varname>ScrnInfoRecs</varname> are allocated at probe | |
1969 | time, and it is the responsibility of the Drivers' <function>Probe()</function> | |
1970 | and <function>PreInit()</function> functions to finish filling them in based | |
1971 | on both data provided on the command line and data provided from the | |
1972 | Config file. The precedence for this is: | |
1973 | ||
1974 | <blockquote><para> | |
1975 | command line -> config file -> probed/default data | |
1976 | </para></blockquote> | |
1977 | </para> | |
1978 | ||
1979 | <para> | |
1980 | For most things in this category there are helper functions that the | |
1981 | drivers can use to ensure that the above precedence is consistently | |
1982 | used. | |
1983 | </para> | |
1984 | ||
1985 | <para> | |
1986 | As well as containing screen-specific data that the XFree86 common layer | |
1987 | (including essential parts of the server infrastructure as well as helper | |
1988 | functions) needs to access, it also contains some data that drivers use | |
1989 | internally. When considering whether to add a new field to the | |
1990 | <structname>ScrnInfoRec</structname>, consider the balance between the convenience | |
1991 | of things that lots of drivers need and the size/obscurity of the | |
1992 | <structname>ScrnInfoRec</structname>. | |
1993 | </para> | |
1994 | ||
1995 | <para> | |
1996 | Per-screen driver specific data that cannot be accommodated with the | |
1997 | static <structname>ScrnInfoRec</structname> fields is held in a driver-defined | |
1998 | data structure, a pointer to which is assigned to the | |
1999 | <structname>ScrnInfoRec</structname>'s <structfield>driverPrivate</structfield> field. This | |
2000 | is per-screen data that persists across server generations (as does the | |
2001 | bulk of the static <structname>ScrnInfoRec</structname> data). It would typically | |
2002 | also include the video card's saved state. | |
2003 | </para> | |
2004 | ||
2005 | <para> | |
2006 | Per-screen data for other modules that the driver uses that is reset for each | |
2007 | server generation is hooked into the <structname>ScrnInfoRec</structname> | |
2008 | through its <structfield>privates</structfield> field. | |
2009 | </para> | |
2010 | ||
2011 | <para> | |
2012 | Once it has stabilised, the data structures and variables accessible to | |
2013 | video drivers will be documented here. In the meantime, those things | |
2014 | defined in the <filename>xf86.h</filename> and <filename>xf86str.h</filename> | |
2015 | files are visible to video drivers. Things defined in | |
2016 | <filename>xf86Priv.h</filename> and <filename>xf86Privstr.h</filename> are NOT | |
2017 | intended to be visible to video drivers, and it is an error for a driver | |
2018 | to include those files. | |
2019 | </para> | |
2020 | ||
2021 | </sect2> | |
2022 | ||
2023 | <sect2> | |
2024 | <title>Accessing global data</title> | |
2025 | ||
2026 | <para> | |
2027 | Some other global state information that the drivers may access via | |
2028 | functions is as follows: | |
2029 | </para> | |
2030 | ||
2031 | <blockquote><para> | |
2032 | <programlisting> | |
2033 | Bool xf86ServerIsExiting(); | |
2034 | </programlisting> | |
2035 | <blockquote><para> | |
2036 | Returns <constant>TRUE</constant> if the server is at the end of a | |
2037 | generation and is in the process of exiting, and | |
2038 | <constant>FALSE</constant> otherwise. | |
2039 | </para></blockquote> | |
2040 | ||
2041 | </para></blockquote> | |
2042 | ||
2043 | <blockquote><para> | |
2044 | <programlisting> | |
2045 | Bool xf86ServerIsResetting(); | |
2046 | </programlisting> | |
2047 | <blockquote><para> | |
2048 | Returns <constant>TRUE</constant> if the server is at the end of a | |
2049 | generation and is in the process of resetting, and | |
2050 | <constant>FALSE</constant> otherwise. | |
2051 | </para></blockquote> | |
2052 | ||
2053 | </para></blockquote> | |
2054 | ||
2055 | <blockquote><para> | |
2056 | <programlisting> | |
2057 | Bool xf86ServerIsInitialising(); | |
2058 | </programlisting> | |
2059 | <blockquote><para> | |
2060 | Returns <constant>TRUE</constant> if the server is at the beginning of | |
2061 | a generation and is in the process of initialising, and | |
2062 | <constant>FALSE</constant> otherwise. | |
2063 | </para></blockquote> | |
2064 | ||
2065 | </para></blockquote> | |
2066 | ||
2067 | <blockquote><para> | |
2068 | <programlisting> | |
2069 | Bool xf86ServerIsOnlyProbing(); | |
2070 | </programlisting> | |
2071 | <blockquote><para> | |
2072 | Returns <constant>TRUE</constant> if the -probeonly command line flag | |
2073 | was specified, and <constant>FALSE</constant> otherwise. | |
2074 | </para></blockquote> | |
2075 | ||
2076 | </para></blockquote> | |
2077 | ||
2078 | <blockquote><para> | |
2079 | <programlisting> | |
2080 | Bool xf86CaughtSignal(); | |
2081 | </programlisting> | |
2082 | <blockquote><para> | |
2083 | Returns <constant>TRUE</constant> if the server has caught a signal, | |
2084 | and <constant>FALSE</constant> otherwise. | |
2085 | </para></blockquote> | |
2086 | ||
2087 | </para></blockquote> | |
2088 | </sect2> | |
2089 | ||
2090 | <sect2> | |
2091 | <title>Allocating private data</title> | |
2092 | ||
2093 | <para> | |
2094 | A driver and any module it uses may allocate per-screen private storage | |
2095 | in either the <structname>ScreenRec</structname> (DIX level) or | |
2096 | <structname>ScrnInfoRec</structname> (XFree86 common layer level). | |
2097 | <structname>ScreenRec</structname> storage persists only for a single server | |
2098 | generation, and <structname>ScrnInfoRec</structname> storage persists across | |
2099 | generations for the lifetime of the server. | |
2100 | </para> | |
2101 | ||
2102 | <para> | |
2103 | The <structname>ScreenRec</structname> <structfield>devPrivates</structfield> data must be | |
2104 | reallocated/initialised at the start of each new generation. This is | |
2105 | normally done from the <function>ChipScreenInit()</function> function, and | |
2106 | Init functions for other modules that it calls. Data allocated in this | |
2107 | way should be freed by the driver's <function>ChipCloseScreen()</function> | |
2108 | functions, and Close functions for other modules that it calls. A new | |
2109 | <structfield>devPrivates</structfield> entry is allocated by calling the | |
2110 | <function>AllocateScreenPrivateIndex()</function> function. | |
2111 | </para> | |
2112 | ||
2113 | <blockquote><para> | |
2114 | <programlisting> | |
2115 | int AllocateScreenPrivateIndex(); | |
2116 | </programlisting> | |
2117 | <blockquote><para> | |
2118 | This function allocates a new element in the | |
2119 | <structfield>devPrivates</structfield> field of all currently existing | |
2120 | <literal remap="tt">ScreenRecs</literal>. The return value is the index of this | |
2121 | new element in the <structfield>devPrivates</structfield> array. The | |
2122 | <structfield>devPrivates</structfield> field is of type | |
2123 | <structname>DevUnion</structname>: | |
2124 | ||
2125 | <programlisting> | |
2126 | typedef union _DevUnion { | |
2127 | pointer ptr; | |
2128 | long val; | |
2129 | unsigned long uval; | |
2130 | pointer (*fptr)(void); | |
2131 | } DevUnion; | |
2132 | </programlisting> | |
2133 | ||
2134 | which allows the element to be used for any of the above types. | |
2135 | It is commonly used as a pointer to data that the caller allocates | |
2136 | after the new index has been allocated. | |
2137 | </para> | |
2138 | ||
2139 | <para> | |
2140 | This function will return <constant>-1</constant> when there is an | |
2141 | error allocating the new index. | |
2142 | </para> | |
2143 | ||
2144 | </blockquote> | |
2145 | </para></blockquote> | |
2146 | ||
2147 | <para> | |
2148 | The <structname>ScrnInfoRec</structname> <structfield>privates</structfield> data persists | |
2149 | for the life of the server, so only needs to be allocated once. This | |
2150 | should be done from the <function>ChipPreInit()</function> function, and Init | |
2151 | functions for other modules that it calls. Data allocated in this way | |
2152 | should be freed by the driver's <function>ChipFreeScreen()</function> functions, | |
2153 | and Free functions for other modules that it calls. A new | |
2154 | <structfield>privates</structfield> entry is allocated by calling the | |
2155 | <function>xf86AllocateScrnInfoPrivateIndex()</function> function. | |
2156 | </para> | |
2157 | ||
2158 | <blockquote><para> | |
2159 | <programlisting> | |
2160 | int xf86AllocateScrnInfoPrivateIndex(); | |
2161 | </programlisting> | |
2162 | <blockquote><para> | |
2163 | This function allocates a new element in the <structfield>privates</structfield> | |
2164 | field of all currently existing <varname>ScrnInfoRecs</varname>. | |
2165 | The return value is the index of this new element in the | |
2166 | <structfield>privates</structfield> array. The <structfield>privates</structfield> | |
2167 | field is of type <structfield>DevUnion</structfield>: | |
2168 | ||
2169 | <programlisting> | |
2170 | typedef union _DevUnion { | |
2171 | pointer ptr; | |
2172 | long val; | |
2173 | unsigned long uval; | |
2174 | pointer (*fptr)(void); | |
2175 | } DevUnion; | |
2176 | </programlisting> | |
2177 | ||
2178 | which allows the element to be used for any of the above types. | |
2179 | It is commonly used as a pointer to data that the caller allocates | |
2180 | after the new index has been allocated. | |
2181 | </para> | |
2182 | ||
2183 | <para> | |
2184 | This function will not return when there is an error allocating | |
2185 | the new index. When there is an error it will cause the server | |
2186 | to exit with a fatal error. The similar function for allocation | |
2187 | privates in the <structname>ScreenRec</structname> | |
2188 | (<function>AllocateScreenPrivateIndex()</function>) differs in this | |
2189 | respect by returning <constant>-1</constant> when the allocation fails. | |
2190 | </para> | |
2191 | ||
2192 | </blockquote> | |
2193 | </para></blockquote> | |
2194 | </sect2> | |
2195 | </sect1> | |
2196 | ||
2197 | <sect1 id="rac"> | |
2198 | <title>Keeping Track of Bus Resources</title> | |
2199 | ||
2200 | <sect2> | |
2201 | <title>Theory of Operation</title> | |
2202 | ||
2203 | <para> | |
2204 | The XFree86 common layer has knowledge of generic access control mechanisms | |
2205 | for devices on certain bus systems (currently the PCI bus) as well as | |
2206 | of methods to enable or disable access to the buses itself. Furthermore | |
2207 | it can access information on resources decoded by these devices and if | |
2208 | necessary modify it. | |
2209 | </para> | |
2210 | ||
2211 | <para> | |
2212 | When first starting the Xserver collects all this information, saves it | |
2213 | for restoration, checks it for consistency, and if necessary, corrects | |
2214 | it. Finally it disables all resources on a generic level prior to | |
2215 | calling any driver function. | |
2216 | </para> | |
2217 | ||
2218 | <para> | |
2219 | When the <function>Probe()</function> function of each driver is called the | |
2220 | device sections are matched against the devices found in the system. | |
2221 | The driver may probe devices at this stage that cannot be identified by | |
2222 | using device independent methods. Access to all resources that can be | |
2223 | controlled in a device independent way is disabled. The | |
2224 | <function>Probe()</function> function should register all non-relocatable | |
2225 | resources at this stage. If a resource conflict is found between | |
2226 | exclusive resources the driver will fail immediately. Optionally the | |
2227 | driver might specify an <function>EntityInit()</function>, | |
2228 | <function>EntityLeave()</function> and <function>EntityEnter()</function> function. | |
2229 | </para> | |
2230 | ||
2231 | <para> | |
2232 | <function>EntityInit()</function> can be used to disable any shared resources | |
2233 | that are not controlled by the generic access control functions. It is | |
2234 | called prior to the PreInit phase regardless if an entity is active or | |
2235 | not. When calling the <function>EntityInit()</function>, | |
2236 | <function>EntityEnter()</function> and <function>EntityLeave()</function> functions | |
2237 | the common level will disable access to all other entities on a generic | |
2238 | level. Since the common level has no knowledge of device specific | |
2239 | methods to disable access to resources it cannot be guaranteed that | |
2240 | certain resources are not decoded by any other entity until the | |
2241 | <function>EntityInit()</function> or <function>EntityEnter()</function> phase is | |
2242 | finished. Device drivers should therefore register all those resources | |
2243 | which they are going to disable. If these resources are never to be | |
2244 | used by any driver function they may be flagged <constant>ResInit</constant> | |
2245 | so that they can be removed from the resource list after processing all | |
2246 | <function>EntityInit()</function> functions. <function>EntityEnter()</function> | |
2247 | should disable decoding of all resources which are not registered as | |
2248 | exclusive and which are not handled by the generic access control in | |
2249 | the common level. The difference to <function>EntityInit()</function> is | |
2250 | that the latter one is only called once during lifetime of the server. | |
2251 | It can therefore be used to set up variables prior to disabling resources. | |
2252 | <function>EntityLeave()</function> should restore the original state when | |
2253 | exiting the server or switching to a different VT. It also needs to | |
2254 | disable device specific access functions if they need to be disabled on | |
2255 | server exit or VT switch. The default state is to enable them before | |
2256 | giving up the VT. | |
2257 | </para> | |
2258 | ||
2259 | <para> | |
2260 | In <function>PreInit()</function> phase each driver should check if any | |
2261 | sharable resources it has registered during <function>Probe()</function> has | |
2262 | been denied and take appropriate action which could simply be to fail. | |
2263 | If it needs to access resources it has disabled during | |
2264 | <function>EntitySetup()</function> it can do so provided it has registered | |
2265 | these and will disable them before returning from | |
2266 | <function>PreInit()</function>. This also applies to all other driver | |
2267 | functions. Several functions are provided to request resource ranges, | |
2268 | register these, correct PCI config space and add replacements for the | |
2269 | generic access functions. Resources may be marked <quote>disabled</quote> or | |
2270 | <quote>unused</quote> during OPERATING stage. Although these steps could also be | |
2271 | performed in <function>ScreenInit()</function>, this is not desirable. | |
2272 | </para> | |
2273 | ||
2274 | <para> | |
2275 | Following <function>PreInit()</function> phase the common level determines | |
2276 | if resource access control is needed. This is the case if more than | |
2277 | one screen is used. If necessary the RAC wrapper module is loaded. In | |
2278 | <function>ScreenInit()</function> the drivers can decide which operations | |
2279 | need to be placed under RAC. Available are the frame buffer operations, | |
2280 | the pointer operations and the colormap operations. Any operation that | |
2281 | requires resources which might be disabled during OPERATING state should | |
2282 | be set to use RAC. This can be specified separately for memory and IO | |
2283 | resources. | |
2284 | </para> | |
2285 | ||
2286 | <para> | |
2287 | When <function>ScreenInit()</function> phase is done the common level will | |
2288 | determine which shared resources are requested by more than one driver | |
2289 | and set the access functions accordingly. This is done following these | |
2290 | rules: | |
2291 | ||
2292 | <orderedlist> | |
2293 | <listitem><para> | |
2294 | The sharable resources registered by each entity are compared. If | |
2295 | a resource is registered by more than one entity the entity will be | |
2296 | marked to need to share this resources type (<constant>IO</constant> or | |
2297 | <constant>MEM</constant>). | |
2298 | </para></listitem> | |
2299 | ||
2300 | <listitem><para> | |
2301 | A resource marked <quote>disabled</quote> during OPERATING state will be ignored | |
2302 | entirely. | |
2303 | </para></listitem> | |
2304 | ||
2305 | <listitem><para> | |
2306 | A resource marked <quote>unused</quote> will only conflicts with an overlapping | |
2307 | resource of an other entity if the second is actually in use during | |
2308 | OPERATING state. | |
2309 | </para></listitem> | |
2310 | ||
2311 | <listitem><para> | |
2312 | If an <quote>unused</quote> resource was found to conflict however the entity | |
2313 | does not use any other resource of this type the entire resource type | |
2314 | will be disabled for that entity. | |
2315 | </para></listitem> | |
2316 | </orderedlist> | |
2317 | </para> | |
2318 | ||
2319 | <para> | |
2320 | The driver has the choice among different ways to control access to | |
2321 | certain resources: | |
2322 | ||
2323 | <orderedlist> | |
2324 | <listitem><para> | |
2325 | It can rely on the generic access functions. This is probably the | |
2326 | most common case. Here the driver only needs to register any resource | |
2327 | it is going to use. | |
2328 | </para></listitem> | |
2329 | ||
2330 | <listitem><para> | |
2331 | It can replace the generic access functions by driver specific | |
2332 | ones. This will mostly be used in cases where no generic access | |
2333 | functions are available. In this case the driver has to make sure | |
2334 | these resources are disabled when entering the <function>PreInit()</function> | |
2335 | stage. Since the replacement functions are registered in | |
2336 | <function>PreInit()</function> the driver will have to enable these | |
2337 | resources itself if it needs to access them during this state. The | |
2338 | driver can specify if the replacement functions can control memory | |
2339 | and/or I/O resources separately. | |
2340 | </para></listitem> | |
2341 | ||
2342 | <listitem><para> | |
2343 | The driver can enable resources itself when it needs them. Each | |
2344 | driver function enabling them needs to disable them before it will | |
2345 | return. This should be used if a resource which can be controlled | |
2346 | in a device dependent way is only required during SETUP state. This | |
2347 | way it can be marked <quote>unused</quote> during OPERATING state. | |
2348 | </para></listitem> | |
2349 | </orderedlist> | |
2350 | </para> | |
2351 | ||
2352 | <para> | |
2353 | A resource which is decoded during OPERATING state however never accessed | |
2354 | by the driver should be marked unused. | |
2355 | </para> | |
2356 | ||
2357 | <para> | |
2358 | Since access switching latencies are an issue during Xserver operation, | |
2359 | the common level attempts to minimize the number of entities that need | |
2360 | to be placed under RAC control. When a wrapped operation is called, | |
2361 | the <function>EnableAccess()</function> function is called before control is | |
2362 | passed on. <function>EnableAccess()</function> checks if a screen is under | |
2363 | access control. If not it just establishes bus routing and returns. | |
2364 | If the screen needs to be under access control, | |
2365 | <function>EnableAccess()</function> determines which resource types | |
2366 | (<literal remap="tt">MEM</literal>, <literal remap="tt">IO</literal>) are required. Then it tests | |
2367 | if this access is already established. If so it simply returns. If | |
2368 | not it disables the currently established access, fixes bus routing and | |
2369 | enables access to all entities registered for this screen. | |
2370 | </para> | |
2371 | ||
2372 | <para> | |
2373 | Whenever a mode switch or a VT-switch is performed the common level will | |
2374 | return to SETUP state. | |
2375 | </para> | |
2376 | </sect2> | |
2377 | ||
2378 | <sect2> | |
2379 | <title>Resource Types</title> | |
2380 | ||
2381 | <para> | |
2382 | Resource have certain properties. When registering resources each range | |
2383 | is accompanied by a flag consisting of the ORed flags of the different | |
2384 | properties the resource has. Each resource range may be classified | |
2385 | according to | |
2386 | ||
2387 | <itemizedlist> | |
2388 | <listitem><para> | |
2389 | its physical properties i.e., if it addresses | |
2390 | memory (<constant>ResMem</constant>) or | |
2391 | I/O space (<constant>ResIo</constant>), | |
2392 | </para></listitem> | |
2393 | <listitem><para> | |
2394 | if it addresses a | |
2395 | block (<constant>ResBlock</constant>) or | |
2396 | sparse (<constant>ResSparse</constant>) | |
2397 | range, | |
2398 | </para></listitem> | |
2399 | <listitem><para> | |
2400 | its access properties. | |
2401 | </para></listitem> | |
2402 | </itemizedlist> | |
2403 | </para> | |
2404 | ||
2405 | <para> | |
2406 | There are two known access properties: | |
2407 | ||
2408 | <itemizedlist> | |
2409 | <listitem><para> | |
2410 | <constant>ResExclusive</constant> | |
2411 | for resources which may not be shared with any other device and | |
2412 | </para></listitem> | |
2413 | <listitem><para> | |
2414 | <constant>ResShared</constant> | |
2415 | for resources which can be disabled and therefore can be shared. | |
2416 | </para></listitem> | |
2417 | </itemizedlist> | |
2418 | </para> | |
2419 | ||
2420 | <para> | |
2421 | If it is necessary to test a resource against any type a generic access | |
2422 | type <constant>ResAny</constant> is provided. If this is set the resource | |
2423 | will conflict with any resource of a different entity intersecting its | |
2424 | range. Further it can be specified that a resource is decoded however | |
2425 | never used during any stage (<constant>ResUnused</constant>) or during | |
2426 | OPERATING state (<constant>ResUnusedOpr</constant>). A resource only visible | |
2427 | during the init functions (ie. <function>EntityInit()</function>, | |
2428 | <function>EntityEnter()</function> and <function>EntityLeave()</function> should | |
2429 | be registered with the flag <constant>ResInit</constant>. A resource that | |
2430 | might conflict with background resource ranges may be flagged with | |
2431 | <constant>ResBios</constant>. This might be useful when registering resources | |
2432 | ranges that were assigned by the system Bios. | |
2433 | </para> | |
2434 | ||
2435 | <para> | |
2436 | Several predefined resource lists are available for VGA and 8514/A | |
2437 | resources in <filename>common/xf86Resources.h</filename>. | |
2438 | </para> | |
2439 | </sect2> | |
2440 | ||
2441 | <sect2 id="avail"> | |
2442 | <title>Available Functions</title> | |
2443 | ||
2444 | <para> | |
2445 | The functions provided for resource management are listed in their order | |
2446 | of use in the driver. | |
2447 | </para> | |
2448 | ||
2449 | <sect3> | |
2450 | <title>Probe Phase</title> | |
2451 | ||
2452 | <para> | |
2453 | In this phase each driver detects those resources it is able to drive, | |
2454 | creates an entity record for each of them, registers non-relocatable | |
2455 | resources and allocates screens and adds the resources to screens. | |
2456 | </para> | |
2457 | ||
2458 | <para> | |
2459 | Two helper functions are provided for matching device sections in the | |
2460 | xorg.conf file to the devices: | |
2461 | </para> | |
2462 | ||
2463 | <blockquote><para> | |
2464 | <programlisting> | |
2465 | int xf86MatchPciInstances(const char *driverName, int vendorID, | |
2466 | SymTabPtr chipsets, PciChipsets *PCIchipsets, | |
2467 | GDevPtr *devList, int numDevs, DriverPtr drvp, | |
2468 | int **foundEntities); | |
2469 | </programlisting> | |
2470 | <blockquote><para> | |
2471 | This function finds matches between PCI cards that a driver supports | |
2472 | and config file device sections. It is intended for use in the | |
2473 | <function>ChipProbe()</function> function of drivers for PCI cards. | |
2474 | Only probed PCI devices with a vendor ID matching | |
2475 | <parameter>vendorID</parameter> are considered. <parameter>devList</parameter> | |
2476 | and <parameter>numDevs</parameter> are typically those found from | |
2477 | calling <function>xf86MatchDevice()</function>, and represent the active | |
2478 | config file device sections relevant to the driver. | |
2479 | <parameter>PCIchipsets</parameter> is a table that provides a mapping | |
2480 | between the PCI device IDs, the driver's internal chipset tokens | |
2481 | and a list of fixed resources. | |
2482 | </para> | |
2483 | ||
2484 | <para> | |
2485 | When a device section doesn't have a <emphasis>BusID</emphasis> entry it | |
2486 | can only match the primary video device. Secondary devices are | |
2487 | only matched with device sections that have a matching | |
2488 | <emphasis>BusID</emphasis> entry. | |
2489 | </para> | |
2490 | ||
2491 | <para> | |
2492 | Once the preliminary matches have been found, a final match is | |
2493 | confirmed by checking if the chipset override, ChipID override or | |
2494 | probed PCI chipset type match one of those given in the | |
2495 | <parameter>chipsets</parameter> and <parameter>PCIchipsets</parameter> lists. | |
2496 | The <parameter>PCIchipsets</parameter> list includes a list of the PCI | |
2497 | device IDs supported by the driver. The list should be terminated | |
2498 | with an entry with PCI ID <constant>-1</constant>". The | |
2499 | <parameter>chipsets</parameter> list is a table mapping the driver's | |
2500 | internal chipset tokens to names, and should be terminated with | |
2501 | a <constant>NULL</constant> entry. Only those entries with a | |
2502 | corresponding entry in the <parameter>PCIchipsets</parameter> list are | |
2503 | considered. The order of precedence is: config file chipset, | |
2504 | config file ChipID, probed PCI device ID. | |
2505 | </para> | |
2506 | ||
2507 | <para> | |
2508 | In cases where a driver handles PCI chipsets with more than one | |
2509 | vendor ID, it may set <parameter>vendorID</parameter> to | |
2510 | <constant>0</constant>, and OR each devID in the list with (the | |
2511 | vendor ID << 16). | |
2512 | </para> | |
2513 | ||
2514 | <para> | |
2515 | Entity index numbers for confirmed matches are returned as an | |
2516 | array via <parameter>foundEntities</parameter>. The PCI information, | |
2517 | chipset token and device section for each match are found in the | |
2518 | <structname>EntityInfoRec</structname> referenced by the indices. | |
2519 | </para> | |
2520 | ||
2521 | <para> | |
2522 | The function return value is the number of confirmed matches. A | |
2523 | return value of <constant>-1</constant> indicates an internal error. | |
2524 | The returned <parameter>foundEntities</parameter> array should be freed | |
2525 | by the driver with <function>xfree()</function> when it is no longer | |
2526 | needed in cases where the return value is greater than zero. | |
2527 | </para> | |
2528 | ||
2529 | </blockquote></para></blockquote> | |
2530 | ||
2531 | <blockquote><para> | |
2532 | <programlisting> | |
2533 | int xf86MatchIsaInstances(const char *driverName, | |
2534 | SymTabPtr chipsets, IsaChipsets *ISAchipsets, | |
2535 | DriverPtr drvp, FindIsaDevProc FindIsaDevice, | |
2536 | GDevPtr *devList, int numDevs, | |
2537 | int **foundEntities); | |
2538 | </programlisting> | |
2539 | <blockquote><para> | |
2540 | This function finds matches between ISA cards that a driver supports | |
2541 | and config file device sections. It is intended for use in the | |
2542 | <function>ChipProbe()</function> function of drivers for ISA cards. | |
2543 | <parameter>devList</parameter> and <parameter>numDevs</parameter> are | |
2544 | typically those found from calling <function>xf86MatchDevice()</function>, | |
2545 | and represent the active config file device sections relevant to | |
2546 | the driver. <parameter>ISAchipsets</parameter> is a table that provides | |
2547 | a mapping between the driver's internal chipset tokens and the | |
2548 | resource classes. <parameter>FindIsaDevice</parameter> is a | |
2549 | driver-provided function that probes the hardware and returns the | |
2550 | chipset token corresponding to what was detected, and | |
2551 | <constant>-1</constant> if nothing was detected. | |
2552 | </para> | |
2553 | ||
2554 | <para> | |
2555 | If the config file device section contains a chipset entry, then | |
2556 | it is checked against the <parameter>chipsets</parameter> list. When | |
2557 | no chipset entry is present, the <parameter>FindIsaDevice</parameter> | |
2558 | function is called instead. | |
2559 | </para> | |
2560 | ||
2561 | <para> | |
2562 | Entity index numbers for confirmed matches are returned as an | |
2563 | array via <parameter>foundEntities</parameter>. The chipset token and | |
2564 | device section for each match are found in the | |
2565 | <structname>EntityInfoRec</structname> referenced by the indices. | |
2566 | </para> | |
2567 | ||
2568 | <para> | |
2569 | The function return value is the number of confirmed matches. A | |
2570 | return value of <constant>-1</constant> indicates an internal error. | |
2571 | The returned <parameter>foundEntities</parameter> array should be freed | |
2572 | by the driver with <function>xfree()</function> when it is no longer | |
2573 | needed in cases where the return value is greater than zero. | |
2574 | </para> | |
2575 | ||
2576 | </blockquote></para></blockquote> | |
2577 | ||
2578 | <para> | |
2579 | These two helper functions make use of several core functions that are | |
2580 | available at the driver level: | |
2581 | </para> | |
2582 | ||
2583 | <blockquote><para> | |
2584 | <programlisting> | |
2585 | Bool xf86ParsePciBusString(const char *busID, int *bus, | |
2586 | int *device, int *func); | |
2587 | </programlisting> | |
2588 | <blockquote><para> | |
2589 | Takes a <parameter>BusID</parameter> string, and if it is in the correct | |
2590 | format, returns the PCI <parameter>bus</parameter>, <parameter>device</parameter>, | |
2591 | <parameter>func</parameter> values that it indicates. The format of the | |
2592 | string is expected to be "PCI:bus:device:func" where each of <quote>bus</quote>, | |
2593 | <quote>device</quote> and <quote>func</quote> are decimal integers. The ":func" part may | |
2594 | be omitted, and the func value assumed to be zero, but this isn't | |
2595 | encouraged. The "PCI" prefix may also be omitted. The prefix | |
2596 | "AGP" is currently equivalent to the "PCI" prefix. If the string | |
2597 | isn't a valid PCI BusID, the return value is <constant>FALSE</constant>. | |
2598 | </para> | |
2599 | ||
2600 | </blockquote></para></blockquote> | |
2601 | ||
2602 | <blockquote><para> | |
2603 | <programlisting> | |
2604 | Bool xf86ComparePciBusString(const char *busID, int bus, | |
2605 | int device, int func); | |
2606 | </programlisting> | |
2607 | <blockquote><para> | |
2608 | Compares a <parameter>BusID</parameter> string with PCI <parameter>bus</parameter>, | |
2609 | <parameter>device</parameter>, <parameter>func</parameter> values. If they | |
2610 | match <constant>TRUE</constant> is returned, and <constant>FALSE</constant> | |
2611 | if they don't. | |
2612 | </para> | |
2613 | ||
2614 | </blockquote></para></blockquote> | |
2615 | ||
2616 | <blockquote><para> | |
2617 | <programlisting> | |
2618 | Bool xf86ParseIsaBusString(const char *busID); | |
2619 | </programlisting> | |
2620 | <blockquote><para> | |
2621 | Compares a <parameter>BusID</parameter> string with the ISA bus ID string | |
2622 | ("ISA" or "ISA:"). If they match <constant>TRUE</constant> is returned, | |
2623 | and <constant>FALSE</constant> if they don't. | |
2624 | </para> | |
2625 | ||
2626 | </blockquote></para></blockquote> | |
2627 | ||
2628 | <blockquote><para> | |
2629 | <programlisting> | |
2630 | Bool xf86CheckPciSlot(int bus, int device, int func); | |
2631 | </programlisting> | |
2632 | <blockquote><para> | |
2633 | Checks if the PCI slot <literal remap="tt">bus:device:func</literal> has been | |
2634 | claimed. If so, it returns <constant>FALSE</constant>, and otherwise | |
2635 | <constant>TRUE</constant>. | |
2636 | </para> | |
2637 | ||
2638 | </blockquote></para></blockquote> | |
2639 | ||
2640 | <blockquote><para> | |
2641 | <programlisting> | |
2642 | int xf86ClaimPciSlot(int bus, int device, int func, DriverPtr drvp, | |
2643 | int chipset, GDevPtr dev, Bool active); | |
2644 | </programlisting> | |
2645 | <blockquote><para> | |
2646 | This function is used to claim a PCI slot, allocate the associated | |
2647 | entity record and initialise their data structures. The return | |
2648 | value is the index of the newly allocated entity record, or | |
2649 | <constant>-1</constant> if the claim fails. This function should always | |
2650 | succeed if <function>xf86CheckPciSlot()</function> returned | |
2651 | <constant>TRUE</constant> for the same PCI slot. | |
2652 | </para> | |
2653 | ||
2654 | </blockquote></para></blockquote> | |
2655 | ||
2656 | <blockquote><para> | |
2657 | <programlisting> | |
2658 | Bool xf86IsPrimaryPci(void); | |
2659 | </programlisting> | |
2660 | <blockquote><para> | |
2661 | This function returns <constant>TRUE</constant> if the primary card is | |
2662 | a PCI device, and <constant>FALSE</constant> otherwise. | |
2663 | </para> | |
2664 | ||
2665 | </blockquote></para></blockquote> | |
2666 | ||
2667 | <blockquote><para> | |
2668 | <programlisting> | |
2669 | int xf86ClaimIsaSlot(DriverPtr drvp, int chipset, | |
2670 | GDevPtr dev, Bool active); | |
2671 | </programlisting> | |
2672 | <blockquote><para> | |
2673 | This allocates an entity record entity and initialise the data | |
2674 | structures. The return value is the index of the newly allocated | |
2675 | entity record. | |
2676 | </para> | |
2677 | ||
2678 | </blockquote></para></blockquote> | |
2679 | ||
2680 | <blockquote><para> | |
2681 | <programlisting> | |
2682 | Bool xf86IsPrimaryIsa(void); | |
2683 | </programlisting> | |
2684 | <blockquote><para> | |
2685 | This function returns <constant>TRUE</constant> if the primary card is | |
2686 | an ISA (non-PCI) device, and <constant>FALSE</constant> otherwise. | |
2687 | </para> | |
2688 | ||
2689 | </blockquote></para></blockquote> | |
2690 | ||
2691 | <para> | |
2692 | Two helper functions are provided to aid configuring entities: | |
2693 | </para> | |
2694 | ||
2695 | <blockquote><para> | |
2696 | <programlisting> | |
2697 | ScrnInfoPtr xf86ConfigPciEntity(ScrnInfoPtr pScrn, | |
2698 | int scrnFlag, int entityIndex, | |
2699 | PciChipsets *p_chip, | |
2700 | resList res, EntityProc init, | |
2701 | EntityProc enter, EntityProc leave, | |
2702 | pointer private); | |
2703 | ||
2704 | ScrnInfoPtr xf86ConfigIsaEntity(ScrnInfoPtr pScrn, | |
2705 | int scrnFlag, int entityIndex, | |
2706 | IsaChipsets *i_chip, | |
2707 | resList res, EntityProc init, | |
2708 | EntityProc enter, EntityProc leave, | |
2709 | pointer private); | |
2710 | </programlisting> | |
2711 | <blockquote><para> | |
2712 | These functions are used to register the non-relocatable resources | |
2713 | for an entity, and the optional entity-specific <parameter>Init</parameter>, <parameter>Enter</parameter> and | |
2714 | <parameter>Leave</parameter> functions. Usually the list of fixed resources is obtained | |
2715 | from the Isa/PciChipsets lists. However an additional list of | |
2716 | resources may be passed. Generally this is not required. | |
2717 | For active entities a <structname>ScrnInfoRec</structname> is allocated | |
2718 | if the <parameter>pScrn</parameter> argument is <constant>NULL</constant>. | |
2719 | The | |
2720 | return value is <constant>TRUE</constant> when successful. The init, enter, leave | |
2721 | functions are defined as follows: | |
2722 | ||
2723 | <blockquote><para> | |
2724 | <programlisting> | |
2725 | typedef void (*EntityProc)(int entityIndex, | |
2726 | pointer private); | |
2727 | </programlisting> | |
2728 | </para></blockquote> | |
2729 | ||
2730 | They are passed the entity index and a pointer to a private scratch | |
2731 | area. This can be set up during <function>Probe()</function> and | |
2732 | its address can be passed to | |
2733 | <function>xf86ConfigIsaEntity()</function> and | |
2734 | <function>xf86ConfigPciEntity()</function> as the last argument. | |
2735 | </para> | |
2736 | ||
2737 | </blockquote></para></blockquote> | |
2738 | ||
2739 | <para> | |
2740 | These two helper functions make use of several core functions that are | |
2741 | available at the driver level: | |
2742 | ||
2743 | <blockquote><para> | |
2744 | <programlisting> | |
2745 | void xf86ClaimFixedResources(resList list, int entityIndex); | |
2746 | </programlisting> | |
2747 | <blockquote><para> | |
2748 | This function registers the non-relocatable resources which cannot | |
2749 | be disabled and which therefore would cause the server to fail | |
2750 | immediately if they were found to conflict. It also records | |
2751 | non-relocatable but sharable resources for processing after the | |
2752 | <function>Probe()</function> phase. | |
2753 | </para> | |
2754 | ||
2755 | </blockquote></para></blockquote> | |
2756 | ||
2757 | <blockquote><para> | |
2758 | <programlisting> | |
2759 | Bool xf86SetEntityFuncs(int entityIndex, EntityProc init, | |
2760 | EntityProc enter, EntityProc leave, pointer); | |
2761 | </programlisting> | |
2762 | <blockquote><para> | |
2763 | This function registers with an entity the <parameter>init</parameter>, | |
2764 | <parameter>enter</parameter>, <parameter>leave</parameter> functions along | |
2765 | with the pointer to their private area. | |
2766 | </para> | |
2767 | ||
2768 | </blockquote></para></blockquote> | |
2769 | ||
2770 | <blockquote><para> | |
2771 | <programlisting> | |
2772 | void xf86AddEntityToScreen(ScrnInfoPtr pScrn, int entityIndex); | |
2773 | </programlisting> | |
2774 | <blockquote><para> | |
2775 | This function associates the entity referenced by | |
2776 | <parameter>entityIndex</parameter> with the screen. | |
2777 | </para> | |
2778 | ||
2779 | </blockquote></para></blockquote> | |
2780 | </para> | |
2781 | </sect3> | |
2782 | ||
2783 | <sect3> | |
2784 | <title>PreInit Phase</title> | |
2785 | ||
2786 | <para> | |
2787 | During this phase the remaining resources should be registered. | |
2788 | <function>PreInit()</function> should call <function>xf86GetEntityInfo()</function> | |
2789 | to obtain a pointer to an <structname>EntityInfoRec</structname> for each entity | |
2790 | it is able to drive and check if any resource are listed in its | |
2791 | <structfield>resources</structfield> field. If resources registered in the Probe | |
2792 | phase have been rejected in the post-Probe phase | |
2793 | (<structfield>resources</structfield> is non-<constant>NULL</constant>), then the driver should | |
2794 | decide if it can continue without using these or if it should fail. | |
2795 | </para> | |
2796 | ||
2797 | <blockquote><para> | |
2798 | <programlisting> | |
2799 | EntityInfoPtr xf86GetEntityInfo(int entityIndex); | |
2800 | </programlisting> | |
2801 | <blockquote><para> | |
2802 | This function returns a pointer to the <structname>EntityInfoRec</structname> | |
2803 | referenced by <parameter>entityIndex</parameter>. The returned | |
2804 | <structname>EntityInfoRec</structname> should be freed with | |
2805 | <function>xfree()</function> when no longer needed. | |
2806 | </para> | |
2807 | ||
2808 | </blockquote></para></blockquote> | |
2809 | ||
2810 | <para> | |
2811 | Several functions are provided to simplify resource registration: | |
2812 | <blockquote><para> | |
2813 | <programlisting> | |
2814 | Bool xf86IsEntityPrimary(int entityIndex); | |
2815 | </programlisting> | |
2816 | <blockquote><para> | |
2817 | This function returns <constant>TRUE</constant> if the entity referenced | |
2818 | by <parameter>entityIndex</parameter> is the primary display device (i.e., | |
2819 | the one initialised at boot time and used in text mode). | |
2820 | </para> | |
2821 | ||
2822 | </blockquote></para></blockquote> | |
2823 | ||
2824 | <blockquote><para> | |
2825 | <programlisting> | |
2826 | Bool xf86IsScreenPrimary(ScrnInfoPtr pScrn); | |
2827 | </programlisting> | |
2828 | <blockquote><para> | |
2829 | This function returns <constant>TRUE</constant> if the primary entity | |
2830 | is registered with the screen referenced by | |
2831 | <parameter>pScrn</parameter>. | |
2832 | </para> | |
2833 | ||
2834 | </blockquote></para></blockquote> | |
2835 | ||
2836 | <blockquote><para> | |
2837 | <programlisting> | |
2838 | pciVideoPtr xf86GetPciInfoForEntity(int entityIndex); | |
2839 | </programlisting> | |
2840 | <blockquote><para> | |
2841 | This function returns a pointer to the <structname>pciVideoRec</structname> | |
2842 | for the specified entity. If the entity is not a PCI device, | |
2843 | <constant>NULL</constant> is returned. | |
2844 | </para> | |
2845 | ||
2846 | </blockquote></para></blockquote> | |
2847 | </para> | |
2848 | ||
2849 | <para> | |
2850 | The primary function for registration of resources is: | |
2851 | <blockquote><para> | |
2852 | <programlisting> | |
2853 | resPtr xf86RegisterResources(int entityIndex, resList list, | |
2854 | int access); | |
2855 | </programlisting> | |
2856 | <blockquote><para> | |
2857 | This function tries to register the resources in | |
2858 | <parameter>list</parameter>. If list is <constant>NULL</constant> it tries | |
2859 | to determine the resources automatically. This only works for | |
2860 | entities that provide a generic way to read out the resource ranges | |
2861 | they decode. So far this is only the case for PCI devices. By | |
2862 | default the PCI resources are registered as shared | |
2863 | (<constant>ResShared</constant>) if the driver wants to set a different | |
2864 | access type it can do so by specifying the access flags in the | |
2865 | third argument. A value of <constant>0</constant> means to use the | |
2866 | default settings. If for any reason the resource broker is not | |
2867 | able to register some of the requested resources the function will | |
2868 | return a pointer to a list of the failed ones. In this case the | |
2869 | driver may be able to move the resource to different locations. | |
2870 | In case of PCI bus entities this is done by passing the list of | |
2871 | failed resources to <function>xf86ReallocatePciResources()</function>. | |
2872 | When the registration succeeds, the return value is | |
2873 | <constant>NULL</constant>. | |
2874 | </para> | |
2875 | ||
2876 | </blockquote></para></blockquote> | |
2877 | </para> | |
2878 | ||
2879 | <blockquote><para> | |
2880 | <programlisting> | |
2881 | resPtr xf86ReallocatePciResources(int entityIndex, resPtr pRes); | |
2882 | </programlisting> | |
2883 | <blockquote><para> | |
2884 | This function takes a list of PCI resources that need to be | |
2885 | reallocated and returns <constant>NULL</constant> when all relocations are | |
2886 | successful. | |
2887 | <function>xf86RegisterResources()</function> should be called again to | |
2888 | register the relocated resources with the broker. | |
2889 | If the reallocation fails, a list of the resources that could not be | |
2890 | relocated is returned. | |
2891 | </para> | |
2892 | ||
2893 | </blockquote></para></blockquote> | |
2894 | ||
2895 | <para> | |
2896 | Two functions are provided to obtain a resource range of a given type: | |
2897 | <blockquote><para> | |
2898 | <programlisting> | |
2899 | resRange xf86GetBlock(long type, memType size, | |
2900 | memType window_start, memType window_end, | |
2901 | memType align_mask, resPtr avoid); | |
2902 | </programlisting> | |
2903 | <blockquote><para> | |
2904 | This function tries to find a block range of size | |
2905 | <parameter>size</parameter> and type <parameter>type</parameter> in a window | |
2906 | bound by <parameter>window_start</parameter> and <parameter>window_end</parameter> | |
2907 | with the alignment specified in <parameter>align_mask</parameter>. | |
2908 | Optionally a list of resource ranges which should be avoided within | |
2909 | the window can be supplied. On failure a zero-length range of | |
2910 | type <constant>ResEnd</constant> will be returned. | |
2911 | </para> | |
2912 | </blockquote></para></blockquote> | |
2913 | ||
2914 | <blockquote><para> | |
2915 | <programlisting> | |
2916 | resRange xf86GetSparse(long type, memType fixed_bits, | |
2917 | memType decode_mask, memType address_mask, | |
2918 | resPtr avoid); | |
2919 | </programlisting> | |
2920 | <blockquote><para> | |
2921 | This function is like the previous one, but attempts to find a | |
2922 | sparse range instead of a block range. Here three values have to | |
2923 | be specified: the <parameter>address_mask</parameter> which marks all | |
2924 | bits of the mask part of the address, the <parameter>decode_mask</parameter> | |
2925 | which masks out the bits which are hardcoded and are therefore | |
2926 | not available for relocation and the values of the fixed bits. | |
2927 | The function tries to find a base that satisfies the given condition. | |
2928 | If the function fails it will return a zero range of type | |
2929 | <constant>ResEnd</constant>. Optionally it might be passed a list of | |
2930 | resource ranges to avoid. | |
2931 | </para> | |
2932 | ||
2933 | </blockquote></para></blockquote> | |
2934 | </para> | |
2935 | ||
2936 | <para> | |
2937 | Some PCI devices are broken in the sense that they return invalid size | |
2938 | information for a certain resource. In this case the driver can supply | |
2939 | the correct size and make sure that the resource range allocated for | |
2940 | the card is large enough to hold the address range decoded by the card. | |
2941 | The function <function>xf86FixPciResource()</function> can be used to do this: | |
2942 | <blockquote><para> | |
2943 | <programlisting> | |
2944 | Bool xf86FixPciResource(int entityIndex, unsigned int prt, | |
2945 | CARD32 alignment, long type); | |
2946 | </programlisting> | |
2947 | <blockquote><para> | |
2948 | This function fixes a PCI resource allocation. The | |
2949 | <parameter>prt</parameter> parameter contains the number of the PCI base | |
2950 | register that needs to be fixed (<constant>0-5</constant>, and | |
2951 | <constant>6</constant> for the BIOS base register). The size is | |
2952 | specified by the alignment. Since PCI resources need to span an | |
2953 | integral range of size <literal remap="tt">2ˆn</literal>, the alignm ent also | |
2954 | specifies the number of addresses that will be decoded. If the | |
2955 | driver specifies a type mask it can override the default type for | |
2956 | PCI resources which is <constant>ResShared</constant>. The resource | |
2957 | broker needs to know that to find a matching resource range. This | |
2958 | function should be called before calling | |
2959 | <function>xf86RegisterResources()</function>. The return value is | |
2960 | <constant>TRUE</constant> when the function succeeds. | |
2961 | </para> | |
2962 | ||
2963 | </blockquote></para></blockquote> | |
2964 | ||
2965 | <blockquote><para> | |
2966 | <programlisting> | |
2967 | Bool xf86CheckPciMemBase(pciVideoPtr pPci, memType base); | |
2968 | </programlisting> | |
2969 | <blockquote><para> | |
2970 | This function checks that the memory base address specified matches | |
2971 | one of the PCI base address register values for the given PCI | |
2972 | device. This is mostly used to check that an externally provided | |
2973 | base address (e.g., from a config file) matches an actual value | |
2974 | allocated to a device. | |
2975 | </para> | |
2976 | ||
2977 | </blockquote></para></blockquote> | |
2978 | </para> | |
2979 | ||
2980 | <para> | |
2981 | The driver may replace the generic access control functions for an entity. | |
2982 | This is done with the <function>xf86SetAccessFuncs()</function>: | |
2983 | <blockquote><para> | |
2984 | <programlisting> | |
2985 | void xf86SetAccessFuncs(EntityInfoPtr pEnt, | |
2986 | xf86SetAccessFuncPtr funcs, | |
2987 | xf86SetAccessFuncPtr oldFuncs); | |
2988 | </programlisting> | |
2989 | with: | |
2990 | <programlisting> | |
2991 | typedef struct { | |
2992 | xf86AccessPtr mem; | |
2993 | xf86AccessPtr io; | |
2994 | xf86AccessPtr io_mem; | |
2995 | } xf86SetAccessFuncRec, *xf86SetAccessFuncPtr; | |
2996 | </programlisting> | |
2997 | <blockquote><para> | |
2998 | The driver can pass three functions: one for I/O access, one for | |
2999 | memory access and one for combined memory and I/O access. If the | |
3000 | memory access and combined access functions are identical the | |
3001 | common level assumes that the memory access cannot be controlled | |
3002 | independently of I/O access, if the I/O access function and the | |
3003 | combined access functions are the same it is assumed that I/O can | |
3004 | not be controlled independently. If memory and I/O have to be | |
3005 | controlled together all three values should be the same. If a | |
3006 | non <constant>NULL</constant> value is passed as third argument it is | |
3007 | interpreted as an address where to store the old access record. | |
3008 | If the third argument is <constant>NULL</constant> it will be assumed | |
3009 | that the generic access should be enabled before replacing the | |
3010 | access functions. Otherwise it will be disabled. The driver may | |
3011 | enable them itself using the returned values. It should do this | |
3012 | from its replacement access functions as the generic access may | |
3013 | be disabled by the common level on certain occasions. If replacement | |
3014 | functions are specified they must control all resources of the | |
3015 | specific type registered for the entity. | |
3016 | </para> | |
3017 | ||
3018 | </blockquote></para></blockquote> | |
3019 | </para> | |
3020 | ||
3021 | <para> | |
3022 | To find out if a specific resource range conflicts with another | |
3023 | resource the <function>xf86ChkConflict()</function> function may be used: | |
3024 | <blockquote><para> | |
3025 | <programlisting> | |
3026 | memType xf86ChkConflict(resRange *rgp, int entityIndex); | |
3027 | </programlisting> | |
3028 | <blockquote><para> | |
3029 | This function checks if the resource range <parameter>rgp</parameter> of | |
3030 | for the specified entity conflicts with with another resource. | |
3031 | If a conflict is found, the address of the start of the conflict | |
3032 | is returned. The return value is zero when there is no conflict. | |
3033 | </para> | |
3034 | ||
3035 | </blockquote></para></blockquote> | |
3036 | </para> | |
3037 | ||
3038 | <para> | |
3039 | The OPERATING state properties of previously registered fixed resources | |
3040 | can be set with the <function>xf86SetOperatingState()</function> function: | |
3041 | <blockquote><para> | |
3042 | <programlisting> | |
3043 | resPtr xf86SetOperatingState(resList list, int entityIndex, | |
3044 | int mask); | |
3045 | </programlisting> | |
3046 | <blockquote><para> | |
3047 | This function is used to set the status of a resource during | |
3048 | OPERATING state. <parameter>list</parameter> holds a list to which | |
3049 | <parameter>mask</parameter> is to be applied. The parameter | |
3050 | <parameter>mask</parameter> may have the value <constant>ResUnusedOpr</constant> | |
3051 | and <constant>ResDisableOpr</constant>. The first one should be used | |
3052 | if a resource isn't used by the driver during OPERATING state | |
3053 | although it is decoded by the device, while the latter one indicates | |
3054 | that the resource is not decoded during OPERATING state. Note | |
3055 | that the resource ranges have to match those specified during | |
3056 | registration. If a range has been specified starting at | |
3057 | <literal remap="tt">A</literal> and ending at <literal remap="tt">B</literal> and suppose | |
3058 | <literal remap="tt">C</literal> us a value satisfying | |
3059 | <literal remap="tt">A < C < B</literal> one may not | |
3060 | specify the resource range <literal remap="tt">(A,B)</literal> by splitting it | |
3061 | into two ranges <literal remap="tt">(A,C)</literal> and <literal remap="tt">(C,B)</literal>. | |
3062 | </para> | |
3063 | ||
3064 | </blockquote></para></blockquote> | |
3065 | </para> | |
3066 | ||
3067 | <para> | |
3068 | The following two functions are provided for special cases: | |
3069 | <blockquote><para> | |
3070 | <programlisting> | |
3071 | void xf86RemoveEntityFromScreen(ScrnInfoPtr pScrn, int entityIndex); | |
3072 | </programlisting> | |
3073 | <blockquote><para> | |
3074 | This function may be used to remove an entity from a screen. This | |
3075 | only makes sense if a screen has more than one entity assigned or | |
3076 | the screen is to be deleted. No test is made if the screen has | |
3077 | any entities left. | |
3078 | </para> | |
3079 | ||
3080 | </blockquote></para></blockquote> | |
3081 | ||
3082 | <blockquote><para> | |
3083 | <programlisting> | |
3084 | void xf86DeallocateResourcesForEntity(int entityIndex, long type); | |
3085 | </programlisting> | |
3086 | <blockquote><para> | |
3087 | This function deallocates all resources of a given type registered | |
3088 | for a certain entity from the resource broker list. | |
3089 | </para> | |
3090 | ||
3091 | </blockquote></para></blockquote> | |
3092 | </para> | |
3093 | ||
3094 | </sect3> | |
3095 | ||
3096 | <sect3> | |
3097 | <title>ScreenInit Phase</title> | |
3098 | ||
3099 | <para> | |
3100 | All that is required in this phase is to setup the RAC flags. Note that | |
3101 | it is also permissible to set these flags up in the PreInit phase. The | |
3102 | RAC flags are held in the <structfield>racIoFlags</structfield> and <structfield>racMemFlags</structfield> fields of the | |
3103 | <structname>ScrnInfoRec</structname> for each screen. They specify which graphics operations | |
3104 | might require the use of shared resources. This can be specified | |
3105 | separately for memory and I/O resources. The available flags are defined | |
3106 | in <filename>rac/xf86RAC.h</filename>. They are: | |
3107 | ||
3108 | <variablelist> | |
3109 | <varlistentry><term><constant>RAC_FB</constant></term> | |
3110 | <listitem><para> | |
3111 | for framebuffer operations (including hw acceleration) | |
3112 | </para></listitem></varlistentry> | |
3113 | <varlistentry><term><constant>RAC_CURSOR</constant></term> | |
3114 | <listitem><para> | |
3115 | for Cursor operations | |
3116 | (??? I'm not sure if we need this for SW cursor it depends | |
3117 | on which level the sw cursor is drawn) | |
3118 | </para></listitem></varlistentry> | |
3119 | <varlistentry><term><constant>RAC_COLORMAP</constant></term> | |
3120 | <listitem><para> | |
3121 | for colormap operations | |
3122 | </para></listitem></varlistentry> | |
3123 | <varlistentry><term><constant>RAC_VIEWPORT</constant></term> | |
3124 | <listitem><para> | |
3125 | for the call to <function>ChipAdjustFrame()</function> | |
3126 | </para></listitem></varlistentry> | |
3127 | </variablelist> | |
3128 | ||
3129 | ||
3130 | The flags are ORed together. | |
3131 | </para> | |
3132 | </sect3> | |
3133 | </sect2> | |
3134 | </sect1> | |
3135 | ||
3136 | <sect1 id="options"> | |
3137 | <title>Config file <quote>Option</quote> entries</title> | |
3138 | ||
3139 | <para> | |
3140 | Option entries are permitted in most sections and subsections of the | |
3141 | config file. There are two forms of option entries: | |
3142 | ||
3143 | <variablelist> | |
3144 | <varlistentry><term>Option "option-name"</term> | |
3145 | <listitem><para> | |
3146 | A boolean option. | |
3147 | </para></listitem></varlistentry> | |
3148 | <varlistentry><term>Option "option-name" "option-value"</term> | |
3149 | <listitem><para> | |
3150 | An option with an arbitrary value. | |
3151 | </para></listitem></varlistentry> | |
3152 | </variablelist> | |
3153 | </para> | |
3154 | ||
3155 | <para> | |
3156 | The option entries are handled by the parser, and a list of the parsed | |
3157 | options is included with each of the appropriate data structures that | |
3158 | the drivers have access to. The data structures used to hold the option | |
3159 | information are opaque to the driver, and a driver must not access the | |
3160 | option data directly. Instead, the common layer provides a set of | |
3161 | functions that may be used to access, check and manipulate the option | |
3162 | data. | |
3163 | </para> | |
3164 | ||
3165 | <para> | |
3166 | First, the low level option handling functions. In most cases drivers | |
3167 | would not need to use these directly. | |
3168 | </para> | |
3169 | ||
3170 | <blockquote><para> | |
3171 | <programlisting> | |
3172 | XF86OptionPtr xf86FindOption(XF86OptionPtr options, const char *name); | |
3173 | </programlisting> | |
3174 | <blockquote><para> | |
3175 | Takes a list of options and an option name, and returns a handle | |
3176 | for the first option entry in the list matching the name. Returns | |
3177 | <constant>NULL</constant> if no match is found. | |
3178 | </para> | |
3179 | ||
3180 | </blockquote></para></blockquote> | |
3181 | ||
3182 | <blockquote><para> | |
3183 | <programlisting> | |
3184 | const char *xf86FindOptionValue(XF86OptionPtr options, const char *name); | |
3185 | </programlisting> | |
3186 | <blockquote><para> | |
3187 | Takes a list of options and an option name, and returns the value | |
3188 | associated with the first option entry in the list matching the | |
3189 | name. If the matching option has no value, an empty string | |
3190 | (<constant>""</constant>) is returned. Returns <constant>NULL</constant> | |
3191 | if no match is found. | |
3192 | </para> | |
3193 | ||
3194 | </blockquote></para></blockquote> | |
3195 | ||
3196 | <blockquote><para> | |
3197 | <programlisting> | |
3198 | void xf86MarkOptionUsed(XF86OptionPtr option); | |
3199 | </programlisting> | |
3200 | <blockquote><para> | |
3201 | Takes a handle for an option, and marks that option as used. | |
3202 | </para> | |
3203 | ||
3204 | </blockquote></para></blockquote> | |
3205 | ||
3206 | <blockquote><para> | |
3207 | <programlisting> | |
3208 | void xf86MarkOptionUsedByName(XF86OptionPtr options, const char *name); | |
3209 | </programlisting> | |
3210 | <blockquote><para> | |
3211 | Takes a list of options and an option name and marks the first | |
3212 | option entry in the list matching the name as used. | |
3213 | </para> | |
3214 | ||
3215 | </blockquote></para></blockquote> | |
3216 | ||
3217 | <para> | |
3218 | Next, the higher level functions that most drivers would use. | |
3219 | </para> | |
3220 | <blockquote><para> | |
3221 | <programlisting> | |
3222 | void xf86CollectOptions(ScrnInfoPtr pScrn, XF86OptionPtr extraOpts); | |
3223 | </programlisting> | |
3224 | <blockquote><para> | |
3225 | Collect the options from each of the config file sections used by | |
3226 | the screen (<parameter>pScrn</parameter>) and return the merged list as | |
3227 | <structfield>pScrn->options</structfield>. This function requires that | |
3228 | <structfield>pScrn->confScreen</structfield>, <structfield>pScrn->display</structfield>, | |
3229 | <structfield>pScrn->monitor</structfield>, | |
3230 | <structfield>pScrn->numEntities</structfield>, and | |
3231 | <structfield>pScrn->entityList</structfield> are initialised. | |
3232 | <parameter>extraOpts</parameter> may optionally be set to an additional | |
3233 | list of options to be combined with the others. The order of | |
3234 | precedence for options is <parameter>extraOpts</parameter>, display, | |
3235 | confScreen, monitor, device. | |
3236 | </para> | |
3237 | ||
3238 | </blockquote></para></blockquote> | |
3239 | ||
3240 | <blockquote><para> | |
3241 | <programlisting> | |
3242 | void xf86ProcessOptions(int scrnIndex, XF86OptionPtr options, | |
3243 | OptionInfoPtr optinfo); | |
3244 | </programlisting> | |
3245 | <blockquote><para> | |
3246 | Processes a list of options according to the information in the | |
3247 | array of <structname>OptionInfoRecs</structname> (<parameter>optinfo</parameter>). | |
3248 | The resulting information is stored in the <structfield>value</structfield> | |
3249 | fields of the appropriate <parameter>optinfo</parameter> entries. The | |
3250 | <structfield>found</structfield> fields are set to <constant>TRUE</constant> | |
3251 | when an option with a value of the correct type if found, and | |
3252 | <constant>FALSE</constant> otherwise. The <structfield>type</structfield> field | |
3253 | is used to determine the expected value type for each option. | |
3254 | Each option in the list of options for which there is a name match | |
3255 | (but not necessarily a value type match) is marked as used. | |
3256 | Warning messages are printed when option values don't match the | |
3257 | types specified in the optinfo data. | |
3258 | </para> | |
3259 | ||
3260 | <para> | |
3261 | NOTE: If this function is called before a driver's screen number | |
3262 | is known (e.g., from the <function>ChipProbe()</function> function) a | |
3263 | <parameter>scrnIndex</parameter> value of <constant>-1</constant> should be | |
3264 | used. | |
3265 | </para> | |
3266 | ||
3267 | <para> | |
3268 | NOTE 2: Given that this function stores into the | |
3269 | <literal remap="tt">OptionInfoRecs</literal> pointed to by <parameter>optinfo</parameter>, | |
3270 | the caller should ensure the <literal remap="tt">OptionInfoRecs</literal> are | |
3271 | (re-)initialised before the call, especially if the caller expects | |
3272 | to use the predefined option values as defaults. | |
3273 | </para> | |
3274 | ||
3275 | <para> | |
3276 | The <structname>OptionInfoRec</structname> is defined as follows: | |
3277 | ||
3278 | <programlisting> | |
3279 | typedef struct { | |
3280 | double freq; | |
3281 | int units; | |
3282 | } OptFrequency; | |
3283 | ||
3284 | typedef union { | |
3285 | unsigned long num; | |
3286 | char * str; | |
3287 | double realnum; | |
3288 | Bool bool; | |
3289 | OptFrequency freq; | |
3290 | } ValueUnion; | |
3291 | ||
3292 | typedef enum { | |
3293 | OPTV_NONE = 0, | |
3294 | OPTV_INTEGER, | |
3295 | OPTV_STRING, /* a non-empty string */ | |
3296 | OPTV_ANYSTR, /* Any string, including an empty one */ | |
3297 | OPTV_REAL, | |
3298 | OPTV_BOOLEAN, | |
3299 | OPTV_PERCENT, | |
3300 | OPTV_FREQ | |
3301 | } OptionValueType; | |
3302 | ||
3303 | typedef enum { | |
3304 | OPTUNITS_HZ = 1, | |
3305 | OPTUNITS_KHZ, | |
3306 | OPTUNITS_MHZ | |
3307 | } OptFreqUnits; | |
3308 | ||
3309 | typedef struct { | |
3310 | int token; | |
3311 | const char* name; | |
3312 | OptionValueType type; | |
3313 | ValueUnion value; | |
3314 | Bool found; | |
3315 | } OptionInfoRec, *OptionInfoPtr; | |
3316 | </programlisting> | |
3317 | </para> | |
3318 | <para> | |
3319 | <constant>OPTV_FREQ</constant> can be used for options values that are | |
3320 | frequencies. These values are a floating point number with an | |
3321 | optional unit name appended. The unit name can be one of "Hz", | |
3322 | "kHz", "k", "MHz", "M". The multiplier associated with the unit | |
3323 | is stored in <structfield>freq.units</structfield>, and the scaled frequency | |
3324 | is stored in <structfield>freq.freq</structfield>. When no unit is specified, | |
3325 | <structfield>freq.units</structfield> is set to <constant>0</constant>, and | |
3326 | <structfield>freq.freq</structfield> is unscaled. | |
3327 | </para> | |
3328 | ||
3329 | <para> | |
3330 | <constant>OPTV_PERCENT</constant> can be used for option values that are | |
3331 | specified in percent (e.g. "20%"). These values are a floating point | |
3332 | number with a percent sign appended. If the percent sign is missing, | |
3333 | the parser will fail to match the value. | |
3334 | </para> | |
3335 | ||
3336 | <para> | |
3337 | Typical usage is to setup an array of | |
3338 | <structname>OptionInfoRec</structname>s with all fields initialised. | |
3339 | The <structfield>value</structfield> and <structfield>found</structfield> fields get | |
3340 | set by <function>xf86ProcessOptions()</function>. For cases where the | |
3341 | value parsing is more complex, the driver should specify | |
3342 | <constant>OPTV_STRING</constant>, and parse the string itself. An | |
3343 | example of using this option handling is included in the | |
3344 | <link linkend="sample">Sample Driver</link> section. | |
3345 | </para> | |
3346 | ||
3347 | </blockquote></para></blockquote> | |
3348 | ||
3349 | <blockquote><para> | |
3350 | <programlisting> | |
3351 | void xf86ShowUnusedOptions(int scrnIndex, XF86OptionPtr options); | |
3352 | </programlisting> | |
3353 | <blockquote><para> | |
3354 | Prints out warning messages for each option in the list of options | |
3355 | that isn't marked as used. This is intended to show options that | |
3356 | the driver hasn't recognised. It would normally be called near | |
3357 | the end of the <function>ChipScreenInit()</function> function, but only | |
3358 | when <code>serverGeneration == 1</code> | |
3359 | </para> | |
3360 | </blockquote></para></blockquote> | |
3361 | ||
3362 | <blockquote><para> | |
3363 | <programlisting> | |
3364 | OptionInfoPtr xf86TokenToOptinfo(const OptionInfoRec *table, | |
3365 | int token); | |
3366 | </programlisting> | |
3367 | <blockquote><para> | |
3368 | Returns a pointer to the <structname>OptionInfoRec</structname> in | |
3369 | <parameter>table</parameter> with a token field matching | |
3370 | <parameter>token</parameter>. Returns <constant>NULL</constant> if no match | |
3371 | is found. | |
3372 | </para> | |
3373 | ||
3374 | </blockquote></para></blockquote> | |
3375 | ||
3376 | <blockquote><para> | |
3377 | <programlisting> | |
3378 | Bool xf86IsOptionSet(const OptionInfoRec *table, int token); | |
3379 | </programlisting> | |
3380 | <blockquote><para> | |
3381 | Returns the <literal remap="tt">found</literal> field of the | |
3382 | <structname>OptionInfoRec</structname> in <parameter>table</parameter> with a | |
3383 | <structfield>token</structfield> field matching <parameter>token</parameter>. This | |
3384 | can be used for options of all types. Note that for options of | |
3385 | type <constant>OPTV_BOOLEAN</constant>, it isn't sufficient to check | |
3386 | this to determine the value of the option. Returns | |
3387 | <constant>FALSE</constant> if no match is found. | |
3388 | </para> | |
3389 | ||
3390 | </blockquote></para></blockquote> | |
3391 | ||
3392 | <blockquote><para> | |
3393 | <programlisting> | |
3394 | char *xf86GetOptValString(const OptionInfoRec *table, int token); | |
3395 | </programlisting> | |
3396 | <blockquote><para> | |
3397 | Returns the <structfield>value.str</structfield> field of the | |
3398 | <structname>OptionInfoRec</structname> in <parameter>table</parameter> with a | |
3399 | token field matching <parameter>token</parameter>. Returns | |
3400 | <constant>NULL</constant> if no match is found. | |
3401 | </para> | |
3402 | ||
3403 | </blockquote></para></blockquote> | |
3404 | ||
3405 | <blockquote><para> | |
3406 | <programlisting> | |
3407 | Bool xf86GetOptValInteger(const OptionInfoRec *table, int token, | |
3408 | ||
3409 | int *value); | |
3410 | </programlisting> | |
3411 | <blockquote><para> | |
3412 | Returns via <parameter>*value</parameter> the <structfield>value.num</structfield> | |
3413 | field of the <structname>OptionInfoRec</structname> in <parameter>table</parameter> | |
3414 | with a <structfield>token</structfield> field matching <parameter>token</parameter>. | |
3415 | <parameter>*value</parameter> is only changed when a match is found so | |
3416 | it can be safely initialised with a default prior to calling this | |
3417 | function. The function return value is as for | |
3418 | <function>xf86IsOptionSet()</function>. | |
3419 | </para> | |
3420 | ||
3421 | </blockquote></para></blockquote> | |
3422 | ||
3423 | <blockquote><para> | |
3424 | <programlisting> | |
3425 | Bool xf86GetOptValULong(const OptionInfoRec *table, int token, | |
3426 | unsigned long *value); | |
3427 | </programlisting> | |
3428 | <blockquote><para> | |
3429 | Like <function>xf86GetOptValInteger()</function>, except the value is | |
3430 | treated as an <type>unsigned long</type>. | |
3431 | </para> | |
3432 | ||
3433 | </blockquote></para></blockquote> | |
3434 | ||
3435 | <blockquote><para> | |
3436 | <programlisting> | |
3437 | Bool xf86GetOptValReal(const OptionInfoRec *table, int token, | |
3438 | double *value); | |
3439 | </programlisting> | |
3440 | <blockquote><para> | |
3441 | Like <function>xf86GetOptValInteger()</function>, except that | |
3442 | <structfield>value.realnum</structfield> is used. | |
3443 | </para> | |
3444 | ||
3445 | </blockquote></para></blockquote> | |
3446 | ||
3447 | <blockquote><para> | |
3448 | <programlisting> | |
3449 | Bool xf86GetOptValFreq(const OptionInfoRec *table, int token, | |
3450 | OptFreqUnits expectedUnits, double *value); | |
3451 | </programlisting> | |
3452 | <blockquote><para> | |
3453 | Like <function>xf86GetOptValInteger()</function>, except that the | |
3454 | <structfield>value.freq</structfield> data is returned. The frequency value | |
3455 | is scaled to the units indicated by <parameter>expectedUnits</parameter>. | |
3456 | The scaling is exact when the units were specified explicitly in | |
3457 | the option's value. Otherwise, the <parameter>expectedUnits</parameter> | |
3458 | field is used as a hint when doing the scaling. In this case, | |
3459 | values larger than <constant>1000</constant> are assumed to have be | |
3460 | specified in the next smallest units. For example, if the Option | |
3461 | value is "10000" and expectedUnits is <constant>OPTUNITS_MHZ</constant>, | |
3462 | the value returned is <constant>10</constant>. | |
3463 | </para> | |
3464 | ||
3465 | </blockquote></para></blockquote> | |
3466 | ||
3467 | <blockquote><para> | |
3468 | <programlisting> | |
3469 | Bool xf86GetOptValBool(const OptionInfoRec *table, int token, Bool *value); | |
3470 | </programlisting> | |
3471 | <blockquote><para> | |
3472 | This function is used to check boolean options | |
3473 | (<constant>OPTV_BOOLEAN</constant>). If the function return value is | |
3474 | <constant>FALSE</constant>, it means the option wasn't set. Otherwise | |
3475 | <parameter>*value</parameter> is set to the boolean value indicated by | |
3476 | the option's value. No option <parameter>value</parameter> is interpreted | |
3477 | as <constant>TRUE</constant>. Option values meaning <constant>TRUE</constant> | |
3478 | are "1", "yes", "on", "true", and option values meaning | |
3479 | <constant>FALSE</constant> are "0", "no", "off", "false". Option names | |
3480 | both with the "no" prefix in their names, and with that prefix | |
3481 | removed are also checked and handled in the obvious way. | |
3482 | <parameter>*value</parameter> is not changed when the option isn't present. | |
3483 | It should normally be set to a default value before calling this | |
3484 | function. | |
3485 | </para> | |
3486 | ||
3487 | </blockquote></para></blockquote> | |
3488 | ||
3489 | <blockquote><para> | |
3490 | <programlisting> | |
3491 | Bool xf86ReturnOptValBool(const OptionInfoRec *table, int token, Bool def); | |
3492 | </programlisting> | |
3493 | <blockquote><para> | |
3494 | This function is used to check boolean options | |
3495 | (<constant>OPTV_BOOLEAN</constant>). If the option is set, its value | |
3496 | is returned. If the options is not set, the default value specified | |
3497 | by <parameter>def</parameter> is returned. The option interpretation is | |
3498 | the same as for <function>xf86GetOptValBool()</function>. | |
3499 | </para> | |
3500 | ||
3501 | </blockquote></para></blockquote> | |
3502 | ||
3503 | <blockquote><para> | |
3504 | <programlisting> | |
3505 | int xf86NameCmp(const char *s1, const char *s2); | |
3506 | </programlisting> | |
3507 | <blockquote><para> | |
3508 | This function should be used when comparing strings from the config | |
3509 | file with expected values. It works like <function>strcmp()</function>, | |
3510 | but is not case sensitive and space, tab, and <quote><literal>_</literal></quote> characters | |
3511 | are ignored in the comparison. The use of this function isn't | |
3512 | restricted to parsing option values. It may be used anywhere | |
3513 | where this functionality required. | |
3514 | </para> | |
3515 | ||
3516 | </blockquote></para></blockquote> | |
3517 | </sect1> | |
3518 | ||
3519 | <sect1> | |
3520 | <title>Modules, Drivers, Include Files and Interface Issues</title> | |
3521 | ||
3522 | <para> | |
3523 | NOTE: this section is incomplete. | |
3524 | </para> | |
3525 | ||
3526 | ||
3527 | <sect2> | |
3528 | <title>Include files</title> | |
3529 | ||
3530 | <para> | |
3531 | The following include files are typically required by video drivers: | |
3532 | ||
3533 | <blockquote><para> | |
3534 | All drivers should include these: | |
3535 | <literallayout><filename> | |
3536 | "xf86.h" | |
3537 | "xf86_OSproc.h" | |
3538 | "xf86_ansic.h" | |
3539 | "xf86Resources.h" | |
3540 | </filename></literallayout> | |
3541 | Wherever inb/outb (and related things) are used the following should be | |
3542 | included: | |
3543 | <literallayout><filename> | |
3544 | "compiler.h" | |
3545 | </filename></literallayout> | |
3546 | Note: in drivers, this must be included after <filename>"xf86_ansic.h"</filename>. | |
3547 | </para> | |
3548 | ||
3549 | <para> | |
3550 | Drivers that need to access the PCI config space need this: | |
3551 | <literallayout><filename> | |
3552 | "xf86Pci.h" | |
3553 | </filename></literallayout> | |
3554 | </para> | |
3555 | ||
3556 | <para> | |
3557 | Drivers that initialise a SW cursor need this: | |
3558 | <literallayout><filename> | |
3559 | "mipointer.h" | |
3560 | </filename></literallayout> | |
3561 | </para> | |
3562 | ||
3563 | <para> | |
3564 | All drivers using the mi colourmap code need this: | |
3565 | <literallayout><filename> | |
3566 | "micmap.h" | |
3567 | </filename></literallayout> | |
3568 | </para> | |
3569 | ||
3570 | <para> | |
3571 | If a driver uses the vgahw module, it needs this: | |
3572 | <literallayout><filename> | |
3573 | "vgaHW.h" | |
3574 | </filename></literallayout> | |
3575 | </para> | |
3576 | ||
3577 | <para> | |
3578 | Drivers supporting VGA or Hercules monochrome screens need: | |
3579 | <literallayout><filename> | |
3580 | "xf1bpp.h" | |
3581 | </filename></literallayout> | |
3582 | </para> | |
3583 | ||
3584 | <para> | |
3585 | Drivers supporting VGA or EGC 16-colour screens need: | |
3586 | <literallayout><filename> | |
3587 | "xf4bpp.h" | |
3588 | </filename></literallayout> | |
3589 | </para> | |
3590 | ||
3591 | <para> | |
3592 | Drivers using cfb need: | |
3593 | <programlisting> | |
3594 | #define PSZ 8 | |
3595 | #include "cfb.h" | |
3596 | #undef PSZ | |
3597 | </programlisting> | |
3598 | </para> | |
3599 | ||
3600 | <para> | |
3601 | Drivers supporting bpp 16, 24 or 32 with cfb need one or more of: | |
3602 | <literallayout><filename> | |
3603 | "cfb16.h" | |
3604 | "cfb24.h" | |
3605 | "cfb32.h" | |
3606 | </filename></literallayout> | |
3607 | </para> | |
3608 | ||
3609 | <para> | |
3610 | If a driver uses the fb manager, it needs this: | |
3611 | <literallayout><filename> | |
3612 | "xf86fbman.h" | |
3613 | </filename></literallayout> | |
3614 | </para> | |
3615 | </blockquote> | |
3616 | </para> | |
3617 | ||
3618 | <para> | |
3619 | Non-driver modules should include <filename>"xf86_ansic.h"</filename> to get the correct | |
3620 | wrapping of ANSI C/libc functions. | |
3621 | </para> | |
3622 | ||
3623 | <para> | |
3624 | All modules must NOT include any system include files, or the following: | |
3625 | ||
3626 | <literallayout><filename> | |
3627 | "xf86Priv.h" | |
3628 | "xf86Privstr.h" | |
3629 | "xf86_OSlib.h" | |
3630 | "Xos.h" | |
3631 | </filename></literallayout> | |
3632 | </para> | |
3633 | ||
3634 | <para> | |
3635 | In addition, "xf86_libc.h" must not be included explicitly. It is | |
3636 | included implicitly by "xf86_ansic.h". | |
3637 | </para> | |
3638 | ||
3639 | </sect2> | |
3640 | </sect1> | |
3641 | ||
3642 | <sect1> | |
3643 | <title>Offscreen Memory Manager</title> | |
3644 | ||
3645 | <para> | |
3646 | Management of offscreen video memory may be handled by the XFree86 | |
3647 | framebuffer manager. Once the offscreen memory manager is running, | |
3648 | drivers or extensions may allocate, free or resize areas of offscreen | |
3649 | video memory using the following functions (definitions taken from | |
3650 | <filename>xf86fbman.h</filename>): | |
3651 | ||
3652 | <programlisting> | |
3653 | typedef struct _FBArea { | |
3654 | ScreenPtr pScreen; | |
3655 | BoxRec box; | |
3656 | int granularity; | |
3657 | void (*MoveAreaCallback)(struct _FBArea*, struct _FBArea*) | |
3658 | void (*RemoveAreaCallback)(struct _FBArea*) | |
3659 | DevUnion devPrivate; | |
3660 | } FBArea, *FBAreaPtr; | |
3661 | ||
3662 | typedef void (*MoveAreaCallbackProcPtr)(FBAreaPtr from, FBAreaPtr to) | |
3663 | typedef void (*RemoveAreaCallbackProcPtr)(FBAreaPtr) | |
3664 | ||
3665 | FBAreaPtr xf86AllocateOffscreenArea ( | |
3666 | ScreenPtr pScreen, | |
3667 | int width, int height, | |
3668 | int granularity, | |
3669 | MoveAreaCallbackProcPtr MoveAreaCallback, | |
3670 | RemoveAreaCallbackProcPtr RemoveAreaCallback, | |
3671 | pointer privData | |
3672 | ) | |
3673 | ||
3674 | void xf86FreeOffscreenArea (FBAreaPtr area) | |
3675 | ||
3676 | Bool xf86ResizeOffscreenArea ( | |
3677 | FBAreaPtr area | |
3678 | int w, int h | |
3679 | ) | |
3680 | </programlisting> | |
3681 | </para> | |
3682 | ||
3683 | <para> | |
3684 | The function: | |
3685 | <programlisting> | |
3686 | Bool xf86FBManagerRunning(ScreenPtr pScreen); | |
3687 | </programlisting> | |
3688 | ||
3689 | can be used by an extension to check if the driver has initialized | |
3690 | the memory manager. The manager is not available if this returns | |
3691 | <constant>FALSE</constant> and the functions above will all fail. | |
3692 | </para> | |
3693 | ||
3694 | ||
3695 | <para> | |
3696 | <function>xf86AllocateOffscreenArea()</function> can be used to request a | |
3697 | rectangle of dimensions <parameter>width</parameter> × <parameter>height</parameter> | |
3698 | (in pixels) from unused offscreen memory. <parameter>granularity</parameter> | |
3699 | specifies that the leftmost edge of the rectangle must lie on some | |
3700 | multiple of <parameter>granularity</parameter> pixels. A granularity of zero | |
3701 | means the same thing as a granularity of one - no alignment preference. | |
3702 | A <parameter>MoveAreaCallback</parameter> can be provided to notify the requester | |
3703 | when the offscreen area is moved. If no <parameter>MoveAreaCallback</parameter> | |
3704 | is supplied then the area is considered to be immovable. The | |
3705 | <parameter>privData</parameter> field will be stored in the manager's internal | |
3706 | structure for that allocated area and will be returned to the requester | |
3707 | in the <parameter>FBArea</parameter> passed via the | |
3708 | <parameter>MoveAreaCallback</parameter>. An optional | |
3709 | <parameter>RemoveAreaCallback</parameter> is provided. If the driver provides | |
3710 | this it indicates that the area should be allocated with a lower priority. | |
3711 | Such an area may be removed when a higher priority request (one that | |
3712 | doesn't have a <parameter>RemoveAreaCallback</parameter>) is made. When this | |
3713 | function is called, the driver will have an opportunity to do whatever | |
3714 | cleanup it needs to do to deal with the loss of the area, but it must | |
3715 | finish its cleanup before the function exits since the offscreen memory | |
3716 | manager will free the area immediately after. | |
3717 | </para> | |
3718 | ||
3719 | <para> | |
3720 | <function>xf86AllocateOffscreenArea()</function> returns <constant>NULL</constant> | |
3721 | if it was unable to allocate the requested area. When no longer needed, | |
3722 | areas should be freed with <function>xf86FreeOffscreenArea()</function>. | |
3723 | </para> | |
3724 | ||
3725 | <para> | |
3726 | <function>xf86ResizeOffscreenArea()</function> resizes an existing | |
3727 | <literal remap="tt">FBArea</literal>. <function>xf86ResizeOffscreenArea()</function> | |
3728 | returns <constant>TRUE</constant> if the resize was successful. If | |
3729 | <function>xf86ResizeOffscreenArea()</function> returns <constant>FALSE</constant>, | |
3730 | the original <literal remap="tt">FBArea</literal> is left unmodified. Resizing an | |
3731 | area maintains the area's original <literal remap="tt">granularity</literal>, | |
3732 | <literal remap="tt">devPrivate</literal>, and <literal remap="tt">MoveAreaCallback</literal>. | |
3733 | <function>xf86ResizeOffscreenArea()</function> has considerably less overhead | |
3734 | than freeing the old area then reallocating the new size, so it should | |
3735 | be used whenever possible. | |
3736 | </para> | |
3737 | ||
3738 | <para> | |
3739 | The function: | |
3740 | <programlisting> | |
3741 | Bool xf86QueryLargestOffscreenArea( | |
3742 | ScreenPtr pScreen, | |
3743 | int *width, int *height, | |
3744 | int granularity, | |
3745 | int preferences, | |
3746 | int priority | |
3747 | ); | |
3748 | </programlisting> | |
3749 | ||
3750 | is provided to query the width and height of the largest single | |
3751 | <structname>FBArea</structname> allocatable given a particular priority. | |
3752 | <parameter>preferences</parameter> can be one of the following to indicate | |
3753 | whether width, height or area should be considered when determining | |
3754 | which is the largest single <structname>FBArea</structname> available. | |
3755 | ||
3756 | <programlisting> | |
3757 | FAVOR_AREA_THEN_WIDTH | |
3758 | FAVOR_AREA_THEN_HEIGHT | |
3759 | FAVOR_WIDTH_THEN_AREA | |
3760 | FAVOR_HEIGHT_THEN_AREA | |
3761 | </programlisting> | |
3762 | </para> | |
3763 | ||
3764 | <para> | |
3765 | <parameter>priority</parameter> is one of the following: | |
3766 | ||
3767 | <blockquote> | |
3768 | <para> | |
3769 | <constant>PRIORITY_LOW</constant> | |
3770 | <blockquote><para> | |
3771 | Return the largest block available without stealing anyone else's | |
3772 | space. This corresponds to the priority of allocating a | |
3773 | <structname>FBArea</structname> when a <function>RemoveAreaCallback</function> | |
3774 | is provided. | |
3775 | </para></blockquote> | |
3776 | </para> | |
3777 | ||
3778 | <para> | |
3779 | <constant>PRIORITY_NORMAL</constant> | |
3780 | <blockquote><para> | |
3781 | Return the largest block available if it is acceptable to steal a | |
3782 | lower priority area from someone. This corresponds to the priority | |
3783 | of allocating a <structname>FBArea</structname> without providing a | |
3784 | <function>RemoveAreaCallback</function>. | |
3785 | </para></blockquote> | |
3786 | </para> | |
3787 | ||
3788 | <para> | |
3789 | <constant>PRIORITY_EXTREME</constant> | |
3790 | <blockquote><para> | |
3791 | Return the largest block available if all <structname>FBArea</structname>s | |
3792 | that aren't locked down were expunged from memory first. This | |
3793 | corresponds to any allocation made directly after a call to | |
3794 | <function>xf86PurgeUnlockedOffscreenAreas()</function>. | |
3795 | </para></blockquote> | |
3796 | </para> | |
3797 | ||
3798 | </blockquote> | |
3799 | </para> | |
3800 | ||
3801 | ||
3802 | <para> | |
3803 | The function: | |
3804 | ||
3805 | <programlisting> | |
3806 | Bool xf86PurgeUnlockedOffscreenAreas(ScreenPtr pScreen); | |
3807 | </programlisting> | |
3808 | ||
3809 | is provided as an extreme method to free up offscreen memory. This | |
3810 | will remove all removable <structname>FBArea</structname> allocations. | |
3811 | </para> | |
3812 | ||
3813 | ||
3814 | <para> | |
3815 | Initialization of the XFree86 framebuffer manager is done via | |
3816 | ||
3817 | <programlisting> | |
3818 | Bool xf86InitFBManager(ScreenPtr pScreen, BoxPtr FullBox); | |
3819 | </programlisting> | |
3820 | ||
3821 | <parameter>FullBox</parameter> represents the area of the framebuffer that the | |
3822 | manager is allowed to manage. This is typically a box with a width of | |
3823 | <structfield>pScrn->displayWidth</structfield> and a height of as many lines as | |
3824 | can be fit within the total video memory, however, the driver can reserve | |
3825 | areas at the extremities by passing a smaller area to the manager. | |
3826 | </para> | |
3827 | </sect1> | |
3828 | ||
3829 | <sect1 id="cmap"> | |
3830 | <title>Colormap Handling</title> | |
3831 | ||
3832 | <para> | |
3833 | A generic colormap handling layer is provided within the XFree86 common | |
3834 | layer. This layer takes care of most of the details, and only requires | |
3835 | a function from the driver that loads the hardware palette when required. | |
3836 | To use the colormap layer, a driver calls the | |
3837 | <function>xf86HandleColormaps()</function> function. | |
3838 | ||
3839 | <blockquote><para> | |
3840 | <programlisting> | |
3841 | Bool xf86HandleColormaps(ScreenPtr pScreen, int maxColors, | |
3842 | int sigRGBbits, LoadPaletteFuncPtr loadPalette, | |
3843 | SetOverscanFuncPtr setOverscan, | |
3844 | unsigned int flags); | |
3845 | </programlisting> | |
3846 | <blockquote><para> | |
3847 | This function must be called after the default colormap has been | |
3848 | initialised. The <structfield>pScrn->gamma</structfield> field must also | |
3849 | be initialised, preferably by calling <function>xf86SetGamma()</function>. | |
3850 | <parameter>maxColors</parameter> is the number of entries in the palette. | |
3851 | <parameter>sigRGBbits</parameter> is the size in bits of each color | |
3852 | component in the DAC's palette. <parameter>loadPalette</parameter> | |
3853 | is a driver-provided function for loading a colormap into the | |
3854 | hardware, and is described below. <parameter>setOverscan</parameter> is | |
3855 | an optional function that may be provided when the overscan color | |
3856 | is an index from the standard LUT and when it needs to be adjusted | |
3857 | to keep it as close to black as possible. The | |
3858 | <parameter>setOverscan</parameter> function programs the overscan index. | |
3859 | It shouldn't normally be used for depths other than 8. | |
3860 | <parameter>setOverscan</parameter> should be set to <constant>NULL</constant> | |
3861 | when it isn't needed. <parameter>flags</parameter> may be set to the | |
3862 | following (which may be ORed together): | |
3863 | ||
3864 | <variablelist> | |
3865 | <varlistentry> | |
3866 | <term><constant>CMAP_PALETTED_TRUECOLOR</constant></term> | |
3867 | <listitem><para> | |
3868 | the TrueColor visual is paletted and is | |
3869 | just a special case of DirectColor. | |
3870 | This flag is only valid for | |
3871 | <code>bpp > 8</code>. | |
3872 | ||
3873 | </para></listitem></varlistentry> | |
3874 | <varlistentry> | |
3875 | <term><constant>CMAP_RELOAD_ON_MODE_SWITCH</constant></term> | |
3876 | <listitem><para> | |
3877 | reload the colormap automatically | |
3878 | after mode switches. This is useful | |
3879 | for when the driver is resetting the | |
3880 | hardware during mode switches and | |
3881 | corrupting or erasing the hardware | |
3882 | palette. | |
3883 | ||
3884 | </para></listitem></varlistentry> | |
3885 | <varlistentry> | |
3886 | <term><constant>CMAP_LOAD_EVEN_IF_OFFSCREEN</constant></term> | |
3887 | <listitem><para> | |
3888 | reload the colormap even if the screen | |
3889 | is switched out of the server's VC. | |
3890 | The palette is <emphasis>not</emphasis> reloaded when | |
3891 | the screen is switched back in, nor after | |
3892 | mode switches. This is useful when the | |
3893 | driver needs to keep track of palette | |
3894 | changes. | |
3895 | ||
3896 | </para></listitem></varlistentry> | |
3897 | </variablelist> | |
3898 | </para> | |
3899 | ||
3900 | <para> | |
3901 | The colormap layer normally reloads the palette after VT enters so it | |
3902 | is not necessary for the driver to save and restore the palette | |
3903 | when switching VTs. The driver must, however, still save the | |
3904 | initial palette during server start up and restore it during | |
3905 | server exit. | |
3906 | </para> | |
3907 | ||
3908 | </blockquote></para></blockquote> | |
3909 | ||
3910 | <blockquote><para> | |
3911 | <programlisting> | |
3912 | void LoadPalette(ScrnInfoPtr pScrn, int numColors, int *indices, | |
3913 | LOCO *colors, VisualPtr pVisual); | |
3914 | </programlisting> | |
3915 | <blockquote><para> | |
3916 | <function>LoadPalette()</function> is a driver-provided function for | |
3917 | loading a colormap into hardware. <parameter>colors</parameter> is the | |
3918 | array of RGB values that represent the full colormap. | |
3919 | <parameter>indices</parameter> is a list of index values into the colors | |
3920 | array. These indices indicate the entries that need to be updated. | |
3921 | <parameter>numColors</parameter> is the number of the indices to be | |
3922 | updated. | |
3923 | </para> | |
3924 | ||
3925 | </blockquote></para></blockquote> | |
3926 | ||
3927 | <blockquote><para> | |
3928 | <programlisting> | |
3929 | void SetOverscan(ScrnInfoPtr pScrn, int overscan); | |
3930 | </programlisting> | |
3931 | <blockquote><para> | |
3932 | <function>SetOverscan()</function> is a driver-provided function for | |
3933 | programming the <parameter>overscan</parameter> index. As described | |
3934 | above, it is normally only appropriate for LUT modes where all | |
3935 | colormap entries are available for the display, but where one of | |
3936 | them is also used for the overscan (typically 8bpp for VGA compatible | |
3937 | LUTs). It isn't required in cases where the overscan area is | |
3938 | never visible. | |
3939 | </para> | |
3940 | ||
3941 | </blockquote></para> | |
3942 | </blockquote></para> | |
3943 | ||
3944 | </sect1> | |
3945 | ||
3946 | <sect1> | |
3947 | <title>DPMS Extension</title> | |
3948 | ||
3949 | <para> | |
3950 | Support code for the DPMS extension is included in the XFree86 common layer. | |
3951 | This code provides an interface between the main extension code, and a means | |
3952 | for drivers to initialise DPMS when they support it. One function is | |
3953 | available to drivers to do this initialisation, and it is always available, | |
3954 | even when the DPMS extension is not supported by the core server (in | |
3955 | which case it returns a failure result). | |
3956 | </para> | |
3957 | ||
3958 | <blockquote><para> | |
3959 | <programlisting> | |
3960 | Bool xf86DPMSInit(ScreenPtr pScreen, DPMSSetProcPtr set, int flags); | |
3961 | </programlisting> | |
3962 | <blockquote><para> | |
3963 | This function registers a driver's DPMS level programming function | |
3964 | <parameter>set</parameter>. It also checks | |
3965 | <structfield>pScrn->options</structfield> for the "dpms" option, and when | |
3966 | present marks DPMS as being enabled for that screen. The | |
3967 | <parameter>set</parameter> function is called whenever the DPMS level | |
3968 | changes, and is used to program the requested level. | |
3969 | <parameter>flags</parameter> is currently not used, and should be | |
3970 | <constant>0</constant>. If the initialisation fails for any reason, | |
3971 | including when there is no DPMS support in the core server, the | |
3972 | function returns <constant>FALSE</constant>. | |
3973 | </para> | |
3974 | ||
3975 | </blockquote></para></blockquote> | |
3976 | ||
3977 | ||
3978 | <para> | |
3979 | Drivers that implement DPMS support must provide the following function, | |
3980 | that gets called when the DPMS level is changed: | |
3981 | ||
3982 | ||
3983 | <blockquote><para> | |
3984 | <programlisting> | |
3985 | void ChipDPMSSet(ScrnInfoPtr pScrn, int level, int flags); | |
3986 | </programlisting> | |
3987 | <blockquote><para> | |
3988 | Program the DPMS level specified by <parameter>level</parameter>. Valid | |
3989 | values of <parameter>level</parameter> are <constant>DPMSModeOn</constant>, | |
3990 | <constant>DPMSModeStandby</constant>, <constant>DPMSModeSuspend</constant>, | |
3991 | <constant>DPMSModeOff</constant>. These values are defined in | |
3992 | <filename>"extensions/dpms.h"</filename>. | |
3993 | </para> | |
3994 | ||
3995 | </blockquote></para></blockquote> | |
3996 | </para> | |
3997 | ||
3998 | </sect1> | |
3999 | ||
4000 | <sect1> | |
4001 | <title>DGA Extension</title> | |
4002 | ||
4003 | <para> | |
4004 | Drivers can support the XFree86 Direct Graphics Architecture (DGA) by | |
4005 | filling out a structure of function pointers and a list of modes and | |
4006 | passing them to DGAInit. | |
4007 | </para> | |
4008 | ||
4009 | <blockquote><para> | |
4010 | <programlisting> | |
4011 | Bool DGAInit(ScreenPtr pScreen, DGAFunctionPtr funcs, | |
4012 | DGAModePtr modes, int num); | |
4013 | ||
4014 | /** The DGAModeRec **/ | |
4015 | ||
4016 | typedef struct { | |
4017 | int num; | |
4018 | DisplayModePtr mode; | |
4019 | int flags; | |
4020 | int imageWidth; | |
4021 | int imageHeight; | |
4022 | int pixmapWidth; | |
4023 | int pixmapHeight; | |
4024 | int bytesPerScanline; | |
4025 | int byteOrder; | |
4026 | int depth; | |
4027 | int bitsPerPixel; | |
4028 | unsigned long red_mask; | |
4029 | unsigned long green_mask; | |
4030 | unsigned long blue_mask; | |
4031 | int viewportWidth; | |
4032 | int viewportHeight; | |
4033 | int xViewportStep; | |
4034 | int yViewportStep; | |
4035 | int maxViewportX; | |
4036 | int maxViewportY; | |
4037 | int viewportFlags; | |
4038 | int offset; | |
4039 | unsigned char *address; | |
4040 | int reserved1; | |
4041 | int reserved2; | |
4042 | } DGAModeRec, *DGAModePtr; | |
4043 | </programlisting> | |
4044 | ||
4045 | <variablelist> | |
4046 | <varlistentry> | |
4047 | <term><structfield>num</structfield></term> | |
4048 | <listitem><para> | |
4049 | Can be ignored. The DGA DDX will assign these numbers. | |
4050 | </para></listitem></varlistentry> | |
4051 | ||
4052 | <varlistentry> | |
4053 | <term><structfield>mode</structfield></term> | |
4054 | <listitem><para> | |
4055 | A pointer to the <structname>DisplayModeRec</structname> for this mode. | |
4056 | </para></listitem></varlistentry> | |
4057 | ||
4058 | <varlistentry> | |
4059 | <term><structfield>flags</structfield></term> | |
4060 | <listitem><para> | |
4061 | The following flags are defined and may be OR'd together: | |
4062 | ||
4063 | <variablelist> | |
4064 | <varlistentry> | |
4065 | <term><constant>DGA_CONCURRENT_ACCESS</constant></term> | |
4066 | <listitem><para> | |
4067 | Indicates that the driver supports concurrent graphics | |
4068 | accelerator and linear framebuffer access. | |
4069 | ||
4070 | </para></listitem></varlistentry> | |
4071 | ||
4072 | <varlistentry> | |
4073 | <term><constant>DGA_FILL_RECT | |
4074 | DGA_BLIT_RECT | |
4075 | DGA_BLIT_RECT_TRANS</constant></term> | |
4076 | <listitem><para> | |
4077 | Indicates that the driver supports the FillRect, BlitRect | |
4078 | or BlitTransRect functions in this mode. | |
4079 | ||
4080 | </para></listitem></varlistentry> | |
4081 | ||
4082 | <varlistentry> | |
4083 | <term><constant>DGA_PIXMAP_AVAILABLE</constant></term> | |
4084 | <listitem><para> | |
4085 | Indicates that Xlib may be used on the framebuffer. | |
4086 | This flag will usually be set unless the driver wishes | |
4087 | to prohibit this for some reason. | |
4088 | ||
4089 | </para></listitem></varlistentry> | |
4090 | ||
4091 | <varlistentry> | |
4092 | <term><constant>DGA_INTERLACED | |
4093 | DGA_DOUBLESCAN</constant></term> | |
4094 | <listitem><para> | |
4095 | Indicates that these are interlaced or double scan modes. | |
4096 | ||
4097 | </para></listitem></varlistentry> | |
4098 | </variablelist> | |
4099 | </para></listitem></varlistentry> | |
4100 | ||
4101 | <varlistentry> | |
4102 | <term><structfield>imageWidth | |
4103 | imageHeight</structfield></term> | |
4104 | <listitem><para> | |
4105 | These are the dimensions of the linear framebuffer | |
4106 | accessible by the client. | |
4107 | ||
4108 | </para></listitem></varlistentry> | |
4109 | ||
4110 | <varlistentry> | |
4111 | <term><structfield>pixmapWidth | |
4112 | pixmapHeight</structfield></term> | |
4113 | <listitem><para> | |
4114 | These are the dimensions of the area of the | |
4115 | framebuffer accessible by the graphics accelerator. | |
4116 | ||
4117 | </para></listitem></varlistentry> | |
4118 | ||
4119 | <varlistentry> | |
4120 | <term><structfield>bytesPerScanline</structfield></term> | |
4121 | <listitem><para> | |
4122 | Pitch of the framebuffer in bytes. | |
4123 | ||
4124 | </para></listitem></varlistentry> | |
4125 | ||
4126 | <varlistentry> | |
4127 | <term><structfield>byteOrder</structfield></term> | |
4128 | <listitem><para> | |
4129 | Usually the same as | |
4130 | <structfield>pScrn->imageByteOrder</structfield>. | |
4131 | ||
4132 | </para></listitem></varlistentry> | |
4133 | ||
4134 | <varlistentry> | |
4135 | <term><structfield>depth</structfield></term> | |
4136 | <listitem><para> | |
4137 | The depth of the framebuffer in this mode. | |
4138 | ||
4139 | </para></listitem></varlistentry> | |
4140 | ||
4141 | <varlistentry> | |
4142 | <term><structfield>bitsPerPixel</structfield></term> | |
4143 | <listitem><para> | |
4144 | The number of bits per pixel in this mode. | |
4145 | ||
4146 | </para></listitem></varlistentry> | |
4147 | ||
4148 | <varlistentry> | |
4149 | <term><structfield>red_mask</structfield></term> | |
4150 | <term><structfield>green_mask</structfield></term> | |
4151 | <term><structfield>blue_mask</structfield></term> | |
4152 | <listitem><para> | |
4153 | The RGB masks for this mode, if applicable. | |
4154 | ||
4155 | </para></listitem></varlistentry> | |
4156 | ||
4157 | <varlistentry> | |
4158 | <term><structfield>viewportWidth</structfield></term> | |
4159 | <term><structfield>viewportHeight</structfield></term> | |
4160 | <listitem><para> | |
4161 | Dimensions of the visible part of the framebuffer. | |
4162 | Usually <structfield>mode->HDisplay</structfield> and | |
4163 | <structfield>mode->VDisplay</structfield>. | |
4164 | ||
4165 | </para></listitem></varlistentry> | |
4166 | ||
4167 | <varlistentry> | |
4168 | <term><structfield>xViewportStep | |
4169 | yViewportStep</structfield></term> | |
4170 | <listitem><para> | |
4171 | The granularity of x and y viewport positions that | |
4172 | the driver supports in this mode. | |
4173 | ||
4174 | </para></listitem></varlistentry> | |
4175 | ||
4176 | <varlistentry> | |
4177 | <term><structfield>maxViewportX | |
4178 | maxViewportY</structfield></term> | |
4179 | <listitem><para> | |
4180 | The maximum viewport position supported by the | |
4181 | driver in this mode. | |
4182 | </para></listitem></varlistentry> | |
4183 | ||
4184 | <varlistentry> | |
4185 | <term><structfield>viewportFlags</structfield></term> | |
4186 | <listitem><para> | |
4187 | The following may be OR'd together: | |
4188 | ||
4189 | <variablelist> | |
4190 | <varlistentry> | |
4191 | <term><constant>DGA_FLIP_IMMEDIATE</constant></term> | |
4192 | <listitem><para> | |
4193 | The driver supports immediate viewport changes. | |
4194 | </para></listitem></varlistentry> | |
4195 | ||
4196 | <varlistentry> | |
4197 | <term><constant>DGA_FLIP_RETRACE</constant></term> | |
4198 | ||
4199 | <listitem><para> | |
4200 | The driver supports viewport changes at retrace. | |
4201 | </para></listitem></varlistentry> | |
4202 | </variablelist> | |
4203 | </para></listitem></varlistentry> | |
4204 | ||
4205 | <varlistentry> | |
4206 | <term><structfield>offset</structfield></term> | |
4207 | <listitem><para> | |
4208 | The offset into the linear framebuffer that corresponds to | |
4209 | pixel (0,0) for this mode. | |
4210 | </para></listitem></varlistentry> | |
4211 | ||
4212 | <varlistentry> | |
4213 | <term><structfield>address</structfield></term> | |
4214 | <listitem><para> | |
4215 | The virtual address of the framebuffer as mapped by the driver. | |
4216 | This is needed when DGA_PIXMAP_AVAILABLE is set. | |
4217 | </para></listitem></varlistentry> | |
4218 | ||
4219 | </variablelist> | |
4220 | ||
4221 | <programlisting> | |
4222 | /** The DGAFunctionRec **/ | |
4223 | ||
4224 | typedef struct { | |
4225 | Bool (*OpenFramebuffer)( | |
4226 | ScrnInfoPtr pScrn, | |
4227 | char **name, | |
4228 | unsigned char **mem, | |
4229 | int *size, | |
4230 | int *offset, | |
4231 | int *extra | |
4232 | ); | |
4233 | void (*CloseFramebuffer)(ScrnInfoPtr pScrn); | |
4234 | Bool (*SetMode)(ScrnInfoPtr pScrn, DGAModePtr pMode); | |
4235 | void (*SetViewport)(ScrnInfoPtr pScrn, int x, int y, int flags); | |
4236 | int (*GetViewport)(ScrnInfoPtr pScrn); | |
4237 | void (*Sync)(ScrnInfoPtr); | |
4238 | void (*FillRect)( | |
4239 | ScrnInfoPtr pScrn, | |
4240 | int x, int y, int w, int h, | |
4241 | unsigned long color | |
4242 | ); | |
4243 | void (*BlitRect)( | |
4244 | ScrnInfoPtr pScrn, | |
4245 | int srcx, int srcy, | |
4246 | int w, int h, | |
4247 | int dstx, int dsty | |
4248 | ); | |
4249 | void (*BlitTransRect)( | |
4250 | ScrnInfoPtr pScrn, | |
4251 | int srcx, int srcy, | |
4252 | int w, int h, | |
4253 | int dstx, int dsty, | |
4254 | unsigned long color | |
4255 | ); | |
4256 | } DGAFunctionRec, *DGAFunctionPtr; | |
4257 | </programlisting> | |
4258 | ||
4259 | ||
4260 | <blockquote><para> | |
4261 | <programlisting> | |
4262 | Bool OpenFramebuffer (pScrn, name, mem, size, offset, extra); | |
4263 | </programlisting> | |
4264 | <blockquote><para> | |
4265 | <function>OpenFramebuffer()</function> should pass the client everything | |
4266 | it needs to know to be able to open the framebuffer. These | |
4267 | parameters are OS specific and their meanings are to be interpreted | |
4268 | by an OS specific client library. | |
4269 | ||
4270 | <variablelist> | |
4271 | <varlistentry> | |
4272 | <term><parameter>name</parameter></term> | |
4273 | <listitem><para> | |
4274 | The name of the device to open or <constant>NULL</constant> if | |
4275 | there is no special device to open. A <constant>NULL</constant> | |
4276 | name tells the client that it should open whatever device | |
4277 | one would usually open to access physical memory. | |
4278 | </para></listitem></varlistentry> | |
4279 | ||
4280 | <varlistentry> | |
4281 | <term><parameter>mem</parameter></term> | |
4282 | <listitem><para> | |
4283 | The physical address of the start of the framebuffer. | |
4284 | </para></listitem></varlistentry> | |
4285 | ||
4286 | <varlistentry> | |
4287 | <term><parameter>size</parameter></term> | |
4288 | <listitem><para> | |
4289 | The size of the framebuffer in bytes. | |
4290 | </para></listitem></varlistentry> | |
4291 | ||
4292 | <varlistentry> | |
4293 | <term><parameter>offset</parameter></term> | |
4294 | <listitem><para> | |
4295 | Any offset into the device, if applicable. | |
4296 | </para></listitem></varlistentry> | |
4297 | ||
4298 | <varlistentry> | |
4299 | <term><parameter>flags</parameter></term> | |
4300 | <listitem><para> | |
4301 | Any additional information that the client may need. | |
4302 | Currently, only the <constant>DGA_NEED_ROOT</constant> flag is | |
4303 | defined. | |
4304 | </para></listitem></varlistentry> | |
4305 | ||
4306 | </variablelist> | |
4307 | </para></blockquote> | |
4308 | </para></blockquote> | |
4309 | ||
4310 | <blockquote><para> | |
4311 | <programlisting> | |
4312 | void CloseFramebuffer (pScrn); | |
4313 | </programlisting> | |
4314 | <blockquote><para> | |
4315 | <function>CloseFramebuffer()</function> merely informs the driver (if it | |
4316 | even cares) that client no longer needs to access the framebuffer | |
4317 | directly. This function is optional. | |
4318 | </para> | |
4319 | ||
4320 | </blockquote></para></blockquote> | |
4321 | ||
4322 | <blockquote><para> | |
4323 | <programlisting> | |
4324 | Bool SetMode (pScrn, pMode); | |
4325 | </programlisting> | |
4326 | <blockquote><para> | |
4327 | <function>SetMode()</function> tells the driver to initialize the mode | |
4328 | passed to it. If <parameter>pMode</parameter> is <constant>NULL</constant>, | |
4329 | then the driver should restore the original pre-DGA mode. | |
4330 | </para> | |
4331 | ||
4332 | </blockquote></para></blockquote> | |
4333 | ||
4334 | <blockquote><para> | |
4335 | <programlisting> | |
4336 | void SetViewport (pScrn, x, y, flags); | |
4337 | </programlisting> | |
4338 | <blockquote><para> | |
4339 | <function>SetViewport()</function> tells the driver to make the upper | |
4340 | left-hand corner of the visible screen correspond to coordinate | |
4341 | <literal remap="tt">(x,y)</literal> on the framebuffer. <parameter>flags</parameter> | |
4342 | currently defined are: | |
4343 | ||
4344 | <variablelist> | |
4345 | <varlistentry> | |
4346 | <term><constant>DGA_FLIP_IMMEDIATE</constant></term> | |
4347 | <listitem><para> | |
4348 | The viewport change should occur immediately. | |
4349 | </para></listitem></varlistentry> | |
4350 | ||
4351 | <varlistentry> | |
4352 | <term><constant>DGA_FLIP_RETRACE</constant></term> | |
4353 | <listitem><para> | |
4354 | The viewport change should occur at the | |
4355 | vertical retrace, but this function should | |
4356 | return sooner if possible. | |
4357 | </para></listitem></varlistentry> | |
4358 | </variablelist> | |
4359 | </para> | |
4360 | ||
4361 | <para> | |
4362 | The <literal remap="tt">(x,y)</literal> locations will be passed as the client | |
4363 | specified them, however, the driver is expected to round these | |
4364 | locations down to the next supported location as specified by the | |
4365 | <structfield>xViewportStep</structfield> and <structfield>yViewportStep</structfield> | |
4366 | for the current mode. | |
4367 | </para> | |
4368 | </blockquote></para></blockquote> | |
4369 | ||
4370 | <blockquote><para> | |
4371 | <programlisting> | |
4372 | int GetViewport (pScrn); | |
4373 | </programlisting> | |
4374 | <blockquote><para> | |
4375 | <function>GetViewport()</function> gets the current page flip status. | |
4376 | Set bits in the returned int correspond to viewport change requests | |
4377 | still pending. For instance, set bit zero if the last SetViewport | |
4378 | request is still pending, bit one if the one before that is still | |
4379 | pending, etc. | |
4380 | </para> | |
4381 | ||
4382 | </blockquote></para></blockquote> | |
4383 | ||
4384 | <blockquote><para> | |
4385 | <programlisting> | |
4386 | void Sync (pScrn); | |
4387 | </programlisting> | |
4388 | <blockquote><para> | |
4389 | This function should ensure that any graphics accelerator operations | |
4390 | have finished. This function should not return until the graphics | |
4391 | accelerator is idle. | |
4392 | </para> | |
4393 | ||
4394 | </blockquote></para></blockquote> | |
4395 | ||
4396 | <blockquote><para> | |
4397 | <programlisting> | |
4398 | void FillRect (pScrn, x, y, w, h, color); | |
4399 | </programlisting> | |
4400 | <blockquote><para> | |
4401 | This optional function should fill a rectangle | |
4402 | <parameter>w × h</parameter> located at | |
4403 | <parameter>(x,y)</parameter> in the given color. | |
4404 | </para> | |
4405 | ||
4406 | </blockquote></para></blockquote> | |
4407 | ||
4408 | <blockquote><para> | |
4409 | <programlisting> | |
4410 | void BlitRect (pScrn, srcx, srcy, w, h, dstx, dsty); | |
4411 | </programlisting> | |
4412 | <blockquote><para> | |
4413 | This optional function should copy an area | |
4414 | <parameter>w × h</parameter> located at | |
4415 | <parameter>(srcx,srcy)</parameter> to location <parameter>(dstx,dsty)</parameter>. | |
4416 | This function will need to handle copy directions as appropriate. | |
4417 | </para> | |
4418 | ||
4419 | </blockquote></para></blockquote> | |
4420 | ||
4421 | <blockquote><para> | |
4422 | <programlisting> | |
4423 | void BlitTransRect (pScrn, srcx, srcy, w, h, dstx, dsty, color); | |
4424 | </programlisting> | |
4425 | <blockquote><para> | |
4426 | This optional function is the same as BlitRect except that pixels | |
4427 | in the source corresponding to the color key <parameter>color</parameter> | |
4428 | should be skipped. | |
4429 | </para> | |
4430 | ||
4431 | </blockquote></para></blockquote> | |
4432 | </para></blockquote> | |
4433 | ||
4434 | </sect1> | |
4435 | ||
4436 | <sect1> | |
4437 | <title>The XFree86 X Video Extension (Xv) Device Dependent Layer</title> | |
4438 | ||
4439 | <para> | |
4440 | XFree86 offers the X Video Extension which allows clients to treat video | |
4441 | as any another primitive and <quote>Put</quote> video into drawables. By default, | |
4442 | the extension reports no video adaptors as being available since the | |
4443 | DDX layer has not been initialized. The driver can initialize the DDX | |
4444 | layer by filling out one or more <literal remap="tt">XF86VideoAdaptorRecs</literal> | |
4445 | as described later in this document and passing a list of | |
4446 | <literal remap="tt">XF86VideoAdaptorPtr</literal> pointers to the following function: | |
4447 | ||
4448 | <programlisting> | |
4449 | Bool xf86XVScreenInit(ScreenPtr pScreen, | |
4450 | XF86VideoAdaptorPtr *adaptPtrs, | |
4451 | int num); | |
4452 | </programlisting> | |
4453 | </para> | |
4454 | ||
4455 | <para> | |
4456 | After doing this, the extension will report video adaptors as being | |
4457 | available, providing the data in their respective | |
4458 | <literal remap="tt">XF86VideoAdaptorRecs</literal> was valid. | |
4459 | <function>xf86XVScreenInit()</function> <emphasis>copies</emphasis> data from the structure | |
4460 | passed to it so the driver may free it after the initialization. At | |
4461 | the moment, the DDX only supports rendering into Window drawables. | |
4462 | Pixmap rendering will be supported after a sufficient survey of suitable | |
4463 | hardware is completed. | |
4464 | </para> | |
4465 | ||
4466 | <para> | |
4467 | The <structname>XF86VideoAdaptorRec</structname>: | |
4468 | ||
4469 | <programlisting> | |
4470 | typedef struct { | |
4471 | unsigned int type; | |
4472 | int flags; | |
4473 | char *name; | |
4474 | int nEncodings; | |
4475 | XF86VideoEncodingPtr pEncodings; | |
4476 | int nFormats; | |
4477 | XF86VideoFormatPtr pFormats; | |
4478 | int nPorts; | |
4479 | DevUnion *pPortPrivates; | |
4480 | int nAttributes; | |
4481 | XF86AttributePtr pAttributes; | |
4482 | int nImages; | |
4483 | XF86ImagePtr pImages; | |
4484 | PutVideoFuncPtr PutVideo; | |
4485 | PutStillFuncPtr PutStill; | |
4486 | GetVideoFuncPtr GetVideo; | |
4487 | GetStillFuncPtr GetStill; | |
4488 | StopVideoFuncPtr StopVideo; | |
4489 | SetPortAttributeFuncPtr SetPortAttribute; | |
4490 | GetPortAttributeFuncPtr GetPortAttribute; | |
4491 | QueryBestSizeFuncPtr QueryBestSize; | |
4492 | PutImageFuncPtr PutImage; | |
4493 | QueryImageAttributesFuncPtr QueryImageAttributes; | |
4494 | } XF86VideoAdaptorRec, *XF86VideoAdaptorPtr; | |
4495 | </programlisting></para> | |
4496 | ||
4497 | <para> | |
4498 | Each adaptor will have its own XF86VideoAdaptorRec. The fields are | |
4499 | as follows: | |
4500 | ||
4501 | <variablelist> | |
4502 | <varlistentry> | |
4503 | <term><structfield>type</structfield></term> | |
4504 | <listitem><para> | |
4505 | This can be any of the following flags OR'd together. | |
4506 | ||
4507 | <variablelist> | |
4508 | <varlistentry> | |
4509 | <term><constant>XvInputMask</constant> | |
4510 | <constant>XvOutputMask</constant></term> | |
4511 | <listitem><para> | |
4512 | These refer to the target drawable and are similar to a Window's | |
4513 | class. <literal remap="tt">XvInputMask</literal> indicates that the adaptor | |
4514 | can put video into a drawable. <literal remap="tt">XvOutputMask</literal> | |
4515 | indicates that the adaptor can get video from a drawable. | |
4516 | </para></listitem></varlistentry> | |
4517 | ||
4518 | <varlistentry> | |
4519 | <term><constant>XvVideoMask</constant> | |
4520 | <constant>XvStillMask</constant> | |
4521 | <constant>XvImageMask</constant></term> | |
4522 | <listitem><para> | |
4523 | These indicate that the adaptor supports video, still or | |
4524 | image primitives respectively. | |
4525 | </para></listitem></varlistentry> | |
4526 | ||
4527 | <varlistentry> | |
4528 | <term><constant>XvWindowMask</constant> | |
4529 | <constant>XvPixmapMask</constant></term> | |
4530 | <listitem><para> | |
4531 | These indicate the types of drawables the adaptor is capable | |
4532 | of rendering into. At the moment, Pixmap rendering is not | |
4533 | supported and the <constant>XvPixmapMask</constant> flag is ignored. | |
4534 | </para></listitem></varlistentry> | |
4535 | </variablelist> | |
4536 | ||
4537 | </para></listitem></varlistentry> | |
4538 | ||
4539 | <varlistentry> | |
4540 | <term><structfield>flags</structfield></term> | |
4541 | <listitem><para> | |
4542 | Currently, the following flags are defined: | |
4543 | ||
4544 | <variablelist> | |
4545 | <varlistentry> | |
4546 | <term><constant>VIDEO_NO_CLIPPING</constant></term> | |
4547 | <listitem><para> | |
4548 | This indicates that the video adaptor does not support | |
4549 | clipping. The driver will never receive <quote>Put</quote> requests | |
4550 | where less than the entire area determined by | |
4551 | <parameter>drw_x</parameter>, <parameter>drw_y</parameter>, | |
4552 | <parameter>drw_w</parameter> and <parameter>drw_h</parameter> is visible. | |
4553 | This flag does not apply to <quote>Get</quote> requests. Hardware | |
4554 | that is incapable of clipping <quote>Gets</quote> may punt or get | |
4555 | the extents of the clipping region passed to it. | |
4556 | </para></listitem> | |
4557 | ||
4558 | </varlistentry> | |
4559 | ||
4560 | <varlistentry> | |
4561 | <term><constant>VIDEO_INVERT_CLIPLIST</constant></term> | |
4562 | <listitem><para> | |
4563 | This indicates that the video driver requires the clip | |
4564 | list to contain the regions which are obscured rather | |
4565 | than the regions which are are visible. | |
4566 | </para></listitem> | |
4567 | ||
4568 | </varlistentry> | |
4569 | ||
4570 | <varlistentry> | |
4571 | <term><constant>VIDEO_OVERLAID_STILLS</constant></term> | |
4572 | <listitem><para> | |
4573 | Implementing PutStill for hardware that does video as an | |
4574 | overlay can be awkward since it's unclear how long to leave | |
4575 | the video up for. When this flag is set, StopVideo will be | |
4576 | called whenever the destination gets clipped or moved so that | |
4577 | the still can be left up until then. | |
4578 | </para></listitem> | |
4579 | ||
4580 | </varlistentry> | |
4581 | ||
4582 | <varlistentry> | |
4583 | <term><constant>VIDEO_OVERLAID_IMAGES</constant></term> | |
4584 | <listitem><para> | |
4585 | Same as <constant>VIDEO_OVERLAID_STILLS</constant> but for images. | |
4586 | </para></listitem> | |
4587 | </varlistentry> | |
4588 | ||
4589 | <varlistentry> | |
4590 | <term><constant>VIDEO_CLIP_TO_VIEWPORT</constant></term> | |
4591 | <listitem><para> | |
4592 | Indicates that the clip region passed to the driver functions | |
4593 | should be clipped to the visible portion of the screen in the | |
4594 | case where the viewport is smaller than the virtual desktop. | |
4595 | </para></listitem></varlistentry> | |
4596 | ||
4597 | </variablelist> | |
4598 | </para></listitem></varlistentry> | |
4599 | ||
4600 | <varlistentry> | |
4601 | <term><structfield>name</structfield></term> | |
4602 | <listitem><para> | |
4603 | The name of the adaptor. | |
4604 | </para></listitem></varlistentry> | |
4605 | ||
4606 | ||
4607 | <varlistentry> | |
4608 | <term><structfield>nEncodings</structfield> | |
4609 | <structfield>pEncodings</structfield></term> | |
4610 | <listitem><para> | |
4611 | The number of encodings the adaptor is capable of and pointer | |
4612 | to the <structname>XF86VideoEncodingRec</structname> array. The | |
4613 | <structname>XF86VideoEncodingRec</structname> is described later on. | |
4614 | For drivers that only support XvImages there should be an encoding | |
4615 | named "XV_IMAGE" and the width and height should specify | |
4616 | the maximum size source image supported. | |
4617 | </para></listitem></varlistentry> | |
4618 | ||
4619 | ||
4620 | <varlistentry> | |
4621 | <term><structfield>nFormats</structfield> | |
4622 | <structfield>pFormats</structfield></term> | |
4623 | <listitem><para> | |
4624 | The number of formats the adaptor is capable of and pointer to | |
4625 | the <structname>XF86VideoFormatRec</structname> array. The | |
4626 | <structname>XF86VideoFormatRec</structname> is described later on. | |
4627 | </para></listitem></varlistentry> | |
4628 | ||
4629 | ||
4630 | <varlistentry> | |
4631 | <term><structfield>nPorts</structfield> | |
4632 | <structfield>pPortPrivates</structfield></term> | |
4633 | <listitem><para> | |
4634 | The number of ports is the number of separate data streams which | |
4635 | the adaptor can handle simultaneously. If you have more than | |
4636 | one port, the adaptor is expected to be able to render into more | |
4637 | than one window at a time. <structfield>pPortPrivates</structfield> is | |
4638 | an array of pointers or ints - one for each port. A port's | |
4639 | private data will be passed to the driver any time the port is | |
4640 | requested to do something like put the video or stop the video. | |
4641 | In the case where there may be many ports, this enables the | |
4642 | driver to know which port the request is intended for. Most | |
4643 | commonly, this will contain a pointer to the data structure | |
4644 | containing information about the port. In Xv, all ports on | |
4645 | a particular adaptor are expected to be identical in their | |
4646 | functionality. | |
4647 | </para></listitem></varlistentry> | |
4648 | ||
4649 | ||
4650 | <varlistentry> | |
4651 | <term><structfield>nAttributes</structfield> | |
4652 | <structfield>pAttributes</structfield></term> | |
4653 | <listitem><para> | |
4654 | The number of attributes recognized by the adaptor and a pointer to | |
4655 | the array of <structname>XF86AttributeRecs</structname>. The | |
4656 | <structname>XF86AttributeRec</structname> is described later on. | |
4657 | </para></listitem></varlistentry> | |
4658 | ||
4659 | ||
4660 | <varlistentry> | |
4661 | <term><structfield>nImages</structfield> | |
4662 | <structfield>pImages</structfield></term> | |
4663 | <listitem><para> | |
4664 | The number of <structname>XF86ImageRecs</structname> supported by the adaptor | |
4665 | and a pointer to the array of <structname>XF86ImageRecs</structname>. The | |
4666 | <structname>XF86ImageRec</structname> is described later on. | |
4667 | </para></listitem></varlistentry> | |
4668 | ||
4669 | ||
4670 | <varlistentry> | |
4671 | <term><structfield> | |
4672 | PutVideo PutStill GetVideo GetStill StopVideo | |
4673 | SetPortAttribute GetPortAttribute QueryBestSize PutImage | |
4674 | QueryImageAttributes | |
4675 | </structfield></term> | |
4676 | <listitem><para> | |
4677 | These functions define the DDX->driver interface. In each | |
4678 | case, the pointer <parameter>data</parameter> is passed to the driver. | |
4679 | This is the port private for that port as described above. All | |
4680 | fields are required except under the following conditions: | |
4681 | ||
4682 | <orderedlist> | |
4683 | <listitem><para> | |
4684 | <structfield>PutVideo</structfield>, <structfield>PutStill</structfield> and | |
4685 | the image routines <structfield>PutImage</structfield> and | |
4686 | <structfield>QueryImageAttributes</structfield> are not required when the | |
4687 | adaptor type does not contain <constant>XvInputMask</constant>. | |
4688 | </para></listitem> | |
4689 | ||
4690 | <listitem><para> | |
4691 | <structfield>GetVideo</structfield> and <structfield>GetStill</structfield> | |
4692 | are not required when the adaptor type does not contain | |
4693 | <constant>XvOutputMask</constant>. | |
4694 | </para></listitem> | |
4695 | ||
4696 | <listitem><para> | |
4697 | <structfield>GetVideo</structfield> and <structfield>PutVideo</structfield> | |
4698 | are not required when the adaptor type does not contain | |
4699 | <constant>XvVideoMask</constant>. | |
4700 | </para></listitem> | |
4701 | ||
4702 | <listitem><para> | |
4703 | <structfield>GetStill</structfield> and <structfield>PutStill</structfield> | |
4704 | are not required when the adaptor type does not contain | |
4705 | <constant>XvStillMask</constant>. | |
4706 | </para></listitem> | |
4707 | ||
4708 | <listitem><para> | |
4709 | <structfield>PutImage</structfield> and <structfield>QueryImageAttributes</structfield> | |
4710 | are not required when the adaptor type does not contain | |
4711 | <constant>XvImageMask</constant>. | |
4712 | </para></listitem> | |
4713 | ||
4714 | </orderedlist> | |
4715 | ||
4716 | </para> | |
4717 | ||
4718 | <para> | |
4719 | With the exception of <structfield>QueryImageAttributes</structfield>, these | |
4720 | functions should return <constant>Success</constant> if the operation was | |
4721 | completed successfully. They can return <constant>XvBadAlloc</constant> | |
4722 | otherwise. <structfield>QueryImageAttributes</structfield> returns the size | |
4723 | of the XvImage queried. | |
4724 | </para> | |
4725 | ||
4726 | <para> | |
4727 | If the <constant>VIDEO_NO_CLIPPING</constant> | |
4728 | flag is set, the <literal remap="tt">clipBoxes</literal> may be ignored by | |
4729 | the driver. <literal remap="tt">ClipBoxes</literal> is an <literal remap="tt">X-Y</literal> | |
4730 | banded region identical to those used throughout the server. | |
4731 | The clipBoxes represent the visible portions of the area determined | |
4732 | by <literal remap="tt">drw_x</literal>, <literal remap="tt">drw_y</literal>, | |
4733 | <literal remap="tt">drw_w</literal> and <literal remap="tt">drw_h</literal> in the Get/Put | |
4734 | function. The boxes are in screen coordinates, are guaranteed | |
4735 | not to overlap and an empty region will never be passed. | |
4736 | If the driver has specified <constant>VIDEO_INVERT_CLIPLIST</constant>, | |
4737 | <literal remap="tt">clipBoxes</literal> will indicate the areas of the primitive | |
4738 | which are obscured rather than the areas visible. | |
4739 | ||
4740 | </para></listitem></varlistentry> | |
4741 | </variablelist> | |
4742 | ||
4743 | <blockquote><para> | |
4744 | <programlisting> | |
4745 | typedef int (* PutVideoFuncPtr)( ScrnInfoPtr pScrn, | |
4746 | short vid_x, short vid_y, short drw_x, short drw_y, | |
4747 | short vid_w, short vid_h, short drw_w, short drw_h, | |
4748 | RegionPtr clipBoxes, pointer data ); | |
4749 | </programlisting> | |
4750 | <blockquote><para> | |
4751 | This indicates that the driver should take a subsection | |
4752 | <parameter>vid_w</parameter> by <parameter>vid_h</parameter> at location | |
4753 | <parameter>(vid_x,vid_y)</parameter> from the video stream and direct | |
4754 | it into the rectangle <parameter>drw_w</parameter> by <parameter>drw_h</parameter> | |
4755 | at location <parameter>(drw_x,drw_y)</parameter> on the screen, scaling as | |
4756 | necessary. Due to the large variations in capabilities of | |
4757 | the various hardware expected to be used with this extension, | |
4758 | it is not expected that all hardware will be able to do this | |
4759 | exactly as described. In that case the driver should just do | |
4760 | <quote>the best it can,</quote> scaling as closely to the target rectangle | |
4761 | as it can without rendering outside of it. In the worst case, | |
4762 | the driver can opt to just not turn on the video. | |
4763 | </para> | |
4764 | ||
4765 | </blockquote></para></blockquote> | |
4766 | ||
4767 | <blockquote><para> | |
4768 | <programlisting> | |
4769 | typedef int (* PutStillFuncPtr)( ScrnInfoPtr pScrn, | |
4770 | short vid_x, short vid_y, short drw_x, short drw_y, | |
4771 | short vid_w, short vid_h, short drw_w, short drw_h, | |
4772 | RegionPtr clipBoxes, pointer data ); | |
4773 | </programlisting> | |
4774 | <blockquote><para> | |
4775 | This is same as <structfield>PutVideo</structfield> except that the driver | |
4776 | should place only one frame from the stream on the screen. | |
4777 | </para> | |
4778 | ||
4779 | </blockquote></para></blockquote> | |
4780 | ||
4781 | <blockquote><para> | |
4782 | <programlisting> | |
4783 | typedef int (* GetVideoFuncPtr)( ScrnInfoPtr pScrn, | |
4784 | short vid_x, short vid_y, short drw_x, short drw_y, | |
4785 | short vid_w, short vid_h, short drw_w, short drw_h, | |
4786 | RegionPtr clipBoxes, pointer data ); | |
4787 | </programlisting> | |
4788 | <blockquote><para> | |
4789 | This is same as <structfield>PutVideo</structfield> except that the driver | |
4790 | gets video from the screen and outputs it. The driver should | |
4791 | do the best it can to get the requested dimensions correct | |
4792 | without reading from an area larger than requested. | |
4793 | </para> | |
4794 | ||
4795 | </blockquote></para></blockquote> | |
4796 | ||
4797 | <blockquote><para> | |
4798 | <programlisting> | |
4799 | typedef int (* GetStillFuncPtr)( ScrnInfoPtr pScrn, | |
4800 | short vid_x, short vid_y, short drw_x, short drw_y, | |
4801 | short vid_w, short vid_h, short drw_w, short drw_h, | |
4802 | RegionPtr clipBoxes, pointer data ); | |
4803 | </programlisting> | |
4804 | <blockquote><para> | |
4805 | This is the same as <literal remap="tt">GetVideo</literal> except that the | |
4806 | driver should place only one frame from the screen into the | |
4807 | output stream. | |
4808 | </para> | |
4809 | ||
4810 | </blockquote></para></blockquote> | |
4811 | ||
4812 | <blockquote><para> | |
4813 | <programlisting> | |
4814 | typedef void (* StopVideoFuncPtr)(ScrnInfoPtr pScrn, | |
4815 | pointer data, Bool cleanup); | |
4816 | </programlisting> | |
4817 | <blockquote><para> | |
4818 | This indicates the driver should stop displaying the video. | |
4819 | This is used to stop both input and output video. The | |
4820 | <parameter>cleanup</parameter> field indicates that the video is | |
4821 | being stopped because the client requested it to stop or | |
4822 | because the server is exiting the current VT. In that case | |
4823 | the driver should deallocate any offscreen memory areas (if | |
4824 | there are any) being used to put the video to the screen. If | |
4825 | <parameter>cleanup</parameter> is not set, the video is being stopped | |
4826 | temporarily due to clipping or moving of the window, etc... | |
4827 | and video will likely be restarted soon so the driver should | |
4828 | not deallocate any offscreen areas associated with that port. | |
4829 | </para> | |
4830 | ||
4831 | </blockquote></para></blockquote> | |
4832 | <blockquote><para> | |
4833 | <programlisting> | |
4834 | typedef int (* SetPortAttributeFuncPtr)(ScrnInfoPtr pScrn, | |
4835 | Atom attribute,INT32 value, pointer data); | |
4836 | </programlisting> | |
4837 | ||
4838 | <programlisting> | |
4839 | typedef int (* GetPortAttributeFuncPtr)(ScrnInfoPtr pScrn, | |
4840 | Atom attribute,INT32 *value, pointer data); | |
4841 | </programlisting> | |
4842 | <blockquote><para> | |
4843 | A port may have particular attributes such as hue, | |
4844 | saturation, brightness or contrast. Xv clients set and | |
4845 | get these attribute values by sending attribute strings | |
4846 | (Atoms) to the server. Such requests end up at these | |
4847 | driver functions. It is recommended that the driver provide | |
4848 | at least the following attributes mentioned in the Xv client | |
4849 | library docs: | |
4850 | <literallayout><constant> | |
4851 | XV_ENCODING | |
4852 | XV_HUE | |
4853 | XV_SATURATION | |
4854 | XV_BRIGHTNESS | |
4855 | XV_CONTRAST | |
4856 | </constant></literallayout> | |
4857 | but the driver may recognize as many atoms as it wishes. If | |
4858 | a requested attribute is unknown by the driver it should return | |
4859 | <constant>BadMatch</constant>. <constant>XV_ENCODING</constant> is the | |
4860 | attribute intended to let the client specify which video | |
4861 | encoding the particular port should be using (see the description | |
4862 | of <structname>XF86VideoEncodingRec</structname> below). If the | |
4863 | requested encoding is unsupported, the driver should return | |
4864 | <constant>XvBadEncoding</constant>. If the value lies outside the | |
4865 | advertised range <constant>BadValue</constant> may be returned. | |
4866 | <constant>Success</constant> should be returned otherwise. | |
4867 | </para> | |
4868 | ||
4869 | </blockquote></para></blockquote> | |
4870 | ||
4871 | <blockquote><para> | |
4872 | <programlisting> | |
4873 | typedef void (* QueryBestSizeFuncPtr)(ScrnInfoPtr pScrn, | |
4874 | Bool motion, short vid_w, short vid_h, | |
4875 | short drw_w, short drw_h, | |
4876 | unsigned int *p_w, unsigned int *p_h, pointer data); | |
4877 | </programlisting> | |
4878 | <blockquote><para> | |
4879 | <function>QueryBestSize</function> provides the client with a way | |
4880 | to query what the destination dimensions would end up being | |
4881 | if they were to request that an area | |
4882 | <parameter>vid_w</parameter> by <parameter>vid_h</parameter> from the video | |
4883 | stream be scaled to rectangle of | |
4884 | <parameter>drw_w</parameter> by <parameter>drw_h</parameter> on the screen. | |
4885 | Since it is not expected that all hardware will be able to | |
4886 | get the target dimensions exactly, it is important that the | |
4887 | driver provide this function. | |
4888 | </para> | |
4889 | ||
4890 | </blockquote></para></blockquote> | |
4891 | ||
4892 | <blockquote><para> | |
4893 | <programlisting> | |
4894 | typedef int (* PutImageFuncPtr)( ScrnInfoPtr pScrn, | |
4895 | short src_x, short src_y, short drw_x, short drw_y, | |
4896 | short src_w, short src_h, short drw_w, short drw_h, | |
4897 | int image, char *buf, short width, short height, | |
4898 | Bool sync, RegionPtr clipBoxes, pointer data ); | |
4899 | </programlisting> | |
4900 | <blockquote><para> | |
4901 | This is similar to <structfield>PutStill</structfield> except that the | |
4902 | source of the video is not a port but the data stored in a system | |
4903 | memory buffer at <parameter>buf</parameter>. The data is in the format | |
4904 | indicated by the <parameter>image</parameter> descriptor and represents a | |
4905 | source of size <parameter>width</parameter> by <parameter>height</parameter>. | |
4906 | If <parameter>sync</parameter> is TRUE the driver should not return | |
4907 | from this function until it is through reading the data | |
4908 | from <parameter>buf</parameter>. Returning when <parameter>sync</parameter> | |
4909 | is TRUE indicates that it is safe for the data at <parameter>buf</parameter> | |
4910 | to be replaced, freed, or modified. | |
4911 | </para> | |
4912 | ||
4913 | </blockquote></para></blockquote> | |
4914 | ||
4915 | <blockquote><para> | |
4916 | <programlisting> | |
4917 | typedef int (* QueryImageAttributesFuncPtr)( ScrnInfoPtr pScrn, | |
4918 | int image, short *width, short *height, | |
4919 | int *pitches, int *offsets); | |
4920 | </programlisting> | |
4921 | <blockquote><para> | |
4922 | This function is called to let the driver specify how data for | |
4923 | a particular <parameter>image</parameter> of size <parameter>width</parameter> | |
4924 | by <parameter>height</parameter> should be stored. Sometimes only | |
4925 | the size and corrected width and height are needed. In that | |
4926 | case <parameter>pitches</parameter> and <parameter>offsets</parameter> are | |
4927 | NULL. The size of the memory required for the image is returned | |
4928 | by this function. The <parameter>width</parameter> and | |
4929 | <parameter>height</parameter> of the requested image can be altered by | |
4930 | the driver to reflect format limitations (such as component | |
4931 | sampling periods that are larger than one). If | |
4932 | <parameter>pitches</parameter> and <parameter>offsets</parameter> are not NULL, | |
4933 | these will be arrays with as many elements in them as there | |
4934 | are planes in the <parameter>image</parameter> format. The driver | |
4935 | should specify the pitch (in bytes) of each scanline in the | |
4936 | particular plane as well as the offset to that plane (in bytes) | |
4937 | from the beginning of the image. | |
4938 | </para> | |
4939 | ||
4940 | </blockquote></para></blockquote> | |
4941 | </para> | |
4942 | ||
4943 | <para> | |
4944 | The XF86VideoEncodingRec: | |
4945 | ||
4946 | <blockquote><para> | |
4947 | <programlisting> | |
4948 | typedef struct { | |
4949 | int id; | |
4950 | char *name; | |
4951 | unsigned short width, height; | |
4952 | XvRationalRec rate; | |
4953 | } XF86VideoEncodingRec, *XF86VideoEncodingPtr; | |
4954 | ||
4955 | </programlisting> | |
4956 | <blockquote><para> | |
4957 | The <structname>XF86VideoEncodingRec</structname> specifies what encodings | |
4958 | the adaptor can support. Most of this data is just informational | |
4959 | and for the client's benefit, and is what will be reported by | |
4960 | <function>XvQueryEncodings</function>. The <parameter>id</parameter> field is | |
4961 | expected to be a unique identifier to allow the client to request a | |
4962 | certain encoding via the <constant>XV_ENCODING</constant> attribute string. | |
4963 | ||
4964 | </para> | |
4965 | </blockquote></para></blockquote> | |
4966 | </para> | |
4967 | ||
4968 | <para> | |
4969 | The XF86VideoFormatRec: | |
4970 | ||
4971 | <blockquote><para> | |
4972 | <programlisting> | |
4973 | typedef struct { | |
4974 | char depth; | |
4975 | short class; | |
4976 | } XF86VideoFormatRec, *XF86VideoFormatPtr; | |
4977 | ||
4978 | </programlisting> | |
4979 | <blockquote><para> | |
4980 | This specifies what visuals the video is viewable in. | |
4981 | <parameter>depth</parameter> is the depth of the visual (not bpp). | |
4982 | <parameter>class</parameter> is the visual class such as | |
4983 | <constant>TrueColor</constant>, <constant>DirectColor</constant> or | |
4984 | <constant>PseudoColor</constant>. Initialization of an adaptor will fail | |
4985 | if none of the visuals on that screen are supported. | |
4986 | </para> | |
4987 | ||
4988 | </blockquote></para></blockquote> | |
4989 | </para> | |
4990 | ||
4991 | <para> | |
4992 | The XF86AttributeRec: | |
4993 | ||
4994 | <blockquote><para> | |
4995 | <programlisting> | |
4996 | typedef struct { | |
4997 | int flags; | |
4998 | int min_value; | |
4999 | int max_value; | |
5000 | char *name; | |
5001 | } XF86AttributeListRec, *XF86AttributeListPtr; | |
5002 | ||
5003 | </programlisting> | |
5004 | <blockquote><para> | |
5005 | Each adaptor may have an array of these advertising the attributes | |
5006 | for its ports. Currently defined flags are <literal remap="tt">XvGettable</literal> | |
5007 | and <literal remap="tt">XvSettable</literal> which may be OR'd together indicating that | |
5008 | attribute is <quote>gettable</quote> or <quote>settable</quote> by the client. The | |
5009 | <literal remap="tt">min</literal> and <literal remap="tt">max</literal> field specify the valid range | |
5010 | for the value. <literal remap="tt">Name</literal> is a text string describing the | |
5011 | attribute by name. | |
5012 | </para> | |
5013 | ||
5014 | </blockquote></para></blockquote> | |
5015 | ||
5016 | </para> | |
5017 | ||
5018 | <para> | |
5019 | The XF86ImageRec: | |
5020 | ||
5021 | <blockquote><para> | |
5022 | <programlisting> | |
5023 | typedef struct { | |
5024 | int id; | |
5025 | int type; | |
5026 | int byte_order; | |
5027 | char guid[16]; | |
5028 | int bits_per_pixel; | |
5029 | int format; | |
5030 | int num_planes; | |
5031 | ||
5032 | /* for RGB formats */ | |
5033 | int depth; | |
5034 | unsigned int red_mask; | |
5035 | unsigned int green_mask; | |
5036 | unsigned int blue_mask; | |
5037 | ||
5038 | /* for YUV formats */ | |
5039 | unsigned int y_sample_bits; | |
5040 | unsigned int u_sample_bits; | |
5041 | unsigned int v_sample_bits; | |
5042 | unsigned int horz_y_period; | |
5043 | unsigned int horz_u_period; | |
5044 | unsigned int horz_v_period; | |
5045 | unsigned int vert_y_period; | |
5046 | unsigned int vert_u_period; | |
5047 | unsigned int vert_v_period; | |
5048 | char component_order[32]; | |
5049 | int scanline_order; | |
5050 | } XF86ImageRec, *XF86ImagePtr; | |
5051 | ||
5052 | </programlisting> | |
5053 | <blockquote><para> | |
5054 | XF86ImageRec describes how video source data is laid out in memory. | |
5055 | The fields are as follows: | |
5056 | ||
5057 | <variablelist> | |
5058 | <varlistentry> | |
5059 | <term><structfield>id</structfield></term> | |
5060 | <listitem><para> | |
5061 | This is a unique descriptor for the format. It is often good to | |
5062 | set this value to the FOURCC for the format when applicable. | |
5063 | </para></listitem></varlistentry> | |
5064 | ||
5065 | <varlistentry> | |
5066 | <term><structfield>type</structfield></term> | |
5067 | <listitem><para> | |
5068 | This is <constant>XvRGB</constant> or <constant>XvYUV</constant>. | |
5069 | </para></listitem></varlistentry> | |
5070 | ||
5071 | <varlistentry> | |
5072 | <term><structfield>byte_order</structfield></term> | |
5073 | <listitem><para> | |
5074 | This is <constant>LSBFirst</constant> or <constant>MSBFirst</constant>. | |
5075 | </para></listitem></varlistentry> | |
5076 | ||
5077 | <varlistentry> | |
5078 | <term><structfield>guid</structfield></term> | |
5079 | <listitem><para> | |
5080 | This is the Globally Unique IDentifier for the format. When | |
5081 | not applicable, all characters should be NULL. | |
5082 | </para></listitem></varlistentry> | |
5083 | ||
5084 | <varlistentry> | |
5085 | <term><structfield>bits_per_pixel</structfield></term> | |
5086 | <listitem><para> | |
5087 | The number of bits taken up (but not necessarily used) by each | |
5088 | pixel. Note that for some planar formats which have fractional | |
5089 | bits per pixel (such as IF09) this number may be rounded _down_. | |
5090 | </para></listitem></varlistentry> | |
5091 | ||
5092 | <varlistentry> | |
5093 | <term><structfield>format</structfield></term> | |
5094 | <listitem><para> | |
5095 | This is <constant>XvPlanar</constant> or <constant>XvPacked</constant>. | |
5096 | </para></listitem></varlistentry> | |
5097 | ||
5098 | <varlistentry> | |
5099 | <term><structfield>num_planes</structfield></term> | |
5100 | <listitem><para> | |
5101 | The number of planes in planar formats. This should be set to | |
5102 | one for packed formats. | |
5103 | </para></listitem></varlistentry> | |
5104 | ||
5105 | <varlistentry> | |
5106 | <term><structfield>depth</structfield></term> | |
5107 | <listitem><para> | |
5108 | The significant bits per pixel in RGB formats (analgous to the | |
5109 | depth of a pixmap format). | |
5110 | </para></listitem></varlistentry> | |
5111 | ||
5112 | <varlistentry> | |
5113 | <term><structfield>red_mask</structfield></term> | |
5114 | <term><structfield>green_mask</structfield></term> | |
5115 | <term><structfield>blue_mask</structfield></term> | |
5116 | <listitem><para> | |
5117 | The red, green and blue bitmasks for packed RGB formats. | |
5118 | </para></listitem></varlistentry> | |
5119 | ||
5120 | <varlistentry> | |
5121 | <term><structfield>y_sample_bits</structfield></term> | |
5122 | <term><structfield>u_sample_bits</structfield></term> | |
5123 | <term><structfield>v_sample_bits</structfield></term> | |
5124 | <listitem><para> | |
5125 | The y, u and v sample sizes (in bits). | |
5126 | </para></listitem></varlistentry> | |
5127 | ||
5128 | <varlistentry> | |
5129 | <term><structfield>horz_y_period</structfield></term> | |
5130 | <term><structfield>horz_u_period</structfield></term> | |
5131 | <term><structfield>horz_v_period</structfield></term> | |
5132 | <listitem><para> | |
5133 | The y, u and v sampling periods in the horizontal direction. | |
5134 | </para></listitem></varlistentry> | |
5135 | ||
5136 | <varlistentry> | |
5137 | <term><structfield>vert_y_period</structfield></term> | |
5138 | <term><structfield>vert_u_period</structfield></term> | |
5139 | <term><structfield>vert_v_period</structfield></term> | |
5140 | <listitem><para> | |
5141 | The y, u and v sampling periods in the vertical direction. | |
5142 | </para></listitem></varlistentry> | |
5143 | ||
5144 | <varlistentry> | |
5145 | <term><structfield>component_order</structfield></term> | |
5146 | <listitem><para> | |
5147 | Uppercase ascii characters representing the order that | |
5148 | samples are stored within packed formats. For planar formats | |
5149 | this represents the ordering of the planes. Unused characters | |
5150 | in the 32 byte string should be set to NULL. | |
5151 | </para></listitem></varlistentry> | |
5152 | ||
5153 | <varlistentry> | |
5154 | <term><structfield>scanline_order</structfield></term> | |
5155 | <listitem><para> | |
5156 | This is <constant>XvTopToBottom</constant> or <constant>XvBottomToTop</constant>. | |
5157 | </para></listitem></varlistentry> | |
5158 | ||
5159 | </variablelist> | |
5160 | </para> | |
5161 | ||
5162 | <para> | |
5163 | Since some formats (particular some planar YUV formats) may not | |
5164 | be completely defined by the parameters above, the guid, when | |
5165 | available, should provide the most accurate description of the | |
5166 | format. | |
5167 | </para> | |
5168 | ||
5169 | </blockquote></para></blockquote> | |
5170 | </para> | |
5171 | </sect1> | |
5172 | ||
5173 | <sect1> | |
5174 | <title>The Loader</title> | |
5175 | ||
5176 | <para> | |
5177 | This section describes the interfaces to the module loader. The loader | |
5178 | interfaces can be divided into two groups: those that are only available to | |
5179 | the XFree86 common layer, and those that are also available to modules. | |
5180 | </para> | |
5181 | ||
5182 | <sect2> | |
5183 | <title>Loader Overview</title> | |
5184 | ||
5185 | <para> | |
5186 | The loader is capable of loading modules in a range of object formats, | |
5187 | and knowledge of these formats is built in to the loader. Knowledge of | |
5188 | new object formats can be added to the loader in a straightforward | |
5189 | manner. This makes it possible to provide OS-independent modules (for | |
5190 | a given CPU architecture type). In addition to this, the loader can | |
5191 | load modules via the OS-provided <function>dlopen(3)</function> service where | |
5192 | available. Such modules are not platform independent, and the semantics | |
5193 | of <function>dlopen()</function> on most systems results in significant | |
5194 | limitations in the use of modules of this type. Support for | |
5195 | <function>dlopen()</function> modules in the loader is primarily for | |
5196 | experimental and development purposes. | |
5197 | </para> | |
5198 | ||
5199 | <para> | |
5200 | Symbols exported by the loader (on behalf of the core X server) to | |
5201 | modules are determined at compile time. Only those symbols explicitly | |
5202 | exported are available to modules. All external symbols of loaded | |
5203 | modules are exported to other modules, and to the core X server. The | |
5204 | loader can be requested to check for unresolved symbols at any time, | |
5205 | and the action to be taken for unresolved symbols can be controlled by | |
5206 | the caller of the loader. Typically the caller identifies which symbols | |
5207 | can safely remain unresolved and which cannot. | |
5208 | </para> | |
5209 | ||
5210 | <para> | |
5211 | NOTE: Now that ISO-C allows pointers to functions and pointers to data to | |
5212 | have different internal representations, some of the following interfaces | |
5213 | will need to be revisited. | |
5214 | </para> | |
5215 | </sect2> | |
5216 | ||
5217 | <sect2> | |
5218 | <title>Semi-private Loader Interface</title> | |
5219 | ||
5220 | <para> | |
5221 | The following is the semi-private loader interface that is available to the | |
5222 | XFree86 common layer. | |
5223 | </para> | |
5224 | ||
5225 | <blockquote><para> | |
5226 | <programlisting> | |
5227 | void LoaderInit(void); | |
5228 | </programlisting> | |
5229 | <blockquote><para> | |
5230 | The <function>LoaderInit()</function> function initialises the loader, | |
5231 | and it must be called once before calling any other loader functions. | |
5232 | This function initialises the tables of exported symbols, and anything | |
5233 | else that might need to be initialised. | |
5234 | </para> | |
5235 | ||
5236 | </blockquote></para></blockquote> | |
5237 | ||
5238 | <blockquote><para> | |
5239 | <programlisting> | |
5240 | void LoaderSetPath(const char *path); | |
5241 | </programlisting> | |
5242 | <blockquote><para> | |
5243 | The <function>LoaderSetPath()</function> function initialises a default | |
5244 | module search path. This must be called if calls to other functions | |
5245 | are to be made without explicitly specifying a module search path. | |
5246 | The search path <parameter>path</parameter> must be a string of one or more | |
5247 | comma separated absolute paths. Modules are expected to be located | |
5248 | below these paths, possibly in subdirectories of these paths. | |
5249 | </para> | |
5250 | ||
5251 | </blockquote></para></blockquote> | |
5252 | ||
5253 | <blockquote><para> | |
5254 | <programlisting> | |
5255 | pointer LoadModule(const char *module, const char *path, | |
5256 | const char **subdirlist, const char **patternlist, | |
5257 | pointer options, const XF86ModReqInfo * modreq, | |
5258 | int *errmaj, int *errmin); | |
5259 | </programlisting> | |
5260 | <blockquote><para> | |
5261 | The <function>LoadModule()</function> function loads the module called | |
5262 | <parameter>module</parameter>. The return value is a module handle, and | |
5263 | may be used in future calls to the loader that require a reference | |
5264 | to a loaded module. The module name <parameter>module</parameter> is | |
5265 | normally the module's canonical name, which doesn't contain any | |
5266 | directory path information, or any object/library file prefixes of | |
5267 | suffixes. Currently a full pathname and/or filename is also accepted. | |
5268 | This might change. The other parameters are: | |
5269 | ||
5270 | <variablelist> | |
5271 | <varlistentry> | |
5272 | <term><parameter>path</parameter></term> | |
5273 | <listitem><para> | |
5274 | An optional comma-separated list of module search paths. | |
5275 | When <constant>NULL</constant>, the default search path is used. | |
5276 | </para></listitem></varlistentry> | |
5277 | ||
5278 | ||
5279 | <varlistentry> | |
5280 | <term><parameter>subdirlist</parameter></term> | |
5281 | <listitem><para> | |
5282 | An optional <constant>NULL</constant> terminated list of | |
5283 | subdirectories to search. When <constant>NULL</constant>, | |
5284 | the default built-in list is used (refer to | |
5285 | <varname>stdSubdirs</varname> in <filename>loadmod.c</filename>). | |
5286 | The default list is also substituted for entries in | |
5287 | <parameter>subdirlist</parameter> with the value | |
5288 | <constant>DEFAULT_LIST</constant>. This makes is possible | |
5289 | to augment the default list instead of replacing it. | |
5290 | Subdir elements must be relative, and must not contain | |
5291 | <literal remap="tt">".."</literal>. If any violate this requirement, | |
5292 | the load fails. | |
5293 | </para></listitem></varlistentry> | |
5294 | ||
5295 | ||
5296 | <varlistentry> | |
5297 | <term><parameter>patternlist</parameter></term> | |
5298 | <listitem><para> | |
5299 | An optional <constant>NULL</constant> terminated list of | |
5300 | POSIX regular expressions used to connect module | |
5301 | filenames with canonical module names. Each regex | |
5302 | should contain exactly one subexpression that corresponds | |
5303 | to the canonical module name. When <constant>NULL</constant>, | |
5304 | the default built-in list is used (refer to | |
5305 | <varname>stdPatterns</varname> in | |
5306 | <filename>loadmod.c</filename>). The default list is also | |
5307 | substituted for entries in <parameter>patternlist</parameter> | |
5308 | with the value <constant>DEFAULT_LIST</constant>. This | |
5309 | makes it possible to augment the default list instead | |
5310 | of replacing it. | |
5311 | </para></listitem></varlistentry> | |
5312 | ||
5313 | ||
5314 | <varlistentry> | |
5315 | <term><parameter>options</parameter></term> | |
5316 | <listitem><para> | |
5317 | An optional parameter that is passed to the newly | |
5318 | loaded module's <literal remap="tt">SetupProc</literal> function | |
5319 | (if it has one). This argument is normally a | |
5320 | <constant>NULL</constant> terminated list of | |
5321 | <structname>Options</structname>, and must be interpreted that | |
5322 | way by modules loaded directly by the XFree86 common | |
5323 | layer. However, it may be used for application-specific | |
5324 | parameter passing in other situations. | |
5325 | </para></listitem></varlistentry> | |
5326 | ||
5327 | ||
5328 | <varlistentry> | |
5329 | <term><parameter>modreq</parameter></term> | |
5330 | <listitem><para> | |
5331 | An optional <structname>XF86ModReqInfo*</structname> containing | |
5332 | version/ABI/vendor information to requirements to | |
5333 | check the newly loaded module against. The main | |
5334 | purpose of this is to allow the loader to verify that | |
5335 | a module of the correct type/version before running | |
5336 | its <function>SetupProc</function> function. | |
5337 | </para> | |
5338 | ||
5339 | <para> | |
5340 | The <literal remap="tt">XF86ModReqInfo</literal> struct is defined | |
5341 | as follows: | |
5342 | <programlisting> | |
5343 | typedef struct { | |
5344 | CARD8 majorversion; /* MAJOR_UNSPEC */ | |
5345 | CARD8 minorversion; /* MINOR_UNSPEC */ | |
5346 | CARD16 patchlevel; /* PATCH_UNSPEC */ | |
5347 | const char * abiclass; /* ABI_CLASS_NONE */ | |
5348 | CARD32 abiversion; /* ABI_VERS_UNSPEC */ | |
5349 | const char * moduleclass; /* MOD_CLASS_NONE */ | |
5350 | } XF86ModReqInfo; | |
5351 | </programlisting> | |
5352 | ||
5353 | The information here is compared against the equivalent | |
5354 | information in the module's | |
5355 | <structname>XF86ModuleVersionInfo</structname> record (which | |
5356 | is described below). The values in comments above | |
5357 | indicate <quote>don't care</quote> settings for each of the fields. | |
5358 | The comparisons made are as follows: | |
5359 | ||
5360 | <variablelist> | |
5361 | <varlistentry> | |
5362 | <term><structfield>majorversion</structfield></term> | |
5363 | <listitem><para> | |
5364 | Must match the module's majorversion | |
5365 | exactly. | |
5366 | </para></listitem></varlistentry> | |
5367 | ||
5368 | <varlistentry> | |
5369 | <term><structfield>minorversion</structfield></term> | |
5370 | <listitem><para> | |
5371 | The module's minor version must be | |
5372 | no less than this value. This | |
5373 | comparison is only made if | |
5374 | <structfield>majorversion</structfield> is | |
5375 | specified and matches. | |
5376 | </para></listitem></varlistentry> | |
5377 | ||
5378 | <varlistentry> | |
5379 | <term><structfield>patchlevel</structfield></term> | |
5380 | <listitem><para> | |
5381 | The module's patchlevel must be no | |
5382 | less than this value. This comparison | |
5383 | is only made if | |
5384 | <structfield>minorversion</structfield> is | |
5385 | specified and matches. | |
5386 | </para></listitem></varlistentry> | |
5387 | ||
5388 | <varlistentry> | |
5389 | <term><structfield>abiclass</structfield></term> | |
5390 | <listitem><para> | |
5391 | String must match the module's abiclass | |
5392 | string. | |
5393 | </para></listitem></varlistentry> | |
5394 | ||
5395 | <varlistentry> | |
5396 | <term><structfield>abiversion</structfield></term> | |
5397 | <listitem><para> | |
5398 | Must be consistent with the module's | |
5399 | abiversion (major equal, minor no | |
5400 | older). | |
5401 | </para></listitem></varlistentry> | |
5402 | ||
5403 | <varlistentry> | |
5404 | <term><structfield>moduleclass</structfield></term> | |
5405 | <listitem><para> | |
5406 | String must match the module's | |
5407 | moduleclass string. | |
5408 | </para></listitem></varlistentry> | |
5409 | ||
5410 | </variablelist> | |
5411 | </para></listitem></varlistentry> | |
5412 | ||
5413 | <varlistentry> | |
5414 | <term><parameter>errmaj</parameter></term> | |
5415 | <listitem><para> | |
5416 | An optional pointer to a variable holding the major | |
5417 | part or the error code. When provided, | |
5418 | <parameter>*errmaj</parameter> is filled in when | |
5419 | <function>LoadModule()</function> fails. | |
5420 | </para></listitem></varlistentry> | |
5421 | ||
5422 | <varlistentry> | |
5423 | <term><parameter>errmin</parameter></term> | |
5424 | <listitem><para> | |
5425 | Like <parameter>errmaj</parameter>, but for the minor part | |
5426 | of the error code. | |
5427 | </para></listitem></varlistentry> | |
5428 | ||
5429 | </variablelist> | |
5430 | ||
5431 | </para></blockquote> | |
5432 | </para></blockquote> | |
5433 | ||
5434 | <blockquote><para> | |
5435 | <programlisting> | |
5436 | void UnloadModule(pointer mod); | |
5437 | </programlisting> | |
5438 | <blockquote><para> | |
5439 | This function unloads the module referred to by the handle mod. | |
5440 | All child modules are also unloaded recursively. This function must | |
5441 | not be used to directly unload modules that are child modules (i.e., | |
5442 | those that have been loaded with the <function>LoadSubModule()</function> | |
5443 | described below). | |
5444 | </para> | |
5445 | ||
5446 | </blockquote></para></blockquote> | |
5447 | </sect2> | |
5448 | ||
5449 | <sect2> | |
5450 | <title>Module Requirements</title> | |
5451 | ||
5452 | <para> | |
5453 | Modules must provide information about themselves to the loader, and | |
5454 | may optionally provide entry points for "setup" and "teardown" functions | |
5455 | (those two functions are referred to here as <function>SetupProc</function> | |
5456 | and <function>TearDownProc</function>). | |
5457 | </para> | |
5458 | ||
5459 | <para> | |
5460 | The module information is contained in the | |
5461 | <structname>XF86ModuleVersionInfo</structname> struct, which is defined as follows: | |
5462 | ||
5463 | <programlisting> | |
5464 | typedef struct { | |
5465 | const char * modname; /* name of module, e.g. "foo" */ | |
5466 | const char * vendor; /* vendor specific string */ | |
5467 | CARD32 _modinfo1_; /* constant MODINFOSTRING1/2 to find */ | |
5468 | CARD32 _modinfo2_; /* infoarea with a binary editor/sign tool */ | |
5469 | CARD32 xf86version; /* contains XF86_VERSION_CURRENT */ | |
5470 | CARD8 majorversion; /* module-specific major version */ | |
5471 | CARD8 minorversion; /* module-specific minor version */ | |
5472 | CARD16 patchlevel; /* module-specific patch level */ | |
5473 | const char * abiclass; /* ABI class that the module uses */ | |
5474 | CARD32 abiversion; /* ABI version */ | |
5475 | const char * moduleclass; /* module class */ | |
5476 | CARD32 checksum[4]; /* contains a digital signature of the */ | |
5477 | /* version info structure */ | |
5478 | } XF86ModuleVersionInfo; | |
5479 | </programlisting> | |
5480 | ||
5481 | The fields are used as follows: | |
5482 | ||
5483 | <variablelist> | |
5484 | <varlistentry> | |
5485 | <term><structfield>modname</structfield></term> | |
5486 | <listitem><para> | |
5487 | The module's name. This field is currently only for | |
5488 | informational purposes, but the loader may be modified | |
5489 | in future to require it to match the module's canonical | |
5490 | name. | |
5491 | </para></listitem></varlistentry> | |
5492 | ||
5493 | ||
5494 | <varlistentry> | |
5495 | <term><structfield>vendor</structfield></term> | |
5496 | <listitem><para> | |
5497 | The module vendor. This field is for informational purposes | |
5498 | only. | |
5499 | </para></listitem></varlistentry> | |
5500 | ||
5501 | ||
5502 | <varlistentry> | |
5503 | <term><structfield>_modinfo1_</structfield></term> | |
5504 | <listitem><para> | |
5505 | This field holds the first part of a signature that can | |
5506 | be used to locate this structure in the binary. It should | |
5507 | always be initialised to <constant>MODINFOSTRING1</constant>. | |
5508 | </para></listitem></varlistentry> | |
5509 | ||
5510 | ||
5511 | <varlistentry> | |
5512 | <term><structfield>_modinfo2_</structfield></term> | |
5513 | <listitem><para> | |
5514 | This field holds the second part of a signature that can | |
5515 | be used to locate this structure in the binary. It should | |
5516 | always be initialised to <constant>MODINFOSTRING2</constant>. | |
5517 | </para></listitem></varlistentry> | |
5518 | ||
5519 | ||
5520 | <varlistentry> | |
5521 | <term><structfield>xf86version</structfield></term> | |
5522 | <listitem><para> | |
5523 | The XFree86 version against which the module was compiled. | |
5524 | This is mostly for informational/diagnostic purposes. It | |
5525 | should be initialised to <constant>XF86_VERSION_CURRENT</constant>, which is | |
5526 | defined in <filename>xf86Version.h</filename>. | |
5527 | </para></listitem></varlistentry> | |
5528 | ||
5529 | ||
5530 | <varlistentry> | |
5531 | <term><structfield>majorversion</structfield></term> | |
5532 | <listitem><para> | |
5533 | The module-specific major version. For modules where this | |
5534 | version is used for more than simply informational | |
5535 | purposes, the major version should only change (be | |
5536 | incremented) when ABI incompatibilities are introduced, | |
5537 | or ABI components are removed. | |
5538 | </para></listitem></varlistentry> | |
5539 | ||
5540 | ||
5541 | <varlistentry> | |
5542 | <term><structfield>minorversion</structfield></term> | |
5543 | <listitem><para> | |
5544 | The module-specific minor version. For modules where this | |
5545 | version is used for more than simply informational | |
5546 | purposes, the minor version should only change (be | |
5547 | incremented) when ABI additions are made in a backward | |
5548 | compatible way. It should be reset to zero when the major | |
5549 | version is increased. | |
5550 | </para></listitem></varlistentry> | |
5551 | ||
5552 | ||
5553 | <varlistentry> | |
5554 | <term><structfield>patchlevel</structfield></term> | |
5555 | <listitem><para> | |
5556 | The module-specific patch level. The patch level should | |
5557 | increase with new revisions of the module where there | |
5558 | are no ABI changes, and it should be reset to zero when | |
5559 | the minor version is increased. | |
5560 | </para></listitem></varlistentry> | |
5561 | ||
5562 | ||
5563 | <varlistentry> | |
5564 | <term><structfield>abiclass</structfield></term> | |
5565 | <listitem><para> | |
5566 | The ABI class that the module requires. The class is | |
5567 | specified as a string for easy extensibility. It should | |
5568 | indicate which (if any) of the X server's built-in ABI | |
5569 | classes that the module relies on, or a third-party ABI | |
5570 | if appropriate. Built-in ABI classes currently defined are: | |
5571 | ||
5572 | <variablelist> | |
5573 | <varlistentry> | |
5574 | <term><constant>ABI_CLASS_NONE</constant></term> | |
5575 | <listitem><para>no class | |
5576 | </para></listitem></varlistentry> | |
5577 | <varlistentry> | |
5578 | <term><constant>ABI_CLASS_ANSIC</constant></term> | |
5579 | <listitem><para>only requires the ANSI C interfaces | |
5580 | </para></listitem></varlistentry> | |
5581 | <varlistentry> | |
5582 | <term><constant>ABI_CLASS_VIDEODRV</constant></term> | |
5583 | <listitem><para>requires the video driver ABI | |
5584 | </para></listitem></varlistentry> | |
5585 | <varlistentry> | |
5586 | <term><constant>ABI_CLASS_XINPUT</constant></term> | |
5587 | <listitem><para>requires the XInput driver ABI | |
5588 | </para></listitem></varlistentry> | |
5589 | <varlistentry> | |
5590 | <term><constant>ABI_CLASS_EXTENSION</constant></term> | |
5591 | <listitem><para>requires the extension module ABI | |
5592 | </para></listitem></varlistentry> | |
5593 | <varlistentry> | |
5594 | <term><constant>ABI_CLASS_FONT</constant></term> | |
5595 | <listitem><para>requires the font module ABI | |
5596 | </para></listitem></varlistentry> | |
5597 | </variablelist> | |
5598 | ||
5599 | </para></listitem></varlistentry> | |
5600 | ||
5601 | <varlistentry> | |
5602 | <term><structfield>abiversion</structfield></term> | |
5603 | <listitem><para> | |
5604 | The version of abiclass that the module requires. The | |
5605 | version consists of major and minor components. The | |
5606 | major version must match and the minor version must be | |
5607 | no newer than that provided by the server or parent | |
5608 | module. Version identifiers for the built-in classes | |
5609 | currently defined are: | |
5610 | ||
5611 | <literallayout><constant> | |
5612 | ABI_ANSIC_VERSION | |
5613 | ABI_VIDEODRV_VERSION | |
5614 | ABI_XINPUT_VERSION | |
5615 | ABI_EXTENSION_VERSION | |
5616 | ABI_FONT_VERSION | |
5617 | </constant></literallayout> | |
5618 | ||
5619 | </para></listitem></varlistentry> | |
5620 | ||
5621 | <varlistentry> | |
5622 | <term><structfield>moduleclass</structfield></term> | |
5623 | <listitem><para> | |
5624 | This is similar to the abiclass field, except that it | |
5625 | defines the type of module rather than the ABI it | |
5626 | requires. For example, although all video drivers require | |
5627 | the video driver ABI, not all modules that require the | |
5628 | video driver ABI are video drivers. This distinction | |
5629 | can be made with the moduleclass. Currently pre-defined | |
5630 | module classes are: | |
5631 | ||
5632 | <literallayout><constant> | |
5633 | MOD_CLASS_NONE | |
5634 | MOD_CLASS_VIDEODRV | |
5635 | MOD_CLASS_XINPUT | |
5636 | MOD_CLASS_FONT | |
5637 | MOD_CLASS_EXTENSION | |
5638 | </constant></literallayout> | |
5639 | ||
5640 | </para></listitem></varlistentry> | |
5641 | ||
5642 | <varlistentry> | |
5643 | <term><structfield>checksum</structfield></term> | |
5644 | <listitem><para> | |
5645 | Not currently used. | |
5646 | </para></listitem></varlistentry> | |
5647 | ||
5648 | </variablelist> | |
5649 | </para> | |
5650 | ||
5651 | <para> | |
5652 | The module version information, and the optional <function>SetupProc</function> | |
5653 | and <function>TearDownProc</function> entry points are found by the loader | |
5654 | by locating a data object in the module called "modnameModuleData", | |
5655 | where "modname" is the canonical name of the module. Modules must | |
5656 | contain such a data object, and it must be declared with global scope, | |
5657 | be compile-time initialised, and is of the following type: | |
5658 | ||
5659 | <programlisting> | |
5660 | typedef struct { | |
5661 | XF86ModuleVersionInfo * vers; | |
5662 | ModuleSetupProc setup; | |
5663 | ModuleTearDownProc teardown; | |
5664 | } XF86ModuleData; | |
5665 | </programlisting> | |
5666 | </para> | |
5667 | ||
5668 | <para> | |
5669 | The vers parameter must be initialised to a pointer to a correctly | |
5670 | initialised <structname>XF86ModuleVersionInfo</structname> struct. The other | |
5671 | two parameter are optional, and should be initialised to | |
5672 | <constant>NULL</constant> when not required. The other parameters are defined | |
5673 | as | |
5674 | ||
5675 | <blockquote><para> | |
5676 | <programlisting> | |
5677 | typedef pointer (*ModuleSetupProc)(pointer, pointer, int *, int *); | |
5678 | ||
5679 | typedef void (*ModuleTearDownProc)(pointer); | |
5680 | ||
5681 | pointer SetupProc(pointer module, pointer options, | |
5682 | int *errmaj, int *errmin); | |
5683 | </programlisting> | |
5684 | <blockquote><para> | |
5685 | When defined, this function is called by the loader after successfully | |
5686 | loading a module. module is a handle for the newly loaded module, | |
5687 | and maybe used by the <function>SetupProc</function> if it calls other | |
5688 | loader functions that require a reference to it. The remaining | |
5689 | arguments are those that were passed to the | |
5690 | <function>LoadModule()</function> (or <function>LoadSubModule()</function>), | |
5691 | and are described above. When the <function>SetupProc</function> is | |
5692 | successful it must return a non-<constant>NULL</constant> value. The | |
5693 | loader checks this, and if it is <constant>NULL</constant> it unloads | |
5694 | the module and reports the failure to the caller of | |
5695 | <function>LoadModule()</function>. If the <function>SetupProc</function> | |
5696 | does things that need to be undone when the module is unloaded, | |
5697 | it should define a <function>TearDownProc</function>, and return a | |
5698 | pointer that the <function>TearDownProc</function> can use to undo what | |
5699 | has been done. | |
5700 | </para> | |
5701 | ||
5702 | <para> | |
5703 | When a module is loaded multiple times, the <function>SetupProc</function> | |
5704 | is called once for each time it is loaded. | |
5705 | </para> | |
5706 | ||
5707 | </blockquote></para></blockquote> | |
5708 | ||
5709 | <blockquote><para> | |
5710 | <programlisting> | |
5711 | void TearDownProc(pointer tearDownData); | |
5712 | </programlisting> | |
5713 | <blockquote><para> | |
5714 | When defined, this function is called when the loader unloads a | |
5715 | module. The <parameter>tearDownData</parameter> parameter is the return | |
5716 | value of the <function>SetupProc()</function> that was called when the | |
5717 | module was loaded. The purpose of this function is to clean up | |
5718 | before the module is unloaded (for example, by freeing allocated | |
5719 | resources). | |
5720 | </para> | |
5721 | ||
5722 | </blockquote></para></blockquote> | |
5723 | </para> | |
5724 | </sect2> | |
5725 | ||
5726 | <sect2> | |
5727 | <title>Public Loader Interface</title> | |
5728 | ||
5729 | <para> | |
5730 | The following is the Loader interface that is available to any part of | |
5731 | the server, and may also be used from within modules. | |
5732 | </para> | |
5733 | ||
5734 | <blockquote><para> | |
5735 | <programlisting> | |
5736 | pointer LoadSubModule(pointer parent, const char *module, | |
5737 | const char **subdirlist, const char **patternlist, | |
5738 | pointer options, const XF86ModReqInfo * modreq, | |
5739 | int *errmaj, int *errmin); | |
5740 | </programlisting> | |
5741 | <blockquote><para> | |
5742 | This function is like the <function>LoadModule()</function> function | |
5743 | described above, except that the module loaded is registered as a | |
5744 | child of the calling module. The <parameter>parent</parameter> parameter | |
5745 | is the calling module's handle. Modules loaded with this function | |
5746 | are automatically unloaded when the parent module is unloaded. The | |
5747 | other difference is that the path parameter may not be specified. | |
5748 | The module search path used for modules loaded with this function | |
5749 | is the default search path as initialised with | |
5750 | <function>LoaderSetPath()</function>. | |
5751 | </para> | |
5752 | ||
5753 | </blockquote></para></blockquote> | |
5754 | ||
5755 | <blockquote><para> | |
5756 | <programlisting> | |
5757 | void UnloadSubModule(pointer module); | |
5758 | </programlisting> | |
5759 | <blockquote><para> | |
5760 | This function unloads the module with handle <parameter>module</parameter>. | |
5761 | If that module itself has children, they are also unloaded. It is | |
5762 | like <function>UnloadModule()</function>, except that it is safe to use | |
5763 | for unloading child modules. | |
5764 | </para> | |
5765 | ||
5766 | </blockquote></para></blockquote> | |
5767 | ||
5768 | <blockquote><para> | |
5769 | <programlisting> | |
5770 | pointer LoaderSymbol(const char *symbol); | |
5771 | </programlisting> | |
5772 | <blockquote><para> | |
5773 | This function returns the address of the symbol with name | |
5774 | <parameter>symbol</parameter>. This may be used to locate a module entry | |
5775 | point with a known name. | |
5776 | </para> | |
5777 | ||
5778 | </blockquote></para></blockquote> | |
5779 | ||
5780 | <blockquote><para> | |
5781 | <programlisting> | |
5782 | char **LoaderlistDirs(const char **subdirlist, | |
5783 | const char **patternlist); | |
5784 | </programlisting> | |
5785 | <blockquote><para> | |
5786 | This function returns a <constant>NULL</constant> terminated list of | |
5787 | canonical modules names for modules found in the default module | |
5788 | search path. The <parameter>subdirlist</parameter> and | |
5789 | <parameter>patternlist</parameter> parameters are as described above, and | |
5790 | can be used to control the locations and names that are searched. | |
5791 | If no modules are found, the return value is <constant>NULL</constant>. | |
5792 | The returned list should be freed by calling | |
5793 | <function>LoaderFreeDirList()</function> when it is no longer needed. | |
5794 | </para> | |
5795 | ||
5796 | </blockquote></para></blockquote> | |
5797 | ||
5798 | <blockquote><para> | |
5799 | <programlisting> | |
5800 | void LoaderFreeDirList(char **list); | |
5801 | </programlisting> | |
5802 | <blockquote><para> | |
5803 | This function frees a module list created by | |
5804 | <function>LoaderlistDirs()</function>. | |
5805 | </para> | |
5806 | ||
5807 | </blockquote></para></blockquote> | |
5808 | ||
5809 | <blockquote><para> | |
5810 | <programlisting> | |
5811 | void LoaderReqSymLists(const char **list0, ...); | |
5812 | </programlisting> | |
5813 | <blockquote><para> | |
5814 | This function allows the registration of required symbols with the | |
5815 | loader. It is normally used by a caller of | |
5816 | <function>LoadSubModule()</function>. If any symbols registered in this | |
5817 | way are found to be unresolved when | |
5818 | <function>LoaderCheckUnresolved()</function> is called then | |
5819 | <function>LoaderCheckUnresolved()</function> will report a failure. | |
5820 | The function takes one or more <constant>NULL</constant> terminated | |
5821 | lists of symbols. The end of the argument list is indicated by a | |
5822 | <constant>NULL</constant> argument. | |
5823 | </para> | |
5824 | ||
5825 | </blockquote></para></blockquote> | |
5826 | ||
5827 | <blockquote><para> | |
5828 | <programlisting> | |
5829 | void LoaderReqSymbols(const char *sym0, ...); | |
5830 | </programlisting> | |
5831 | <blockquote><para> | |
5832 | This function is like <function>LoaderReqSymLists()</function> except | |
5833 | that its arguments are symbols rather than lists of symbols. This | |
5834 | function is more convenient when single functions are to be registered, | |
5835 | especially when the single function might depend on runtime factors. | |
5836 | The end of the argument list is indicated by a <constant>NULL</constant> | |
5837 | argument. | |
5838 | </para> | |
5839 | ||
5840 | </blockquote></para></blockquote> | |
5841 | ||
5842 | <blockquote><para> | |
5843 | <programlisting> | |
5844 | void LoaderRefSymLists(const char **list0, ...); | |
5845 | </programlisting> | |
5846 | <blockquote><para> | |
5847 | This function allows the registration of possibly unresolved symbols | |
5848 | with the loader. When <function>LoaderCheckUnresolved()</function> is | |
5849 | run it won't generate warnings for symbols registered in this way | |
5850 | unless they were also registered as required symbols. | |
5851 | The function takes one or more <constant>NULL</constant> terminated | |
5852 | lists of symbols. The end of the argument list is indicated by a | |
5853 | <constant>NULL</constant> argument. | |
5854 | </para> | |
5855 | ||
5856 | </blockquote></para></blockquote> | |
5857 | ||
5858 | <blockquote><para> | |
5859 | <programlisting> | |
5860 | void LoaderRefSymbols(const char *sym0, ...); | |
5861 | </programlisting> | |
5862 | <blockquote><para> | |
5863 | This function is like <function>LoaderRefSymLists()</function> except | |
5864 | that its arguments are symbols rather than lists of symbols. This | |
5865 | function is more convenient when single functions are to be registered, | |
5866 | especially when the single function might depend on runtime factors. | |
5867 | The end of the argument list is indicated by a <constant>NULL</constant> | |
5868 | argument. | |
5869 | </para> | |
5870 | ||
5871 | </blockquote></para></blockquote> | |
5872 | ||
5873 | <blockquote><para> | |
5874 | <programlisting> | |
5875 | int LoaderCheckUnresolved(int delayflag); | |
5876 | </programlisting> | |
5877 | <blockquote><para> | |
5878 | This function checks for unresolved symbols. It generates warnings | |
5879 | for unresolved symbols that have not been registered with | |
5880 | <function>LoaderRefSymLists()</function>, and maps them to a dummy | |
5881 | function. This behaviour may change in future. If unresolved | |
5882 | symbols are found that have been registered with | |
5883 | <function>LoaderReqSymLists()</function> or | |
5884 | <function>LoaderReqSymbols()</function> then this function returns a | |
5885 | non-zero value. If none of these symbols are unresolved the return | |
5886 | value is zero, indicating success. | |
5887 | </para> | |
5888 | ||
5889 | <para> | |
5890 | The <parameter>delayflag</parameter> parameter should normally be set to | |
5891 | <constant>LD_RESOLV_IFDONE</constant>. | |
5892 | </para> | |
5893 | ||
5894 | </blockquote></para></blockquote> | |
5895 | ||
5896 | <blockquote><para> | |
5897 | <programlisting> | |
5898 | LoaderErrorMsg(const char *name, const char *modname, | |
5899 | int errmaj, int errmin); | |
5900 | </programlisting> | |
5901 | <blockquote><para> | |
5902 | This function prints an error message that includes the text <quote>Failed | |
5903 | to load module</quote>, the module name <parameter>modname</parameter>, a message | |
5904 | specific to the <parameter>errmaj</parameter> value, and the value if | |
5905 | <parameter>errmin</parameter>. If <parameter>name</parameter> is | |
5906 | non-<constant>NULL</constant>, it is printed as an identifying prefix | |
5907 | to the message (followed by a <quote>:</quote>). | |
5908 | </para> | |
5909 | ||
5910 | </blockquote></para></blockquote> | |
5911 | </sect2> | |
5912 | ||
5913 | <sect2> | |
5914 | <title>Special Registration Functions</title> | |
5915 | ||
5916 | <para> | |
5917 | The loader contains some functions for registering some classes of modules. | |
5918 | These may be moved out of the loader at some point. | |
5919 | </para> | |
5920 | ||
5921 | <blockquote><para> | |
5922 | <programlisting> | |
5923 | void LoadExtension(ExtensionModule *ext); | |
5924 | </programlisting> | |
5925 | <blockquote><para> | |
5926 | This registers the entry points for the extension identified by | |
5927 | <parameter>ext</parameter>. The <structname>ExtensionModule</structname> struct is | |
5928 | defined as: | |
5929 | ||
5930 | <programlisting> | |
5931 | typedef struct { | |
5932 | InitExtension initFunc; | |
5933 | char * name; | |
5934 | Bool *disablePtr; | |
5935 | } ExtensionModule; | |
5936 | </programlisting> | |
5937 | </para> | |
5938 | ||
5939 | </blockquote></para></blockquote> | |
5940 | ||
5941 | </sect2> | |
5942 | ||
5943 | </sect1> | |
5944 | ||
5945 | <sect1> | |
5946 | <title>Helper Functions</title> | |
5947 | ||
5948 | <para> | |
5949 | This section describe <quote>helper</quote> functions that video driver | |
5950 | might find useful. While video drivers are not required to use any of | |
5951 | these to be considered <quote>compliant</quote>, the use of appropriate helpers is | |
5952 | strongly encouraged to improve the consistency of driver behaviour. | |
5953 | </para> | |
5954 | ||
5955 | <sect2> | |
5956 | <title>Functions for printing messages</title> | |
5957 | ||
5958 | <blockquote><para> | |
5959 | <programlisting> | |
5960 | ErrorF(const char *format, ...); | |
5961 | </programlisting> | |
5962 | <blockquote><para> | |
5963 | This is the basic function for writing to the error log (typically | |
5964 | stderr and/or a log file). Video drivers should usually avoid | |
5965 | using this directly in favour of the more specialised functions | |
5966 | described below. This function is useful for printing messages | |
5967 | while debugging a driver. | |
5968 | </para> | |
5969 | ||
5970 | </blockquote></para></blockquote> | |
5971 | ||
5972 | <blockquote><para> | |
5973 | <programlisting> | |
5974 | FatalError(const char *format, ...); | |
5975 | </programlisting> | |
5976 | <blockquote><para> | |
5977 | This prints a message and causes the Xserver to abort. It should | |
5978 | rarely be used within a video driver, as most error conditions | |
5979 | should be flagged by the return values of the driver functions. | |
5980 | This allows the higher layers to decide how to proceed. In rare | |
5981 | cases, this can be used within a driver if a fatal unexpected | |
5982 | condition is found. | |
5983 | </para> | |
5984 | ||
5985 | </blockquote></para></blockquote> | |
5986 | ||
5987 | <blockquote><para> | |
5988 | <programlisting> | |
5989 | xf86ErrorF(const char *format, ...); | |
5990 | </programlisting> | |
5991 | <blockquote><para> | |
5992 | This is like <function>ErrorF()</function>, except that the message is | |
5993 | only printed when the Xserver's verbosity level is set to the | |
5994 | default (<constant>1</constant>) or higher. It means that the messages | |
5995 | are not printed when the server is started with the | |
5996 | <option>-quiet</option> flag. Typically this function would only be | |
5997 | used for continuing messages started with one of the more specialised | |
5998 | functions described below. | |
5999 | </para> | |
6000 | ||
6001 | </blockquote></para></blockquote> | |
6002 | ||
6003 | <blockquote><para> | |
6004 | <programlisting> | |
6005 | xf86ErrorFVerb(int verb, const char *format, ...); | |
6006 | </programlisting> | |
6007 | <blockquote><para> | |
6008 | Like <function>xf86ErrorF()</function>, except the minimum verbosity | |
6009 | level for which the message is to be printed is given explicitly. | |
6010 | Passing a <parameter>verb</parameter> value of zero means the message | |
6011 | is always printed. A value higher than <constant>1</constant> can be | |
6012 | used for information would normally not be needed, but which might | |
6013 | be useful when diagnosing problems. | |
6014 | </para> | |
6015 | ||
6016 | </blockquote></para></blockquote> | |
6017 | ||
6018 | ||
6019 | <blockquote><para> | |
6020 | <programlisting> | |
6021 | xf86Msg(MessageType type, const char *format, ...); | |
6022 | </programlisting> | |
6023 | <blockquote><para> | |
6024 | This is like <function>xf86ErrorF()</function>, except that the message | |
6025 | is prefixed with a marker determined by the value of | |
6026 | <parameter>type</parameter>. The marker is used to indicate the type of | |
6027 | message (warning, error, probed value, config value, etc). Note | |
6028 | the <varname>xf86Verbose</varname> value is ignored for messages of | |
6029 | type <constant>X_ERROR</constant>. | |
6030 | </para> | |
6031 | ||
6032 | <para> | |
6033 | The marker values are: | |
6034 | ||
6035 | <variablelist> | |
6036 | <varlistentry> | |
6037 | <term><constant>X_PROBED</constant></term> | |
6038 | <listitem><para>Value was probed. | |
6039 | </para></listitem></varlistentry> | |
6040 | <varlistentry> | |
6041 | <term><constant>X_CONFIG</constant></term> | |
6042 | <listitem><para>Value was given in the config file. | |
6043 | </para></listitem></varlistentry> | |
6044 | <varlistentry> | |
6045 | <term><constant>X_DEFAULT</constant></term> | |
6046 | <listitem><para>Value is a default. | |
6047 | </para></listitem></varlistentry> | |
6048 | <varlistentry> | |
6049 | <term><constant>X_CMDLINE</constant></term> | |
6050 | <listitem><para>Value was given on the command line. | |
6051 | </para></listitem></varlistentry> | |
6052 | <varlistentry> | |
6053 | <term><constant>X_NOTICE</constant></term> | |
6054 | <listitem><para>Notice. | |
6055 | </para></listitem></varlistentry> | |
6056 | <varlistentry> | |
6057 | <term><constant>X_ERROR</constant></term> | |
6058 | <listitem><para>Error message. | |
6059 | </para></listitem></varlistentry> | |
6060 | <varlistentry> | |
6061 | <term><constant>X_WARNING</constant></term> | |
6062 | <listitem><para>Warning message. | |
6063 | </para></listitem></varlistentry> | |
6064 | <varlistentry> | |
6065 | <term><constant>X_INFO</constant></term> | |
6066 | <listitem><para>Informational message. | |
6067 | </para></listitem></varlistentry> | |
6068 | <varlistentry> | |
6069 | <term><constant>X_NONE</constant></term> | |
6070 | <listitem><para>No prefix. | |
6071 | </para></listitem></varlistentry> | |
6072 | <varlistentry> | |
6073 | <term><constant>X_NOT_IMPLEMENTED</constant></term> | |
6074 | <listitem><para>The message relates to functionality | |
6075 | that is not yetimplemented. | |
6076 | </para></listitem></varlistentry> | |
6077 | </variablelist> | |
6078 | ||
6079 | </para> | |
6080 | ||
6081 | </blockquote></para></blockquote> | |
6082 | ||
6083 | <blockquote><para> | |
6084 | <programlisting> | |
6085 | xf86MsgVerb(MessageType type, int verb, const char *format, ...); | |
6086 | </programlisting> | |
6087 | <blockquote><para> | |
6088 | Like <function>xf86Msg()</function>, but with the verbosity level given | |
6089 | explicitly. | |
6090 | </para> | |
6091 | ||
6092 | </blockquote></para></blockquote> | |
6093 | ||
6094 | <blockquote><para> | |
6095 | <programlisting> | |
6096 | xf86DrvMsg(int scrnIndex, MessageType type, const char *format, ...); | |
6097 | </programlisting> | |
6098 | <blockquote><para> | |
6099 | This is like <function>xf86Msg()</function> except that the driver's | |
6100 | name (the <structfield>name</structfield> field of the | |
6101 | <structname>ScrnInfoRec</structname>) followed by the | |
6102 | <parameter>scrnIndex</parameter> in parentheses is printed following the | |
6103 | prefix. This should be used by video drivers in most cases as it | |
6104 | clearly indicates which driver/screen the message is for. If | |
6105 | <parameter>scrnIndex</parameter> is negative, this function behaves | |
6106 | exactly like <function>xf86Msg()</function>. | |
6107 | </para> | |
6108 | ||
6109 | <para> | |
6110 | NOTE: This function can only be used after the | |
6111 | <structname>ScrnInfoRec</structname> and its <structfield>name</structfield> field | |
6112 | have been allocated. Normally, this means that it can not be | |
6113 | used before the END of the <function>ChipProbe()</function> function. | |
6114 | Prior to that, use <function>xf86Msg()</function>, providing the | |
6115 | driver's name explicitly. No screen number can be supplied at | |
6116 | that point. | |
6117 | </para> | |
6118 | ||
6119 | </blockquote></para></blockquote> | |
6120 | ||
6121 | <blockquote><para> | |
6122 | <programlisting> | |
6123 | xf86DrvMsgVerb(int scrnIndex, MessageType type, int verb, | |
6124 | const char *format, ...); | |
6125 | </programlisting> | |
6126 | <blockquote><para> | |
6127 | Like <function>xf86DrvMsg()</function>, but with the verbosity level | |
6128 | given explicitly. | |
6129 | </para> | |
6130 | ||
6131 | </blockquote></para></blockquote> | |
6132 | </sect2> | |
6133 | ||
6134 | ||
6135 | <sect2> | |
6136 | <title>Functions for setting values based on command line and config file</title> | |
6137 | ||
6138 | <blockquote><para> | |
6139 | <programlisting> | |
6140 | Bool xf86SetDepthBpp(ScrnInfoPtr scrp, int depth, int bpp, | |
6141 | ||
6142 | int fbbpp, int depth24flags); | |
6143 | </programlisting> | |
6144 | <blockquote><para> | |
6145 | This function sets the <structfield>depth</structfield>, <structfield>pixmapBPP</structfield> and <structfield>bitsPerPixel</structfield> fields | |
6146 | of the <structname>ScrnInfoRec</structname>. It also determines the defaults for display-wide | |
6147 | attributes and pixmap formats the screen will support, and finds | |
6148 | the Display subsection that matches the depth/bpp. This function | |
6149 | should normally be called very early from the | |
6150 | <function>ChipPreInit()</function> function. | |
6151 | </para> | |
6152 | ||
6153 | <para> | |
6154 | It requires that the <structfield>confScreen</structfield> field of the <structname>ScrnInfoRec</structname> be | |
6155 | initialised prior to calling it. This is done by the XFree86 | |
6156 | common layer prior to calling <function>ChipPreInit()</function>. | |
6157 | </para> | |
6158 | ||
6159 | <para> | |
6160 | The parameters passed are: | |
6161 | ||
6162 | <variablelist> | |
6163 | <varlistentry> | |
6164 | <term><parameter>depth</parameter></term> | |
6165 | <listitem><para> | |
6166 | driver's preferred default depth if no other is given. | |
6167 | If zero, use the overall server default. | |
6168 | </para></listitem></varlistentry> | |
6169 | ||
6170 | <varlistentry> | |
6171 | <term><parameter>bpp</parameter></term> | |
6172 | <listitem><para> | |
6173 | Same, but for the pixmap bpp. | |
6174 | </para></listitem></varlistentry> | |
6175 | ||
6176 | <varlistentry> | |
6177 | <term><parameter>fbbpp</parameter></term> | |
6178 | <listitem><para> | |
6179 | Same, but for the framebuffer bpp. | |
6180 | </para></listitem></varlistentry> | |
6181 | ||
6182 | <varlistentry> | |
6183 | <term><parameter>depth24flags</parameter></term> | |
6184 | <listitem><para> | |
6185 | Flags that indicate the level of 24/32bpp support | |
6186 | and whether conversion between different framebuffer | |
6187 | and pixmap formats is supported. The flags for this | |
6188 | argument are defined as follows, and multiple flags | |
6189 | may be ORed together: | |
6190 | ||
6191 | <variablelist> | |
6192 | <varlistentry> | |
6193 | <term><constant>NoDepth24Support</constant></term> | |
6194 | <listitem><para>No depth 24 formats supported | |
6195 | </para></listitem></varlistentry> | |
6196 | <varlistentry> | |
6197 | <term><constant>Support24bppFb</constant></term> | |
6198 | <listitem><para>24bpp framebuffer supported | |
6199 | </para></listitem></varlistentry> | |
6200 | <varlistentry> | |
6201 | <term><constant>Support32bppFb</constant></term> | |
6202 | <listitem><para>32bpp framebuffer supported | |
6203 | </para></listitem></varlistentry> | |
6204 | <varlistentry> | |
6205 | <term><constant>SupportConvert24to32</constant></term> | |
6206 | <listitem><para>Can convert 24bpp pixmap to 32bpp fb | |
6207 | </para></listitem></varlistentry> | |
6208 | <varlistentry> | |
6209 | <term><constant>SupportConvert32to24</constant></term> | |
6210 | <listitem><para>Can convert 32bpp pixmap to 24bpp fb | |
6211 | </para></listitem></varlistentry> | |
6212 | <varlistentry> | |
6213 | <term><constant>ForceConvert24to32</constant></term> | |
6214 | <listitem><para>Force 24bpp pixmap to 32bpp fb conversion | |
6215 | </para></listitem></varlistentry> | |
6216 | <varlistentry> | |
6217 | <term><constant>ForceConvert32to24</constant></term> | |
6218 | <listitem><para>Force 32bpp pixmap to 24bpp fb conversion | |
6219 | </para></listitem></varlistentry> | |
6220 | </variablelist> | |
6221 | </para></listitem></varlistentry> | |
6222 | ||
6223 | </variablelist> | |
6224 | </para> | |
6225 | ||
6226 | <para> | |
6227 | It uses the command line, config file, and default values in the | |
6228 | correct order of precedence to determine the depth and bpp values. | |
6229 | It is up to the driver to check the results to see that it supports | |
6230 | them. If not the <function>ChipPreInit()</function> function should | |
6231 | return <constant>FALSE</constant>. | |
6232 | </para> | |
6233 | ||
6234 | <para> | |
6235 | If only one of depth/bpp is given, the other is set to a reasonable | |
6236 | (and consistent) default. | |
6237 | </para> | |
6238 | ||
6239 | <para> | |
6240 | If a driver finds that the initial <parameter>depth24flags</parameter> | |
6241 | it uses later results in a fb format that requires more video | |
6242 | memory than is available it may call this function a second time | |
6243 | with a different <parameter>depth24flags</parameter> setting. | |
6244 | </para> | |
6245 | ||
6246 | <para> | |
6247 | On success, the return value is <constant>TRUE</constant>. On failure | |
6248 | it prints an error message and returns <constant>FALSE</constant>. | |
6249 | </para> | |
6250 | ||
6251 | <para> | |
6252 | The following fields of the <structname>ScrnInfoRec</structname> are | |
6253 | initialised by this function: | |
6254 | ||
6255 | <blockquote><para> | |
6256 | <structfield>depth</structfield>, <structfield>bitsPerPixel</structfield>, | |
6257 | <structfield>display</structfield>, <structfield>imageByteOrder</structfield>, | |
6258 | <structfield>bitmapScanlinePad</structfield>, | |
6259 | <structfield>bitmapScanlineUnit</structfield>, <structfield>bitmapBitOrder</structfield>, | |
6260 | <structfield>numFormats</structfield>, <structfield>formats</structfield>, | |
6261 | <structfield>fbFormat</structfield>. | |
6262 | </para></blockquote> | |
6263 | </para> | |
6264 | ||
6265 | </blockquote></para></blockquote> | |
6266 | ||
6267 | <blockquote><para> | |
6268 | <programlisting> | |
6269 | void xf86PrintDepthBpp(scrnInfoPtr scrp); | |
6270 | </programlisting> | |
6271 | <blockquote><para> | |
6272 | This function can be used to print out the depth and bpp settings. | |
6273 | It should be called after the final call to | |
6274 | <function>xf86SetDepthBpp()</function>. | |
6275 | </para> | |
6276 | ||
6277 | </blockquote></para></blockquote> | |
6278 | ||
6279 | <blockquote><para> | |
6280 | <programlisting> | |
6281 | Bool xf86SetWeight(ScrnInfoPtr scrp, rgb weight, rgb mask); | |
6282 | </programlisting> | |
6283 | <blockquote><para> | |
6284 | This function sets the <structfield>weight</structfield>, <structfield>mask</structfield>, | |
6285 | <structfield>offset</structfield> and <structfield>rgbBits</structfield> fields of the | |
6286 | <structname>ScrnInfoRec</structname>. It would normally be called fairly | |
6287 | early in the <function>ChipPreInit()</function> function for | |
6288 | depths > 8bpp. | |
6289 | </para> | |
6290 | ||
6291 | <para> | |
6292 | It requires that the <structfield>depth</structfield> and | |
6293 | <structfield>display</structfield> fields of the <structname>ScrnInfoRec</structname> | |
6294 | be initialised prior to calling it. | |
6295 | </para> | |
6296 | ||
6297 | <para> | |
6298 | The parameters passed are: | |
6299 | ||
6300 | <variablelist> | |
6301 | <varlistentry> | |
6302 | <term><parameter>weight</parameter></term> | |
6303 | <listitem><para> | |
6304 | driver's preferred default weight if no other is given. | |
6305 | If zero, use the overall server default. | |
6306 | ||
6307 | </para></listitem></varlistentry> | |
6308 | ||
6309 | <varlistentry> | |
6310 | <term><parameter>mask</parameter></term> | |
6311 | <listitem><para> | |
6312 | Same, but for mask. | |
6313 | ||
6314 | </para></listitem></varlistentry> | |
6315 | </variablelist> | |
6316 | </para> | |
6317 | ||
6318 | <para> | |
6319 | It uses the command line, config file, and default values in the | |
6320 | correct order of precedence to determine the weight value. It | |
6321 | derives the mask and offset values from the weight and the defaults. | |
6322 | It is up to the driver to check the results to see that it supports | |
6323 | them. If not the <function>ChipPreInit()</function> function should | |
6324 | return <constant>FALSE</constant>. | |
6325 | </para> | |
6326 | ||
6327 | <para> | |
6328 | On success, this function prints a message showing the weight | |
6329 | values selected, and returns <constant>TRUE</constant>. | |
6330 | </para> | |
6331 | ||
6332 | <para> | |
6333 | On failure it prints an error message and returns <constant>FALSE</constant>. | |
6334 | </para> | |
6335 | ||
6336 | <para> | |
6337 | The following fields of the <structname>ScrnInfoRec</structname> are | |
6338 | initialised by this function: | |
6339 | ||
6340 | <blockquote><para> | |
6341 | <structfield>weight</structfield>, | |
6342 | <structfield>mask</structfield>, | |
6343 | <structfield>offset</structfield>. | |
6344 | </para></blockquote> | |
6345 | </para> | |
6346 | ||
6347 | </blockquote></para></blockquote> | |
6348 | ||
6349 | <blockquote><para> | |
6350 | <programlisting> | |
6351 | Bool xf86SetDefaultVisual(ScrnInfoPtr scrp, int visual); | |
6352 | </programlisting> | |
6353 | <blockquote><para> | |
6354 | This function sets the <structfield>defaultVisual</structfield> field of the | |
6355 | <structname>ScrnInfoRec</structname>. It would normally be called fairly | |
6356 | early from the <function>ChipPreInit()</function> function. | |
6357 | </para> | |
6358 | ||
6359 | <para> | |
6360 | It requires that the <structfield>depth</structfield> and | |
6361 | <structfield>display</structfield> fields of the <structname>ScrnInfoRec</structname> | |
6362 | be initialised prior to calling it. | |
6363 | </para> | |
6364 | ||
6365 | <para> | |
6366 | The parameters passed are: | |
6367 | ||
6368 | <variablelist> | |
6369 | <varlistentry> | |
6370 | <term><parameter>visual</parameter></term> | |
6371 | <listitem><para> | |
6372 | driver's preferred default visual if no other is given. | |
6373 | If <constant>-1</constant>, use the overall server default. | |
6374 | </para></listitem></varlistentry> | |
6375 | ||
6376 | </variablelist> | |
6377 | </para> | |
6378 | ||
6379 | <para> | |
6380 | It uses the command line, config file, and default values in the | |
6381 | correct order of precedence to determine the default visual value. | |
6382 | It is up to the driver to check the result to see that it supports | |
6383 | it. If not the <function>ChipPreInit()</function> function should | |
6384 | return <constant>FALSE</constant>. | |
6385 | </para> | |
6386 | ||
6387 | <para> | |
6388 | On success, this function prints a message showing the default visual | |
6389 | selected, and returns <constant>TRUE</constant>. | |
6390 | </para> | |
6391 | ||
6392 | <para> | |
6393 | On failure it prints an error message and returns <constant>FALSE</constant>. | |
6394 | </para> | |
6395 | ||
6396 | </blockquote></para></blockquote> | |
6397 | ||
6398 | <blockquote><para> | |
6399 | <programlisting> | |
6400 | Bool xf86SetGamma(ScrnInfoPtr scrp, Gamma gamma); | |
6401 | </programlisting> | |
6402 | <blockquote><para> | |
6403 | This function sets the <structfield>gamma</structfield> field of the | |
6404 | <structname>ScrnInfoRec</structname>. It would normally be called fairly | |
6405 | early from the <function>ChipPreInit()</function> function in cases | |
6406 | where the driver supports gamma correction. | |
6407 | </para> | |
6408 | ||
6409 | <para> | |
6410 | It requires that the <structfield>monitor</structfield> field of the | |
6411 | <structname>ScrnInfoRec</structname> be initialised prior to calling it. | |
6412 | </para> | |
6413 | ||
6414 | <para> | |
6415 | The parameters passed are: | |
6416 | ||
6417 | <variablelist> | |
6418 | <varlistentry> | |
6419 | <term><parameter>gamma</parameter></term> | |
6420 | <listitem><para> | |
6421 | driver's preferred default gamma if no other is given. | |
6422 | If zero (<code>< 0.01</code>), use the overall server | |
6423 | default. | |
6424 | </para></listitem></varlistentry> | |
6425 | ||
6426 | </variablelist> | |
6427 | </para> | |
6428 | ||
6429 | <para> | |
6430 | It uses the command line, config file, and default values in the | |
6431 | correct order of precedence to determine the gamma value. It is | |
6432 | up to the driver to check the results to see that it supports | |
6433 | them. If not the <function>ChipPreInit()</function> function should | |
6434 | return <constant>FALSE</constant>. | |
6435 | </para> | |
6436 | ||
6437 | <para> | |
6438 | On success, this function prints a message showing the gamma | |
6439 | value selected, and returns <constant>TRUE</constant>. | |
6440 | </para> | |
6441 | ||
6442 | <para> | |
6443 | On failure it prints an error message and returns <constant>FALSE</constant>. | |
6444 | </para> | |
6445 | ||
6446 | </blockquote></para></blockquote> | |
6447 | ||
6448 | ||
6449 | <blockquote><para> | |
6450 | <programlisting> | |
6451 | void xf86SetDpi(ScrnInfoPtr pScrn, int x, int y); | |
6452 | </programlisting> | |
6453 | <blockquote><para> | |
6454 | This function sets the <structfield>xDpi</structfield> and <structfield>yDpi</structfield> | |
6455 | fields of the <structname>ScrnInfoRec</structname>. The driver can specify | |
6456 | preferred defaults by setting <parameter>x</parameter> and <parameter>y</parameter> | |
6457 | to non-zero values. The <option>-dpi</option> command line option | |
6458 | overrides all other settings. Otherwise, if the | |
6459 | <emphasis>DisplaySize</emphasis> entry is present in the screen's &k.monitor; | |
6460 | config file section, it is used together with the virtual size to | |
6461 | calculate the dpi values. This function should be called after | |
6462 | all the mode resolution has been done. | |
6463 | </para> | |
6464 | ||
6465 | </blockquote></para></blockquote> | |
6466 | ||
6467 | <blockquote><para> | |
6468 | <programlisting> | |
6469 | void xf86SetBlackWhitePixels(ScrnInfoPtr pScrn); | |
6470 | </programlisting> | |
6471 | <blockquote><para> | |
6472 | This functions sets the <structfield>blackPixel</structfield> and | |
6473 | <structfield>whitePixel</structfield> fields of the <structname>ScrnInfoRec</structname> | |
6474 | according to whether or not the <option>-flipPixels</option> command | |
6475 | line options is present. | |
6476 | </para> | |
6477 | ||
6478 | </blockquote></para></blockquote> | |
6479 | ||
6480 | <blockquote><para> | |
6481 | <programlisting> | |
6482 | const char *xf86GetVisualName(int visual); | |
6483 | </programlisting> | |
6484 | <blockquote><para> | |
6485 | Returns a printable string with the visual name matching the | |
6486 | numerical visual class provided. If the value is outside the | |
6487 | range of valid visual classes, <constant>NULL</constant> is returned. | |
6488 | </para> | |
6489 | ||
6490 | </blockquote></para></blockquote> | |
6491 | ||
6492 | </sect2> | |
6493 | ||
6494 | <sect2> | |
6495 | <title>Primary Mode functions</title> | |
6496 | ||
6497 | <para> | |
6498 | The primary mode helper functions are those which would normally be | |
6499 | used by a driver, unless it has unusual requirements which cannot | |
6500 | be catered for the by the helpers. | |
6501 | </para> | |
6502 | ||
6503 | <blockquote><para> | |
6504 | <programlisting> | |
6505 | int xf86ValidateModes(ScrnInfoPtr scrp, DisplayModePtr availModes, | |
6506 | char **modeNames, ClockRangePtr clockRanges, | |
6507 | int *linePitches, int minPitch, int maxPitch, | |
6508 | int pitchInc, int minHeight, int maxHeight, | |
6509 | int virtualX, int virtualY, | |
6510 | unsigned long apertureSize, | |
6511 | LookupModeFlags strategy); | |
6512 | </programlisting> | |
6513 | <blockquote><para> | |
6514 | This function basically selects the set of modes to use based on | |
6515 | those available and the various constraints. It also sets some | |
6516 | other related parameters. It is normally called near the end of | |
6517 | the <function>ChipPreInit()</function> function. | |
6518 | </para> | |
6519 | ||
6520 | <para> | |
6521 | The parameters passed to the function are: | |
6522 | ||
6523 | <variablelist> | |
6524 | <varlistentry> | |
6525 | <term><parameter>availModes</parameter></term> | |
6526 | <listitem><para> | |
6527 | List of modes available for the monitor. | |
6528 | </para></listitem></varlistentry> | |
6529 | ||
6530 | <varlistentry> | |
6531 | <term><parameter>modeNames</parameter></term> | |
6532 | <listitem><para> | |
6533 | List of mode names that the screen is requesting. | |
6534 | </para></listitem></varlistentry> | |
6535 | ||
6536 | <varlistentry> | |
6537 | <term><parameter>clockRanges</parameter></term> | |
6538 | <listitem><para> | |
6539 | A list of clock ranges allowed by the driver. Each | |
6540 | range includes whether interlaced or multiscan modes | |
6541 | are supported for that range. See below for more on | |
6542 | <parameter>clockRanges</parameter>. | |
6543 | </para></listitem></varlistentry> | |
6544 | ||
6545 | <varlistentry> | |
6546 | <term><parameter>linePitches</parameter></term> | |
6547 | <listitem><para> | |
6548 | List of line pitches supported by the driver. | |
6549 | This is optional and should be <constant>NULL</constant> when | |
6550 | not used. | |
6551 | </para></listitem></varlistentry> | |
6552 | ||
6553 | <varlistentry> | |
6554 | <term><parameter>minPitch</parameter></term> | |
6555 | <listitem><para> | |
6556 | Minimum line pitch supported by the driver. This must | |
6557 | be supplied when <parameter>linePitches</parameter> is | |
6558 | <constant>NULL</constant>, and is ignored otherwise. | |
6559 | </para></listitem></varlistentry> | |
6560 | ||
6561 | <varlistentry> | |
6562 | <term><parameter>maxPitch</parameter></term> | |
6563 | <listitem><para> | |
6564 | Maximum line pitch supported by the driver. This is | |
6565 | required when <parameter>minPitch</parameter> is required. | |
6566 | </para></listitem></varlistentry> | |
6567 | ||
6568 | <varlistentry> | |
6569 | <term><parameter>pitchInc</parameter></term> | |
6570 | <listitem><para> | |
6571 | Granularity of horizontal pitch values as supported by | |
6572 | the chipset. This is expressed in bits. This must be | |
6573 | supplied. | |
6574 | </para></listitem></varlistentry> | |
6575 | ||
6576 | <varlistentry> | |
6577 | <term><parameter>minHeight</parameter></term> | |
6578 | <listitem><para> | |
6579 | minimum virtual height allowed. If zero, no limit is | |
6580 | imposed. | |
6581 | </para></listitem></varlistentry> | |
6582 | ||
6583 | <varlistentry> | |
6584 | <term><parameter>maxHeight</parameter></term> | |
6585 | <listitem><para> | |
6586 | maximum virtual height allowed. If zero, no limit is | |
6587 | imposed. | |
6588 | </para></listitem></varlistentry> | |
6589 | ||
6590 | <varlistentry> | |
6591 | <term><parameter>virtualX</parameter></term> | |
6592 | <listitem><para> | |
6593 | If greater than zero, this is the virtual width value | |
6594 | that will be used. Otherwise, the virtual width is | |
6595 | chosen to be the smallest that can accommodate the modes | |
6596 | selected. | |
6597 | </para></listitem></varlistentry> | |
6598 | ||
6599 | <varlistentry> | |
6600 | <term><parameter>virtualY</parameter></term> | |
6601 | <listitem><para> | |
6602 | If greater than zero, this is the virtual height value | |
6603 | that will be used. Otherwise, the virtual height is | |
6604 | chosen to be the smallest that can accommodate the modes | |
6605 | selected. | |
6606 | </para></listitem></varlistentry> | |
6607 | ||
6608 | <varlistentry> | |
6609 | <term><parameter>apertureSize</parameter></term> | |
6610 | <listitem><para> | |
6611 | The size (in bytes) of the aperture used to access video | |
6612 | memory. | |
6613 | </para></listitem></varlistentry> | |
6614 | ||
6615 | <varlistentry> | |
6616 | <term><parameter>strategy</parameter></term> | |
6617 | <listitem><para> | |
6618 | The strategy to use when choosing from multiple modes | |
6619 | with the same name. The options are: | |
6620 | ||
6621 | <variablelist> | |
6622 | <varlistentry> | |
6623 | <term><constant>LOOKUP_DEFAULT</constant></term> | |
6624 | <listitem><para>??? | |
6625 | </para></listitem></varlistentry> | |
6626 | <varlistentry> | |
6627 | <term><constant>LOOKUP_BEST_REFRESH</constant></term> | |
6628 | <listitem><para>mode with best refresh rate | |
6629 | </para></listitem></varlistentry> | |
6630 | <varlistentry> | |
6631 | <term><constant>LOOKUP_CLOSEST_CLOCK</constant></term> | |
6632 | <listitem><para>mode with closest matching clock | |
6633 | </para></listitem></varlistentry> | |
6634 | <varlistentry> | |
6635 | <term><constant>LOOKUP_LIST_ORDER</constant></term> | |
6636 | <listitem><para>first usable mode in list | |
6637 | </para></listitem></varlistentry> | |
6638 | </variablelist> | |
6639 | ||
6640 | The following options can also be combined (OR'ed) with | |
6641 | one of the above: | |
6642 | ||
6643 | <variablelist> | |
6644 | <varlistentry> | |
6645 | <term><constant>LOOKUP_CLKDIV2</constant></term> | |
6646 | <listitem><para>Allow halved clocks | |
6647 | </para></listitem></varlistentry> | |
6648 | <varlistentry> | |
6649 | <term><constant>LOOKUP_OPTIONAL_TOLERANCES</constant></term> | |
6650 | <listitem><para> | |
6651 | Allow missing horizontal sync and/or vertical refresh | |
6652 | ranges in the xorg.conf Monitor section | |
6653 | </para></listitem></varlistentry> | |
6654 | </variablelist> | |
6655 | ||
6656 | <constant>LOOKUP_OPTIONAL_TOLERANCES</constant> should only be | |
6657 | specified when the driver can ensure all modes it generates | |
6658 | can sync on, or at least not damage, the monitor or digital | |
6659 | flat panel. Horizontal sync and/or vertical refresh ranges | |
6660 | specified by the user will still be honoured (and acted upon). | |
6661 | ||
6662 | </para></listitem></varlistentry> | |
6663 | </variablelist> | |
6664 | </para> | |
6665 | ||
6666 | <para> | |
6667 | This function requires that the following fields of the | |
6668 | <structname>ScrnInfoRec</structname> are initialised prior to calling it: | |
6669 | ||
6670 | <variablelist> | |
6671 | <varlistentry> | |
6672 | <term><structfield>clock[]</structfield></term> | |
6673 | <listitem><para> | |
6674 | List of discrete clocks (when non-programmable) | |
6675 | </para></listitem></varlistentry> | |
6676 | <varlistentry> | |
6677 | <term><structfield>numClocks</structfield></term> | |
6678 | <listitem><para> | |
6679 | Number of discrete clocks (when non-programmable) | |
6680 | </para></listitem></varlistentry> | |
6681 | <varlistentry> | |
6682 | <term><structfield>progClock</structfield></term> | |
6683 | <listitem><para> | |
6684 | Whether the clock is programmable or not | |
6685 | </para></listitem></varlistentry> | |
6686 | <varlistentry> | |
6687 | <term><structfield>monitor</structfield></term> | |
6688 | <listitem><para> | |
6689 | Pointer to the applicable xorg.conf monitor section | |
6690 | </para></listitem></varlistentry> | |
6691 | <varlistentry> | |
6692 | <term><structfield>fdFormat</structfield></term> | |
6693 | <listitem><para> | |
6694 | Format of the screen buffer | |
6695 | </para></listitem></varlistentry> | |
6696 | <varlistentry> | |
6697 | <term><structfield>videoRam</structfield></term> | |
6698 | <listitem><para> | |
6699 | total video memory size (in bytes) | |
6700 | </para></listitem></varlistentry> | |
6701 | <varlistentry> | |
6702 | <term><structfield>maxHValue</structfield></term> | |
6703 | <listitem><para> | |
6704 | Maximum horizontal timing value allowed | |
6705 | </para></listitem></varlistentry> | |
6706 | <varlistentry> | |
6707 | <term><structfield>maxVValue</structfield></term> | |
6708 | <listitem><para> | |
6709 | Maximum vertical timing value allowed | |
6710 | </para></listitem></varlistentry> | |
6711 | <varlistentry> | |
6712 | <term><structfield>xInc</structfield></term> | |
6713 | <listitem><para> | |
6714 | Horizontal timing increment in pixels (defaults to 8) | |
6715 | </para></listitem></varlistentry> | |
6716 | </variablelist> | |
6717 | </para> | |
6718 | ||
6719 | <para> | |
6720 | This function fills in the following <structname>ScrnInfoRec</structname> | |
6721 | fields: | |
6722 | ||
6723 | <variablelist> | |
6724 | <varlistentry> | |
6725 | <term><structfield>modePool</structfield></term> | |
6726 | <listitem><para> | |
6727 | A subset of the modes available to the monitor which | |
6728 | are compatible with the driver. | |
6729 | </para></listitem></varlistentry> | |
6730 | ||
6731 | <varlistentry> | |
6732 | <term><structfield>modes</structfield></term> | |
6733 | <listitem><para> | |
6734 | One mode entry for each of the requested modes, with | |
6735 | the status field of each filled in to indicate if | |
6736 | the mode has been accepted or not. This list of | |
6737 | modes is a circular list. | |
6738 | </para></listitem></varlistentry> | |
6739 | ||
6740 | <varlistentry> | |
6741 | <term><structfield>virtualX</structfield></term> | |
6742 | <listitem><para> | |
6743 | The resulting virtual width. | |
6744 | </para></listitem></varlistentry> | |
6745 | ||
6746 | <varlistentry> | |
6747 | <term><structfield>virtualY</structfield></term> | |
6748 | <listitem><para> | |
6749 | The resulting virtual height. | |
6750 | </para></listitem></varlistentry> | |
6751 | ||
6752 | <varlistentry> | |
6753 | <term><structfield>displayWidth</structfield></term> | |
6754 | <listitem><para> | |
6755 | The resulting line pitch. | |
6756 | </para></listitem></varlistentry> | |
6757 | ||
6758 | <varlistentry> | |
6759 | <term><structfield>virtualFrom</structfield></term> | |
6760 | <listitem><para> | |
6761 | Where the virtual size was determined from. | |
6762 | </para></listitem></varlistentry> | |
6763 | ||
6764 | </variablelist> | |
6765 | </para> | |
6766 | ||
6767 | <para> | |
6768 | The first stage of this function checks that the | |
6769 | <parameter>virtualX</parameter> and <parameter>virtualY</parameter> values | |
6770 | supplied (if greater than zero) are consistent with the line pitch | |
6771 | and <parameter>maxHeight</parameter> limitations. If not, an error | |
6772 | message is printed, and the return value is <constant>-1</constant>. | |
6773 | </para> | |
6774 | ||
6775 | <para> | |
6776 | The second stage sets up the mode pool, eliminating immediately | |
6777 | any modes that exceed the driver's line pitch limits, and also | |
6778 | the virtual width and height limits (if greater than zero). For | |
6779 | each mode removed an informational message is printed at verbosity | |
6780 | level <constant>2</constant>. If the mode pool ends up being empty, | |
6781 | a warning message is printed, and the return value is | |
6782 | <constant>0</constant>. | |
6783 | </para> | |
6784 | ||
6785 | <para> | |
6786 | The final stage is to lookup each mode name, and fill in the remaining | |
6787 | parameters. If an error condition is encountered, a message is | |
6788 | printed, and the return value is <constant>-1</constant>. Otherwise, | |
6789 | the return value is the number of valid modes found | |
6790 | (<constant>0</constant> if none are found). | |
6791 | </para> | |
6792 | ||
6793 | <para> | |
6794 | Even if the supplied mode names include duplicates, no two names will | |
6795 | ever match the same mode. Furthermore, if the supplied mode names do not | |
6796 | yield a valid mode (including the case where no names are passed at all), | |
6797 | the function will continue looking through the mode pool until it finds | |
6798 | a mode that survives all checks, or until the mode pool is exhausted. | |
6799 | </para> | |
6800 | ||
6801 | <para> | |
6802 | A message is only printed by this function when a fundamental | |
6803 | problem is found. It is intended that this function may be called | |
6804 | more than once if there is more than one set of constraints that | |
6805 | the driver can work within. | |
6806 | </para> | |
6807 | ||
6808 | <para> | |
6809 | If this function returns <constant>-1</constant>, the | |
6810 | <function>ChipPreInit()</function> function should return | |
6811 | <constant>FALSE</constant>. | |
6812 | </para> | |
6813 | ||
6814 | <para> | |
6815 | <parameter>clockRanges</parameter> is a linked list of clock ranges | |
6816 | allowed by the driver. If a mode doesn't fit in any of the defined | |
6817 | <parameter>clockRanges</parameter>, it is rejected. The first | |
6818 | <literal remap="tt">clockRange</literal> that matches all requirements is used. | |
6819 | This structure needs to be initialized to NULL when allocated. | |
6820 | </para> | |
6821 | ||
6822 | <para> | |
6823 | <parameter>clockRanges</parameter> contains the following fields: | |
6824 | ||
6825 | <variablelist> | |
6826 | <varlistentry> | |
6827 | <term><structfield>minClock</structfield></term> | |
6828 | <term><structfield>maxClock</structfield></term> | |
6829 | <listitem><para> | |
6830 | The lower and upper mode clock bounds for which the rest | |
6831 | of the <structname>clockRange</structname> parameters apply. | |
6832 | Since these are the mode clocks, they are not scaled | |
6833 | with the <structfield>ClockMulFactor</structfield> and | |
6834 | <structfield>ClockDivFactor</structfield>. It is up to the driver | |
6835 | to adjust these values if they depend on the clock | |
6836 | scaling factors. | |
6837 | </para></listitem></varlistentry> | |
6838 | ||
6839 | <varlistentry> | |
6840 | <term><structfield>clockIndex</structfield></term> | |
6841 | <listitem><para> | |
6842 | (not used yet) <constant>-1</constant> for programmable clocks | |
6843 | </para></listitem></varlistentry> | |
6844 | ||
6845 | <varlistentry> | |
6846 | <term><structfield>interlaceAllowed</structfield></term> | |
6847 | <listitem><para> | |
6848 | <constant>TRUE</constant> if interlacing is allowed for this | |
6849 | range | |
6850 | </para></listitem></varlistentry> | |
6851 | ||
6852 | <varlistentry> | |
6853 | <term><structfield>doubleScanAllowed</structfield></term> | |
6854 | <listitem><para> | |
6855 | <constant>TRUE</constant> if doublescan or multiscan is allowed | |
6856 | for this range | |
6857 | </para></listitem></varlistentry> | |
6858 | ||
6859 | <varlistentry> | |
6860 | <term><structfield>ClockMulFactor</structfield></term> | |
6861 | <term><structfield>ClockDivFactor</structfield></term> | |
6862 | <listitem><para> | |
6863 | Scaling factors that are applied to the mode clocks ONLY | |
6864 | before selecting a clock index (when there is no | |
6865 | programmable clock) or a <structfield>SynthClock</structfield> | |
6866 | value. This is useful for drivers that support pixel | |
6867 | multiplexing or that need to scale the clocks because | |
6868 | of hardware restrictions (like sending 24bpp data to an | |
6869 | 8 bit RAMDAC using a tripled clock). | |
6870 | </para> | |
6871 | ||
6872 | <para> | |
6873 | Note that these parameters describe what must be done | |
6874 | to the mode clock to achieve the data transport clock | |
6875 | between graphics controller and RAMDAC. For example | |
6876 | for <literal remap="tt">2:1</literal> pixel multiplexing, two pixels | |
6877 | are sent to the RAMDAC on each clock. This allows the | |
6878 | RAMDAC clock to be half of the actual pixel clock. | |
6879 | Hence, <code>ClockMulFactor=1</code> and | |
6880 | <code>ClockDivFactor=2</code>. This means that the | |
6881 | clock used for clock selection (ie, determining the | |
6882 | correct clock index from the list of discrete clocks) | |
6883 | or for the <structfield>SynthClock</structfield> field in case of | |
6884 | a programmable clock is: (<code>mode->Clock * | |
6885 | ClockMulFactor) / ClockDivFactor</code>. | |
6886 | </para></listitem></varlistentry> | |
6887 | ||
6888 | <varlistentry> | |
6889 | <term><structfield>PrivFlags</structfield></term> | |
6890 | <listitem><para> | |
6891 | This field is copied into the | |
6892 | <literal remap="tt">mode->PrivFlags</literal> field when this | |
6893 | <literal remap="tt">clockRange</literal> is selected by | |
6894 | <function>xf86ValidateModes()</function>. It allows the | |
6895 | driver to find out what clock range was selected, so it | |
6896 | knows it needs to set up pixel multiplexing or any other | |
6897 | range-dependent feature. This field is purely | |
6898 | driver-defined: it may contain flag bits, an index or | |
6899 | anything else (as long as it is an <literal remap="tt">INT</literal>). | |
6900 | </para></listitem></varlistentry> | |
6901 | </variablelist> | |
6902 | </para> | |
6903 | ||
6904 | <para> | |
6905 | Note that the <structfield>mode->SynthClock</structfield> field is always | |
6906 | filled in by <function>xf86ValidateModes()</function>: it will contain | |
6907 | the <quote>data transport clock</quote>, which is the clock that will have | |
6908 | to be programmed in the chip when it has a programmable clock, or | |
6909 | the clock that will be picked from the clocks list when it is not | |
6910 | a programmable one. Thus: | |
6911 | ||
6912 | <programlisting> | |
6913 | mode->SynthClock = (mode->Clock * ClockMulFactor) / ClockDivFactor | |
6914 | </programlisting> | |
6915 | </para> | |
6916 | ||
6917 | </blockquote></para></blockquote> | |
6918 | ||
6919 | <blockquote><para> | |
6920 | <programlisting> | |
6921 | void xf86PruneDriverModes(ScrnInfoPtr scrp); | |
6922 | </programlisting> | |
6923 | <blockquote><para> | |
6924 | This function deletes modes in the modes field of the | |
6925 | <structname>ScrnInfoRec</structname> that have been marked as invalid. | |
6926 | This is normally run after having run | |
6927 | <function>xf86ValidateModes()</function> for the last time. For each | |
6928 | mode that is deleted, a warning message is printed out indicating | |
6929 | the reason for it being deleted. | |
6930 | </para> | |
6931 | ||
6932 | </blockquote></para></blockquote> | |
6933 | ||
6934 | <blockquote><para> | |
6935 | <programlisting> | |
6936 | void xf86SetCrtcForModes(ScrnInfoPtr scrp, int adjustFlags); | |
6937 | </programlisting> | |
6938 | <blockquote><para> | |
6939 | This function fills in the <structname>Crtc*</structname> fields for all | |
6940 | the modes in the <structfield>modes</structfield> field of the | |
6941 | <structname>ScrnInfoRec</structname>. The <parameter>adjustFlags</parameter> | |
6942 | parameter determines how the vertical CRTC values are scaled for | |
6943 | interlaced modes. They are halved if it is | |
6944 | <constant>INTERLACE_HALVE_V</constant>. The vertical CRTC values are | |
6945 | doubled for doublescan modes, and are further multiplied by the | |
6946 | <literal remap="tt">VScan</literal> value. | |
6947 | </para> | |
6948 | ||
6949 | <para> | |
6950 | This function is normally called after calling | |
6951 | <function>xf86PruneDriverModes()</function>. | |
6952 | </para> | |
6953 | ||
6954 | </blockquote></para></blockquote> | |
6955 | ||
6956 | <blockquote><para> | |
6957 | <programlisting> | |
6958 | void xf86PrintModes(ScrnInfoPtr scrp); | |
6959 | </programlisting> | |
6960 | <blockquote><para> | |
6961 | This function prints out the virtual size setting, and the line | |
6962 | pitch being used. It also prints out two lines for each mode being | |
6963 | used. The first line includes the mode's pixel clock, horizontal sync | |
6964 | rate, refresh rate, and whether it is interlaced, doublescanned and/or | |
6965 | multi-scanned. The second line is the mode's Modeline. | |
6966 | </para> | |
6967 | ||
6968 | <para> | |
6969 | This function is normally called after calling | |
6970 | <function>xf86SetCrtcForModes()</function>. | |
6971 | </para> | |
6972 | ||
6973 | </blockquote></para></blockquote> | |
6974 | ||
6975 | </sect2> | |
6976 | ||
6977 | <sect2> | |
6978 | <title>Secondary Mode functions</title> | |
6979 | ||
6980 | <para> | |
6981 | The secondary mode helper functions are functions which are normally | |
6982 | used by the primary mode helper functions, and which are not normally | |
6983 | called directly by a driver. If a driver has unusual requirements | |
6984 | and needs to do its own mode validation, it might be able to make | |
6985 | use of some of these secondary mode helper functions. | |
6986 | </para> | |
6987 | ||
6988 | <blockquote><para> | |
6989 | <programlisting> | |
6990 | int xf86GetNearestClock(ScrnInfoPtr scrp, int freq, Bool allowDiv2, | |
6991 | int *divider); | |
6992 | </programlisting> | |
6993 | <blockquote><para> | |
6994 | This function returns the index of the closest clock to the | |
6995 | frequency <parameter>freq</parameter> given (in kHz). It assumes that | |
6996 | the number of clocks is greater than zero. It requires that the | |
6997 | <structfield>numClocks</structfield> and <structfield>clock</structfield> fields of the | |
6998 | <structname>ScrnInfoRec</structname> are initialised. The | |
6999 | <structfield>allowDiv2</structfield> field determines if the clocks can be | |
7000 | halved. The <parameter>*divider</parameter> return value indicates | |
7001 | whether clock division is used when determining the clock returned. | |
7002 | </para> | |
7003 | ||
7004 | <para> | |
7005 | This function is only for non-programmable clocks. | |
7006 | </para> | |
7007 | ||
7008 | </blockquote></para></blockquote> | |
7009 | ||
7010 | <blockquote><para> | |
7011 | <programlisting> | |
7012 | const char *xf86ModeStatusToString(ModeStatus status); | |
7013 | </programlisting> | |
7014 | <blockquote><para> | |
7015 | This function converts the <parameter>status</parameter> value to a | |
7016 | descriptive printable string. | |
7017 | </para> | |
7018 | ||
7019 | </blockquote></para></blockquote> | |
7020 | ||
7021 | <blockquote><para> | |
7022 | <programlisting> | |
7023 | ModeStatus xf86LookupMode(ScrnInfoPtr scrp, DisplayModePtr modep, | |
7024 | ClockRangePtr clockRanges, LookupModeFlags strategy); | |
7025 | </programlisting> | |
7026 | <blockquote><para> | |
7027 | This function takes a pointer to a mode with the name filled in, | |
7028 | and looks for a mode in the <structfield>modePool</structfield> list which | |
7029 | matches. The parameters of the matching mode are filled in to | |
7030 | <parameter>*modep</parameter>. The <parameter>clockRanges</parameter> and | |
7031 | <parameter>strategy</parameter> parameters are as for the | |
7032 | <function>xf86ValidateModes()</function> function above. | |
7033 | </para> | |
7034 | ||
7035 | <para> | |
7036 | This function requires the <structfield>modePool</structfield>, | |
7037 | <structfield>clock[]</structfield>, <structfield>numClocks</structfield> and | |
7038 | <structfield>progClock</structfield> fields of the <structname>ScrnInfoRec</structname> | |
7039 | to be initialised before being called. | |
7040 | </para> | |
7041 | ||
7042 | <para> | |
7043 | The return value is <constant>MODE_OK</constant> if a mode was found. | |
7044 | Otherwise it indicates why a matching mode could not be found. | |
7045 | </para> | |
7046 | ||
7047 | </blockquote></para></blockquote> | |
7048 | ||
7049 | <blockquote><para> | |
7050 | <programlisting> | |
7051 | ModeStatus xf86InitialCheckModeForDriver(ScrnInfoPtr scrp, | |
7052 | DisplayModePtr mode, ClockRangePtr clockRanges, | |
7053 | LookupModeFlags strategy, int maxPitch, | |
7054 | int virtualX, int virtualY); | |
7055 | </programlisting> | |
7056 | <blockquote><para> | |
7057 | This function checks the passed mode against some basic driver | |
7058 | constraints. Apart from the ones passed explicitly, the | |
7059 | <structfield>maxHValue</structfield> and <structfield>maxVValue</structfield> fields of | |
7060 | the <structname>ScrnInfoRec</structname> are also used. If the | |
7061 | <structfield>ValidMode</structfield> field of the <structname>ScrnInfoRec</structname> | |
7062 | is set, that function is also called to check the mode. Next, the | |
7063 | mode is checked against the monitor's constraints. | |
7064 | </para> | |
7065 | ||
7066 | <para> | |
7067 | If the mode is consistent with all constraints, the return value | |
7068 | is <constant>MODE_OK</constant>. Otherwise the return value indicates | |
7069 | which constraint wasn't met. | |
7070 | </para> | |
7071 | ||
7072 | </blockquote></para></blockquote> | |
7073 | ||
7074 | <blockquote><para> | |
7075 | <programlisting> | |
7076 | void xf86DeleteMode(DisplayModePtr *modeList, DisplayModePtr mode); | |
7077 | </programlisting> | |
7078 | <blockquote><para> | |
7079 | This function deletes the <parameter>mode</parameter> given from the | |
7080 | <parameter>modeList</parameter>. It never prints any messages, so it is | |
7081 | up to the caller to print a message if required. | |
7082 | </para> | |
7083 | ||
7084 | </blockquote></para></blockquote> | |
7085 | </sect2> | |
7086 | ||
7087 | <sect2> | |
7088 | <title>Functions for handling strings and tokens</title> | |
7089 | ||
7090 | <para> | |
7091 | Tables associating strings and numerical tokens combined with the | |
7092 | following functions provide a compact way of handling strings from | |
7093 | the config file, and for converting tokens into printable strings. | |
7094 | The table data structure is: | |
7095 | ||
7096 | <programlisting> | |
7097 | typedef struct { | |
7098 | int token; | |
7099 | const char * name; | |
7100 | } SymTabRec, *SymTabPtr; | |
7101 | </programlisting> | |
7102 | </para> | |
7103 | ||
7104 | <para> | |
7105 | A table is an initialised array of <structname>SymTabRec</structname>. The | |
7106 | tokens must be non-negative integers. Multiple names may be mapped | |
7107 | to a single token. The table is terminated with an element with a | |
7108 | <structfield>token</structfield> value of <constant>-1</constant> and | |
7109 | <constant>NULL</constant> for the <structfield>name</structfield>. | |
7110 | </para> | |
7111 | ||
7112 | <blockquote><para> | |
7113 | <programlisting> | |
7114 | const char *xf86TokenToString(SymTabPtr table, int token); | |
7115 | </programlisting> | |
7116 | <blockquote><para> | |
7117 | This function returns the first string in <parameter>table</parameter> | |
7118 | that matches <parameter>token</parameter>. If no match is found, | |
7119 | <constant>NULL</constant> is returned (NOTE, older versions of this | |
7120 | function would return the string "unknown" when no match is found). | |
7121 | </para> | |
7122 | ||
7123 | </blockquote></para></blockquote> | |
7124 | ||
7125 | <blockquote><para> | |
7126 | <programlisting> | |
7127 | int xf86StringToToken(SymTabPtr table, const char *string); | |
7128 | </programlisting> | |
7129 | <blockquote><para> | |
7130 | This function returns the first token in <parameter>table</parameter> | |
7131 | that matches <parameter>string</parameter>. The | |
7132 | <function>xf86NameCmp()</function> function is used to determine the | |
7133 | match. If no match is found, <constant>-1</constant> is returned. | |
7134 | </para> | |
7135 | ||
7136 | </blockquote></para></blockquote> | |
7137 | ||
7138 | </sect2> | |
7139 | ||
7140 | <sect2> | |
7141 | <title>Functions for finding which config file entries to use</title> | |
7142 | ||
7143 | <para> | |
7144 | These functions can be used to select the appropriate config file | |
7145 | entries that match the detected hardware. They are described above | |
7146 | in the <link linkend="probe">Probe</link> and | |
7147 | <link linkend="avail">Available Functions</link> sections. | |
7148 | </para> | |
7149 | ||
7150 | </sect2> | |
7151 | ||
7152 | <sect2> | |
7153 | <title>Probing discrete clocks on old hardware</title> | |
7154 | ||
7155 | <para> | |
7156 | The <function>xf86GetClocks()</function> function may be used to assist | |
7157 | in finding the discrete pixel clock values on older hardware. | |
7158 | </para> | |
7159 | ||
7160 | <blockquote><para> | |
7161 | <programlisting> | |
7162 | void xf86GetClocks(ScrnInfoPtr pScrn, int num, | |
7163 | Bool (*ClockFunc)(ScrnInfoPtr, int), | |
7164 | void (*ProtectRegs)(ScrnInfoPtr, Bool), | |
7165 | void (*BlankScreen)(ScrnInfoPtr, Bool), | |
7166 | int vertsyncreg, int maskval, int knownclkindex, | |
7167 | int knownclkvalue); | |
7168 | </programlisting> | |
7169 | <blockquote><para> | |
7170 | This function uses a comparative sampling method to measure the | |
7171 | discrete pixel clock values. The number of discrete clocks to | |
7172 | measure is given by <parameter>num</parameter>. <parameter>clockFunc</parameter> | |
7173 | is a function that selects the <parameter>n</parameter>'th clock. It | |
7174 | should also save or restore any state affected by programming the | |
7175 | clocks when the index passed is <constant>CLK_REG_SAVE</constant> or | |
7176 | <constant>CLK_REG_RESTORE</constant>. <parameter>ProtectRegs</parameter> is | |
7177 | a function that does whatever is required to protect the hardware | |
7178 | state while selecting a new clock. <parameter>BlankScreen</parameter> | |
7179 | is a function that blanks the screen. <parameter>vertsyncreg</parameter> | |
7180 | and <parameter>maskval</parameter> are the register and bitmask to | |
7181 | check for the presence of vertical sync pulses. | |
7182 | <parameter>knownclkindex</parameter> and <parameter>knownclkvalue</parameter> | |
7183 | are the index and value of a known clock. These are the known | |
7184 | references on which the comparative measurements are based. The | |
7185 | number of clocks probed is set in <structfield>pScrn->numClocks</structfield>, | |
7186 | and the probed clocks are set in the <structfield>pScrn->clock[]</structfield> | |
7187 | array. All of the clock values are in units of kHz. | |
7188 | </para> | |
7189 | ||
7190 | </blockquote></para></blockquote> | |
7191 | ||
7192 | <blockquote><para> | |
7193 | <programlisting> | |
7194 | void xf86ShowClocks(ScrnInfoPtr scrp, MessageType from); | |
7195 | </programlisting> | |
7196 | <blockquote><para> | |
7197 | Print out the pixel clocks <parameter>scrp->clock[]</parameter>. | |
7198 | <parameter>from</parameter> indicates whether the clocks were probed | |
7199 | or from the config file. | |
7200 | </para> | |
7201 | ||
7202 | </blockquote></para></blockquote> | |
7203 | </sect2> | |
7204 | ||
7205 | <sect2> | |
7206 | <title>Other helper functions</title> | |
7207 | ||
7208 | <blockquote><para> | |
7209 | <programlisting> | |
7210 | Bool xf86IsUnblank(int mode); | |
7211 | </programlisting> | |
7212 | <blockquote><para> | |
7213 | Returns <constant>TRUE</constant> when the screen saver mode specified | |
7214 | by <parameter>mode</parameter> requires the screen be unblanked, | |
7215 | and <constant>FALSE</constant> otherwise. The screen saver modes that | |
7216 | require blanking are <constant>SCREEN_SAVER_ON</constant> and | |
7217 | <constant>SCREEN_SAVER_CYCLE</constant>, and the screen saver modes that | |
7218 | require unblanking are <constant>SCREEN_SAVER_OFF</constant> and | |
7219 | <constant>SCREEN_SAVER_FORCER</constant>. Drivers may call this helper | |
7220 | from their <function>SaveScreen()</function> function to interpret the | |
7221 | screen saver modes. | |
7222 | </para> | |
7223 | ||
7224 | </blockquote></para></blockquote> | |
7225 | </sect2> | |
7226 | </sect1> | |
7227 | ||
7228 | <sect1> | |
7229 | <title>The vgahw module</title> | |
7230 | ||
7231 | <para> | |
7232 | The vgahw modules provides an interface for saving, restoring and | |
7233 | programming the standard VGA registers, and for handling VGA colourmaps. | |
7234 | </para> | |
7235 | ||
7236 | <sect2> | |
7237 | <title>Data Structures</title> | |
7238 | ||
7239 | <para> | |
7240 | The public data structures used by the vgahw module are | |
7241 | <structname>vgaRegRec</structname> and <structname>vgaHWRec</structname>. They are | |
7242 | defined in <filename>vgaHW.h.</filename> | |
7243 | </para> | |
7244 | ||
7245 | </sect2> | |
7246 | ||
7247 | <sect2> | |
7248 | <title>General vgahw Functions</title> | |
7249 | ||
7250 | <blockquote><para> | |
7251 | <programlisting> | |
7252 | Bool vgaHWGetHWRec(ScrnInfoPtr pScrn); | |
7253 | </programlisting> | |
7254 | <blockquote><para> | |
7255 | This function allocates a <structname>vgaHWRec</structname> structure, and | |
7256 | hooks it into the <structname>ScrnInfoRec</structname>'s | |
7257 | <structfield>privates</structfield>. Like all information hooked into the | |
7258 | <structfield>privates</structfield>, it is persistent, and only needs to be | |
7259 | allocated once per screen. This function should normally be called | |
7260 | from the driver's <function>ChipPreInit()</function> function. The | |
7261 | <structname>vgaHWRec</structname> is zero-allocated, and the following | |
7262 | fields are explicitly initialised: | |
7263 | ||
7264 | <variablelist> | |
7265 | <varlistentry> | |
7266 | <term><structfield>ModeReg.DAC[]</structfield></term> | |
7267 | <listitem><para>initialised with a default colourmap | |
7268 | </para></listitem></varlistentry> | |
7269 | <varlistentry> | |
7270 | <term><structfield>ModeReg.Attribute[0x11]</structfield></term> | |
7271 | <listitem><para>initialised with the default overscan index | |
7272 | </para></listitem></varlistentry> | |
7273 | <varlistentry> | |
7274 | <term><structfield>ShowOverscan</structfield></term> | |
7275 | <listitem><para>initialised according to the "ShowOverscan" option | |
7276 | </para></listitem></varlistentry> | |
7277 | <varlistentry> | |
7278 | <term><structfield>paletteEnabled</structfield></term> | |
7279 | <listitem><para>initialised to FALSE | |
7280 | </para></listitem></varlistentry> | |
7281 | <varlistentry> | |
7282 | <term><structfield>cmapSaved</structfield></term> | |
7283 | <listitem><para>initialised to FALSE | |
7284 | </para></listitem></varlistentry> | |
7285 | <varlistentry> | |
7286 | <term><structfield>pScrn</structfield></term> | |
7287 | <listitem><para>initialised to pScrn | |
7288 | </para></listitem></varlistentry> | |
7289 | </variablelist> | |
7290 | </para> | |
7291 | ||
7292 | <para> | |
7293 | In addition to the above, <function>vgaHWSetStdFuncs()</function> is | |
7294 | called to initialise the register access function fields with the | |
7295 | standard VGA set of functions. | |
7296 | </para> | |
7297 | ||
7298 | <para> | |
7299 | Once allocated, a pointer to the <structname>vgaHWRec</structname> can be | |
7300 | obtained from the <literal remap="tt">ScrnInfoPtr</literal> with the | |
7301 | <literal remap="tt">VGAHWPTR(pScrn)</literal> macro. | |
7302 | </para> | |
7303 | ||
7304 | </blockquote></para></blockquote> | |
7305 | ||
7306 | <blockquote><para> | |
7307 | <programlisting> | |
7308 | void vgaHWFreeHWRec(ScrnInfoPtr pScrn); | |
7309 | </programlisting> | |
7310 | <blockquote><para> | |
7311 | This function frees a <structname>vgaHWRec</structname> structure. It | |
7312 | should be called from a driver's <function>ChipFreeScreen()</function> | |
7313 | function. | |
7314 | </para> | |
7315 | ||
7316 | </blockquote></para></blockquote> | |
7317 | ||
7318 | <blockquote><para> | |
7319 | <programlisting> | |
7320 | Bool vgaHWSetRegCounts(ScrnInfoPtr pScrn, int numCRTC, | |
7321 | int numSequencer, int numGraphics, int numAttribute); | |
7322 | </programlisting> | |
7323 | <blockquote><para> | |
7324 | This function allows the number of CRTC, Sequencer, Graphics and | |
7325 | Attribute registers to be changed. This makes it possible for | |
7326 | extended registers to be saved and restored with | |
7327 | <function>vgaHWSave()</function> and <function>vgaHWRestore()</function>. | |
7328 | This function should be called after a <structname>vgaHWRec</structname> | |
7329 | has been allocated with <function>vgaHWGetHWRec()</function>. The | |
7330 | default values are defined in <filename>vgaHW.h</filename> as follows: | |
7331 | ||
7332 | <programlisting> | |
7333 | #define VGA_NUM_CRTC 25 | |
7334 | #define VGA_NUM_SEQ 5 | |
7335 | #define VGA_NUM_GFX 9 | |
7336 | #define VGA_NUM_ATTR 21 | |
7337 | </programlisting> | |
7338 | </para> | |
7339 | ||
7340 | </blockquote></para></blockquote> | |
7341 | ||
7342 | <blockquote><para> | |
7343 | <programlisting> | |
7344 | Bool vgaHWCopyReg(vgaRegPtr dst, vgaRegPtr src); | |
7345 | </programlisting> | |
7346 | <blockquote><para> | |
7347 | This function copies the contents of the VGA saved registers in | |
7348 | <parameter>src</parameter> to <parameter>dst</parameter>. Note that it isn't | |
7349 | possible to simply do this with <function>memcpy()</function> (or | |
7350 | similar). This function returns <constant>TRUE</constant> unless there | |
7351 | is a problem allocating space for the <structfield>CRTC</structfield> and | |
7352 | related fields in <parameter>dst</parameter>. | |
7353 | </para> | |
7354 | ||
7355 | </blockquote></para></blockquote> | |
7356 | ||
7357 | <blockquote><para> | |
7358 | <programlisting> | |
7359 | void vgaHWSetStdFuncs(vgaHWPtr hwp); | |
7360 | </programlisting> | |
7361 | <blockquote><para> | |
7362 | This function initialises the register access function fields of | |
7363 | <parameter>hwp</parameter> with the standard VGA set of functions. This | |
7364 | is called by <function>vgaHWGetHWRec()</function>, so there is usually | |
7365 | no need to call this explicitly. The register access functions | |
7366 | are described below. If the registers are shadowed in some other | |
7367 | port I/O space (for example a PCI I/O region), these functions | |
7368 | can be used to access the shadowed registers if | |
7369 | <structfield>hwp->PIOOffset</structfield> is initialised with | |
7370 | <literal remap="tt">offset</literal>, calculated in such a way that when the | |
7371 | standard VGA I/O port value is added to it the correct offset into | |
7372 | the PIO area results. This value is initialised to zero in | |
7373 | <function>vgaHWGetHWRec()</function>. (Note: the PIOOffset functionality | |
7374 | is present in XFree86 4.1.0 and later.) | |
7375 | </para> | |
7376 | ||
7377 | </blockquote></para></blockquote> | |
7378 | ||
7379 | <blockquote><para> | |
7380 | <programlisting> | |
7381 | void vgaHWSetMmioFuncs(vgaHWPtr hwp, CARD8 *base, int offset); | |
7382 | </programlisting> | |
7383 | <blockquote><para> | |
7384 | This function initialised the register access function fields of | |
7385 | hwp with a generic MMIO set of functions. | |
7386 | <structfield>hwp->MMIOBase</structfield> is initialised with | |
7387 | <parameter>base</parameter>, which must be the virtual address that the | |
7388 | start of MMIO area is mapped to. <structfield>hwp->MMIOOffset</structfield> | |
7389 | is initialised with <parameter>offset</parameter>, which must be calculated | |
7390 | in such a way that when the standard VGA I/O port value is added | |
7391 | to it the correct offset into the MMIO area results. That means | |
7392 | that these functions are only suitable when the VGA I/O ports are | |
7393 | made available in a direct mapping to the MMIO space. If that is | |
7394 | not the case, the driver will need to provide its own register | |
7395 | access functions. The register access functions are described | |
7396 | below. | |
7397 | </para> | |
7398 | ||
7399 | </blockquote></para></blockquote> | |
7400 | ||
7401 | <blockquote><para> | |
7402 | <programlisting> | |
7403 | Bool vgaHWMapMem(ScrnInfoPtr pScrn); | |
7404 | </programlisting> | |
7405 | <blockquote><para> | |
7406 | This function maps the VGA memory window. It requires that the | |
7407 | <structname>vgaHWRec</structname> be allocated. If a driver requires | |
7408 | non-default <structfield>MapPhys</structfield> or <structfield>MapSize</structfield> | |
7409 | settings (the physical location and size of the VGA memory window) | |
7410 | then those fields of the <structname>vgaHWRec</structname> must be initialised | |
7411 | before calling this function. Otherwise, this function initialiases | |
7412 | the default values of <constant>0xA0000</constant> for | |
7413 | <structfield>MapPhys</structfield> and <code>(64 * 1024)</code> for | |
7414 | <structfield>MapSize</structfield>. This function must be called before | |
7415 | attempting to save or restore the VGA state. If the driver doesn't | |
7416 | call it explicitly, the <function>vgaHWSave()</function> and | |
7417 | <function>vgaHWRestore()</function> functions may call it if they need | |
7418 | to access the VGA memory (in which case they will also call | |
7419 | <function>vgaHWUnmapMem()</function> to unmap the VGA memory before | |
7420 | exiting). | |
7421 | </para> | |
7422 | ||
7423 | </blockquote></para></blockquote> | |
7424 | ||
7425 | <blockquote><para> | |
7426 | <programlisting> | |
7427 | void vgaHWUnmapMem(ScrnInfoPtr pScrn); | |
7428 | </programlisting> | |
7429 | <blockquote><para> | |
7430 | This function unmaps the VGA memory window. It must only be called | |
7431 | after the memory has been mapped. The <structfield>Base</structfield> field | |
7432 | of the <structname>vgaHWRec</structname> field is set to <constant>NULL</constant> | |
7433 | to indicate that the memory is no longer mapped. | |
7434 | </para> | |
7435 | ||
7436 | </blockquote></para></blockquote> | |
7437 | ||
7438 | <blockquote><para> | |
7439 | <programlisting> | |
7440 | void vgaHWGetIOBase(vgaHWPtr hwp); | |
7441 | </programlisting> | |
7442 | <blockquote><para> | |
7443 | This function initialises the <structfield>IOBase</structfield> field of the | |
7444 | <structname>vgaHWRec</structname>. This function must be called before | |
7445 | using any other functions that access the video hardware. | |
7446 | </para> | |
7447 | ||
7448 | <para> | |
7449 | A macro <function>VGAHW_GET_IOBASE()</function> is also available in | |
7450 | <filename>vgaHW.h</filename> that returns the I/O base, and this may | |
7451 | be used when the vgahw module is not loaded (for example, in the | |
7452 | <function>ChipProbe()</function> function). | |
7453 | </para> | |
7454 | ||
7455 | </blockquote></para></blockquote> | |
7456 | ||
7457 | <blockquote><para> | |
7458 | <programlisting> | |
7459 | void vgaHWUnlock(vgaHWPtr hwp); | |
7460 | </programlisting> | |
7461 | <blockquote><para> | |
7462 | This function unlocks the VGA <literal remap="tt">CRTC[0-7]</literal> registers, | |
7463 | and must be called before attempting to write to those registers. | |
7464 | </para> | |
7465 | ||
7466 | </blockquote></para></blockquote> | |
7467 | ||
7468 | <blockquote><para> | |
7469 | <programlisting> | |
7470 | void vgaHWLock(vgaHWPtr hwp); | |
7471 | </programlisting> | |
7472 | <blockquote><para> | |
7473 | This function locks the VGA <literal remap="tt">CRTC[0-7]</literal> registers. | |
7474 | </para> | |
7475 | ||
7476 | </blockquote></para></blockquote> | |
7477 | ||
7478 | <blockquote><para> | |
7479 | <programlisting> | |
7480 | void vgaHWEnable(vgaHWPtr hwp); | |
7481 | </programlisting> | |
7482 | <blockquote><para> | |
7483 | This function enables the VGA subsystem. (Note, this function is | |
7484 | present in XFree86 4.1.0 and later.). | |
7485 | </para> | |
7486 | ||
7487 | </blockquote></para></blockquote> | |
7488 | ||
7489 | <blockquote><para> | |
7490 | <programlisting> | |
7491 | void vgaHWDisable(vgaHWPtr hwp); | |
7492 | </programlisting> | |
7493 | <blockquote><para> | |
7494 | This function disables the VGA subsystem. (Note, this function is | |
7495 | present in XFree86 4.1.0 and later.). | |
7496 | </para> | |
7497 | ||
7498 | </blockquote></para></blockquote> | |
7499 | ||
7500 | <blockquote><para> | |
7501 | <programlisting> | |
7502 | void vgaHWSave(ScrnInfoPtr pScrn, vgaRegPtr save, int flags); | |
7503 | </programlisting> | |
7504 | <blockquote><para> | |
7505 | This function saves the VGA state. The state is written to the | |
7506 | <structname>vgaRegRec</structname> pointed to by <parameter>save</parameter>. | |
7507 | <parameter>flags</parameter> is set to one or more of the following flags | |
7508 | ORed together: | |
7509 | ||
7510 | <variablelist> | |
7511 | <varlistentry> | |
7512 | <term><constant>VGA_SR_MODE</constant></term> | |
7513 | <listitem><para>the mode setting registers are saved | |
7514 | </para></listitem></varlistentry> | |
7515 | <varlistentry> | |
7516 | <term><constant>VGA_SR_FONTS</constant></term> | |
7517 | <listitem><para>the text mode font/text data is saved | |
7518 | </para></listitem></varlistentry> | |
7519 | <varlistentry> | |
7520 | <term><constant>VGA_SR_CMAP</constant></term> | |
7521 | <listitem><para>the colourmap (LUT) is saved | |
7522 | </para></listitem></varlistentry> | |
7523 | <varlistentry> | |
7524 | <term><constant>VGA_SR_ALL</constant></term> | |
7525 | <listitem><para>all of the above are saved | |
7526 | </para></listitem></varlistentry> | |
7527 | </variablelist> | |
7528 | </para> | |
7529 | ||
7530 | <para> | |
7531 | The <structname>vgaHWRec</structname> and its <structfield>IOBase</structfield> fields | |
7532 | must be initialised before this function is called. If | |
7533 | <constant>VGA_SR_FONTS</constant> is set in <parameter>flags</parameter>, the | |
7534 | VGA memory window must be mapped. If it isn't then | |
7535 | <function>vgaHWMapMem()</function> will be called to map it, and | |
7536 | <function>vgaHWUnmapMem()</function> will be called to unmap it | |
7537 | afterwards. <function>vgaHWSave()</function> uses the three functions | |
7538 | below in the order <function>vgaHWSaveColormap()</function>, | |
7539 | <function>vgaHWSaveMode()</function>, <function>vgaHWSaveFonts()</function> to | |
7540 | carry out the different save phases. It is undecided at this | |
7541 | stage whether they will remain part of the vgahw module's public | |
7542 | interface or not. | |
7543 | </para> | |
7544 | ||
7545 | </blockquote></para></blockquote> | |
7546 | ||
7547 | <blockquote><para> | |
7548 | <programlisting> | |
7549 | void vgaHWSaveMode(ScrnInfoPtr pScrn, vgaRegPtr save); | |
7550 | </programlisting> | |
7551 | <blockquote><para> | |
7552 | This function saves the VGA mode registers. They are saved to | |
7553 | the <structname>vgaRegRec</structname> pointed to by <parameter>save</parameter>. | |
7554 | The registers saved are: | |
7555 | ||
7556 | <literallayout> | |
7557 | MiscOut | |
7558 | CRTC[0-0x18] | |
7559 | Attribute[0-0x14] | |
7560 | Graphics[0-8] | |
7561 | Sequencer[0-4] | |
7562 | </literallayout> | |
7563 | </para> | |
7564 | ||
7565 | <para> | |
7566 | The number of registers actually saved may be modified by a prior call | |
7567 | to <function>vgaHWSetRegCounts()</function>. | |
7568 | </para> | |
7569 | ||
7570 | </blockquote></para></blockquote> | |
7571 | ||
7572 | <blockquote><para> | |
7573 | <programlisting> | |
7574 | void vgaHWSaveFonts(ScrnInfoPtr pScrn, vgaRegPtr save); | |
7575 | </programlisting> | |
7576 | <blockquote><para> | |
7577 | This function saves the text mode font and text data held in the | |
7578 | video memory. If called while in a graphics mode, no save is | |
7579 | done. The VGA memory window must be mapped with | |
7580 | <function>vgaHWMapMem()</function> before to calling this function. | |
7581 | </para> | |
7582 | ||
7583 | <para> | |
7584 | On some platforms, one or more of the font/text plane saves may be | |
7585 | no-ops. This is the case when the platform's VC driver already | |
7586 | takes care of this. | |
7587 | </para> | |
7588 | ||
7589 | </blockquote></para></blockquote> | |
7590 | ||
7591 | <blockquote><para> | |
7592 | <programlisting> | |
7593 | void vgaHWSaveColormap(ScrnInfoPtr pScrn, vgaRegPtr save); | |
7594 | </programlisting> | |
7595 | <blockquote><para> | |
7596 | This function saves the VGA colourmap (LUT). Before saving it, it | |
7597 | attempts to verify that the colourmap is readable. In rare cases | |
7598 | where it isn't readable, a default colourmap is saved instead. | |
7599 | </para> | |
7600 | ||
7601 | </blockquote></para></blockquote> | |
7602 | ||
7603 | <blockquote><para> | |
7604 | <programlisting> | |
7605 | void vgaHWRestore(ScrnInfoPtr pScrn, vgaRegPtr restore, int flags); | |
7606 | </programlisting> | |
7607 | <blockquote><para> | |
7608 | This function programs the VGA state. The state programmed is | |
7609 | that contained in the <structname>vgaRegRec</structname> pointed to by | |
7610 | <parameter>restore</parameter>. <parameter>flags</parameter> is the same | |
7611 | as described above for the <function>vgaHWSave()</function> function. | |
7612 | </para> | |
7613 | ||
7614 | <para> | |
7615 | The <structname>vgaHWRec</structname> and its <structfield>IOBase</structfield> fields | |
7616 | must be initialised before this function is called. If | |
7617 | <constant>VGA_SR_FONTS</constant> is set in <parameter>flags</parameter>, the | |
7618 | VGA memory window must be mapped. If it isn't then | |
7619 | <function>vgaHWMapMem()</function> will be called to map it, and | |
7620 | <function>vgaHWUnmapMem()</function> will be called to unmap it | |
7621 | afterwards. <function>vgaHWRestore()</function> uses the three functions | |
7622 | below in the order <function>vgaHWRestoreFonts()</function>, | |
7623 | <function>vgaHWRestoreMode()</function>, | |
7624 | <function>vgaHWRestoreColormap()</function> to carry out the different | |
7625 | restore phases. It is undecided at this stage whether they will | |
7626 | remain part of the vgahw module's public interface or not. | |
7627 | </para> | |
7628 | ||
7629 | </blockquote></para></blockquote> | |
7630 | ||
7631 | <blockquote><para> | |
7632 | <programlisting> | |
7633 | void vgaHWRestoreMode(ScrnInfoPtr pScrn, vgaRegPtr restore); | |
7634 | </programlisting> | |
7635 | <blockquote><para> | |
7636 | This function restores the VGA mode registers. They are restored | |
7637 | from the data in the <structname>vgaRegRec</structname> pointed to by | |
7638 | <parameter>restore</parameter>. The registers restored are: | |
7639 | ||
7640 | <literallayout> | |
7641 | MiscOut | |
7642 | CRTC[0-0x18] | |
7643 | Attribute[0-0x14] | |
7644 | Graphics[0-8] | |
7645 | Sequencer[0-4] | |
7646 | </literallayout> | |
7647 | </para> | |
7648 | ||
7649 | <para> | |
7650 | The number of registers actually restored may be modified by a prior call | |
7651 | to <function>vgaHWSetRegCounts()</function>. | |
7652 | </para> | |
7653 | ||
7654 | </blockquote></para></blockquote> | |
7655 | ||
7656 | <blockquote><para> | |
7657 | <programlisting> | |
7658 | void vgaHWRestoreFonts(ScrnInfoPtr pScrn, vgaRegPtr restore); | |
7659 | </programlisting> | |
7660 | <blockquote><para> | |
7661 | This function restores the text mode font and text data to the | |
7662 | video memory. The VGA memory window must be mapped with | |
7663 | <function>vgaHWMapMem()</function> before to calling this function. | |
7664 | </para> | |
7665 | ||
7666 | <para> | |
7667 | On some platforms, one or more of the font/text plane restores | |
7668 | may be no-ops. This is the case when the platform's VC driver | |
7669 | already takes care of this. | |
7670 | </para> | |
7671 | ||
7672 | </blockquote></para></blockquote> | |
7673 | ||
7674 | <blockquote><para> | |
7675 | <programlisting> | |
7676 | void vgaHWRestoreColormap(ScrnInfoPtr pScrn, vgaRegPtr restore); | |
7677 | </programlisting> | |
7678 | <blockquote><para> | |
7679 | This function restores the VGA colourmap (LUT). | |
7680 | </para> | |
7681 | ||
7682 | </blockquote></para></blockquote> | |
7683 | ||
7684 | <blockquote><para> | |
7685 | <programlisting> | |
7686 | void vgaHWInit(ScrnInfoPtr pScrn, DisplayModePtr mode); | |
7687 | </programlisting> | |
7688 | <blockquote><para> | |
7689 | This function fills in the <structname>vgaHWRec</structname>'s | |
7690 | <structfield>ModeReg</structfield> field with the values appropriate for | |
7691 | programming the given video mode. It requires that the | |
7692 | <structname>ScrnInfoRec</structname>'s <structfield>depth</structfield> field is | |
7693 | initialised, which determines how the registers are programmed. | |
7694 | </para> | |
7695 | ||
7696 | </blockquote></para></blockquote> | |
7697 | ||
7698 | <blockquote><para> | |
7699 | <programlisting> | |
7700 | void vgaHWSeqReset(vgaHWPtr hwp, Bool start); | |
7701 | </programlisting> | |
7702 | <blockquote><para> | |
7703 | Do a VGA sequencer reset. If start is <constant>TRUE</constant>, the | |
7704 | reset is started. If start is <constant>FALSE</constant>, the reset | |
7705 | is ended. | |
7706 | </para> | |
7707 | ||
7708 | </blockquote></para></blockquote> | |
7709 | ||
7710 | <blockquote><para> | |
7711 | <programlisting> | |
7712 | void vgaHWProtect(ScrnInfoPtr pScrn, Bool on); | |
7713 | </programlisting> | |
7714 | <blockquote><para> | |
7715 | This function protects VGA registers and memory from corruption | |
7716 | during loads. It is typically called with on set to | |
7717 | <constant>TRUE</constant> before programming, and with on set to | |
7718 | <constant>FALSE</constant> after programming. | |
7719 | </para> | |
7720 | ||
7721 | </blockquote></para></blockquote> | |
7722 | ||
7723 | <blockquote><para> | |
7724 | <programlisting> | |
7725 | Bool vgaHWSaveScreen(ScreenPtr pScreen, int mode); | |
7726 | </programlisting> | |
7727 | <blockquote><para> | |
7728 | This function blanks and unblanks the screen. It is blanked when | |
7729 | <parameter>mode</parameter> is <constant>SCREEN_SAVER_ON</constant> or | |
7730 | <constant>SCREEN_SAVER_CYCLE</constant>, and unblanked when | |
7731 | <parameter>mode</parameter> is <constant>SCREEN_SAVER_OFF</constant> or | |
7732 | <constant>SCREEN_SAVER_FORCER</constant>. | |
7733 | </para> | |
7734 | ||
7735 | </blockquote></para></blockquote> | |
7736 | ||
7737 | <blockquote><para> | |
7738 | <programlisting> | |
7739 | void vgaHWBlankScreen(ScrnInfoPtr pScrn, Bool on); | |
7740 | </programlisting> | |
7741 | <blockquote><para> | |
7742 | This function blanks and unblanks the screen. It is blanked when | |
7743 | <parameter>on</parameter> is <constant>FALSE</constant>, and unblanked when | |
7744 | <parameter>on</parameter> is <constant>TRUE</constant>. This function is | |
7745 | provided for use in cases where the <structname>ScrnInfoRec</structname> | |
7746 | can't be derived from the <structname>ScreenRec</structname> (while probing | |
7747 | for clocks, for example). | |
7748 | </para> | |
7749 | ||
7750 | </blockquote></para></blockquote> | |
7751 | ||
7752 | </sect2> | |
7753 | ||
7754 | <sect2> | |
7755 | <title>VGA Colormap Functions</title> | |
7756 | ||
7757 | <para> | |
7758 | The vgahw module uses the standard colormap support (see the | |
7759 | <link linkend="cmap">Colormap Handling</link> section. This is initialised | |
7760 | with the following function: | |
7761 | ||
7762 | <blockquote><para> | |
7763 | <programlisting> | |
7764 | Bool vgaHWHandleColormaps(ScreenPtr pScreen); | |
7765 | </programlisting> | |
7766 | </para></blockquote> | |
7767 | </para> | |
7768 | ||
7769 | </sect2> | |
7770 | ||
7771 | <sect2> | |
7772 | <title>VGA Register Access Functions</title> | |
7773 | ||
7774 | <para> | |
7775 | The vgahw module abstracts access to the standard VGA registers by | |
7776 | using a set of functions held in the <structname>vgaHWRec</structname>. When | |
7777 | the <structname>vgaHWRec</structname> is created these function pointers are | |
7778 | initialised with the set of standard VGA I/O register access functions. | |
7779 | In addition to these, the vgahw module includes a basic set of MMIO | |
7780 | register access functions, and the <structname>vgaHWRec</structname> function | |
7781 | pointers can be initialised to these by calling the | |
7782 | <function>vgaHWSetMmioFuncs()</function> function described above. Some | |
7783 | drivers/platforms may require a different set of functions for VGA | |
7784 | access. The access functions are described here. | |
7785 | </para> | |
7786 | ||
7787 | ||
7788 | <blockquote><para> | |
7789 | <programlisting> | |
7790 | void writeCrtc(vgaHWPtr hwp, CARD8 index, CARD8 value); | |
7791 | </programlisting> | |
7792 | <blockquote><para> | |
7793 | Write <parameter>value</parameter> to CRTC register <parameter>index</parameter>. | |
7794 | </para> | |
7795 | ||
7796 | </blockquote></para></blockquote> | |
7797 | ||
7798 | <blockquote><para> | |
7799 | <programlisting> | |
7800 | CARD8 readCrtc(vgaHWPtr hwp, CARD8 index); | |
7801 | </programlisting> | |
7802 | <blockquote><para> | |
7803 | Return the value read from CRTC register <parameter>index</parameter>. | |
7804 | </para> | |
7805 | ||
7806 | </blockquote></para></blockquote> | |
7807 | ||
7808 | <blockquote><para> | |
7809 | <programlisting> | |
7810 | void writeGr(vgaHWPtr hwp, CARD8 index, CARD8 value); | |
7811 | </programlisting> | |
7812 | <blockquote><para> | |
7813 | Write <parameter>value</parameter> to Graphics Controller register | |
7814 | <parameter>index</parameter>. | |
7815 | </para> | |
7816 | ||
7817 | </blockquote></para></blockquote> | |
7818 | ||
7819 | <blockquote><para> | |
7820 | <programlisting> | |
7821 | CARD8 readGR(vgaHWPtr hwp, CARD8 index); | |
7822 | </programlisting> | |
7823 | <blockquote><para> | |
7824 | Return the value read from Graphics Controller register | |
7825 | <parameter>index</parameter>. | |
7826 | </para> | |
7827 | ||
7828 | </blockquote></para></blockquote> | |
7829 | ||
7830 | <blockquote><para> | |
7831 | <programlisting> | |
7832 | void writeSeq(vgaHWPtr hwp, CARD8 index, CARD8, value); | |
7833 | </programlisting> | |
7834 | <blockquote><para> | |
7835 | Write <parameter>value</parameter> to Sequencer register | |
7836 | <parameter>index</parameter>. | |
7837 | </para> | |
7838 | ||
7839 | </blockquote></para></blockquote> | |
7840 | ||
7841 | <blockquote><para> | |
7842 | <programlisting> | |
7843 | CARD8 readSeq(vgaHWPtr hwp, CARD8 index); | |
7844 | </programlisting> | |
7845 | <blockquote><para> | |
7846 | Return the value read from Sequencer register <parameter>index</parameter>. | |
7847 | </para> | |
7848 | ||
7849 | </blockquote></para></blockquote> | |
7850 | ||
7851 | <blockquote><para> | |
7852 | <programlisting> | |
7853 | void writeAttr(vgaHWPtr hwp, CARD8 index, CARD8, value); | |
7854 | </programlisting> | |
7855 | <blockquote><para> | |
7856 | Write <parameter>value</parameter> to Attribute Controller register | |
7857 | <parameter>index</parameter>. When writing out the index value this | |
7858 | function should set bit 5 (<constant>0x20</constant>) according to the | |
7859 | setting of <structfield>hwp->paletteEnabled</structfield> in order to | |
7860 | preserve the palette access state. It should be cleared when | |
7861 | <structfield>hwp->paletteEnabled</structfield> is <constant>TRUE</constant> | |
7862 | and set when it is <constant>FALSE</constant>. | |
7863 | </para> | |
7864 | ||
7865 | </blockquote></para></blockquote> | |
7866 | ||
7867 | <blockquote><para> | |
7868 | <programlisting> | |
7869 | CARD8 readAttr(vgaHWPtr hwp, CARD8 index); | |
7870 | </programlisting> | |
7871 | <blockquote><para> | |
7872 | Return the value read from Attribute Controller register | |
7873 | <parameter>index</parameter>. When writing out the index value this | |
7874 | function should set bit 5 (<constant>0x20</constant>) according to the | |
7875 | setting of <structfield>hwp->paletteEnabled</structfield> in order to | |
7876 | preserve the palette access state. It should be cleared when | |
7877 | <structfield>hwp->paletteEnabled</structfield> is <constant>TRUE</constant> | |
7878 | and set when it is <constant>FALSE</constant>. | |
7879 | </para> | |
7880 | ||
7881 | </blockquote></para></blockquote> | |
7882 | ||
7883 | <blockquote><para> | |
7884 | <programlisting> | |
7885 | void writeMiscOut(vgaHWPtr hwp, CARD8 value); | |
7886 | </programlisting> | |
7887 | <blockquote><para> | |
7888 | Write <quote><parameter>value</parameter></quote> to the Miscellaneous Output register. | |
7889 | </para> | |
7890 | ||
7891 | </blockquote></para></blockquote> | |
7892 | ||
7893 | <blockquote><para> | |
7894 | <programlisting> | |
7895 | CARD8 readMiscOut(vgwHWPtr hwp); | |
7896 | </programlisting> | |
7897 | <blockquote><para> | |
7898 | Return the value read from the Miscellaneous Output register. | |
7899 | </para> | |
7900 | ||
7901 | </blockquote></para></blockquote> | |
7902 | ||
7903 | <blockquote><para> | |
7904 | <programlisting> | |
7905 | void enablePalette(vgaHWPtr hwp); | |
7906 | </programlisting> | |
7907 | <blockquote><para> | |
7908 | Clear the palette address source bit in the Attribute Controller | |
7909 | index register and set <literal remap="tt">hwp->paletteEnabled</literal> to | |
7910 | <constant>TRUE</constant>. | |
7911 | </para> | |
7912 | ||
7913 | </blockquote></para></blockquote> | |
7914 | ||
7915 | <blockquote><para> | |
7916 | <programlisting> | |
7917 | void disablePalette(vgaHWPtr hwp); | |
7918 | </programlisting> | |
7919 | <blockquote><para> | |
7920 | Set the palette address source bit in the Attribute Controller | |
7921 | index register and set <literal remap="tt">hwp->paletteEnabled</literal> to | |
7922 | <constant>FALSE</constant>. | |
7923 | </para> | |
7924 | ||
7925 | </blockquote></para></blockquote> | |
7926 | ||
7927 | <blockquote><para> | |
7928 | <programlisting> | |
7929 | void writeDacMask(vgaHWPtr hwp, CARD8 value); | |
7930 | </programlisting> | |
7931 | <blockquote><para> | |
7932 | Write <parameter>value</parameter> to the DAC Mask register. | |
7933 | </para> | |
7934 | ||
7935 | </blockquote></para></blockquote> | |
7936 | ||
7937 | <blockquote><para> | |
7938 | <programlisting> | |
7939 | CARD8 readDacMask(vgaHWptr hwp); | |
7940 | </programlisting> | |
7941 | <blockquote><para> | |
7942 | Return the value read from the DAC Mask register. | |
7943 | </para> | |
7944 | ||
7945 | </blockquote></para></blockquote> | |
7946 | ||
7947 | <blockquote><para> | |
7948 | <programlisting> | |
7949 | void writeDacReadAddress(vgaHWPtr hwp, CARD8 value); | |
7950 | </programlisting> | |
7951 | <blockquote><para> | |
7952 | Write <parameter>value</parameter> to the DAC Read Address register. | |
7953 | </para> | |
7954 | ||
7955 | </blockquote></para></blockquote> | |
7956 | ||
7957 | <blockquote><para> | |
7958 | <programlisting> | |
7959 | void writeDacWriteAddress(vgaHWPtr hwp, CARD8 value); | |
7960 | </programlisting> | |
7961 | <blockquote><para> | |
7962 | Write <parameter>value</parameter> to the DAC Write Address register. | |
7963 | </para> | |
7964 | ||
7965 | </blockquote></para></blockquote> | |
7966 | ||
7967 | <blockquote><para> | |
7968 | <programlisting> | |
7969 | void writeDacData(vgaHWPtr hwp, CARD8 value); | |
7970 | </programlisting> | |
7971 | <blockquote><para> | |
7972 | Write <parameter>value</parameter> to the DAC Data register. | |
7973 | </para> | |
7974 | ||
7975 | </blockquote></para></blockquote> | |
7976 | ||
7977 | <blockquote><para> | |
7978 | <programlisting> | |
7979 | CARD8 readDacData(vgaHWptr hwp); | |
7980 | </programlisting> | |
7981 | <blockquote><para> | |
7982 | Return the value read from the DAC Data register. | |
7983 | </para> | |
7984 | ||
7985 | </blockquote></para></blockquote> | |
7986 | ||
7987 | <blockquote><para> | |
7988 | <programlisting> | |
7989 | CARD8 readEnable(vgaHWptr hwp); | |
7990 | </programlisting> | |
7991 | <blockquote><para> | |
7992 | Return the value read from the VGA Enable register. (Note: This | |
7993 | function is present in XFree86 4.1.0 and later.) | |
7994 | </para> | |
7995 | ||
7996 | </blockquote></para></blockquote> | |
7997 | ||
7998 | <blockquote><para> | |
7999 | <programlisting> | |
8000 | void writeEnable(vgaHWPtr hwp, CARD8 value); | |
8001 | </programlisting> | |
8002 | <blockquote><para> | |
8003 | Write <parameter>value</parameter> to the VGA Enable register. (Note: This | |
8004 | function is present in XFree86 4.1.0 and later.) | |
8005 | </para> | |
8006 | ||
8007 | </blockquote></para></blockquote> | |
8008 | </sect2> | |
8009 | </sect1> | |
8010 | ||
8011 | <sect1 id="sample"> | |
8012 | <title>Some notes about writing a driver</title> | |
8013 | ||
8014 | <note><para>NOTE: some parts of this are not up to date</para></note> | |
8015 | ||
8016 | <para> | |
8017 | The following is an outline for writing a basic unaccelerated driver | |
8018 | for a PCI video card with a linear mapped framebuffer, and which has a | |
8019 | VGA core. It is includes some general information that is relevant to | |
8020 | most drivers (even those which don't fit that basic description). | |
8021 | </para> | |
8022 | ||
8023 | <para> | |
8024 | The information here is based on the initial conversion of the Matrox | |
8025 | Millennium driver to the <quote>new design</quote>. For a fleshing out and sample | |
8026 | implementation of some of the bits outlined here, refer to that driver. | |
8027 | Note that this is an example only. The approach used here will not be | |
8028 | appropriate for all drivers. | |
8029 | </para> | |
8030 | ||
8031 | <para> | |
8032 | Each driver must reserve a unique driver name, and a string that is used | |
8033 | to prefix all of its externally visible symbols. This is to avoid name | |
8034 | space clashes when loading multiple drivers. The examples here are for | |
8035 | the <quote>ZZZ</quote> driver, which uses the <quote>ZZZ</quote> or <quote>zzz</quote> prefix for its externally | |
8036 | visible symbols. | |
8037 | </para> | |
8038 | ||
8039 | <sect2> | |
8040 | <title>Include files</title> | |
8041 | ||
8042 | <para> | |
8043 | All drivers normally include the following headers: | |
8044 | <literallayout><filename> | |
8045 | "xf86.h" | |
8046 | "xf86_OSproc.h" | |
8047 | "xf86_ansic.h" | |
8048 | "xf86Resources.h" | |
8049 | </filename></literallayout> | |
8050 | Wherever inb/outb (and related things) are used the following should be | |
8051 | included: | |
8052 | <literallayout><filename> | |
8053 | "compiler.h" | |
8054 | </filename></literallayout> | |
8055 | Note: in drivers, this must be included after <filename>"xf86_ansic.h"</filename>. | |
8056 | </para> | |
8057 | ||
8058 | <para> | |
8059 | Drivers that need to access PCI vendor/device definitions need this: | |
8060 | <literallayout><filename> | |
8061 | "xf86PciInfo.h" | |
8062 | </filename></literallayout> | |
8063 | </para> | |
8064 | ||
8065 | <para> | |
8066 | Drivers that need to access the PCI config space need this: | |
8067 | <literallayout><filename> | |
8068 | "xf86Pci.h" | |
8069 | </filename></literallayout> | |
8070 | </para> | |
8071 | ||
8072 | <para> | |
8073 | Drivers using the mi banking wrapper need: | |
8074 | ||
8075 | <literallayout><filename> | |
8076 | "mibank.h" | |
8077 | </filename></literallayout> | |
8078 | </para> | |
8079 | ||
8080 | <para> | |
8081 | Drivers that initialise a SW cursor need this: | |
8082 | <literallayout><filename> | |
8083 | "mipointer.h" | |
8084 | </filename></literallayout> | |
8085 | </para> | |
8086 | ||
8087 | <para> | |
8088 | All drivers using the mi colourmap code need this: | |
8089 | <literallayout><filename> | |
8090 | "micmap.h" | |
8091 | </filename></literallayout> | |
8092 | </para> | |
8093 | ||
8094 | <para> | |
8095 | If a driver uses the vgahw module, it needs this: | |
8096 | <literallayout><filename> | |
8097 | "vgaHW.h" | |
8098 | </filename></literallayout> | |
8099 | </para> | |
8100 | ||
8101 | <para> | |
8102 | Drivers supporting VGA or Hercules monochrome screens need: | |
8103 | <literallayout><filename> | |
8104 | "xf1bpp.h" | |
8105 | </filename></literallayout> | |
8106 | </para> | |
8107 | ||
8108 | <para> | |
8109 | Drivers supporting VGA or EGC 16-colour screens need: | |
8110 | <literallayout><filename> | |
8111 | "xf4bpp.h" | |
8112 | </filename></literallayout> | |
8113 | </para> | |
8114 | ||
8115 | <para> | |
8116 | Drivers using cfb need: | |
8117 | <programlisting> | |
8118 | #define PSZ 8 | |
8119 | #include "cfb.h" | |
8120 | #undef PSZ | |
8121 | </programlisting> | |
8122 | </para> | |
8123 | ||
8124 | <para> | |
8125 | Drivers supporting bpp 16, 24 or 32 with cfb need one or more of: | |
8126 | <literallayout><filename> | |
8127 | "cfb16.h" | |
8128 | "cfb24.h" | |
8129 | "cfb32.h" | |
8130 | </filename></literallayout> | |
8131 | </para> | |
8132 | ||
8133 | <para> | |
8134 | The driver's own header file: | |
8135 | <literallayout><filename> | |
8136 | "zzz.h" | |
8137 | </filename></literallayout> | |
8138 | </para> | |
8139 | ||
8140 | <para> | |
8141 | Drivers must NOT include the following: | |
8142 | ||
8143 | <literallayout><filename> | |
8144 | "xf86Priv.h" | |
8145 | "xf86Privstr.h" | |
8146 | "xf86_libc.h" | |
8147 | "xf86_OSlib.h" | |
8148 | "Xos.h"</filename> | |
8149 | any OS header | |
8150 | </literallayout> | |
8151 | </para> | |
8152 | ||
8153 | </sect2> | |
8154 | ||
8155 | <sect2> | |
8156 | <title>Data structures and initialisation</title> | |
8157 | ||
8158 | <itemizedlist> | |
8159 | <listitem> | |
8160 | <para>The following macros should be defined: | |
8161 | <programlisting> | |
8162 | #define VERSION <version-as-an-int> | |
8163 | #define ZZZ_NAME "ZZZ" /* the name used to prefix messages */ | |
8164 | #define ZZZ_DRIVER_NAME "zzz" /* the driver name as used in config file */ | |
8165 | #define ZZZ_MAJOR_VERSION <int> | |
8166 | #define ZZZ_MINOR_VERSION <int> | |
8167 | #define ZZZ_PATCHLEVEL <int> | |
8168 | </programlisting> | |
8169 | </para> | |
8170 | <para> | |
8171 | NOTE: <constant>ZZZ_DRIVER_NAME</constant> should match the name of the | |
8172 | driver module without things like the "lib" prefix, the "_drv" suffix | |
8173 | or filename extensions. | |
8174 | </para> | |
8175 | </listitem> | |
8176 | ||
8177 | <listitem> | |
8178 | <para> | |
8179 | A DriverRec must be defined, which includes the functions required | |
8180 | at the pre-probe phase. The name of this DriverRec must be an | |
8181 | upper-case version of ZZZ_DRIVER_NAME (for the purposes of static | |
8182 | linking). | |
8183 | <programlisting> | |
8184 | DriverRec ZZZ = { | |
8185 | VERSION, | |
8186 | ZZZ_DRIVER_NAME, | |
8187 | ZZZIdentify, | |
8188 | ZZZProbe, | |
8189 | ZZZAvailableOptions, | |
8190 | NULL, | |
8191 | 0 | |
8192 | }; | |
8193 | </programlisting> | |
8194 | </para> | |
8195 | </listitem> | |
8196 | ||
8197 | <listitem> | |
8198 | <para>Define list of supported chips and their matching ID: | |
8199 | <programlisting> | |
8200 | static SymTabRec ZZZChipsets[] = { | |
8201 | { PCI_CHIP_ZZZ1234, "zzz1234a" }, | |
8202 | { PCI_CHIP_ZZZ5678, "zzz5678a" }, | |
8203 | { -1, NULL } | |
8204 | }; | |
8205 | </programlisting> | |
8206 | </para> | |
8207 | <para> | |
8208 | The token field may be any integer value that the driver may use to | |
8209 | uniquely identify the supported chipsets. For drivers that support | |
8210 | only PCI devices using the PCI device IDs might be a natural choice, | |
8211 | but this isn't mandatory. For drivers that support both PCI and other | |
8212 | devices (like ISA), some other ID should probably used. When other | |
8213 | IDs are used as the tokens it is recommended that the names be | |
8214 | defined as an <type>enum</type> type. | |
8215 | </para> | |
8216 | </listitem> | |
8217 | ||
8218 | <listitem> | |
8219 | <para> | |
8220 | If the driver uses the <function>xf86MatchPciInstances()</function> | |
8221 | helper (recommended for drivers that support PCI cards) a list that | |
8222 | maps PCI IDs to chip IDs and fixed resources must be defined: | |
8223 | <programlisting> | |
8224 | static PciChipsets ZZZPciChipsets[] = { | |
8225 | { PCI_CHIP_ZZZ1234, PCI_CHIP_ZZZ1234, RES_SHARED_VGA }, | |
8226 | { PCI_CHIP_ZZZ5678, PCI_CHIP_ZZZ5678, RES_SHARED_VGA }, | |
8227 | { -1, -1, RES_UNDEFINED } | |
8228 | } | |
8229 | </programlisting> | |
8230 | </para> | |
8231 | </listitem> | |
8232 | ||
8233 | <listitem> | |
8234 | <para> | |
8235 | Define the <structname>XF86ModuleVersionInfo</structname> struct for the | |
8236 | driver. This is required for the dynamically loaded version: | |
8237 | <programlisting> | |
8238 | static XF86ModuleVersionInfo zzzVersRec = | |
8239 | { | |
8240 | "zzz", | |
8241 | MODULEVENDORSTRING, | |
8242 | MODINFOSTRING1, | |
8243 | MODINFOSTRING2, | |
8244 | XF86_VERSION_CURRENT, | |
8245 | ZZZ_MAJOR_VERSION, ZZZ_MINOR_VERSION, ZZZ_PATCHLEVEL, | |
8246 | ABI_CLASS_VIDEODRV, | |
8247 | ABI_VIDEODRV_VERSION, | |
8248 | MOD_CLASS_VIDEODRV, | |
8249 | {0,0,0,0} | |
8250 | }; | |
8251 | </programlisting> | |
8252 | </para> | |
8253 | </listitem> | |
8254 | ||
8255 | <listitem> | |
8256 | <para> | |
8257 | Define a data structure to hold the driver's screen-specific data. | |
8258 | This must be used instead of global variables. This would be defined | |
8259 | in the <filename>"zzz.h"</filename> file, something like: | |
8260 | <programlisting> | |
8261 | typedef struct { | |
8262 | type1 field1; | |
8263 | type2 field2; | |
8264 | int fooHack; | |
8265 | Bool pciRetry; | |
8266 | Bool noAccel; | |
8267 | Bool hwCursor; | |
8268 | CloseScreenProcPtr CloseScreen; | |
8269 | OptionInfoPtr Options; | |
8270 | ... | |
8271 | } ZZZRec, *ZZZPtr; | |
8272 | </programlisting> | |
8273 | </para> | |
8274 | </listitem> | |
8275 | ||
8276 | <listitem> | |
8277 | <para> | |
8278 | Define the list of config file Options that the driver accepts. For | |
8279 | consistency between drivers those in the list of <quote>standard</quote> options | |
8280 | should be used where appropriate before inventing new options. | |
8281 | ||
8282 | <programlisting> | |
8283 | typedef enum { | |
8284 | OPTION_FOO_HACK, | |
8285 | OPTION_PCI_RETRY, | |
8286 | OPTION_HW_CURSOR, | |
8287 | OPTION_NOACCEL | |
8288 | } ZZZOpts; | |
8289 | ||
8290 | static const OptionInfoRec ZZZOptions[] = { | |
8291 | { OPTION_FOO_HACK, "FooHack", OPTV_INTEGER, {0}, FALSE }, | |
8292 | { OPTION_PCI_RETRY, "PciRetry", OPTV_BOOLEAN, {0}, FALSE }, | |
8293 | { OPTION_HW_CURSOR, "HWcursor", OPTV_BOOLEAN, {0}, FALSE }, | |
8294 | { OPTION_NOACCEL, "NoAccel", OPTV_BOOLEAN, {0}, FALSE }, | |
8295 | { -1, NULL, OPTV_NONE, {0}, FALSE } | |
8296 | }; | |
8297 | </programlisting> | |
8298 | </para> | |
8299 | </listitem> | |
8300 | </itemizedlist> | |
8301 | </sect2> | |
8302 | ||
8303 | <sect2> | |
8304 | <title>Functions</title> | |
8305 | ||
8306 | ||
8307 | <sect3> | |
8308 | <title>SetupProc</title> | |
8309 | ||
8310 | <para> | |
8311 | For dynamically loaded modules, a <varname>ModuleData</varname> | |
8312 | variable is required. It is should be the name of the driver | |
8313 | prepended to "ModuleData". A <function>Setup()</function> function is | |
8314 | also required, which calls <function>xf86AddDriver()</function> to add | |
8315 | the driver to the main list of drivers. | |
8316 | </para> | |
8317 | ||
8318 | <programlisting> | |
8319 | static MODULESETUPPROTO(zzzSetup); | |
8320 | ||
8321 | XF86ModuleData zzzModuleData = { &zzzVersRec, zzzSetup, NULL }; | |
8322 | ||
8323 | static pointer | |
8324 | zzzSetup(pointer module, pointer opts, int *errmaj, int *errmin) | |
8325 | { | |
8326 | static Bool setupDone = FALSE; | |
8327 | ||
8328 | /* This module should be loaded only once, but check to be sure. */ | |
8329 | ||
8330 | if (!setupDone) { | |
8331 | /* | |
8332 | * Modules that this driver always requires may be loaded | |
8333 | * here by calling LoadSubModule(). | |
8334 | */ | |
8335 | ||
8336 | setupDone = TRUE; | |
8337 | xf86AddDriver(&MGA, module, 0); | |
8338 | ||
8339 | /* | |
8340 | * The return value must be non-NULL on success even though | |
8341 | * there is no TearDownProc. | |
8342 | */ | |
8343 | return (pointer)1; | |
8344 | } else { | |
8345 | if (errmaj) *errmaj = LDR_ONCEONLY; | |
8346 | return NULL; | |
8347 | } | |
8348 | } | |
8349 | </programlisting> | |
8350 | </sect3> | |
8351 | ||
8352 | <sect3> | |
8353 | <title>GetRec, FreeRec</title> | |
8354 | ||
8355 | <para> | |
8356 | A function is usually required to allocate the driver's | |
8357 | screen-specific data structure and hook it into the | |
8358 | <structname>ScrnInfoRec</structname>'s <structfield>driverPrivate</structfield> field. | |
8359 | The <structname>ScrnInfoRec</structname>'s <structfield>driverPrivate</structfield> is | |
8360 | initialised to <constant>NULL</constant>, so it is easy to check if the | |
8361 | initialisation has already been done. After allocating it, initialise | |
8362 | the fields. By using <function>xnfcalloc()</function> to do the allocation | |
8363 | it is zeroed, and if the allocation fails the server exits. | |
8364 | </para> | |
8365 | ||
8366 | <para> | |
8367 | NOTE: | |
8368 | When allocating structures from inside the driver which are defined | |
8369 | on the common level it is important to initialize the structure to | |
8370 | zero. | |
8371 | Only this guarantees that the server remains source compatible to | |
8372 | future changes in common level structures. | |
8373 | </para> | |
8374 | ||
8375 | <programlisting> | |
8376 | static Bool | |
8377 | ZZZGetRec(ScrnInfoPtr pScrn) | |
8378 | { | |
8379 | if (pScrn->driverPrivate != NULL) | |
8380 | return TRUE; | |
8381 | pScrn->driverPrivate = xnfcalloc(sizeof(ZZZRec), 1); | |
8382 | /* Initialise as required */ | |
8383 | ... | |
8384 | return TRUE; | |
8385 | } | |
8386 | </programlisting> | |
8387 | ||
8388 | <para> | |
8389 | Define a macro in <filename>"zzz.h"</filename> which gets a pointer to | |
8390 | the <structname>ZZZRec</structname> when given <parameter>pScrn</parameter>: | |
8391 | ||
8392 | <programlisting> | |
8393 | #define ZZZPTR(p) ((ZZZPtr)((p)->driverPrivate)) | |
8394 | </programlisting> | |
8395 | </para> | |
8396 | ||
8397 | <para> | |
8398 | Define a function to free the above, setting it to <constant>NULL</constant> | |
8399 | once it has been freed: | |
8400 | ||
8401 | <programlisting> | |
8402 | static void | |
8403 | ZZZFreeRec(ScrnInfoPtr pScrn) | |
8404 | { | |
8405 | if (pScrn->driverPrivate == NULL) | |
8406 | return; | |
8407 | xfree(pScrn->driverPrivate); | |
8408 | pScrn->driverPrivate = NULL; | |
8409 | } | |
8410 | </programlisting> | |
8411 | </para> | |
8412 | </sect3> | |
8413 | ||
8414 | <sect3> | |
8415 | <title>Identify</title> | |
8416 | ||
8417 | <para> | |
8418 | Define the <function>Identify()</function> function. It is run before | |
8419 | the Probe, and typically prints out an identifying message, which | |
8420 | might include the chipsets it supports. This function is mandatory: | |
8421 | ||
8422 | <programlisting> | |
8423 | static void | |
8424 | ZZZIdentify(int flags) | |
8425 | { | |
8426 | xf86PrintChipsets(ZZZ_NAME, "driver for ZZZ Tech chipsets", | |
8427 | ZZZChipsets); | |
8428 | } | |
8429 | </programlisting> | |
8430 | </para> | |
8431 | </sect3> | |
8432 | ||
8433 | <sect3> | |
8434 | <title>Probe</title> | |
8435 | ||
8436 | <para> | |
8437 | Define the <function>Probe()</function> function. The purpose of this | |
8438 | is to find all instances of the hardware that the driver supports, | |
8439 | and for the ones not already claimed by another driver, claim the | |
8440 | slot, and allocate a <structname>ScrnInfoRec</structname>. This should be | |
8441 | a minimal probe, and it should under no circumstances leave the | |
8442 | state of the hardware changed. Because a device is found, don't | |
8443 | assume that it will be used. Don't do any initialisations other | |
8444 | than the required <structname>ScrnInfoRec</structname> initialisations. | |
8445 | Don't allocate any new data structures. | |
8446 | </para> | |
8447 | ||
8448 | <para> | |
8449 | This function is mandatory. | |
8450 | </para> | |
8451 | ||
8452 | <para> | |
8453 | NOTE: The <function>xf86DrvMsg()</function> functions cannot be used from | |
8454 | the Probe. | |
8455 | </para> | |
8456 | ||
8457 | <programlisting> | |
8458 | static Bool | |
8459 | ZZZProbe(DriverPtr drv, int flags) | |
8460 | { | |
8461 | Bool foundScreen = FALSE; | |
8462 | int numDevSections, numUsed; | |
8463 | GDevPtr *devSections; | |
8464 | int *usedChips; | |
8465 | int i; | |
8466 | ||
8467 | /* | |
8468 | * Find the config file Device sections that match this | |
8469 | * driver, and return if there are none. | |
8470 | */ | |
8471 | if ((numDevSections = xf86MatchDevice(ZZZ_DRIVER_NAME, | |
8472 | &devSections)) <= 0) { | |
8473 | return FALSE; | |
8474 | } | |
8475 | ||
8476 | /* | |
8477 | * Since this is a PCI card, "probing" just amounts to checking | |
8478 | * the PCI data that the server has already collected. If there | |
8479 | * is none, return. | |
8480 | * | |
8481 | * Although the config file is allowed to override things, it | |
8482 | * is reasonable to not allow it to override the detection | |
8483 | * of no PCI video cards. | |
8484 | * | |
8485 | * The provided xf86MatchPciInstances() helper takes care of | |
8486 | * the details. | |
8487 | */ | |
8488 | /* test if PCI bus present */ | |
8489 | if (xf86GetPciVideoInfo()) { | |
8490 | ||
8491 | numUsed = xf86MatchPciInstances(ZZZ_NAME, PCI_VENDOR_ZZZ, | |
8492 | ZZZChipsets, ZZZPciChipsets, devSections, | |
8493 | numDevSections, drv, &usedChips); | |
8494 | ||
8495 | for (i = 0; i < numUsed; i++) { | |
8496 | ScrnInfoPtr pScrn = NULL; | |
8497 | if ((pScrn = xf86ConfigPciEntity(pScrn, flags, usedChips[i], | |
8498 | ZZZPciChipsets, NULL, NULL, | |
8499 | NULL, NULL, NULL))) { | |
8500 | /* Allocate a ScrnInfoRec */ | |
8501 | pScrn->driverVersion = VERSION; | |
8502 | pScrn->driverName = ZZZ_DRIVER_NAME; | |
8503 | pScrn->name = ZZZ_NAME; | |
8504 | pScrn->Probe = ZZZProbe; | |
8505 | pScrn->PreInit = ZZZPreInit; | |
8506 | pScrn->ScreenInit = ZZZScreenInit; | |
8507 | pScrn->SwitchMode = ZZZSwitchMode; | |
8508 | pScrn->AdjustFrame = ZZZAdjustFrame; | |
8509 | pScrn->EnterVT = ZZZEnterVT; | |
8510 | pScrn->LeaveVT = ZZZLeaveVT; | |
8511 | pScrn->FreeScreen = ZZZFreeScreen; | |
8512 | pScrn->ValidMode = ZZZValidMode; | |
8513 | foundScreen = TRUE; | |
8514 | /* add screen to entity */ | |
8515 | } | |
8516 | } | |
8517 | xfree(usedChips); | |
8518 | } | |
8519 | ||
8520 | #ifdef HAS_ISA_DEVS | |
8521 | /* | |
8522 | * If the driver supports ISA hardware, the following block | |
8523 | * can be included too. | |
8524 | */ | |
8525 | numUsed = xf86MatchIsaInstances(ZZZ_NAME, ZZZChipsets, | |
8526 | ZZZIsaChipsets, drv, ZZZFindIsaDevice, | |
8527 | devSections, numDevSections, &usedChips); | |
8528 | for (i = 0; i < numUsed; i++) { | |
8529 | ScrnInfoPtr pScrn = NULL; | |
8530 | if ((pScrn = xf86ConfigIsaEntity(pScrn, flags, usedChips[i], | |
8531 | ZZZIsaChipsets, NULL, NULL, NULL, | |
8532 | NULL, NULL))) { | |
8533 | pScrn->driverVersion = VERSION; | |
8534 | pScrn->driverName = ZZZ_DRIVER_NAME; | |
8535 | pScrn->name = ZZZ_NAME; | |
8536 | pScrn->Probe = ZZZProbe; | |
8537 | pScrn->PreInit = ZZZPreInit; | |
8538 | pScrn->ScreenInit = ZZZScreenInit; | |
8539 | pScrn->SwitchMode = ZZZSwitchMode; | |
8540 | pScrn->AdjustFrame = ZZZAdjustFrame; | |
8541 | pScrn->EnterVT = ZZZEnterVT; | |
8542 | pScrn->LeaveVT = ZZZLeaveVT; | |
8543 | pScrn->FreeScreen = ZZZFreeScreen; | |
8544 | pScrn->ValidMode = ZZZValidMode; | |
8545 | foundScreen = TRUE; | |
8546 | } | |
8547 | } | |
8548 | xfree(usedChips); | |
8549 | #endif /* HAS_ISA_DEVS */ | |
8550 | ||
8551 | xfree(devSections); | |
8552 | return foundScreen; | |
8553 | </programlisting> | |
8554 | </sect3> | |
8555 | ||
8556 | <sect3> | |
8557 | <title>AvailableOptions</title> | |
8558 | ||
8559 | <para> | |
8560 | Define the <function>AvailableOptions()</function> function. The purpose | |
8561 | of this is to return the available driver options back to the | |
8562 | -configure option, so that an xorg.conf file can be built and the | |
8563 | user can see which options are available for them to use. | |
8564 | </para> | |
8565 | </sect3> | |
8566 | ||
8567 | <sect3> | |
8568 | <title>PreInit</title> | |
8569 | ||
8570 | <para> | |
8571 | Define the <function>PreInit()</function> function. The purpose of | |
8572 | this is to find all the information required to determine if the | |
8573 | configuration is usable, and to initialise those parts of the | |
8574 | <structname>ScrnInfoRec</structname> that can be set once at the beginning | |
8575 | of the first server generation. The information should be found in | |
8576 | the least intrusive way possible. | |
8577 | </para> | |
8578 | ||
8579 | <para> | |
8580 | This function is mandatory. | |
8581 | </para> | |
8582 | ||
8583 | <para> | |
8584 | NOTES: | |
8585 | <orderedlist> | |
8586 | <listitem><para> | |
8587 | The <function>PreInit()</function> function is only called once | |
8588 | during the life of the X server (at the start of the first | |
8589 | generation). | |
8590 | </para></listitem> | |
8591 | ||
8592 | <listitem><para> | |
8593 | Data allocated here must be of the type that persists for | |
8594 | the life of the X server. This means that data that hooks into | |
8595 | the <structname>ScrnInfoRec</structname>'s <structfield>privates</structfield> | |
8596 | field should be allocated here, but data that hooks into the | |
8597 | <structname>ScreenRec</structname>'s <structfield>devPrivates</structfield> field | |
8598 | should not be allocated here. The <structfield>driverPrivate</structfield> | |
8599 | field should also be allocated here. | |
8600 | </para></listitem> | |
8601 | ||
8602 | <listitem><para> | |
8603 | Although the <structname>ScrnInfoRec</structname> has been allocated | |
8604 | before this function is called, the <structname>ScreenRec</structname> | |
8605 | has not been allocated. That means that things requiring it | |
8606 | cannot be used in this function. | |
8607 | </para></listitem> | |
8608 | ||
8609 | <listitem><para> | |
8610 | Very little of the <structname>ScrnInfoRec</structname> has been | |
8611 | initialised when this function is called. It is important to | |
8612 | get the order of doing things right in this function. | |
8613 | </para></listitem> | |
8614 | ||
8615 | </orderedlist> | |
8616 | </para> | |
8617 | ||
8618 | <programlisting> | |
8619 | static Bool | |
8620 | ZZZPreInit(ScrnInfoPtr pScrn, int flags) | |
8621 | { | |
8622 | /* Fill in the monitor field */ | |
8623 | pScrn->monitor = pScrn->confScreen->monitor; | |
8624 | ||
8625 | /* | |
8626 | * If using the vgahw module, it will typically be loaded | |
8627 | * here by calling xf86LoadSubModule(pScrn, "vgahw"); | |
8628 | */ | |
8629 | ||
8630 | /* | |
8631 | * Set the depth/bpp. Use the globally preferred depth/bpp. If the | |
8632 | * driver has special default depth/bpp requirements, the defaults should | |
8633 | * be specified here explicitly. | |
8634 | * We support both 24bpp and 32bpp framebuffer layouts. | |
8635 | * This sets pScrn->display also. | |
8636 | */ | |
8637 | if (!xf86SetDepthBpp(pScrn, 0, 0, 0, | |
8638 | Support24bppFb | Support32bppFb)) { | |
8639 | return FALSE; | |
8640 | } else { | |
8641 | if (depth/bpp isn't one we support) { | |
8642 | print error message; | |
8643 | return FALSE; | |
8644 | } | |
8645 | } | |
8646 | /* Print out the depth/bpp that was set */ | |
8647 | xf86PrintDepthBpp(pScrn); | |
8648 | ||
8649 | /* Set bits per RGB for 8bpp */ | |
8650 | if (pScrn->depth <= 8) { | |
8651 | /* Take into account a dac_6_bit option here */ | |
8652 | pScrn->rgbBits = 6 or 8; | |
8653 | } | |
8654 | ||
8655 | /* | |
8656 | * xf86SetWeight() and xf86SetDefaultVisual() must be called | |
8657 | * after pScrn->display is initialised. | |
8658 | */ | |
8659 | ||
8660 | /* Set weight/mask/offset for depth > 8 */ | |
8661 | if (pScrn->depth > 8) { | |
8662 | if (!xf86SetWeight(pScrn, defaultWeight, defaultMask)) { | |
8663 | return FALSE; | |
8664 | } else { | |
8665 | if (weight isn't one we support) { | |
8666 | print error message; | |
8667 | return FALSE; | |
8668 | } | |
8669 | } | |
8670 | } | |
8671 | ||
8672 | /* Set the default visual. */ | |
8673 | if (!xf86SetDefaultVisual(pScrn, -1)) { | |
8674 | return FALSE; | |
8675 | } else { | |
8676 | if (visual isn't one we support) { | |
8677 | print error message; | |
8678 | return FALSE; | |
8679 | } | |
8680 | } | |
8681 | ||
8682 | /* If the driver supports gamma correction, set the gamma. */ | |
8683 | if (!xf86SetGamma(pScrn, default_gamma)) { | |
8684 | return FALSE; | |
8685 | } | |
8686 | ||
8687 | /* This driver uses a programmable clock */ | |
8688 | pScrn->progClock = TRUE; | |
8689 | ||
8690 | /* Allocate the ZZZRec driverPrivate */ | |
8691 | if (!ZZZGetRec(pScrn)) { | |
8692 | return FALSE; | |
8693 | } | |
8694 | ||
8695 | pZzz = ZZZPTR(pScrn); | |
8696 | ||
8697 | /* Collect all of the option flags (fill in pScrn->options) */ | |
8698 | xf86CollectOptions(pScrn, NULL); | |
8699 | ||
8700 | /* | |
8701 | * Process the options based on the information in ZZZOptions. | |
8702 | * The results are written to pZzz->Options. If all of the options | |
8703 | * processing is done within this function a local variable "options" | |
8704 | * can be used instead of pZzz->Options. | |
8705 | */ | |
8706 | if (!(pZzz->Options = xalloc(sizeof(ZZZOptions)))) | |
8707 | return FALSE; | |
8708 | (void)memcpy(pZzz->Options, ZZZOptions, sizeof(ZZZOptions)); | |
8709 | xf86ProcessOptions(pScrn->scrnIndex, pScrn->options, pZzz->Options); | |
8710 | ||
8711 | /* | |
8712 | * Set various fields of ScrnInfoRec and/or ZZZRec based on | |
8713 | * the options found. | |
8714 | */ | |
8715 | from = X_DEFAULT; | |
8716 | pZzz->hwCursor = FALSE; | |
8717 | if (xf86IsOptionSet(pZzz->Options, OPTION_HW_CURSOR)) { | |
8718 | from = X_CONFIG; | |
8719 | pZzz->hwCursor = TRUE; | |
8720 | } | |
8721 | xf86DrvMsg(pScrn->scrnIndex, from, "Using %s cursor\n", | |
8722 | pZzz->hwCursor ? "HW" : "SW"); | |
8723 | if (xf86IsOptionSet(pZzz->Options, OPTION_NOACCEL)) { | |
8724 | pZzz->noAccel = TRUE; | |
8725 | xf86DrvMsg(pScrn->scrnIndex, X_CONFIG, | |
8726 | "Acceleration disabled\n"); | |
8727 | } else { | |
8728 | pZzz->noAccel = FALSE; | |
8729 | } | |
8730 | if (xf86IsOptionSet(pZzz->Options, OPTION_PCI_RETRY)) { | |
8731 | pZzz->UsePCIRetry = TRUE; | |
8732 | xf86DrvMsg(pScrn->scrnIndex, X_CONFIG, "PCI retry enabled\n"); | |
8733 | } | |
8734 | pZzz->fooHack = 0; | |
8735 | if (xf86GetOptValInteger(pZzz->Options, OPTION_FOO_HACK, | |
8736 | &pZzz->fooHack)) { | |
8737 | xf86DrvMsg(pScrn->scrnIndex, X_CONFIG, "Foo Hack set to %d\n", | |
8738 | pZzz->fooHack); | |
8739 | } | |
8740 | ||
8741 | /* | |
8742 | * Find the PCI slot(s) that this screen claimed in the probe. | |
8743 | * In this case, exactly one is expected, so complain otherwise. | |
8744 | * Note in this case we're not interested in the card types so | |
8745 | * that parameter is set to NULL. | |
8746 | */ | |
8747 | if ((i = xf86GetPciInfoForScreen(pScrn->scrnIndex, &pciList, NULL)) | |
8748 | != 1) { | |
8749 | print error message; | |
8750 | ZZZFreeRec(pScrn); | |
8751 | if (i > 0) | |
8752 | xfree(pciList); | |
8753 | return FALSE; | |
8754 | } | |
8755 | /* Note that pciList should be freed below when no longer needed */ | |
8756 | ||
8757 | /* | |
8758 | * Determine the chipset, allowing config file chipset and | |
8759 | * chipid values to override the probed information. The config | |
8760 | * chipset value has precedence over its chipid value if both | |
8761 | * are present. | |
8762 | * | |
8763 | * It isn't necessary to fill in pScrn->chipset if the driver | |
8764 | * keeps track of the chipset in its ZZZRec. | |
8765 | */ | |
8766 | ||
8767 | ... | |
8768 | ||
8769 | /* | |
8770 | * Determine video memory, fb base address, I/O addresses, etc, | |
8771 | * allowing the config file to override probed values. | |
8772 | * | |
8773 | * Set the appropriate pScrn fields (videoRam is probably the | |
8774 | * most important one that other code might require), and | |
8775 | * print out the settings. | |
8776 | */ | |
8777 | ||
8778 | ... | |
8779 | ||
8780 | /* Initialise a clockRanges list. */ | |
8781 | ||
8782 | ... | |
8783 | ||
8784 | /* Set any other chipset specific things in the ZZZRec */ | |
8785 | ||
8786 | ... | |
8787 | ||
8788 | /* Select valid modes from those available */ | |
8789 | ||
8790 | i = xf86ValidateModes(pScrn, pScrn->monitor->Modes, | |
8791 | pScrn->display->modes, clockRanges, | |
8792 | NULL, minPitch, maxPitch, rounding, | |
8793 | minHeight, maxHeight, | |
8794 | pScrn->display->virtualX, | |
8795 | pScrn->display->virtualY, | |
8796 | pScrn->videoRam * 1024, | |
8797 | LOOKUP_BEST_REFRESH); | |
8798 | if (i == -1) { | |
8799 | ZZZFreeRec(pScrn); | |
8800 | return FALSE; | |
8801 | } | |
8802 | ||
8803 | /* Prune the modes marked as invalid */ | |
8804 | ||
8805 | xf86PruneDriverModes(pScrn); | |
8806 | ||
8807 | /* If no valid modes, return */ | |
8808 | ||
8809 | if (i == 0 || pScrn->modes == NULL) { | |
8810 | print error message; | |
8811 | ZZZFreeRec(pScrn); | |
8812 | return FALSE; | |
8813 | } | |
8814 | ||
8815 | /* | |
8816 | * Initialise the CRTC fields for the modes. This driver expects | |
8817 | * vertical values to be halved for interlaced modes. | |
8818 | */ | |
8819 | xf86SetCrtcForModes(pScrn, INTERLACE_HALVE_V); | |
8820 | ||
8821 | /* Set the current mode to the first in the list. */ | |
8822 | pScrn->currentMode = pScrn->modes; | |
8823 | ||
8824 | /* Print the list of modes being used. */ | |
8825 | xf86PrintModes(pScrn); | |
8826 | ||
8827 | /* Set the DPI */ | |
8828 | xf86SetDpi(pScrn, 0, 0); | |
8829 | ||
8830 | /* Load bpp-specific modules */ | |
8831 | switch (pScrn->bitsPerPixel) { | |
8832 | case 1: | |
8833 | mod = "xf1bpp"; | |
8834 | break; | |
8835 | case 4: | |
8836 | mod = "xf4bpp"; | |
8837 | break; | |
8838 | case 8: | |
8839 | mod = "cfb"; | |
8840 | break; | |
8841 | case 16: | |
8842 | mod = "cfb16"; | |
8843 | break; | |
8844 | case 24: | |
8845 | mod = "cfb24"; | |
8846 | break; | |
8847 | case 32: | |
8848 | mod = "cfb32"; | |
8849 | break; | |
8850 | } | |
8851 | if (mod && !xf86LoadSubModule(pScrn, mod)) | |
8852 | ZZZFreeRec(pScrn); | |
8853 | return FALSE; | |
8854 | ||
8855 | ||
8856 | /* Done */ | |
8857 | return TRUE; | |
8858 | } | |
8859 | </programlisting> | |
8860 | </sect3> | |
8861 | ||
8862 | <sect3> | |
8863 | <title>MapMem, UnmapMem</title> | |
8864 | ||
8865 | <para> | |
8866 | Define functions to map and unmap the video memory and any other | |
8867 | memory apertures required. These functions are not mandatory, but | |
8868 | it is often useful to have such functions. | |
8869 | </para> | |
8870 | ||
8871 | <programlisting> | |
8872 | static Bool | |
8873 | ZZZMapMem(ScrnInfoPtr pScrn) | |
8874 | { | |
8875 | /* Call xf86MapPciMem() to map each PCI memory area */ | |
8876 | ... | |
8877 | return TRUE or FALSE; | |
8878 | } | |
8879 | ||
8880 | static Bool | |
8881 | ZZZUnmapMem(ScrnInfoPtr pScrn) | |
8882 | { | |
8883 | /* Call xf86UnMapVidMem() to unmap each memory area */ | |
8884 | ... | |
8885 | return TRUE or FALSE; | |
8886 | } | |
8887 | </programlisting> | |
8888 | </sect3> | |
8889 | ||
8890 | <sect3> | |
8891 | <title>Save, Restore</title> | |
8892 | ||
8893 | <para> | |
8894 | Define functions to save and restore the original video state. These | |
8895 | functions are not mandatory, but are often useful. | |
8896 | </para> | |
8897 | ||
8898 | <programlisting> | |
8899 | static void | |
8900 | ZZZSave(ScrnInfoPtr pScrn) | |
8901 | { | |
8902 | /* | |
8903 | * Save state into per-screen data structures. | |
8904 | * If using the vgahw module, vgaHWSave will typically be | |
8905 | * called here. | |
8906 | */ | |
8907 | ... | |
8908 | } | |
8909 | ||
8910 | static void | |
8911 | ZZZRestore(ScrnInfoPtr pScrn) | |
8912 | { | |
8913 | /* | |
8914 | * Restore state from per-screen data structures. | |
8915 | * If using the vgahw module, vgaHWRestore will typically be | |
8916 | * called here. | |
8917 | */ | |
8918 | ... | |
8919 | } | |
8920 | </programlisting> | |
8921 | </sect3> | |
8922 | ||
8923 | <sect3> | |
8924 | <title>ModeInit</title> | |
8925 | ||
8926 | <para> | |
8927 | Define a function to initialise a new video mode. This function isn't | |
8928 | mandatory, but is often useful. | |
8929 | </para> | |
8930 | ||
8931 | <programlisting> | |
8932 | static Bool | |
8933 | ZZZModeInit(ScrnInfoPtr pScrn, DisplayModePtr mode) | |
8934 | { | |
8935 | /* | |
8936 | * Program a video mode. If using the vgahw module, | |
8937 | * vgaHWInit and vgaRestore will typically be called here. | |
8938 | * Once up to the point where there can't be a failure | |
8939 | * set pScrn->vtSema to TRUE. | |
8940 | */ | |
8941 | ... | |
8942 | } | |
8943 | </programlisting> | |
8944 | </sect3> | |
8945 | ||
8946 | <sect3> | |
8947 | <title>ScreenInit</title> | |
8948 | ||
8949 | <para> | |
8950 | Define the <function>ScreenInit()</function> function. This is called | |
8951 | at the start of each server generation, and should fill in as much | |
8952 | of the <structname>ScreenRec</structname> as possible as well as any other | |
8953 | data that is initialised once per generation. It should initialise | |
8954 | the framebuffer layers it is using, and initialise the initial video | |
8955 | mode. | |
8956 | </para> | |
8957 | ||
8958 | <para> | |
8959 | This function is mandatory. | |
8960 | </para> | |
8961 | ||
8962 | <para> | |
8963 | NOTE: The <structname>ScreenRec</structname> (<parameter>pScreen</parameter>) is | |
8964 | passed to this driver, but it and the | |
8965 | <varname>ScrnInfoRecs</varname> are not yet hooked into each | |
8966 | other. This means that in this function, and functions it | |
8967 | calls, one cannot be found from the other. | |
8968 | </para> | |
8969 | ||
8970 | <programlisting> | |
8971 | static Bool | |
8972 | ZZZScreenInit(ScreenPtr pScreen, int argc, char **argv) | |
8973 | { | |
8974 | /* Get the ScrnInfoRec */ | |
8975 | pScrn = xf86ScreenToScrn(pScreen); | |
8976 | ||
8977 | /* | |
8978 | * If using the vgahw module, its data structures and related | |
8979 | * things are typically initialised/mapped here. | |
8980 | */ | |
8981 | ||
8982 | /* Save the current video state */ | |
8983 | ZZZSave(pScrn); | |
8984 | ||
8985 | /* Initialise the first mode */ | |
8986 | ZZZModeInit(pScrn, pScrn->currentMode); | |
8987 | ||
8988 | /* Set the viewport if supported */ | |
8989 | ||
8990 | ZZZAdjustFrame(pScrn, pScrn->frameX0, pScrn->frameY0); | |
8991 | ||
8992 | /* | |
8993 | * Setup the screen's visuals, and initialise the framebuffer | |
8994 | * code. | |
8995 | */ | |
8996 | ||
8997 | /* Reset the visual list */ | |
8998 | miClearVisualTypes(); | |
8999 | ||
9000 | /* | |
9001 | * Setup the visuals supported. This driver only supports | |
9002 | * TrueColor for bpp > 8, so the default set of visuals isn't | |
9003 | * acceptable. To deal with this, call miSetVisualTypes with | |
9004 | * the appropriate visual mask. | |
9005 | */ | |
9006 | ||
9007 | if (pScrn->bitsPerPixel > 8) { | |
9008 | if (!miSetVisualTypes(pScrn->depth, TrueColorMask, | |
9009 | pScrn->rgbBits, pScrn->defaultVisual)) | |
9010 | return FALSE; | |
9011 | } else { | |
9012 | if (!miSetVisualTypes(pScrn->depth, | |
9013 | miGetDefaultVisualMask(pScrn->depth), | |
9014 | pScrn->rgbBits, pScrn->defaultVisual)) | |
9015 | return FALSE; | |
9016 | } | |
9017 | ||
9018 | /* | |
9019 | * Initialise the framebuffer. | |
9020 | */ | |
9021 | ||
9022 | switch (pScrn->bitsPerPixel) { | |
9023 | case 1: | |
9024 | ret = xf1bppScreenInit(pScreen, FbBase, | |
9025 | pScrn->virtualX, pScrn->virtualY, | |
9026 | pScrn->xDpi, pScrn->yDpi, | |
9027 | pScrn->displayWidth); | |
9028 | break; | |
9029 | case 4: | |
9030 | ret = xf4bppScreenInit(pScreen, FbBase, | |
9031 | pScrn->virtualX, pScrn->virtualY, | |
9032 | pScrn->xDpi, pScrn->yDpi, | |
9033 | pScrn->displayWidth); | |
9034 | break; | |
9035 | case 8: | |
9036 | ret = cfbScreenInit(pScreen, FbBase, | |
9037 | pScrn->virtualX, pScrn->virtualY, | |
9038 | pScrn->xDpi, pScrn->yDpi, | |
9039 | pScrn->displayWidth); | |
9040 | break; | |
9041 | case 16: | |
9042 | ret = cfb16ScreenInit(pScreen, FbBase, | |
9043 | pScrn->virtualX, pScrn->virtualY, | |
9044 | pScrn->xDpi, pScrn->yDpi, | |
9045 | pScrn->displayWidth); | |
9046 | break; | |
9047 | case 24: | |
9048 | ret = cfb24ScreenInit(pScreen, FbBase, | |
9049 | pScrn->virtualX, pScrn->virtualY, | |
9050 | pScrn->xDpi, pScrn->yDpi, | |
9051 | pScrn->displayWidth); | |
9052 | break; | |
9053 | case 32: | |
9054 | ret = cfb32ScreenInit(pScreen, FbBase, | |
9055 | pScrn->virtualX, pScrn->virtualY, | |
9056 | pScrn->xDpi, pScrn->yDpi, | |
9057 | pScrn->displayWidth); | |
9058 | break; | |
9059 | default: | |
9060 | print a message about an internal error; | |
9061 | ret = FALSE; | |
9062 | break; | |
9063 | } | |
9064 | ||
9065 | if (!ret) | |
9066 | return FALSE; | |
9067 | ||
9068 | /* Override the default mask/offset settings */ | |
9069 | if (pScrn->bitsPerPixel > 8) { | |
9070 | for (i = 0, visual = pScreen->visuals; | |
9071 | i < pScreen->numVisuals; i++, visual++) { | |
9072 | if ((visual->class | DynamicClass) == DirectColor) { | |
9073 | visual->offsetRed = pScrn->offset.red; | |
9074 | visual->offsetGreen = pScrn->offset.green; | |
9075 | visual->offsetBlue = pScrn->offset.blue; | |
9076 | visual->redMask = pScrn->mask.red; | |
9077 | visual->greenMask = pScrn->mask.green; | |
9078 | visual->blueMask = pScrn->mask.blue; | |
9079 | } | |
9080 | } | |
9081 | } | |
9082 | ||
9083 | /* | |
9084 | * If banking is needed, initialise an miBankInfoRec (defined in | |
9085 | * "mibank.h"), and call miInitializeBanking(). | |
9086 | */ | |
9087 | if (!miInitializeBanking(pScreen, pScrn->virtualX, pScrn->virtualY, | |
9088 | pScrn->displayWidth, pBankInfo)) | |
9089 | return FALSE; | |
9090 | ||
9091 | /* | |
9092 | * Set initial black & white colourmap indices. | |
9093 | */ | |
9094 | xf86SetBlackWhitePixels(pScreen); | |
9095 | ||
9096 | /* | |
9097 | * Install colourmap functions. If using the vgahw module, | |
9098 | * vgaHandleColormaps would usually be called here. | |
9099 | */ | |
9100 | ||
9101 | ... | |
9102 | ||
9103 | /* | |
9104 | * Initialise cursor functions. This example is for the mi | |
9105 | * software cursor. | |
9106 | */ | |
9107 | miDCInitialize(pScreen, xf86GetPointerScreenFuncs()); | |
9108 | ||
9109 | /* Initialise the default colourmap */ | |
9110 | switch (pScrn->depth) { | |
9111 | case 1: | |
9112 | if (!xf1bppCreateDefColormap(pScreen)) | |
9113 | return FALSE; | |
9114 | break; | |
9115 | case 4: | |
9116 | if (!xf4bppCreateDefColormap(pScreen)) | |
9117 | return FALSE; | |
9118 | break; | |
9119 | default: | |
9120 | if (!cfbCreateDefColormap(pScreen)) | |
9121 | return FALSE; | |
9122 | break; | |
9123 | } | |
9124 | ||
9125 | /* | |
9126 | * Wrap the CloseScreen vector and set SaveScreen. | |
9127 | */ | |
9128 | ZZZPTR(pScrn)->CloseScreen = pScreen->CloseScreen; | |
9129 | pScreen->CloseScreen = ZZZCloseScreen; | |
9130 | pScreen->SaveScreen = ZZZSaveScreen; | |
9131 | ||
9132 | /* Report any unused options (only for the first generation) */ | |
9133 | if (serverGeneration == 1) { | |
9134 | xf86ShowUnusedOptions(pScrn->scrnIndex, pScrn->options); | |
9135 | } | |
9136 | ||
9137 | /* Done */ | |
9138 | return TRUE; | |
9139 | } | |
9140 | </programlisting> | |
9141 | </sect3> | |
9142 | ||
9143 | <sect3> | |
9144 | <title>SwitchMode</title> | |
9145 | ||
9146 | <para> | |
9147 | Define the <function>SwitchMode()</function> function if mode switching | |
9148 | is supported by the driver. | |
9149 | </para> | |
9150 | ||
9151 | <programlisting> | |
9152 | static Bool | |
9153 | ZZZSwitchMode(ScrnInfoPtr pScrn, DisplayModePtr mode) | |
9154 | { | |
9155 | return ZZZModeInit(pScrn, mode); | |
9156 | } | |
9157 | </programlisting> | |
9158 | </sect3> | |
9159 | ||
9160 | <sect3> | |
9161 | <title>AdjustFrame</title> | |
9162 | ||
9163 | <para> | |
9164 | Define the <function>AdjustFrame()</function> function if the driver | |
9165 | supports this. | |
9166 | </para> | |
9167 | ||
9168 | <programlisting> | |
9169 | static void | |
9170 | ZZZAdjustFrame(ScrnInfoPtr pScrn, int x, int y) | |
9171 | { | |
9172 | /* Adjust the viewport */ | |
9173 | } | |
9174 | </programlisting> | |
9175 | </sect3> | |
9176 | ||
9177 | <sect3> | |
9178 | <title>EnterVT, LeaveVT</title> | |
9179 | ||
9180 | <para> | |
9181 | Define the <function>EnterVT()</function> and <function>LeaveVT()</function> | |
9182 | functions. | |
9183 | </para> | |
9184 | ||
9185 | <para> | |
9186 | These functions are mandatory. | |
9187 | </para> | |
9188 | ||
9189 | <programlisting> | |
9190 | static Bool | |
9191 | ZZZEnterVT(ScrnInfoPtr pScrn) | |
9192 | { | |
9193 | return ZZZModeInit(pScrn, pScrn->currentMode); | |
9194 | } | |
9195 | ||
9196 | static void | |
9197 | ZZZLeaveVT(ScrnInfoPtr pScrn) | |
9198 | { | |
9199 | ZZZRestore(pScrn); | |
9200 | } | |
9201 | </programlisting> | |
9202 | </sect3> | |
9203 | ||
9204 | <sect3> | |
9205 | <title>CloseScreen</title> | |
9206 | ||
9207 | <para> | |
9208 | Define the <function>CloseScreen()</function> function: | |
9209 | </para> | |
9210 | ||
9211 | <para> | |
9212 | This function is mandatory. Note that it unwraps the previously | |
9213 | wrapped <structfield>pScreen->CloseScreen</structfield>, and finishes by | |
9214 | calling it. | |
9215 | </para> | |
9216 | ||
9217 | <programlisting> | |
9218 | static Bool | |
9219 | ZZZCloseScreen(ScreenPtr pScreen) | |
9220 | { | |
9221 | ScrnInfoPtr pScrn = xf86ScreenToScrn(pScreen); | |
9222 | if (pScrn->vtSema) { | |
9223 | ZZZRestore(pScrn); | |
9224 | ZZZUnmapMem(pScrn); | |
9225 | } | |
9226 | pScrn->vtSema = FALSE; | |
9227 | pScreen->CloseScreen = ZZZPTR(pScrn)->CloseScreen; | |
9228 | return (*pScreen->CloseScreen)(pScreen); | |
9229 | } | |
9230 | </programlisting> | |
9231 | </sect3> | |
9232 | ||
9233 | <sect3> | |
9234 | <title>SaveScreen</title> | |
9235 | ||
9236 | <para> | |
9237 | Define the <function>SaveScreen()</function> function (the screen | |
9238 | blanking function). When using the vgahw module, this will typically | |
9239 | be: | |
9240 | ||
9241 | <programlisting> | |
9242 | static Bool | |
9243 | ZZZSaveScreen(ScreenPtr pScreen, int mode) | |
9244 | { | |
9245 | return vgaHWSaveScreen(pScreen, mode); | |
9246 | } | |
9247 | </programlisting> | |
9248 | </para> | |
9249 | ||
9250 | <para> | |
9251 | This function is mandatory. Before modifying any hardware register | |
9252 | directly this function needs to make sure that the Xserver is active | |
9253 | by checking if <parameter>pScrn</parameter> is non-NULL and for | |
9254 | <literal remap="tt">pScrn->vtSema == TRUE</literal>. | |
9255 | </para> | |
9256 | </sect3> | |
9257 | ||
9258 | <sect3> | |
9259 | <title>FreeScreen</title> | |
9260 | ||
9261 | <para> | |
9262 | Define the <function>FreeScreen()</function> function. This function | |
9263 | is optional. It should be defined if the <structname>ScrnInfoRec</structname> | |
9264 | <structfield>driverPrivate</structfield> field is used so that it can be freed | |
9265 | when a screen is deleted by the common layer for reasons possibly | |
9266 | beyond the driver's control. This function is not used in during | |
9267 | normal (error free) operation. The per-generation data is freed by | |
9268 | the <function>CloseScreen()</function> function. | |
9269 | </para> | |
9270 | ||
9271 | <programlisting> | |
9272 | static void | |
9273 | ZZZFreeScreen(ScrnInfoPtr pScrn) | |
9274 | { | |
9275 | /* | |
9276 | * If the vgahw module is used vgaHWFreeHWRec() would be called | |
9277 | * here. | |
9278 | */ | |
9279 | ZZZFreeRec(pScrn); | |
9280 | } | |
9281 | ||
9282 | </programlisting> | |
9283 | ||
9284 | </sect3> | |
9285 | ||
9286 | </sect2> | |
9287 | ||
9288 | </sect1> | |
9289 | ||
9290 | </article> |