1
XFree86 X server ``New Design'' (DRAFT)
3
The XFree86 Project, Inc
5
Last modified 2003 January 22
7
NOTE: This is a DRAFT document, and the interfaces described here are subject
8
to change without notice.
12
The broad design principles are:
16
o We cannot rewrite the complete server
18
o We don't want to re-invent the wheel
22
o As many things as possible should go into modules
24
o The basic loader binary should be minimal
26
o A clean design with well defined layering is important
28
o DDX specific global variables are a nono
30
o The structure should be flexible enough to allow future extensions
32
o The structure should minimize duplication of common code
34
o keep important features in mind
36
o multiple screens, including multiple instances of drivers
38
o mixing different color depths and visuals on different and ideally
39
even on the same screen
41
o better control of the PCI device used
43
o better config file parser
45
o get rid of all VGA compatibility assumptions
47
Unless we find major deficiencies in the DIX layer, we should avoid making
50
2. The XF86Config File
52
The XF86Config file format is similar to the old format, with the following
57
The Device sections are similar to what they used to be, and describe hard-
58
ware-specific information for a single video card. Device Some new keywords
62
Specifies the name of the driver to be used for the card. This
66
Specifies uniquely the location of the card on the bus. The pur-
67
pose is to identify particular cards in a multi-headed configura-
68
tion. The format of the argument is intentionally vague, and may
69
be architecture dependent. For a PCI bus, it is something like
72
A Device section is considered ``active'' if there is a reference to it in an
73
active Screen section.
77
The Screen sections are similar to what they used to be. They no longer have
78
a Driver keyword, but an Identifier keyword is added. (The Driver keyword
79
may be accepted in place of the Identifier keyword for compatibility pur-
80
poses.) The identifier can be used to identify which screen is to be active
81
when multiple Screen sections are present. It is possible to specify the
82
active screen from the command line. A default is chosen in the absence of
83
one being specified. A Screen section is considered ``active'' if there is a
84
reference to it either from the command line, or from an active ServerLayout
87
2.3 InputDevice section
89
The InputDevice section is a new section that describes configuration infor-
90
mation for input devices. It replaces the old Keyboard, Pointer and XInput
91
sections. Like the Device section, it has two mandatory keywords: Identifier
92
and Driver. For compatibility purposes the old Keyboard and Pointer sections
93
are converted by the parser into InputDevice sections as follows:
96
Identifier "Implicit Core Keyboard"
101
Identifier "Implicit Core Pointer"
105
An InputDevice section is considered active if there is a reference to it in
106
an active ServerLayout section. An InputDevice section may also be refer-
107
enced implicitly if there is no ServerLayout section, if the -screen command
108
line options is used, or if the ServerLayout section doesn't reference any
109
InputDevice sections. In this case, the first sections with drivers "key-
110
board" and "mouse" are used as the core keyboard and pointer respectively.
112
2.4 ServerLayout section
114
The ServerLayout section is a new section that is used to identify which
115
Screen sections are to be used in a multi-headed configuration, and the rela-
116
tive layout of those screens. It also identifies which InputDevice sections
117
are to be used. Each ServerLayout section has an identifier, a list of
118
Screen section identifiers, and a list of InputDevice section identifiers.
119
ServerFlags options may also be included in a ServerLayout section, making it
120
possible to override the global values in the ServerFlags section.
122
A ServerLayout section can be made active by being referenced on the command
123
line. In the absence of this, a default will be chosen (the first one
124
found). The screen names may optionally be followed by a number specifying
125
the preferred screen number, and optionally by information specifying the
126
physical positioning of the screen, either in absolute terms or relative to
127
another screen (or screens). When no screen number is specified, they are
128
numbered according to the order in which they are listed. The old (now obso-
129
lete) method of providing the positioning information is to give the names of
130
the four adjacent screens. The order of these is top, bottom, left, right.
131
Here is an example of a ServerLayout section for two screens using the old
132
method, with the second located to the right of the first:
134
Section "ServerLayout"
135
Identifier "Main Layout"
136
Screen 0 "Screen 1" "" "" "" "Screen 2"
141
The preferred way of specifying the layout is to explicitly specify the
142
screen's location in absolute terms or relative to another screen.
144
In the absolute case, the upper left corner's coordinates are given after the
145
Absolute keyword. If the coordinates are omitted, a value of (0,0) is
146
assumed. An example of absolute positioning follows:
148
Section "ServerLayout"
149
Identifier "Main Layout"
150
Screen 0 "Screen 1" Absolute 0 0
151
Screen 1 "Screen 2" Absolute 1024 0
152
Screen "Screen 3" Absolute 2048 0
155
In the relative case, the position is specified by either using one of the
156
following keywords followed by the name of the reference screen:
168
When the Relative keyword is used, the reference screen name is followed by
169
the coordinates of the new screen's origin relative to reference screen. The
170
following example shows how to use some of the relative positioning options.
172
Section "ServerLayout"
173
Identifier "Main Layout"
175
Screen 1 "Screen 2" RightOf "Screen 1"
176
Screen "Screen 3" Relative "Screen 1" 2048 0
181
Options are used more extensively. They may appear in most sections now.
182
Options related to drivers can be present in the Screen, Device and Monitor
183
sections and the Display subsections. The order of precedence is Display,
184
Screen, Monitor, Device. Options have been extended to allow an optional
185
value to be specified in addition to the option name. For more details about
186
options, see the Options (section 10., page 1) section for details.
190
The driver interface consists of a minimal set of entry points that are
191
required based on the external events that the driver must react to. No non-
192
essential structure is imposed on the way they are used beyond that. This is
193
a significant difference compared with the old design.
195
The entry points for drawing operations are already taken care of by the
196
framebuffer code (including, XAA). Extensions and enhancements to frame-
197
buffer code are outside the scope of this document.
199
This approach to the driver interface provides good flexibility, but does
200
increase the complexity of drivers. To help address this, the XFree86 common
201
layer provides a set of ``helper'' functions to take care of things that most
202
drivers need. These helpers help minimise the amount of code duplication
203
between drivers. The use of helper functions by drivers is however optional,
204
though encouraged. The basic philosophy behind the helper functions is that
205
they should be useful to many drivers, that they should balance this against
206
the complexity of their interface. It is inevitable that some drivers may
207
find some helpers unsuitable and need to provide their own code.
209
Events that a driver needs to react to are:
212
An initialisation function is called from the DIX layer for each
213
screen at the start of each server generation.
216
The server takes control of the console.
219
The server releases control of the console.
225
Change the origin of the physical view port.
227
ScreenSaver state change
228
Screen saver activation/deactivation.
231
A close screen function is called from the DIX layer for each
232
screen at the end of each server generation.
234
In addition to these events, the following functions are required by the
235
XFree86 common layer:
238
Print a driver identifying message.
241
This is how a driver identifies if there is any hardware present
242
that it knows how to drive.
245
Process information from the XF86Config file, determine the full
246
characteristics of the hardware, and determine if a valid config-
249
The VidMode extension also requires:
252
Identify if a new mode is usable with the current configuration.
253
The PreInit function (and/or helpers it calls) may also make use
254
of the ValidMode function or something similar.
256
Other extensions may require other entry points. The drivers will inform the
257
common layer of these in such cases.
259
4. Resource Access Control Introduction
261
Graphics devices are accessed through ranges in I/O or memory space. While
262
most modern graphics devices allow relocation of such ranges many of them
263
still require the use of well established interfaces such as VGA memory and
264
IO ranges or 8514/A IO ranges. With modern buses (like PCI) it is possible
265
for multiple video devices to share access to these resources. The RAC
266
(Resource Access Control) subsystem provides a mechanism for this.
268
4.1 Terms and Definitions
272
``Bus'' is ambiguous as it is used for different things: it may refer to
273
physical incompatible extension connectors in a computer system. The RAC
274
system knows two such systems: The ISA bus and the PCI bus. (On the software
275
level EISA, MCA and VL buses are currently treated like ISA buses). ``Bus''
276
may also refer to logically different entities on a single bus system which
277
are connected via bridges. A PCI system may have several distinct PCI buses
278
connecting each other by PCI-PCI bridges or to the host CPU by HOST-PCI
281
Systems that host more than one bus system link these together using bridges.
282
Bridges are a concern to RAC as they might block or pass specific resources.
283
PCI-PCI bridges may be set up to pass VGA resources to the secondary bus.
284
PCI-ISA buses pass any resources not decoded on the primary PCI bus to the
285
ISA bus. This way VGA resources (although exclusive on the ISA bus) can be
286
shared by ISA and PCI cards. Currently HOST-PCI bridges are not yet handled
287
by RAC as they require specific drivers.
291
The smallest independently addressable unit on a system bus is referred to as
292
an entity. So far we know ISA and PCI entities. PCI entities can be located
293
on the PCI bus by an unique ID consisting of the bus, card and function num-
298
``Resource'' refers to a range of memory or I/O addresses an entity can
301
If a device is capable of disabling this decoding the resource is called
302
sharable. For PCI devices a generic method is provided to control resource
303
decoding. Other devices will have to provide a device specific function to
306
If the entity is capable of decoding this range at a different location this
307
resource is considered relocatable.
309
Resources which start at a specific address and occupy a single continuous
310
range are called block resources.
312
Alternatively resource addresses can be decoded in a way that they satisfy
315
address & mask == base
321
Resources addressed in such a way are called sparse resources.
325
The resource access control system knows two server states: the SETUP and the
326
OPERATING state. The SETUP state is entered whenever a mode change takes
327
place or the server exits or does VT switching. During this state all entity
328
resources are under resource access control. During OPERATING state only
329
those entities are controlled which actually have shared resources that con-
332
5. Control Flow in the Server and Mandatory Driver Functions
334
At the start of each server generation, main() (dix/main.c) calls the DDX
335
function InitOutput(). This is the first place that the DDX gets control.
336
InitOutput() is expected to fill in the global screenInfo struct, and one
337
screenInfo.screen[] entry for each screen present. Here is what InitOutput()
340
5.1 Parse the XF86Config file
342
This is done at the start of the first server generation only.
344
The XF86Config file is read in full, and the resulting information stored in
345
data structures. None of the parsed information is processed at this point.
346
The parser data structures are opaque to the video drivers and to most of the
349
The entire file is parsed first to remove any section ordering requirements.
351
5.2 Initial processing of parsed information and command line options
353
This is done at the start of the first server generation only.
355
The initial processing is to determine paths like the ModulePath, etc, and to
356
determine which ServerLayout, Screen and Device sections are active.
358
5.3 Enable port I/O access
360
Port I/O access is controlled from the XFree86 common layer, and is ``all or
361
nothing''. It is enabled prior to calling driver probes, at the start of
362
subsequent server generations, and when VT switching back to the Xserver. It
363
is disabled at the end of server generations, and when VT switching away from
366
The implementation details of this may vary on different platforms.
368
5.4 General bus probe
370
This is done at the start of the first server generation only.
372
In the case of ix86 machines, this will be a general PCI probe. The full
373
information obtained here will be available to the drivers. This information
374
persists for the life of the Xserver. In the PCI case, the PCI information
375
for all video cards found is available by calling xf86GetPciVideoInfo().
377
pciVideoPtr *xf86GetPciVideoInfo(void)
379
returns a pointer to a list of pointers to pciVideoRec
380
entries, of which there is one for each detected PCI
381
video card. The list is terminated with a NULL pointer.
382
If no PCI video cards were detected, the return value is
385
After the bus probe, the resource broker is initialised.
387
5.5 Load initial set of modules
389
This is done at the start of the first server generation only.
391
The core server contains a list of mandatory modules. These are loaded
392
first. Currently the only module on this list is the bitmap font module.
394
The next set of modules loaded are those specified explicitly in the Module
395
section of the config file.
397
The final set of initial modules are the driver modules referenced by the
398
active Device and InputDevice sections in the config file. Each of these
399
modules is loaded exactly once.
401
5.6 Register Video and Input Drivers
403
This is done at the start of the first server generation only.
405
When a driver module is loaded, the loader calls its Setup function. For
406
video drivers, this function calls xf86AddDriver() to register the driver's
407
DriverRec, which contains a small set of essential details and driver entry
408
points required during the early phase of InitOutput(). xf86AddDriver() adds
409
it to the global xf86DriverList[] array.
411
The DriverRec contains the driver canonical name, the Identify(), Probe() and
412
AvailableOptions() function entry points as well as a pointer to the driver's
413
module (as returned from the loader when the driver was loaded) and a refer-
414
ence count which keeps track of how many screens are using the driver. The
415
entry driver entry points are those required prior to the driver allocating
416
and filling in its ScrnInfoRec.
418
For a static server, the xf86DriverList[] array is initialised at build time,
419
and the loading of modules is not done.
421
A similar procedure is used for input drivers. The input driver's Setup
422
function calls xf86AddInputDriver() to register the driver's InputDriverRec,
423
which contains a small set of essential details and driver entry points
424
required during the early phase of InitInput(). xf86AddInputDriver() adds it
425
to the global xf86InputDriverList[] array. For a static server, the
426
xf86InputDriverList[] array is initialised at build time.
428
Both the xf86DriverList[] and xf86InputDriverList[] arrays have been ini-
429
tialised by the end of this stage.
431
Once all the drivers are registered, their ChipIdentify() functions are
434
void ChipIdentify(int flags)
436
This is expected to print a message indicating the driver
437
name, a short summary of what it supports, and a list of
438
the chipset names that it supports. It may use the
439
xf86PrintChipsets() helper to do this.
441
void xf86PrintChipsets(const char *drvname, const char *drvmsg,
445
This function provides an easy way for a driver's ChipI-
446
dentify function to format the identification message.
448
5.7 Initialise Access Control
450
This is done at the start of the first server generation only.
452
The Resource Access Control (RAC) subsystem is initialised before calling any
453
driver functions that may access hardware. All generic bus information is
454
probed and saved (for restoration later). All (shared resource) video
455
devices are disabled at the generic bus level, and a probe is done to find
456
the ``primary'' video device. These devices remain disabled for the next
459
5.8 Video Driver Probe
461
This is done at the start of the first server generation only. The Chip-
462
Probe() function of each registered video driver is called.
464
Bool ChipProbe(DriverPtr drv, int flags)
466
The purpose of this is to identify all instances of hard-
467
ware supported by the driver. The flags value is cur-
468
rently either 0, PROBE_DEFAULT or PROBE_DETECT.
469
PROBE_DETECT is used if "-configure" or "-probe" command
470
line arguments are given and indicates to the Probe()
471
function that it should not configure the bus entities
472
and that no XF86Config information is available.
474
The probe must find the active device sections that match
475
the driver by calling xf86MatchDevice(). The number of
476
matches found limits the maximum number of instances for
477
this driver. If no matches are found, the function
478
should return FALSE immediately.
480
Devices that cannot be identified by using device-inde-
481
pendent methods should be probed at this stage (keeping
482
in mind that access to all resources that can be disabled
483
in a device-independent way are disabled during this
484
phase). The probe must be a minimal probe. It should
485
just determine if there is a card present that the driver
486
can drive. It should use the least intrusive probe meth-
487
ods possible. It must not do anything that is not essen-
488
tial, like probing for other details such as the amount
489
of memory installed, etc. It is recommended that the
490
xf86MatchPciInstances() helper function be used for iden-
491
tifying matching PCI devices, and similarly the
492
xf86MatchIsaInstances() for ISA (non-PCI) devices (see
493
the RAC (section 9., page 1) section). These helpers
494
also checks and claims the appropriate entity. When not
495
using the helper, that should be done with xf86CheckPciS-
496
lot() and xf86ClaimPciSlot() for PCI devices and
497
xf86ClaimIsaSlot() for ISA devices (see the RAC (section
498
9., page 1) section).
500
The probe must register all non-relocatable resources at
501
this stage. If a resource conflict is found between
502
exclusive resources the driver will fail immediately.
503
This is usually best done with the xf86ConfigPciEntity()
504
helper function for PCI and xf86ConfigIsaEntity() for ISA
505
(see the RAC (section 9., page 1) section). It is possi-
506
ble to register some entity specific functions with those
507
helpers. When not using the helpers, the xf86AddEntity-
508
ToScreen() xf86ClaimFixedResources() and xf86SetEntity-
509
Funcs() should be used instead (see the RAC (section 9.,
512
If a chipset is specified in an active device section
513
which the driver considers relevant (ie it has no driver
514
specified, or the driver specified matches the driver
515
doing the probe), the Probe must return FALSE if the
516
chipset doesn't match one supported by the driver.
518
If there are no active device sections that the driver
519
considers relevant, it must return FALSE.
521
Allocate a ScrnInfoRec for each active instance of the
522
hardware found, and fill in the basic information,
523
including the other driver entry points. This is best
524
done with the xf86ConfigIsaEntity() helper function for
525
ISA instances or xf86ConfigPciEntity() for PCI instances.
526
These functions allocate a ScrnInfoRec for active enti-
527
ties. Optionally xf86AllocateScreen() function may also
528
be used to allocate the ScrnInfoRec. Any of these func-
529
tions take care of initialising fields to defined
532
Claim the entities for each instance of the hardware
533
found. This prevents other drivers from claiming the
536
Must leave hardware in the same state it found it in, and
537
must not do any hardware initialisation.
539
All detection can be overridden via the config file, and
540
that parsed information is available to the driver at
543
Returns TRUE if one or more instances are found, and
546
int xf86MatchDevice(const char *drivername,
548
GDevPtr **driversectlist)
550
This function takes the name of the driver and returns
551
via driversectlist a list of device sections that match
552
the driver name. The function return value is the number
553
of matches found. If a fatal error is encountered the
556
The caller should use xfree() to free *driversectlist
557
when it is no longer needed.
559
ScrnInfoPtr xf86AllocateScreen(DriverPtr drv, int flags)
561
This function allocates a new ScrnInfoRec in the
562
xf86Screens[] array. This function is normally called by
563
the video driver ChipProbe() functions. The return value
564
is a pointer to the newly allocated ScrnInfoRec. The
565
scrnIndex, origIndex, module and drv fields are ini-
566
tialised. The reference count in drv is incremented.
567
The storage for any currently allocated ``privates''
568
pointers is also allocated and the privates field ini-
569
tialised (the privates data is of course not allocated or
570
initialised). This function never returns on failure.
571
If the allocation fails, the server exits with a fatal
572
error. The flags value is not currently used, and should
575
At the completion of this, a list of ScrnInfoRecs have been allocated in the
576
xf86Screens[] array, and the associated entities and fixed resources have
577
been claimed. The following ScrnInfoRec fields must be initialised at this
596
(*) These are initialised when the ScrnInfoRec is allocated, and not explic-
599
The following ScrnInfoRec fields must be initialised if the driver is going
609
This is done at the start of the first server generation only.
611
After the Probe phase is finished, there will be some number of ScrnInfoRecs.
612
These are then matched with the active Screen sections in the XF86Config, and
613
those not having an active Screen section are deleted. If the number of
614
remaining screens is 0, InitOutput() sets screenInfo.numScreens to 0 and
617
At this point the following fields of the ScrnInfoRecs must be initialised:
621
5.10 Allocate non-conflicting resources
623
This is done at the start of the first server generation only.
625
Before calling the drivers again, the resource information collected from the
626
Probe phase is processed. This includes checking the extent of PCI resources
627
for the probed devices, and resolving any conflicts in the relocatable PCI
628
resources. It also reports conflicts, checks bus routing issues, and any-
629
thing else that is needed to enable the entities for the next phase.
631
If any drivers registered an EntityInit() function during the Probe phase,
632
then they are called here.
634
5.11 Sort the Screens and pre-check Monitor Information
636
This is done at the start of the first server generation only.
638
The list of screens is sorted to match the ordering requested in the config
641
The list of modes for each active monitor is checked against the monitor's
642
parameters. Invalid modes are pruned.
646
This is done at the start of the first server generation only.
648
For each ScrnInfoRec, enable access to the screens entities and call the
649
ChipPreInit() function.
651
Bool ChipPreInit(ScrnInfoRec screen, int flags)
653
The purpose of this function is to find out all the
654
information required to determine if the configuration is
655
usable, and to initialise those parts of the ScrnInfoRec
656
that can be set once at the beginning of the first server
659
The number of entities registered for the screen should
660
be checked against the expected number (most drivers
661
expect only one). The entity information for each of
662
them should be retrieved (with xf86GetEntityInfo()) and
663
checked for the correct bus type and that none of the
664
sharable resources registered during the Probe phase was
667
Access to resources for the entities that can be con-
668
trolled in a device-independent way are enabled before
669
this function is called. If the driver needs to access
670
any resources that it has disabled in an EntityInit()
671
function that it registered, then it may enable them here
672
providing that it disables them before this function
675
This includes probing for video memory, clocks, ramdac,
676
and all other HW info that is needed. It includes deter-
677
mining the depth/bpp/visual and related info. It
678
includes validating and determining the set of video
679
modes that will be used (and anything that is required to
682
This information should be determined in the least intru-
683
sive way possible. The state of the HW must remain
684
unchanged by this function. Although video memory
685
(including MMIO) may be mapped within this function, it
686
must be unmapped before returning. Driver specific
687
information should be stored in a structure hooked into
688
the ScrnInfoRec's driverPrivate field. Any other modules
689
which require persistent data (ie data that persists
690
across server generations) should be initialised in this
691
function, and they should allocate a ``privates'' index
692
to hook their data into by calling xf86AllocateScrnInfo-
693
PrivateIndex(). The ``privates'' data is persistent.
695
Helper functions for some of these things are provided at
696
the XFree86 common level, and the driver can choose to
699
All additional resources that the screen needs must be
700
registered here. This should be done with xf86Register-
701
Resources(). If some of the fixed resources registered
702
in the Probe phase are not needed or not decoded by the
703
hardware when in the OPERATING server state, their status
704
should be updated with xf86SetOperatingState().
706
Modules may be loaded at any point in this function, and
707
all modules that the driver will need must be loaded
708
before the end of this function. Either the
709
xf86LoadSubModule() or the xf86LoadDrvSubModule() func-
710
tion should be used to load modules depending on whether
711
a ScrnInfoRec has been set up. A driver may unload a mod-
712
ule within this function if it was only needed temporar-
713
ily, and the xf86UnloadSubModule() function should be
714
used to do that. Otherwise there is no need to explic-
715
itly unload modules because the loader takes care of mod-
716
ule dependencies and will unload submodules automatically
717
if/when the driver module is unloaded.
719
The bulk of the ScrnInfoRec fields should be filled out
722
ChipPreInit() returns FALSE when the configuration is
723
unusable in some way (unsupported depth, no valid modes,
724
not enough video memory, etc), and TRUE if it is usable.
726
It is expected that if the ChipPreInit() function returns
727
TRUE, then the only reasons that subsequent stages in the
728
driver might fail are lack or resources (like xalloc
729
failures). All other possible reasons for failure should
730
be determined by the ChipPreInit() function.
732
The ScrnInfoRecs for screens where the ChipPreInit() fails are removed. If
733
none remain, InitOutput() sets screenInfo.numScreens to 0 and returns.
735
At this point, further fields of the ScrnInfoRecs would normally be filled
736
in. Most are not strictly mandatory, but many are required by other layers
737
and/or helper functions that the driver may choose to use. The documentation
738
for those layers and helper functions indicates which they require.
740
The following fields of the ScrnInfoRecs should be filled in if the driver is
767
progClock (TRUE if clock is programmable)
771
numClocks (if not programmable)
772
clock[] (if not programmable)
781
pointer xf86LoadSubModule(ScrnInfoPtr pScrn, const char *name): and
782
pointer xf86LoadDrvSubModule(DriverPtr drv, const char *name):
784
Load a module that a driver depends on. This function
785
loads the module name as a sub module of the driver. The
786
return value is a handle identifying the new module. If
787
the load fails, the return value will be NULL. If a
788
driver needs to explicitly unload a module it has loaded
789
in this way, the return value must be saved and passed to
790
xf86UnloadSubModule() when unloading.
792
void xf86UnloadSubModule(pointer module)
794
Unloads the module referenced by module. module should
795
be a pointer returned previously by xf86LoadSubModule()
796
or xf86LoadDrvSubModule() .
798
5.13 Cleaning up Unused Drivers
800
At this point it is known which screens will be in use, and which drivers are
801
being used. Unreferenced drivers (and modules they may have loaded) are
804
5.14 Consistency Checks
806
The parameters that must be global to the server, like pixmap formats, bitmap
807
bit order, bitmap scanline unit and image byte order are compared for each of
808
the screens. If a mismatch is found, the server exits with an appropriate
811
5.15 Check if Resource Control is Needed
813
Determine if resource access control is needed. This is the case if more
814
than one screen is used. If necessary the RAC wrapper module is loaded.
816
5.16 AddScreen (ScreenInit)
818
At this point, the valid screens are known. AddScreen() is called for each
819
of them, passing ChipScreenInit() as the argument. AddScreen() is a DIX
820
function that allocates a new screenInfo.screen[] entry (aka pScreen), and
821
does some basic initialisation of it. It then calls the ChipScreenInit()
822
function, with pScreen as one of its arguments. If ChipScreenInit() returns
823
FALSE, AddScreen() returns -1. Otherwise it returns the index of the screen.
824
AddScreen() should only fail because of programming errors or failure to
825
allocate resources (like memory). All configuration problems should be
826
detected BEFORE this point.
828
Bool ChipScreenInit(int index, ScreenPtr pScreen,
830
int argc, char **argv)
832
This is called at the start of each server generation.
834
Fill in all of pScreen, possibly doing some of this by
835
calling ScreenInit functions from other layers like mi,
836
framebuffers (cfb, etc), and extensions.
838
Decide which operations need to be placed under resource
839
access control. The classes of operations are the frame
840
buffer operations (RAC_FB), the pointer operations
841
(RAC_CURSOR), the viewport change operations (RAC_VIEW-
842
PORT) and the colormap operations (RAC_COLORMAP). Any
843
operation that requires resources which might be disabled
844
during OPERATING state should be set to use RAC. This
845
can be specified separately for memory and IO resources
846
(the racMemFlags and racIoFlags fields of the ScrnInfoRec
849
Map any video memory or other memory regions.
851
Save the video card state. Enough state must be saved so
852
that the original state can later be restored.
854
Initialise the initial video mode. The ScrnInfoRec's
855
vtSema field should be set to TRUE just prior to changing
856
the video hardware's state.
858
The ChipScreenInit() function (or functions from other layers that it calls)
859
should allocate entries in the ScreenRec's devPrivates area by calling Allo-
860
cateScreenPrivateIndex() if it needs per-generation storage. Since the
861
ScreenRec's devPrivates information is cleared for each server generation,
862
this is the correct place to initialise it.
864
After AddScreen() has successfully returned, the following ScrnInfoRec fields
871
The ChipScreenInit() function should initialise the CloseScreen and Save-
872
Screen fields of pScreen. The old value of pScreen->CloseScreen should be
873
saved as part of the driver's per-screen private data, allowing it to be
874
called from ChipCloseScreen(). This means that the existing CloseScreen()
877
5.17 Finalising RAC Initialisation
879
After all the ChipScreenInit() functions have been called, each screen has
880
registered its RAC requirements. This information is used to determine which
881
shared resources are requested by more than one driver and set the access
882
functions accordingly. This is done following these rules:
884
1. The sharable resources registered by each entity are compared. If a
885
resource is registered by more than one entity the entity will be
886
marked to indicate that it needs to share this resources type (IO or
889
2. A resource marked ``disabled'' during OPERATING state will be ignored
892
3. A resource marked ``unused'' will only conflict with an overlapping
893
resource of an other entity if the second is actually in use during
896
4. If an ``unused'' resource was found to conflict but the entity does not
897
use any other resource of this type the entire resource type will be
898
disabled for that entity.
900
5.18 Finishing InitOutput()
902
At this point InitOutput() is finished, and all the screens have been setup
903
in their initial video mode.
907
When a SwitchMode event is received, ChipSwitchMode() is called (when it
910
Bool ChipSwitchMode(int index, DisplayModePtr mode, int flags)
912
Initialises the new mode for the screen identified by
913
index;. The viewport may need to be adjusted also.
915
5.20 Changing Viewport
917
When a Change Viewport event is received, ChipAdjustFrame() is called (when
920
void ChipAdjustFrame(int index, int x, int y, int flags)
922
Changes the viewport for the screen identified by index;.
924
It should be noted that many chipsets impose restrictions
925
on where the viewport may be placed in the virtual reso-
926
lution, either for alignment reasons, or to prevent the
927
start of the viewport from being positioned within a
928
pixel (as can happen in a 24bpp mode). After calculating
929
the value the chipset's panning registers need to be set
930
to for non-DGA modes, this function should recalculate
931
the ScrnInfoRec's frameX0, frameY0, frameX1 and frameY1
932
fields to correspond to that value. If this is not done,
933
switching to another mode might cause the position of a
934
hardware cursor to change.
938
When a VT switch event is received, xf86VTSwitch() is called. xf86VTSwitch()
943
o enable port I/O access
945
o save and initialise the bus/resource state
947
o enter the SETUP server state
949
o calls ChipEnterVT() for each screen
951
o enter the OPERATING server state
955
o Restore fb from saved pixmap for each screen
957
o Enable all input devices
961
o Save fb to pixmap for each screen
965
o enter the SETUP server state
967
o calls ChipLeaveVT() for each screen
969
o disable all input devices
971
o restore bus/resource state
973
o disables port I/O access
975
Bool ChipEnterVT(int index, int flags)
977
This function should initialise the current video mode
978
and initialise the viewport, turn on the HW cursor if
981
Should it re-save the video state before initialising the
984
void ChipLeaveVT(int index, int flags)
986
This function should restore the saved video state. If
987
appropriate it should also turn off the HW cursor, and
988
invalidate any pixmap/font caches.
990
Optionally, ChipLeaveVT() may also unmap memory regions. If so,
991
ChipEnterVT() will need to remap them. Additionally, if an aper-
992
ture used to access video memory is unmapped and remapped in this
993
fashion, ChipEnterVT() will also need to notify the framebuffer
994
layers of the aperture's new location in virtual memory. This is
995
done with a call to the screen's ModifyPixmapHeader() function, as
998
(*pScreen->ModifyPixmapHeader)(pScrn->ppix,
1000
-1, -1, -1, -1, -1, NewApertureAddress);
1002
where the ``ppix'' field in a ScrnInfoRec
1003
points to the pixmap used by the screen's
1004
SaveRestoreImage() function to hold the
1005
screen's contents while switched out.
1007
Currently, aperture remapping, as described here, should not be
1008
attempted if the driver uses the xf8_16bpp or xf8_32bpp framebuffer
1009
layers. A pending restructuring of VT switching will address this
1010
restriction in the near future.
1012
Other layers may wrap the ChipEnterVT() and ChipLeaveVT() functions if they
1013
need to take some action when these events are received.
1015
5.22 End of server generation
1017
At the end of each server generation, the DIX layer calls ChipCloseScreen()
1020
Bool ChipCloseScreen(int index, ScreenPtr pScreen)
1022
This function should restore the saved video state and
1023
unmap the memory regions.
1025
It should also free per-screen data structures allocated
1026
by the driver. Note that the persistent data held in the
1027
ScrnInfoRec's driverPrivate field should not be freed
1028
here because it is needed by subsequent server genera-
1031
The ScrnInfoRec's vtSema field should be set to FALSE
1032
once the video HW state has been restored.
1034
Before freeing the per-screen driver data the saved Clos-
1035
eScreen value should be restored to pScreen->CloseScreen,
1036
and that function should be called after freeing the
1039
6. Optional Driver Functions
1041
The functions outlined here can be called from the XFree86 common layer, but
1042
their presence is optional.
1046
When a mode validation helper supplied by the XFree86-common layer is being
1047
used, it can be useful to provide a function to check for hw specific mode
1050
ModeStatus ChipValidMode(int index, DisplayModePtr mode,
1052
Bool verbose, int flags)
1054
Check the passed mode for hw-specific constraints, and
1055
return the appropriate status value.
1057
This function may also modify the effective timings and clock of the passed
1058
mode. These have been stored in the mode's Crtc* and SynthClock elements,
1059
and have already been adjusted for interlacing, doublescanning, multiscanning
1060
and clock multipliers and dividers. The function should not modify any other
1061
mode field, unless it wants to modify the mode timings reported to the user
1062
by xf86PrintModes().
1064
The function is called once for every mode in the XF86Config Monitor section
1065
assigned to the screen, with flags set to MODECHECK_INITIAL. It is subse-
1066
quently called for every mode in the XF86Config Display subsection assigned
1067
to the screen, with flags set to MODECHECK_FINAL. In the second case, the
1068
mode will have successfully passed all other tests. In addition, the ScrnIn-
1069
foRec's virtualX, virtualY and displayWidth fields will have been set as if
1070
the mode to be validated were to be the last mode accepted.
1072
In effect, calls with MODECHECK_INITIAL are intended for checks that do not
1073
depend on any mode other than the one being validated, while calls with MOD-
1074
ECHECK_FINAL are intended for checks that may involve more than one mode.
1076
6.2 Free screen data
1078
When a screen is deleted prior to the completion of the ScreenInit phase the
1079
ChipFreeScreen() function is called when defined.
1081
void ChipFreeScreen(int scrnindex, int flags)
1083
Free any driver-allocated data that may have been allo-
1084
cated up to and including an unsuccessful Chip-
1085
ScreenInit() call. This would predominantly be data
1086
allocated by ChipPreInit() that persists across server
1087
generations. It would include the driverPrivate, and any
1088
``privates'' entries that modules may have allocated.
1090
7. Recommended driver functions
1092
The functions outlined here are for internal use by the driver only. They
1093
are entirely optional, and are never accessed directly from higher layers.
1094
The sample function declarations shown here are just examples. The interface
1095
(if any) used is up to the driver.
1099
Save the video state. This could be called from ChipScreenInit() and (possi-
1102
void ChipSave(ScrnInfoPtr pScrn)
1104
Saves the current state. This will only be saving pre-
1105
server states or states before returning to the server.
1106
There is only one current saved state per screen and it
1107
is stored in private storage in the screen.
1111
Restore the original video state. This could be called from the
1112
ChipLeaveVT() and ChipCloseScreen() functions.
1114
void ChipRestore(ScrnInfoPtr pScrn)
1116
Restores the saved state from the private storage. Usu-
1117
ally only used for restoring text modes.
1121
Initialise a video mode. This could be called from the ChipScreenInit(),
1122
ChipSwitchMode() and ChipEnterVT() functions.
1124
Bool ChipModeInit(ScrnInfoPtr pScrn, DisplayModePtr mode)
1126
Programs the hardware for the given video mode.
1128
8. Data and Data Structures
1130
8.1 Command line data
1132
Command line options are typically global, and are stored in global vari-
1133
ables. These variables are read-only and are available to drivers via a
1134
function call interface. Most of these command line values are processed via
1135
helper functions to ensure that they are treated consistently by all drivers.
1136
The other means of access is provided for cases where the supplied helper
1137
functions might not be appropriate.
1141
xf86Verbose verbosity level
1142
xf86Bpp -bpp from the command line
1143
xf86Depth -depth from the command line
1144
xf86Weight -weight from the command line
1145
xf86Gamma -{r,g,b,}gamma from the command line
1146
xf86FlipPixels -flippixels from the command line
1147
xf86ProbeOnly -probeonly from the command line
1148
defaultColorVisualClass -cc from the command line
1150
If we ever do allow for screen-specific command line options, we may need to
1153
These can be accessed in a read-only manner by drivers with the following
1156
int xf86GetVerbosity()
1158
Returns the value of xf86Verbose.
1162
Returns the -depth command line setting. If not set on
1163
the command line, -1 is returned.
1167
Returns the -weight command line setting. If not set on
1168
the command line, {0, 0, 0} is returned.
1170
Gamma xf86GetGamma()
1172
Returns the -gamma or -rgamma, -ggamma, -bgamma command
1173
line settings. If not set on the command line, {0.0,
1174
0.0, 0.0} is returned.
1176
Bool xf86GetFlipPixels()
1178
Returns TRUE if -flippixels is present on the command
1179
line, and FALSE otherwise.
1181
const char *xf86GetServerName()
1183
Returns the name of the X server from the command line.
1187
Config file data contains parts that are global, and parts that are Screen
1188
specific. All of it is parsed into data structures that neither the drivers
1189
or most other parts of the server need to know about.
1191
The global data is typically not required by drivers, and as such, most of it
1192
is stored in the private xf86InfoRec.
1194
The screen-specific data collected from the config file is stored in screen,
1195
device, display, monitor-specific data structures that are separate from the
1196
ScrnInfoRecs, with the appropriate elements/fields hooked into the ScrnIn-
1197
foRecs as required. The screen config data is held in confScreenRec, device
1198
data in the GDevRec, monitor data in the MonRec, and display data in the Dis-
1201
The XFree86 common layer's screen specific data (the actual data in use for
1202
each screen) is held in the ScrnInfoRecs. As has been outlined above, the
1203
ScrnInfoRecs are allocated at probe time, and it is the responsibility of the
1204
Drivers' Probe() and PreInit() functions to finish filling them in based on
1205
both data provided on the command line and data provided from the Config
1206
file. The precedence for this is:
1208
command line -> config file -> probed/default data
1210
For most things in this category there are helper functions that the drivers
1211
can use to ensure that the above precedence is consistently used.
1213
As well as containing screen-specific data that the XFree86 common layer
1214
(including essential parts of the server infrastructure as well as helper
1215
functions) needs to access, it also contains some data that drivers use
1216
internally. When considering whether to add a new field to the ScrnInfoRec,
1217
consider the balance between the convenience of things that lots of drivers
1218
need and the size/obscurity of the ScrnInfoRec.
1220
Per-screen driver specific data that cannot be accommodated with the static
1221
ScrnInfoRec fields is held in a driver-defined data structure, a pointer to
1222
which is assigned to the ScrnInfoRec's driverPrivate field. This is per-
1223
screen data that persists across server generations (as does the bulk of the
1224
static ScrnInfoRec data). It would typically also include the video card's
1227
Per-screen data for other modules that the driver uses (for example, the XAA
1228
module) that is reset for each server generation is hooked into the ScrnIn-
1229
foRec through it's privates field.
1231
Once it has stabilised, the data structures and variables accessible to video
1232
drivers will be documented here. In the meantime, those things defined in
1233
the xf86.h and xf86str.h files are visible to video drivers. Things defined
1234
in xf86Priv.h and xf86Privstr.h are NOT intended to be visible to video
1235
drivers, and it is an error for a driver to include those files.
1237
8.3 Accessing global data
1239
Some other global state information that the drivers may access via functions
1242
Bool xf86ServerIsExiting()
1244
Returns TRUE if the server is at the end of a generation
1245
and is in the process of exiting, and FALSE otherwise.
1247
Bool xf86ServerIsResetting()
1249
Returns TRUE if the server is at the end of a generation
1250
and is in the process of resetting, and FALSE otherwise.
1252
Bool xf86ServerIsInitialising()
1254
Returns TRUE if the server is at the beginning of a gen-
1255
eration and is in the process of initialising, and FALSE
1258
Bool xf86ServerIsOnlyProbing()
1260
Returns TRUE if the -probeonly command line flag was
1261
specified, and FALSE otherwise.
1263
Bool xf86CaughtSignal()
1265
Returns TRUE if the server has caught a signal, and FALSE
1268
8.4 Allocating private data
1270
A driver and any module it uses may allocate per-screen private storage in
1271
either the ScreenRec (DIX level) or ScrnInfoRec (XFree86 common layer level).
1272
ScreenRec storage persists only for a single server generation, and ScrnIn-
1273
foRec storage persists across generations for the lifetime of the server.
1275
The ScreenRec devPrivates data must be reallocated/initialised at the start
1276
of each new generation. This is normally done from the ChipScreenInit()
1277
function, and Init functions for other modules that it calls. Data allocated
1278
in this way should be freed by the driver's ChipCloseScreen() functions, and
1279
Close functions for other modules that it calls. A new devPrivates entry is
1280
allocated by calling the AllocateScreenPrivateIndex() function.
1282
int AllocateScreenPrivateIndex()
1284
This function allocates a new element in the devPrivates
1285
field of all currently existing ScreenRecs. The return
1286
value is the index of this new element in the devPrivates
1287
array. The devPrivates field is of type DevUnion:
1289
typedef union _DevUnion {
1293
pointer (*fptr)(void);
1296
which allows the element to be used for any of the above
1297
types. It is commonly used as a pointer to data that the
1298
caller allocates after the new index has been allocated.
1300
This function will return -1 when there is an error allo-
1301
cating the new index.
1303
The ScrnInfoRec privates data persists for the life of the server, so only
1304
needs to be allocated once. This should be done from the ChipPreInit() func-
1305
tion, and Init functions for other modules that it calls. Data allocated in
1306
this way should be freed by the driver's ChipFreeScreen() functions, and Free
1307
functions for other modules that it calls. A new privates entry is allocated
1308
by calling the xf86AllocateScrnInfoPrivateIndex() function.
1310
int xf86AllocateScrnInfoPrivateIndex()
1312
This function allocates a new element in the privates
1313
field of all currently existing ScrnInfoRecs. The return
1314
value is the index of this new element in the privates
1315
array. The privates field is of type DevUnion:
1317
typedef union _DevUnion {
1321
pointer (*fptr)(void);
1324
which allows the element to be used for any of the above
1325
types. It is commonly used as a pointer to data that the
1326
caller allocates after the new index has been allocated.
1328
This function will not return when there is an error
1329
allocating the new index. When there is an error it will
1330
cause the server to exit with a fatal error. The similar
1331
function for allocation privates in the ScreenRec (Allo-
1332
cateScreenPrivateIndex()) differs in this respect by
1333
returning -1 when the allocation fails.
1335
9. Keeping Track of Bus Resources
1337
9.1 Theory of Operation
1339
The XFree86 common layer has knowledge of generic access control mechanisms
1340
for devices on certain bus systems (currently the PCI bus) as well as of
1341
methods to enable or disable access to the buses itself. Furthermore it can
1342
access information on resources decoded by these devices and if necessary
1345
When first starting the Xserver collects all this information, saves it for
1346
restoration, checks it for consistency, and if necessary, corrects it.
1347
Finally it disables all resources on a generic level prior to calling any
1350
When the Probe() function of each driver is called the device sections are
1351
matched against the devices found in the system. The driver may probe
1352
devices at this stage that cannot be identified by using device independent
1353
methods. Access to all resources that can be controlled in a device indepen-
1354
dent way is disabled. The Probe() function should register all non-relocat-
1355
able resources at this stage. If a resource conflict is found between exclu-
1356
sive resources the driver will fail immediately. Optionally the driver might
1357
specify an EntityInit(), EntityLeave() and EntityEnter() function.
1359
EntityInit() can be used to disable any shared resources that are not con-
1360
trolled by the generic access control functions. It is called prior to the
1361
PreInit phase regardless if an entity is active or not. When calling the
1362
EntityInit(), EntityEnter() and EntityLeave() functions the common level will
1363
disable access to all other entities on a generic level. Since the common
1364
level has no knowledge of device specific methods to disable access to
1365
resources it cannot be guaranteed that certain resources are not decoded by
1366
any other entity until the EntityInit() or EntityEnter() phase is finished.
1367
Device drivers should therefore register all those resources which they are
1368
going to disable. If these resources are never to be used by any driver
1369
function they may be flagged ResInit so that they can be removed from the
1370
resource list after processing all EntityInit() functions. EntityEnter()
1371
should disable decoding of all resources which are not registered as exclu-
1372
sive and which are not handled by the generic access control in the common
1373
level. The difference to EntityInit() is that the latter one is only called
1374
once during lifetime of the server. It can therefore be used to set up vari-
1375
ables prior to disabling resources. EntityLeave() should restore the origi-
1376
nal state when exiting the server or switching to a different VT. It also
1377
needs to disable device specific access functions if they need to be disabled
1378
on server exit or VT switch. The default state is to enable them before giv-
1381
In PreInit() phase each driver should check if any sharable resources it has
1382
registered during Probe() has been denied and take appropriate action which
1383
could simply be to fail. If it needs to access resources it has disabled
1384
during EntitySetup() it can do so provided it has registered these and will
1385
disable them before returning from PreInit(). This also applies to all other
1386
driver functions. Several functions are provided to request resource ranges,
1387
register these, correct PCI config space and add replacements for the generic
1388
access functions. Resources may be marked ``disabled'' or ``unused'' during
1389
OPERATING stage. Although these steps could also be performed in
1390
ScreenInit(), this is not desirable.
1392
Following PreInit() phase the common level determines if resource access con-
1393
trol is needed. This is the case if more than one screen is used. If neces-
1394
sary the RAC wrapper module is loaded. In ScreenInit() the drivers can
1395
decide which operations need to be placed under RAC. Available are the frame
1396
buffer operations, the pointer operations and the colormap operations. Any
1397
operation that requires resources which might be disabled during OPERATING
1398
state should be set to use RAC. This can be specified separately for memory
1401
When ScreenInit() phase is done the common level will determine which shared
1402
resources are requested by more than one driver and set the access functions
1403
accordingly. This is done following these rules:
1405
1. The sharable resources registered by each entity are compared. If a
1406
resource is registered by more than one entity the entity will be
1407
marked to need to share this resources type (IO or MEM).
1409
2. A resource marked ``disabled'' during OPERATING state will be ignored
1412
3. A resource marked ``unused'' will only conflicts with an overlapping
1413
resource of an other entity if the second is actually in use during
1416
4. If an ``unused'' resource was found to conflict however the entity does
1417
not use any other resource of this type the entire resource type will
1418
be disabled for that entity.
1420
The driver has the choice among different ways to control access to certain
1423
1. It can rely on the generic access functions. This is probably the most
1424
common case. Here the driver only needs to register any resource it is
1427
2. It can replace the generic access functions by driver specific ones.
1428
This will mostly be used in cases where no generic access functions are
1429
available. In this case the driver has to make sure these resources
1430
are disabled when entering the PreInit() stage. Since the replacement
1431
functions are registered in PreInit() the driver will have to enable
1432
these resources itself if it needs to access them during this state.
1433
The driver can specify if the replacement functions can control memory
1434
and/or I/O resources separately.
1436
3. The driver can enable resources itself when it needs them. Each driver
1437
function enabling them needs to disable them before it will return.
1438
This should be used if a resource which can be controlled in a device
1439
dependent way is only required during SETUP state. This way it can be
1440
marked ``unused'' during OPERATING state.
1442
A resource which is decoded during OPERATING state however never accessed by
1443
the driver should be marked unused.
1445
Since access switching latencies are an issue during Xserver operation, the
1446
common level attempts to minimize the number of entities that need to be
1447
placed under RAC control. When a wrapped operation is called, the EnableAc-
1448
cess() function is called before control is passed on. EnableAccess() checks
1449
if a screen is under access control. If not it just establishes bus routing
1450
and returns. If the screen needs to be under access control, EnableAccess()
1451
determines which resource types (MEM, IO) are required. Then it tests if
1452
this access is already established. If so it simply returns. If not it dis-
1453
ables the currently established access, fixes bus routing and enables access
1454
to all entities registered for this screen.
1456
Whenever a mode switch or a VT-switch is performed the common level will
1457
return to SETUP state.
1461
Resource have certain properties. When registering resources each range is
1462
accompanied by a flag consisting of the ORed flags of the different proper-
1463
ties the resource has. Each resource range may be classified according to
1465
o its physical properties i.e., if it addresses memory (ResMem) or I/O
1468
o if it addresses a block (ResBlock) or sparse (ResSparse) range,
1470
o its access properties.
1472
There are two known access properties:
1474
o ResExclusive for resources which may not be shared with any other device
1477
o ResShared for resources which can be disabled and therefore can be
1480
If it is necessary to test a resource against any type a generic access type
1481
ResAny is provided. If this is set the resource will conflict with any
1482
resource of a different entity intersecting its range. Further it can be
1483
specified that a resource is decoded however never used during any stage
1484
(ResUnused) or during OPERATING state (ResUnusedOpr). A resource only visi-
1485
ble during the init functions (ie. EntityInit(), EntityEnter() and
1486
EntityLeave() should be registered with the flag ResInit. A resource that
1487
might conflict with background resource ranges may be flagged with ResBios.
1488
This might be useful when registering resources ranges that were assigned by
1491
Several predefined resource lists are available for VGA and 8514/A resources
1492
in common/xf86Resources.h.
1494
9.3 Available Functions
1496
The functions provided for resource management are listed in their order of
1501
In this phase each driver detects those resources it is able to drive, cre-
1502
ates an entity record for each of them, registers non-relocatable resources
1503
and allocates screens and adds the resources to screens.
1505
Two helper functions are provided for matching device sections in the
1506
XF86Config file to the devices:
1508
int xf86MatchPciInstances(const char *driverName, int vendorID,
1510
SymTabPtr chipsets, PciChipsets *PCIchipsets,
1512
GDevPtr *devList, int numDevs, DriverPtr drvp,
1514
int **foundEntities)
1516
This function finds matches between PCI cards that a
1517
driver supports and config file device sections. It is
1518
intended for use in the ChipProbe() function of drivers
1519
for PCI cards. Only probed PCI devices with a vendor ID
1520
matching vendorID are considered. devList and numDevs
1521
are typically those found from calling xf86MatchDevice(),
1522
and represent the active config file device sections rel-
1523
evant to the driver. PCIchipsets is a table that pro-
1524
vides a mapping between the PCI device IDs, the driver's
1525
internal chipset tokens and a list of fixed resources.
1527
When a device section doesn't have a BusID entry it can
1528
only match the primary video device. Secondary devices
1529
are only matched with device sections that have a match-
1532
Once the preliminary matches have been found, a final
1533
match is confirmed by checking if the chipset override,
1534
ChipID override or probed PCI chipset type match one of
1535
those given in the chipsets and PCIchipsets lists. The
1536
PCIchipsets list includes a list of the PCI device IDs
1537
supported by the driver. The list should be terminated
1538
with an entry with PCI ID -1". The chipsets list is a
1539
table mapping the driver's internal chipset tokens to
1540
names, and should be terminated with a NULL entry. Only
1541
those entries with a corresponding entry in the PCI-
1542
chipsets list are considered. The order of precedence
1543
is: config file chipset, config file ChipID, probed PCI
1546
In cases where a driver handles PCI chipsets with more
1547
than one vendor ID, it may set vendorID to 0, and OR each
1548
devID in the list with (the vendor ID << 16).
1550
Entity index numbers for confirmed matches are returned
1551
as an array via foundEntities. The PCI information,
1552
chipset token and device section for each match are found
1553
in the EntityInfoRec referenced by the indices.
1555
The function return value is the number of confirmed
1556
matches. A return value of -1 indicates an internal
1557
error. The returned foundEntities array should be freed
1558
by the driver with xfree() when it is no longer needed in
1559
cases where the return value is greater than zero.
1561
int xf86MatchIsaInstances(const char *driverName,
1563
SymTabPtr chipsets, IsaChipsets *ISAchipsets,
1565
DriverPtr drvp, FindIsaDevProc FindIsaDevice,
1567
GDevPtr *devList, int numDevs, int **foundEntities)
1569
This function finds matches between ISA cards that a
1570
driver supports and config file device sections. It is
1571
intended for use in the ChipProbe() function of drivers
1572
for ISA cards. devList and numDevs are typically those
1573
found from calling xf86MatchDevice(), and represent the
1574
active config file device sections relevant to the
1575
driver. ISAchipsets is a table that provides a mapping
1576
between the driver's internal chipset tokens and the
1577
resource classes. FindIsaDevice is a driver-provided
1578
function that probes the hardware and returns the chipset
1579
token corresponding to what was detected, and -1 if noth-
1582
If the config file device section contains a chipset
1583
entry, then it is checked against the chipsets list.
1584
When no chipset entry is present, the FindIsaDevice func-
1585
tion is called instead.
1587
Entity index numbers for confirmed matches are returned
1588
as an array via foundEntities. The chipset token and
1589
device section for each match are found in the EntityIn-
1590
foRec referenced by the indices.
1592
The function return value is the number of confirmed
1593
matches. A return value of -1 indicates an internal
1594
error. The returned foundEntities array should be freed
1595
by the driver with xfree() when it is no longer needed in
1596
cases where the return value is greater than zero.
1598
These two helper functions make use of several core functions that are avail-
1599
able at the driver level:
1601
Bool xf86ParsePciBusString(const char *busID, int *bus,
1603
int *device, int *func)
1605
Takes a BusID string, and if it is in the correct format,
1606
returns the PCI bus, device, func values that it indi-
1607
cates. The format of the string is expected to be
1608
"PCI:bus:device:func" where each of `bus', `device' and
1609
`func' are decimal integers. The ":func" part may be
1610
omitted, and the func value assumed to be zero, but this
1611
isn't encouraged. The "PCI" prefix may also be omitted.
1612
The prefix "AGP" is currently equivalent to the "PCI"
1613
prefix. If the string isn't a valid PCI BusID, the
1614
return value is FALSE.
1616
Bool xf86ComparePciBusString(const char *busID, int bus,
1618
int device, int func)
1620
Compares a BusID string with PCI bus, device, func val-
1621
ues. If they match TRUE is returned, and FALSE if they
1624
Bool xf86ParseIsaBusString(const char *busID)
1626
Compares a BusID string with the ISA bus ID string ("ISA"
1627
or "ISA:"). If they match TRUE is returned, and FALSE if
1630
Bool xf86CheckPciSlot(int bus, int device, int func)
1632
Checks if the PCI slot bus:device:func has been claimed.
1633
If so, it returns FALSE, and otherwise TRUE.
1635
int xf86ClaimPciSlot(int bus, int device, int func, DriverPtr drvp,
1637
int chipset, GDevPtr dev, Bool active)
1639
This function is used to claim a PCI slot, allocate the
1640
associated entity record and initialise their data struc-
1641
tures. The return value is the index of the newly allo-
1642
cated entity record, or -1 if the claim fails. This
1643
function should always succeed if xf86CheckPciSlot()
1644
returned TRUE for the same PCI slot.
1646
Bool xf86IsPrimaryPci(void)
1648
This function returns TRUE if the primary card is a PCI
1649
device, and FALSE otherwise.
1651
int xf86ClaimIsaSlot(DriverPtr drvp, int chipset,
1653
GDevPtr dev, Bool active)
1655
This allocates an entity record entity and initialise the
1656
data structures. The return value is the index of the
1657
newly allocated entity record.
1659
Bool xf86IsPrimaryIsa(void)
1661
This function returns TRUE if the primary card is an ISA
1662
(non-PCI) device, and FALSE otherwise.
1664
Two helper functions are provided to aid configuring entities:
1666
ScrnInfoPtr xf86ConfigPciEntity(ScrnInfoPtr pScrn,
1668
int scrnFlag, int entityIndex,
1670
PciChipsets *p_chip,
1672
resList res, EntityProc init,
1674
EntityProc enter, EntityProc leave,
1678
ScrnInfoPtr xf86ConfigIsaEntity(ScrnInfoPtr pScrn,
1680
int scrnFlag, int entityIndex,
1682
IsaChipsets *i_chip,
1684
resList res, EntityProc init,
1686
EntityProc enter, EntityProc leave,
1690
These functions are used to register the non-relocatable
1691
resources for an entity, and the optional entity-specific
1692
Init, Enter and Leave functions. Usually the list of
1693
fixed resources is obtained from the Isa/PciChipsets
1694
lists. However an additional list of resources may be
1695
passed. Generally this is not required. For active
1696
entities a ScrnInfoRec is allocated if the pScrn argument
1697
is NULL. The return value is TRUE when successful. The
1698
init, enter, leave functions are defined as follows:
1700
typedef void (*EntityProc)(int entityIndex,
1704
They are passed the entity index and a pointer to a pri-
1705
vate scratch area. This can be set up during Probe() and
1706
its address can be passed to xf86ConfigIsaEntity() and
1707
xf86ConfigPciEntity() as the last argument.
1709
These two helper functions make use of several core functions that are avail-
1710
able at the driver level:
1712
void xf86ClaimFixedResources(resList list, int entityIndex)
1714
This function registers the non-relocatable resources
1715
which cannot be disabled and which therefore would cause
1716
the server to fail immediately if they were found to con-
1717
flict. It also records non-relocatable but sharable
1718
resources for processing after the Probe() phase.
1720
Bool xf86SetEntityFuncs(int entityIndex, EntityProc init,
1722
EntityProc enter, EntityProc leave, pointer)
1724
This function registers with an entity the init, enter,
1725
leave functions along with the pointer to their private
1728
void xf86AddEntityToScreen(ScrnInfoPtr pScrn, int entityIndex)
1730
This function associates the entity referenced by enti-
1731
tyIndex with the screen.
1735
During this phase the remaining resources should be registered. PreInit()
1736
should call xf86GetEntityInfo() to obtain a pointer to an EntityInfoRec for
1737
each entity it is able to drive and check if any resource are listed in its
1738
resources field. If resources registered in the Probe phase have been
1739
rejected in the post-Probe phase (resources is non-NULL), then the driver
1740
should decide if it can continue without using these or if it should fail.
1742
EntityInfoPtr xf86GetEntityInfo(int entityIndex)
1744
This function returns a pointer to the EntityInfoRec ref-
1745
erenced by entityIndex. The returned EntityInfoRec
1746
should be freed with xfree() when no longer needed.
1748
Several functions are provided to simplify resource registration:
1750
Bool xf86IsEntityPrimary(int entityIndex)
1752
This function returns TRUE if the entity referenced by
1753
entityIndex is the primary display device (i.e., the one
1754
initialised at boot time and used in text mode).
1755
Bool xf86IsScreenPrimary(int scrnIndex)
1757
This function returns TRUE if the primary entity is reg-
1758
istered with the screen referenced by scrnIndex.
1760
pciVideoPtr xf86GetPciInfoForEntity(int entityIndex)
1762
This function returns a pointer to the pciVideoRec for
1763
the specified entity. If the entity is not a PCI device,
1766
The primary function for registration of resources is:
1768
resPtr xf86RegisterResources(int entityIndex, resList list,
1772
This function tries to register the resources in list.
1773
If list is NULL it tries to determine the resources auto-
1774
matically. This only works for entities that provide a
1775
generic way to read out the resource ranges they decode.
1776
So far this is only the case for PCI devices. By default
1777
the PCI resources are registered as shared (ResShared) if
1778
the driver wants to set a different access type it can do
1779
so by specifying the access flags in the third argument.
1780
A value of 0 means to use the default settings. If for
1781
any reason the resource broker is not able to register
1782
some of the requested resources the function will return
1783
a pointer to a list of the failed ones. In this case the
1784
driver may be able to move the resource to different
1785
locations. In case of PCI bus entities this is done by
1786
passing the list of failed resources to xf86ReallocateP-
1787
ciResources(). When the registration succeeds, the
1788
return value is NULL.
1790
resPtr xf86ReallocatePciResources(int entityIndex, resPtr pRes)
1792
This function takes a list of PCI resources that need to
1793
be reallocated and returns NULL when all relocations are
1794
successful. xf86RegisterResources() should be called
1795
again to register the relocated resources with the bro-
1796
ker. If the reallocation fails, a list of the resources
1797
that could not be relocated is returned.
1799
Two functions are provided to obtain a resource range of a given type:
1801
resRange xf86GetBlock(long type, memType size,
1803
memType window_start, memType window_end,
1805
memType align_mask, resPtr avoid)
1807
This function tries to find a block range of size size
1808
and type type in a window bound by window_start and win-
1809
dow_end with the alignment specified in align_mask.
1810
Optionally a list of resource ranges which should be
1811
avoided within the window can be supplied. On failure a
1812
zero-length range of type ResEnd will be returned.
1814
resRange xf86GetSparse(long type, memType fixed_bits,
1816
memType decode_mask, memType address_mask,
1820
This function is like the previous one, but attempts to
1821
find a sparse range instead of a block range. Here three
1822
values have to be specified: the address_mask which marks
1823
all bits of the mask part of the address, the decode_mask
1824
which masks out the bits which are hardcoded and are
1825
therefore not available for relocation and the values of
1826
the fixed bits. The function tries to find a base that
1827
satisfies the given condition. If the function fails it
1828
will return a zero range of type ResEnd. Optionally it
1829
might be passed a list of resource ranges to avoid.
1831
Some PCI devices are broken in the sense that they return invalid size infor-
1832
mation for a certain resource. In this case the driver can supply the cor-
1833
rect size and make sure that the resource range allocated for the card is
1834
large enough to hold the address range decoded by the card. The function
1835
xf86FixPciResource() can be used to do this:
1837
Bool xf86FixPciResource(int entityIndex, unsigned int prt,
1839
CARD32 alignment, long type)
1841
This function fixes a PCI resource allocation. The prt
1842
parameter contains the number of the PCI base register
1843
that needs to be fixed (0-5, and 6 for the BIOS base reg-
1844
ister). The size is specified by the alignment. Since
1845
PCI resources need to span an integral range of size 2^n,
1846
the alignment also specifies the number of addresses that
1847
will be decoded. If the driver specifies a type mask it
1848
can override the default type for PCI resources which is
1849
ResShared. The resource broker needs to know that to
1850
find a matching resource range. This function should be
1851
called before calling xf86RegisterResources(). The
1852
return value is TRUE when the function succeeds.
1854
Bool xf86CheckPciMemBase(pciVideoPtr pPci, memType base)
1856
This function checks that the memory base address speci-
1857
fied matches one of the PCI base address register values
1858
for the given PCI device. This is mostly used to check
1859
that an externally provided base address (e.g., from a
1860
config file) matches an actual value allocated to a
1863
The driver may replace the generic access control functions for an entity.
1864
This is done with the xf86SetAccessFuncs():
1866
void xf86SetAccessFuncs(EntityInfoPtr pEnt,
1868
xf86SetAccessFuncPtr funcs,
1870
xf86SetAccessFuncPtr oldFuncs)
1877
xf86AccessPtr io_mem;
1878
} xf86SetAccessFuncRec, *xf86SetAccessFuncPtr;
1880
The driver can pass three functions: one for I/O access,
1881
one for memory access and one for combined memory and I/O
1882
access. If the memory access and combined access func-
1883
tions are identical the common level assumes that the
1884
memory access cannot be controlled independently of I/O
1885
access, if the I/O access function and the combined
1886
access functions are the same it is assumed that I/O can
1887
not be controlled independently. If memory and I/O have
1888
to be controlled together all three values should be the
1889
same. If a non NULL value is passed as third argument it
1890
is interpreted as an address where to store the old
1891
access record. If the third argument is NULL it will be
1892
assumed that the generic access should be enabled before
1893
replacing the access functions. Otherwise it will be
1894
disabled. The driver may enable them itself using the
1895
returned values. It should do this from its replacement
1896
access functions as the generic access may be disabled by
1897
the common level on certain occasions. If replacement
1898
functions are specified they must control all resources
1899
of the specific type registered for the entity.
1901
To find out if a specific resource range conflicts with another resource the
1902
xf86ChkConflict() function may be used:
1904
memType xf86ChkConflict(resRange *rgp, int entityIndex)
1906
This function checks if the resource range rgp of for the
1907
specified entity conflicts with with another resource.
1908
If a conflict is found, the address of the start of the
1909
conflict is returned. The return value is zero when
1910
there is no conflict.
1912
The OPERATING state properties of previously registered fixed resources can
1913
be set with the xf86SetOperatingState() function:
1915
resPtr xf86SetOperatingState(resList list, int entityIndex,
1919
This function is used to set the status of a resource
1920
during OPERATING state. list holds a list to which mask
1921
is to be applied. The parameter mask may have the value
1922
ResUnusedOpr and ResDisableOpr. The first one should be
1923
used if a resource isn't used by the driver during OPER-
1924
ATING state although it is decoded by the device, while
1925
the latter one indicates that the resource is not decoded
1926
during OPERATING state. Note that the resource ranges
1927
have to match those specified during registration. If a
1928
range has been specified starting at A and ending at B
1929
and suppose C us a value satisfying A < C < B one may not
1930
specify the resource range (A,B) by splitting it into two
1931
ranges (A,C) and (C,B).
1933
The following two functions are provided for special cases:
1935
void xf86RemoveEntityFromScreen(ScrnInfoPtr pScrn, int entityIndex)
1937
This function may be used to remove an entity from a
1938
screen. This only makes sense if a screen has more than
1939
one entity assigned or the screen is to be deleted. No
1940
test is made if the screen has any entities left.
1942
void xf86DeallocateResourcesForEntity(int entityIndex, long type)
1944
This function deallocates all resources of a given type
1945
registered for a certain entity from the resource broker
1948
9.3.3 ScreenInit Phase
1950
All that is required in this phase is to setup the RAC flags. Note that it
1951
is also permissible to set these flags up in the PreInit phase. The RAC
1952
flags are held in the racIoFlags and racMemFlags fields of the ScrnInfoRec
1953
for each screen. They specify which graphics operations might require the
1954
use of shared resources. This can be specified separately for memory and I/O
1955
resources. The available flags are defined in rac/xf86RAC.h. They are:
1959
for framebuffer operations (including hw acceleration)
1963
for Cursor operations (??? I'm not sure if we need this for SW cur-
1964
sor it depends on which level the sw cursor is drawn)
1968
for colormap operations
1972
for the call to ChipAdjustFrame()
1974
The flags are ORed together.
1976
10. Config file ``Option'' entries
1978
Option entries are permitted in most sections and subsections of the config
1979
file. There are two forms of option entries:
1981
Option "option-name"
1984
Option "option-name" "option-value"
1985
An option with an arbitrary value.
1987
The option entries are handled by the parser, and a list of the parsed
1988
options is included with each of the appropriate data structures that the
1989
drivers have access to. The data structures used to hold the option informa-
1990
tion are opaque to the driver, and a driver must not access the option data
1991
directly. Instead, the common layer provides a set of functions that may be
1992
used to access, check and manipulate the option data.
1994
First, the low level option handling functions. In most cases drivers would
1995
not need to use these directly.
1997
pointer xf86FindOption(pointer options, const char *name)
1999
Takes a list of options and an option name, and returns a
2000
handle for the first option entry in the list matching
2001
the name. Returns NULL if no match is found.
2002
char *xf86FindOptionValue(pointer options, const char *name)
2004
Takes a list of options and an option name, and returns
2005
the value associated with the first option entry in the
2006
list matching the name. If the matching option has no
2007
value, an empty string ("") is returned. Returns NULL if
2010
void xf86MarkOptionUsed(pointer option)
2012
Takes a handle for an option, and marks that option as
2015
void xf86MarkOptionUsedByName(pointer options, const char *name)
2017
Takes a list of options and an option name and marks the
2018
first option entry in the list matching the name as used.
2020
Next, the higher level functions that most drivers would use.
2022
void xf86CollectOptions(ScrnInfoPtr pScrn, pointer extraOpts)
2024
Collect the options from each of the config file sections
2025
used by the screen (pScrn) and return the merged list as
2026
pScrn->options. This function requires that pScrn->conf-
2027
Screen, pScrn->display, pScrn->monitor, pScrn->numEnti-
2028
ties, and pScrn->entityList are initialised. extraOpts
2029
may optionally be set to an additional list of options to
2030
be combined with the others. The order of precedence for
2031
options is extraOpts, display, confScreen, monitor,
2034
void xf86ProcessOptions(int scrnIndex, pointer options,
2036
OptionInfoPtr optinfo)
2038
Processes a list of options according to the information
2039
in the array of OptionInfoRecs (optinfo). The resulting
2040
information is stored in the value fields of the appro-
2041
priate optinfo entries. The found fields are set to TRUE
2042
when an option with a value of the correct type if found,
2043
and FALSE otherwise. The type field is used to determine
2044
the expected value type for each option. Each option in
2045
the list of options for which there is a name match (but
2046
not necessarily a value type match) is marked as used.
2047
Warning messages are printed when option values don't
2048
match the types specified in the optinfo data.
2050
NOTE: If this function is called before a driver's screen
2051
number is known (e.g., from the ChipProbe() function) a
2052
scrnIndex value of -1 should be used.
2054
NOTE 2: Given that this function stores into the Option-
2055
InfoRecs pointed to by optinfo, the caller should ensure
2056
the OptionInfoRecs are (re-)initialised before the call,
2057
especially if the caller expects to use the predefined
2058
option values as defaults.
2060
The OptionInfoRec is defined as follows:
2078
OPTV_STRING, /* a non-empty string */
2079
OPTV_ANYSTR, /* Any string, including an empty one */
2094
OptionValueType type;
2097
} OptionInfoRec, *OptionInfoPtr;
2099
OPTV_FREQ can be used for options values that are fre-
2100
quencies. These values are a floating point number with
2101
an optional unit name appended. The unit name can be one
2102
of "Hz", "kHz", "k", "MHz", "M". The multiplier associ-
2103
ated with the unit is stored in freq.units, and the
2104
scaled frequency is stored in freq.freq. When no unit is
2105
specified, freq.units is set to 0, and freq.freq is
2108
Typical usage is to setup an array of OptionInfoRecs with
2109
all fields initialised. The value and found fields get
2110
set by xf86ProcessOptions(). For cases where the value
2111
parsing is more complex, the driver should specify
2112
OPTV_STRING, and parse the string itself. An example of
2113
using this option handling is included in the Sample
2114
Driver (section 20., page 1) section.
2116
void xf86ShowUnusedOptions(int scrnIndex, pointer options)
2118
Prints out warning messages for each option in the list
2119
of options that isn't marked as used. This is intended
2120
to show options that the driver hasn't recognised. It
2121
would normally be called near the end of the Chip-
2122
ScreenInit() function, but only when serverGenera-
2125
OptionInfoPtr xf86TokenToOptinfo(const OptionInfoRec *table,
2129
Returns a pointer to the OptionInfoRec in table with a
2130
token field matching token. Returns NULL if no match is
2133
Bool xf86IsOptionSet(const OptionInfoRec *table, int token)
2135
Returns the found field of the OptionInfoRec in table
2136
with a token field matching token. This can be used for
2137
options of all types. Note that for options of type
2138
OPTV_BOOLEAN, it isn't sufficient to check this to deter-
2139
mine the value of the option. Returns FALSE if no match
2142
char *xf86GetOptValString(const OptionInfoRec *table, int token)
2144
Returns the value.str field of the OptionInfoRec in table
2145
with a token field matching token. Returns NULL if no
2148
Bool xf86GetOptValInteger(const OptionInfoRec *table, int token,
2152
Returns via *value the value.num field of the OptionIn-
2153
foRec in table with a token field matching token. *value
2154
is only changed when a match is found so it can be safely
2155
initialised with a default prior to calling this func-
2156
tion. The function return value is as for xf86IsOption-
2159
Bool xf86GetOptValULong(const OptionInfoRec *table, int token,
2161
unsigned long *value)
2163
Like xf86GetOptValInteger(), except the value is treated
2164
as an unsigned long.
2166
Bool xf86GetOptValReal(const OptionInfoRec *table, int token,
2170
Like xf86GetOptValInteger(), except that value.realnum is
2173
Bool xf86GetOptValFreq(const OptionInfoRec *table, int token,
2175
OptFreqUnits expectedUnits, double *value)
2177
Like xf86GetOptValInteger(), except that the value.freq
2178
data is returned. The frequency value is scaled to the
2179
units indicated by expectedUnits. The scaling is exact
2180
when the units were specified explicitly in the option's
2181
value. Otherwise, the expectedUnits field is used as a
2182
hint when doing the scaling. In this case, values larger
2183
than 1000 are assumed to have be specified in the next
2184
smallest units. For example, if the Option value is
2185
"10000" and expectedUnits is OPTUNITS_MHZ, the value
2188
Bool xf86GetOptValBool(const OptionInfoRec *table, int token, Bool
2191
This function is used to check boolean options
2192
(OPTV_BOOLEAN). If the function return value is FALSE,
2193
it means the option wasn't set. Otherwise *value is set
2194
to the boolean value indicated by the option's value. No
2195
option value is interpreted as TRUE. Option values mean-
2196
ing TRUE are "1", "yes", "on", "true", and option values
2197
meaning FALSE are "0", "no", "off", "false". Option
2198
names both with the "no" prefix in their names, and with
2199
that prefix removed are also checked and handled in the
2200
obvious way. *value is not changed when the option isn't
2201
present. It should normally be set to a default value
2202
before calling this function.
2204
Bool xf86ReturnOptValBool(const OptionInfoRec *table, int token,
2207
This function is used to check boolean options
2208
(OPTV_BOOLEAN). If the option is set, its value is
2209
returned. If the options is not set, the default value
2210
specified by def is returned. The option interpretation
2211
is the same as for xf86GetOptValBool().
2213
int xf86NameCmp(const char *s1, const char *s2)
2215
This function should be used when comparing strings from
2216
the config file with expected values. It works like str-
2217
cmp(), but is not case sensitive and space, tab, and `_'
2218
characters are ignored in the comparison. The use of
2219
this function isn't restricted to parsing option values.
2220
It may be used anywhere where this functionality
2223
11. Modules, Drivers, Include Files and Interface Issues
2225
NOTE: this section is incomplete.
2229
The following include files are typically required by video drivers:
2231
All drivers should include these:
2241
Wherever inb/outb (and related things) are used the following
2246
Note: in drivers, this must be included after "xf86_ansic.h".
2248
Drivers that need to access PCI vendor/device definitions need
2253
Drivers that need to access the PCI config space need this:
2257
Drivers that initialise a SW cursor need this:
2261
All drivers implementing backing store need this:
2265
All drivers using the mi colourmap code need this:
2269
If a driver uses the vgahw module, it needs this:
2273
Drivers supporting VGA or Hercules monochrome screens need:
2277
Drivers supporting VGA or EGC 16-colour screens need:
2281
Drivers using cfb need:
2289
Drivers supporting bpp 16, 24 or 32 with cfb need one or more of:
2297
If a driver uses XAA, it needs these:
2303
If a driver uses the fb manager, it needs this:
2307
Non-driver modules should include "xf86_ansic.h" to get the correct wrapping
2308
of ANSI C/libc functions.
2310
All modules must NOT include any system include files, or the following:
2320
In addition, "xf86_libc.h" must not be included explicitly. It is included
2321
implicitly by "xf86_ansic.h".
2323
12. Offscreen Memory Manager
2325
Management of offscreen video memory may be handled by the XFree86 frame-
2326
buffer manager. Once the offscreen memory manager is running, drivers or
2327
extensions may allocate, free or resize areas of offscreen video memory using
2328
the following functions (definitions taken from xf86fbman.h):
2330
typedef struct _FBArea {
2334
void (*MoveAreaCallback)(struct _FBArea*, struct _FBArea*)
2335
void (*RemoveAreaCallback)(struct _FBArea*)
2336
DevUnion devPrivate;
2337
} FBArea, *FBAreaPtr;
2339
typedef void (*MoveAreaCallbackProcPtr)(FBAreaPtr from, FBAreaPtr to)
2340
typedef void (*RemoveAreaCallbackProcPtr)(FBAreaPtr)
2342
FBAreaPtr xf86AllocateOffscreenArea (
2344
int width, int height,
2346
MoveAreaCallbackProcPtr MoveAreaCallback,
2347
RemoveAreaCallbackProcPtr RemoveAreaCallback,
2351
void xf86FreeOffscreenArea (FBAreaPtr area)
2353
Bool xf86ResizeOffscreenArea (
2360
Bool xf86FBManagerRunning(ScreenPtr pScreen)
2362
can be used by an extension to check if the driver has initialized the memory
2363
manager. The manager is not available if this returns FALSE and the func-
2364
tions above will all fail.
2366
xf86AllocateOffscreenArea() can be used to request a rectangle of dimensions
2367
width x height (in pixels) from unused offscreen memory. granularity speci-
2368
fies that the leftmost edge of the rectangle must lie on some multiple of
2369
granularity pixels. A granularity of zero means the same thing as a granu-
2370
larity of one - no alignment preference. A MoveAreaCallback can be provided
2371
to notify the requester when the offscreen area is moved. If no MoveArea-
2372
Callback is supplied then the area is considered to be immovable. The priv-
2373
Data field will be stored in the manager's internal structure for that allo-
2374
cated area and will be returned to the requester in the FBArea passed via the
2375
MoveAreaCallback. An optional RemoveAreaCallback is provided. If the driver
2376
provides this it indicates that the area should be allocated with a lower
2377
priority. Such an area may be removed when a higher priority request (one
2378
that doesn't have a RemoveAreaCallback) is made. When this function is
2379
called, the driver will have an opportunity to do whatever cleanup it needs
2380
to do to deal with the loss of the area, but it must finish its cleanup
2381
before the function exits since the offscreen memory manager will free the
2382
area immediately after.
2384
xf86AllocateOffscreenArea() returns NULL if it was unable to allocate the
2385
requested area. When no longer needed, areas should be freed with xf86Free-
2388
xf86ResizeOffscreenArea() resizes an existing FBArea. xf86ResizeOff-
2389
screenArea() returns TRUE if the resize was successful. If xf86ResizeOff-
2390
screenArea() returns FALSE, the original FBArea is left unmodified. Resizing
2391
an area maintains the area's original granularity, devPrivate, and MoveArea-
2392
Callback. xf86ResizeOffscreenArea() has considerably less overhead than
2393
freeing the old area then reallocating the new size, so it should be used
2398
Bool xf86QueryLargestOffscreenArea(
2402
int *width, int *height,
2412
is provided to query the width and height of the largest single FBArea allo-
2413
catable given a particular priority. preferences can be one of the following
2414
to indicate whether width, height or area should be considered when determin-
2415
ing which is the largest single FBArea available.
2417
FAVOR_AREA_THEN_WIDTH
2419
FAVOR_AREA_THEN_HEIGHT
2421
FAVOR_WIDTH_THEN_AREA
2423
FAVOR_HEIGHT_THEN_AREA
2425
priority is one of the following:
2429
Return the largest block available without stealing any-
2430
one else's space. This corresponds to the priority of
2431
allocating a FBArea when a RemoveAreaCallback is pro-
2436
Return the largest block available if it is acceptable to
2437
steal a lower priority area from someone. This corre-
2438
sponds to the priority of allocating a FBArea without
2439
providing a RemoveAreaCallback.
2443
Return the largest block available if all FBAreas that
2444
aren't locked down were expunged from memory first. This
2445
corresponds to any allocation made directly after a call
2446
to xf86PurgeUnlockedOffscreenAreas().
2450
Bool xf86PurgeUnlockedOffscreenAreas(ScreenPtr pScreen)
2452
is provided as an extreme method to free up offscreen memory. This will
2453
remove all removable FBArea allocations.
2455
Initialization of the XFree86 framebuffer manager is done via
2457
Bool xf86InitFBManager(ScreenPtr pScreen, BoxPtr FullBox)
2459
FullBox represents the area of the framebuffer that the manager is allowed to
2460
manage. This is typically a box with a width of pScrn->displayWidth and a
2461
height of as many lines as can be fit within the total video memory, however,
2462
the driver can reserve areas at the extremities by passing a smaller area to
2465
xf86InitFBManager() must be called before XAA is initialized since XAA uses
2466
the manager for it's pixmap cache.
2468
An alternative function is provided to allow the driver to initialize the
2469
framebuffer manager with a Region rather than a box.
2471
Bool xf86InitFBManagerRegion(ScreenPtr pScreen,
2473
RegionPtr FullRegion)
2475
xf86InitFBManagerRegion(), unlike xf86InitFBManager(), does not remove the
2476
area used for the visible screen so that area should not be included in the
2477
region passed to the function. xf86InitFBManagerRegion() is useful when non-
2478
contiguous areas are available to be managed, and is required when multiple
2479
framebuffers are stored in video memory (as in the case where an overlay of a
2480
different depth is stored as a second framebuffer in offscreen memory).
2482
13. Colormap Handling
2484
A generic colormap handling layer is provided within the XFree86 common
2485
layer. This layer takes care of most of the details, and only requires a
2486
function from the driver that loads the hardware palette when required. To
2487
use the colormap layer, a driver calls the xf86HandleColormaps() function.
2489
Bool xf86HandleColormaps(ScreenPtr pScreen, int maxColors,
2491
int sigRGBbits, LoadPaletteFuncPtr loadPalette,
2493
SetOverscanFuncPtr setOverscan, unsigned int flags)
2495
This function must be called after the default colormap
2496
has been initialised. The pScrn->gamma field must also
2497
be initialised, preferably by calling xf86SetGamma().
2498
maxColors is the number of entries in the palette.
2499
sigRGBbits is the size in bits of each color component in
2500
the DAC's palette. loadPalette is a driver-provided
2501
function for loading a colormap into the hardware, and is
2502
described below. setOverscan is an optional function
2503
that may be provided when the overscan color is an index
2504
from the standard LUT and when it needs to be adjusted to
2505
keep it as close to black as possible. The setOverscan
2506
function programs the overscan index. It shouldn't nor-
2507
mally be used for depths other than 8. setOverscan
2508
should be set to NULL when it isn't needed. flags may be
2509
set to the following (which may be ORed together):
2511
CMAP_PALETTED_TRUECOLOR
2513
the TrueColor visual is paletted and is just a
2514
special case of DirectColor. This flag is only
2517
CMAP_RELOAD_ON_MODE_SWITCH
2519
reload the colormap automatically after mode
2520
switches. This is useful for when the driver
2521
is resetting the hardware during mode switches
2522
and corrupting or erasing the hardware palette.
2524
CMAP_LOAD_EVEN_IF_OFFSCREEN
2526
reload the colormap even if the screen is
2527
switched out of the server's VC. The palette
2528
is not reloaded when the screen is switched
2529
back in, nor after mode switches. This is use-
2530
ful when the driver needs to keep track of
2533
The colormap layer normally reloads the palette after VT
2534
enters so it is not necessary for the driver to save and
2535
restore the palette when switching VTs. The driver must,
2536
however, still save the initial palette during server
2537
start up and restore it during server exit.
2539
void LoadPalette(ScrnInfoPtr pScrn, int numColors, int *indices,
2541
LOCO *colors, VisualPtr pVisual)
2543
LoadPalette() is a driver-provided function for loading a
2544
colormap into hardware. colors is the array of RGB val-
2545
ues that represent the full colormap. indices is a list
2546
of index values into the colors array. These indices
2547
indicate the entries that need to be updated. numColors
2548
is the number of the indices to be updated.
2550
void SetOverscan(ScrnInfoPtr pScrn, int overscan)
2552
SetOverscan() is a driver-provided function for program-
2553
ming the overscan index. As described above, it is nor-
2554
mally only appropriate for LUT modes where all colormap
2555
entries are available for the display, but where one of
2556
them is also used for the overscan (typically 8bpp for
2557
VGA compatible LUTs). It isn't required in cases where
2558
the overscan area is never visible.
2562
Support code for the DPMS extension is included in the XFree86 common layer.
2563
This code provides an interface between the main extension code, and a means
2564
for drivers to initialise DPMS when they support it. One function is avail-
2565
able to drivers to do this initialisation, and it is always available, even
2566
when the DPMS extension is not supported by the core server (in which case it
2567
returns a failure result).
2569
Bool xf86DPMSInit(ScreenPtr pScreen, DPMSSetProcPtr set, int flags)
2571
This function registers a driver's DPMS level programming
2572
function set. It also checks pScrn->options for the
2573
"dpms" option, and when present marks DPMS as being
2574
enabled for that screen. The set function is called
2575
whenever the DPMS level changes, and is used to program
2576
the requested level. flags is currently not used, and
2577
should be 0. If the initialisation fails for any reason,
2578
including when there is no DPMS support in the core
2579
server, the function returns FALSE.
2581
Drivers that implement DPMS support must provide the following function, that
2582
gets called when the DPMS level is changed:
2584
void ChipDPMSSet(ScrnInfoPtr pScrn, int level, int flags)
2586
Program the DPMS level specified by level. Valid values
2587
of level are DPMSModeOn, DPMSModeStandby, DPMSModeSus-
2588
pend, DPMSModeOff. These values are defined in "exten-
2593
Drivers can support the XFree86 Direct Graphics Architecture (DGA) by filling
2594
out a structure of function pointers and a list of modes and passing them to
2597
Bool DGAInit(ScreenPtr pScreen, DGAFunctionPtr funcs,
2599
DGAModePtr modes, int num)
2601
/** The DGAModeRec **/
2605
DisplayModePtr mode;
2611
int bytesPerScanline;
2615
unsigned long red_mask;
2616
unsigned long green_mask;
2617
unsigned long blue_mask;
2626
unsigned char *address;
2629
} DGAModeRec, *DGAModePtr;
2633
Can be ignored. The DGA DDX will assign these
2638
A pointer to the DisplayModeRec for this mode.
2642
The following flags are defined and may be OR'd
2645
DGA_CONCURRENT_ACCESS
2647
Indicates that the driver supports
2648
concurrent graphics accelerator and
2649
linear framebuffer access.
2657
Indicates that the driver supports
2658
the FillRect, BlitRect or BlitTran-
2659
sRect functions in this mode.
2661
DGA_PIXMAP_AVAILABLE
2663
Indicates that Xlib may be used on
2664
the framebuffer. This flag will usu-
2665
ally be set unless the driver wishes
2666
to prohibit this for some reason.
2672
Indicates that these are interlaced
2673
or double scan modes.
2679
These are the dimensions of the linear frame-
2680
buffer accessible by the client.
2686
These are the dimensions of the area of the
2687
framebuffer accessible by the graphics acceler-
2692
Pitch of the framebuffer in bytes.
2696
Usually the same as pScrn->imageByteOrder.
2700
The depth of the framebuffer in this mode.
2704
The number of bits per pixel in this mode.
2712
The RGB masks for this mode, if applicable.
2718
Dimensions of the visible part of the frame-
2719
buffer. Usually mode->HDisplay and mode->VDis-
2726
The granularity of x and y viewport positions
2727
that the driver supports in this mode.
2733
The maximum viewport position supported by the
2734
driver in this mode.
2738
The following may be OR'd together:
2742
The driver supports immediate view-
2747
The driver supports viewport changes
2752
The offset into the linear framebuffer that
2753
corresponds to pixel (0,0) for this mode.
2757
The virtual address of the framebuffer as
2758
mapped by the driver. This is needed when
2759
DGA_PIXMAP_AVAILABLE is set.
2761
/** The DGAFunctionRec **/
2764
Bool (*OpenFramebuffer)(
2767
unsigned char **mem,
2772
void (*CloseFramebuffer)(ScrnInfoPtr pScrn);
2773
Bool (*SetMode)(ScrnInfoPtr pScrn, DGAModePtr pMode);
2774
void (*SetViewport)(ScrnInfoPtr pScrn, int x, int y, int flags);
2775
int (*GetViewport)(ScrnInfoPtr pScrn);
2776
void (*Sync)(ScrnInfoPtr);
2779
int x, int y, int w, int h,
2788
void (*BlitTransRect)(
2795
} DGAFunctionRec, *DGAFunctionPtr;
2797
Bool OpenFramebuffer (pScrn, name, mem, size, offset, extra)
2799
OpenFramebuffer() should pass the client everything it
2800
needs to know to be able to open the framebuffer. These
2801
parameters are OS specific and their meanings are to be
2802
interpreted by an OS specific client library.
2806
The name of the device to open or NULL if there
2807
is no special device to open. A NULL name
2808
tells the client that it should open whatever
2809
device one would usually open to access physi-
2814
The physical address of the start of the frame-
2819
The size of the framebuffer in bytes.
2823
Any offset into the device, if applicable.
2827
Any additional information that the client may
2828
need. Currently, only the DGA_NEED_ROOT flag
2831
void CloseFramebuffer (pScrn)
2833
CloseFramebuffer() merely informs the driver (if it even
2834
cares) that client no longer needs to access the frame-
2835
buffer directly. This function is optional.
2837
Bool SetMode (pScrn, pMode)
2839
SetMode() tells the driver to initialize the mode passed
2840
to it. If pMode is NULL, then the driver should restore
2841
the original pre-DGA mode.
2843
void SetViewport (pScrn, x, y, flags)
2845
SetViewport() tells the driver to make the upper left-
2846
hand corner of the visible screen correspond to coordi-
2847
nate (x,y) on the framebuffer. Flags currently defined
2852
The viewport change should occur immediately.
2856
The viewport change should occur at the verti-
2857
cal retrace, but this function should return
2860
The (x,y) locations will be passed as the client speci-
2861
fied them, however, the driver is expected to round these
2862
locations down to the next supported location as speci-
2863
fied by the xViewportStep and yViewportStep for the cur-
2866
int GetViewport (pScrn)
2868
GetViewport() gets the current page flip status. Set
2869
bits in the returned int correspond to viewport change
2870
requests still pending. For instance, set bit zero if
2871
the last SetViewport request is still pending, bit one if
2872
the one before that is still pending, etc.
2876
This function should ensure that any graphics accelerator
2877
operations have finished. This function should not
2878
return until the graphics accelerator is idle.
2880
void FillRect (pScrn, x, y, w, h, color)
2882
This optional function should fill a rectangle w � h
2883
located at (x,y) in the given color.
2885
void BlitRect (pScrn, srcx, srcy, w, h, dstx, dsty)
2887
This optional function should copy an area w � h located
2888
at (srcx,srcy) to location (dstx,dsty). This function
2889
will need to handle copy directions as appropriate.
2891
void BlitTransRect (pScrn, srcx, srcy, w, h, dstx, dsty, color)
2893
This optional function is the same as BlitRect except
2894
that pixels in the source corresponding to the color key
2895
color should be skipped.
2897
16. The XFree86 X Video Extension (Xv) Device Dependent Layer
2899
XFree86 offers the X Video Extension which allows clients to treat video as
2900
any another primitive and ``Put'' video into drawables. By default, the
2901
extension reports no video adaptors as being available since the DDX layer
2902
has not been initialized. The driver can initialize the DDX layer by filling
2903
out one or more XF86VideoAdaptorRecs as described later in this document and
2904
passing a list of XF86VideoAdaptorPtr pointers to the following function:
2906
Bool xf86XVScreenInit(
2910
XF86VideoAdaptorPtr *adaptPtrs,
2914
After doing this, the extension will report video adaptors as being avail-
2915
able, providing the data in their respective XF86VideoAdaptorRecs was valid.
2916
xf86XVScreenInit() copies data from the structure passed to it so the driver
2917
may free it after the initialization. At the moment, the DDX only supports
2918
rendering into Window drawables. Pixmap rendering will be supported after a
2919
sufficient survey of suitable hardware is completed.
2921
The XF86VideoAdaptorRec:
2928
XF86VideoEncodingPtr pEncodings;
2930
XF86VideoFormatPtr pFormats;
2932
DevUnion *pPortPrivates;
2934
XF86AttributePtr pAttributes;
2936
XF86ImagePtr pImages;
2937
PutVideoFuncPtr PutVideo;
2938
PutStillFuncPtr PutStill;
2939
GetVideoFuncPtr GetVideo;
2940
GetStillFuncPtr GetStill;
2941
StopVideoFuncPtr StopVideo;
2942
SetPortAttributeFuncPtr SetPortAttribute;
2943
GetPortAttributeFuncPtr GetPortAttribute;
2944
QueryBestSizeFuncPtr QueryBestSize;
2945
PutImageFuncPtr PutImage;
2946
QueryImageAttributesFuncPtr QueryImageAttributes;
2947
} XF86VideoAdaptorRec, *XF86VideoAdaptorPtr;
2949
Each adaptor will have its own XF86VideoAdaptorRec. The fields are
2954
This can be any of the following flags OR'd together.
2956
XvInputMask XvOutputMask
2958
These refer to the target drawable and are sim-
2959
ilar to a Window's class. XvInputMask indicates
2960
that the adaptor can put video into a drawable.
2961
XvOutputMask indicates that the adaptor can get
2962
video from a drawable.
2964
XvVideoMask XvStillMask XvImageMask
2966
These indicate that the adaptor supports video,
2967
still or image primitives respectively.
2969
XvWindowMask XvPixmapMask
2971
These indicate the types of drawables the adap-
2972
tor is capable of rendering into. At the
2973
moment, Pixmap rendering is not supported and
2974
the XvPixmapMask flag is ignored.
2978
Currently, the following flags are defined:
2982
This indicates that the video adaptor does not
2983
support clipping. The driver will never
2984
receive ``Put'' requests where less than the
2985
entire area determined by drw_x, drw_y, drw_w
2986
and drw_h is visible. This flag does not apply
2987
to ``Get'' requests. Hardware that is inca-
2988
pable of clipping ``Gets'' may punt or get the
2989
extents of the clipping region passed to it.
2991
VIDEO_INVERT_CLIPLIST
2993
This indicates that the video driver requires
2994
the clip list to contain the regions which are
2995
obscured rather than the regions which are are
2998
VIDEO_OVERLAID_STILLS
3000
Implementing PutStill for hardware that does
3001
video as an overlay can be awkward since it's
3002
unclear how long to leave the video up for.
3003
When this flag is set, StopVideo will be called
3004
whenever the destination gets clipped or moved
3005
so that the still can be left up until then.
3007
VIDEO_OVERLAID_IMAGES
3009
Same as VIDEO_OVERLAID_STILLS but for images.
3011
VIDEO_CLIP_TO_VIEWPORT
3013
Indicates that the clip region passed to the
3014
driver functions should be clipped to the visi-
3015
ble portion of the screen in the case where the
3016
viewport is smaller than the virtual desktop.
3020
The name of the adaptor.
3026
The number of encodings the adaptor is capable of and
3027
pointer to the XF86VideoEncodingRec array. The
3028
XF86VideoEncodingRec is described later on. For drivers
3029
that only support XvImages there should be an encoding
3030
named "XV_IMAGE" and the width and height should specify
3031
the maximum size source image supported.
3037
The number of formats the adaptor is capable of and
3038
pointer to the XF86VideoFormatRec array. The XF86Video-
3039
FormatRec is described later on.
3045
The number of ports is the number of separate data
3046
streams which the adaptor can handle simultaneously. If
3047
you have more than one port, the adaptor is expected to
3048
be able to render into more than one window at a time.
3049
pPortPrivates is an array of pointers or ints - one for
3050
each port. A port's private data will be passed to the
3051
driver any time the port is requested to do something
3052
like put the video or stop the video. In the case where
3053
there may be many ports, this enables the driver to know
3054
which port the request is intended for. Most commonly,
3055
this will contain a pointer to the data structure con-
3056
taining information about the port. In Xv, all ports on
3057
a particular adaptor are expected to be identical in
3058
their functionality.
3064
The number of attributes recognized by the adaptor and a
3065
pointer to the array of XF86AttributeRecs. The
3066
XF86AttributeRec is described later on.
3072
The number of XF86ImageRecs supported by the adaptor and
3073
a pointer to the array of XF86ImageRecs. The XF86ImageRec
3074
is described later on.
3076
PutVideo PutStill GetVideo GetStill StopVideo SetPortAttribute Get-
3077
PortAttribute QueryBestSize PutImage QueryImageAttributes
3079
These functions define the DDX->driver interface. In
3080
each case, the pointer data is passed to the driver.
3081
This is the port private for that port as described
3082
above. All fields are required except under the follow-
3085
1. PutVideo, PutStill and the image routines PutImage
3086
and QueryImageAttributes are not required when the
3087
adaptor type does not contain XvInputMask.
3089
2. GetVideo and GetStill are not required when the
3090
adaptor type does not contain XvOutputMask.
3092
3. GetVideo and PutVideo are not required when the
3093
adaptor type does not contain XvVideoMask.
3095
4. GetStill and PutStill are not required when the
3096
adaptor type does not contain XvStillMask.
3098
5. PutImage and QueryImageAttributes are not required
3099
when the adaptor type does not contain XvImageMask.
3101
With the exception of QueryImageAttributes, these func-
3102
tions should return Success if the operation was com-
3103
pleted successfully. They can return XvBadAlloc other-
3104
wise. QueryImageAttributes returns the size of the XvIm-
3107
If the VIDEO_NO_CLIPPING flag is set, the clipBoxes may
3108
be ignored by the driver. ClipBoxes is an X-Y banded
3109
region identical to those used throughout the server.
3110
The clipBoxes represent the visible portions of the area
3111
determined by drw_x, drw_y, drw_w and drw_h in the
3112
Get/Put function. The boxes are in screen coordinates,
3113
are guaranteed not to overlap and an empty region will
3114
never be passed. If the driver has specified
3115
VIDEO_INVERT_CLIPLIST, clipBoxes will indicate the areas
3116
of the primitive which are obscured rather than the areas
3119
typedef int (* PutVideoFuncPtr)( ScrnInfoPtr pScrn,
3121
short vid_x, short vid_y, short drw_x, short drw_y,
3123
short vid_w, short vid_h, short drw_w, short drw_h,
3125
RegionPtr clipBoxes, pointer data )
3127
This indicates that the driver should take a subsection
3128
vid_w by vid_h at location (vid_x,vid_y) from the video
3129
stream and direct it into the rectangle drw_w by drw_h at
3130
location (drw_x,drw_y) on the screen, scaling as neces-
3131
sary. Due to the large variations in capabilities of the
3132
various hardware expected to be used with this extension,
3133
it is not expected that all hardware will be able to do
3134
this exactly as described. In that case the driver
3135
should just do ``the best it can,'' scaling as closely to
3136
the target rectangle as it can without rendering outside
3137
of it. In the worst case, the driver can opt to just not
3140
typedef int (* PutStillFuncPtr)( ScrnInfoPtr pScrn,
3142
short vid_x, short vid_y, short drw_x, short drw_y,
3144
short vid_w, short vid_h, short drw_w, short drw_h,
3146
RegionPtr clipBoxes, pointer data )
3148
This is same as PutVideo except that the driver should
3149
place only one frame from the stream on the screen.
3151
typedef int (* GetVideoFuncPtr)( ScrnInfoPtr pScrn,
3153
short vid_x, short vid_y, short drw_x, short drw_y,
3155
short vid_w, short vid_h, short drw_w, short drw_h,
3157
RegionPtr clipBoxes, pointer data )
3159
This is same as PutVideo except that the driver gets
3160
video from the screen and outputs it. The driver should
3161
do the best it can to get the requested dimensions cor-
3162
rect without reading from an area larger than requested.
3164
typedef int (* GetStillFuncPtr)( ScrnInfoPtr pScrn,
3166
short vid_x, short vid_y, short drw_x, short drw_y,
3168
short vid_w, short vid_h, short drw_w, short drw_h,
3170
RegionPtr clipBoxes, pointer data )
3172
This is the same as GetVideo except that the driver
3173
should place only one frame from the screen into the out-
3176
typedef void (* StopVideoFuncPtr)(ScrnInfoPtr pScrn,
3178
pointer data, Bool cleanup)
3180
This indicates the driver should stop displaying the
3181
video. This is used to stop both input and output video.
3182
The cleanup field indicates that the video is being
3183
stopped because the client requested it to stop or
3184
because the server is exiting the current VT. In that
3185
case the driver should deallocate any offscreen memory
3186
areas (if there are any) being used to put the video to
3187
the screen. If cleanup is not set, the video is being
3188
stopped temporarily due to clipping or moving of the win-
3189
dow, etc... and video will likely be restarted soon so
3190
the driver should not deallocate any offscreen areas
3191
associated with that port.
3193
typedef int (* SetPortAttributeFuncPtr)(ScrnInfoPtr pScrn,
3195
Atom attribute,INT32 value, pointer data)
3197
typedef int (* GetPortAttributeFuncPtr)(ScrnInfoPtr pScrn,
3199
Atom attribute,INT32 *value, pointer data)
3201
A port may have particular attributes such as hue, satu-
3202
ration, brightness or contrast. Xv clients set and get
3203
these attribute values by sending attribute strings
3204
(Atoms) to the server. Such requests end up at these
3205
driver functions. It is recommended that the driver pro-
3206
vide at least the following attributes mentioned in the
3207
Xv client library docs:
3219
but the driver may recognize as many atoms as it wishes.
3220
If a requested attribute is unknown by the driver it
3221
should return BadMatch. XV_ENCODING is the attribute
3222
intended to let the client specify which video encoding
3223
the particular port should be using (see the description
3224
of XF86VideoEncodingRec below). If the requested encod-
3225
ing is unsupported, the driver should return XvBadEncod-
3226
ing. If the value lies outside the advertised range Bad-
3227
Value may be returned. Success should be returned other-
3230
typedef void (* QueryBestSizeFuncPtr)(ScrnInfoPtr pScrn,
3232
Bool motion, short vid_w, short vid_h,
3234
short drw_w, short drw_h,
3236
unsigned int *p_w, unsigned int *p_h, pointer data)
3238
QueryBestSize provides the client with a way to query
3239
what the destination dimensions would end up being if
3240
they were to request that an area vid_w by vid_h from the
3241
video stream be scaled to rectangle of drw_w by drw_h on
3242
the screen. Since it is not expected that all hardware
3243
will be able to get the target dimensions exactly, it is
3244
important that the driver provide this function.
3246
typedef int (* PutImageFuncPtr)( ScrnInfoPtr pScrn,
3248
short src_x, short src_y, short drw_x, short drw_y,
3250
short src_w, short src_h, short drw_w, short drw_h,
3252
int image, char *buf, short width, short height,
3254
Bool sync, RegionPtr clipBoxes, pointer data )
3256
This is similar to PutStill except that the source of the
3257
video is not a port but the data stored in a system mem-
3258
ory buffer at buf. The data is in the format indicated
3259
by the image descriptor and represents a source of size
3260
width by height. If sync is TRUE the driver should not
3261
return from this function until it is through reading the
3262
data from buf. Returning when sync is TRUE indicates
3263
that it is safe for the data at buf to be replaced,
3266
typedef int (* QueryImageAttributesFuncPtr)( ScrnInfoPtr pScrn,
3268
int image, short *width, short *height,
3270
int *pitches, int *offsets)
3272
This function is called to let the driver specify how
3273
data for a particular image of size width by height
3274
should be stored. Sometimes only the size and corrected
3275
width and height are needed. In that case pitches and
3276
offsets are NULL. The size of the memory required for
3277
the image is returned by this function. The width and
3278
height of the requested image can be altered by the
3279
driver to reflect format limitations (such as component
3280
sampling periods that are larger than one). If pitches
3281
and offsets are not NULL, these will be arrays with as
3282
many elements in them as there are planes in the image
3283
format. The driver should specify the pitch (in bytes)
3284
of each scanline in the particular plane as well as the
3285
offset to that plane (in bytes) from the beginning of the
3288
The XF86VideoEncodingRec:
3293
unsigned short width, height;
3295
} XF86VideoEncodingRec, *XF86VideoEncodingPtr;
3297
The XF86VideoEncodingRec specifies what encodings the adaptor can
3298
support. Most of this data is just informational and for the
3299
client's benefit, and is what will be reported by XvQueryEncodings.
3300
The id field is expected to be a unique identifier to allow the
3301
client to request a certain encoding via the XV_ENCODING attribute
3304
The XF86VideoFormatRec:
3309
} XF86VideoFormatRec, *XF86VideoFormatPtr;
3311
This specifies what visuals the video is viewable in. depth is the
3312
depth of the visual (not bpp). class is the visual class such as
3313
TrueColor, DirectColor or PseudoColor. Initialization of an adap-
3314
tor will fail if none of the visuals on that screen are supported.
3316
The XF86AttributeRec:
3323
} XF86AttributeListRec, *XF86AttributeListPtr;
3324
Each adaptor may have an array of these advertising the attributes
3325
for its ports. Currently defined flags are XvGettable and XvSet-
3326
table which may be OR'd together indicating that attribute is
3327
``gettable'' or ``settable'' by the client. The min and max field
3328
specify the valid range for the value. Name is a text string
3329
describing the attribute by name.
3342
/* for RGB formats */
3344
unsigned int red_mask;
3345
unsigned int green_mask;
3346
unsigned int blue_mask;
3348
/* for YUV formats */
3349
unsigned int y_sample_bits;
3350
unsigned int u_sample_bits;
3351
unsigned int v_sample_bits;
3352
unsigned int horz_y_period;
3353
unsigned int horz_u_period;
3354
unsigned int horz_v_period;
3355
unsigned int vert_y_period;
3356
unsigned int vert_u_period;
3357
unsigned int vert_v_period;
3358
char component_order[32];
3360
} XF86ImageRec, *XF86ImagePtr;
3362
XF86ImageRec describes how video source data is laid out in memory.
3363
The fields are as follows:
3367
This is a unique descriptor for the format. It is often
3368
good to set this value to the FOURCC for the format when
3373
This is XvRGB or XvYUV.
3377
This is LSBFirst or MSBFirst.
3381
This is the Globally Unique IDentifier for the format.
3382
When not applicable, all characters should be NULL.
3386
The number of bits taken up (but not necessarily used) by
3387
each pixel. Note that for some planar formats which have
3388
fractional bits per pixel (such as IF09) this number may
3393
This is XvPlanar or XvPacked.
3397
The number of planes in planar formats. This should be
3398
set to one for packed formats.
3402
The significant bits per pixel in RGB formats (analgous
3403
to the depth of a pixmap format).
3405
red_mask green_mask blue_mask
3407
The red, green and blue bitmasks for packed RGB formats.
3409
y_sample_bits u_sample_bits v_sample_bits
3411
The y, u and v sample sizes (in bits).
3413
horz_y_period horz_u_period horz_v_period
3415
The y, u and v sampling periods in the horizontal direc-
3418
vert_y_period vert_u_period vert_v_period
3420
The y, u and v sampling periods in the vertical direc-
3425
Uppercase ascii characters representing the order that
3426
samples are stored within packed formats. For planar
3427
formats this represents the ordering of the planes.
3428
Unused characters in the 32 byte string should be set to
3433
This is XvTopToBottom or XvBottomToTop.
3435
Since some formats (particular some planar YUV formats) may not be
3436
completely defined by the parameters above, the guid, when avail-
3437
able, should provide the most accurate description of the format.
3441
This section describes the interfaces to the module loader. The loader
3442
interfaces can be divided into two groups: those that are only available to
3443
the XFree86 common layer, and those that are also available to modules.
3445
17.1 Loader Overview
3447
The loader is capable of loading modules in a range of object formats, and
3448
knowledge of these formats is built in to the loader. Knowledge of new
3449
object formats can be added to the loader in a straightforward manner. This
3450
makes it possible to provide OS-independent modules (for a given CPU archi-
3451
tecture type). In addition to this, the loader can load modules via the OS-
3452
provided dlopen(3) service where available. Such modules are not platform
3453
independent, and the semantics of dlopen() on most systems results in signif-
3454
icant limitations in the use of modules of this type. Support for dlopen()
3455
modules in the loader is primarily for experimental and development purposes.
3457
Symbols exported by the loader (on behalf of the core X server) to modules
3458
are determined at compile time. Only those symbols explicitly exported are
3459
available to modules. All external symbols of loaded modules are exported to
3460
other modules, and to the core X server. The loader can be requested to
3461
check for unresolved symbols at any time, and the action to be taken for
3462
unresolved symbols can be controlled by the caller of the loader. Typically
3463
the caller identifies which symbols can safely remain unresolved and which
3466
NOTE: Now that ISO-C allows pointers to functions and pointers to data to
3467
have different internal representations, some of the following interfaces
3468
will need to be revisited.
3470
17.2 Semi-private Loader Interface
3472
The following is the semi-private loader interface that is available to the
3473
XFree86 common layer.
3475
void LoaderInit(void)
3477
The LoaderInit() function initialises the loader, and it
3478
must be called once before calling any other loader func-
3479
tions. This function initialises the tables of exported
3480
symbols, and anything else that might need to be ini-
3483
void LoaderSetPath(const char *path)
3485
The LoaderSetPath() function initialises a default module
3486
search path. This must be called if calls to other func-
3487
tions are to be made without explicitly specifying a mod-
3488
ule search path. The search path path must be a string
3489
of one or more comma separated absolute paths. Modules
3490
are expected to be located below these paths, possibly in
3491
subdirectories of these paths.
3493
pointer LoadModule(const char *module, const char *path,
3495
const char **subdirlist, const char **patternlist,
3497
pointer options, const XF86ModReqInfo * modreq,
3499
int *errmaj, int *errmin)
3501
The LoadModule() function loads the module called module.
3502
The return value is a module handle, and may be used in
3503
future calls to the loader that require a reference to a
3504
loaded module. The module name module is normally the
3505
module's canonical name, which doesn't contain any direc-
3506
tory path information, or any object/library file pre-
3507
fixes of suffixes. Currently a full pathname and/or
3508
filename is also accepted. This might change. The other
3513
An optional comma-separated list of module
3514
search paths. When NULL, the default search
3519
An optional NULL terminated list of subdirecto-
3520
ries to search. When NULL, the default built-
3521
in list is used (refer to stdSubdirs in load-
3522
mod.c). The default list is also substituted
3523
for entries in subdirlist with the value
3524
DEFAULT_LIST. This makes is possible to aug-
3525
ment the default list instead of replacing it.
3526
Subdir elements must be relative, and must not
3527
contain "..". If any violate this requirement,
3532
An optional NULL terminated list of POSIX regu-
3533
lar expressions used to connect module file-
3534
names with canonical module names. Each regex
3535
should contain exactly one subexpression that
3536
corresponds to the canonical module name. When
3537
NULL, the default built-in list is used (refer
3538
to stdPatterns in loadmod.c). The default list
3539
is also substituted for entries in patternlist
3540
with the value DEFAULT_LIST. This makes it
3541
possible to augment the default list instead of
3546
An optional parameter that is passed to the
3547
newly loaded module's SetupProc function (if it
3548
has one). This argument is normally a NULL
3549
terminated list of Options, and must be inter-
3550
preted that way by modules loaded directly by
3551
the XFree86 common layer. However, it may be
3552
used for application-specific parameter passing
3553
in other situations.
3555
When loading ``external'' modules (modules that
3556
don't have the standard entry point, for exam-
3557
ple a special shared library) the options
3558
parameter can be set to EXTERN_MODULE to tell
3559
the loader not to reject the module when it
3560
doesn't find the standard entry point.
3564
An optional XF86ModReqInfo* containing ver-
3565
sion/ABI/vendor information to requirements to
3566
check the newly loaded module against. The
3567
main purpose of this is to allow the loader to
3568
verify that a module of the correct type/ver-
3569
sion before running its SetupProc function.
3570
The XF86ModReqInfo struct is defined as fol-
3574
CARD8 majorversion; /* MAJOR_UNSPEC */
3575
CARD8 minorversion; /* MINOR_UNSPEC */
3576
CARD16 patchlevel; /* PATCH_UNSPEC */
3577
const char * abiclass; /* ABI_CLASS_NONE */
3578
CARD32 abiversion; /* ABI_VERS_UNSPEC */
3579
const char * moduleclass; /* MOD_CLASS_NONE */
3582
The information here is compared against the
3583
equivalent information in the module's XF86Mod-
3584
uleVersionInfo record (which is described
3585
below). The values in comments above indicate
3586
``don't care'' settings for each of the fields.
3587
The comparisons made are as follows:
3591
Must match the module's majorversion
3596
The module's minor version must be no
3597
less than this value. This compari-
3598
son is only made if majorversion is
3599
specified and matches.
3603
The module's patchlevel must be no
3604
less than this value. This compari-
3605
son is only made if minorversion is
3606
specified and matches.
3610
String must match the module's abi-
3615
Must be consistent with the module's
3616
abiversion (major equal, minor no
3621
String must match the module's mod-
3626
An optional pointer to a variable holding the
3627
major part or the error code. When provided,
3628
*errmaj is filled in when LoadModule() fails.
3632
Like errmaj, but for the minor part of the
3635
void UnloadModule(pointer mod)
3637
This function unloads the module referred to by the han-
3638
dle mod. All child modules are also unloaded recur-
3639
sively. This function must not be used to directly
3640
unload modules that are child modules (i.e., those that
3641
have been loaded with the LoadSubModule() described
3644
17.3 Module Requirements
3646
Modules must provide information about themselves to the loader, and may
3647
optionally provide entry points for "setup" and "teardown" functions (those
3648
two functions are referred to here as SetupProc and TearDownProc).
3650
The module information is contained in the XF86ModuleVersionInfo struct,
3651
which is defined as follows:
3654
const char * modname; /* name of module, e.g. "foo" */
3655
const char * vendor; /* vendor specific string */
3656
CARD32 _modinfo1_; /* constant MODINFOSTRING1/2 to find */
3657
CARD32 _modinfo2_; /* infoarea with a binary editor/sign tool */
3658
CARD32 xf86version; /* contains XF86_VERSION_CURRENT */
3659
CARD8 majorversion; /* module-specific major version */
3660
CARD8 minorversion; /* module-specific minor version */
3661
CARD16 patchlevel; /* module-specific patch level */
3662
const char * abiclass; /* ABI class that the module uses */
3663
CARD32 abiversion; /* ABI version */
3664
const char * moduleclass; /* module class */
3665
CARD32 checksum[4]; /* contains a digital signature of the */
3666
/* version info structure */
3667
} XF86ModuleVersionInfo;
3669
The fields are used as follows:
3673
The module's name. This field is currently only for
3674
informational purposes, but the loader may be modified in
3675
future to require it to match the module's canonical
3680
The module vendor. This field is for informational pur-
3685
This field holds the first part of a signature that can
3686
be used to locate this structure in the binary. It
3687
should always be initialised to MODINFOSTRING1.
3691
This field holds the second part of a signature that can
3692
be used to locate this structure in the binary. It
3693
should always be initialised to MODINFOSTRING2.
3697
The XFree86 version against which the module was com-
3698
piled. This is mostly for informational/diagnostic pur-
3699
poses. It should be initialised to XF86_VERSION_CURRENT,
3700
which is defined in xf86Version.h.
3704
The module-specific major version. For modules where
3705
this version is used for more than simply informational
3706
purposes, the major version should only change (be incre-
3707
mented) when ABI incompatibilities are introduced, or ABI
3708
components are removed.
3712
The module-specific minor version. For modules where
3713
this version is used for more than simply informational
3714
purposes, the minor version should only change (be incre-
3715
mented) when ABI additions are made in a backward compat-
3716
ible way. It should be reset to zero when the major ver-
3721
The module-specific patch level. The patch level should
3722
increase with new revisions of the module where there are
3723
no ABI changes, and it should be reset to zero when the
3724
minor version is increased.
3728
The ABI class that the module requires. The class is
3729
specified as a string for easy extensibility. It should
3730
indicate which (if any) of the X server's built-in ABI
3731
classes that the module relies on, or a third-party ABI
3732
if appropriate. Built-in ABI classes currently defined
3739
only requires the ANSI C interfaces
3743
requires the video driver ABI
3747
requires the XInput driver ABI
3751
requires the extension module ABI
3755
requires the font module ABI
3759
The version of abiclass that the module requires. The
3760
version consists of major and minor components. The
3761
major version must match and the minor version must be no
3762
newer than that provided by the server or parent module.
3763
Version identifiers for the built-in classes currently
3767
ABI_VIDEODRV_VERSION
3771
ABI_EXTENSION_VERSION
3777
This is similar to the abiclass field, except that it
3778
defines the type of module rather than the ABI it
3779
requires. For example, although all video drivers
3780
require the video driver ABI, not all modules that
3781
require the video driver ABI are video drivers. This
3782
distinction can be made with the moduleclass. Currently
3783
pre-defined module classes are:
3799
The module version information, and the optional SetupProc and TearDownProc
3800
entry points are found by the loader by locating a data object in the module
3801
called "modnameModuleData", where "modname" is the canonical name of the mod-
3802
ule. Modules must contain such a data object, and it must be declared with
3803
global scope, be compile-time initialised, and is of the following type:
3806
XF86ModuleVersionInfo * vers;
3807
ModuleSetupProc setup;
3808
ModuleTearDownProc teardown;
3811
The vers parameter must be initialised to a pointer to a correctly ini-
3812
tialised XF86ModuleVersionInfo struct. The other two parameter are optional,
3813
and should be initialised to NULL when not required. The other parameters
3816
typedef pointer (*ModuleSetupProc)(pointer, pointer, int *, int *)
3818
typedef void (*ModuleTearDownProc)(pointer)
3820
pointer SetupProc(pointer module, pointer options,
3822
int *errmaj, int *errmin)
3824
When defined, this function is called by the loader after
3825
successfully loading a module. module is a handle for
3826
the newly loaded module, and maybe used by the SetupProc
3827
if it calls other loader functions that require a refer-
3828
ence to it. The remaining arguments are those that were
3829
passed to the LoadModule() (or LoadSubModule()), and are
3830
described above. When the SetupProc is successful it must
3831
return a non-NULL value. The loader checks this, and if
3832
it is NULL it unloads the module and reports the failure
3833
to the caller of LoadModule(). If the SetupProc does
3834
things that need to be undone when the module is
3835
unloaded, it should define a TearDownProc, and return a
3836
pointer that the TearDownProc can use to undo what has
3839
When a module is loaded multiple times, the SetupProc is
3840
called once for each time it is loaded.
3842
void TearDownProc(pointer tearDownData)
3844
When defined, this function is called when the loader
3845
unloads a module. The tearDownData parameter is the
3846
return value of the SetupProc() that was called when the
3847
module was loaded. The purpose of this function is to
3848
clean up before the module is unloaded (for example, by
3849
freeing allocated resources).
3851
17.4 Public Loader Interface
3853
The following is the Loader interface that is available to any part of the
3854
server, and may also be used from within modules.
3856
pointer LoadSubModule(pointer parent, const char *module,
3858
const char **subdirlist, const char **patternlist,
3860
pointer options, const XF86ModReqInfo * modreq,
3862
int *errmaj, int *errmin)
3864
This function is like the LoadModule() function described
3865
above, except that the module loaded is registered as a
3866
child of the calling module. The parent parameter is the
3867
calling module's handle. Modules loaded with this func-
3868
tion are automatically unloaded when the parent module is
3869
unloaded. The other difference is that the path parame-
3870
ter may not be specified. The module search path used
3871
for modules loaded with this function is the default
3872
search path as initialised with LoaderSetPath().
3874
void UnloadSubModule(pointer module)
3876
This function unloads the module with handle module. If
3877
that module itself has children, they are also unloaded.
3878
It is like UnloadModule(), except that it is safe to use
3879
for unloading child modules.
3881
pointer LoaderSymbol(const char *symbol)
3883
This function returns the address of the symbol with name
3884
symbol. This may be used to locate a module entry point
3887
char **LoaderlistDirs(const char **subdirlist,
3889
const char **patternlist)
3891
This function returns a NULL terminated list of canonical
3892
modules names for modules found in the default module
3893
search path. The subdirlist and patternlist parameters
3894
are as described above, and can be used to control the
3895
locations and names that are searched. If no modules are
3896
found, the return value is NULL. The returned list
3897
should be freed by calling LoaderFreeDirList() when it is
3900
void LoaderFreeDirList(char **list)
3902
This function frees a module list created by Loaderlist-
3905
void LoaderReqSymLists(const char **list0, ...)
3907
This function allows the registration of required symbols
3908
with the loader. It is normally used by a caller of
3909
LoadSubModule(). If any symbols registered in this way
3910
are found to be unresolved when LoaderCheckUnresolved()
3911
is called then LoaderCheckUnresolved() will report a
3912
failure. The function takes one or more NULL terminated
3913
lists of symbols. The end of the argument list is indi-
3914
cated by a NULL argument.
3916
void LoaderReqSymbols(const char *sym0, ...)
3918
This function is like LoaderReqSymLists() except that its
3919
arguments are symbols rather than lists of symbols. This
3920
function is more convenient when single functions are to
3921
be registered, especially when the single function might
3922
depend on runtime factors. The end of the argument list
3923
is indicated by a NULL argument.
3925
void LoaderRefSymLists(const char **list0, ...)
3927
This function allows the registration of possibly unre-
3928
solved symbols with the loader. When LoaderCheckUnre-
3929
solved() is run it won't generate warnings for symbols
3930
registered in this way unless they were also registered
3931
as required symbols. The function takes one or more NULL
3932
terminated lists of symbols. The end of the argument
3933
list is indicated by a NULL argument.
3935
void LoaderRefSymbols(const char *sym0, ...)
3937
This function is like LoaderRefSymLists() except that its
3938
arguments are symbols rather than lists of symbols. This
3939
function is more convenient when single functions are to
3940
be registered, especially when the single function might
3941
depend on runtime factors. The end of the argument list
3942
is indicated by a NULL argument.
3944
int LoaderCheckUnresolved(int delayflag)
3946
This function checks for unresolved symbols. It gener-
3947
ates warnings for unresolved symbols that have not been
3948
registered with LoaderRefSymLists(), and maps them to a
3949
dummy function. This behaviour may change in future. If
3950
unresolved symbols are found that have been registered
3951
with LoaderReqSymLists() or LoaderReqSymbols() then this
3952
function returns a non-zero value. If none of these sym-
3953
bols are unresolved the return value is zero, indicating
3956
The delayflag parameter should normally be set to
3959
LoaderErrorMsg(const char *name, const char *modname,
3961
int errmaj, int errmin)
3963
This function prints an error message that includes the
3964
text ``Failed to load module'', the module name modname,
3965
a message specific to the errmaj value, and the value if
3966
errmin. If name is non-NULL, it is printed as an identi-
3967
fying prefix to the message (followed by a `:').
3969
17.5 Special Registration Functions
3971
The loader contains some functions for registering some classes of modules.
3972
These may be moved out of the loader at some point.
3974
void LoadExtension(ExtensionModule *ext)
3976
This registers the entry points for the extension identi-
3977
fied by ext. The ExtensionModule struct is defined as:
3980
InitExtension initFunc;
3983
InitExtension setupFunc;
3986
void LoadFont(FontModule *font)
3988
This registers the entry points for the font rasteriser
3989
module identified by font. The FontModule struct is
3998
18. Helper Functions
4000
This section describe ``helper'' functions that video driver might find use-
4001
ful. While video drivers are not required to use any of these to be consid-
4002
ered ``compliant'', the use of appropriate helpers is strongly encouraged to
4003
improve the consistency of driver behaviour.
4005
18.1 Functions for printing messages
4007
ErrorF(const char *format, ...)
4009
This is the basic function for writing to the error log
4010
(typically stderr and/or a log file). Video drivers
4011
should usually avoid using this directly in favour of the
4012
more specialised functions described below. This func-
4013
tion is useful for printing messages while debugging a
4016
FatalError(const char *format, ...)
4018
This prints a message and causes the Xserver to abort.
4019
It should rarely be used within a video driver, as most
4020
error conditions should be flagged by the return values
4021
of the driver functions. This allows the higher layers
4022
to decide how to proceed. In rare cases, this can be
4023
used within a driver if a fatal unexpected condition is
4026
xf86ErrorF(const char *format, ...)
4028
This is like ErrorF(), except that the message is only
4029
printed when the Xserver's verbosity level is set to the
4030
default (1) or higher. It means that the messages are
4031
not printed when the server is started with the -quiet
4032
flag. Typically this function would only be used for
4033
continuing messages started with one of the more spe-
4034
cialised functions described below.
4036
xf86ErrorFVerb(int verb, const char *format, ...)
4038
Like xf86ErrorF(), except the minimum verbosity level for
4039
which the message is to be printed is given explicitly.
4040
Passing a verb value of zero means the message is always
4041
printed. A value higher than 1 can be used for informa-
4042
tion would normally not be needed, but which might be
4043
useful when diagnosing problems.
4045
xf86Msg(MessageType type, const char *format, ...)
4047
This is like xf86ErrorF(), except that the message is
4048
prefixed with a marker determined by the value of type.
4049
The marker is used to indicate the type of message (warn-
4050
ing, error, probed value, config value, etc). Note the
4051
xf86Verbose value is ignored for messages of type
4054
The marker values are:
4062
Value was given in the config file.
4070
Value was given on the command line.
4086
Informational message.
4094
The message relates to functionality
4095
that is not yet implemented.
4097
xf86MsgVerb(MessageType type, int verb, const char *format, ...)
4099
Like xf86Msg(), but with the verbosity level given
4102
xf86DrvMsg(int scrnIndex, MessageType type, const char *format,
4105
This is like xf86Msg() except that the driver's name (the
4106
name field of the ScrnInfoRec) followed by the scrnIndex
4107
in parentheses is printed following the prefix. This
4108
should be used by video drivers in most cases as it
4109
clearly indicates which driver/screen the message is for.
4110
If scrnIndex is negative, this function behaves exactly
4112
NOTE: This function can only be used after the ScrnIn-
4113
foRec and its name field have been allocated. Normally,
4114
this means that it can not be used before the END of the
4115
ChipProbe() function. Prior to that, use xf86Msg(), pro-
4116
viding the driver's name explicitly. No screen number
4117
can be supplied at that point.
4119
xf86DrvMsgVerb(int scrnIndex, MessageType type, int verb,
4121
const char *format, ...)
4123
Like xf86DrvMsg(), but with the verbosity level given
4126
18.2 Functions for setting values based on command line and config file
4128
Bool xf86SetDepthBpp(ScrnInfoPtr scrp, int depth, int bpp,
4130
int fbbpp, int depth24flags)
4132
This function sets the depth, pixmapBPP and bitsPerPixel
4133
fields of the ScrnInfoRec. It also determines the
4134
defaults for display-wide attributes and pixmap formats
4135
the screen will support, and finds the Display subsection
4136
that matches the depth/bpp. This function should nor-
4137
mally be called very early from the ChipPreInit() func-
4139
It requires that the confScreen field of the ScrnInfoRec
4140
be initialised prior to calling it. This is done by the
4141
XFree86 common layer prior to calling ChipPreInit().
4143
The parameters passed are:
4147
driver's preferred default depth if no other is
4148
given. If zero, use the overall server
4153
Same, but for the pixmap bpp.
4157
Same, but for the framebuffer bpp.
4161
Flags that indicate the level of 24/32bpp sup-
4162
port and whether conversion between different
4163
framebuffer and pixmap formats is supported.
4164
The flags for this argument are defined as fol-
4165
lows, and multiple flags may be ORed together:
4168
No depth 24 formats supported
4172
24bpp framebuffer supported
4176
32bpp framebuffer supported
4178
SupportConvert24to32
4180
Can convert 24bpp pixmap to 32bpp fb
4182
SupportConvert32to24
4184
Can convert 32bpp pixmap to 24bpp fb
4188
Force 24bpp pixmap to 32bpp fb con-
4193
Force 32bpp pixmap to 24bpp fb con-
4196
It uses the command line, config file, and default values
4197
in the correct order of precedence to determine the depth
4198
and bpp values. It is up to the driver to check the
4199
results to see that it supports them. If not the Chip-
4200
PreInit() function should return FALSE.
4202
If only one of depth/bpp is given, the other is set to a
4203
reasonable (and consistent) default.
4205
If a driver finds that the initial depth24flags it uses
4206
later results in a fb format that requires more video
4207
memory than is available it may call this function a sec-
4208
ond time with a different depth24flags setting.
4210
On success, the return value is TRUE. On failure it
4211
prints an error message and returns FALSE.
4213
The following fields of the ScrnInfoRec are initialised
4216
depth, bitsPerPixel, display, imageByteOrder,
4217
bitmapScanlinePad, bitmapScanlineUnit, bitmap-
4218
BitOrder, numFormats, formats, fbFormat.
4220
void xf86PrintDepthBpp(scrnInfoPtr scrp)
4222
This function can be used to print out the depth and bpp
4223
settings. It should be called after the final call to
4226
Bool xf86SetWeight(ScrnInfoPtr scrp, rgb weight, rgb mask)
4228
This function sets the weight, mask, offset and rgbBits
4229
fields of the ScrnInfoRec. It would normally be called
4230
fairly early in the ChipPreInit() function for
4233
It requires that the depth and display fields of the
4234
ScrnInfoRec be initialised prior to calling it.
4235
The parameters passed are:
4239
driver's preferred default weight if no other
4240
is given. If zero, use the overall server
4247
It uses the command line, config file, and default values
4248
in the correct order of precedence to determine the
4249
weight value. It derives the mask and offset values from
4250
the weight and the defaults. It is up to the driver to
4251
check the results to see that it supports them. If not
4252
the ChipPreInit() function should return FALSE.
4254
On success, this function prints a message showing the
4255
weight values selected, and returns TRUE.
4257
On failure it prints an error message and returns FALSE.
4259
The following fields of the ScrnInfoRec are initialised
4262
weight, mask, offset.
4264
Bool xf86SetDefaultVisual(ScrnInfoPtr scrp, int visual)
4266
This function sets the defaultVisual field of the ScrnIn-
4267
foRec. It would normally be called fairly early from the
4268
ChipPreInit() function.
4270
It requires that the depth and display fields of the
4271
ScrnInfoRec be initialised prior to calling it.
4273
The parameters passed are:
4277
driver's preferred default visual if no other
4278
is given. If -1, use the overall server
4281
It uses the command line, config file, and default values
4282
in the correct order of precedence to determine the
4283
default visual value. It is up to the driver to check
4284
the result to see that it supports it. If not the Chip-
4285
PreInit() function should return FALSE.
4287
On success, this function prints a message showing the
4288
default visual selected, and returns TRUE.
4290
On failure it prints an error message and returns FALSE.
4292
Bool xf86SetGamma(ScrnInfoPtr scrp, Gamma gamma)
4294
This function sets the gamma field of the ScrnInfoRec.
4295
It would normally be called fairly early from the Chip-
4296
PreInit() function in cases where the driver supports
4299
It requires that the monitor field of the ScrnInfoRec be
4300
initialised prior to calling it.
4301
The parameters passed are:
4305
driver's preferred default gamma if no other is
4306
given. If zero (< 0.01), use the overall
4309
It uses the command line, config file, and default values
4310
in the correct order of precedence to determine the gamma
4311
value. It is up to the driver to check the results to
4312
see that it supports them. If not the ChipPreInit()
4313
function should return FALSE.
4315
On success, this function prints a message showing the
4316
gamma value selected, and returns TRUE.
4318
On failure it prints an error message and returns FALSE.
4320
void xf86SetDpi(ScrnInfoPtr pScrn, int x, int y)
4322
This function sets the xDpi and yDpi fields of the Scrn-
4323
InfoRec. The driver can specify preferred defaults by
4324
setting x and y to non-zero values. The -dpi command
4325
line option overrides all other settings. Otherwise, if
4326
the DisplaySize entry is present in the screen's Monitor
4327
config file section, it is used together with the virtual
4328
size to calculate the dpi values. This function should
4329
be called after all the mode resolution has been done.
4331
void xf86SetBlackWhitePixels(ScrnInfoPtr pScrn)
4333
This functions sets the blackPixel and whitePixel fields
4334
of the ScrnInfoRec according to whether or not the -flip-
4335
Pixels command line options is present.
4337
const char *xf86GetVisualName(int visual)
4339
Returns a printable string with the visual name matching
4340
the numerical visual class provided. If the value is
4341
outside the range of valid visual classes, NULL is
4344
18.3 Primary Mode functions
4346
The primary mode helper functions are those which would normally be used by a
4347
driver, unless it has unusual requirements which cannot be catered for the by
4350
int xf86ValidateModes(ScrnInfoPtr scrp, DisplayModePtr availModes,
4352
char **modeNames, ClockRangePtr clockRanges,
4354
int *linePitches, int minPitch, int maxPitch,
4356
int pitchInc, int minHeight, int maxHeight,
4358
int virtualX, int virtualY,
4360
unsigned long apertureSize,
4362
LookupModeFlags strategy)
4364
This function basically selects the set of modes to use
4365
based on those available and the various constraints. It
4366
also sets some other related parameters. It is normally
4367
called near the end of the ChipPreInit() function.
4369
The parameters passed to the function are:
4372
List of modes available for the monitor.
4376
List of mode names that the screen is request-
4381
A list of clock ranges allowed by the driver.
4382
Each range includes whether interlaced or mul-
4383
tiscan modes are supported for that range. See
4384
below for more on clockRanges.
4388
List of line pitches supported by the driver.
4389
This is optional and should be NULL when not
4394
Minimum line pitch supported by the driver.
4395
This must be supplied when linePitches is NULL,
4396
and is ignored otherwise.
4400
Maximum line pitch supported by the driver.
4401
This is required when minPitch is required.
4405
Granularity of horizontal pitch values as sup-
4406
ported by the chipset. This is expressed in
4407
bits. This must be supplied.
4411
minimum virtual height allowed. If zero, no
4416
maximum virtual height allowed. If zero, no
4421
If greater than zero, this is the virtual width
4422
value that will be used. Otherwise, the vir-
4423
tual width is chosen to be the smallest that
4424
can accommodate the modes selected.
4428
If greater than zero, this is the virtual
4429
height value that will be used. Otherwise, the
4430
virtual height is chosen to be the smallest
4431
that can accommodate the modes selected.
4435
The size (in bytes) of the aperture used to
4436
access video memory.
4440
The strategy to use when choosing from multiple
4441
modes with the same name. The options are:
4449
mode with best refresh rate
4451
LOOKUP_CLOSEST_CLOCK
4453
mode with closest matching clock
4457
first usable mode in list
4459
The following options can also be combined
4460
(OR'ed) with one of the above:
4466
LOOKUP_OPTIONAL_TOLERANCES
4468
Allow missing horizontal sync and/or
4469
vertical refresh ranges in the
4470
XF86Config Monitor section
4472
LOOKUP_OPTIONAL_TOLERANCES should only be spec-
4473
ified when the driver can ensure all modes it
4474
generates can sync on, or at least not damage,
4475
the monitor or digital flat panel. Horizontal
4476
sync and/or vertical refresh ranges specified
4477
by the user will still be honoured (and acted
4480
This function requires that the following fields of the
4481
ScrnInfoRec are initialised prior to calling it:
4485
List of discrete clocks (when non-programmable)
4489
Number of discrete clocks (when non-pro-
4494
Whether the clock is programmable or not
4498
Pointer to the applicable XF86Config monitor
4503
Format of the screen buffer
4507
total video memory size (in bytes)
4511
Maximum horizontal timing value allowed
4515
Maximum vertical timing value allowed
4519
Horizontal timing increment in pixels (defaults
4522
This function fills in the following ScrnInfoRec fields:
4526
A subset of the modes available to the monitor
4527
which are compatible with the driver.
4531
One mode entry for each of the requested modes,
4532
with the status field of each filled in to
4533
indicate if the mode has been accepted or not.
4534
This list of modes is a circular list.
4538
The resulting virtual width.
4542
The resulting virtual height.
4546
The resulting line pitch.
4550
Where the virtual size was determined from.
4552
The first stage of this function checks that the virtualX
4553
and virtualY values supplied (if greater than zero) are
4554
consistent with the line pitch and maxHeight limitations.
4555
If not, an error message is printed, and the return value
4558
The second stage sets up the mode pool, eliminating imme-
4559
diately any modes that exceed the driver's line pitch
4560
limits, and also the virtual width and height limits (if
4561
greater than zero). For each mode removed an informa-
4562
tional message is printed at verbosity level 2. If the
4563
mode pool ends up being empty, a warning message is
4564
printed, and the return value is 0.
4566
The final stage is to lookup each mode name, and fill in
4567
the remaining parameters. If an error condition is
4568
encountered, a message is printed, and the return value
4569
is -1. Otherwise, the return value is the number of
4570
valid modes found (0 if none are found).
4572
Even if the supplied mode names include duplicates, no
4573
two names will ever match the same mode. Furthermore, if
4574
the supplied mode names do not yield a valid mode
4575
(including the case where no names are passed at all),
4576
the function will continue looking through the mode pool
4577
until it finds a mode that survives all checks, or until
4578
the mode pool is exhausted.
4580
A message is only printed by this function when a funda-
4581
mental problem is found. It is intended that this func-
4582
tion may be called more than once if there is more than
4583
one set of constraints that the driver can work within.
4585
If this function returns -1, the ChipPreInit() function
4586
should return FALSE.
4588
clockRanges is a linked list of clock ranges allowed by
4589
the driver. If a mode doesn't fit in any of the defined
4590
clockRanges, it is rejected. The first clockRange that
4591
matches all requirements is used. This structure needs
4592
to be initialized to NULL when allocated.
4594
clockRanges contains the following fields:
4600
The lower and upper mode clock bounds for which
4601
the rest of the clockRange parameters apply.
4602
Since these are the mode clocks, they are not
4603
scaled with the ClockMulFactor and ClockDivFac-
4604
tor. It is up to the driver to adjust these
4605
values if they depend on the clock scaling fac-
4610
(not used yet) -1 for programmable clocks
4614
TRUE if interlacing is allowed for this range
4618
TRUE if doublescan or multiscan is allowed for
4625
Scaling factors that are applied to the mode
4626
clocks ONLY before selecting a clock index
4627
(when there is no programmable clock) or a Syn-
4628
thClock value. This is useful for drivers that
4629
support pixel multiplexing or that need to
4630
scale the clocks because of hardware restric-
4631
tions (like sending 24bpp data to an 8 bit RAM-
4632
DAC using a tripled clock).
4634
Note that these parameters describe what must
4635
be done to the mode clock to achieve the data
4636
transport clock between graphics controller and
4637
RAMDAC. For example for 2:1 pixel multiplex-
4638
ing, two pixels are sent to the RAMDAC on each
4639
clock. This allows the RAMDAC clock to be half
4640
of the actual pixel clock. Hence, ClockMulFac-
4641
tor=1 and ClockDivFactor=2. This means that
4642
the clock used for clock selection (ie, deter-
4643
mining the correct clock index from the list of
4644
discrete clocks) or for the SynthClock field in
4645
case of a programmable clock is: (mode->Clock
4646
* ClockMulFactor) / ClockDivFactor.
4650
This field is copied into the mode->PrivFlags
4651
field when this clockRange is selected by
4652
xf86ValidateModes(). It allows the driver to
4653
find out what clock range was selected, so it
4654
knows it needs to set up pixel multiplexing or
4655
any other range-dependent feature. This field
4656
is purely driver-defined: it may contain flag
4657
bits, an index or anything else (as long as it
4660
Note that the mode->SynthClock field is always filled in
4661
by xf86ValidateModes(): it will contain the ``data trans-
4662
port clock'', which is the clock that will have to be
4663
programmed in the chip when it has a programmable clock,
4664
or the clock that will be picked from the clocks list
4665
when it is not a programmable one. Thus:
4669
(mode->Clock * ClockMulFactor) / ClockDivFactor
4671
void xf86PruneDriverModes(ScrnInfoPtr scrp)
4673
This function deletes modes in the modes field of the
4674
ScrnInfoRec that have been marked as invalid. This is
4675
normally run after having run xf86ValidateModes() for the
4676
last time. For each mode that is deleted, a warning mes-
4677
sage is printed out indicating the reason for it being
4680
void xf86SetCrtcForModes(ScrnInfoPtr scrp, int adjustFlags)
4682
This function fills in the Crtc* fields for all the modes
4683
in the modes field of the ScrnInfoRec. The adjustFlags
4684
parameter determines how the vertical CRTC values are
4685
scaled for interlaced modes. They are halved if it is
4686
INTERLACE_HALVE_V. The vertical CRTC values are doubled
4687
for doublescan modes, and are further multiplied by the
4690
This function is normally called after calling
4691
xf86PruneDriverModes().
4693
void xf86PrintModes(ScrnInfoPtr scrp)
4695
This function prints out the virtual size setting, and
4696
the line pitch being used. It also prints out two lines
4697
for each mode being used. The first line includes the
4698
mode's pixel clock, horizontal sync rate, refresh rate,
4699
and whether it is interlaced, doublescanned and/or multi-
4700
scanned. The second line is the mode's Modeline.
4701
This function is normally called after calling
4702
xf86SetCrtcForModes().
4704
18.4 Secondary Mode functions
4706
The secondary mode helper functions are functions which are normally used by
4707
the primary mode helper functions, and which are not normally called directly
4708
by a driver. If a driver has unusual requirements and needs to do its own
4709
mode validation, it might be able to make use of some of these secondary mode
4712
int xf86GetNearestClock(ScrnInfoPtr scrp, int freq, Bool allowDiv2,
4716
This function returns the index of the closest clock to
4717
the frequency freq given (in kHz). It assumes that the
4718
number of clocks is greater than zero. It requires that
4719
the numClocks and clock fields of the ScrnInfoRec are
4720
initialised. The allowDiv2 field determines if the
4721
clocks can be halved. The *divider return value indi-
4722
cates whether clock division is used when determining the
4725
This function is only for non-programmable clocks.
4727
const char *xf86ModeStatusToString(ModeStatus status)
4729
This function converts the status value to a descriptive
4732
ModeStatus xf86LookupMode(ScrnInfoPtr scrp, DisplayModePtr modep,
4734
ClockRangePtr clockRanges, LookupModeFlags strategy)
4736
This function takes a pointer to a mode with the name
4737
filled in, and looks for a mode in the modePool list
4738
which matches. The parameters of the matching mode are
4739
filled in to *modep. The clockRanges and strategy param-
4740
eters are as for the xf86ValidateModes() function above.
4742
This function requires the modePool, clock[], numClocks
4743
and progClock fields of the ScrnInfoRec to be initialised
4744
before being called.
4746
The return value is MODE_OK if a mode was found. Other-
4747
wise it indicates why a matching mode could not be found.
4749
ModeStatus xf86InitialCheckModeForDriver(ScrnInfoPtr scrp,
4751
DisplayModePtr mode, ClockRangePtr clockRanges,
4753
LookupModeFlags strategy, int maxPitch,
4755
int virtualX, int virtualY)
4757
This function checks the passed mode against some basic
4758
driver constraints. Apart from the ones passed explic-
4759
itly, the maxHValue and maxVValue fields of the ScrnIn-
4760
foRec are also used. If the ValidMode field of the Scrn-
4761
InfoRec is set, that function is also called to check the
4762
mode. Next, the mode is checked against the monitor's
4765
If the mode is consistent with all constraints, the
4766
return value is MODE_OK. Otherwise the return value
4767
indicates which constraint wasn't met.
4769
void xf86DeleteMode(DisplayModePtr *modeList, DisplayModePtr mode)
4771
This function deletes the mode given from the modeList.
4772
It never prints any messages, so it is up to the caller
4773
to print a message if required.
4775
18.5 Functions for handling strings and tokens
4777
Tables associating strings and numerical tokens combined with the following
4778
functions provide a compact way of handling strings from the config file, and
4779
for converting tokens into printable strings. The table data structure is:
4784
} SymTabRec, *SymTabPtr;
4786
A table is an initialised array of SymTabRec. The tokens must be non-nega-
4787
tive integers. Multiple names may be mapped to a single token. The table is
4788
terminated with an element with a token value of -1 and NULL for the name.
4790
const char *xf86TokenToString(SymTabPtr table, int token)
4792
This function returns the first string in table that
4793
matches token. If no match is found, NULL is returned
4794
(NOTE, older versions of this function would return the
4795
string "unknown" when no match is found).
4797
int xf86StringToToken(SymTabPtr table, const char *string)
4799
This function returns the first token in table that
4800
matches string. The xf86NameCmp() function is used to
4801
determine the match. If no match is found, -1 is
4804
18.6 Functions for finding which config file entries to use
4806
These functions can be used to select the appropriate config file entries
4807
that match the detected hardware. They are described above in the Probe
4808
(section 5.8, page 1) and Available Functions (section 9.3, page 1) sections.
4810
18.7 Probing discrete clocks on old hardware
4812
The xf86GetClocks() function may be used to assist in finding the discrete
4813
pixel clock values on older hardware.
4815
void xf86GetClocks(ScrnInfoPtr pScrn, int num,
4817
Bool (*ClockFunc)(ScrnInfoPtr, int),
4819
void (*ProtectRegs)(ScrnInfoPtr, Bool),
4821
void (*BlankScreen)(ScrnInfoPtr, Bool),
4823
int vertsyncreg, int maskval, int knownclkindex,
4827
This function uses a comparative sampling method to mea-
4828
sure the discrete pixel clock values. The number of dis-
4829
crete clocks to measure is given by num. clockFunc is a
4830
function that selects the n'th clock. It should also
4831
save or restore any state affected by programming the
4832
clocks when the index passed is CLK_REG_SAVE or
4833
CLK_REG_RESTORE. ProtectRegs is a function that does
4834
whatever is required to protect the hardware state while
4835
selecting a new clock. BlankScreen is a function that
4836
blanks the screen. vertsyncreg and maskval are the reg-
4837
ister and bitmask to check for the presence of vertical
4838
sync pulses. knownclkindex and knownclkvalue are the
4839
index and value of a known clock. These are the known
4840
references on which the comparative measurements are
4841
based. The number of clocks probed is set in pScrn->num-
4842
Clocks, and the probed clocks are set in the
4843
pScrn->clock[] array. All of the clock values are in
4846
void xf86ShowClocks(ScrnInfoPtr scrp, MessageType from)
4848
Print out the pixel clocks scrp->clock[]. from indicates
4849
whether the clocks were probed or from the config file.
4851
18.8 Other helper functions
4853
Bool xf86IsUnblank(int mode)
4855
Returns TRUE when the screen saver mode specified by mode
4856
requires the screen be unblanked, and FALSE otherwise.
4857
The screen saver modes that require blanking are
4858
SCREEN_SAVER_ON and SCREEN_SAVER_CYCLE, and the screen
4859
saver modes that require unblanking are SCREEN_SAVER_OFF
4860
and SCREEN_SAVER_FORCER. Drivers may call this helper
4861
from their SaveScreen() function to interpret the screen
4864
19. The vgahw module
4866
The vgahw modules provides an interface for saving, restoring and programming
4867
the standard VGA registers, and for handling VGA colourmaps.
4869
19.1 Data Structures
4871
The public data structures used by the vgahw module are vgaRegRec and vgaH-
4872
WRec. They are defined in vgaHW.h.
4874
19.2 General vgahw Functions
4876
Bool vgaHWGetHWRec(ScrnInfoPtr pScrn)
4878
This function allocates a vgaHWRec structure, and hooks
4879
it into the ScrnInfoRec's privates. Like all information
4880
hooked into the privates, it is persistent, and only
4881
needs to be allocated once per screen. This function
4882
should normally be called from the driver's ChipPreInit()
4883
function. The vgaHWRec is zero-allocated, and the fol-
4884
lowing fields are explicitly initialised:
4887
initialised with a default colourmap
4889
ModeReg.Attribute[0x11]
4891
initialised with the default overscan index
4895
initialised according to the "ShowOverscan"
4900
initialised to FALSE
4904
initialised to FALSE
4908
initialised to pScrn
4910
In addition to the above, vgaHWSetStdFuncs() is called to
4911
initialise the register access function fields with the
4912
standard VGA set of functions.
4914
Once allocated, a pointer to the vgaHWRec can be obtained
4915
from the ScrnInfoPtr with the VGAHWPTR(pScrn) macro.
4917
void vgaHWFreeHWRec(ScrnInfoPtr pScrn)
4919
This function frees a vgaHWRec structure. It should be
4920
called from a driver's ChipFreeScreen() function.
4922
Bool vgaHWSetRegCounts(ScrnInfoPtr pScrn, int numCRTC,
4924
int numSequencer, int numGraphics, int numAttribute)
4926
This function allows the number of CRTC, Sequencer,
4927
Graphics and Attribute registers to be changed. This
4928
makes it possible for extended registers to be saved and
4929
restored with vgaHWSave() and vgaHWRestore(). This func-
4930
tion should be called after a vgaHWRec has been allocated
4931
with vgaHWGetHWRec(). The default values are defined in
4934
#define VGA_NUM_CRTC 25
4935
#define VGA_NUM_SEQ 5
4936
#define VGA_NUM_GFX 9
4937
#define VGA_NUM_ATTR 21
4939
Bool vgaHWCopyReg(vgaRegPtr dst, vgaRegPtr src)
4941
This function copies the contents of the VGA saved regis-
4942
ters in src to dst. Note that it isn't possible to sim-
4943
ply do this with memcpy() (or similar). This function
4944
returns TRUE unless there is a problem allocating space
4945
for the CRTC and related fields in dst.
4947
void vgaHWSetStdFuncs(vgaHWPtr hwp)
4949
This function initialises the register access function
4950
fields of hwp with the standard VGA set of functions.
4951
This is called by vgaHWGetHWRec(), so there is usually no
4952
need to call this explicitly. The register access func-
4953
tions are described below. If the registers are shadowed
4954
in some other port I/O space (for example a PCI I/O
4955
region), these functions can be used to access the shad-
4956
owed registers if hwp->PIOOffset is initialised with off-
4957
set, calculated in such a way that when the standard VGA
4958
I/O port value is added to it the correct offset into the
4959
PIO area results. This value is initialised to zero in
4960
vgaHWGetHWRec(). (Note: the PIOOffset functionality is
4961
present in XFree86 4.1.0 and later.)
4963
void vgaHWSetMmioFuncs(vgaHWPtr hwp, CARD8 *base, int offset)
4965
This function initialised the register access function
4966
fields of hwp with a generic MMIO set of functions.
4967
hwp->MMIOBase is initialised with base, which must be the
4968
virtual address that the start of MMIO area is mapped to.
4969
hwp->MMIOOffset is initialised with offset, which must be
4970
calculated in such a way that when the standard VGA I/O
4971
port value is added to it the correct offset into the
4972
MMIO area results. That means that these functions are
4973
only suitable when the VGA I/O ports are made available
4974
in a direct mapping to the MMIO space. If that is not
4975
the case, the driver will need to provide its own regis-
4976
ter access functions. The register access functions are
4979
Bool vgaHWMapMem(ScrnInfoPtr pScrn)
4981
This function maps the VGA memory window. It requires
4982
that the vgaHWRec be allocated. If a driver requires
4983
non-default MapPhys or MapSize settings (the physical
4984
location and size of the VGA memory window) then those
4985
fields of the vgaHWRec must be initialised before calling
4986
this function. Otherwise, this function initialiases the
4987
default values of 0xA0000 for MapPhys and (64 * 1024) for
4988
MapSize. This function must be called before attempting
4989
to save or restore the VGA state. If the driver doesn't
4990
call it explicitly, the vgaHWSave() and vgaHWRestore()
4991
functions may call it if they need to access the VGA mem-
4992
ory (in which case they will also call vgaHWUnmapMem() to
4993
unmap the VGA memory before exiting).
4995
void vgaHWUnmapMem(ScrnInfoPtr pScrn)
4997
This function unmaps the VGA memory window. It must only
4998
be called after the memory has been mapped. The Base
4999
field of the vgaHWRec field is set to NULL to indicate
5000
that the memory is no longer mapped.
5002
void vgaHWGetIOBase(vgaHWPtr hwp)
5004
This function initialises the IOBase field of the vgaH-
5005
WRec. This function must be called before using any
5006
other functions that access the video hardware.
5008
A macro VGAHW_GET_IOBASE() is also available in vgaHW.h
5009
that returns the I/O base, and this may be used when the
5010
vgahw module is not loaded (for example, in the Chip-
5013
void vgaHWUnlock(vgaHWPtr hwp)
5015
This function unlocks the VGA CRTC[0-7] registers, and
5016
must be called before attempting to write to those regis-
5019
void vgaHWLock(vgaHWPtr hwp)
5021
This function locks the VGA CRTC[0-7] registers.
5023
void vgaHWEnable(vgaHWPtr hwp)
5025
This function enables the VGA subsystem. (Note, this
5026
function is present in XFree86 4.1.0 and later.).
5028
void vgaHWDisable(vgaHWPtr hwp)
5030
This function disables the VGA subsystem. (Note, this
5031
function is present in XFree86 4.1.0 and later.).
5033
void vgaHWSave(ScrnInfoPtr pScrn, vgaRegPtr save, int flags)
5035
This function saves the VGA state. The state is written
5036
to the vgaRegRec pointed to by save. flags is set to one
5037
or more of the following flags ORed together:
5041
the mode setting registers are saved
5045
the text mode font/text data is saved
5049
the colourmap (LUT) is saved
5053
all of the above are saved
5055
The vgaHWRec and its IOBase fields must be initialised
5056
before this function is called. If VGA_SR_FONTS is set
5057
in flags, the VGA memory window must be mapped. If it
5058
isn't then vgaHWMapMem() will be called to map it, and
5059
vgaHWUnmapMem() will be called to unmap it afterwards.
5060
vgaHWSave() uses the three functions below in the order
5061
vgaHWSaveColormap(), vgaHWSaveMode(), vgaHWSaveFonts() to
5062
carry out the different save phases. It is undecided at
5063
this stage whether they will remain part of the vgahw
5064
module's public interface or not.
5066
void vgaHWSaveMode(ScrnInfoPtr pScrn, vgaRegPtr save)
5068
This function saves the VGA mode registers. They are
5069
saved to the vgaRegRec pointed to by save. The registers
5082
The number of registers actually saved may be modified by
5083
a prior call to vgaHWSetRegCounts().
5085
void vgaHWSaveFonts(ScrnInfoPtr pScrn, vgaRegPtr save)
5087
This function saves the text mode font and text data held
5088
in the video memory. If called while in a graphics mode,
5089
no save is done. The VGA memory window must be mapped
5090
with vgaHWMapMem() before to calling this function.
5092
On some platforms, one or more of the font/text plane
5093
saves may be no-ops. This is the case when the plat-
5094
form's VC driver already takes care of this.
5096
void vgaHWSaveColormap(ScrnInfoPtr pScrn, vgaRegPtr save)
5098
This function saves the VGA colourmap (LUT). Before sav-
5099
ing it, it attempts to verify that the colourmap is read-
5100
able. In rare cases where it isn't readable, a default
5101
colourmap is saved instead.
5103
void vgaHWRestore(ScrnInfoPtr pScrn, vgaRegPtr restore, int flags)
5105
This function programs the VGA state. The state pro-
5106
grammed is that contained in the vgaRegRec pointed to by
5107
restore. flags is the same as described above for the
5108
vgaHWSave() function.
5110
The vgaHWRec and its IOBase fields must be initialised
5111
before this function is called. If VGA_SR_FONTS is set
5112
in flags, the VGA memory window must be mapped. If it
5113
isn't then vgaHWMapMem() will be called to map it, and
5114
vgaHWUnmapMem() will be called to unmap it afterwards.
5115
vgaHWRestore() uses the three functions below in the
5116
order vgaHWRestoreFonts(), vgaHWRestoreMode(), vgaHWRe-
5117
storeColormap() to carry out the different restore
5118
phases. It is undecided at this stage whether they will
5119
remain part of the vgahw module's public interface or
5122
void vgaHWRestoreMode(ScrnInfoPtr pScrn, vgaRegPtr restore)
5124
This function restores the VGA mode registers. They are
5125
restored from the data in the vgaRegRec pointed to by
5126
restore. The registers restored are:
5138
The number of registers actually restored may be modified
5139
by a prior call to vgaHWSetRegCounts().
5141
void vgaHWRestoreFonts(ScrnInfoPtr pScrn, vgaRegPtr restore)
5143
This function restores the text mode font and text data
5144
to the video memory. The VGA memory window must be
5145
mapped with vgaHWMapMem() before to calling this func-
5148
On some platforms, one or more of the font/text plane
5149
restores may be no-ops. This is the case when the plat-
5150
form's VC driver already takes care of this.
5152
void vgaHWRestoreColormap(ScrnInfoPtr pScrn, vgaRegPtr restore)
5154
This function restores the VGA colourmap (LUT).
5156
void vgaHWInit(ScrnInfoPtr pScrn, DisplayModePtr mode)
5158
This function fills in the vgaHWRec's ModeReg field with
5159
the values appropriate for programming the given video
5160
mode. It requires that the ScrnInfoRec's depth field is
5161
initialised, which determines how the registers are pro-
5164
void vgaHWSeqReset(vgaHWPtr hwp, Bool start)
5166
Do a VGA sequencer reset. If start is TRUE, the reset is
5167
started. If start is FALSE, the reset is ended.
5169
void vgaHWProtect(ScrnInfoPtr pScrn, Bool on)
5171
This function protects VGA registers and memory from cor-
5172
ruption during loads. It is typically called with on set
5173
to TRUE before programming, and with on set to FALSE
5176
Bool vgaHWSaveScreen(ScreenPtr pScreen, int mode)
5178
This function blanks and unblanks the screen. It is
5179
blanked when mode is SCREEN_SAVER_ON or
5180
SCREEN_SAVER_CYCLE, and unblanked when mode is
5181
SCREEN_SAVER_OFF or SCREEN_SAVER_FORCER.
5183
void vgaHWBlankScreen(ScrnInfoPtr pScrn, Bool on)
5185
This function blanks and unblanks the screen. It is
5186
blanked when on is FALSE, and unblanked when on is TRUE.
5187
This function is provided for use in cases where the
5188
ScrnInfoRec can't be derived from the ScreenRec (while
5189
probing for clocks, for example).
5191
19.3 VGA Colormap Functions
5193
The vgahw module uses the standard colormap support (see the Colormap Han-
5194
dling (section 13., page 1) section. This is initialised with the following
5197
Bool vgaHWHandleColormaps(ScreenPtr pScreen)
5199
19.4 VGA Register Access Functions
5201
The vgahw module abstracts access to the standard VGA registers by using a
5202
set of functions held in the vgaHWRec. When the vgaHWRec is created these
5203
function pointers are initialised with the set of standard VGA I/O register
5204
access functions. In addition to these, the vgahw module includes a basic
5205
set of MMIO register access functions, and the vgaHWRec function pointers can
5206
be initialised to these by calling the vgaHWSetMmioFuncs() function described
5207
above. Some drivers/platforms may require a different set of functions for
5208
VGA access. The access functions are described here.
5210
void writeCrtc(vgaHWPtr hwp, CARD8 index, CARD8 value)
5212
Write value to CRTC register index.
5214
CARD8 readCrtc(vgaHWPtr hwp, CARD8 index)
5216
Return the value read from CRTC register index.
5218
void writeGr(vgaHWPtr hwp, CARD8 index, CARD8 value)
5220
Write value to Graphics Controller register index.
5222
CARD8 readGR(vgaHWPtr hwp, CARD8 index)
5224
Return the value read from Graphics Controller register
5227
void writeSeq(vgaHWPtr hwp, CARD8 index, CARD8, value)
5229
Write value to Sequencer register index.
5231
CARD8 readSeq(vgaHWPtr hwp, CARD8 index)
5233
Return the value read from Sequencer register index.
5235
void writeAttr(vgaHWPtr hwp, CARD8 index, CARD8, value)
5237
Write value to Attribute Controller register index. When
5238
writing out the index value this function should set bit
5239
5 (0x20) according to the setting of hwp->paletteEnabled
5240
in order to preserve the palette access state. It should
5241
be cleared when hwp->paletteEnabled is TRUE and set when
5244
CARD8 readAttr(vgaHWPtr hwp, CARD8 index)
5246
Return the value read from Attribute Controller register
5247
index. When writing out the index value this function
5248
should set bit 5 (0x20) according to the setting of
5249
hwp->paletteEnabled in order to preserve the palette
5250
access state. It should be cleared when hwp->paletteEn-
5251
abled is TRUE and set when it is FALSE.
5253
void writeMiscOut(vgaHWPtr hwp, CARD8 value)
5255
Write `value' to the Miscellaneous Output register.
5257
CARD8 readMiscOut(vgwHWPtr hwp)
5259
Return the value read from the Miscellaneous Output reg-
5262
void enablePalette(vgaHWPtr hwp)
5264
Clear the palette address source bit in the Attribute
5265
Controller index register and set hwp->paletteEnabled to
5268
void disablePalette(vgaHWPtr hwp)
5270
Set the palette address source bit in the Attribute Con-
5271
troller index register and set hwp->paletteEnabled to
5274
void writeDacMask(vgaHWPtr hwp, CARD8 value)
5276
Write value to the DAC Mask register.
5278
CARD8 readDacMask(vgaHWptr hwp)
5280
Return the value read from the DAC Mask register.
5282
void writeDacReadAddress(vgaHWPtr hwp, CARD8 value)
5284
Write value to the DAC Read Address register.
5286
void writeDacWriteAddress(vgaHWPtr hwp, CARD8 value)
5288
Write value to the DAC Write Address register.
5290
void writeDacData(vgaHWPtr hwp, CARD8 value)
5292
Write value to the DAC Data register.
5294
CARD8 readDacData(vgaHWptr hwp)
5296
Return the value read from the DAC Data register.
5298
CARD8 readEnable(vgaHWptr hwp)
5300
Return the value read from the VGA Enable register.
5301
(Note: This function is present in XFree86 4.1.0 and
5304
void writeEnable(vgaHWPtr hwp, CARD8 value)
5306
Write value to the VGA Enable register. (Note: This
5307
function is present in XFree86 4.1.0 and later.)
5309
20. Some notes about writing a driver
5311
NOTE: some parts of this are not up to date
5313
The following is an outline for writing a basic unaccelerated driver for a
5314
PCI video card with a linear mapped framebuffer, and which has a VGA core.
5315
It is includes some general information that is relevant to most drivers
5316
(even those which don't fit that basic description).
5318
The information here is based on the initial conversion of the Matrox Millen-
5319
nium driver to the ``new design''. For a fleshing out and sample implementa-
5320
tion of some of the bits outlined here, refer to that driver. Note that this
5321
is an example only. The approach used here will not be appropriate for all
5324
Each driver must reserve a unique driver name, and a string that is used to
5325
prefix all of its externally visible symbols. This is to avoid name space
5326
clashes when loading multiple drivers. The examples here are for the ``ZZZ''
5327
driver, which uses the ``ZZZ'' or ``zzz'' prefix for its externally visible
5332
All drivers normally include the following headers:
5342
Wherever inb/outb (and related things) are used the following should be
5347
Note: in drivers, this must be included after "xf86_ansic.h".
5349
Drivers that need to access PCI vendor/device definitions need this:
5353
Drivers that need to access the PCI config space need this:
5357
Drivers using the mi banking wrapper need:
5361
Drivers that initialise a SW cursor need this:
5365
All drivers implementing backing store need this:
5369
All drivers using the mi colourmap code need this:
5373
If a driver uses the vgahw module, it needs this:
5377
Drivers supporting VGA or Hercules monochrome screens need:
5381
Drivers supporting VGA or EGC 16-colour screens need:
5385
Drivers using cfb need:
5393
Drivers supporting bpp 16, 24 or 32 with cfb need one or more of:
5401
The driver's own header file:
5405
Drivers must NOT include the following:
5419
20.2 Data structures and initialisation
5421
o The following macros should be defined:
5423
#define VERSION <version-as-an-int>
5424
#define ZZZ_NAME "ZZZ" /* the name used to prefix messages */
5425
#define ZZZ_DRIVER_NAME "zzz" /* the driver name as used in config file */
5426
#define ZZZ_MAJOR_VERSION <int>
5427
#define ZZZ_MINOR_VERSION <int>
5428
#define ZZZ_PATCHLEVEL <int>
5430
NOTE: ZZZ_DRIVER_NAME should match the name of the driver module without
5431
things like the "lib" prefix, the "_drv" suffix or filename extensions.
5433
o A DriverRec must be defined, which includes the functions required at
5434
the pre-probe phase. The name of this DriverRec must be an upper-case
5435
version of ZZZ_DRIVER_NAME (for the purposes of static linking).
5442
ZZZAvailableOptions,
5447
o Define list of supported chips and their matching ID:
5449
static SymTabRec ZZZChipsets[] = {
5450
{ PCI_CHIP_ZZZ1234, "zzz1234a" },
5451
{ PCI_CHIP_ZZZ5678, "zzz5678a" },
5455
The token field may be any integer value that the driver may use to
5456
uniquely identify the supported chipsets. For drivers that support only
5457
PCI devices using the PCI device IDs might be a natural choice, but this
5458
isn't mandatory. For drivers that support both PCI and other devices
5459
(like ISA), some other ID should probably used. When other IDs are used
5460
as the tokens it is recommended that the names be defined as an enum
5463
o If the driver uses the xf86MatchPciInstances() helper (recommended for
5464
drivers that support PCI cards) a list that maps PCI IDs to chip IDs and
5465
fixed resources must be defined:
5467
static PciChipsets ZZZPciChipsets[] = {
5468
{ PCI_CHIP_ZZZ1234, PCI_CHIP_ZZZ1234, RES_SHARED_VGA },
5469
{ PCI_CHIP_ZZZ5678, PCI_CHIP_ZZZ5678, RES_SHARED_VGA },
5470
{ -1, -1, RES_UNDEFINED }
5473
o Define the XF86ModuleVersionInfo struct for the driver. This is
5474
required for the dynamically loaded version:
5476
#ifdef XFree86LOADER
5477
static XF86ModuleVersionInfo zzzVersRec =
5483
XF86_VERSION_CURRENT,
5484
ZZZ_MAJOR_VERSION, ZZZ_MINOR_VERSION, ZZZ_PATCHLEVEL,
5486
ABI_VIDEODRV_VERSION,
5492
o Define a data structure to hold the driver's screen-specific data. This
5493
must be used instead of global variables. This would be defined in the
5494
"zzz.h" file, something like:
5503
CloseScreenProcPtr CloseScreen;
5504
OptionInfoPtr Options;
5508
o Define the list of config file Options that the driver accepts. For
5509
consistency between drivers those in the list of ``standard'' options
5510
should be used where appropriate before inventing new options.
5519
static const OptionInfoRec ZZZOptions[] = {
5520
{ OPTION_FOO_HACK, "FooHack", OPTV_INTEGER, {0}, FALSE },
5521
{ OPTION_PCI_RETRY, "PciRetry", OPTV_BOOLEAN, {0}, FALSE },
5522
{ OPTION_HW_CURSOR, "HWcursor", OPTV_BOOLEAN, {0}, FALSE },
5523
{ OPTION_NOACCEL, "NoAccel", OPTV_BOOLEAN, {0}, FALSE },
5524
{ -1, NULL, OPTV_NONE, {0}, FALSE }
5531
For dynamically loaded modules, a ModuleData variable is required. It is
5532
should be the name of the driver prepended to "ModuleData". A Setup() func-
5533
tion is also required, which calls xf86AddDriver() to add the driver to the
5534
main list of drivers.
5536
#ifdef XFree86LOADER
5538
static MODULESETUPPROTO(mgaSetup);
5540
XF86ModuleData zzzModuleData = { &zzzVersRec, zzzSetup, NULL };
5543
zzzSetup(pointer module, pointer opts, int *errmaj, int *errmin)
5545
static Bool setupDone = FALSE;
5547
/* This module should be loaded only once, but check to be sure. */
5551
* Modules that this driver always requires may be loaded
5552
* here by calling LoadSubModule().
5556
xf86AddDriver(&MGA, module, 0);
5559
* The return value must be non-NULL on success even though
5560
* there is no TearDownProc.
5564
if (errmaj) *errmaj = LDR_ONCEONLY;
5570
20.3.2 GetRec, FreeRec
5572
A function is usually required to allocate the driver's screen-specific data
5573
structure and hook it into the ScrnInfoRec's driverPrivate field. The Scrn-
5574
InfoRec's driverPrivate is initialised to NULL, so it is easy to check if the
5575
initialisation has already been done. After allocating it, initialise the
5576
fields. By using xnfcalloc() to do the allocation it is zeroed, and if the
5577
allocation fails the server exits.
5579
NOTE: When allocating structures from inside the driver which are defined on
5580
the common level it is important to initialize the structure to zero. Only
5581
this guarantees that the server remains source compatible to future changes
5582
in common level structures.
5585
ZZZGetRec(ScrnInfoPtr pScrn)
5587
if (pScrn->driverPrivate != NULL)
5589
pScrn->driverPrivate = xnfcalloc(sizeof(ZZZRec), 1);
5590
/* Initialise as required */
5595
Define a macro in "zzz.h" which gets a pointer to the ZZZRec when given
5598
#define ZZZPTR(p) ((ZZZPtr)((p)->driverPrivate))
5600
Define a function to free the above, setting it to NULL once it has been
5604
ZZZFreeRec(ScrnInfoPtr pScrn)
5606
if (pScrn->driverPrivate == NULL)
5608
xfree(pScrn->driverPrivate);
5609
pScrn->driverPrivate = NULL;
5614
Define the Identify() function. It is run before the Probe, and typically
5615
prints out an identifying message, which might include the chipsets it sup-
5616
ports. This function is mandatory:
5619
ZZZIdentify(int flags)
5621
xf86PrintChipsets(ZZZ_NAME, "driver for ZZZ Tech chipsets",
5627
Define the Probe() function. The purpose of this is to find all instances of
5628
the hardware that the driver supports, and for the ones not already claimed
5629
by another driver, claim the slot, and allocate a ScrnInfoRec. This should
5630
be a minimal probe, and it should under no circumstances leave the state of
5631
the hardware changed. Because a device is found, don't assume that it will
5632
be used. Don't do any initialisations other than the required ScrnInfoRec
5633
initialisations. Don't allocate any new data structures.
5635
This function is mandatory.
5637
NOTE: The xf86DrvMsg() functions cannot be used from the Probe.
5640
ZZZProbe(DriverPtr drv, int flags)
5642
Bool foundScreen = FALSE;
5643
int numDevSections, numUsed;
5644
GDevPtr *devSections;
5649
* Find the config file Device sections that match this
5650
* driver, and return if there are none.
5652
if ((numDevSections = xf86MatchDevice(ZZZ_DRIVER_NAME,
5653
&devSections)) <= 0) {
5658
* Since this is a PCI card, "probing" just amounts to checking
5659
* the PCI data that the server has already collected. If there
5662
* Although the config file is allowed to override things, it
5663
* is reasonable to not allow it to override the detection
5664
* of no PCI video cards.
5666
* The provided xf86MatchPciInstances() helper takes care of
5669
/* test if PCI bus present */
5670
if (xf86GetPciVideoInfo()) {
5672
numUsed = xf86MatchPciInstances(ZZZ_NAME, PCI_VENDOR_ZZZ,
5673
ZZZChipsets, ZZZPciChipsets, devSections,
5674
numDevSections, drv, &usedChips);
5676
for (i = 0; i < numUsed; i++) {
5677
ScrnInfoPtr pScrn = NULL;
5678
if ((pScrn = xf86ConfigPciEntity(pScrn, flags, usedChips[i],
5679
ZZZPciChipsets, NULL, NULL,
5680
NULL, NULL, NULL))) {
5681
/* Allocate a ScrnInfoRec */
5682
pScrn->driverVersion = VERSION;
5683
pScrn->driverName = ZZZ_DRIVER_NAME;
5684
pScrn->name = ZZZ_NAME;
5685
pScrn->Probe = ZZZProbe;
5686
pScrn->PreInit = ZZZPreInit;
5687
pScrn->ScreenInit = ZZZScreenInit;
5688
pScrn->SwitchMode = ZZZSwitchMode;
5689
pScrn->AdjustFrame = ZZZAdjustFrame;
5690
pScrn->EnterVT = ZZZEnterVT;
5691
pScrn->LeaveVT = ZZZLeaveVT;
5692
pScrn->FreeScreen = ZZZFreeScreen;
5693
pScrn->ValidMode = ZZZValidMode;
5695
/* add screen to entity */
5703
* If the driver supports ISA hardware, the following block
5704
* can be included too.
5706
numUsed = xf86MatchIsaInstances(ZZZ_NAME, ZZZChipsets,
5707
ZZZIsaChipsets, drv, ZZZFindIsaDevice,
5708
devSections, numDevSections, &usedChips);
5709
for (i = 0; i < numUsed; i++) {
5710
ScrnInfoPtr pScrn = NULL;
5711
if ((pScrn = xf86ConfigIsaEntity(pScrn, flags, usedChips[i],
5712
ZZZIsaChipsets, NULL, NULL, NULL,
5714
pScrn->driverVersion = VERSION;
5715
pScrn->driverName = ZZZ_DRIVER_NAME;
5716
pScrn->name = ZZZ_NAME;
5717
pScrn->Probe = ZZZProbe;
5718
pScrn->PreInit = ZZZPreInit;
5719
pScrn->ScreenInit = ZZZScreenInit;
5720
pScrn->SwitchMode = ZZZSwitchMode;
5721
pScrn->AdjustFrame = ZZZAdjustFrame;
5722
pScrn->EnterVT = ZZZEnterVT;
5723
pScrn->LeaveVT = ZZZLeaveVT;
5724
pScrn->FreeScreen = ZZZFreeScreen;
5725
pScrn->ValidMode = ZZZValidMode;
5730
#endif /* HAS_ISA_DEVS */
5735
20.3.5 AvailableOptions
5737
Define the AvailableOptions() function. The purpose of this is to return the
5738
available driver options back to the -configure option, so that an XF86Config
5739
file can be built and the user can see which options are available for them
5744
Define the PreInit() function. The purpose of this is to find all the infor-
5745
mation required to determine if the configuration is usable, and to ini-
5746
tialise those parts of the ScrnInfoRec that can be set once at the beginning
5747
of the first server generation. The information should be found in the least
5748
intrusive way possible.
5750
This function is mandatory.
5754
1. The PreInit() function is only called once during the life of the X
5755
server (at the start of the first generation).
5757
2. Data allocated here must be of the type that persists for the life of
5758
the X server. This means that data that hooks into the ScrnInfoRec's
5759
privates field should be allocated here, but data that hooks into the
5760
ScreenRec's devPrivates field should not be allocated here. The
5761
driverPrivate field should also be allocated here.
5763
3. Although the ScrnInfoRec has been allocated before this function is
5764
called, the ScreenRec has not been allocated. That means that things
5765
requiring it cannot be used in this function.
5767
4. Very little of the ScrnInfoRec has been initialised when this function
5768
is called. It is important to get the order of doing things right in
5772
ZZZPreInit(ScrnInfoPtr pScrn, int flags)
5774
/* Fill in the monitor field */
5775
pScrn->monitor = pScrn->confScreen->monitor;
5778
* If using the vgahw module, it will typically be loaded
5779
* here by calling xf86LoadSubModule(pScrn, "vgahw");
5783
* Set the depth/bpp. Our preferred default depth/bpp is 8, and
5784
* we support both 24bpp and 32bpp framebuffer layouts.
5785
* This sets pScrn->display also.
5787
if (!xf86SetDepthBpp(pScrn, 8, 8, 8,
5788
Support24bppFb | Support32bppFb)) {
5791
if (depth/bpp isn't one we support) {
5792
print error message;
5796
/* Print out the depth/bpp that was set */
5797
xf86PrintDepthBpp(pScrn);
5799
/* Set bits per RGB for 8bpp */
5800
if (pScrn->depth <= 8) {
5801
/* Take into account a dac_6_bit option here */
5802
pScrn->rgbBits = 6 or 8;
5806
* xf86SetWeight() and xf86SetDefaultVisual() must be called
5807
* after pScrn->display is initialised.
5810
/* Set weight/mask/offset for depth > 8 */
5811
if (pScrn->depth > 8) {
5812
if (!xf86SetWeight(pScrn, defaultWeight, defaultMask)) {
5815
if (weight isn't one we support) {
5816
print error message;
5822
/* Set the default visual. */
5823
if (!xf86SetDefaultVisual(pScrn, -1)) {
5826
if (visual isn't one we support) {
5827
print error message;
5832
/* If the driver supports gamma correction, set the gamma. */
5833
if (!xf86SetGamma(pScrn, default_gamma)) {
5837
/* This driver uses a programmable clock */
5838
pScrn->progClock = TRUE;
5840
/* Allocate the ZZZRec driverPrivate */
5841
if (!ZZZGetRec(pScrn)) {
5845
pZzz = ZZZPTR(pScrn);
5847
/* Collect all of the option flags (fill in pScrn->options) */
5848
xf86CollectOptions(pScrn, NULL);
5851
* Process the options based on the information in ZZZOptions.
5852
* The results are written to pZzz->Options. If all of the options
5853
* processing is done within this function a local variable "options"
5854
* can be used instead of pZzz->Options.
5856
if (!(pZzz->Options = xalloc(sizeof(ZZZOptions))))
5858
(void)memcpy(pZzz->Options, ZZZOptions, sizeof(ZZZOptions));
5859
xf86ProcessOptions(pScrn->scrnIndex, pScrn->options, pZzz->Options);
5862
* Set various fields of ScrnInfoRec and/or ZZZRec based on
5863
* the options found.
5866
pZzz->hwCursor = FALSE;
5867
if (xf86IsOptionSet(pZzz->Options, OPTION_HW_CURSOR)) {
5869
pZzz->hwCursor = TRUE;
5871
xf86DrvMsg(pScrn->scrnIndex, from, "Using %s cursor\n",
5872
pZzz->hwCursor ? "HW" : "SW");
5873
if (xf86IsOptionSet(pZzz->Options, OPTION_NOACCEL)) {
5874
pZzz->noAccel = TRUE;
5875
xf86DrvMsg(pScrn->scrnIndex, X_CONFIG,
5876
"Acceleration disabled\n");
5878
pZzz->noAccel = FALSE;
5880
if (xf86IsOptionSet(pZzz->Options, OPTION_PCI_RETRY)) {
5881
pZzz->UsePCIRetry = TRUE;
5882
xf86DrvMsg(pScrn->scrnIndex, X_CONFIG, "PCI retry enabled\n");
5885
if (xf86GetOptValInteger(pZzz->Options, OPTION_FOO_HACK,
5887
xf86DrvMsg(pScrn->scrnIndex, X_CONFIG, "Foo Hack set to %d\n",
5892
* Find the PCI slot(s) that this screen claimed in the probe.
5893
* In this case, exactly one is expected, so complain otherwise.
5894
* Note in this case we're not interested in the card types so
5895
* that parameter is set to NULL.
5897
if ((i = xf86GetPciInfoForScreen(pScrn->scrnIndex, &pciList, NULL))
5899
print error message;
5905
/* Note that pciList should be freed below when no longer needed */
5908
* Determine the chipset, allowing config file chipset and
5909
* chipid values to override the probed information. The config
5910
* chipset value has precedence over its chipid value if both
5913
* It isn't necessary to fill in pScrn->chipset if the driver
5914
* keeps track of the chipset in its ZZZRec.
5920
* Determine video memory, fb base address, I/O addresses, etc,
5921
* allowing the config file to override probed values.
5923
* Set the appropriate pScrn fields (videoRam is probably the
5924
* most important one that other code might require), and
5925
* print out the settings.
5930
/* Initialise a clockRanges list. */
5934
/* Set any other chipset specific things in the ZZZRec */
5938
/* Select valid modes from those available */
5940
i = xf86ValidateModes(pScrn, pScrn->monitor->Modes,
5941
pScrn->display->modes, clockRanges,
5942
NULL, minPitch, maxPitch, rounding,
5943
minHeight, maxHeight,
5944
pScrn->display->virtualX,
5945
pScrn->display->virtualY,
5946
pScrn->videoRam * 1024,
5947
LOOKUP_BEST_REFRESH);
5953
/* Prune the modes marked as invalid */
5955
xf86PruneDriverModes(pScrn);
5957
/* If no valid modes, return */
5959
if (i == 0 || pScrn->modes == NULL) {
5960
print error message;
5966
* Initialise the CRTC fields for the modes. This driver expects
5967
* vertical values to be halved for interlaced modes.
5969
xf86SetCrtcForModes(pScrn, INTERLACE_HALVE_V);
5971
/* Set the current mode to the first in the list. */
5972
pScrn->currentMode = pScrn->modes;
5974
/* Print the list of modes being used. */
5975
xf86PrintModes(pScrn);
5978
xf86SetDpi(pScrn, 0, 0);
5980
/* Load bpp-specific modules */
5981
switch (pScrn->bitsPerPixel) {
6001
if (mod && !xf86LoadSubModule(pScrn, mod))
6005
/* Load XAA if needed */
6006
if (!pZzz->noAccel || pZzz->hwCursor)
6007
if (!xf86LoadSubModule(pScrn, "xaa")) {
6016
20.3.7 MapMem, UnmapMem
6018
Define functions to map and unmap the video memory and any other memory aper-
6019
tures required. These functions are not mandatory, but it is often useful to
6020
have such functions.
6023
ZZZMapMem(ScrnInfoPtr pScrn)
6025
/* Call xf86MapPciMem() to map each PCI memory area */
6027
return TRUE or FALSE;
6031
ZZZUnmapMem(ScrnInfoPtr pScrn)
6033
/* Call xf86UnMapVidMem() to unmap each memory area */
6035
return TRUE or FALSE;
6038
20.3.8 Save, Restore
6040
Define functions to save and restore the original video state. These func-
6041
tions are not mandatory, but are often useful.
6044
ZZZSave(ScrnInfoPtr pScrn)
6047
* Save state into per-screen data structures.
6048
* If using the vgahw module, vgaHWSave will typically be
6055
ZZZRestore(ScrnInfoPtr pScrn)
6058
* Restore state from per-screen data structures.
6059
* If using the vgahw module, vgaHWRestore will typically be
6067
Define a function to initialise a new video mode. This function isn't manda-
6068
tory, but is often useful.
6071
ZZZModeInit(ScrnInfoPtr pScrn, DisplayModePtr mode)
6074
* Program a video mode. If using the vgahw module,
6075
* vgaHWInit and vgaRestore will typically be called here.
6076
* Once up to the point where there can't be a failure
6077
* set pScrn->vtSema to TRUE.
6084
Define the ScreenInit() function. This is called at the start of each server
6085
generation, and should fill in as much of the ScreenRec as possible as well
6086
as any other data that is initialised once per generation. It should ini-
6087
tialise the framebuffer layers it is using, and initialise the initial video
6090
This function is mandatory.
6092
NOTE: The ScreenRec (pScreen) is passed to this driver, but it and the Scrn-
6093
InfoRecs are not yet hooked into each other. This means that in this func-
6094
tion, and functions it calls, one cannot be found from the other.
6097
ZZZScreenInit(int scrnIndex, ScreenPtr pScreen, int argc, char **argv)
6099
/* Get the ScrnInfoRec */
6100
pScrn = xf86Screens[pScreen->myNum];
6103
* If using the vgahw module, its data structures and related
6104
* things are typically initialised/mapped here.
6107
/* Save the current video state */
6110
/* Initialise the first mode */
6111
ZZZModeInit(pScrn, pScrn->currentMode);
6113
/* Set the viewport if supported */
6115
ZZZAdjustFrame(scrnIndex, pScrn->frameX0, pScrn->frameY0, 0);
6118
* Setup the screen's visuals, and initialise the framebuffer
6122
/* Reset the visual list */
6123
miClearVisualTypes();
6126
* Setup the visuals supported. This driver only supports
6127
* TrueColor for bpp > 8, so the default set of visuals isn't
6128
* acceptable. To deal with this, call miSetVisualTypes with
6129
* the appropriate visual mask.
6132
if (pScrn->bitsPerPixel > 8) {
6133
if (!miSetVisualTypes(pScrn->depth, TrueColorMask,
6134
pScrn->rgbBits, pScrn->defaultVisual))
6137
if (!miSetVisualTypes(pScrn->depth,
6138
miGetDefaultVisualMask(pScrn->depth),
6139
pScrn->rgbBits, pScrn->defaultVisual))
6144
* Initialise the framebuffer.
6147
switch (pScrn->bitsPerPixel) {
6149
ret = xf1bppScreenInit(pScreen, FbBase,
6150
pScrn->virtualX, pScrn->virtualY,
6151
pScrn->xDpi, pScrn->yDpi,
6152
pScrn->displayWidth);
6155
ret = xf4bppScreenInit(pScreen, FbBase,
6156
pScrn->virtualX, pScrn->virtualY,
6157
pScrn->xDpi, pScrn->yDpi,
6158
pScrn->displayWidth);
6161
ret = cfbScreenInit(pScreen, FbBase,
6162
pScrn->virtualX, pScrn->virtualY,
6163
pScrn->xDpi, pScrn->yDpi,
6164
pScrn->displayWidth);
6167
ret = cfb16ScreenInit(pScreen, FbBase,
6168
pScrn->virtualX, pScrn->virtualY,
6169
pScrn->xDpi, pScrn->yDpi,
6170
pScrn->displayWidth);
6173
ret = cfb24ScreenInit(pScreen, FbBase,
6174
pScrn->virtualX, pScrn->virtualY,
6175
pScrn->xDpi, pScrn->yDpi,
6176
pScrn->displayWidth);
6179
ret = cfb32ScreenInit(pScreen, FbBase,
6180
pScrn->virtualX, pScrn->virtualY,
6181
pScrn->xDpi, pScrn->yDpi,
6182
pScrn->displayWidth);
6185
print a message about an internal error;
6193
/* Override the default mask/offset settings */
6194
if (pScrn->bitsPerPixel > 8) {
6195
for (i = 0, visual = pScreen->visuals;
6196
i < pScreen->numVisuals; i++, visual++) {
6197
if ((visual->class | DynamicClass) == DirectColor) {
6198
visual->offsetRed = pScrn->offset.red;
6199
visual->offsetGreen = pScrn->offset.green;
6200
visual->offsetBlue = pScrn->offset.blue;
6201
visual->redMask = pScrn->mask.red;
6202
visual->greenMask = pScrn->mask.green;
6203
visual->blueMask = pScrn->mask.blue;
6209
* If banking is needed, initialise an miBankInfoRec (defined in
6210
* "mibank.h"), and call miInitializeBanking().
6212
if (!miInitializeBanking(pScreen, pScrn->virtualX, pScrn->virtualY,
6213
pScrn->displayWidth, pBankInfo))
6217
* If backing store is to be supported (as is usually the case),
6220
miInitializeBackingStore(pScreen);
6223
* Set initial black & white colourmap indices.
6225
xf86SetBlackWhitePixels(pScreen);
6228
* Install colourmap functions. If using the vgahw module,
6229
* vgaHandleColormaps would usually be called here.
6235
* Initialise cursor functions. This example is for the mi
6238
miDCInitialize(pScreen, xf86GetPointerScreenFuncs());
6240
/* Initialise the default colourmap */
6241
switch (pScrn->depth) {
6243
if (!xf1bppCreateDefColormap(pScreen))
6247
if (!xf4bppCreateDefColormap(pScreen))
6251
if (!cfbCreateDefColormap(pScreen))
6257
* Wrap the CloseScreen vector and set SaveScreen.
6259
ZZZPTR(pScrn)->CloseScreen = pScreen->CloseScreen;
6260
pScreen->CloseScreen = ZZZCloseScreen;
6261
pScreen->SaveScreen = ZZZSaveScreen;
6263
/* Report any unused options (only for the first generation) */
6264
if (serverGeneration == 1) {
6265
xf86ShowUnusedOptions(pScrn->scrnIndex, pScrn->options);
6274
Define the SwitchMode() function if mode switching is supported by the
6278
ZZZSwitchMode(int scrnIndex, DisplayModePtr mode, int flags)
6280
return ZZZModeInit(xf86Screens[scrnIndex], mode);
6285
Define the AdjustFrame() function if the driver supports this.
6288
ZZZAdjustFrame(int scrnIndex, int x, int y, int flags)
6290
/* Adjust the viewport */
6293
20.3.13 EnterVT, LeaveVT
6295
Define the EnterVT() and LeaveVT() functions.
6297
These functions are mandatory.
6300
ZZZEnterVT(int scrnIndex, int flags)
6302
ScrnInfoPtr pScrn = xf86Screens[scrnIndex];
6303
return ZZZModeInit(pScrn, pScrn->currentMode);
6307
ZZZLeaveVT(int scrnIndex, int flags)
6309
ScrnInfoPtr pScrn = xf86Screens[scrnIndex];
6315
Define the CloseScreen() function:
6317
This function is mandatory. Note that it unwraps the previously wrapped
6318
pScreen->CloseScreen, and finishes by calling it.
6321
ZZZCloseScreen(int scrnIndex, ScreenPtr pScreen)
6323
ScrnInfoPtr pScrn = xf86Screens[scrnIndex];
6324
if (pScrn->vtSema) {
6328
pScrn->vtSema = FALSE;
6329
pScreen->CloseScreen = ZZZPTR(pScrn)->CloseScreen;
6330
return (*pScreen->CloseScreen)(scrnIndex, pScreen);
6335
Define the SaveScreen() function (the screen blanking function). When using
6336
the vgahw module, this will typically be:
6339
ZZZSaveScreen(ScreenPtr pScreen, int mode)
6341
return vgaHWSaveScreen(pScreen, mode);
6344
This function is mandatory. Before modifying any hardware register directly
6345
this function needs to make sure that the Xserver is active by checking if
6346
pScrn is non-NULL and for pScrn->vtSema == TRUE.
6350
Define the FreeScreen() function. This function is optional. It should be
6351
defined if the ScrnInfoRec driverPrivate field is used so that it can be
6352
freed when a screen is deleted by the common layer for reasons possibly
6353
beyond the driver's control. This function is not used in during normal
6354
(error free) operation. The per-generation data is freed by the Clos-
6358
ZZZFreeScreen(int scrnIndex, int flags)
6361
* If the vgahw module is used vgaHWFreeHWRec() would be called
6364
ZZZFreeRec(xf86Screens[scrnIndex]);
6367
Generated from XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/DESIGN.sgml,v 1.52 2003/02/25 19:31:00 dawes Exp $
6370
$XFree86: xc/programs/Xserver/hw/xfree86/doc/DESIGN,v 1.47 2003/02/25 21:32:33 dawes Exp $
added
removed
unix/xc/programs/Xserver/hw/xfree86/doc/DESIGN
